
  )
}
```

A publish card whose Publish button runs its own async action, beside Discard and Export.

### Variants

```tsx
'use client'

import type { ReactNode } from 'react'
import { Button } from '@youj/react'
import { ArrowUpRightIcon, DownloadIcon, PlusIcon, TrashIcon, UserPlusIcon } from '@youj/icons'

export default function ButtonVariants() {
  return (
    
      
        
          
        
        
          
        
        
          
        
        
          
        
        
          
        
        
          
        
      
    
  )
}

function Variant({ name, note, children }: { name: string; note: string; children: ReactNode }) {
  return (
    
      {children}
      
        {name}
        {note}
      
    
  )
}
```

The six variants, each with a note on when to use it.

One `default` button per view carries the accent. `secondary` and `outline` sit beside it, `ghost` handles quiet actions and dismissals, and `danger` marks the action that deletes or revokes. `link` is an action styled as text. It's still a button.

Youj icons inside a button play when the button is hovered or keyboard-focused, with no wiring. An icon at either end sits 2px closer to its edge than text would, which reads as even padding.

### Sizes

```tsx
'use client'

import { Button } from '@youj/react'
import { PlusIcon, RocketIcon } from '@youj/icons'

const TEXT = [
  { size: 'xs', height: '24' },
  { size: 'sm', height: '28' },
  { size: 'default', height: '32' },
  { size: 'lg', height: '40' },
] as const

const ICON = [
  { size: 'icon-xs', height: '24' },
  { size: 'icon-sm', height: '28' },
  { size: 'icon', height: '32' },
  { size: 'icon-lg', height: '40' },
] as const

export default function ButtonSizes() {
  return (
    
      
        {TEXT.map(({ size, height }) => (
          
            
            
              {size} · {height}px
            
          
        ))}
      
      
        {ICON.map(({ size, height }) => (
          
            {/* Icon-only buttons are named by aria-label. */}
            
            
              {size} · {height}px
            
          
        ))}
      
    
  )
}
```

Text sizes from extra small to large, and the four matching icon sizes.

Four text sizes and four square icon sizes sit on the control-height scale: 24, 28, 32 and 40px. On touch screens (`pointer: coarse`), every size is 8px taller and a default button is never under 44px, so it is a 44px target without a prop. The extra-small and small sizes stay compact and reach 44px with an invisible hit area around them.

An icon-only button has no visible text, so it needs an `aria-label`.

### Async

```tsx
'use client'

import { Button } from '@youj/react'
import { DownloadIcon, ListChecksIcon } from '@youj/icons'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function ButtonAsync() {
  return (
    
      
        Usage report
        September, all projects. 14,208 rows.
      
      
        {/* onClick returns a promise: the button is busy until it settles. No state to keep. */}
        
        
      
    
  )
}
```

Export CSV and Run checks buttons that stay busy while their onClick promise is pending.

Return a promise from `onClick` and the button looks after the wait: it shows its loading state (a spinner in place of the label, `aria-busy`, presses blocked, focus kept) until the promise settles, then returns to normal. There is no prop and no state to keep. A rejected promise ends the wait too, and the error surfaces as it would for any unawaited handler, so catch it in the handler if you need to show it. An explicit `loading` prop always wins.

```tsx

```

### Hold to confirm

```tsx
'use client'

import { AsyncButton } from '@youj/react'
import { TrashIcon } from '@youj/icons'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function ButtonHold() {
  return (
    
      
        Delete “atlas-web”
        Removes 214 deployments and every domain.
      
      {/* Runs only once the press is held: the fill sweeps across, letting go early springs it back. */}
       wait(1200)} pendingLabel="Deleting…" successLabel="Deleted">
        
        Delete project
      
    
  )
}
```

A danger zone whose Delete project button runs only after the press is held, then confirms as Deleted.

Hold to confirm lives on `AsyncButton`, not on the plain `Button`: pass `hold` and the action runs only once a press is held, by a pointer or with Space or Enter held down. While held, a fill sweeps across from the inline start, so the press shows how long is left. Letting go early springs the fill back and nothing runs. When the fill is full the action starts and the button goes through its usual lifecycle: the spinner, then the success tint with the drawn check and `successLabel`, held, then back to rest (or the error, if it fails). The press sound plays as the hold completes, not on the press. `hold` (or `hold={true}`) takes twice the `deliberate` motion token, scaled by the provider's speed; a number is milliseconds.

```tsx
 deleteProject(id)} pendingLabel="Deleting…" successLabel="Deleted">
  Delete project

```

```tsx
'use client'

import { AsyncButton } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function AsyncButtonHold() {
  return (
    
      
        €1,240.00 to Northwind Ltd
        Invoice INV-2041 · arrives today
      
      {/* A full hold runs the action; then Sending… → Sent, as any AsyncButton. */}
       wait(1400)} pendingLabel="Sending…" successLabel="Sent" errorLabel="Payment declined">
        Send payment
      
    
  )
}
```

```tsx
 sendPayment(invoice)} pendingLabel="Sending…" successLabel="Sent">
  Send payment

```

Use a hold for actions that are easy to trigger by mistake and costly to undo, where a dialog would be too much. For a slower, more deliberate gesture, use [Slide to Confirm](https://www.youj.dev/docs/components/slide-to-confirm).

### Loading

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@youj/react'
import { DownloadIcon, ListChecksIcon } from '@youj/icons'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function ButtonLoading() {
  const [exporting, setExporting] = useState(false)
  const [checking, setChecking] = useState(false)

  return (
    
      
        Usage report
        September, all projects. 14,208 rows.
      
      
        {/* `loading` is controlled: you decide when the wait starts and ends. */}
        
        
      
    
  )
}
```

Two buttons whose loading state is set from state you own.

`loading` is the controlled alternative, for work that starts somewhere else or outlives the press. The label hands over to a spinner without changing the button's width, presses are blocked, and focus stays on the button.

Pass `loading` (even as `false`) from the first render on any button that can load. Its live region then exists before it has anything to say, which some screen readers need before they'll announce a change.

## Installation & usage

```bash
pnpm add @youj/react
```

For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation).

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add button
```

It brings `spinner`, `youj-core`, `youj-labels-button`, `youj-presets`, `youj-ui-core` with it.

Use a button to save, submit, open a dialog or start another action on the page. For navigation, use a link; `buttonVariants` gives it the same look. For an option that stays on or off, use a [Toggle](https://www.youj.dev/docs/components/toggle) or a [Switch](https://www.youj.dev/docs/components/switch). For work that runs on press and shows its outcome in the button, see [Async actions](#async-actions).

```tsx
import { Button } from '@youj/react'

export function SaveBar() {
  return (
    
      
      
    
  )
}
```

It renders a native `
```

A `render` element with an `href` or `to` (an anchor, Next.js `Link`, React Router `Link`) or another tag such as `span` sets `nativeButton={false}` for you, so Base UI doesn't expect a `
          
        
        
          
          
          
        
      

      {/* A split button: filled buttons have no border, so a separator draws the seam. */}
      
        
        
        
          }>
            
          
          
            Create a merge commit
            Squash and merge
            Rebase and merge
          
        
      
    
  )
}
```

Nested groups of icon and text buttons, and a split Merge button with a menu half.

Filled buttons have no border, so put a `ButtonGroupSeparator` between them to draw the seam. The menu half is a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) whose trigger renders as a `Button`.

### With inputs

```tsx
'use client'

import { MinusIcon, PlusIcon, SearchIcon } from '@youj/icons'
import { Button, ButtonGroup, ButtonGroupText, Input } from '@youj/react'

export default function ButtonGroupInputs() {
  return (
    
      
        
        
      

      {/* ButtonGroupText renders as a label, so the prefix names the input. */}
      
        }>https://
        
      

      
        
        
      
    
  )
}
```

A search input with its button, a URL input with a text prefix, and a vertical zoom pair.

Inputs, selects and a `ButtonGroupText` join the same strip. `ButtonGroupText` renders any element through `render`, so a prefix can be the input's `label`. Set `orientation="vertical"` to stack the members.

## Installation & usage

```bash
pnpm add @youj/react
```

For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation).

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add button-group
```

It brings `separator`, `youj-ui-core` with it.

Use a button group when a few actions belong together and should read as one control: previous and next, a split button with its options, a search field with its button. For a set of options where one is chosen, use a [Toggle Group](https://www.youj.dev/docs/components/toggle-group). For a long, dense row of controls that should be one tab stop, use a [Toolbar](https://www.youj.dev/docs/components/toolbar).

```tsx
import { Button, ButtonGroup } from '@youj/react'

export function Pager() {
  return (
    
      
      
    
  )
}
```

The group takes away the inner corners and the doubled border where members meet, and a focused member rises above its neighbors so its ring isn't clipped. Corners are start and end, not left and right, so a group mirrors in right-to-left layouts. Nest groups to make clusters with a gap between them. The API matches shadcn/ui's Button Group.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### ButtonGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |

#### ButtonGroupSeparator

Takes the props of `ComponentProps`.

`ButtonGroupText` takes `render` and any `div` props.

### Reduced motion

The group itself doesn't move. Its buttons keep their own behavior: under reduced motion they don't scale when pressed.

### Accessibility

- The group is a `group`; give it an `aria-label` when its purpose isn't obvious from its buttons.
- Every member keeps its own role, name and tab stop. If the group is long and dense enough that tabbing through it is a chore, use a [Toolbar](https://www.youj.dev/docs/components/toolbar) instead, which is one tab stop.
- The separator is a `separator` with `aria-orientation`. Name icon-only buttons with `aria-label`.

---

# Toggle

> Turn an option on or off with a button that stays pressed.

Source: https://www.youj.dev/docs/components/toggle

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Toggle } from '@youj/react'
import { cn } from '@youj/core'
import { ClockIcon, CornerDownLeftIcon, PinIcon } from '@youj/icons'

const LOG = [
  { time: '14:02:11.204', line: 'Cloning github.com/youj/web (branch main, commit 4f2a91c)' },
  { time: '14:02:13.871', line: 'Installing dependencies from pnpm-lock.yaml with pnpm 10.34' },
  { time: '14:02:26.040', line: 'Compiled 48 routes in 11.8s, 3 of them static with a 60 second revalidation window' },
  { time: '14:02:39.512', line: 'Deployed to production at youj.io' },
]

export default function ToggleDemo() {
  const [timestamps, setTimestamps] = useState(true)
  const [wrap, setWrap] = useState(false)
  const [pinned, setPinned] = useState(false)

  return (
    
      
        Build logs
        
          
          Timestamps
        
        
          
          Wrap
        
        {/* Icon-only: the name stays the same, and aria-pressed carries the state. */}
        
          
        
      
      
        {LOG.map(({ time, line }) => (
          
            {timestamps && {time}}
            {line}
          
        ))}
      
    
  )
}
```

Build log options: Timestamps and Wrap toggles with labels, and an icon-only Pin toggle.

### State icons

```tsx
'use client'

import { useState } from 'react'
import { Toggle } from '@youj/react'
import { BookmarkIcon, EyeIcon, MicIcon, PinIcon, type YoujIconComponent } from '@youj/icons'

const TOGGLES: { id: string; label: string; Icon: YoujIconComponent; states: [string, string] }[] = [
  { id: 'pin', label: 'Pin project', Icon: PinIcon, states: ['Unpinned', 'Pinned'] },
  { id: 'save', label: 'Save to reading list', Icon: BookmarkIcon, states: ['Not saved', 'Saved'] },
  { id: 'mute', label: 'Mute microphone', Icon: MicIcon, states: ['Live', 'Muted'] },
  { id: 'hide', label: 'Hide resolved threads', Icon: EyeIcon, states: ['Shown', 'Hidden'] },
]

export default function ToggleIcons() {
  const [pressed, setPressed] = useState>({ pin: true })

  return (
    
      
        {TOGGLES.map(({ id, label, Icon, states }) => {
          const on = Boolean(pressed[id])
          return (
            
              {/* A state icon follows `pressed` through its `active` prop, and reverses mid-morph. */}
               setPressed((p) => ({ ...p, [id]: next }))}
              >
                
              
              
                {states[on ? 1 : 0]}
              
            
          )
        })}
      
    
  )
}
```

Four icon toggles whose icons morph between their two states as you press.

A Youj state icon inside a toggle can follow the pressed state through its `active` prop. It morphs to its second state as the toggle presses, and a quick second press reverses it from wherever it is.

```tsx

  

```

### Variants and sizes

```tsx
'use client'

import type { ReactNode } from 'react'
import { Toggle } from '@youj/react'
import { FilterIcon, ItalicIcon, UnderlineIcon } from '@youj/icons'

export default function ToggleVariants() {
  return (
    
      
        
          
            
          
          
            
          
        
        
          
            
          
          
            
          
        
        
          
            
            Failed only
          
        
        
          
            
          
          
            
          
          
            
          
        
        
          
            
          
          
            
          
        
      
    
  )
}

function Specimen({ label, children }: { label: string; children: ReactNode }) {
  return (
    
      {children}
      {label}
    
  )
}
```

The default and outline variants, a labeled toggle, the three sizes and a disabled toggle.

`default` is borderless, for toolbars that already have a frame. `outline` adds a border and suits toggles that stand alone. Three sizes, `sm`, `default` and `lg`, match the button heights (28, 32 and 40px).

## Installation & usage

```bash
pnpm add @youj/react
```

For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation).

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add toggle
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a toggle for a view or formatting option that applies at once and is read from the button itself: pressed means on. For a setting in a form or a settings list, use a [Switch](https://www.youj.dev/docs/components/switch). For a set of related options, use a [Toggle Group](https://www.youj.dev/docs/components/toggle-group), and for a one-off action, a [Button](https://www.youj.dev/docs/components/button).

```tsx
import { useState } from 'react'
import { Toggle } from '@youj/react'
import { CornerDownLeftIcon } from '@youj/icons'

export function WrapLines() {
  const [wrap, setWrap] = useState(false)
  return (
    
      
      Wrap
    
  )
}
```

Use `pressed` and `onPressedChange` to control it, or `defaultPressed` to let it hold its own state. Pressed reads as a filled neutral key with full-strength text. The accent stays reserved for actions.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), pressing plays `toggleOn` and releasing `toggleOff`. `false` keeps this one silent. |
| `variant` | `'default' \| 'outline'` | `'default'` |  |
| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` |  |

Also takes the props of `TogglePrimitive.Props`, `VariantProps`.

The state comes from Base UI's Toggle, and these are the props you'll reach for:

| Prop | Type | Description |
| --- | --- | --- |
| `pressed` | `boolean` | Controlled state. |
| `defaultPressed` | `boolean` | Initial state when uncontrolled. Default `false`. |
| `onPressedChange` | `(pressed: boolean, details) => void` | Called when the user toggles it. |
| `disabled` | `boolean` | Ignores presses. |
| `value` | `string` | Identifies it inside a Toggle Group. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | scales to 0.97 while held |
| Release, hover and pressed fill | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | scale back, background and text colors |

**Reduced motion:** No press scale. The fill and text colors still change on the fast token, since nothing moves.

#### Reduced motion

The press doesn't scale. Colors still change, so the pressed state reads the same, and a state icon switches to its second state instantly instead of morphing.

### Accessibility

- It's a `
      
      default
      
        Monthly
        Yearly
      
      lg
      
        
          
        
        
          
        
        
          
        
      
    
  )
}
```

The three sizes beside each other.

`size` is `sm`, `default` or `lg`. Each is the height of the matching control, so a segmented control sits in a row with inputs and buttons of the same size. Icon-only segments need an `aria-label`. Give the control `className="w-full"` to stretch it, and the segments share the width.

## Installation & usage

```bash
pnpm add @youj/react
```

For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation).

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add segmented-control
```

It brings `toggle-group`, `use-controllable-state`, `youj-core` with it.

Use a segmented control for a small, fixed set of options where one is always chosen and the choice changes a view in place: a time range, a billing period, a layout. It's a thin wrapper over [Toggle Group](https://www.youj.dev/docs/components/toggle-group)'s `segmented` look (plain labels on a hairline, a 2px accent bar under the pressed one) with a simpler contract: the value is one string, and it can't be emptied.

Reach for something else when the shape is different:

- **[Toggle Group](https://www.youj.dev/docs/components/toggle-group)** when several options can be on at once (bold, italic, underline), or when the choice may be cleared.
- **[Tabs](https://www.youj.dev/docs/components/tabs)** when each option owns a panel of content that the others hide.
- **[Radio Group](https://www.youj.dev/docs/components/radio-group)** for a choice inside a form that's submitted later.
- **[Select](https://www.youj.dev/docs/components/select)** when there are more options than fit in a row.

```tsx
import { SegmentedControl, SegmentedControlItem } from '@youj/react'

export function RangePicker() {
  const [range, setRange] = useState('7d')
  return (
    
      24h
      7d
      30d
    
  )
}
```

`onValueChange` receives the pressed segment's value as a string. Pressing the segment that's already pressed does nothing, so there's always a choice. `variant="pill"` sets the segments in a recessed track with a raised key instead, which suits a control that sits inside a capsule or on a well. Leave `defaultValue` out to start with nothing pressed; the first press picks one.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### SegmentedControl

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'underline' \| 'pill'` | `'underline'` | `underline` (a bar on a hairline) or `pill` (a raised key in a recessed track). |
| `value` | `string` |  | The pressed segment's value (controlled). |
| `defaultValue` | `string` | `''` | The segment pressed at first (uncontrolled). Leave it out to start with none pressed. |
| `onValueChange` | `(value: string) => void` |  | Called with the newly pressed segment's value. Never called with an empty value. |
| `aria-label` | `string` |  | Names the control for assistive tech, e.g. "View" or "Range". |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), a new choice plays `select`. `false` keeps this one silent. |
| `size` | `'default' \| 'sm' \| 'lg'` |  |  |

Also takes the props of `ToggleGroupProps`.

It also takes Toggle Group's `size`, `orientation`, `loopFocus` and `disabled`, and the props of a `div`.

#### SegmentedControlItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'default' \| 'sm' \| 'lg'` |  |  |
| `value` (required) | `string` |  | The value this segment stands for. |

Each segment takes a `value` and `disabled`, and the props of a `button`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Indicator | `spring.smooth` | 0.36s, bounce 0 | glides to the pressed segment and retargets if you press again mid-glide |
| Indicator appears | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | when a control with no value gets its first |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | each segment scales to 0.97 while held |
| Hover and text color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |

**Reduced motion:** The indicator jumps to the pressed segment, and segments don't scale when pressed.

The bar (or the key, in `pill`) is one [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator): transform-only layout projection, so its corners stay round in flight and nothing around it reflows. Resizes and font loads move it into place without animating.

#### Reduced motion

The indicator moves straight to the pressed segment, and presses don't scale. Which segment is pressed reads exactly the same.

### Accessibility

- The control is a `group` named by its `aria-label`, and each segment is a `

Save changes ) } ``` A project form with a name and a URL, validated with zod as each field is touched, and a Save button that shows the submission. Clear the name in the demo and press Save. The error grows in under the field, focus lands on it, and the button shakes to "Check the form". Enter in any field presses `FormSubmit`, so the keyboard gets the same states as a click, and a second press while the submission runs is ignored. On an invalid submit, focus moves to the first invalid control in document order and scrolls it to the middle of the view: smoothly, or at once under reduced motion. `mode: 'onTouched'` validates each field as it's left, which is the gentlest default for long forms. A rule only the server knows, such as a URL that's already taken, comes back as a field error. Set it with `form.setError` inside `onSubmit`, then throw: the message appears on its field, focus moves there, and the button shows its `errorLabel`. Type "taken" in the demo's URL field to see it. An `onSubmit` that throws without setting a field error shakes the button to `errorLabel` and leaves the fields as they were. ```tsx onSubmit={async (values) => { const result = await api.save(values) if (result.error === 'slug_taken') { form.setError('slug', { message: `orion.dev/${values.slug} is already in use.` }) throw new Error('slug_taken') } }} ``` ### Pickers ```tsx 'use client' import { zodResolver } from '@hookform/resolvers/zod' import { useForm } from 'react-hook-form' import { z } from 'zod' import { FieldGroup, TagInput, TimePicker } from '@youj/react' import { Combobox } from '@youj/react/command' import { DatePicker } from '@youj/react/date' import { Form, FormField, FormSelect, FormSubmit } from '@youj/react/form' const OWNERS = [ { value: 'ada', label: 'Ada Lovelace', description: 'ada@orion.dev' }, { value: 'grace', label: 'Grace Hopper', description: 'grace@orion.dev' }, { value: 'dieter', label: 'Dieter Rams', description: 'dieter@orion.dev' }, { value: 'susan', label: 'Susan Kare', description: 'susan@orion.dev' }, ] const REGIONS = [ { value: 'fra', label: 'Frankfurt' }, { value: 'iad', label: 'Washington, D.C.' }, { value: 'sin', label: 'Singapore' }, ] // The pickers hold null while empty, so each required one refines it away. const schema = z.object({ owner: z .string() .nullable() .refine((v) => v !== null, 'Someone has to own the launch.'), region: z .string() .nullable() .refine((v) => v !== null, 'Pick where it launches.'), launch: z .date() .nullable() .refine((v) => v !== null, 'Pick a launch date.'), time: z .string() .nullable() .refine((v) => v !== null, 'Pick a time.'), labels: z.array(z.string()).min(1, 'Add at least one label.'), }) type Values = z.input const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) export default function FormPickers() { const form = useForm>({ resolver: zodResolver(schema), defaultValues: { owner: null, region: null, launch: null, time: '10:00', labels: [] }, mode: 'onTouched', }) return ( ) } ``` Pickers mapped onto a form field. `FormField` passes its render function react-hook-form's `field`. Spread it onto an [Input](https://www.youj.dev/docs/components/input). The pickers take `value` and `onValueChange` instead of an event, so map the parts: `ref`, `value`, `onValueChange={field.onChange}` and `onBlur`. Empty pickers hold `null`, so a required one refines it away in the schema. ```tsx {(field) => ( )} ``` Passing `ref` matters: it's how the form finds the control to focus when it's invalid. ## Installation & usage ```bash pnpm add @youj/react react-hook-form ``` For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation). Or copy the source into your app with the Youj CLI (import the package as above unless you copy in): ```bash npx @youj/cli add form ``` It brings `async-button`, `field`, `select`, `youj-core`, `youj-labels-form` with it. The copy is 26 registry items, about 9,700 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `collapse`, `field`, `icon-check`, `icon-chevron-down`, `icon-chevron-up`, `icon-engine`, `icon-loader-ring` and 7 more. Requires `react-hook-form`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies), and the examples below also use `zod` and `@hookform/resolvers` (`pnpm add react-hook-form zod @hookform/resolvers`). Import it from `@youj/react/form`. `Form` builds on [react-hook-form](https://react-hook-form.com). Validate with any resolver: `zodResolver(schema)` from `@hookform/resolvers` is the usual one. Use `Form` when you need validation, such as in settings, sign-in or a create flow. It connects labels and errors, focuses the first invalid control, and shows submission states in the button. For a field without validation, wrap an [Input](https://www.youj.dev/docs/components/input) in a [Field](https://www.youj.dev/docs/components/field). Install what it needs first, or the build fails on a missing export: With pnpm, npm, Yarn or Bun: ```bash pnpm add react-hook-form @hookform/resolvers zod npm install react-hook-form @hookform/resolvers zod yarn add react-hook-form @hookform/resolvers zod bun add react-hook-form @hookform/resolvers zod ``` In the Next.js App Router, render this from a Client Component, a file that starts with `'use client'`: it takes functions (`onSubmit` and a `resolver`), and a Server Component can't pass those. [Server rendering](https://www.youj.dev/docs/guides/ssr) has the rest. ```tsx import { zodResolver } from '@hookform/resolvers/zod' import { useForm } from 'react-hook-form' import { z } from 'zod' import { FieldGroup, Input } from '@youj/react' import { Form, FormField, FormSubmit } from '@youj/react/form' const schema = z.object({ name: z.string().trim().min(3, 'Use at least 3 characters.') }) export function RenameProject() { const form = useForm({ resolver: zodResolver(schema), defaultValues: { name: 'Orion' }, mode: 'onTouched' }) return ( ) } ``` `Form` takes the `useForm()` return value and an `onSubmit` that receives the resolver's output. Resolve for success, and reject or throw for failure. `FormField` is a [Field](https://www.youj.dev/docs/components/field) around one controlled value: its `label` names the control, its `description` and error describe it, and the control is marked invalid while the error shows. `FormSubmit` is an [Async Button](https://www.youj.dev/docs/components/button#async-actions) that validates and then runs `onSubmit`. The parts are shadcn's: `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription` and `FormMessage`. The shorthand above lays them out for you; to place them yourself, or to move a shadcn form over, give `FormField` a `render` (see [shadcn's parts](#shadcns-parts)). The difference from shadcn's Form: `Form` takes the `useForm()` return value as `form` and an `onSubmit`, and renders the `

` itself, so there is no `` to write. ### shadcn's parts Give `FormField` a `render` and it only provides the field to its parts, as shadcn's does. `FormItem` is a [Field](https://www.youj.dev/docs/components/field): it groups the label, control, description and message. `FormControl` marks its control invalid, `FormMessage` shows the field's error and `useFormField()` reads the name, validity and error for a part of your own. ```tsx import { Input } from '@youj/react' import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, FormSubmit } from '@youj/react/form' api.rename(values)}> ( Project name Shown on the dashboard. )} /> Save ``` The `label` and `description` props and the `children` function are the shorthand for exactly this: a `FormItem` with a `FormLabel`, your control, a `FormDescription` and a `FormMessage`. Use `render` when you want a different order, or no label. ### Select `FormSelect` is a `FormField` with a [Select](https://www.youj.dev/docs/components/select) in it, built from `options`. It wires the field's value, change, blur and focus target for you, and takes the same `name`, `label`, `description` and `required`. An empty select holds `null`, so a required one refines it away in the schema (see [Required pickers with zod](#required-pickers-with-zod)). ```tsx import { Form, FormSelect } from '@youj/react/form' const regions = [ { value: 'fra', label: 'Frankfurt' }, { value: 'iad', label: 'Washington, D.C.' }, { value: 'sin', label: 'Singapore', disabled: true }, ] ``` For grouped or custom items, compose a `Select` inside `FormField` and map the parts as below: `value`, `onValueChange` and `items` on `Select`, and `ref` and `onBlur` on `SelectTrigger`. ### Checkbox and Radio Group A [Checkbox](https://www.youj.dev/docs/components/checkbox) holds a boolean and a [Radio Group](https://www.youj.dev/docs/components/radio-group) a string, and both take a value and a change handler instead of an event. Map `value` to `checked` for the checkbox, and `onChange` to `onCheckedChange` and `onValueChange`. Start the checkbox at `false` in `defaultValues`; an unchosen radio group holds `undefined`. ```tsx import { Checkbox, Field, FieldLabel, RadioGroup, RadioGroupItem } from '@youj/react' {(field) => ( )} {(field) => ( Free Pro )} ``` ### Required pickers with zod An empty picker or select holds `null`, so the form's values (the schema's input) allow `null` while the submitted values (its output) don't. Two things make TypeScript see that: - **Refine with a type guard.** `(value): value is string => value !== null` narrows the output to `string`. A refine that only returns a boolean keeps `string | null`. - **Give `useForm` the input and the output.** Let it infer both from `zodResolver(schema)`, or name all three generics: `useForm, unknown, z.output>`. `useForm>` names only the output, so `defaultValues: { region: null }` and the resolver no longer type-check. ```tsx import { zodResolver } from '@hookform/resolvers/zod' import { useForm } from 'react-hook-form' import { z } from 'zod' import { FieldGroup } from '@youj/react' import { Combobox } from '@youj/react/command' import { Form, FormField, FormSelect, FormSubmit } from '@youj/react/form' const chosen = (value: string | null): value is string => value !== null const schema = z.object({ region: z.string().nullable().refine(chosen, 'Choose a region.'), owner: z.string().nullable().refine(chosen, 'Choose an owner.'), }) export function CreateService() { // Values hold null while empty (the input); onSubmit gets strings (the output). const form = useForm, unknown, z.output>({ resolver: zodResolver(schema), defaultValues: { region: null, owner: null }, mode: 'onTouched', }) return ( ) } ``` `values` in `onSubmit` is `{ region: string; owner: string }`, and an empty field shows its refine message. ## Description Each example's description is under Examples. ## Code Each example's code is under Examples. ## Reference ### Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `form` (required) | `UseFormReturn` | | The useForm() return value. | | `onSubmit` (required) | `(values: Output) => unknown` | | Runs with the resolver's output (a zod schema's parsed values). Resolve for success; reject (or throw) for failure. | Also takes the props of `ComponentProps<'form'>`. #### FormField | Prop | Type | Default | Description | | --- | --- | --- | --- | | `render` | `never` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | | `label` | `ReactNode` | | | | `description` | `ReactNode` | | | | `children` | `(field: ControllerRenderProps, state: ControllerFieldState) => ReactNode` | | Renders the control inside the shorthand's label, description and message. Spread `field` onto an Input; map it (`value`, `onValueChange={field.onChange}`, `onBlur`, `ref`) onto the pickers. | | `name` (required) | `N` | | | | `control` | `Control` | | For type inference from useForm(); defaults to the surrounding Form's. | With `children` it also takes every [Field](https://www.youj.dev/docs/components/field) prop except `invalid`, which it sets from the field's state, such as `required`, `disabled` and `orientation`. #### FormItem | Prop | Type | Default | Description | | --- | --- | --- | --- | | `orientation` | `'horizontal' \| 'vertical' \| 'responsive'` | | | | `required` | `boolean` | | Marks the label and makes the control required. | The other parts (`FormLabel`, `FormControl`, `FormDescription`, `FormMessage`) take the props of the [Field](https://www.youj.dev/docs/components/field) part they are named after. #### FormSelect | Prop | Type | Default | Description | | --- | --- | --- | --- | | `options` (required) | `ReadonlyArray>>>` | | The choices, in order. The trigger shows the chosen one's label. | | `placeholder` | `ReactNode` | | Shown while the value is empty (`null`). | | `size` | `'sm' \| 'default'` | ``default`` | Trigger height. | | `name` (required) | `N` | | | | `orientation` | `'horizontal' \| 'vertical' \| 'responsive'` | | | | `label` | `ReactNode` | | | | `render` | `never` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | | `required` | `boolean` | | Marks the label and makes the control required. | | `description` | `ReactNode` | | | | `control` | `Control` | | For type inference from useForm(); defaults to the surrounding Form's. | It also takes every `FormField` prop except `children`. Each option is `{ value, label, disabled? }`. #### FormSubmit | Prop | Type | Default | Description | | --- | --- | --- | --- | | `invalidLabel` | `string` | `"Check the form"` | Shown beside the cross when fields need attention. | | `variant` | `'default' \| 'danger' \| 'ghost' \| 'outline' \| 'link' \| 'secondary'` | | `default \| secondary \| outline \| ghost \| danger \| link`. | | `size` | `'default' \| 'sm' \| 'lg' \| 'xs' \| 'icon' \| 'icon-xs' \| 'icon-sm' \| 'icon-lg'` | | | | `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the button plays `tap` as it's pressed. `false` keeps this one silent. | | `pendingLabel` | `string` | | Shown beside the spinner while the action runs, and announced. Announced as "Working…" when omitted. | | `successLabel` | `string \| ((result: TResult) => string)` | `"Done"` | Shown beside the check and announced. A function gets what `onAction` resolved with: `successLabel={(user) => `Saved ${user.name}`}`. Under `status` there is no outcome to read, so pass a string. | | `errorLabel` | `string \| ((error: unknown) => string)` | `"Failed"` | Shown beside the cross and announced assertively. A function gets what `onAction` rejected or threw with, whatever that is: `errorLabel={(error) => error instanceof Error ? error.message : 'Failed'}`. Under `status`, pass a string (`errorLabel={mutation.error?.message}`). | | `resetAfter` | `number` | | How long success / error hold before the label returns, in ms. Default: 3 × the deliberate token. | | `onActionStateChange` | `(state: AsyncState) => void` | | Fires on every state change: idle → pending → success \| error → idle. | | `hold` | `boolean \| number` | | Hold to confirm: the action runs only once a press is held (a pointer, or Space or Enter held down) for this long. `true` takes twice the deliberate motion token; a number is milliseconds. The button fills from its inline start while held and springs back if let go early; a full hold runs the action and the button carries on through pending to success or error. It is described as "Hold to confirm". | `FormSubmit` takes every [Async Button](https://www.youj.dev/docs/components/button#async-actions) prop except `onAction`, `status` and `type`, including `pendingLabel`, `successLabel`, `errorLabel` and `resetAfter`. `FormInvalidError` is the error `FormSubmit` sees when validation fails, for code that calls the submission itself. ### Motion | Moment | Tokens | Value | Note | | --- | --- | --- | --- | | Error in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the message grows from 0 height and fades in under its control (Field) | | Error out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the text fades before the height closes | | Submit pending | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the label crossfades to a spinner (Async Button) | | Button width | `spring.snappy` | 0.2s, bounce 0 | follows each new label | | Submit success | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | a check draws on beside `successLabel` | | Invalid or failed | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | a 4, 3 and 2px shake to `invalidLabel` or `errorLabel` | | Focus first invalid | | smooth scroll | scrolls it to the middle of the view | **Reduced motion:** Errors appear and disappear at once, the button's states swap instantly without a shake, and the first invalid control is scrolled to without smooth scrolling. #### Reduced motion Errors appear and disappear without the height animation. The submit button's states swap at once and don't shake, and focusing the first invalid control scrolls straight to it. Validation, messages and focus behave exactly the same. ### Accessibility - The `

` sets `noValidate`: the schema validates, and messages are written in your voice rather than the browser's. - Each `FormField` label names its control, and the description and error are linked to it with `aria-describedby`. The control carries `aria-invalid` while its error shows, and `required` marks it required: native `required` on an Input, `aria-required` on custom controls such as Combobox, MultiSelect, TagInput and TimePicker. - An invalid submit moves focus to the first invalid control, with a visible focus ring, so keyboard and screen reader users land on the problem rather than having to find it. - `FormSubmit` announces pending and success politely and failures assertively, as Async Button does. Presses while it runs are ignored. --- # Field > Connect a form control to its label, description and error messages. Source: https://www.youj.dev/docs/components/field ## Examples ### Demo ```tsx 'use client' import { useRef, useState, type FormEvent } from 'react' import { Button, Checkbox, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, Input, } from '@youj/react' const SCOPES = [ { id: 'read', label: 'Read', description: 'Projects, deployments and logs.' }, { id: 'write', label: 'Write', description: 'Create deployments and change settings.' }, { id: 'admin', label: 'Admin', description: 'Members, billing and deletion. Rarely needed.' }, ] export default function FieldDemo() { const name = useRef(null) const [error, setError] = useState() const [created, setCreated] = useState('') function submit(event: FormEvent) { event.preventDefault() const value = name.current?.value.trim() ?? '' const problem = !value ? 'Give the token a name.' : value.length < 3 ? 'Use at least 3 characters.' : undefined setError(problem) if (problem) name.current?.focus() else setCreated(value) } return (

Create an API token Tokens act as you. Give each one the least access it needs. {/* The error grows in below the input, and the fields beneath ease down to make room. */} Token name setError(undefined)} /> {error} Only you see this.

Scopes {SCOPES.map((scope) => ( {scope.label} {scope.description} ))}

{created && `Created “${created}”. Copy it now: it won’t be shown again.`}

) } ``` An API token form: a required name whose error grows in on submit, and a group of scopes as horizontal fields. ### Validation ```tsx 'use client' import { useState } from 'react' import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, Input } from '@youj/react' const TAKEN = ['youj', 'admin', 'docs', 'status'] function passwordErrors(value: string) { const errors: { message: string }[] = [] if (value.length < 12) errors.push({ message: 'Use at least 12 characters.' }) if (!/[\d\W_]/.test(value)) errors.push({ message: 'Include a number or a symbol.' }) return errors } export default function FieldValidation() { const [handle, setHandle] = useState('youj') const [password, setPassword] = useState('') const taken = TAKEN.includes(handle.trim().toLowerCase()) const problems = password ? passwordErrors(password) : [] return ( Team handle {/* Children in, message shown; undefined, message gone. It collapses over its last text. */} {taken ? `@${handle.trim()} is taken. Try another.` : undefined} Used in URLs: youj.io/@{handle.trim() || 'handle'} 0}> New password {/* Several problems become a list; duplicates collapse. */} Region Set when the team was created. ) } ``` Errors from children, from an `errors` list, or from the control's own validation, easing open and closed. FieldError shows what you pass it. Give it children for one message, or `errors` for several, in react-hook-form's `{ message }` shape: duplicates collapse, and several messages become a list. With neither, it shows the control's own validation message whenever Base UI marks the field invalid, from native constraints such as `required` or from a `validate` function, checked when `validationMode` says. A message grows the layout open. Its panel eases from zero height while the text fades in, so the fields below move down with it instead of jumping. When the error clears, the panel closes over the last message. An error that's already there when the Field first renders simply appears, as the taken handle in the preview does. ### Orientation ```tsx 'use client' import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel, Input, Switch } from '@youj/react' export default function FieldOrientation() { return ( {/* horizontal: what it does on one side, the control on the other. */} Failed deploy alerts Email the team when a production deploy fails. Weekly summary A Monday digest of traffic, builds and spend. {/* responsive: stacked in a narrow group, side by side once the group is wide enough. */} Alert address A shared inbox works best. ) } ``` The same field stacked, side by side, and responsive to its group's width. `vertical`, the default, stacks label, control and description: the shape for forms. `horizontal` puts the control beside a FieldContent of label and description: the shape for settings rows. `responsive` stacks inside a narrow FieldGroup and sits side by side once the group is at least 28rem wide. It's a container query, so it follows the group's width, not the viewport's. ### Choice cards ```tsx 'use client' import { Checkbox, Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet, FieldTitle } from '@youj/react' const FEATURES = [ { id: 'comments', title: 'Preview comments', description: 'Reviewers leave notes right on a preview deployment.', on: true }, { id: 'insights', title: 'Speed Insights', description: 'Real-user Core Web Vitals for every route.' }, { id: 'analytics', title: 'Web Analytics', description: 'Privacy-friendly traffic, with no cookie banner.', on: true }, ] export default function FieldChoices() { return (

Enable for youj-web You can change these per project later.

{FEATURES.map((feature) => ( // A FieldLabel around a whole Field becomes a choice card: the card is the target and carries the focus ring. {feature.title} {feature.description} ))}

) } ``` A whole Field wrapped in a FieldLabel: the card is the click target, and it tints when checked. Wrap a whole Field in a FieldLabel and it becomes a choice card. The entire card is the click target, it tints when its checkbox or radio is checked, and it carries the focus ring for the control inside. Use FieldTitle for the card's heading, because the FieldLabel around it already names the control. ## Installation & usage ```bash pnpm add @youj/react ``` For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation). Or copy the source into your app with the Youj CLI (import the package as above unless you copy in): ```bash npx @youj/cli add field ``` It brings `collapse`, `label`, `separator`, `youj-core`, `youj-presets`, `youj-ui-core` with it. Wrap form controls in Field to connect their labels, descriptions and errors for assistive technology. Group controls that answer one question with FieldSet and FieldLegend. A search or toolbar input already named by `aria-label` does not need a Field. ```tsx import { Field, FieldDescription, FieldError, FieldLabel, Input } from '@youj/react' export function WorkspaceName({ error }: { error?: string }) { return ( Workspace name {error} Shown in the sidebar and in invite emails. ) } ``` Field is Base UI's Field, so the wiring is correct by construction. FieldLabel names the control, FieldDescription and a visible FieldError describe it, and `invalid` and `disabled` reach it. `required` is Youj's addition: set it once on the Field and the label shows the mark while the control becomes required. Every Youj control works inside a Field: Input, Textarea, Input Group, Checkbox, Radio Group, Switch, Slider and Select. ## Description Each example's description is under Examples. ## Code Each example's code is under Examples. ## Reference ### Structure | Part | Renders | Use it for | | --- | --- | --- | | `Field` | `div` | One control with its label, description and error. | | `FieldLabel` | `label` | The control's name. Wrapping a whole Field makes a choice card. | | `FieldDescription` | `p` | Help text, added to the control's description. | | `FieldError` | `div` | Errors, shown in a panel that grows in and collapses out. | | `FieldContent` | `div` | The label-and-description column beside a horizontal control. | | `FieldTitle` | `div` | A label-styled heading that doesn't label anything, for choice cards. | | `FieldSet` | `fieldset` | A group of controls that answer one question. | | `FieldLegend` | `div` | The group's name, linked to its fieldset. `variant="label"` sets it at label size. | | `FieldGroup` | `div` | Stacks fields and sets. It's the container that `responsive` measures. | | `FieldSeparator` | `div` | A hairline between groups, with optional text in the middle. | Outside a Field, the label, description and error parts render as plain elements with the same look, so you can compose them freely. ### Label Outside a Field, use Label: a plain `` with the same type, linked to its control by `htmlFor`. `required` shows the same decorative mark. It ships as its own registry item, `label`, which Field installs for you. ```tsx import { Checkbox, Label } from '@youj/react'

Accept the terms

) } function State({ label, children }: { label: string; children: ReactNode }) { return (

{label}

{children}

) } ``` Inputs in their hover, focus, invalid, disabled and read-only states. Hover strengthens the border. Focus turns the border accent inside a soft 3px halo, so the field reads as lit rather than outlined. Invalid swaps both to the destructive color. Disabled and read-only are native, and read-only gets a muted fill so it doesn't look editable. Set `aria-invalid` yourself on a standalone input. Inside a Field, `invalid` sets it for you. ### Controlled ```tsx 'use client' import { useState } from 'react' import { Field, FieldDescription, FieldLabel, Input } from '@youj/react' // Lowercase letters, numbers and single dashes, as a URL segment allows. const slugify = (value: string) => value .toLowerCase() .replace(/[^a-z0-9]+/g, '-') .replace(/^-+/, '') .slice(0, 32) export default function InputControlled() { const [slug, setSlug] = useState('acme-web') return ( Project URL {/* onValueChange hands you the string. The value you pass back is what the input shows. */} setSlug(slugify(value))} spellCheck={false} className="font-mono text-ui-sm" /> Deploys to {slug.replace(/-+$/, '') || 'your-project'}.youj.app ) } ``` An input whose value you own. `onValueChange` hands you the new string, and the `value` you pass back is what the input shows. Use it to format as people type. The standard `onChange` event works too. ## Installation & usage ```bash pnpm add @youj/react ``` For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation). Or copy the source into your app with the Youj CLI (import the package as above unless you copy in): ```bash npx @youj/cli add input ``` It brings `field`, `youj-presets`, `youj-ui-core` with it. Use Input for short text such as a name, email address or URL. Choose a [Textarea](https://www.youj.dev/docs/components/textarea) for multiple lines, an [Input Group](https://www.youj.dev/docs/components/input-group) for a prefix, icon or button inside the field, or a [Select](https://www.youj.dev/docs/components/select) for a known list of answers. ```tsx import { Field, FieldLabel, Input } from '@youj/react' export function DisplayName() { return ( Display name ) } ``` Inside a [Field](https://www.youj.dev/docs/components/field), the input is labeled, described and validated with no extra wiring, and it takes `required` from the Field. On its own, name it with `aria-label` or a [Label](https://www.youj.dev/docs/components/field#label). ## Description Each example's description is under Examples. ## Code Each example's code is under Examples. ## Reference ### Props Takes the props of `InputPrimitive.Props`. Every native input attribute passes through, plus Base UI's `onValueChange(value, details)`, which reports the new value as a string. ### Motion | Moment | Tokens | Value | Note | | --- | --- | --- | --- | | Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | border color, fill and the focus halo | **Reduced motion:** There is nothing to reduce: the input only changes color, on the fast token. #### Reduced motion The input doesn't move. Its border, fill and halo change color on the `fast` token with or without reduced motion. ### Accessibility - It's a native ``. Give it a visible label through a Field, or an `aria-label` when the context names it, like a search box. - Focus shows as an accent border and halo. A transparent outline rides along, so Windows high-contrast mode still draws a focus indicator. - Text is 13px, and 16px on touch screens, so iOS doesn't zoom the page when the input takes focus. - Pick the right `type`, `inputMode` and `autoComplete`. They choose the on-screen keyboard and let browsers and password managers fill the field. --- # Textarea > Collect multi-line text in a field that grows with its content, then scrolls. Source: https://www.youj.dev/docs/components/textarea ## Examples ### Demo ```tsx 'use client' import { useState } from 'react' import { Button, Field, FieldDescription, FieldError, FieldLabel, Textarea } from '@youj/react' const LIMIT = 280 export default function TextareaDemo() { const [value, setValue] = useState('') const [sent, setSent] = useState(false) const left = LIMIT - value.length return (

{ event.preventDefault() setSent(true) setValue('') }} > What could be better?

{
            setValue(event.target.value)
            setSent(false)
          }}
          placeholder="The more specific, the more useful."
        />
        <div className="flex items-start justify-between gap-3">
          {left < 0 ? (
            <FieldError>{`${-left} characters over the limit.`}</FieldError>
          ) : (
            <FieldDescription>Goes straight to the team that owns it.</FieldDescription>
          )}
          {/* The count updates silently. Only the last 20 characters are announced. */}
          <span aria-hidden className="shrink-0 font-mono text-ui-xs text-fg-muted tabular-nums">
            {left}
          </span>
        </div>
        <span aria-live="polite" className="sr-only">
          {left >= 0 && left <= 20 ? `${left} characters left` : ''}
        </span>
      </Field>
      <div className="mt-3 flex items-center justify-between gap-3">
        <p role="status" className="text-ui-sm text-fg-muted">
          {sent && 'Thanks. The team reads every one.'}
        </p>
        <Button type="submit" disabled={left < 0 || value.trim() === ''}>
          Send feedback
        </Button>
      </div>
    </form>
  )
}
```

A feedback form whose Textarea counts down to a 280-character limit and turns the count into an error once it is exceeded.

Count in the description line and turn the count into an error once it's exceeded, as the demo does. Announce only the last stretch: a live region that speaks on every keystroke drowns out what's being typed.

```tsx
<span aria-live="polite" className="sr-only">
  {left >= 0 && left <= 20 ? `${left} characters left` : ''}
</span>
```

### States

```tsx
'use client'

import type { ReactNode } from 'react'
import { Textarea } from '@youj/react'

const NOTES =
  'Shipped the new pricing page behind the pricing-v2 flag.\nFollow-ups: the OG image, redirects from /plans, and the changelog entry.'

export default function TextareaStates() {
  return (
    <div className="@container w-full max-w-xl">
      <div className="grid gap-x-6 gap-y-5 @md:grid-cols-2">
        <State label="empty">
          <Textarea aria-label="Reply" placeholder="Write a reply…" />
        </State>
        <State label="filled · grows with its content">
          <Textarea aria-label="Release notes" defaultValue={NOTES} />
        </State>
        <State label="invalid">
          <Textarea aria-label="Summary" defaultValue="WIP" aria-invalid />
        </State>
        <State label="disabled">
          <Textarea aria-label="Review notes" defaultValue="Locked while the release is in review." disabled />
        </State>
      </div>
    </div>
  )
}

function State({ label, children }: { label: string; children: ReactNode }) {
  return (
    <div className="flex flex-col gap-2">
      <p className="font-mono text-ui-xs text-fg-muted">{label}</p>
      {children}
    </div>
  )
}
```

A textarea growing with its content, and its states.

It starts three lines tall and grows with its content up to 16rem, then scrolls. Growth is CSS `field-sizing: content`. In browsers without it, the box keeps its starting height and you can drag it taller. Border, hover, focus and invalid match Input.

### Fixed height

```tsx
'use client'

import { useState } from 'react'
import { Button, Field, FieldDescription, FieldLabel, Textarea } from '@youj/react'

const PASTED = `# Production
DATABASE_URL=postgres://web@db.internal.youj.io:5432/youj?sslmode=require
REDIS_URL=redis://cache.internal.youj.io:6379/0
SESSION_TTL=86400
LOG_LEVEL=info`

// A variable is a KEY=value line. Comments and blank lines don't count.
const countVariables = (text: string) => text.split('\n').filter((line) => /^\s*[A-Za-z_]\w*\s*=/.test(line)).length
const variables = (n: number) => (n === 1 ? '1 variable' : `${n} variables`)

export default function TextareaFixed() {
  const [env, setEnv] = useState(PASTED)
  const [imported, setImported] = useState(0)
  const count = countVariables(env)

return (
    <form
      className="w-full max-w-md"
      onSubmit={(event) => {
        event.preventDefault()
        setImported(count)
      }}
    >
      <Field>
        <FieldLabel>Paste a .env file</FieldLabel>
        {/* A fixed six rows, and long values scroll sideways instead of wrapping onto the next line. */}
        <Textarea
          value={env}
          onChange={(event) => {
            setEnv(event.target.value)
            setImported(0)
          }}
          placeholder="KEY=value, one per line"
          rows={6}
          wrap="off"
          spellCheck={false}
          autoCapitalize="off"
          autoComplete="off"
          className="field-sizing-fixed font-mono text-ui-sm"
        />
        <FieldDescription>One KEY=value per line; long values scroll sideways. Keys that already exist in Production are overwritten.</FieldDescription>
      </Field>
      <div className="mt-3 flex items-center justify-between gap-3">
        <p role="status" className="text-ui-sm text-fg-muted">
          {imported > 0 && `Imported ${variables(imported)}.`}
        </p>
        <Button type="submit" disabled={count === 0}>
          {count > 0 ? `Import ${variables(count)}` : 'Import'}
        </Button>
      </div>
    </form>
  )
}
```

A textarea that keeps a fixed height.

Pasted text, like a `.env` file or a certificate, is easier to check in a box that stays put. Add the `field-sizing-fixed` class and set `rows` to hold the height, and set `wrap="off"` so long lines scroll sideways instead of wrapping.

## Installation & usage

```bash
pnpm add @youj/react
```

For an app already set up with `npx @youj/cli init`, which installs the peers (`@youj/core`, `@youj/motion`, `motion` and Base UI) and wires the provider. New app? Start at [Installation](/docs/installation).

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add textarea
```

It brings `field`, `input`, `youj-ui-core` with it.

Use Textarea for comments, feedback, descriptions and other multi-line text. Use an [Input](https://www.youj.dev/docs/components/input) for a single line. Wrap the textarea in an [Input Group](https://www.youj.dev/docs/components/input-group) when you need a toolbar or send button inside its frame.

```tsx
import { Field, FieldDescription, FieldLabel, Textarea } from '@youj/react'

export function ProjectDescription() {
  return (
    <Field>
      <FieldLabel>Description</FieldLabel>
      <Textarea name="description" placeholder="What does this project do?" />
      <FieldDescription>Shown on the project page and in search.</FieldDescription>
    </Field>
  )
}
```

It renders a real `<textarea>` through Base UI's field control, so inside a [Field](https://www.youj.dev/docs/components/field) it's labeled, described, validated and made `required` exactly like an Input. `rows`, `cols` and `wrap` go to the element.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  |  |
| `defaultValue` | `string` |  |  |

`value` and `defaultValue` take strings. Every other native textarea attribute passes through, including `onChange`, `rows` and `maxLength`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | border color, fill and the focus halo |

**Reduced motion:** There is nothing to reduce: growing with its content is instant, and colors change on the fast token.

#### Reduced motion

The textarea doesn't animate. It grows line by line as you type, with or without reduced motion.

### Accessibility

- It's a native `<textarea>`: `Enter` adds a new line and `Tab` moves focus on.
- Label it through a Field, or with `aria-label` when the context names it.
- If you use `maxLength`, say so in the description. The browser stops accepting input silently, which reads as a broken keyboard.
- Text is 16px on touch screens, so iOS doesn't zoom the page on focus.

---

# Input Group

> Put icons, text, shortcuts and buttons inside an input or textarea’s frame.

Source: https://www.youj.dev/docs/components/input-group

## Examples

### Demo

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  Kbd,
  KbdGroup,
} from '@youj/react'
import { useYouj } from '@youj/core'
import { CopyIcon, EyeIcon, SearchIcon } from '@youj/icons'

const KEY = 'pk_demo_51N8fTq2eZvKYlo2C9w'

export default function InputGroupDemo() {
  const k = useYouj()
  const [copied, setCopied] = useState(false)
  const [shown, setShown] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)
  useEffect(() => () => clearTimeout(timer.current), [])

function copy() {
    void navigator.clipboard?.writeText(KEY).catch(() => {})
    setCopied(true)
    clearTimeout(timer.current)
    // The check holds for three deliberate steps, the same hold as a Button's onAction.
    timer.current = setTimeout(() => setCopied(false), k.ms('deliberate') * 3)
  }

return (
    <FieldGroup className="w-full max-w-sm">
      <InputGroup>
        <InputGroupAddon>
          <SearchIcon />
        </InputGroupAddon>
        <InputGroupInput aria-label="Search" placeholder="Search projects, people, docs…" />
        <InputGroupAddon align="inline-end">
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>K</Kbd>
          </KbdGroup>
        </InputGroupAddon>
      </InputGroup>
      <Field>
        <FieldLabel>Publishable key</FieldLabel>
        <InputGroup>
          <InputGroupInput readOnly defaultValue={KEY} className="font-mono text-ui-sm" />
          <InputGroupAddon align="inline-end">
            {/* CopyIcon is a state icon: `active` morphs it to a check. */}
            <InputGroupButton size="icon-xs" aria-label="Copy key" onClick={copy}>
              <CopyIcon active={copied} />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        <FieldDescription>Safe to ship in client code.</FieldDescription>
        <span role="status" className="sr-only">
          {copied ? 'Key copied' : ''}
        </span>
      </Field>
      <Field>
        <FieldLabel>Database password</FieldLabel>
        <InputGroup>
          <InputGroupInput type={shown ? 'text' : 'password'} defaultValue="correct-horse-battery" autoComplete="off" />
          <InputGroupAddon align="inline-end">
            {/* The name says what pressing does, and aria-pressed says whether it's on. */}
            <InputGroupButton size="icon-xs" aria-label="Show password" aria-pressed={shown} onClick={() => setShown((s) => !s)}>
              <EyeIcon active={shown} />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
      </Field>
    </FieldGroup>
  )
}
```

Input groups holding a search icon, a shortcut hint and a copy button for an API key.

### Addons

```tsx
'use client'

import type { ReactNode } from 'react'
import { InputGroup, InputGroupAddon, InputGroupInput, InputGroupText } from '@youj/react'
import { AtSignIcon, GlobeIcon, SearchIcon } from '@youj/icons'

export default function InputGroupAddons() {
  return (
    <div className="@container w-full max-w-xl">
      <div className="grid gap-x-6 gap-y-5 @md:grid-cols-2">
        <Specimen label="prefix text · end icon">
          <InputGroup>
            <InputGroupAddon>
              <InputGroupText>https://</InputGroupText>
            </InputGroupAddon>
            <InputGroupInput aria-label="Domain" placeholder="youj.io" className="ps-0.5" />
            <InputGroupAddon align="inline-end">
              <GlobeIcon />
            </InputGroupAddon>
          </InputGroup>
        </Specimen>
        <Specimen label="prefix · suffix">
          <InputGroup>
            <InputGroupAddon>
              <InputGroupText>$</InputGroupText>
            </InputGroupAddon>
            <InputGroupInput aria-label="Monthly budget" defaultValue="2,400" inputMode="decimal" className="tabular-nums" />
            <InputGroupAddon align="inline-end">
              <InputGroupText>USD / month</InputGroupText>
            </InputGroupAddon>
          </InputGroup>
        </Specimen>
        <Specimen label="invalid">
          <InputGroup>
            <InputGroupAddon>
              <AtSignIcon />
            </InputGroupAddon>
            <InputGroupInput aria-label="Handle" defaultValue="priya raman" aria-invalid />
          </InputGroup>
        </Specimen>
        <Specimen label="disabled">
          <InputGroup>
            <InputGroupAddon>
              <SearchIcon />
            </InputGroupAddon>
            <InputGroupInput aria-label="Search logs" placeholder="Search is paused during maintenance" disabled />
          </InputGroup>
        </Specimen>
      </div>
    </div>
  )
}

function Specimen({ label, children }: { label: string; children: ReactNode }) {
  return (
    <div className="flex flex-col gap-2">
      <p className="font-mono text-ui-xs text-fg-muted">{label}</p>
      {children}
    </div>
  )
}
```

Addons on each edge of the control.

An addon sits on an edge set by `align`: `inline-start` (the default) or `inline-end` beside the control, or `block-start` or `block-end` above or below it. The edges are logical, so they swap sides under right-to-left text. Put icons straight in, and wrap text in InputGroupText.

### Textarea and toolbars

```tsx
'use client'

import { useRef, useState } from 'react'
import { AsyncButton, InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupTextarea, Kbd } from '@youj/react'
import { ArrowUpIcon, PaperclipIcon } from '@youj/icons'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function InputGroupComposer() {
  const [comment, setComment] = useState('')
  const send = useRef<HTMLButtonElement>(null)

return (
    <InputGroup className="w-full max-w-md">
      <InputGroupTextarea
        aria-label="Comment on this preview"
        placeholder="Leave a comment on youj-web-4f2a91c…"
        value={comment}
        onChange={(event) => setComment(event.target.value)}
        onKeyDown={(event) => {
          // Enter sends; Shift+Enter keeps its newline.
          if (event.key === 'Enter' && !event.shiftKey) {
            event.preventDefault()
            send.current?.click()
          }
        }}
      />
      <InputGroupAddon align="block-end" className="justify-between">
        <InputGroupText className="text-ui-sm">
          <Kbd>⏎</Kbd> to send
        </InputGroupText>
        <div className="flex items-center gap-1">
          <InputGroupButton size="icon-xs" aria-label="Attach a file">
            <PaperclipIcon />
          </InputGroupButton>
          {/* An AsyncButton in the addon: it spins, lands on a check, and announces "Comment posted". */}
          <AsyncButton
            ref={send}
            size="icon-xs"
            variant="default"
            aria-label="Send comment"
            disabled={comment.trim() === ''}
            focusableWhenDisabled
            onAction={async () => {
              await wait(900)
              setComment('')
            }}
            successLabel="Comment posted"
            errorLabel="Couldn’t post the comment"
          >
            <ArrowUpIcon />
          </AsyncButton>
        </div>
      </InputGroupAddon>
    </InputGroup>
  )
}
```

A textarea with a toolbar under it and an async send button.

InputGroupTextarea grows with its content like a [Textarea](https://www.youj.dev/docs/components/textarea). A `block-end` addon under it becomes a toolbar. InputGroupButton is a [Button](https://www.youj.dev/docs/components/button) sized for the frame. For work the button runs itself, put an [Async Button](https://www.youj.dev/docs/components/button#async-actions) in the addon: the send button in the preview spins, lands on a check and announces "Comment posted", while staying square.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add input-group
```

It brings `button`, `field`, `textarea`, `youj-presets`, `youj-ui-core` with it.

The copy is 16 registry items, about 7,800 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-engine`, `icon-loader-ring`, `input`, `label`, `separator`, `spinner`, `textarea`.

Use an input group when something belongs inside the field's border: a search icon, a `https://` prefix, a unit, a copy button, a shortcut hint. If the extra piece is its own action next to the field, like a Send button after an email address, put a [Button](https://www.youj.dev/docs/components/button) beside a plain [Input](https://www.youj.dev/docs/components/input) instead.

```tsx
import { InputGroup, InputGroupAddon, InputGroupInput, Kbd, KbdGroup } from '@youj/react'
import { SearchIcon } from '@youj/icons'

export function Search() {
  return (
    <InputGroup>
      <InputGroupAddon>
        <SearchIcon />
      </InputGroupAddon>
      <InputGroupInput aria-label="Search" placeholder="Search projects…" />
      <InputGroupAddon align="inline-end">
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </InputGroupAddon>
    </InputGroup>
  )
}
```

The group is the frame. The InputGroupInput or InputGroupTextarea inside it is bare, and the frame takes its hover, focus halo, invalid and disabled treatment. Clicking an addon's empty space focuses the control, as it would on a native field. Buttons inside keep their own clicks and their own focus ring.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### InputGroup

Takes the props of `ComponentProps<'div'>`.

#### InputGroupAddon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'inline-end' \| 'inline-start' \| 'block-start' \| 'block-end'` | `'inline-start'` |  |

#### InputGroupButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'danger' \| 'ghost' \| 'outline' \| 'link' \| 'secondary'` | `'ghost'` | `default \| secondary \| outline \| ghost \| danger \| link`. |
| `loading` | `boolean` |  | Swaps the label for a spinner without changing the button's width, sets aria-busy, and blocks presses while keeping keyboard focus on the button. Pass it (even as `false`) on any button that can load, so its live region exists before the first announcement. Without it, a click handler that returns a promise puts the button in this state until the promise settles; an explicit `loading` (even `false`) wins. For a success or error label after the work, use AsyncButton. |
| `loadingLabel` | `string` | `"Loading"` | Announced when loading starts. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the button plays `tap` as it's pressed. `false` keeps this one silent. |
| `size` | `'sm' \| 'xs' \| 'icon-xs' \| 'icon-sm'` | `'xs'` |  |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` |  |

It defaults to the `ghost` variant, `type="button"` and the `xs` size, so it never submits a form by accident and fits inside a 32px frame.

#### InputGroupInput and InputGroupTextarea

InputGroupInput takes every Input prop, and InputGroupTextarea every Textarea prop. InputGroupText is a styled `<span>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the frame: border color and the focus halo |
| Buttons | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | press and hover, as on Button |

**Reduced motion:** The frame only changes color. Buttons inside follow Button's reduced motion: no press scale, and async states swap instantly.

#### Reduced motion

The frame's border and halo change color as usual, since nothing moves. Buttons in the group lose their press scale, and async buttons swap states instantly.

### Accessibility

- The frame is a `group`. The control inside is the labeled element: put the InputGroup inside a [Field](https://www.youj.dev/docs/components/field) and the FieldLabel names the control, or give the control an `aria-label`.
- Icon-only buttons inside need an `aria-label`, like any icon-only button.
- A reveal button, like the password eye above, keeps one name and reports its state with `aria-pressed`.
- Keyboard hints such as ⌘ K are visual. If the shortcut matters, say it in the control's description too.
- Addons are `select-none` text. Anything in them that people need to read, like a unit, belongs in the label or description as well.

---

# Password Input

> Enter a password with a visibility toggle, optional strength meter and requirements checklist.

Source: https://www.youj.dev/docs/components/password-input

## Examples

### Demo

```tsx
'use client'

import { useId, useState } from 'react'
import {
  AsyncButton,
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
  PasswordInput,
  PasswordRequirements,
  PasswordStrength,
  defaultPasswordRequirements,
} from '@youj/react'

export default function PasswordInputDemo() {
  const [next, setNext] = useState('')
  const [confirm, setConfirm] = useState('')
  const rulesId = useId()
  const allMet = defaultPasswordRequirements.every((rule) => rule.test(next))
  const mismatch = confirm.length > 0 && confirm !== next

return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Change password</CardTitle>
        <CardDescription>Stays signed in here.</CardDescription>
      </CardHeader>
      <CardContent>
        <FieldGroup>
          <Field>
            <FieldLabel>Current password</FieldLabel>
            <PasswordInput defaultValue="hunter2hunter2" />
          </Field>
          <Field>
            <FieldLabel>New password</FieldLabel>
            <PasswordInput autoComplete="new-password" value={next} onValueChange={setNext} aria-describedby={rulesId} />
            <PasswordStrength value={next} />
            <PasswordRequirements id={rulesId} value={next} />
          </Field>
          <Field invalid={mismatch}>
            <FieldLabel>Confirm new password</FieldLabel>
            <PasswordInput autoComplete="new-password" value={confirm} onValueChange={setConfirm} />
            <FieldError>{mismatch ? 'Passwords don’t match yet.' : undefined}</FieldError>
          </Field>
        </FieldGroup>
      </CardContent>
      <CardFooter className="justify-end">
        <AsyncButton
          disabled={!allMet || confirm !== next}
          onAction={() => new Promise((resolve) => setTimeout(resolve, 900))}
          pendingLabel="Updating…"
          successLabel="Password updated"
        >
          Update password
        </AsyncButton>
      </CardFooter>
    </Card>
  )
}
```

A change-password card: the new password gets a strength meter and a requirements checklist, and the confirmation checks that the two match.

`PasswordRequirements` ticks each rule as the password meets it, with a drawn check. The defaults are `defaultPasswordRequirements`: at least eight characters, upper and lower case, a number and a symbol. Pass `requirements` as `{ label, test }` pairs for your own, and reuse the same list to decide when the form can submit, as the demo does.

### Reveal

```tsx
'use client'

import { Field, FieldError, FieldLabel, PasswordInput } from '@youj/react'

export default function PasswordInputStates() {
  return (
    <div className="grid w-full max-w-lg gap-6 sm:grid-cols-2">
      <Field>
        <FieldLabel>Revealed</FieldLabel>
        <PasswordInput defaultValue="correct horse" defaultVisible />
      </Field>
      <Field invalid>
        <FieldLabel>Password</FieldLabel>
        <PasswordInput defaultValue="nope" />
        <FieldError>That password is incorrect.</FieldError>
      </Field>
      <Field disabled>
        <FieldLabel>Disabled</FieldLabel>
        <PasswordInput defaultValue="secret" />
      </Field>
    </div>
  )
}
```

The visibility toggle.

The eye button shows the password as text and hides it again. Pressing it with a pointer keeps focus and the caret in the field, so people can check a character mid-word and carry on typing. `visible`, `defaultVisible` and `onVisibleChange` control it from outside. While Caps Lock is on, a quiet mark sits beside the eye and screen readers hear it once.

### Strength

```tsx
'use client'

import { PasswordStrength } from '@youj/react'

const SAMPLES = ['password', 'youj', 'youj42', 'Youj-42', 'Youj-42-motion!']

export default function PasswordInputStrength() {
  return (
    <dl className="grid w-full max-w-sm gap-4">
      {SAMPLES.map((sample) => (
        <div key={sample} className="grid gap-1.5">
          <dt className="font-mono text-ui-sm text-fg-muted">{sample}</dt>
          <dd>
            <PasswordStrength value={sample} />
          </dd>
        </div>
      ))}
    </dl>
  )
}
```

The strength meter as a password gets stronger.

`PasswordStrength` is a meter in four segments that fill from the inline start and tint from danger to success. The built-in estimate weighs length and character variety against common passwords, runs (`abc`, `321`) and repeats (`aaa`), and keeps anything under eight characters weak however varied it is. It's also exported on its own as `scorePassword`.

### Your own scorer

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, PasswordInput, PasswordStrength } from '@youj/react'

// A length-only policy for passphrases: every five characters earns a step.
const scoreLength = (password: string) => Math.min(4, Math.floor(password.length / 5))

export default function PasswordInputCustomScorer() {
  const [value, setValue] = useState('correct horse battery staple')

return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Passphrase</FieldLabel>
      <PasswordInput autoComplete="new-password" value={value} onValueChange={setValue} placeholder="four random words" />
      <PasswordStrength value={value} scorer={scoreLength} labels={['Too short', 'Short', 'Okay', 'Long', 'Passphrase']} />
      <FieldDescription>Four or more words beat any symbol.</FieldDescription>
    </Field>
  )
}
```

A strength meter using a scorer of your own.

Pass `scorer` for your own policy or a thorough estimator such as zxcvbn or a server check. It returns a 0 to 4 score, or `{ score, label }` to name the step. `labels` renames all five steps, very weak to strong.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add password-input
```

It brings `icon-caps-lock`, `icon-check`, `icon-eye`, `input-group`, `youj-core`, `youj-labels-password-input`, `youj-presets`, `youj-ui-core` with it.

The copy is 21 registry items, about 8,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-caps-lock`, `icon-check`, `icon-engine`, `icon-eye`, `icon-loader-ring`, `input`, `input-group` and 4 more.

Use it for every password: signing in, choosing a new one, confirming a change. `PasswordInput` alone is enough for a sign-in form. When people choose a password, add `PasswordStrength` and `PasswordRequirements` under it in the same [Field](https://www.youj.dev/docs/components/field), so the rules and the estimate update as they type. For a one-time code sent by email or an authenticator app, use [Input OTP](https://www.youj.dev/docs/components/input-otp) instead.

```tsx
import { useId, useState } from 'react'
import { Field, FieldLabel, PasswordInput, PasswordRequirements, PasswordStrength } from '@youj/react'

export function NewPassword() {
  const [value, setValue] = useState('')
  const rulesId = useId()
  return (
    <Field>
      <FieldLabel>New password</FieldLabel>
      <PasswordInput autoComplete="new-password" value={value} onValueChange={setValue} aria-describedby={rulesId} />
      <PasswordStrength value={value} />
      <PasswordRequirements id={rulesId} value={value} />
    </Field>
  )
}
```

`autoComplete` defaults to `current-password`. Set `new-password` when people choose one, so password managers offer to generate it. Point the input's `aria-describedby` at the checklist's `id` so the rules are read with the field.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` |  | Controlled visibility. |
| `defaultVisible` | `boolean` | `false` |  |
| `onVisibleChange` | `(visible: boolean) => void` |  |  |
| `autoComplete` | `string` | `'current-password'` |  |
| `groupClassName` | `string` |  | Wrapper class; `className` goes to the input. |

Also takes the props of `InputPrimitive.Props`.

`className` styles the input and `groupClassName` the group around it. Other Base UI Input props pass through, such as `value`, `onValueChange` and `name`.

#### PasswordStrength

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  | The password to score. |
| `scorer` | `(password: string) => number \| PasswordStrengthResult` |  | Your own estimate: a 0–4 score, or `{ score, label }`. |
| `labels` | `readonly [string, string, string, string, string]` |  | Five labels, very weak → strong. |

Also takes the props of `ComponentProps<'div'>`.

#### PasswordRequirements

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `requirements` | `PasswordRequirement[]` |  |  |

Also takes the props of `ComponentProps<'ul'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the eye blinks shut and open again |
| Slash on | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | drawn through the eye after a `fast` delay |
| Hide | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the slash retracts and the eye settles |
| Strength segments | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | fill from the inline start and tint, one stagger step apart; they empty from the far end |
| Strength label | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | color follows the score |
| Requirement met | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the check draws on |
| Check landing | `spring.settle` | 0.45s, bounce 0.3 | a small settle after a `base` delay |

**Reduced motion:** The eye swaps at once, segments fill without a stagger, and checks appear already drawn.

#### Reduced motion

The eye swaps between open and slashed at once, the strength segments fill together with no stagger, and met requirements show their check already drawn. Every state change is still visible and announced.

### Accessibility

- The reveal button is named "Show password" and reports its state with `aria-pressed`. It keeps focus in the field on a pointer press, and it's a normal button for the keyboard.
- Caps Lock is announced once through a polite live region when it turns on.
- `PasswordStrength` is a `meter` labeled "Password strength" with the step's name as its `aria-valuetext`. Because a meter's value isn't announced as it changes, the new step is announced politely, once per change.
- Each requirement reads as "Done:" or "Not yet:" before its label, so the checklist makes sense without its icons.
- `autoCapitalize`, `autoCorrect` and `spellCheck` are off, so a revealed password isn't changed or underlined.

---

# Input OTP

> Enter and verify a one-time code, with a countdown before resending.

Source: https://www.youj.dev/docs/components/input-otp

## Examples

### Demo

```tsx
'use client'

import {
  Button,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
  InputOTP,
  InputOTPResend,
  useOTPVerification,
} from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function InputOTPDemo() {
  // Runs when the last slot fills: verifying, then success or a shake and a cleared code.
  const otp = useOTPVerification(async (code) => {
    await wait(900)
    return code === '424242'
  })

return (
    <Card className="w-full max-w-[440px] min-w-0">
      <CardHeader>
        <CardTitle>Two-factor authentication</CardTitle>
        <CardDescription>Enter your 6-digit code.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Field invalid={otp.status === 'error'}>
          <FieldLabel>Authentication code</FieldLabel>
          <InputOTP groups={[3, 3]} {...otp.field} />
          <FieldError>{otp.status === 'error' ? 'That code didn’t match. Try again.' : undefined}</FieldError>
          <FieldDescription>
            Try <span className="font-mono text-fg">424242</span>. Anything else fails.
          </FieldDescription>
        </Field>
        <div className="flex items-center justify-between border-t border-line pt-3">
          <span className="text-ui-sm text-fg-muted">Didn’t get it?</span>
          <InputOTPResend seconds={15} onResend={() => wait(700)} className="-me-2" />
        </div>
        {otp.status === 'success' && (
          <Button variant="outline" size="sm" className="self-start" onClick={otp.reset}>
            Start over
          </Button>
        )}
      </CardContent>
    </Card>
  )
}
```

A two-factor card: a six-slot code in two groups of three, verified when the last digit is entered, with a resend button.

`InputOTPResend` holds "Resend code" behind a countdown ("Resend in 0:24") that starts straight away and restarts after each send. The send runs through AsyncButton's `onAction`, so it shows a spinner and then a check or an error in place. `seconds` sets the wait, 30 by default. While waiting, the button stays focusable, so keyboard users can read how long is left. `useCountdown` is exported for your own timers.

### Lengths and groups

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, InputOTP } from '@youj/react'

export default function InputOTPLengths() {
  return (
    <div className="flex max-w-full min-w-0 flex-col gap-6">
      <Field className="w-fit">
        <FieldLabel>PIN</FieldLabel>
        <InputOTP length={4} defaultValue="12" />
      </Field>
      <Field className="w-fit">
        <FieldLabel>Email code</FieldLabel>
        <InputOTP groups={[3, 3]} defaultValue="4829" />
      </Field>
      <Field className="w-fit">
        <FieldLabel>Recovery code</FieldLabel>
        {/* Letters and digits, upper-cased as they're typed or pasted. */}
        <InputOTP mode="alphanumeric" length={8} groups={[4, 4]} defaultValue="A7C9" />
        <FieldDescription>From the backup codes you saved when you turned on 2FA.</FieldDescription>
      </Field>
    </div>
  )
}
```

Codes of different lengths, groups and modes.

`length` sets 4 to 8 slots, 6 by default. `groups` splits a long code into readable chunks with a dash between them, such as `[3, 3]` or `[4, 4]`. `mode="alphanumeric"` accepts letters and digits and upper-cases them, for recovery and invite codes.

Pasting a code fills every slot at once. Spaces and dashes in the pasted text are dropped, so `424 242` and `424-242` both work.

### Status

```tsx
'use client'

import { InputOTP, type OTPStatus } from '@youj/react'

const STATES: { label: string; value: string; status?: OTPStatus; disabled?: boolean }[] = [
  { label: 'Verifying', value: '424242', status: 'verifying' },
  { label: 'Success', value: '424242', status: 'success' },
  { label: 'Error', value: '123456', status: 'error' },
  { label: 'Disabled', value: '42', disabled: true },
]

export default function InputOTPStates() {
  return (
    <dl className="grid gap-5">
      {STATES.map((state) => (
        <div key={state.label} className="grid gap-1.5">
          <dt className="text-ui-sm text-fg-muted">{state.label}</dt>
          <dd>
            <InputOTP aria-label={`${state.label} code`} defaultValue={state.value} status={state.status} disabled={state.disabled} />
          </dd>
        </div>
      ))}
    </dl>
  )
}
```

The verifying, success and error statuses.

Drive `status` yourself when verification lives somewhere else. `verifying` makes the field read-only with a spinner beside it, `success` turns the slots green from the inline start and draws a check, and `error` shakes the row and marks it invalid. `statusLabels` renames what's announced for each.

### Auto-submit

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, InputOTP } from '@youj/react'

export default function InputOTPAutoSubmit() {
  const [submitted, setSubmitted] = useState<string | null>(null)

return (
    <form
      className="flex w-fit flex-col gap-3"
      onSubmit={(event) => {
        event.preventDefault()
        setSubmitted(String(new FormData(event.currentTarget).get('code')))
      }}
    >
      <Field>
        <FieldLabel>Email code</FieldLabel>
        <InputOTP name="code" autoSubmit />
        <FieldDescription>The form submits itself as soon as the last digit lands.</FieldDescription>
      </Field>
      <p role="status" className="text-ui-sm text-fg-muted">
        {submitted ? `Submitted ${submitted}` : ''}
      </p>
    </form>
  )
}
```

A code that submits its form once it is complete.

Without verification in JavaScript, `autoSubmit` submits the owning form once the code is complete, and `onComplete` fires once each time the last slot fills.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add input-otp
```

It brings `async-button`, `async-feedback`, `field`, `icon-check`, `input`, `sliding-indicator`, `spinner`, `youj-core`, `youj-labels-input-otp`, `youj-ui-core` with it.

The copy is 23 registry items, about 9,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `collapse`, `field`, `icon-check`, `icon-engine`, `icon-loader-ring`, `input`, `label` and 4 more.

Use it for short codes people copy from somewhere else: an authenticator app, an email, a text message, a recovery sheet. It's one real input, laid over 4 to 8 slots that only draw it, so SMS autofill and password managers work, paste fills the whole code, and a screen reader meets one labeled field instead of six. For a secret people choose themselves, use a [Password Input](https://www.youj.dev/docs/components/password-input). For a quantity, use a [Number Input](https://www.youj.dev/docs/components/number-input).

```tsx
import { Field, FieldLabel, InputOTP, useOTPVerification } from '@youj/react'

export function VerifyCode() {
  const otp = useOTPVerification(async (code) => {
    const res = await fetch('/api/verify', { method: 'POST', body: code })
    return res.ok
  })
  return (
    <Field invalid={otp.status === 'error'}>
      <FieldLabel>Authentication code</FieldLabel>
      <InputOTP groups={[3, 3]} {...otp.field} />
    </Field>
  )
}
```

`useOTPVerification(verify)` runs `verify` once the last slot fills and drives `status` through verifying to success or error. Resolve `true`, or nothing, for success. Resolve `false`, or throw, for an error: the row shakes, and the code clears once the shake has played so the next attempt starts empty. Spread its `field` onto `InputOTP`, and call `reset()` to start over.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | `6` | Number of characters, 4–8. |
| `value` | `string` |  |  |
| `defaultValue` | `string` | `''` |  |
| `onValueChange` | `(value: string) => void` |  |  |
| `onComplete` | `(value: string) => void` |  | Called once each time the last slot is filled. |
| `autoSubmit` | `boolean` | `false` | Submit the owning form when the code is complete. |
| `mode` | `'numeric' \| 'alphanumeric'` | `'numeric'` | Digits only (default), or letters and digits (upper-cased), e.g. recovery codes. |
| `groups` | `number[]` |  | Slot grouping, e.g. [3, 3]. Groups are split by a dash. Default: one group. |
| `status` | `'idle' \| 'verifying' \| 'success' \| 'error'` | `'idle'` | verifying: read-only with a spinner. success: green slots and a drawn check. error: a shake. |
| `statusLabels` | `{ verifying?: string; success?: string; error?: string }` |  | Announced for each status. |
| `className` | `string` |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `ref` | `Ref<HTMLInputElement>` |  | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |

Also takes the props of `InputPrimitive.Props`.

Other Base UI Input props pass through, such as `name`, `aria-label` and `onFocus`.

#### InputOTPResend

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onResend` (required) | `() => unknown` |  | Sends a new code. Resolve for success; reject to show the error. |
| `seconds` | `number` | `30` | Seconds to wait between sends. |
| `autoStart` | `boolean` | `true` | Start waiting straight away (a code was just sent). |
| `waitingLabel` | `(time: string) => string` | ``Resend in 0:24`` | The label while waiting. |
| `children` | `string` |  |  |
| `variant` | `'default' \| 'danger' \| 'ghost' \| 'outline' \| 'link' \| 'secondary'` | `'ghost'` | `default \| secondary \| outline \| ghost \| danger \| link`. |
| `size` | `'default' \| 'sm' \| 'lg' \| 'xs' \| 'icon' \| 'icon-xs' \| 'icon-sm' \| 'icon-lg'` | `'sm'` |  |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the button plays `tap` as it's pressed. `false` keeps this one silent. |
| `pendingLabel` | `string` |  | Shown beside the spinner while the action runs, and announced. Announced as "Working…" when omitted. |
| `successLabel` | `string \| ((result: TResult) => string)` | `"Done"` | Shown beside the check and announced. A function gets what `onAction` resolved with: `successLabel={(user) => `Saved ${user.name}`}`. Under `status` there is no outcome to read, so pass a string. |
| `errorLabel` | `string \| ((error: unknown) => string)` | `"Failed"` | Shown beside the cross and announced assertively. A function gets what `onAction` rejected or threw with, whatever that is: `errorLabel={(error) => error instanceof Error ? error.message : 'Failed'}`. Under `status`, pass a string (`errorLabel={mutation.error?.message}`). |
| `resetAfter` | `number` |  | How long success / error hold before the label returns, in ms. Default: 3 × the deliberate token. |
| `onActionStateChange` | `(state: AsyncState) => void` |  | Fires on every state change: idle → pending → success \| error → idle. |
| `hold` | `boolean \| number` |  | Hold to confirm: the action runs only once a press is held (a pointer, or Space or Enter held down) for this long. `true` takes twice the deliberate motion token; a number is milliseconds. The button fills from its inline start while held and springs back if let go early; a full hold runs the action and the button carries on through pending to success or error. It is described as "Hold to confirm". |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Caret frame | `spring.smooth` | 0.36s, bounce 0 | one focus frame glides from slot to slot as you type or arrow (Sliding Indicator) |
| Character in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | each character rises 4px into its slot |
| Caret blink | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1); × 2 per blink | in an empty active slot |
| Success | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | slot borders turn green from the inline start, one tight stagger step apart |
| Success check | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | draws on beside the slots |
| Error shake | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | 4, 3 and 2px, decaying |
| Clear after error | `duration.slow` | 340ms | with `useOTPVerification`, once the shake has played |

**Reduced motion:** The frame jumps between slots, characters appear in place, the caret holds still, success tints every slot at once and errors don't shake.

#### Reduced motion

The focus frame jumps to the active slot, characters appear with no rise, the caret doesn't blink, success tints every slot at once and the check appears drawn, and an error marks the field without a shake. With `useOTPVerification`, the code clears straight after an error.

### Accessibility

- It's a single `<input>` with `autocomplete="one-time-code"`, `inputmode="numeric"` (or `text` in alphanumeric mode) and a pattern. The slots are hidden from assistive technology, so the field has one label and one value.
- Arrow keys move between slots (mirrored in right-to-left layouts), Home and ArrowUp go to the first, End and ArrowDown to the last, and typing over a filled slot replaces it.
- While verifying, the input is read-only and `aria-busy`. An error sets `aria-invalid`, so a surrounding Field shows its message.
- Verifying and success are announced politely, and errors assertively, through a live region beside the field.
- On touch screens the hidden text is 16px, so iOS doesn't zoom into the field on focus.

---

# Number Input

> Enter or step through a number, formatted for your locale, currency or unit.

Source: https://www.youj.dev/docs/components/number-input

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, NumberInput } from '@youj/react'

export default function NumberInputDemo() {
  const [budget, setBudget] = useState<number | null>(2400)

return (
    <Field className="w-64">
      <FieldLabel>Monthly budget</FieldLabel>
      <NumberInput
        value={budget}
        onValueChange={setBudget}
        min={0}
        max={50000}
        step={100}
        largeStep={1000}
        format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}
      />
      <FieldDescription>Alerts at 80%. Shift+arrows step by $1,000.</FieldDescription>
    </Field>
  )
}
```

A monthly budget formatted as US dollars, stepping by 100, or by 1,000 with Shift.

Arrow keys and the buttons move by `step`. Shift with an arrow moves by `largeStep`, which defaults to 10. Pressing and holding a button repeats, and Home and End jump to `min` and `max`. The mouse wheel doesn't change the value unless you set `allowWheelScrub`, because a page scrolling past a focused field shouldn't edit a form.

### Formats

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, NumberInput } from '@youj/react'

export default function NumberInputFormats() {
  return (
    <div className="grid w-full max-w-lg gap-6 sm:grid-cols-2">
      <Field>
        <FieldLabel>Discount</FieldLabel>
        {/* 0.15 shows as 15%, and steps of 0.05 move it by 5%. */}
        <NumberInput defaultValue={0.15} min={0} max={1} step={0.05} format={{ style: 'percent' }} />
      </Field>
      <Field>
        <FieldLabel>Memory</FieldLabel>
        <NumberInput defaultValue={4} min={1} max={64} format={{ style: 'unit', unit: 'gigabyte' }} />
      </Field>
      <Field>
        <FieldLabel>Rate limit</FieldLabel>
        <NumberInput defaultValue={120} min={10} max={1000} step={10} unit="req/min" />
      </Field>
      <Field>
        <FieldLabel>Seats</FieldLabel>
        <NumberInput defaultValue={1} min={1} max={5} />
        <FieldDescription>Up to five seats on this plan.</FieldDescription>
      </Field>
    </div>
  )
}
```

Currency, percent and unit formats.

`format` takes `Intl.NumberFormat` options, so currency, percent and units come from the platform: the symbol, the separators and the placement all follow the locale. A percent value is a fraction, so `0.15` shows as 15%. `unit` and `prefix` add a plain text addon instead, for units Intl doesn't know, like `req/min`.

### States and locales

```tsx
'use client'

import { Field, FieldError, FieldLabel, NumberInput } from '@youj/react'

export default function NumberInputStates() {
  return (
    <div className="grid w-full max-w-lg gap-6 sm:grid-cols-2">
      <Field invalid required>
        <FieldLabel>Replicas</FieldLabel>
        <NumberInput min={1} max={20} placeholder="1–20" />
        <FieldError>Run at least one replica.</FieldError>
      </Field>
      <Field disabled>
        <FieldLabel>Concurrency</FieldLabel>
        <NumberInput defaultValue={8} />
      </Field>
      <Field>
        <FieldLabel>Betrag</FieldLabel>
        {/* Reads and shows “1.234,50 €”, whatever the browser's locale. */}
        <NumberInput locale="de-DE" defaultValue={1234.5} step={0.5} format={{ style: 'currency', currency: 'EUR' }} />
      </Field>
      <Field>
        <FieldLabel>Build timeout</FieldLabel>
        <NumberInput defaultValue={15} min={1} max={60} unit="min" steppers={false} />
      </Field>
    </div>
  )
}
```

Invalid and disabled fields, a locale and the steppers option.

Inside an invalid Field the group takes the error treatment, and a disabled Field disables the input and both buttons. `locale` sets the parsing and display locale (default: the YoujProvider's locale, en-US without one), and `steppers={false}` drops the buttons for a plain formatted field.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add number-input
```

It brings `counter`, `field`, `icon-minus`, `icon-plus`, `input-group`, `youj-core`, `youj-labels-number-input`, `youj-ui-core` with it.

The copy is 22 registry items, about 8,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `counter`, `field`, `icon-engine`, `icon-loader-ring`, `icon-minus`, `icon-plus`, `input`, `input-group` and 5 more.

Use a number input when the answer is a quantity people adjust: a budget, a replica count, a timeout, a discount. It parses what they type in the locale it formats in, clamps it to `min` and `max`, and formats it back with `Intl.NumberFormat`. For a value picked along a range by feel, use a [Slider](https://www.youj.dev/docs/components/slider). For digits that aren't a quantity, such as a verification code or a phone number, use [Input OTP](https://www.youj.dev/docs/components/input-otp) or [Phone Input](https://www.youj.dev/docs/components/phone-input).

```tsx
import { useState } from 'react'
import { Field, FieldLabel, NumberInput } from '@youj/react'

export function Replicas() {
  const [replicas, setReplicas] = useState<number | null>(3)
  return (
    <Field>
      <FieldLabel>Replicas</FieldLabel>
      <NumberInput value={replicas} onValueChange={setReplicas} min={1} max={20} />
    </Field>
  )
}
```

The value is a `number`, or `null` when the field is empty. It's built on Base UI's NumberField and rendered as an [Input Group](https://www.youj.dev/docs/components/input-group), so it takes a [Field](https://www.youj.dev/docs/components/field)'s label, description, error and `required` with no extra wiring.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` |  |  |
| `defaultValue` | `number \| null` |  |  |
| `onValueChange` | `(value: number \| null) => void` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` | `1` | Per ArrowUp/Down and button press. |
| `largeStep` | `number` | `10` | Per Shift+ArrowUp/Down. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options: { style: 'currency', currency: 'USD' }, { style: 'percent' }, { style: 'unit', unit: 'gigabyte' }… |
| `locale` | `Intl.LocalesArgument` |  | Default: the YoujProvider locale. |
| `unit` | `ReactNode` |  | A plain suffix addon ("GB", "req/s"). |
| `prefix` | `ReactNode` |  | A plain prefix addon. |
| `allowWheelScrub` | `boolean` | `false` | Let the mouse wheel step the value while the field is focused. |
| `steppers` | `boolean` | `true` | Shows the − / + buttons. |
| `placeholder` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `readOnly` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `name` | `string` |  |  |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Step | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the number nudges 3px from the direction it moved: up for more, down for less |
| Stepper press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the − and + buttons press like every Button |

**Reduced motion:** The number changes in place with no nudge.

A held button fires a step on every repeat, and each one restarts the nudge, so a fast count reads as movement rather than a flicker. Typing a value never nudges: only steps from the keyboard, the buttons or the wheel do.

#### Reduced motion

Steps change the number in place, with no nudge. Formatting, clamping and press-and-hold are unchanged.

### Accessibility

- It's Base UI's NumberField: a text input described as a number field, inside a group, so screen readers hear the formatted value as it changes.
- ArrowUp and ArrowDown step by `step`, Shift with an arrow by `largeStep`, and Home and End go to the bounds.
- The steppers are named "Decrease" and "Increase". They stay out of the tab order, because the arrow keys already do their job from the input.
- Name it with a Field's label, or with `aria-label` on its own. A `unit` addon is visible text, so the label doesn't need to repeat it.

---

# Scrub Number Field

> A compact field you scrub: press its handle and move sideways, or type, or use the arrow keys.

Source: https://www.youj.dev/docs/components/scrub-number-field

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ScrubNumberField } from '@youj/react'

export default function ScrubNumberFieldDemo() {
  const [blur, setBlur] = useState(24)
  return (
    <div className="flex w-full max-w-xs flex-col items-start gap-4">
      <div className="w-40">
        <ScrubNumberField aria-label="Blur" label="B" unit="px" min={0} max={100} value={blur} onValueChange={setBlur} />
      </div>
      <div className="h-16 w-full rounded-lg bg-accent" style={{ filter: `blur(${blur / 8}px)` }} aria-hidden />
    </div>
  )
}
```

A blur radius, scrubbed with the mouse and shown on the bar below.

Press the **B** and move left or right: the value changes one step for every few pixels, and keeps following the pointer when it leaves the field. Hold Shift to go ten times coarser and Alt ten times finer, and change your mind mid-drag: the pace follows the key as it is now. The value stops at `min` and `max`. A click on the handle, without moving, just focuses the field.

### In a panel

```tsx
'use client'

import { ScrubNumberField } from '@youj/react'

export default function ScrubNumberFieldPair() {
  return (
    <div className="grid w-full max-w-xs grid-cols-2 gap-1.5">
      <ScrubNumberField aria-label="X" label="X" size="sm" defaultValue={12} />
      <ScrubNumberField aria-label="Y" label="Y" size="sm" defaultValue={-4} />
      <ScrubNumberField aria-label="Rotation" label="↻" size="sm" defaultValue={0} min={-180} max={180} unit="°" />
      <ScrubNumberField aria-label="Opacity" label="α" size="sm" defaultValue={0.5} min={0} max={1} step={0.1} />
    </div>
  )
}
```

Pairs of small fields, with a letter, a symbol, a unit and a 0 to 1 range.

The `label` is the drag handle: a letter, a symbol or an icon. `size="sm"` fits a dense panel such as an [Inspector Panel](https://www.youj.dev/docs/components/inspector-panel). `step={0.1}` makes Alt drag in hundredths.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add scrub-number-field
```

It brings `input-group`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

The copy is 18 registry items, about 8,000 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-engine`, `icon-loader-ring`, `input`, `input-group`, `label`, `separator`, `spinner` and 2 more.

Use a scrub number field where people tune a number by feel and want the exact value too: a position, a blur, a rotation, an opacity. For a quantity entered in a form, with steppers and locale formatting, use a [Number Input](https://www.youj.dev/docs/components/number-input); for a value on a visible range, a [Slider](https://www.youj.dev/docs/components/slider).

```tsx
import { useState } from 'react'
import { ScrubNumberField } from '@youj/react'

export function Blur() {
  const [blur, setBlur] = useState(24)
  return <ScrubNumberField aria-label="Blur" label="B" unit="px" min={0} max={100} value={blur} onValueChange={setBlur} />
}
```

The value is a `number`. Typed text commits on Enter or blur and is clamped but not snapped to the step, so `12.5` stays `12.5`; text that isn't a number is put back. Both `.` and `,` are read as a decimal separator.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  |  |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `(value: number) => void` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` | `1` | Per ArrowUp/Down and per few pixels of drag. |
| `largeStep` | `number` | `step * 10` | Per PageUp/PageDown. |
| `label` | `ReactNode` |  | The drag handle: an icon, or a letter. Hidden from assistive tech; name the field with `aria-label`. |
| `unit` | `string` |  | A plain suffix inside the field: "px", "%", "°". |
| `size` | `'sm' \| 'default'` | `'default'` | `sm` fits a dense panel. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `disabled` | `boolean` |  |  |
| `readOnly` | `boolean` |  |  |
| `invalid` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `name` | `string` |  |  |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  | Names the field for assistive tech ("Blur"). |
| `aria-labelledby` | `string` |  |  |

#### Data attributes

The root carries `data-slot="scrub-number-field"` and `data-size` (`sm` or `default`), plus `data-yj-scrubbing` while the handle is being dragged. The handle is `scrub-number-field-handle` in `data-slot`.

### Accessibility

- The field is an input with `role="spinbutton"` and `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and an `aria-valuetext` that reads the value with its unit ("24 px"). Name it with `aria-label` or `aria-labelledby`; the handle is hidden from assistive technology.
- ArrowUp and ArrowDown step by `step`, with Shift ×10 and Alt ×0.1. PageUp and PageDown step by `largeStep` (default ten steps). Home and End go to `min` and `max`.
- Dragging is an extra for pointer users: everything it does is available from the keyboard.
- The mouse wheel never changes the value, so a scrolling page doesn't edit a form.
- Nothing animates, so there is no reduced motion to honor; a drag changes the value directly.

---

# Phone Input

> Enter a phone number with a country picker, live formatting and E.164 storage.

Source: https://www.youj.dev/docs/components/phone-input

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldError, FieldLabel, PhoneInput, type PhoneInputChange } from '@youj/react'

export default function PhoneInputDemo() {
  const [value, setValue] = useState('+14155550123')
  const [details, setDetails] = useState<PhoneInputChange | null>(null)
  const [touched, setTouched] = useState(false)
  const incomplete = touched && !!value && details?.complete === false

return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <Field invalid={incomplete} onBlur={() => setTouched(true)}>
        <FieldLabel>Mobile number</FieldLabel>
        <PhoneInput
          value={value}
          onValueChange={(next, change) => {
            setValue(next)
            setDetails(change)
          }}
        />
        <FieldError>{incomplete ? `That’s short for a ${details!.country.name} number.` : undefined}</FieldError>
        <FieldDescription>We’ll text a code to confirm it. Paste +44 20 7946 0958 to switch country.</FieldDescription>
      </Field>
      <code className="font-mono text-ui-sm text-fg-muted">value: {value || '""'}</code>
    </div>
  )
}
```

A mobile number field starting with a US number, with the stored E.164 value shown beneath it.

### Typing and pasting

```tsx
'use client'

import { PhoneInput } from '@youj/react'

// E.164 values: each picks its country and shows in that country's pattern.
const NUMBERS = [
  { label: 'London office', value: '+442079460958' },
  { label: 'Paris mobile', value: '+33612345678' },
  { label: 'Tokyo mobile', value: '+819012345678' },
  { label: 'São Paulo mobile', value: '+5511912345678' },
]

export default function PhoneInputFormats() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      {NUMBERS.map((number) => (
        <PhoneInput key={number.value} aria-label={number.label} defaultValue={number.value} />
      ))}
    </div>
  )
}
```

Formatting as you type, and the country switching on a pasted international number.

The national number is formatted from a pattern per country as you type: `(415) 555-0123` in the US, `2079 460958` in the UK, where the pattern groups the national digits without the leading 0. The caret stays after the digit you typed, whatever punctuation the pattern adds, and Backspace over a space or dash deletes the digit before it. Typing or pasting an international number, such as `+44 20 7946 0958` or `0044…`, switches the country by itself.

Formatting is deliberately small: one pattern per country and no carrier rules. Validate strictly on the server, or with a library such as libphonenumber-js, before you rely on a number.

### Countries

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, PHONE_COUNTRIES, PhoneInput } from '@youj/react'

// Only the countries this service delivers to, from the starter set.
const EUROPE = PHONE_COUNTRIES.filter((country) => ['AT', 'BE', 'DE', 'ES', 'FR', 'IT', 'NL', 'PT'].includes(country.code))

export default function PhoneInputCountries() {
  return (
    <div className="grid w-full max-w-lg gap-6 sm:grid-cols-2">
      <Field>
        <FieldLabel>Delivery contact</FieldLabel>
        <PhoneInput name="phone" countries={EUROPE} defaultCountry="DE" />
        <FieldDescription>We deliver within the EU.</FieldDescription>
      </Field>
      <Field disabled>
        <FieldLabel>Account phone</FieldLabel>
        <PhoneInput defaultValue="+4930123456" disabled />
        <FieldDescription>Managed by your organization.</FieldDescription>
      </Field>
    </div>
  )
}
```

A narrowed set of countries.

The starter set, `PHONE_COUNTRIES`, covers 51 countries. Pass `countries` to narrow it to where you operate, or to add your own as `{ code, name, dial, pattern }`, with a `#` per digit in the pattern. `defaultCountry` sets the starting country by ISO code, `US` by default.

`flagOf`, `formatNational` and `parsePhone` are exported for showing and parsing stored numbers elsewhere in your app.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add phone-input
```

It brings `input-group`, `select`, `youj-core`, `youj-labels-phone-input`, `youj-ui-core` with it.

The copy is 23 registry items, about 8,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-check`, `icon-chevron-down`, `icon-chevron-up`, `icon-engine`, `icon-loader-ring`, `input`, `input-group` and 6 more.

Use it wherever you ask for a phone number: a mobile for verification codes, a contact for deliveries, a support callback. People pick a country from a list of flags (type a country's name to jump to it), type the national number in the pattern they know, and your code gets one unambiguous value, `+14155550123`. For a verification code sent to that number, use [Input OTP](https://www.youj.dev/docs/components/input-otp). For a free-form contact field that might hold anything, a plain [Input](https://www.youj.dev/docs/components/input) with `type="tel"` is enough.

```tsx
import { useState } from 'react'
import { Field, FieldLabel, PhoneInput } from '@youj/react'

export function MobileNumber() {
  const [phone, setPhone] = useState('')
  return (
    <Field>
      <FieldLabel>Mobile number</FieldLabel>
      <PhoneInput value={phone} onValueChange={setPhone} defaultCountry="GB" />
    </Field>
  )
}
```

The value is E.164: a `+`, the calling code and the national digits, with no spaces. `onValueChange` also passes the chosen `country`, the `national` digits and whether the number is `complete` for that country's pattern, which the demo uses to flag a short number when the field loses focus. Give it a `name` to submit the E.164 value with a form.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | E.164, e.g. '+14155550123'. |
| `defaultValue` | `string` |  |  |
| `onValueChange` | `(value: string, details: PhoneInputChange) => void` |  |  |
| `defaultCountry` | `string` | `'US'` | ISO code of the country to start with. |
| `countries` | `PhoneCountry[]` | `PHONE_COUNTRIES` |  |
| `name` | `string` |  | Submits the E.164 value in a hidden input. |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `placeholder` | `string` |  |  |
| `className` | `string` |  |  |
| `id` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `aria-describedby` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Country list opens | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the Select popup scales from 96% and fades in (`yj-pop`) |
| Country list closes | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the trigger and the field, like every control |

**Reduced motion:** The country list opens and closes at once. Formatting is unchanged.

#### Reduced motion

The country list appears and disappears at once. Typing, formatting and country detection behave the same.

### Accessibility

- The number is a `type="tel"` input with `autocomplete="tel-national"`, so browsers and password managers can fill it, and phones show the dial pad.
- The country trigger has its own name, such as "Country, United Kingdom +44", so inside a Field the Field's label names the number and not the country.
- The country list is a [Select](https://www.youj.dev/docs/components/select): type a country's name to jump to it, arrow through the list and press Enter. Choosing one moves focus back to the number.
- Flags are decorative and hidden from assistive technology. Each option reads as its country name.

---

# Checkbox

> Select an option with checked, unchecked and mixed states.

Source: https://www.youj.dev/docs/components/checkbox

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Checkbox, Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet } from '@youj/react'

const TOPICS = [
  { id: 'mentions', label: 'Mentions', description: 'Someone mentions you or replies to your thread.' },
  { id: 'deployments', label: 'Failed deployments', description: 'A production or preview build fails.' },
  { id: 'domains', label: 'Domains', description: 'A certificate renews or a DNS record changes.' },
  { id: 'billing', label: 'Billing', description: 'Invoices, usage alerts and plan changes.' },
]

export default function CheckboxDemo() {
  const [on, setOn] = useState(['mentions', 'deployments'])
  const all = on.length === TOPICS.length
  const some = on.length > 0 && !all

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-5">
      <FieldSet>
        <FieldLegend>Email notifications</FieldLegend>
        {/* The parent is mixed while only some topics are on. Ticking it turns them all on. */}
        <Field orientation="horizontal" className="border-b border-line pb-4">
          <Checkbox checked={all} indeterminate={some} onCheckedChange={(next) => setOn(next ? TOPICS.map((t) => t.id) : [])} />
          <FieldLabel>Everything</FieldLabel>
        </Field>
        {TOPICS.map((topic) => (
          <Field key={topic.id} orientation="horizontal">
            <Checkbox
              checked={on.includes(topic.id)}
              onCheckedChange={(next) => setOn((current) => (next ? [...current, topic.id] : current.filter((id) => id !== topic.id)))}
            />
            <FieldContent>
              <FieldLabel>{topic.label}</FieldLabel>
              <FieldDescription>{topic.description}</FieldDescription>
            </FieldContent>
          </Field>
        ))}
      </FieldSet>
    </div>
  )
}
```

Email notification topics under an "Everything" checkbox that is mixed while only some of them are on.

A parent that stands for a group is mixed while only some of its children are checked. Derive `checked` and `indeterminate` from the children, and let the parent's change set all of them. The mixed state draws a dash and reports `aria-checked="mixed"`. Try it in the demo.

```tsx
const all = on.length === topics.length
const some = on.length > 0 && !all

<Checkbox
  checked={all}
  indeterminate={some}
  onCheckedChange={(next) => setOn(next ? topics.map((t) => t.id) : [])}
/>
```

### States

```tsx
'use client'

import { Checkbox, Field, FieldLabel } from '@youj/react'

export default function CheckboxStates() {
  return (
    <div className="grid w-full max-w-lg grid-cols-2 gap-x-8 gap-y-5 sm:grid-cols-3">
      <Field orientation="horizontal">
        <Checkbox />
        <FieldLabel>Unchecked</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Checkbox defaultChecked />
        <FieldLabel>Checked</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Checkbox indeterminate />
        <FieldLabel>Mixed</FieldLabel>
      </Field>
      {/* A Field marked invalid reaches the control, which draws its box in the danger color. */}
      <Field orientation="horizontal" invalid>
        <Checkbox />
        <FieldLabel>Invalid</FieldLabel>
      </Field>
      <Field orientation="horizontal" disabled>
        <Checkbox />
        <FieldLabel>Disabled</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Checkbox readOnly defaultChecked />
        <FieldLabel>Read-only</FieldLabel>
      </Field>
    </div>
  )
}
```

Disabled, invalid and read-only checkboxes.

`disabled` and `invalid` go on the `Field`, which passes them to the control and dims or colors the label with it. `readOnly` keeps the value visible and reachable by keyboard, but it can't change.

### Choice cards

```tsx
'use client'

import { Checkbox, Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet, FieldTitle } from '@youj/react'

const ENVIRONMENTS = [
  { id: 'production', title: 'Production', description: 'youj.io and every production alias.', checked: true },
  { id: 'preview', title: 'Preview', description: 'Branch and pull request deployments.', checked: true },
  { id: 'development', title: 'Development', description: 'Pulled by the CLI for local runs.' },
]

export default function CheckboxCards() {
  return (
    <FieldSet className="w-full max-w-xl">
      <FieldLegend variant="label">Environments</FieldLegend>
      <FieldDescription>Where DATABASE_URL is available. Changes apply to the next deployment.</FieldDescription>
      <div className="grid gap-2.5 sm:grid-cols-3">
        {ENVIRONMENTS.map((env) => (
          // A FieldLabel around a Field makes a choice card: the whole card is the target and carries the focus ring.
          <FieldLabel key={env.id}>
            <Field orientation="horizontal" name={env.id}>
              <FieldContent>
                <FieldTitle>{env.title}</FieldTitle>
                <FieldDescription>{env.description}</FieldDescription>
              </FieldContent>
              <Checkbox defaultChecked={env.checked} />
            </Field>
          </FieldLabel>
        ))}
      </div>
    </FieldSet>
  )
}
```

Checkboxes as choice cards.

Wrap a `Field` in a `FieldLabel` to turn the whole card into the target. The card takes the focus ring from the checkbox inside it, and it tints when checked. Use `FieldTitle` for the card's title, since a label can't contain another label.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add checkbox
```

It brings `field`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Checkbox for options submitted with a form or for selecting several items. Use a [Switch](https://www.youj.dev/docs/components/switch) for settings that apply immediately, or a [Radio Group](https://www.youj.dev/docs/components/radio-group) for a single choice.

Put the checkbox in a `Field` with a `FieldLabel`. The label names the control, and clicking it toggles the box.

```tsx
import { Checkbox, Field, FieldLabel } from '@youj/react'

export function RememberDevice() {
  return (
    <Field orientation="horizontal">
      <Checkbox defaultChecked />
      <FieldLabel>Remember this device</FieldLabel>
    </Field>
  )
}
```

It's uncontrolled with `defaultChecked`. To own the state, pass `checked` and `onCheckedChange`. Inside a form, `name` and `value` submit it like a native checkbox, and `required` on the surrounding `Field` marks the label and makes the box required.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), ticking plays `toggleOn` and unticking `toggleOff`. `false` keeps this one silent. |

Also takes the props of `CheckboxPrimitive.Root.Props`.

The props you'll use most come from Base UI:

| Prop | Type | Description |
| --- | --- | --- |
| `checked` | `boolean` | Controlled state. Pair it with `onCheckedChange`. |
| `defaultChecked` | `boolean` | Initial state, uncontrolled. Default `false`. |
| `onCheckedChange` | `(checked, details) => void` | Called on every tick and untick. |
| `indeterminate` | `boolean` | Shows the mixed state and reports `aria-checked="mixed"`. |
| `disabled` | `boolean` | Ignores presses. Set it on the `Field` to dim the label too. |
| `readOnly` | `boolean` | Keeps the current value. |
| `required` | `boolean` | Must be checked before the form submits. Defaults to the `Field`'s `required`. |
| `name`, `value` | `string` | What the hidden input submits. With no `value`, a checked box submits `"on"`. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the stroke draws from zero on every tick |
| Check lands | `spring.settle` | 0.45s, bounce 0.3 | the mark settles from 88% scale, after a `base` delay |
| Mixed dash | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | draws from the start of the line |
| Uncheck | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the glyph fades |
| Box fill | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | background and border color |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the box squeezes to 90% |

**Reduced motion:** The check and the dash appear whole, and the box doesn't squeeze on press. The fill still changes color.

A tick is a small arrival, so the check earns the `settle` spring, Youj's one overshoot. The indicator stays mounted while unchecked, so a tick that reverses mid-draw continues from where the stroke is, with no jump.

#### Reduced motion

The check appears whole instead of drawing, and pressing doesn't squeeze the box. Checked, unchecked and mixed still look different, so the state reads the same without the motion.

### Accessibility

- It's a `checkbox` role with `aria-checked` of `true`, `false` or `mixed`. `Space` toggles it and `Enter` doesn't, as with a native checkbox.
- A `FieldLabel` in the same `Field` names it. Outside a `Field`, use `Label` with `htmlFor` and an `id`, or an `aria-label`.
- The 16px box has a 24px hit area, and 40px on touch screens.
- The box's border clears 3:1 against the page, and focus shows a 2px accent outline.

---

# Radio Group

> Choose one option from a visible list or a set of cards.

Source: https://www.youj.dev/docs/components/radio-group

## Examples

### Demo

```tsx
'use client'

import {
  Badge,
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
  FieldLegend,
  FieldSet,
  FieldTitle,
  RadioGroup,
  RadioGroupItem,
} from '@youj/react'

const PLANS = [
  { value: 'hobby', title: 'Hobby', price: '$0', description: 'Side projects. One member and community support.' },
  { value: 'pro', title: 'Pro', price: '$20', description: 'Teams that ship daily. Previews, analytics and priority support.', popular: true },
  { value: 'enterprise', title: 'Enterprise', price: 'Custom', description: 'SSO, audit logs, an uptime SLA and a named contact.' },
]

export default function RadioGroupDemo() {
  return (
    <FieldSet className="w-full max-w-md">
      <FieldLegend>Plan</FieldLegend>
      <FieldDescription>Change or cancel at any time. Billing is prorated to the day.</FieldDescription>
      <RadioGroup defaultValue="pro" name="plan">
        {PLANS.map((plan) => (
          // A FieldLabel around a Field makes the whole card the target.
          <FieldLabel key={plan.value}>
            <Field orientation="horizontal">
              <FieldContent>
                <FieldTitle>
                  {plan.title}
                  {plan.popular && <Badge>Popular</Badge>}
                </FieldTitle>
                <FieldDescription>{plan.description}</FieldDescription>
              </FieldContent>
              <span className="text-ui font-medium text-fg tabular-nums">{plan.price}</span>
              <RadioGroupItem value={plan.value} />
            </Field>
          </FieldLabel>
        ))}
      </RadioGroup>
    </FieldSet>
  )
}
```

A plan picker as choice cards, with Pro chosen.

The demo wraps each `Field` in a `FieldLabel`, so the whole card is the target. The card tints when it's chosen and carries the focus ring for the radio inside it. Put the title in a `FieldTitle`, since a label can't contain another label.

### Lists

```tsx
'use client'

import { Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet, RadioGroup, RadioGroupItem } from '@youj/react'

const MACHINES = [
  { value: 'standard', label: 'Standard', detail: '4 vCPUs, 8 GB of memory' },
  { value: 'enhanced', label: 'Enhanced', detail: '8 vCPUs, 16 GB of memory' },
  { value: 'turbo', label: 'Turbo', detail: '30 vCPUs, 60 GB. Enterprise plans only.', disabled: true },
]

export default function RadioGroupList() {
  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend variant="label">Build machine</FieldLegend>
      <RadioGroup defaultValue="standard" name="machine">
        {MACHINES.map((machine) => (
          <Field key={machine.value} orientation="horizontal" disabled={machine.disabled}>
            <RadioGroupItem value={machine.value} />
            <FieldContent>
              <FieldLabel>{machine.label}</FieldLabel>
              <FieldDescription>{machine.detail}</FieldDescription>
            </FieldContent>
          </Field>
        ))}
      </RadioGroup>
    </FieldSet>
  )
}
```

A plain list with a disabled option.

A plain list suits short options. Put `disabled` on an option's `Field` to dim its label with it. The arrow keys skip disabled options.

### In a row

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, FieldLegend, FieldSet, RadioGroup, RadioGroupItem } from '@youj/react'

const CHANNELS = [
  { value: 'stable', label: 'Stable', note: 'Updates after two weeks in beta.' },
  { value: 'beta', label: 'Beta', note: 'New features a few days early.' },
  { value: 'canary', label: 'Canary', note: 'Every merged change. Expect rough edges.' },
]

export default function RadioGroupInline() {
  const [channel, setChannel] = useState('stable')
  const current = CHANNELS.find((c) => c.value === channel)

return (
    <FieldSet className="w-full max-w-md">
      <FieldLegend variant="label">Release channel</FieldLegend>
      {/* A short set can sit in a row. Arrow keys move the choice in any layout. */}
      <RadioGroup value={channel} onValueChange={(value) => setChannel(value as string)} className="flex flex-wrap gap-x-6 gap-y-3">
        {CHANNELS.map((c) => (
          <Field key={c.value} orientation="horizontal" className="w-auto">
            <RadioGroupItem value={c.value} />
            <FieldLabel>{c.label}</FieldLabel>
          </Field>
        ))}
      </RadioGroup>
      <FieldDescription>{current?.note}</FieldDescription>
    </FieldSet>
  )
}
```

A short set laid out in a row, with the choice controlled.

Short sets can sit in a row. The arrow keys move the choice in any layout, and here the choice is controlled, so the description follows it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add radio-group
```

It brings `field`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Radio Group when people need to choose one option and see the full list. Use a [Select](https://www.youj.dev/docs/components/select) for longer lists, [Checkboxes](https://www.youj.dev/docs/components/checkbox) for choices that can combine, or a [Toggle Group](https://www.youj.dev/docs/components/toggle-group) for view settings.

Each `RadioGroupItem` sits in its own `Field` with a `FieldLabel`. Name the group with a `FieldSet` and `FieldLegend`, or with `aria-label` on the `RadioGroup`.

```tsx
import { Field, FieldLabel, FieldLegend, FieldSet, RadioGroup, RadioGroupItem } from '@youj/react'

export function Density() {
  return (
    <FieldSet>
      <FieldLegend variant="label">Density</FieldLegend>
      <RadioGroup defaultValue="comfortable" name="density">
        <Field orientation="horizontal">
          <RadioGroupItem value="comfortable" />
          <FieldLabel>Comfortable</FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <RadioGroupItem value="compact" />
          <FieldLabel>Compact</FieldLabel>
        </Field>
      </RadioGroup>
    </FieldSet>
  )
}
```

`defaultValue` makes it uncontrolled. Pass `value` and `onValueChange` to own the choice, and `name` to submit it with a form.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

Takes the props of `RadioGroupPrimitive.Props`.

#### RadioGroupItem

Takes the props of `RadioPrimitive.Root.Props`.

The group takes Base UI's `value`, `defaultValue`, `onValueChange`, `name`, `disabled`, `readOnly` and `required`. Each item takes a `value`, plus its own `disabled`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Dot in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the chosen dot grows from zero |
| Dot out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the previous dot shrinks away at the same time |
| Ring fill | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | background and border color |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the ring squeezes to 90% |

**Reduced motion:** The dot appears and disappears without scaling, and the ring doesn't squeeze on press.

The dot is a CSS transition, so a choice that changes mid-way picks up from the dot's current scale.

#### Reduced motion

The dot switches on and off without growing, and the press doesn't squeeze. The chosen option still shows the filled ring and the dot, so the choice reads the same.

### Accessibility

- The group is one tab stop. `Tab` lands on the chosen option, the arrow keys move the choice and wrap at the ends, and `Space` selects the focused option.
- The group is a `radiogroup`, named by its `FieldLegend` or `aria-label`. Each item is a `radio`, named by its `FieldLabel`.
- `required` on the group or its `Field` makes a choice mandatory before the form submits.
- Each 16px radio has a 24px hit area, and 40px on touch screens.

---

# Choice Card

> Pick from options shown as cards, with an icon, a description and a radio, checkbox or switch.

Source: https://www.youj.dev/docs/components/choice-card

## Examples

### Demo

```tsx
'use client'

import { ChoiceCard, ChoiceCardGroup, FieldLegend, FieldSet } from '@youj/react'
import { EyeIcon, ShieldIcon, SquarePenIcon, WalletIcon } from '@youj/icons'

const ACCESS = [
  { value: 'manage', icon: <ShieldIcon />, title: 'Manage', description: 'Members, billing and every project' },
  { value: 'build', icon: <SquarePenIcon />, title: 'Build', description: 'Create, edit and publish projects' },
  { value: 'review', icon: <EyeIcon />, title: 'Review', description: 'Comment on and approve changes' },
  { value: 'billing', icon: <WalletIcon />, title: 'Billing', description: 'Invoices and payment methods only' },
]

export default function ChoiceCardDemo() {
  return (
    <FieldSet className="w-full max-w-lg">
      <FieldLegend variant="label">Access level</FieldLegend>
      <ChoiceCardGroup defaultValue="build" name="access" columns={2}>
        {ACCESS.map((access) => (
          <ChoiceCard key={access.value} {...access} />
        ))}
      </ChoiceCardGroup>
    </FieldSet>
  )
}
```

An access-level picker as a two-column grid of radio cards, with Build chosen.

The whole card is the target. When its control is on, the card's edge doubles in the accent and its icon tile tints. Tab lands on the chosen card and the arrow keys move the choice.

### Option rows

```tsx
'use client'

import { ChoiceCard, ChoiceCardGroup, FieldLegend, FieldSet } from '@youj/react'

export default function ChoiceCardOptions() {
  return (
    <FieldSet className="w-full max-w-xl">
      <FieldLegend variant="label">When the build minutes run out</FieldLegend>
      <ChoiceCardGroup defaultValue="queue" name="overage">
        <ChoiceCard value="queue" title="Queue until the cycle resets" badge="Suggested" note="No extra cost" />
        <ChoiceCard value="burst" title="Buy a burst pack" note="+1,000 min for $12" />
        <ChoiceCard value="stop" title="Stop non-production builds" note="Production keeps running" />
      </ChoiceCardGroup>
    </FieldSet>
  )
}
```

Three ways to handle an overage, one marked as suggested, each with what it means at the row's end.

A string `badge` becomes a [Badge](https://www.youj.dev/docs/components/badge) beside the title; pass a node for anything else. `note` sits at the end of a horizontal card, for a price, a limit or a consequence.

### Switch cards

```tsx
'use client'

import { useState } from 'react'
import { ChoiceCard, ChoiceCardGroup, HatchedBar } from '@youj/react'
import { LayersIcon, MoonIcon, TimerIcon } from '@youj/icons'

const LEVERS = [
  { id: 'cache', icon: <LayersIcon />, title: 'Cache dependencies', saving: 0.32, minutes: '−410 min', description: 'Reuse installs between builds on the same lockfile.' },
  { id: 'sleep', icon: <MoonIcon />, title: 'Sleep idle previews', saving: 0.18, minutes: '−230 min', description: 'Previews nobody opened for a day stop until visited.' },
  { id: 'batch', icon: <TimerIcon />, title: 'Batch docs builds', saving: 0.09, minutes: '−115 min', description: 'Docs-only commits build once an hour.' },
]

export default function ChoiceCardSwitches() {
  const [on, setOn] = useState<Record<string, boolean>>({ cache: true })
  return (
    <ChoiceCardGroup control="switch" aria-label="Ways to save build minutes" columns={3} className="w-full max-w-3xl">
      {LEVERS.map((lever) => (
        <ChoiceCard
          key={lever.id}
          orientation="vertical"
          icon={lever.icon}
          title={lever.title}
          description={lever.description}
          checked={!!on[lever.id]}
          onCheckedChange={(checked) => setOn((prev) => ({ ...prev, [lever.id]: checked }))}
        >
          <div className="flex flex-col gap-2">
            <span className="text-ui-lg font-medium text-fg tabular-nums">{lever.minutes}</span>
            <div className="overflow-hidden rounded-full bg-band">
              <HatchedBar
                orientation="horizontal"
                value={lever.saving}
                max={0.4}
                tone={on[lever.id] ? 'success' : 'neutral'}
                fill={on[lever.id] ? 'solid' : 'hatched'}
              />
            </div>
          </div>
        </ChoiceCard>
      ))}
    </ChoiceCardGroup>
  )
}
```

Ways to save build minutes as vertical switch cards, each with its saving as a figure and a meter.

`orientation="vertical"` puts the icon and the control on top and the text under them. Children go under the description, so a meter or a figure belongs to the card it describes. Each switch is its own tab stop.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add choice-card
```

It brings `badge`, `checkbox`, `field`, `radio-group`, `switch`, `youj-presets`, `youj-ui-core` with it.

The copy is 14 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `badge`, `checkbox`, `collapse`, `field`, `icon-engine`, `icon-x`, `label`, `radio-group`, `separator`, `switch`.

Use Choice Cards when each option needs a sentence or a figure to be chosen well: plans, roles, strategies, settings. For short options a [Radio Group](https://www.youj.dev/docs/components/radio-group) or [Checkboxes](https://www.youj.dev/docs/components/checkbox) take less room.

```tsx
import { ChoiceCard, ChoiceCardGroup, FieldLegend, FieldSet } from '@youj/react'

export function AccessLevel() {
  return (
    <FieldSet>
      <FieldLegend variant="label">Access level</FieldLegend>
      <ChoiceCardGroup defaultValue="build" name="access" columns={2}>
        <ChoiceCard value="manage" title="Manage" description="Members, billing and every project" />
        <ChoiceCard value="build" title="Build" description="Create, edit and publish projects" />
      </ChoiceCardGroup>
    </FieldSet>
  )
}
```

A plan picker uses the other slots. `title` and `description` name the plan, `badge` marks the suggested one, `note` puts the price at the row's end, and `children` go under the description, here the plan's limit. Horizontal cards (the default) are rows; `orientation="vertical"` makes them tall cards for a three-column pricing grid, and moves the price into `children`, since `note` is for rows:

```tsx
import { ChoiceCard, ChoiceCardGroup, FieldLegend, FieldSet } from '@youj/react'

export function PlanPicker() {
  return (
    <FieldSet>
      <FieldLegend variant="label">Plan</FieldLegend>
      <ChoiceCardGroup defaultValue="pro" name="plan">
        <ChoiceCard value="hobby" title="Hobby" description="For side projects" note="$0 / mo">
          <p className="text-ui-sm text-fg-muted">3 projects</p>
        </ChoiceCard>
        <ChoiceCard value="pro" title="Pro" description="For a team shipping weekly" badge="Suggested" note="$20 / mo">
          <p className="text-ui-sm text-fg-muted">Unlimited projects</p>
        </ChoiceCard>
      </ChoiceCardGroup>
    </FieldSet>
  )
}
```

```tsx
<ChoiceCardGroup defaultValue="pro" name="plan" columns={3}>
  <ChoiceCard orientation="vertical" value="hobby" title="Hobby" description="For side projects">
    <p className="text-ui-lg font-semibold">$0 / mo</p>
  </ChoiceCard>
  <ChoiceCard orientation="vertical" value="pro" title="Pro" description="For a team" badge="Suggested">
    <p className="text-ui-lg font-semibold">$20 / mo</p>
  </ChoiceCard>
  <ChoiceCard orientation="vertical" value="scale" title="Scale" description="For a company">
    <p className="text-ui-lg font-semibold">$90 / mo</p>
  </ChoiceCard>
</ChoiceCardGroup>
```

`ChoiceCardGroup` sets the control for its cards. `control="radio"` (the default) is one choice: `value`, `defaultValue` and `onValueChange` take a string. `control="checkbox"` is any number: they take the list of ticked values. `control="switch"` groups independent toggles, and each card takes its own `checked`, `defaultChecked` and `onCheckedChange`. A card outside a group is a checkbox unless its `control` says otherwise.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The card's value in a radio or checkbox group. |
| `control` | `'radio' \| 'checkbox' \| 'switch'` |  | The control. Defaults to the group's, or `checkbox` outside a group. |
| `checked` | `boolean` |  | On or off, for a checkbox or switch card that isn't in a checkbox group. |
| `defaultChecked` | `boolean` |  |  |
| `onCheckedChange` | `(checked: boolean) => void` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `icon` | `ReactNode` |  | A small mark in a tile at the card's start (decorative). |
| `badge` | `ReactNode` |  | Beside the title: a string becomes a Badge ("Suggested"), any other node shows as given. |
| `note` | `ReactNode` |  | Trailing text at the row's end, such as what the choice costs. Horizontal cards only. |
| `children` | `ReactNode` |  | Anything under the description: a meter, a figure, a link. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | `horizontal` (default): one row, the control first. `vertical`: the icon and control on top, the text under them. |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Submits a standalone checkbox or switch with a native form. |
| `id` | `string` |  |  |
| `className` | `string` |  |  |

#### ChoiceCardGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `1 \| 2 \| 3 \| 4` | `1` | Cards per row from the `sm` breakpoint up (3 and 4 reach that count at `lg`). |
| `control` | `'checkbox' \| 'switch' \| 'radio'` |  |  |

The group also takes the props of the group it renders: Base UI's RadioGroup for `radio`, CheckboxGroup for `checkbox`, and a `div` for `switch`. `columns` (1 to 4) lays the cards out from the `sm` breakpoint up.

#### Data attributes

The card and the group carry `data-yj-control` (`radio`, `checkbox` or `switch`), and the card's Field carries `data-orientation`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Card edge | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the border doubles in the accent when the control turns on |
| Icon tile | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | tints to the accent with the card |
| Hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the card takes the hover tint |

**Reduced motion:** The control drops its own motion (the radio's dot, the checkbox's draw, the switch's travel), and the card's tint still changes, so the choice reads the same.

The control inside keeps its own motion and sound: see [Radio Group](https://www.youj.dev/docs/components/radio-group), [Checkbox](https://www.youj.dev/docs/components/checkbox) and [Switch](https://www.youj.dev/docs/components/switch).

#### Reduced motion

The controls switch state without moving. The card's edge and the icon tile still change, so what is chosen stays clear.

### Accessibility

- Each card is a `label` around its control, so clicking anywhere on it operates the control, and the card's text names it.
- A radio group is one tab stop: `Tab` lands on the chosen card, the arrow keys move the choice and wrap, and disabled cards are skipped. Checkbox and switch cards are each a tab stop, toggled with `Space`.
- The card carries the focus ring for the control inside, which drops its own.
- Name the group with a `FieldLegend` in a `FieldSet`, or `aria-label` on the `ChoiceCardGroup`. The icon is decorative and hidden from assistive technology.

---

# Switch

> Turn a setting on or off and apply it immediately.

Source: https://www.youj.dev/docs/components/switch

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel, Switch } from '@youj/react'

const SETTINGS = [
  { id: 'previews', label: 'Preview deployments', description: 'Build every pull request on its own URL.', on: true },
  { id: 'protection', label: 'Deployment protection', description: 'Ask visitors to sign in before they see a preview.', on: true },
  { id: 'cache', label: 'Build cache', description: 'Reuse dependencies and outputs between builds.', on: true },
  { id: 'insights', label: 'Speed Insights', description: 'Collect Core Web Vitals from real visitors.', on: false },
]

export default function SwitchDemo() {
  const [state, setState] = useState(() => Object.fromEntries(SETTINGS.map((s) => [s.id, s.on])))

return (
    <FieldGroup className="w-full max-w-md gap-0 divide-y divide-line rounded-xl border border-line bg-surface">
      {SETTINGS.map((setting) => (
        <Field key={setting.id} orientation="horizontal" className="px-4 py-3.5">
          <FieldContent>
            <FieldLabel>{setting.label}</FieldLabel>
            <FieldDescription>{setting.description}</FieldDescription>
          </FieldContent>
          <Switch checked={state[setting.id]} onCheckedChange={(next) => setState((s) => ({ ...s, [setting.id]: next }))} />
        </Field>
      ))}
    </FieldGroup>
  )
}
```

A list of project settings, each with a label, a description and a switch.

### It applies immediately

```tsx
'use client'

import { useState } from 'react'
import { Badge, Field, FieldContent, FieldDescription, FieldLabel, Switch } from '@youj/react'

export default function SwitchImmediate() {
  const [maintenance, setMaintenance] = useState(false)

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-4 border-b border-line px-4 py-3">
        <div className="min-w-0">
          <p className="truncate text-ui font-medium text-fg">youj.io</p>
          <p className="text-ui-sm text-fg-muted">Production · 4f2a91c</p>
        </div>
        {/* The switch applies on its own, so the page reflects it at once: no Save button. */}
        <Badge variant={maintenance ? 'warning' : 'success'}>{maintenance ? 'Maintenance' : 'Live'}</Badge>
      </div>
      <Field orientation="horizontal" className="px-4 py-3.5">
        <FieldContent>
          <FieldLabel>Maintenance mode</FieldLabel>
          <FieldDescription>Serve a holding page to every visitor until you switch it off.</FieldDescription>
        </FieldContent>
        <Switch checked={maintenance} onCheckedChange={setMaintenance} />
      </Field>
    </div>
  )
}
```

A switch that applies its change as soon as it is flipped.

A switch promises that the change has already happened. Reflect it right away, in the same view, and don't pair it with a Save button. If the change can fail, show that too, and flip the switch back.

### Sizes and states

```tsx
'use client'

import { Field, FieldLabel, Switch } from '@youj/react'

export default function SwitchSizes() {
  return (
    <div className="grid w-full max-w-md grid-cols-1 gap-x-10 gap-y-5 sm:grid-cols-2">
      <Field orientation="horizontal">
        <Switch defaultChecked />
        <FieldLabel>Default</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch size="sm" defaultChecked />
        <FieldLabel>Small, for dense rows</FieldLabel>
      </Field>
      <Field orientation="horizontal" disabled>
        <Switch defaultChecked />
        <FieldLabel>Disabled</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch readOnly defaultChecked />
        <FieldLabel>Read-only</FieldLabel>
      </Field>
    </div>
  )
}
```

Switches in each size and state.

`size="sm"` fits dense rows and tables, and `size="lg"` suits touch-first and spacious settings. `disabled` on the `Field` dims the label with the switch. `readOnly` keeps the value but ignores presses.

### Liquid

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel, Switch } from '@youj/react'

const SETTINGS = [
  { id: 'focus', label: 'Focus mode', description: 'Hold notifications until you finish.', on: true },
  { id: 'power', label: 'Low power mode', description: 'Pause background sync and dim the screen.', on: false },
  { id: 'nearby', label: 'Share with nearby', description: 'Let people around you send you files.', on: true },
]

export default function SwitchLiquid() {
  const [state, setState] = useState(() => Object.fromEntries(SETTINGS.map((s) => [s.id, s.on])))

return (
    <FieldGroup className="w-full max-w-md gap-0 divide-y divide-line rounded-xl border border-line bg-surface">
      {SETTINGS.map((setting) => (
        <Field key={setting.id} orientation="horizontal" className="px-4 py-3.5">
          <FieldContent>
            <FieldLabel>{setting.label}</FieldLabel>
            <FieldDescription>{setting.description}</FieldDescription>
          </FieldContent>
          <Switch variant="liquid" checked={state[setting.id]} onCheckedChange={(next) => setState((s) => ({ ...s, [setting.id]: next }))} />
        </Field>
      ))}
    </FieldGroup>
  )
}
```

A settings list with liquid switches.

`variant="liquid"` draws the thumb as a glass droplet on a wider track. It stretches as it travels, overshoots its end and settles, and the accent pours into the track behind it. Everything else is the same switch: the role, the keyboard, the props and the Field wiring. Use it where the product has a softer, more playful look; keep one variant per screen.

### Liquid sizes

```tsx
'use client'

import { Field, FieldLabel, Switch } from '@youj/react'

export default function SwitchLiquidSizes() {
  return (
    <div className="grid w-full max-w-md grid-cols-1 gap-x-10 gap-y-5 sm:grid-cols-2">
      <Field orientation="horizontal">
        <Switch variant="liquid" size="sm" defaultChecked />
        <FieldLabel>Small</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch variant="liquid" defaultChecked />
        <FieldLabel>Default</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch variant="liquid" size="lg" defaultChecked />
        <FieldLabel>Large</FieldLabel>
      </Field>
      <Field orientation="horizontal" disabled>
        <Switch variant="liquid" defaultChecked />
        <FieldLabel>Disabled</FieldLabel>
      </Field>
    </div>
  )
}
```

Liquid switches in each size, and disabled.

The liquid track is wider than the default one at every size, to give the droplet room to stretch. The thumb catches a little of the accent in its lower edge as it crosses the fill, and its highlight stays at the top in both themes.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add switch
```

It brings `field`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Switch for settings that apply immediately, such as muting a channel or turning on previews. For a value saved with a form, use a [Checkbox](https://www.youj.dev/docs/components/checkbox). For named alternatives such as light and dark, use a [Toggle Group](https://www.youj.dev/docs/components/toggle-group) or [Radio Group](https://www.youj.dev/docs/components/radio-group).

```tsx
import { Field, FieldLabel, Switch } from '@youj/react'

export function AirplaneMode() {
  return (
    <Field orientation="horizontal">
      <Switch />
      <FieldLabel>Airplane mode</FieldLabel>
    </Field>
  )
}
```

In a settings row, put the label and its description in a `FieldContent` first and the switch last, so the label leads and the control lines up at the end of every row.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` |  |
| `variant` | `'default' \| 'liquid'` | `'default'` | `liquid` draws a glass droplet for a thumb that stretches as it travels, overshoots and settles, pouring the accent into the track behind it. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), toggling plays `toggleOn` or `toggleOff`. `false` keeps this one silent. |

Also takes the props of `SwitchPrimitive.Root.Props`.

| Data attribute | Values |
| --- | --- |
| `data-size` | `sm`, `default`, `lg` |
| `data-variant` | `default`, `liquid` |
| `data-checked`, `data-unchecked`, `data-disabled` | Base UI's state |

It also takes Base UI's `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `readOnly`, `required`, `name` and `value`. The `required` default comes from the surrounding `Field`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Thumb travel | `spring.snappy` | 0.2s, bounce 0 | one thumb width, mirrored under right-to-left |
| Track color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | off to on |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the thumb squeezes to 85% |

**Reduced motion:** The thumb jumps to its end and doesn't squeeze on press. The track still changes color.

The spring drives a single value from 0 to 1, and CSS turns it into the thumb's translate. A switch flipped back mid-flight retargets the spring from where the thumb is, so rapid toggling never jumps.

#### Liquid

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Droplet travel | `spring.settle` | 0.45s, bounce 0.3 | overshoots its end and settles |
| Stretch | `spring.settle` | 0.45s, bounce 0.3 | up to 30% wider and 18% flatter with the spring’s speed, squashed against the end while it overshoots |
| Fill | `spring.settle` | 0.45s, bounce 0.3 | the accent, clipped to the traveled part of the track, follows the same value |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the droplet swells to 110% |

**Reduced motion:** The plain switch's: the droplet jumps to its end, doesn't stretch or swell, and the fill shows at once.

The liquid switch springs on `settle`, the kit's one spring that overshoots, so the droplet lands with a small wobble. Its stretch is read from the spring's speed, so a rapid toggle that retargets mid-flight stretches it the right amount.

#### Reduced motion

The thumb moves to its end at once and the press doesn't squeeze it. The thumb's position and the track color still show the state. The liquid droplet does the same: no stretch, no swell, and the fill shows at once.

### Accessibility

- It's a `switch` role with `aria-checked`. `Space` toggles it.
- A `FieldLabel` in the same `Field` names it. Outside a `Field`, give it `aria-label`, or pair `Label htmlFor` with the switch's `id`.
- In both states the thumb clears 3:1 against the track, and the track clears 3:1 against the page. The liquid droplet is a near-white glass on the same off track and the accent fill. The thumb's side shows the state too, so it doesn't rest on color alone.
- The hit area extends past the track, and grows on touch screens.

---

# Slider

> Adjust a value or range along a track.

Source: https://www.youj.dev/docs/components/slider

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, Slider } from '@youj/react'

const usd = { style: 'currency', currency: 'USD', maximumFractionDigits: 0 } as const
const formatter = new Intl.NumberFormat('en-US', usd)

export default function SliderDemo() {
  const [limit, setLimit] = useState(400)

return (
    <Field className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <div className="flex items-baseline justify-between gap-4">
        <FieldLabel>Monthly spend limit</FieldLabel>
        <span className="font-mono text-ui text-fg tabular-nums">{formatter.format(limit)}</span>
      </div>
      {/* `format` makes assistive tech hear "$400", not "400". */}
      <Slider value={limit} onValueChange={(value) => setLimit(value as number)} min={0} max={2000} step={50} format={usd} locale="en-US" />
      <FieldDescription>We pause deployments at the limit and email the owners at 80%.</FieldDescription>
    </Field>
  )
}
```

A monthly spend limit Slider with its value read out in US dollars beside the label.

### Ranges

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, Slider } from '@youj/react'

export default function SliderRange() {
  const [range, setRange] = useState([120, 480])

return (
    <Field className="w-full max-w-sm">
      <div className="flex items-baseline justify-between gap-4">
        <FieldLabel>Response time</FieldLabel>
        <span className="font-mono text-ui text-fg tabular-nums">
          {range[0]}–{range[1]} ms
        </span>
      </div>
      {/* Two values make a range. Each thumb gets its own name. */}
      <Slider
        value={range}
        onValueChange={(value) => setRange(value as number[])}
        min={0}
        max={1000}
        step={10}
        minStepsBetweenValues={5}
        thumbLabels={['Fastest response', 'Slowest response']}
      />
      <FieldDescription>Show requests that took this long to answer.</FieldDescription>
    </Field>
  )
}
```

A slider with two thumbs.

Pass two values and the slider draws a range with two thumbs. Name each one with `thumbLabels`, and use `minStepsBetweenValues` to keep them apart.

### Liquid

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, Slider } from '@youj/react'

export default function SliderLiquid() {
  const [level, setLevel] = useState(64)

return (
    <Field className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <div className="flex items-baseline justify-between gap-4">
        <FieldLabel>Tank level</FieldLabel>
        <span className="font-mono text-ui text-fg tabular-nums">{level}%</span>
      </div>
      <Slider variant="liquid" value={level} onValueChange={(value) => setLevel(value as number)} format={{ style: 'unit', unit: 'percent' }} />
      <FieldDescription>Refill starts when the tank drops below 20%.</FieldDescription>
    </Field>
  )
}
```

A tank level Slider whose fill is a liquid.

`variant="liquid"` draws the track as a tube, the thumb as a glass droplet and the fill as a liquid. Drag fast and the surface leans back behind the thumb; stop and it sloshes forward, then settles. Arrow keys make small waves. Everything else is the same slider: the role, the keyboard, the props and the Field wiring. Use it where the value is a level or an amount, like a tank, a budget or a volume, and keep one variant per screen.

### Ticks

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, Slider } from '@youj/react'

export default function SliderTicks() {
  const [seats, setSeats] = useState(14)

return (
    <Field className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <div className="flex items-baseline justify-between gap-4">
        <FieldLabel>Seats</FieldLabel>
        <span className="font-mono text-ui text-fg tabular-nums">{seats} seats</span>
      </div>
      <Slider variant="ticks" tone="chart-4" value={seats} onValueChange={(value) => setSeats(value as number)} min={1} max={40} />
      <FieldDescription>Each seat is $9 a month, billed with the plan.</FieldDescription>
    </Field>
  )
}
```

A seat count read off a ruler.

`variant="ticks"` swaps the rail for a ruler: fine ticks across the thumb's travel, a taller one every fifth, lit in `tone` up to a slim fader cap and quiet past it. Use it for a value people read off a scale, like the lines of an estimate builder. There is a tick per step while that's at most 61 (so 1 to 40 seats shows 40), else 41; `ticks` sets the count. A range lights the ticks between its two thumbs. It is horizontal only.

### Without a visible label

```tsx
'use client'

import { useState } from 'react'
import { MonitorIcon, SmartphoneIcon } from '@youj/icons'
import { Slider } from '@youj/react'

export default function SliderWidth() {
  const [width, setWidth] = useState(768)

return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-lg border border-line bg-surface px-3 py-2">
      <SmartphoneIcon size={16} className="text-fg-muted" />
      {/* No visible label here, so aria-label names the thumb. */}
      <Slider aria-label="Preview width" value={width} onValueChange={(value) => setWidth(value as number)} min={320} max={1440} step={8} />
      <MonitorIcon size={16} className="text-fg-muted" />
      <span className="w-16 shrink-0 text-end font-mono text-ui-sm text-fg tabular-nums">{width} px</span>
    </div>
  )
}
```

A slider named by `aria-label`.

When the slider sits in a toolbar with no label of its own, `aria-label` names the thumb. Base UI would otherwise name a thumb only from a `Field` or slider label, so Youj's `Slider` passes it through to the thumb for you.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add slider
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Slider to adjust a value within a range, such as a threshold or zoom level. Show the current value beside it. Add an [Input](https://www.youj.dev/docs/components/input), or use one instead, when people need to enter an exact number.

Inside a `Field`, the `FieldLabel` names the thumb.

```tsx
import { Field, FieldLabel, Slider } from '@youj/react'

export function Volume() {
  return (
    <Field>
      <FieldLabel>Volume</FieldLabel>
      <Slider defaultValue={60} />
    </Field>
  )
}
```

`min` and `max` default to 0 and 100. `step` sets the increment, and `format` takes `Intl.NumberFormat` options, so the value is announced as "$400" rather than "400". Use `onValueChange` for what follows the drag, like a readout, and Base UI's `onValueCommitted` for work that should wait until the thumb is released, like a save.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Names the thumb. Base UI names a thumb from a Field/Slider label, never from the root's aria-label, so it is forwarded to the thumb here. |
| `thumbLabels` | `string[]` |  | One name per thumb for a range, e.g. ['Minimum price', 'Maximum price']. |
| `getAriaValueText` | `(formattedValue: string, value: number, index: number) => string` |  | What a screen reader says for a thumb's value when `format` can't say it, e.g. with a unit. |
| `variant` | `'default' \| 'liquid' \| 'ticks'` | `'default'` | `liquid` fills a tube with a liquid whose surface sloshes as the value changes, leaning with the drag's speed and settling on a spring. `ticks` reads the value off a ruler of fine ticks, lit up to the thumb (horizontal only). |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The fill's color in the default and `ticks` variants: the accent, a chart color, a status or neutral. |
| `ticks` | `number` |  | With `variant="ticks"`: how many ticks the ruler has, ends included. Default: one per step while that's at most 61, else 41. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the liquid slider plays `tick` as its value changes. `false` keeps this one silent. |

Also takes the props of `SliderPrimitive.Root.Props`.

| Data attribute | Values |
| --- | --- |
| `data-variant` | `default`, `liquid`, `ticks` |
| `data-tone` | the `tone` |
| `data-orientation`, `data-dragging`, `data-disabled` | Base UI's state |

It also takes Base UI's `value`, `defaultValue`, `onValueChange`, `onValueCommitted`, `min`, `max`, `step`, `largeStep`, `minStepsBetweenValues`, `format`, `locale`, `orientation`, `disabled` and `name`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Thumb |  | no easing | tracks the pointer 1:1, and keyboard steps land at once |
| Halo | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | grows behind the thumb on hover, focus and drag |

**Reduced motion:** The halo fades in without growing. The thumb follows the pointer and the keyboard exactly as before.

A slider is direct manipulation, so the thumb never eases toward the pointer. The motion is in the halo, a disc that grows behind the thumb on transform and opacity.

#### Liquid

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lean | `spring.snappy` | 0.2s, bounce 0 | the surface tilts back from the thumb with the value’s speed |
| Slosh | `spring.settle` | 0.45s, bounce 0.3 | once the value rests, the surface swings past level and settles |
| Swell | `spring.settle` | 0.45s, bounce 0.3 | the middle of the surface bulges with the speed of the lean, a second wave on the first |

**Reduced motion:** The surface stays level. The thumb and the fill follow the value exactly as on the plain slider.

The thumb and the length of the fill stay direct; only the liquid's surface moves. With sound on, the liquid slider plays `tick` as its value changes (the sound pack keeps a fast drag from repeating it), and `sound={false}` keeps one silent.

#### Ticks

The lit ticks follow the value with no easing, like the thumb; only the halo moves.

#### Reduced motion

The halo appears without scaling. Everything else is already direct: the thumb moves with the pointer, and the value changes as it moves. The liquid's surface stays level.

### Accessibility

- Each thumb is a `slider` with `aria-valuenow`, and `aria-valuetext` formatted with `format`.
- The arrow keys step. `Page Up`, `Page Down` and `Shift` with an arrow take large steps, and `Home` and `End` jump to the ends.
- Name it with a `FieldLabel`, with `aria-label` for a single thumb, or with `thumbLabels` for a range.
- The liquid and the ruler's ticks are decorative and hidden from assistive tech; the thumb's value says the same thing.
- The thumb has a 32px hit area, and 40px on touch screens. Under right-to-left, the range fills from the right and the arrow keys follow the reading direction.

---

# Gradient Slider

> Set a value on a scale that runs from one feel to another, with named zones along it.

Source: https://www.youj.dev/docs/components/gradient-slider

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { GradientSlider } from '@youj/react'

const ZONES = [{ label: 'Literal', to: 0.4 }, { label: 'Balanced', to: 0.95 }, { label: 'Exploratory' }]

export default function GradientSliderDemo() {
  const [creativity, setCreativity] = useState(0.65)
  return (
    <div className="w-full max-w-md rounded-2xl border border-line bg-surface p-6">
      <GradientSlider label="Creativity" value={creativity} onValueChange={setCreativity} min={0} max={1.5} step={0.05} ticks={15} zones={ZONES} />
    </div>
  )
}
```

A Creativity slider with Literal, Balanced and Exploratory zones under its track.

### Colors

```tsx
'use client'

import { GradientSlider } from '@youj/react'

export default function GradientSliderTones() {
  return (
    <div className="grid w-full max-w-md gap-8 rounded-2xl border border-line bg-surface p-6">
      <GradientSlider label="Glow" tone="accent" defaultValue={62} zones={[{ label: 'Subtle', to: 33 }, { label: 'Present', to: 66 }, { label: 'Vivid' }]} />
      {/* Status colours only where the far end really is a risk. */}
      <GradientSlider
        label="Auto-merge threshold"
        tone="status"
        defaultValue={0.2}
        min={0}
        max={1}
        step={0.01}
        format={{ style: 'percent' }}
        zones={[{ label: 'Reviewed', to: 0.3 }, { label: 'Sampled', to: 0.7 }, { label: 'Unchecked' }]}
      />
    </div>
  )
}
```

The same slider in each tone.

The gradient comes from your theme, so it changes with it. Pick it with `tone`:

- `spectrum`, the default, uses the theme's chart colors from cool to warm. It suggests nothing good or bad, so it suits a preference such as creativity. In a theme without chart colors, it runs from gray to the accent.
- `accent` runs the accent from faint to full.
- `status` runs from success through warning to danger. Use it only when the far end really is a risk, such as how much work goes unchecked. On a scale like creativity, a red end would tell people that high values are wrong.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add gradient-slider
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-gradient-slider`, `youj-presets`, `youj-ui-core` with it.

Use a gradient slider when a value is a feel rather than a number: how freely a model writes, how warm a light is, how strong an effect is. The track is a color gradient, lit up to the thumb. The thumb shows the exact value, and named zones under the track say which stretch you're in, such as "Literal", "Balanced" or "Exploratory".

```tsx
import { GradientSlider } from '@youj/react'

<GradientSlider
  label="Creativity"
  value={creativity}
  onValueChange={setCreativity}
  min={0}
  max={1.5}
  step={0.05}
  zones={[{ label: 'Literal', to: 0.4 }, { label: 'Balanced', to: 0.95 }, { label: 'Exploratory' }]}
/>
```

Each zone runs up to its `to` value, and the last one runs to `max`. `ticks` sets how many divisions the ruler under the track shows, and zone edges get longer ticks. `format` takes `Intl.NumberFormat` options for the value. Use `onValueCommitted` for work that should wait until the thumb is let go, like a save.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `style` | `CSSProperties` |  |  |
| `value` | `number` |  |  |
| `defaultValue` | `number` |  |  |
| `onValueChange` | `(value: number) => void` |  |  |
| `onValueCommitted` | `(value: number) => void` |  | Fires when a drag or key press ends: the moment to save. |
| `label` | `ReactNode` |  | A visible name over the track (an eyebrow in Bezel). It also names the thumb. |
| `aria-label` | `string` |  | Names the thumb when there's no visible `label`. |
| `zones` | `GradientSliderZone[]` | `[]` | The named stretches of the range, in order: [{ label: 'Literal', to: 0.4 }, …]. The first and last read as its two ends. |
| `tone` | `'spectrum' \| 'accent' \| 'status'` | `'spectrum'` | The gradient, from the theme’s tokens. `spectrum` (default): the chart palette, cool to warm, with no judgment in it. `accent`: the accent from faint to full. `status`: success, warning, danger, only for a scale whose far end really is a risk. |
| `ticks` | `number` | `10` | How many divisions the ruler shows. Zone edges and the ends are major ticks. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the value in the thumb and as spoken. Default: two decimals below 10, whole numbers above. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), crossing into another zone plays `tick`. `false` keeps it quiet. |

Also takes the props of `SliderPrimitive.Root.Props`.

It's built on Base UI's slider, and also takes `min`, `max`, `step`, `largeStep`, `disabled`, `name` and `locale`.

### Styling

Parts: `gradient-slider` (with `data-tone`), `gradient-slider-label`, `gradient-slider-control`, `gradient-slider-track`, `gradient-slider-rail`, `gradient-slider-fill`, `gradient-slider-thumb`, `gradient-slider-value`, `gradient-slider-ruler`, `gradient-slider-tick` (with `data-major`), `gradient-slider-zones` and `gradient-slider-zone` (with `data-active`). In Bezel the label and the zone names are small mono capitals.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Thumb |  | no easing | follows the pointer exactly, and keyboard steps land at once |
| Hold or focus | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the glass thumb swells slightly |
| New zone | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | its name lights up as you cross into it |

**Reduced motion:** The thumb doesn't swell, and colors change at once. The thumb still follows the pointer and the keys.

### Accessibility

- `label` names the thumb. Without one, use `aria-label`.
- The value is spoken with its zone ("0.65, Balanced"). The wording comes from the labels' `gradientSliderValue`, which the language packs translate.
- The arrow keys step. Page Up, Page Down and Shift with an arrow take large steps, and Home and End jump to the ends.
- In a right-to-left page the scale runs from the right, and the arrow keys follow.
- With sound on, crossing into another zone plays `tick`. `sound={false}` turns it off.

---

# Histogram Range

> Choose a range while seeing the distribution of values it filters.

Source: https://www.youj.dev/docs/components/histogram-range

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { HistogramRange } from '@youj/react'

/** Uploads per size bin, 0 to 64 MB in 40 bins: most files small, a long tail of big ones. */
const UPLOADS = Array.from({ length: 40 }, (_, i) => {
  const x = (i + 0.5) * (64 / 40)
  const mu = Math.log(9) + 0.62 ** 2
  return Math.round((Math.exp(-((Math.log(x) - mu) ** 2) / (2 * 0.62 ** 2)) / (x * 0.62 * Math.sqrt(2 * Math.PI))) * 48_600 * (64 / 40))
})

export default function HistogramRangeDemo() {
  const [range, setRange] = useState<[number, number]>([4.8, 38])

return (
    <div className="w-full max-w-lg">
      <HistogramRange
        label="File size"
        bins={UPLOADS}
        min={0}
        max={64}
        step={0.1}
        value={range}
        onValueChange={setRange}
        format={(v) => `${v.toFixed(1)} MB`}
        formatTick={(v) => (v === 0 ? '0' : `${v} MB`)}
        ticks={[0, 16, 32, 48, 64]}
      />
    </div>
  )
}
```

A file-size filter: a range from 0 to 64 MB drawn over a histogram of uploads.

### New data

```tsx
'use client'

import { useState } from 'react'
import { HistogramRange, SegmentedControl, SegmentedControlItem } from '@youj/react'

/** Nightly prices, as raw values: HistogramRange counts them into bins. */
function prices(seed: number, median: number) {
  let s = seed
  const random = () => ((s = (s * 16807) % 2147483647) - 1) / 2147483646
  return Array.from({ length: 1500 }, () => Math.round(median * Math.exp(0.5 * (random() + random() + random() + random() - 2) * Math.sqrt(3))))
}

const CITIES = { Lisbon: prices(7, 110), Paris: prices(11, 190), Kyoto: prices(3, 150) }
const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })

export default function HistogramRangeData() {
  const [city, setCity] = useState<keyof typeof CITIES>('Lisbon')

return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <SegmentedControl value={city} onValueChange={(value) => setCity(value as keyof typeof CITIES)} aria-label="City">
        {Object.keys(CITIES).map((name) => (
          <SegmentedControlItem key={name} value={name}>
            {name}
          </SegmentedControlItem>
        ))}
      </SegmentedControl>
      {/* New data glides the bars to their new heights; the range stays where you left it. */}
      <HistogramRange
        label="Price per night"
        data={CITIES[city]}
        binCount={36}
        min={0}
        max={450}
        step={5}
        defaultValue={[80, 260]}
        format={usd.format}
        ticks={[0, 150, 300, 450]}
      />
    </div>
  )
}
```

The bars gliding to new heights as the data changes.

When the data changes, the bars glide to their new heights; the range stays where it was.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add histogram-range
```

It brings `slider`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-histogram-range`, `youj-presets`, `youj-ui-core` with it.

Use a histogram range when the shape of the data should guide the cut: file sizes, prices, response times, scores. People see where the values bunch up before they choose, and the bars inside the range show what they're keeping. For a range on its own, a [Slider](https://www.youj.dev/docs/components/slider) with two values is enough.

```tsx
import { useState } from 'react'
import { HistogramRange } from '@youj/react'

export function SizeFilter({ bins }: { bins: number[] }) {
  const [range, setRange] = useState<[number, number]>([4.8, 38])
  return (
    <HistogramRange
      label="File size"
      bins={bins}
      min={0}
      max={64}
      step={0.1}
      value={range}
      onValueChange={setRange}
      format={(v) => `${v.toFixed(1)} MB`}
    />
  )
}
```

Pass counts you've already binned as `bins`, evenly spaced from `min` to `max`, or raw values as `data` and it counts them into `binCount` bins (40 by default); values outside `min` and `max` are left out. It's controlled with `value` and `onValueChange`, or uncontrolled with `defaultValue`; `onValueCommitted` fires once a drag or key press ends.

`format` turns a value into text: the readout above the plot, what a screen reader says for each thumb, and the axis. `formatTick` formats the axis on its own (say "0" rather than "0.0 MB"), and `ticks` picks the values it marks.

The accent stays on the track between the thumbs and on the readout, and the bars in range are a stronger neutral. `tone="accent"` puts the accent on those bars too. Each thumb is drawn as a caliper's jaw: an upright tab on the track with a hairline guide that rises through the plot, so you read each end of the cut against the bars it falls in.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `readonly number[]` |  | Raw values, counted into `binCount` even bins from `min` to `max`. Values outside are left out. |
| `bins` | `readonly number[]` |  | Counts per bin, evenly spaced from `min` to `max`. Used instead of `data`. |
| `binCount` | `number` | `40` | How many bins `data` is counted into. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `value` | `Range` |  |  |
| `defaultValue` | `Range` | `[min, max]` |  |
| `onValueChange` | `(value: Range) => void` |  |  |
| `onValueCommitted` | `(value: Range) => void` |  | Called once a drag or key press ends, with the final range. |
| `label` | `string` |  | The visible name over the plot ("Duration"). It names the group, and the thumbs as its minimum and maximum. |
| `format` | `(value: number) => string` |  | Formats a value for the readout, the thumbs' spoken values and, unless `formatTick` is set, the axis. Default: the locale's number format. |
| `formatTick` | `(value: number) => string` | ``format`` | Formats an axis tick. |
| `ticks` | `readonly number[]` |  | The values the axis marks. Default: four, evenly spaced from `min` to `max`. |
| `tone` | `'neutral' \| 'accent'` | `'neutral'` | The bars inside the range: a stronger neutral, or the accent. |
| `thumbLabels` | `[string, string]` |  | Names for the two thumbs. Default: the label's minimum and maximum. |
| `name` | `string` |  | Also submits both ends with a native form, under this name. |
| `disabled` | `boolean` |  |  |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Thumbs and range |  | no easing | track the pointer 1:1; the bars in range are a copy clipped to it, so a bar under a thumb is cut at its center |
| Data changes | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | each bar’s height glides (a clip-path, so corners stay crisp) in a quick wave from the first bin |
| First paint | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the bars rise from the baseline the same way |
| Thumb halo | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the Slider’s halo on hover, focus and drag |

**Reduced motion:** The bars take their heights in one frame, on first paint and on every change. The thumbs and the range were direct already.

#### Reduced motion

Only the bars move, so only they change: they take their new heights at once. Dragging was never animated.

### Accessibility

- The component is a `group` named by `label`. Its thumbs are the [Slider](https://www.youj.dev/docs/components/slider)'s: each is a `slider` named as the label's minimum and maximum ("Minimum file size"), or by `thumbLabels`, and speaks its value through `format`.
- The arrow keys step, Page Up, Page Down and Shift with an arrow take large steps, and Home and End jump to the ends. The whole plot is the hit area: a press anywhere moves the nearest thumb.
- The bars and the axis are hidden from assistive tech. The readout is spoken through a polite live region half a second after the range stops changing, not on every step.
- Under right-to-left, the minimum sits on the right, and the bars, the accent and the axis mirror with the thumbs.

---

# Dial

> Adjust a value on a circular scale, with a measured value and setpoints for reference.

Source: https://www.youj.dev/docs/components/dial

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Dial, SegmentedControl, SegmentedControlItem } from '@youj/react'

type Mode = 'heat' | 'cool'

export default function DialDemo() {
  const [mode, setMode] = useState<Mode>('heat')
  const [target, setTarget] = useState(21.5)
  const room = mode === 'heat' ? 19.8 : 25.4
  return (
    <div className="flex w-full max-w-72 flex-col items-center gap-5">
      <SegmentedControl aria-label="Mode" value={mode} onValueChange={(v) => (setMode(v as Mode), setTarget(v === 'heat' ? 21.5 : 23))} className="w-full">
        <SegmentedControlItem value="heat" className="flex-1">
          Heat
        </SegmentedControlItem>
        <SegmentedControlItem value="cool" className="flex-1">
          Cool
        </SegmentedControlItem>
      </SegmentedControl>
      <Dial
        label="Target temperature"
        caption={mode === 'heat' ? 'Heating to' : 'Cooling to'}
        value={target}
        onValueChange={setTarget}
        min={12}
        max={28}
        step={0.5}
        current={room}
        tone={mode === 'heat' ? 'warm' : 'cool'}
        marks={[
          { value: 17, label: 'Away' },
          { value: 18, label: 'Night' },
          { value: 21, label: 'Morning' },
        ]}
        format={{ style: 'unit', unit: 'celsius', minimumFractionDigits: 1, maximumFractionDigits: 1 }}
      />
    </div>
  )
}
```

A thermostat dial with a Heat and Cool switch, a target value and the measured room temperature.

### Ticks

```tsx
'use client'

import { useState } from 'react'
import { Dial } from '@youj/react'

export default function DialTicks() {
  const [humidity, setHumidity] = useState(42)
  return (
    <div className="w-full max-w-64">
      <Dial
        variant="ticks"
        label="Humidity"
        value={humidity}
        onValueChange={setHumidity}
        format={{ style: 'unit', unit: 'percent' }}
        bands={[
          { from: 0, tone: 'warm' },
          { from: 30, tone: 'success' },
          { from: 60, tone: 'chart-5' },
        ]}
      />
    </div>
  )
}
```

A humidity control whose ticks change color as the air goes from dry to comfortable to damp.

`variant="ticks"` draws the arc as a ring of fine radial ticks, with no band or knob. The ticks from the start up to the value light in the tone and reach outward, longest at the value; the tick at the edge lights partway and the next few warm up a little, as Progress's ticks do. `ticks` sets how many there are (55 by default). `bands` change the tone by value: list them in ascending order, and the last band whose `from` the value has reached sets the tone. Dragging, the keys, `current`, `marks` and the figure work as on the default dial.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dial
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-dial`, `youj-presets`, `youj-ui-core` with it.

Use a dial for a bounded value people turn: a thermostat, a volume, a fan speed, a brightness. The arc runs three quarters of the way round, from the lower left to the lower right, ticked at every step, with the value as an ink knob on the band and large in mono in the middle. Give it a measured value and the stretch between the two lights in its tone, heating up to the target or cooling down to it. For a value along a line, use a [Slider](https://www.youj.dev/docs/components/slider); to show a score that isn't set by hand, a [Gauge](https://www.youj.dev/docs/components/gauge). For a window of the day that may run past midnight, such as a sleep schedule, use an [Hours Dial](https://www.youj.dev/docs/components/hours-dial).

```tsx
import { Dial } from '@youj/react'

<Dial
  label="Target temperature"
  caption="Heating to"
  value={target}
  onValueChange={setTarget}
  min={12}
  max={28}
  step={0.5}
  current={19.8}
  tone="warm"
  marks={[{ value: 17, label: 'Night' }, { value: 21, label: 'Morning' }]}
  format={{ style: 'unit', unit: 'celsius', maximumFractionDigits: 1 }}
/>
```

`min`, `max` and `step` bound the value, which snaps to the step; `largeStep` (ten steps by default) is what Page Up and Down take. `current` shows a measured value: a marker inside the band, "Now 19.8°C" under the figure, and the stretch between it and the value lit. `tone` colors that stretch: `warm` and `cool` suit heating and cooling, and the accent, a chart color or neutral suit anything else. `marks` put small rings on the ruler for setpoints, such as a schedule's. `format` sets how the figures read, and `caption` puts a mono capital over the figure. It's uncontrolled with `defaultValue`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  |  |
| `defaultValue` | `number` |  |  |
| `onValueChange` | `(value: number) => void` |  |  |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `largeStep` | `number` | `10` | Per Page Up/Down and Shift+arrow. |
| `current` | `number` |  | A measured value to show against the setting: a room's temperature. |
| `marks` | `DialMark[]` | `[]` | Setpoints on the ruler. |
| `tone` | `'accent' \| 'warm' \| 'cool' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The lit stretch's color. `warm` and `cool` suit heating and cooling; `success`, `warning` and `danger` suit `bands`. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the figures: { style: 'unit', unit: 'celsius' }. Default: whole numbers. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Dial". |
| `caption` | `ReactNode` |  | A mono capital over the figure: "Heating to". |
| `sound` | `boolean` | `true` | Plays the tick cue at every step. |
| `variant` | `'default' \| 'ticks'` | `'default'` | `ticks` draws the arc as a ring of radial ticks that light up to the value, with no band or knob. |
| `ticks` | `number` | `55` | How many ticks the `ticks` variant draws. |
| `bands` | `DialBand[]` | `[]` | Tones by value, in ascending order: the last band whose `from` the value has reached sets the tone, over `tone`. |

Also takes the props of `SliderPrimitive.Root.Props<number>`.

### Styling

Parts: `dial` (with `data-variant`, `data-tone` and `data-dragging`; `data-tone` is the band's tone when `bands` set one), `dial-face`, `dial-arc`, `dial-ruler`, `dial-track`, `dial-range`, `dial-mark`, `dial-current`, `dial-knob`, `dial-thumb`, `dial-center`, `dial-label`, `dial-value` and `dial-now`. The ticks variant draws `dial-ticks`, a `dial-tick` each, and `dial-focus` in place of the ruler, band and knob.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Keyboard or click | `spring.snappy` | 0.2s, bounce 0 | the knob and the lit stretch glide to the new value together, retargeting mid-flight |
| Drag | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the knob follows the pointer 1:1, snapping to the step |
| Hover, focus or drag | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | a halo in the tone comes up round the knob |
| Ticks: keyboard or click | `spring.snappy` | 0.2s, bounce 0 | the lit ticks follow the value on the same spring, reaching outward as the edge passes |
| Ticks: band change | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the lit ticks cross-fade to the new tone |

**Reduced motion:** Every change jumps.

#### Reduced motion

The knob and the lit stretch, or the lit ticks, jump to each new value.

### Accessibility

- It's a Base UI slider under the arc: a native range input named by `label` (default: the labels' "Dial"), with the measured value spoken beside the setting ("21.5 °C, now 19.8 °C"). The marks are its description ("Night: 17 °C; Morning: 21 °C").
- Arrows step, Page Up and Down take large steps, and Home and End jump to the ends. A pointer anywhere on the band drags the knob round and focuses the dial, so the keys carry on from there.
- A dial turns clockwise in every script, so the arc and its keys keep their direction under RTL: right and up raise the value. The text in the center follows the page.
- Every step plays the tick cue, like a detent, behind `sound` (on by default).
- Its words come from the labels (`dial`, `dialNow`, `dialValueNow`, `dialMark`), translated by the language packs.

---

# Select

> Choose one option from a popup list.

Source: https://www.youj.dev/docs/components/select

## Examples

### Demo

```tsx
'use client'

import {
  Field,
  FieldDescription,
  FieldLabel,
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from '@youj/react'

const REGIONS = {
  Americas: [
    { value: 'iad1', label: 'Washington, D.C.' },
    { value: 'sfo1', label: 'San Francisco' },
    { value: 'gru1', label: 'São Paulo' },
  ],
  Europe: [
    { value: 'fra1', label: 'Frankfurt' },
    { value: 'cdg1', label: 'Paris' },
    { value: 'arn1', label: 'Stockholm' },
  ],
  'Asia Pacific': [
    { value: 'hnd1', label: 'Tokyo' },
    { value: 'sin1', label: 'Singapore' },
    { value: 'syd1', label: 'Sydney' },
  ],
}

// Lets the trigger show "Frankfurt" for fra1 before the popup has ever opened.
const items = Object.fromEntries(Object.values(REGIONS).flat().map((region) => [region.value, region.label]))

export default function SelectDemo() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Function region</FieldLabel>
      <Select items={items} defaultValue="fra1" name="region">
        <SelectTrigger className="w-full">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {Object.entries(REGIONS).map(([group, regions], index) => (
            <SelectGroup key={group}>
              {index > 0 && <SelectSeparator />}
              <SelectLabel>{group}</SelectLabel>
              {regions.map((region) => (
                <SelectItem key={region.value} value={region.value}>
                  {/* The space keeps the option's name "Frankfurt fra1", not "Frankfurtfra1". */}
                  {region.label}{' '}
                  <span className="ms-auto font-mono text-ui-xs text-fg-muted">{region.value}</span>
                </SelectItem>
              ))}
            </SelectGroup>
          ))}
        </SelectContent>
      </Select>
      <FieldDescription>Closest to your database. Changing it redeploys.</FieldDescription>
    </Field>
  )
}
```

A function region Select with regions grouped by continent.

`SelectGroup` with a `SelectLabel` titles a run of options, and `SelectSeparator` draws a hairline between groups. Items can hold more than text: in the demo, each region carries its code in muted type. Keep a space between the label and the extra text, so the option's accessible name reads "Frankfurt fra1".

### States

```tsx
'use client'

import { Field, FieldError, FieldLabel, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@youj/react'

const ROLES = [
  { value: 'owner', label: 'Owner' },
  { value: 'admin', label: 'Admin' },
  { value: 'member', label: 'Member' },
  { value: 'viewer', label: 'Viewer' },
  { value: 'billing', label: 'Billing (Enterprise)', disabled: true },
]

function RoleOptions() {
  return ROLES.map((role) => (
    <SelectItem key={role.value} value={role.value} disabled={role.disabled}>
      {role.label}
    </SelectItem>
  ))
}

export default function SelectStates() {
  return (
    <div className="grid w-full max-w-xl gap-x-6 gap-y-5 sm:grid-cols-2">
      <Field>
        <FieldLabel>Placeholder</FieldLabel>
        <Select items={ROLES}>
          <SelectTrigger className="w-full">
            <SelectValue placeholder="Choose a role" />
          </SelectTrigger>
          <SelectContent>
            <RoleOptions />
          </SelectContent>
        </Select>
      </Field>
      <Field>
        <FieldLabel>Small, as a dropdown</FieldLabel>
        {/* alignItemWithTrigger={false} opens below the trigger instead of over it. */}
        <Select items={ROLES} defaultValue="member">
          <SelectTrigger size="sm" className="w-full">
            <SelectValue />
          </SelectTrigger>
          <SelectContent alignItemWithTrigger={false}>
            <RoleOptions />
          </SelectContent>
        </Select>
      </Field>
      <Field disabled>
        <FieldLabel>Disabled</FieldLabel>
        <Select items={ROLES} defaultValue="owner">
          <SelectTrigger className="w-full">
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            <RoleOptions />
          </SelectContent>
        </Select>
      </Field>
      <Field invalid>
        <FieldLabel>Invalid</FieldLabel>
        <Select items={ROLES}>
          <SelectTrigger className="w-full">
            <SelectValue placeholder="Choose a role" />
          </SelectTrigger>
          <SelectContent>
            <RoleOptions />
          </SelectContent>
        </Select>
        <FieldError>Pick a role before you send the invite.</FieldError>
      </Field>
    </div>
  )
}
```

A placeholder, sizes and states.

`SelectValue` takes a `placeholder` for when nothing is chosen. `size="sm"` fits toolbars and dense forms. By default the popup opens over the trigger with the chosen option lined up on it. Pass `alignItemWithTrigger={false}` to open it below the trigger, like a menu. `disabled` and `invalid` go on the `Field`, and a `FieldError` explains what's wrong.

### Multiple values

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@youj/react'

const EVENTS = [
  { value: 'deploy-failed', label: 'Failed deployments' },
  { value: 'deploy-promoted', label: 'Production promotions' },
  { value: 'domain-renewal', label: 'Domain renewals' },
  { value: 'usage-alert', label: 'Usage alerts' },
  { value: 'invoice', label: 'Invoices' },
  { value: 'member-joined', label: 'New teammates' },
]

// Two labels fit the trigger. Past that, name the first and count the rest.
function summarize(values: string[]) {
  const labels = EVENTS.filter((event) => values.includes(event.value)).map((event) => event.label)
  if (labels.length === 0) return 'Choose events'
  if (labels.length <= 2) return labels.join(', ')
  return `${labels[0]} and ${labels.length - 1} more`
}

export default function SelectMultiple() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Email me about</FieldLabel>
      <Select items={EVENTS} multiple defaultValue={['deploy-failed', 'usage-alert']} name="notifications">
        <SelectTrigger className="w-full">
          <SelectValue>{(values: string[]) => summarize(values)}</SelectValue>
        </SelectTrigger>
        {/* Options toggle and the popup stays open, so it opens below the trigger rather than over it. */}
        <SelectContent alignItemWithTrigger={false}>
          {EVENTS.map((event) => (
            <SelectItem key={event.value} value={event.value}>
              {event.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
      <FieldDescription>Sent to ana@youj.dev. Failed deployments also post to Slack.</FieldDescription>
    </Field>
  )
}
```

A select that takes several values.

With `multiple`, the value is an array: each option toggles, and the popup stays open until you close it. The trigger lists the chosen labels, separated by commas. Give `SelectValue` a function of the value to write a shorter summary, like "Failed deployments and 2 more".

### Soft

```tsx
'use client'

import { Card, CardContent, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@youj/react'

const MODELS = [
  { value: 'sonnet', label: 'Sonnet' },
  { value: 'opus', label: 'Opus' },
  { value: 'haiku', label: 'Haiku' },
]

export default function SelectSoft() {
  return (
    <Card className="w-full max-w-xs">
      <CardContent>
        <Select items={MODELS} defaultValue="sonnet">
          <SelectTrigger variant="soft" aria-label="Model" className="w-full">
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            {MODELS.map((m) => (
              <SelectItem key={m.value} value={m.value}>
                {m.label}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      </CardContent>
    </Card>
  )
}
```

A borderless picker inside a card.

`variant="soft"` drops the edge and fills the trigger with the theme's quiet band, with the same corner and height as any field, a hover step and the usual focus ring. Use it for a picker that sits inside a card or panel (a model, category or sort picker), where the card already frames it. The fill is a little under 3:1 against the card, so the chevron and the value identify the control rather than an edge: keep the default outlined field where a select has to read on its own, such as in a form. `ghost` goes further and has no fill until hover.

### Dense rows

```tsx
'use client'

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@youj/react'

const STATUSES = [
  { value: 'todo', label: 'To do' },
  { value: 'doing', label: 'In progress' },
  { value: 'done', label: 'Done' },
]

const ISSUES = [
  { id: 'ENG-188', title: 'Fix login redirect loop', status: 'doing' },
  { id: 'ENG-192', title: 'Keyboard shortcuts cheat sheet', status: 'todo' },
  { id: 'ENG-163', title: 'Onboarding checklist', status: 'done' },
]

export default function SelectDense() {
  return (
    <ul className="flex w-full max-w-md flex-col divide-y divide-line-subtle">
      {ISSUES.map((issue) => (
        <li key={issue.id} className="flex items-center gap-3 py-1.5">
          <span className="font-mono text-ui-sm text-fg-muted">{issue.id}</span>
          <span className="min-w-0 flex-1 truncate text-ui">{issue.title}</span>
          <Select items={STATUSES} defaultValue={issue.status}>
            <SelectTrigger variant="ghost" size="sm" hideIcon aria-label={`Status of ${issue.id}`}>
              <SelectValue />
            </SelectTrigger>
            <SelectContent alignItemWithTrigger={false} align="end">
              {STATUSES.map((s) => (
                <SelectItem key={s.value} value={s.value}>
                  {s.label}
                </SelectItem>
              ))}
            </SelectContent>
          </Select>
        </li>
      ))}
    </ul>
  )
}
```

A status picker on each row of a list, with no chevron.

`hideIcon` leaves out the trigger's chevron, for a row of selects where the value alone says it opens (an issue's status, a table cell). With `variant="ghost"` and `size="sm"` the trigger is just its value until hover. It stays a combobox, named by its `aria-label` and reporting `aria-expanded`, so nothing changes for the keyboard or a screen reader. Keep the chevron where a select stands alone.

```tsx
<SelectTrigger variant="ghost" size="sm" hideIcon aria-label="Status of ENG-188">
  <SelectValue />
</SelectTrigger>
```

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add select
```

It brings `field`, `icon-check`, `icon-chevron-down`, `icon-chevron-up`, `input`, `presentation`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

The copy is 14 registry items, about 8,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `collapse`, `field`, `icon-check`, `icon-chevron-down`, `icon-chevron-up`, `icon-engine`, `input`, `label`, `presentation`, `separator`.

Use Select for one value from a list, such as a region or role. For a short list, a [Radio Group](https://www.youj.dev/docs/components/radio-group) keeps every option visible. Use a [Command](https://www.youj.dev/docs/components/command) list when people need to search.

In the Next.js App Router, render this from a Client Component, a file that starts with `'use client'`: it takes functions (`onValueChange`), and a Server Component can't pass those. [Server rendering](https://www.youj.dev/docs/guides/ssr) has the rest.

```tsx
import { Field, FieldLabel, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@youj/react'

const roles = [
  { value: 'admin', label: 'Admin' },
  { value: 'member', label: 'Member' },
  { value: 'viewer', label: 'Viewer' },
]

export function RoleSelect() {
  return (
    <Field>
      <FieldLabel>Role</FieldLabel>
      <Select items={roles} defaultValue="member" name="role">
        <SelectTrigger className="w-full">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {roles.map((role) => (
            <SelectItem key={role.value} value={role.value}>
              {role.label}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </Field>
  )
}
```

Pass `items`, either an array of `{ value, label }` or an object that maps values to labels, so the trigger can show the chosen label before the popup has ever opened. Without it, the labels are read from the `SelectItem`s written inside the Select. Items that a component of your own renders can't be read, so there `SelectValue` would show the raw value, and development warns once to pass `items`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Select

Takes the props of `SelectPrimitive.Root.Props<Value, Multiple>`.

It takes Base UI's `items`, `value`, `defaultValue`, `onValueChange`, `open`, `onOpenChange`, `multiple`, `disabled`, `readOnly`, `required` and `name`. The `required` default comes from the surrounding `Field`.

#### SelectTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default'` | `'default'` |  |
| `variant` | `'default' \| 'ghost' \| 'soft'` | `'default'` | `ghost`: no field fill or edge, a hover step instead, at the button corner: a select that sits in a toolbar or composer as a quiet button (a model or sort picker). `soft`: no edge, filled with the theme's quiet band (a hover step under the pointer) at the field's own corner and height: a picker inside a card, which already frames it. The fill is a little under 3:1 against the card, so the chevron and the value identify the control, not an edge; keep the default where the select must read on its own. |
| `hideIcon` | `boolean` | `false` | Leaves out the chevron, for a dense row of selects (a table cell, a property list) where the value alone shows it opens. The trigger keeps its role, name and `aria-expanded`. |

#### SelectContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |

The popup's position comes from `side`, `sideOffset`, `align`, `alignOffset` and `alignItemWithTrigger`, which default to `bottom`, `6`, `center`, `0` and `true`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scales from 96% and fades in, from its transform origin |
| Open over the trigger | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | fades only |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Chevron | `spring.snappy` | 0.2s, bounce 0 | turns over while open |
| Scroll arrows | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fade in and out on long lists |

**Reduced motion:** The popup appears and closes at once, and the chevron flips without turning.

The popup wears motion's `yj-pop` preset. When it opens lined up over the trigger, it only fades: growing out of the option you're already looking at reads as a jump.

#### Reduced motion

The popup opens and closes without scaling or fading, and the chevron flips straight to its new direction. The highlighted and chosen options still show the same way.

### Accessibility

- The trigger is a `combobox` that opens a `listbox`. `Space`, `Enter` and `ArrowDown` open it, and typing jumps to a matching option.
- In the popup, the arrow keys, `Home` and `End` move the highlight, `Enter` chooses, and `Escape` closes and returns focus to the trigger.
- A `FieldLabel` names the trigger, and a `FieldDescription` or `FieldError` describes it. Outside a `Field`, give the trigger an `aria-label`.
- A `FieldError` renders as an `alert`, so it's announced when it appears.

---

# Native Select

> Use the browser’s built-in picker with Youj field styling.

Source: https://www.youj.dev/docs/components/native-select

## Examples

### Demo

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@youj/react'

export default function NativeSelectDemo() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel htmlFor="region">Region</FieldLabel>
      <NativeSelect id="region" name="region" defaultValue="fra" className="w-full">
        <NativeSelectOptGroup label="Europe">
          <NativeSelectOption value="fra">Frankfurt (eu-central-1)</NativeSelectOption>
          <NativeSelectOption value="dub">Dublin (eu-west-1)</NativeSelectOption>
        </NativeSelectOptGroup>
        <NativeSelectOptGroup label="Americas">
          <NativeSelectOption value="iad">Virginia (us-east-1)</NativeSelectOption>
          <NativeSelectOption value="sfo">California (us-west-1)</NativeSelectOption>
        </NativeSelectOptGroup>
      </NativeSelect>
      <FieldDescription>Where new projects store their data.</FieldDescription>
    </Field>
  )
}
```

A Region select with options grouped under Europe and Americas, and a description beneath it.

### Sizes and states

```tsx
'use client'

import { Field, FieldError, FieldLabel, NativeSelect, NativeSelectOption } from '@youj/react'

const SIZES = ['sm', 'default', 'lg'] as const

export default function NativeSelectStates() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-6">
      <div className="flex items-center gap-2">
        {SIZES.map((size) => (
          <NativeSelect key={size} size={size} aria-label={`Priority (${size})`} defaultValue="high">
            <NativeSelectOption value="urgent">Urgent</NativeSelectOption>
            <NativeSelectOption value="high">High</NativeSelectOption>
            <NativeSelectOption value="low">Low</NativeSelectOption>
          </NativeSelect>
        ))}
      </div>

{/* An empty value reads as a placeholder. */}
      <Field data-invalid>
        <FieldLabel htmlFor="plan">Plan</FieldLabel>
        <NativeSelect id="plan" aria-invalid defaultValue="" className="w-full">
          <NativeSelectOption value="" disabled>
            Choose a plan
          </NativeSelectOption>
          <NativeSelectOption value="hobby">Hobby</NativeSelectOption>
          <NativeSelectOption value="pro">Pro</NativeSelectOption>
        </NativeSelect>
        <FieldError>Pick a plan to continue.</FieldError>
      </Field>

<NativeSelect aria-label="Team" disabled defaultValue="design" className="w-full">
        <NativeSelectOption value="design">Design</NativeSelectOption>
      </NativeSelect>
    </div>
  )
}
```

Native selects in each size and state.

`size` is `sm`, `default` or `lg`, matching the control heights of inputs and buttons. An empty value reads as a placeholder, `aria-invalid` turns the border red, and `disabled` dims it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add native-select
```

It brings `icon-chevron-down`, `input`, `youj-ui-core` with it.

Use a native select when the operating system's picker serves people better than a custom popup: long option lists on phones, where the OS wheel or sheet is faster; forms that must work before JavaScript loads; plain server-rendered forms. When you need custom rows, icons, search or motion in the popup, use [Select](https://www.youj.dev/docs/components/select) or a [Combobox](https://www.youj.dev/docs/components/combobox).

```tsx
import { NativeSelect, NativeSelectOption } from '@youj/react'

export function Priority() {
  return (
    <NativeSelect name="priority" aria-label="Priority" defaultValue="high">
      <NativeSelectOption value="urgent">Urgent</NativeSelectOption>
      <NativeSelectOption value="high">High</NativeSelectOption>
      <NativeSelectOption value="low">Low</NativeSelectOption>
    </NativeSelect>
  )
}
```

`NativeSelect` takes every `<select>` prop: `value` and `onChange`, `name`, `required`, `disabled`, `aria-invalid`. `className` sizes the wrapper, so `className="w-full"` makes it fill its column. Group options with `NativeSelectOptGroup`. Put it in a [Field](https://www.youj.dev/docs/components/field) for a label, a description and an error. The API matches shadcn/ui's Native Select.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | The control height. |

### Reduced motion

The picker is the operating system's, so there's no motion to reduce. The field's colors ease on hover and focus in both modes.

### Accessibility

- It's a real `<select>`, so keyboards, screen readers, autofill and form submission all work the platform's way, before and after hydration.
- Name it with a `FieldLabel` or `aria-label`. The chevron is decorative (`aria-hidden`).
- Option colors follow the popover tokens where the browser lets a page style them; elsewhere the picker is the system's own and follows the page's color scheme.

---

# Tag Input

> Enter free-form values as chips, with validation and duplicate removal.

Source: https://www.youj.dev/docs/components/tag-input

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, TagInput } from '@youj/react'

function checkTopic(tag: string) {
  if (!/^[a-z0-9-]+$/.test(tag)) return 'Use lowercase letters, numbers and hyphens.'
  if (tag.length > 24) return 'Keep topics under 25 characters.'
}

export default function TagInputDemo() {
  const [topics, setTopics] = useState(['react', 'design-systems', 'motion'])

return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Topics</FieldLabel>
      <TagInput value={topics} onValueChange={setTopics} validate={checkTopic} maxTags={8} placeholder="Add a topic…" />
      <FieldDescription>Press Enter or comma to add. Try “motion” again, or “UI Kit”.</FieldDescription>
    </Field>
  )
}
```

A Topics field holding three tags, validated as lowercase words and capped at eight.

`validate` receives the new tag and the current list, and returns a reason to reject it, or nothing to accept it. A rejected tag stays in the field so it can be fixed: the frame shakes, its border turns destructive, and the reason grows in under it and is read out. A duplicate isn't added. The chip that already holds it flashes instead, so you can see where it is. Try "motion" or "UI Kit" in the demo.

`maxTags` caps the list, and the field stops accepting new tags at the limit.

Chips can be reordered from the keyboard: focus one and press Alt with an arrow key to move it. Moves are announced, and the chips glide to their new places.

### Pasting a list

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, TagInput } from '@youj/react'

export default function TagInputPaste() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Allowed email domains</FieldLabel>
      <TagInput
        defaultValue={['orion.dev']}
        placeholder="Paste or type domains…"
        validate={(tag) => (/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(tag) ? undefined : `“${tag}” isn’t a domain.`)}
      />
      <FieldDescription>Paste “acme.com, example.org, nope” to add several at once.</FieldDescription>
    </Field>
  )
}
```

Pasting a list of values into the field.

Paste "alpha, beta, gamma", or a list with one item per line, and each becomes a chip. Commas, new lines, tabs and semicolons all separate. Items that fail `validate` stay in the field with the reason.

### Email recipients

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, TagInput } from '@youj/react'

const isEmail = (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)

export default function TagInputEmails() {
  const [emails, setEmails] = useState(['mara@northwind.dev', 'ilya@northwind.dev', 'sol@kestrel.studio'])
  return (
    <Field className="w-full max-w-md">
      <FieldLabel>Invite by email</FieldLabel>
      <TagInput
        value={emails}
        onValueChange={setEmails}
        validate={(tag) => (isEmail(tag) ? undefined : `“${tag}” isn’t an email address.`)}
        maxTags={10}
        name="invite"
        placeholder="name@company.com"
      />
      <FieldDescription>Press Enter after each one, or paste a list. Up to 10 at a time.</FieldDescription>
    </Field>
  )
}
```

Inviting people by email, three addresses already added.

Each address is checked by `validate` as it's added, so a typo stays in the field with the reason instead of becoming a chip. `maxTags` caps one batch of invites, and `name` submits every address with the form.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tag-input
```

It brings `badge`, `collapse`, `field`, `input-group`, `presence-list`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-tag-input`, `youj-presets`, `youj-ui-core` with it.

The copy is 24 registry items, about 8,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `badge`, `button`, `collapse`, `field`, `icon-engine`, `icon-loader-ring`, `icon-x`, `input`, `input-group`, `label` and 7 more.

Use a tag input for values people make up: repository topics, allowed email domains, keywords, recipients. Nothing is chosen from a list. For values from a known list, use a [Multi-select](https://www.youj.dev/docs/components/multi-select), which searches and groups them.

```tsx
import { Field, FieldLabel, TagInput } from '@youj/react'

export function TopicsField() {
  const [topics, setTopics] = useState(['react', 'motion'])
  return (
    <Field>
      <FieldLabel>Topics</FieldLabel>
      <TagInput
        value={topics}
        onValueChange={setTopics}
        validate={(tag) => (/^[a-z0-9-]+$/.test(tag) ? undefined : 'Use lowercase letters, numbers and hyphens.')}
        maxTags={8}
      />
    </Field>
  )
}
```

The field is an [Input Group](https://www.youj.dev/docs/components/input-group) whose text input sits inline after the chips and wraps with them. Enter or a comma adds what you typed. `delimiters` changes the keys besides Enter, and `addOnBlur` (on by default) adds the text when the field is left.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` |  |  |
| `defaultValue` | `string[]` | `[]` |  |
| `onValueChange` | `(value: string[]) => void` |  |  |
| `validate` | `(tag: string, tags: string[]) => string \| null \| undefined \| void` |  | Returns a reason to reject a tag, or nothing to accept it. `tags` is the current list. |
| `delimiters` | `string[]` | `[',']` | Keys that commit the typed text, besides Enter. |
| `addOnBlur` | `boolean` | `true` | Adds the typed text when the field loses focus. |
| `maxTags` | `number` |  | The most tags; the field stops accepting new ones at the limit. |
| `placeholder` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits each tag with a native form, under this name. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Chip enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades down into its slot (PresenceList) |
| Chip leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades where it stands |
| Chips reflow or reorder | `spring.smooth` | 0.36s, bounce 0 | glide to their new places |
| Rejected | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the frame shakes a decaying 4, 3 and 2px |
| Reason | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | grows in under the field (Collapse) |
| Duplicate flash | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the existing chip tints at once, then fades back |

**Reduced motion:** No shake and no glide: chips appear, leave and reorder in one frame. The duplicate flash and the reason still show, so the feedback survives.

#### Reduced motion

The rejection doesn't shake and chips don't glide. The duplicate chip still flashes and the reason still appears, because they carry the message rather than decorate it.

### Accessibility

- The text input is named by its `FieldLabel`, or by `aria-label`. While a tag is rejected, it carries `aria-invalid` and is described by the reason, which is a `role="alert"` message and is read out at once.
- In the field, Backspace when empty, or ArrowLeft at the start, reaches the last chip. On a chip, arrows move between chips, Alt with an arrow moves the chip itself, Home and End jump to the ends, Backspace or Delete removes it and focus lands on its neighbor, and Escape returns to the field.
- Each chip's remove button is named after its tag. Additions, removals, moves and duplicates are announced politely.
- With `name`, each tag is submitted with a native form under that name.

---

# Rating

> Collect or display a rating with stars or custom icons, including half steps.

Source: https://www.youj.dev/docs/components/rating

## Examples

### Demo

```tsx
'use client'

import { useId, useState } from 'react'
import {
  AsyncButton,
  Card,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
  Field,
  FieldDescription,
  FieldLabel,
  Rating,
  Textarea,
} from '@youj/react'

const WORDS = ['', 'Poor', 'Fair', 'Good', 'Great', 'Excellent']

export default function RatingDemo() {
  const [rating, setRating] = useState(0)
  const [preview, setPreview] = useState<number | null>(null)
  const shown = preview ?? rating
  const labelId = useId()

return (
    <Card className="w-full max-w-[380px]">
      <CardHeader>
        <CardTitle>How was your stay?</CardTitle>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Field>
          <FieldLabel id={labelId}>Overall</FieldLabel>
          <div className="flex items-center gap-3">
            <Rating
              aria-labelledby={labelId}
              value={rating}
              onValueChange={setRating}
              onPreviewChange={setPreview}
              allowHalf
              size="lg"
            />
            {/* What a click would set while the pointer hovers, then what's set. */}
            <span aria-hidden className={`text-ui tabular-nums transition-colors yj-duration-fast ease-standard ${preview === null ? 'text-fg' : 'text-fg-muted'}`}>
              {shown ? (
                <>
                  {shown} <span className="text-fg-subtle">of 5</span> · {WORDS[Math.ceil(shown)]}
                </>
              ) : (
                <span className="text-fg-subtle">Tap to rate</span>
              )}
            </span>
          </div>
        </Field>
        <Field>
          <FieldLabel>Anything to add?</FieldLabel>
          <Textarea placeholder="The view, the breakfast, the bed…" />
          <FieldDescription>Reviews are public and show your first name.</FieldDescription>
        </Field>
      </CardContent>
      <CardFooter className="justify-end">
        <AsyncButton disabled={!rating} onAction={() => new Promise((resolve) => setTimeout(resolve, 800))} successLabel="Thanks!">
          Post review
        </AsyncButton>
      </CardFooter>
    </Card>
  )
}
```

A review card with a half-step Rating and a readout that names what a click would set.

### Read-only

```tsx
'use client'

import { Rating } from '@youj/react'

const PRODUCTS = [
  { name: 'Linen overshirt', rating: 4.5, reviews: 128 },
  { name: 'Merino crew', rating: 4, reviews: 86 },
  { name: 'Canvas tote', rating: 3.5, reviews: 41 },
]

export default function RatingReadOnly() {
  return (
    <ul className="flex w-full max-w-xs flex-col divide-y divide-line">
      {PRODUCTS.map((product) => (
        <li key={product.name} className="flex items-center justify-between gap-3 py-2.5">
          <span className="text-ui">{product.name}</span>
          <span className="flex items-center gap-2">
            <Rating readOnly value={product.rating} allowHalf size="sm" />
            <span className="text-ui-sm text-fg-muted tabular-nums">({product.reviews})</span>
          </span>
        </li>
      ))}
    </ul>
  )
}
```

Read-only ratings for lists and summaries.

`readOnly` shows a rating without interaction, for lists and summaries. It's an image with a label such as "Rated 4.5 out of 5", so a screen reader hears one sentence and not five icons.

### Icons, scales and states

```tsx
'use client'

import { HeartIcon } from 'lucide-react'
import { Rating } from '@youj/react'

export default function RatingIcons() {
  return (
    <dl className="grid gap-5">
      <div className="grid gap-1.5">
        <dt className="text-ui-sm text-fg-muted">Hearts</dt>
        <dd>
          <Rating
            aria-label="How much did you love it?"
            icon={HeartIcon}
            unit="hearts"
            defaultValue={4}
            className="[&_[data-slot=rating-fill]]:text-danger"
          />
        </dd>
      </div>
      <div className="grid gap-1.5">
        <dt className="text-ui-sm text-fg-muted">A 10-point score</dt>
        <dd>
          <Rating aria-label="Score" max={10} size="sm" defaultValue={7} />
        </dd>
      </div>
      <div className="grid gap-1.5">
        <dt className="text-ui-sm text-fg-muted">Disabled</dt>
        <dd>
          <Rating aria-label="Rating" disabled defaultValue={3} />
        </dd>
      </div>
      <div className="grid gap-1.5">
        <dt className="text-ui-sm text-fg-muted">Right to left</dt>
        <dd dir="rtl">
          <Rating aria-label="Rating" allowHalf defaultValue={3.5} />
        </dd>
      </div>
    </dl>
  )
}
```

Custom icons, scales, sizes and states.

The default star is Rating's own: plump points, rounded by the same stroke that draws its outline. `icon` takes a Youj icon such as `HeartIcon`, or a lucide-style one, filled with the current color, and `unit` names it in the value text ("4 of 5 hearts"). A filled key is the accent (its text color); tint it by setting the color of `[data-slot=rating-fill]`, as the hearts do here with `text-danger`. `max` sets the number of keys, 5 by default, and `size` is `sm`, `default` or `lg` (24, 28 and 32px keys). In a right-to-left layout the fill runs from the right and the arrow keys follow it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add rating
```

It brings `youj-core`, `youj-labels-rating`, `youj-presets`, `youj-ui-core` with it.

Use it to ask for a quick judgment on a fixed scale, such as a review, a satisfaction survey or a score, and to show one back in a list of products or results. It's one focusable control, so a keyboard user reaches it with one Tab and sets it with the arrows or a digit. When the scale has named steps that matter more than their position, such as "Not likely" to "Very likely", a [Radio Group](https://www.youj.dev/docs/components/radio-group) says so more plainly. For an arbitrary number along a range, use a [Slider](https://www.youj.dev/docs/components/slider).

```tsx
import { useState } from 'react'
import { Rating } from '@youj/react'

export function RateStay() {
  const [rating, setRating] = useState(0)
  return <Rating aria-label="Overall" value={rating} onValueChange={setRating} allowHalf />
}
```

The value is a number from 0 to `max`, where 0 means no rating. Each icon sits in a small key of its own, in a row like a segmented control's segments. An empty key is a plain key with a muted outline; a filled one turns the accent, with the icon solid in the accent's contrast color, and a half step fills the left half of a key. Hovering previews the value under the pointer: the keys fill there one by one, the key under the pointer lifts, and keys of the value already set keep a faint accent tint while the preview sits below them. Leaving restores it. Clicking commits it, and clicking the current value again clears it. `allowHalf` rates half a key at a time. With a `name`, the value is submitted with a form.

### A readout

Rating draws no text of its own beyond what it says to a screen reader. `onPreviewChange` reports the value under the pointer, or `null` when it leaves, so a readout beside it can say what a click would set, as the demo's "4.5 of 5 · Excellent" does. Hide that readout from assistive tech (`aria-hidden`): the slider already speaks its value.

```tsx
const [rating, setRating] = useState(0)
const [preview, setPreview] = useState<number | null>(null)
const shown = preview ?? rating

<Rating aria-label="Overall" value={rating} onValueChange={setRating} onPreviewChange={setPreview} />
<span aria-hidden>{shown ? `${shown} of 5` : 'Tap to rate'}</span>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  |  |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `(value: number) => void` |  |  |
| `onPreviewChange` | `(value: number \| null) => void` |  | The value under the pointer while it hovers, or null when it leaves: what a click would set. |
| `max` | `number` | `5` | Number of icons. |
| `allowHalf` | `boolean` | `false` | Half steps. |
| `readOnly` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `icon` | `RatingIcon` | `Star` | The icon, filled with currentColor: a Youj icon or a lucide-style one. |
| `unit` | `string` | `'stars'` | What one icon is, for the value text ("stars", "hearts"). |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` |  |
| `name` | `string` |  | Submits the value in a hidden input. |
| `className` | `string` |  |  |
| `id` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `aria-describedby` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Preview sweep | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | each key’s fill slides to its share, one tight stagger step per key from the edge it moves from |
| Lift | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the key under the pointer rises 2px and scales to 1.05 |
| Commit press | `spring.settle` | 0.45s, bounce 0.3 | the committed key presses to 0.86 and springs back with a little overshoot |
| Ripple | `duration.base`, `ease.emphasized` | 220ms; cubic-bezier(0.6, 0, 0.1, 1) | the filled keys before it rise to 1.06 and back, a tight stagger step apart |
| Glint | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | five short accent rays open just outside the committed key and fade |

**Reduced motion:** The fill snaps to the new value; nothing lifts, presses or glints.

#### Reduced motion

The fill moves to the new value at once, and nothing lifts, presses or glints. The hover preview still shows what a click will commit, with the keys of the value already set faintly tinted.

### Accessibility

- It's one `slider` with a value text such as "3.5 of 5 stars", or "No rating" at 0. Name it with `aria-label` or `aria-labelledby`, as the demo does with the Field's label.
- ArrowRight and ArrowUp step up, ArrowLeft and ArrowDown step down (mirrored in right-to-left layouts), Home and Backspace clear it, End sets the maximum and a digit jumps to that value.
- The hit area reaches a few pixels past the keys, and the focus ring hugs the row.
- Disabled, it leaves the tab order and reports `aria-disabled`.
- `readOnly` renders `role="img"` with a label ("Rated 4.5 out of 5", or your `aria-label`), and takes no focus.
- Empty keys are edged in the control line tone, which holds 3:1 against the surface, so the scale reads before anything is filled. A filled key's icon is the accent's contrast color on the accent.

---

# Calendar

> Pick a date or range from a month grid.

Source: https://www.youj.dev/docs/components/calendar

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { format } from 'date-fns'
import { Calendar } from '@youj/react/date'

export default function CalendarDemo() {
  const [date, setDate] = useState<Date | undefined>(new Date())

return (
    <div className="flex flex-col items-center gap-3">
      <div className="rounded-xl border border-line bg-surface p-3 shadow-xs">
        <Calendar mode="single" selected={date} onSelect={setDate} />
      </div>
      <p className="text-ui-sm text-fg-muted" aria-live="polite">
        {date ? format(date, 'EEEE, MMMM d, yyyy') : 'No date selected'}
      </p>
    </div>
  )
}
```

A single-date Calendar with today selected and the chosen day read out beneath it.

### Ranges

```tsx
'use client'

import { useState } from 'react'
import { addDays } from 'date-fns'
import { Calendar, type DateRangePickerProps } from '@youj/react/date'

type DateRange = NonNullable<DateRangePickerProps['value']>

export default function CalendarRange() {
  const today = new Date()
  const [range, setRange] = useState<DateRange | undefined>({ from: addDays(today, -3), to: addDays(today, 9) })

return (
    <div className="rounded-xl border border-line bg-surface p-3 shadow-xs">
      <Calendar mode="range" numberOfMonths={2} showOutsideDays={false} fixedWeeks={false} selected={range} onSelect={setRange} />
    </div>
  )
}
```

Range selection, with the chosen days drawn as one continuous band.

With `mode="range"`, the chosen days form one continuous band with solid ends. The band runs unbroken across each week and rounds off at the week's edges and where a month begins or ends mid-week, so it reads as rows. Show two months with `numberOfMonths={2}`. They sit side by side from the `sm` breakpoint and stack below it.

### Bounds and disabled days

```tsx
'use client'

import { useState } from 'react'
import { addDays, format, isWeekend } from 'date-fns'
import { Calendar } from '@youj/react/date'

export default function CalendarBounded() {
  const today = new Date()
  const last = addDays(today, 60)
  const [date, setDate] = useState<Date | undefined>()

return (
    <div className="rounded-xl border border-line bg-surface p-3 shadow-xs">
      <Calendar
        mode="single"
        selected={date}
        onSelect={setDate}
        startMonth={today}
        endMonth={last}
        disabled={[{ before: today }, { after: last }, isWeekend]}
        footer={date ? `Deploy window: ${format(date, 'PPP')}` : 'Weekdays in the next 60 days.'}
      />
    </div>
  )
}
```

A calendar with bounded months and disabled days.

`startMonth` and `endMonth` stop the arrows at the bounds. `disabled` takes react-day-picker matchers: dates, `{ before }` and `{ after }`, day-of-week objects, or a function such as date-fns's `isWeekend`. A `footer` sits under the grid, which is a good place to confirm the choice.

## Installation & usage

```bash
pnpm add @youj/react date-fns react-day-picker
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add calendar
```

It brings `button`, `icon-chevron-down`, `icon-chevron-left`, `icon-chevron-right`, `icon-chevron-up`, `use-now`, `youj-core`, `youj-labels-calendar`, `youj-ui-core` with it.

Requires `date-fns` and `react-day-picker`, [optional dependencies](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/date`.

Use Calendar when choosing a date is the main task and the month should stay visible. In a form, use [Date Picker](https://www.youj.dev/docs/components/date-picker) or [Date Range Picker](https://www.youj.dev/docs/components/date-range-picker). Both put this calendar in a popover and let people type a date.

```tsx
import { useState } from 'react'
import { Calendar } from '@youj/react/date'

export function DeployDay() {
  const [date, setDate] = useState<Date | undefined>(new Date())
  return <Calendar mode="single" selected={date} onSelect={setDate} />
}
```

`Calendar` is [react-day-picker](https://daypicker.dev) dressed in Youj's controls: every day and both arrows are a ghost [Button](https://www.youj.dev/docs/components/button), so hover, press and the focus ring match every other control. Every react-day-picker prop works as its docs describe: `mode` (`single`, `multiple` or `range`), `selected` and `onSelect`, `disabled` matchers, `startMonth` and `endMonth`, `numberOfMonths`, `locale`, `footer` and more.

Today carries a dot under its number. `showOutsideDays` and `fixedWeeks` are on by default, so the grid keeps six rows and the popover around it doesn't change height from month to month.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

`Calendar` takes react-day-picker's `DayPicker` props, unchanged, and passes `animate` only while motion is allowed. It sets three defaults of its own: `showOutsideDays`, `fixedWeeks` and `animate` are all `true`. `classNames` and `components` merge over Youj's, so you can restyle one part or replace one component without losing the rest. `CalendarDayButton` is exported for custom day rendering.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Month enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | from the side it comes from, a third of the width, fading in |
| Month leaves | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the other way, fading out |
| Day hover and press | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the Button's background and press scale |

**Reduced motion:** The month changes in place, with no slide. Days don't scale when pressed.

The slide only plays when the month changes from the arrows. Moving across a month's edge from the keyboard swaps the month in place, because react-day-picker keeps focus stable on the day. Under right-to-left layouts the slide is mirrored.

#### Reduced motion

The month swaps in place instead of sliding, and the day buttons don't scale when pressed. Selection, keyboard navigation and labels are unchanged.

### Accessibility

- The grid is react-day-picker's `role="grid"`, labeled with the month and year in the locale you pass.
- Arrow keys move by day, PageUp and PageDown by month, Shift with PageUp or PageDown by year, and Home and End to the start and end of the week. Enter or Space selects.
- Days carry full date labels ("Monday, September 28th, 2026"), today and selected states, and disabled days are skipped for selection.
- The arrows are real buttons, named "Go to the Previous Month" and "Go to the Next Month", and disabled at the bounds.

---

# Time Picker

> Enter a time using your locale’s clock format.

Source: https://www.youj.dev/docs/components/time-picker

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, TimePicker } from '@youj/react'

export default function TimePickerDemo() {
  const [time, setTime] = useState<string | null>('09:30')

return (
    <Field className="w-full max-w-60">
      <FieldLabel>Daily standup</FieldLabel>
      {/* A fixed locale renders the same AM/PM words on the server and in the browser. */}
      <TimePicker value={time} onValueChange={setTime} step={15} hourCycle={12} locale="en-US" />
      <FieldDescription>{time ? `Stored as ${time}. ` : ''}Quarter-hour steps.</FieldDescription>
    </Field>
  )
}
```

A daily standup time on a 12-hour clock, in 15-minute steps.

Type digits and the picker moves on by itself once a segment can't take another: "7" in the hours means 07, while "1" waits for a second digit. A colon or ArrowRight moves on too, so "245p" types 2:45 PM. ArrowUp and ArrowDown step, wrapping around, and minutes step by `step`. Home and End jump to a segment's ends, Backspace clears it, and A or P sets the period. A typed minute that falls between steps snaps to the nearest step when you leave the field.

### Clocks and locales

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, TimePicker } from '@youj/react'

export default function TimePickerClocks() {
  return (
    <div className="flex w-full max-w-60 flex-col gap-6">
      <Field>
        <FieldLabel>Maintenance starts (UTC)</FieldLabel>
        <TimePicker hourCycle={24} defaultValue="02:00" step={5} />
        <FieldDescription>24-hour clock, 5-minute steps.</FieldDescription>
      </Field>
      <Field>
        <FieldLabel>Beginn</FieldLabel>
        <TimePicker locale="de-DE" defaultValue="14:45" />
        <FieldDescription>German locale: 24-hour by default.</FieldDescription>
      </Field>
    </div>
  )
}
```

Clocks that follow the locale.

The clock follows the locale: `locale="de-DE"` gives a 24-hour clock, `en-US` a 12-hour one with its own AM and PM words. `hourCycle` overrides the locale when a time is always shown one way, such as UTC maintenance windows on a 24-hour clock.

Default: the YoujProvider's locale (en-US without one), never the runtime's, so the server and the browser render the same clock and AM/PM words.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add time-picker
```

It brings `field`, `icon-clock`, `input-group`, `use-controllable-state`, `youj-core`, `youj-labels-time-picker`, `youj-presets`, `youj-ui-core` with it.

The copy is 20 registry items, about 8,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-clock`, `icon-engine`, `icon-loader-ring`, `input`, `input-group`, `label`, `separator` and 3 more.

Use a time picker for a time of day: a standup, a maintenance window, a reminder. It works like the platform's own time field, with hours, minutes and, on a 12-hour clock, AM or PM, but it's styled and stepped like the rest of the kit. Pair it with a [Date Picker](https://www.youj.dev/docs/components/date-picker) when the moment needs a day too. For a duration, use a [Number Input](https://www.youj.dev/docs/components/number-input). Where a time is spun rather than typed (a touch-first form, an alarm), a [Wheel Picker](https://www.youj.dev/docs/components/wheel-picker) with hour and minute columns is the alternative.

```tsx
import { Field, FieldLabel, TimePicker } from '@youj/react'

export function Standup() {
  const [time, setTime] = useState<string | null>('09:30')
  return (
    <Field>
      <FieldLabel>Daily standup</FieldLabel>
      <TimePicker value={time} onValueChange={setTime} step={15} />
    </Field>
  )
}
```

The value is a 24-hour `"HH:mm"` string, like `<input type="time">`, once both hours and minutes are set, and `null` otherwise. Each segment is a spinbutton in one [Input Group](https://www.youj.dev/docs/components/input-group) frame.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string \| null` |  | "HH:mm", 24-hour. |
| `defaultValue` | `string \| null` | `null` |  |
| `onValueChange` | `(value: string \| null) => void` |  |  |
| `hourCycle` | `12 \| 24` |  | 12 or 24. Default: the locale's. |
| `locale` | `string` |  | A BCP 47 locale for the clock and the AM/PM words. Default: the YoujProvider locale. |
| `step` | `number` | `1` | Minutes per ArrowUp/Down, and the grid a typed minute snaps to. |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits "HH:mm" with a native form. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Segment focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the focused segment takes a soft accent tint |

**Reduced motion:** Nothing else moves, so reduced motion changes nothing: the tint still marks the focused segment.

#### Reduced motion

The only motion is the focused segment's tint, which stays, because it shows where you're typing.

### Accessibility

- The segments sit in a group named by the Field's label, or by `aria-label`. Each is a `spinbutton` named "Hours", "Minutes" or "AM/PM", with its range and a value text that reads "Empty" while it's unset.
- The Field's description and error describe every segment, and `aria-invalid` and `aria-required` follow the Field.
- Tab moves between segments like any other field. The arrows, digits, Home, End, Backspace, A and P work as described above.
- With `name`, a hidden input submits the `"HH:mm"` value with a native form.

---

# Wheel Picker

> Spin a drum of values to pick one: a time, a date or any short list, one column per part.

Source: https://www.youj.dev/docs/components/wheel-picker

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { WheelPicker, type WheelPickerColumn } from '@youj/react'

const pad = (n: number) => String(n).padStart(2, '0')

const COLUMNS: WheelPickerColumn[] = [
  { id: 'hour', label: 'Hours', options: Array.from({ length: 12 }, (_, i) => ({ value: String(i + 1), label: String(i + 1) })) },
  { id: 'minute', label: 'Minutes', options: Array.from({ length: 12 }, (_, i) => ({ value: pad(i * 5), label: pad(i * 5) })) },
  {
    id: 'period',
    label: 'AM or PM',
    options: [
      { value: 'AM', label: 'AM' },
      { value: 'PM', label: 'PM' },
    ],
  },
]

export default function WheelPickerDemo() {
  const [alarm, setAlarm] = useState<Record<string, string>>({ hour: '7', minute: '30', period: 'AM' })

return (
    <div className="flex flex-col items-center gap-3">
      <WheelPicker aria-label="Alarm" columns={COLUMNS} value={alarm} onValueChange={setAlarm} />
      <p className="text-ui-sm text-fg-muted tabular-nums">
        Alarm at {alarm.hour}:{alarm.minute} {alarm.period}
      </p>
    </div>
  )
}
```

An alarm in three columns: hours, minutes in fives, and AM or PM.

Drag a column, or flick it and let it coast onto a row. The mouse wheel and trackpad turn it too, and a click on a row brings it to the band. Each column wraps neither way here; pass `loop` to make every column run round.

### Date

```tsx
'use client'

import { useState } from 'react'
import { WheelPicker, type WheelPickerColumn } from '@youj/react'

const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
const daysIn = (year: number, month: number) => new Date(year, month, 0).getDate()
const numbers = (from: number, to: number) => Array.from({ length: to - from + 1 }, (_, i) => ({ value: String(from + i), label: String(from + i) }))

export default function WheelPickerDate() {
  const [date, setDate] = useState<Record<string, string>>({ month: '2', day: '14', year: '1990' })
  const days = daysIn(Number(date.year), Number(date.month))
  const columns: WheelPickerColumn[] = [
    { id: 'month', label: 'Month', options: MONTHS.map((m, i) => ({ value: String(i + 1), label: m })) },
    // Every month shows 31 rows, so the column never changes length; the days a month lacks are disabled.
    { id: 'day', label: 'Day', options: numbers(1, 31).map((o) => ({ ...o, disabled: Number(o.value) > days })) },
    { id: 'year', label: 'Year', options: numbers(1930, 2026) },
  ]

const change = (next: Record<string, string>) => {
    const max = daysIn(Number(next.year), Number(next.month))
    setDate(Number(next.day) > max ? { ...next, day: String(max) } : next)
  }

return <WheelPicker aria-label="Date of birth" columns={columns} value={date} onValueChange={change} />
}
```

A date of birth: month, day and year.

The day column always has 31 rows, so it never changes length as the month turns; the days a month lacks are `disabled`, and the wheel won't rest on them. The app clamps the day when the month changes.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add wheel-picker
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-wheel-picker`, `youj-ui-core` with it.

Use a wheel picker where spinning is the natural gesture: touch-first forms, a timer, an alarm, a short list to choose from in place. For a time typed at a keyboard, use a [Time Picker](https://www.youj.dev/docs/components/time-picker); for a long list to search, a [Select](https://www.youj.dev/docs/components/select) or a [Combobox](https://www.youj.dev/docs/components/combobox).

```tsx
import { WheelPicker } from '@youj/react'

<WheelPicker
  aria-label="Alarm"
  columns={[
    { id: 'hour', label: 'Hours', options: hours },
    { id: 'minute', label: 'Minutes', options: minutes },
  ]}
  value={alarm}
  onValueChange={setAlarm}
/>
```

Each column is `{ id, label, options }`, and each option `{ value, label, disabled? }`. With columns, the value is an object of each column's value by its `id`. One column has a shorthand: `options` and `label` on the picker, with a plain string value.

```tsx
<WheelPicker label="Fruit" options={fruit} defaultValue="cherry" />
```

It is uncontrolled with `defaultValue` (a column left out starts on its first row it can rest on), or controlled with `value` and `onValueChange`. The value is committed when a column is let go, so `onValueChange` fires once per spin, not on every row it passes.

`size` (`sm`, `default` or `lg`) sets the row height and type, following the theme's control heights. The picker keeps its size while it turns: each column is as wide as its widest label.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `WheelPickerColumn[]` |  | The wheels, start to end. |
| `value` | `Record<string, string>` |  | The chosen value of each column, by column id. Controlled. |
| `defaultValue` | `Record<string, string>` |  | The starting values when uncontrolled. A column left out starts on its first row it can rest on. |
| `onValueChange` | `(value: Record<string, string>) => void` |  |  |
| `options` | `never` |  | One wheel's rows: the shorthand for a single column. |
| `label` | `never` |  | The wheel's accessible name. Default "Value" (translated). |
| `loop` | `boolean` |  | Every column wraps around: past the last row comes the first. |
| `size` | `'default' \| 'sm' \| 'lg'` | ``default`` | The row height and type size. |
| `disabled` | `boolean` |  | Blocks dragging, scrolling and keys, and takes the columns out of the tab order. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), every row that passes the band ticks. `false` keeps it silent. |

#### Data attributes

The root carries `data-size`, plus `data-yj-loop` with `loop` and `data-disabled` when disabled. Each column is `wheel-picker-column` with `data-id` (its column id) and `data-dragging` while a pointer holds it; each drawn row is `wheel-picker-item` with `data-index`, and `data-selected` in the band and `data-disabled` when it can't be chosen. The band is `wheel-picker-band`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drag |  |  | the column follows the pointer 1:1; past either end it pulls less the further it goes |
| Flick | `duration.slow` | 340ms | the column coasts on with the flick’s momentum and decays onto the row it reaches |
| Let go past an end | `spring.smooth` | 0.36s, bounce 0 | the column springs back to the first or last row |
| Key, click, wheel or new value | `spring.smooth` | 0.36s, bounce 0 | the column turns to the row |
| Rows |  |  | rows curve away on a drum and fade towards the top and bottom; the row in the band is full strength |

**Reduced motion:** A drag still follows the pointer. There is no momentum: a release, key, click or new value puts the row in the band at once.

#### Reduced motion

Dragging works the same. A release lands on the nearest row with no momentum, and keys, clicks and new values turn the column at once.

#### Sound

With sound on (`YoujProvider`'s `sound`), every row that passes the band ticks. `sound={false}` keeps the picker silent.

### Accessibility

- Each column is a `spinbutton` named by its `label`, its value text the chosen row's label, so a screen reader reads "Hours, 7" and each new row as it turns. Give the picker an `aria-label` too when it has more than one column; it is a `group`.
- ArrowUp turns to the next row and ArrowDown to the one before; Page Up and Page Down turn five rows; Home and End go to the first and last. Disabled rows are skipped.
- Typing jumps to the next row whose label starts with what was typed; the same letter again moves on to the next match.
- ArrowLeft and ArrowRight move between columns, mirrored in right-to-left, where the columns run from the right too.
- Each column is one tab stop with a visible focus ring. `disabled` takes the columns out of the tab order and sets `aria-disabled`.
- Touch, pen and mouse drag; each pointer is captured, so a drag keeps going outside the column. The wheel turns the column under the pointer without scrolling the page.

---

# Hours Dial

> Set a window of the day on a 24-hour face, with two handles that may run past midnight.

Source: https://www.youj.dev/docs/components/hours-dial

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { HoursDial, SegmentedControl, SegmentedControlItem, type HoursDialValue } from '@youj/react'

type Days = 'weekdays' | 'weekend'

export default function HoursDialDemo() {
  const [days, setDays] = useState<Days>('weekdays')
  const [sleep, setSleep] = useState<Record<Days, HoursDialValue>>({
    weekdays: { start: 22 * 60 + 30, end: 6 * 60 + 45 },
    weekend: { start: 23 * 60 + 30, end: 8 * 60 + 30 },
  })
  return (
    <div className="flex w-full max-w-72 flex-col items-center gap-5">
      <SegmentedControl aria-label="Days" value={days} onValueChange={(v) => setDays(v as Days)} className="w-full">
        <SegmentedControlItem value="weekdays" className="flex-1">
          Weekdays
        </SegmentedControlItem>
        <SegmentedControlItem value="weekend" className="flex-1">
          Weekend
        </SegmentedControlItem>
      </SegmentedControl>
      <HoursDial label="Sleep schedule" caption="Asleep" value={sleep[days]} onValueChange={(v) => setSleep((s) => ({ ...s, [days]: v }))} />
    </div>
  )
}
```

A sleep schedule for weekdays and the weekend: drag either handle, or the lit band to move the whole night.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add hours-dial
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-hours-dial`, `youj-presets`, `youj-ui-core` with it.

Use an hours dial for a stretch of the day: a sleep schedule, quiet hours, a shift, opening hours. The face is a whole day, midnight at the top and turning clockwise, with a ruler of quarter-hour ticks all the way round. A hollow handle marks the start and a solid one the end; the ticks between them light in the tone, and the center reads the length large in mono with the two times under it. For one bounded value on an arc, such as a temperature or a volume, use a [Dial](https://www.youj.dev/docs/components/dial); for a single time, a [Time Picker](https://www.youj.dev/docs/components/time-picker).

```tsx
import { HoursDial } from '@youj/react'

<HoursDial
  label="Sleep schedule"
  caption="Asleep"
  value={sleep}
  onValueChange={setSleep}
/>
```

The value is `{ start, end }` in minutes after midnight (0–1439); an `end` before the `start` runs past midnight, so `{ start: 1350, end: 420 }` is 22:30 to 07:00. `step` (15 minutes) is what an arrow key moves and what a drag snaps to, and `largeStep` (an hour) is what Page Up and Down move. The handles never meet: the window stays at least a step long and a step short of a whole day. `tone` colors the lit stretch (the accent, a chart color or neutral), `caption` puts a mono capital over the length, and the times read in the provider's locale (12- or 24-hour as it writes them). It's uncontrolled with `defaultValue`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `HoursDialValue` |  |  |
| `defaultValue` | `HoursDialValue` | `{ start: 22 * 60 + 30, end: 7 * 60 }` |  |
| `onValueChange` | `(value: HoursDialValue) => void` |  |  |
| `step` | `number` | `15` | Minutes per arrow key and the snap of a drag; a divisor of 60 suits best. |
| `largeStep` | `number` | `60` | Minutes per Page Up/Down. |
| `tone` | `'accent' \| 'neutral' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The lit stretch's color. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name of the pair of handles. Default: the labels' "Time range". |
| `caption` | `ReactNode` |  | A mono capital over the length: "Asleep". |
| `disabled` | `boolean` | `false` |  |
| `sound` | `boolean` | `true` | Plays the tick cue at every step. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `hours-dial` (with `data-tone`, `data-dragging` set to `start`, `end` or `window` while a pointer holds it, and `data-disabled`), `hours-dial-face`, `hours-dial-band`, `hours-dial-ruler`, `hours-dial-range`, `hours-dial-numerals`, `hours-dial-start` and `hours-dial-end` (the handles, with `data-dragging`), `hours-dial-center`, `hours-dial-label`, `hours-dial-value` and `hours-dial-times`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Keyboard or click | `spring.snappy` | 0.2s, bounce 0 | the handles and the lit stretch glide to the new times together, the short way round, retargeting mid-flight |
| Drag | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | a handle, or the whole window, follows the pointer 1:1, snapping to the step |
| Hover or drag | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the handle grows a little |

**Reduced motion:** Every change jumps.

#### Reduced motion

The handles and the lit stretch jump to each new time.

### Accessibility

- It's a group named by `label` (default: the labels' "Time range") holding two sliders, "Start" and "End", each valued in minutes after midnight. Their value text is the time and the window's length in the locale ("10:30 PM, 8 hours, 30 minutes in all").
- Arrows move a handle by the step, Page Up and Down by an hour, Home to midnight and End to the last step before it; steps wrap round midnight. A press on the face focuses the handle it moves, so the keys carry on from there.
- A clock turns clockwise in every script, so the face and its keys keep their direction under RTL: right and up move later. The text in the center follows the page.
- Every step plays the tick cue, like a detent, behind `sound` (on by default).
- Its words come from the labels (`hoursDial`, `hoursDialStart`, `hoursDialEnd`, `hoursDialValue`), translated by the language packs.

---

# Dialog

> Focus on a short task in a modal window that keeps keyboard focus inside.

Source: https://www.youj.dev/docs/components/dialog

## Examples

### Demo

```tsx
'use client'

import { useState, type FormEvent } from 'react'
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
  Input,
} from '@youj/react'
import { PencilIcon } from '@youj/icons'
import { IllustrationDesignTools } from '@youj/illustrations'

const slugify = (name: string) =>
  name
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-|-$/g, '')

export default function DialogDemo() {
  const [open, setOpen] = useState(false)
  const [name, setName] = useState('Orion')
  const [draft, setDraft] = useState(name)
  const [touched, setTouched] = useState(false)
  const [saving, setSaving] = useState(false)
  const invalid = touched && draft.trim() === ''

function save(event: FormEvent) {
    event.preventDefault()
    setTouched(true)
    if (draft.trim() === '') return
    setSaving(true)
    // Stands in for the request to your API.
    setTimeout(() => {
      setName(draft.trim())
      setSaving(false)
      setOpen(false)
    }, 900)
  }

return (
    <div className="flex w-full max-w-sm items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="grid size-9 shrink-0 place-items-center rounded-lg bg-accent-subtle font-mono text-ui-sm font-semibold text-accent-text">
        {name.slice(0, 2).toUpperCase()}
      </div>
      <div className="flex min-w-0 flex-1 flex-col">
        <span className="truncate text-ui font-semibold text-fg">{name}</span>
        <span className="truncate text-ui-sm text-fg-muted">acme.dev/{slugify(name)}</span>
      </div>
      <Dialog
        open={open}
        onOpenChange={(next) => {
          // The dialog holds while the save runs, so its outcome isn't hidden.
          if (saving) return
          setOpen(next)
          if (next) {
            setDraft(name)
            setTouched(false)
          }
        }}
      >
        <DialogTrigger render={<Button variant="outline" size="sm" />}>
          <PencilIcon />
          Rename
        </DialogTrigger>
        <DialogContent>
          <form onSubmit={save} noValidate className="flex flex-col gap-4">
            <div className="flex items-center gap-4">
              {/* Decorative: with no title the scene is hidden from assistive tech. */}
              <IllustrationDesignTools unit={9} className="-my-4 -mx-2 shrink-0" />
              <DialogHeader>
                <DialogTitle>Rename project</DialogTitle>
                <DialogDescription>The name shows in the sidebar and in the project’s URL.</DialogDescription>
              </DialogHeader>
            </div>
            <Field invalid={invalid}>
              <FieldLabel>Name</FieldLabel>
              <Input
                value={draft}
                onChange={(event) => setDraft(event.target.value)}
                onFocus={(event) => event.currentTarget.select()}
                readOnly={saving}
                autoComplete="off"
              />
              {invalid ? (
                <FieldError>Enter a name for the project.</FieldError>
              ) : (
                <FieldDescription>acme.dev/{slugify(draft) || '…'}</FieldDescription>
              )}
            </Field>
            <DialogFooter>
              <DialogClose render={<Button variant="outline" disabled={saving} />}>Cancel</DialogClose>
              <Button type="submit" loading={saving} loadingLabel="Saving">
                Save
              </Button>
            </DialogFooter>
          </form>
        </DialogContent>
      </Dialog>
    </div>
  )
}
```

A project card whose Rename button opens a form dialog with a validated name field and a save that takes a moment.

The Demo story is a form in a dialog. Four details make it hold up:

- Put the `<form>` inside `DialogContent`, around the header, the fields and the footer, so Enter submits from any field.
- Control `open` and ignore close requests while the save runs. The outcome then shows in the dialog, next to the choice that caused it, and not on a page the person has already left.
- Make the field `readOnly` instead of `disabled` while saving. Disabling the focused field would drop focus onto the page.
- Focus starts on the first field, so people can type straight away. Select its text on focus when the task is to replace it.

```tsx
<Dialog open={open} onOpenChange={(next) => !saving && setOpen(next)}>
```

### Nested dialogs

```tsx
'use client'

import { useState } from 'react'
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldLabel,
  Input,
  Switch,
} from '@youj/react'
import { ArrowLeftRightIcon, SettingsIcon } from '@youj/icons'
import { IllustrationDelivery, IllustrationPadlock, LineGrid } from '@youj/illustrations'

export default function DialogNested() {
  const [transferOpen, setTransferOpen] = useState(false)
  const [workspace, setWorkspace] = useState('')
  const [requested, setRequested] = useState('')

return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        <SettingsIcon />
        Project settings
      </DialogTrigger>
      <DialogContent className="max-w-lg">
        {/* Decorative: with no title the scene is hidden from assistive tech. */}
        <div className="relative isolate grid place-items-center overflow-hidden rounded-lg border border-line py-2">
          <LineGrid gap={16} />
          <IllustrationPadlock unit={10} />
        </div>
        <DialogHeader>
          <DialogTitle>Orion settings</DialogTitle>
          <DialogDescription>
            {requested ? `Transfer to ${requested} requested.` : 'Visibility, previews and ownership.'}
          </DialogDescription>
        </DialogHeader>
        <div className="flex flex-col divide-y divide-line rounded-lg border border-line">
          <Field orientation="horizontal" className="justify-between p-3">
            <FieldLabel>Public preview links</FieldLabel>
            <Switch defaultChecked />
          </Field>
          <Field orientation="horizontal" className="justify-between p-3">
            <FieldLabel>Comments on previews</FieldLabel>
            <Switch />
          </Field>
          <div className="flex items-center justify-between gap-3 p-3">
            <div className="flex flex-col">
              <span className="text-ui font-medium text-fg">Transfer ownership</span>
              <span className="text-ui-sm text-fg-muted">Move Orion to another workspace.</span>
            </div>
            {/* A dialog inside a dialog: opening it pushes this one a step back. */}
            <Dialog open={transferOpen} onOpenChange={setTransferOpen}>
              <DialogTrigger render={<Button variant="outline" size="sm" />}>
                <ArrowLeftRightIcon />
                Transfer…
              </DialogTrigger>
              <DialogContent>
                <form
                  className="flex flex-col gap-4"
                  onSubmit={(event) => {
                    event.preventDefault()
                    setRequested(workspace.trim() || 'acme-labs')
                    setTransferOpen(false)
                  }}
                >
                  <div className="flex items-center gap-4">
                    {/* Decorative: with no title the scene is hidden from assistive tech. */}
                    <IllustrationDelivery unit={9} className="-my-4 -mx-2 shrink-0" />
                    <DialogHeader>
                      <DialogTitle>Transfer Orion</DialogTitle>
                      <DialogDescription>Deployments keep running. Members of this workspace lose access.</DialogDescription>
                    </DialogHeader>
                  </div>
                  <Field>
                    <FieldLabel>Destination workspace</FieldLabel>
                    <Input value={workspace} onChange={(event) => setWorkspace(event.target.value)} placeholder="acme-labs" />
                  </Field>
                  <DialogFooter>
                    <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
                    <Button type="submit">Request transfer</Button>
                  </DialogFooter>
                </form>
              </DialogContent>
            </Dialog>
          </div>
        </div>
        <DialogFooter>
          <DialogClose render={<Button />}>Done</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

A dialog that opens a second dialog on top of it.

A dialog can open another one. The parent moves down, shrinks and dims under a wash, so the stack reads as depth, and it comes forward again when the child closes. Base UI keeps one scrim for the whole stack. Escape closes only the top dialog, and focus goes back to the control that opened it.

Nest sparingly. One level for a follow-up question reads clearly. A third level is a sign that the task wants a page of its own.

### Long content

```tsx
'use client'

import {
  Badge,
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@youj/react'
import { SparklesIcon } from '@youj/icons'
import { IllustrationAnnouncement } from '@youj/illustrations'

const RELEASES = [
  { version: '4.14', title: 'Streaming search results', notes: 'Results render from the edge as they arrive, so the first ones show in under 100 ms.' },
  { version: '4.13', title: 'Preview comments sync', notes: 'Comments on a preview link to the issue in your tracker and resolve when it closes.' },
  { version: '4.12', title: 'Audit log filters', notes: 'Filter the audit log by member, project and action, and export any view as CSV.' },
  { version: '4.11', title: 'Faster cold starts', notes: 'Functions on the edge runtime start 38% faster, with no change to your code.' },
  { version: '4.10', title: 'Protected previews', notes: 'Only members of the workspace can open preview links, unless you share a pass.' },
  { version: '4.9', title: 'Rollbacks from the CLI', notes: 'Roll production back to any earlier deployment with one command.' },
  { version: '4.8', title: 'Environment groups', notes: 'Share one set of variables across projects, and override it per project.' },
  { version: '4.7', title: 'Region pinning', notes: 'Pin a project’s functions to one region, close to its database.' },
  { version: '4.6', title: 'Build cache insights', notes: 'See which steps hit the cache and how much time each one saved.' },
  { version: '4.5', title: 'Custom 404 pages', notes: 'Serve your own not-found page for every route a project doesn’t match.' },
  { version: '4.4', title: 'Deploy hooks', notes: 'Trigger a deployment from any service with a signed URL.' },
  { version: '4.3', title: 'Team roles', notes: 'Give members viewer, developer or admin access, per project.' },
]

export default function DialogLong() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        <SparklesIcon />
        What’s new
      </DialogTrigger>
      {/* No × button: the footer's action is the one way out besides Escape and the scrim. */}
      <DialogContent showCloseButton={false} className="max-w-lg">
        {/* Decorative: with no title the scene is hidden from assistive tech. */}
        <div className="grid place-items-center rounded-lg py-3">
          <IllustrationAnnouncement unit={13} />
        </div>
        <DialogHeader>
          <DialogTitle>What’s new in Orion</DialogTitle>
          <DialogDescription>Everything that shipped this quarter.</DialogDescription>
        </DialogHeader>
        <ol className="flex flex-col gap-4">
          {RELEASES.map((release) => (
            <li key={release.version} className="flex flex-col gap-1">
              <span className="flex items-center gap-2 text-ui font-medium text-fg">
                <Badge variant="secondary" className="font-mono">
                  {release.version}
                </Badge>
                {release.title}
              </span>
              <p className="text-ui text-fg-muted">{release.notes}</p>
            </li>
          ))}
        </ol>
        <DialogFooter>
          <DialogClose render={<Button />}>Got it</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

A dialog taller than the window, scrolling inside the viewport.

A dialog taller than the window scrolls inside the viewport, while the page behind it stays put. When the first control sits below the fold, focus starts on the dialog itself, so the reader begins at the title and not at the bottom. `showCloseButton={false}` removes the × when the footer already offers the way out.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dialog
```

It brings `button`, `presentation`, `youj-core`, `youj-labels-dialog`, `youj-presets`, `youj-ui-core` with it.

The copy is 12 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-engine`, `icon-loader-ring`, `presentation`, `spinner`.

Use Dialog for a short task that needs attention, such as renaming a project or inviting a teammate. It blocks the rest of the page, so keep it focused. Use a [Sheet](https://www.youj.dev/docs/components/sheet) for more space, a [Drawer](https://www.youj.dev/docs/components/drawer) for swipe dismissal, or a [Popover](https://www.youj.dev/docs/components/popover) for controls that leave the page usable. Confirm destructive actions with an [Alert Dialog](https://www.youj.dev/docs/components/alert-dialog).

In the Next.js App Router, render this from a Client Component, a file that starts with `'use client'`: it takes functions (`onOpenChange`), and a Server Component can't pass those. [Server rendering](https://www.youj.dev/docs/guides/ssr) has the rest.

```tsx
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@youj/react'

export function InviteDialog() {
  return (
    <Dialog>
      <DialogTrigger render={<Button />}>Invite</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Invite to Orion</DialogTitle>
          <DialogDescription>They can see and deploy every branch of the project.</DialogDescription>
        </DialogHeader>
        <InviteForm id="invite" />
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
          <Button type="submit" form="invite">
            Send invite
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

`DialogContent` renders the whole overlay: a portal, the scrim, a viewport that centers the popup, and the popup with a × button in its top corner. `DialogTrigger` and `DialogClose` take a `render` prop, so any [Button](https://www.youj.dev/docs/components/button) can open or close the dialog. `Dialog` is Base UI's root, so `open`, `defaultOpen`, `onOpenChange`, `modal` and `disablePointerDismissal` work as Base UI documents them.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

`DialogContent` adds two props to Base UI's `Dialog.Popup`: `showCloseButton` and `presentation`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `true` | Renders the × button in the top corner. |
| `presentation` | `'auto' \| 'sheet' \| 'dialog'` | `'auto'` | `auto` (the default) is a centered dialog under a pointer and a bottom sheet on touch; `dialog` or `sheet` forces one. |

Also takes the props of `DialogPrimitive.Popup.Props`.

`Dialog` (Root) passes its props through to Base UI and adds `sound`: with sound on (`YoujProvider`’s `sound`) opening plays the `open` cue and closing the `close` cue, and `sound={false}` keeps that dialog silent. The other parts add styling only and pass their props through to Base UI: `DialogTrigger`, `DialogClose`, `DialogTitle`, `DialogDescription`, `DialogOverlay` (Backdrop) and `DialogPortal`. `DialogHeader` and `DialogFooter` are plain `div`s. The footer stacks its actions with the primary one on top on narrow screens, and lines them up at the end from the `sm` breakpoint; in a touch sheet they always stack at full width.

### Touch

On a touch device the dialog is a bottom sheet. It rises from the bottom of the screen over the scrim, spans the screen's width up to 36rem and has a grab handle. Pull it down to close it, alongside Escape, the × and a tap on the scrim: a quick flick closes it from a short pull, and a short, slow pull springs back. Focus returns to the trigger, as it does for the centered dialog. Content taller than 90% of the screen scrolls inside the sheet, and a pull only moves the sheet once that content is scrolled to the top. The sheet clears the home indicator and moves up to stay above the on-screen keyboard.

The footer's actions stack at full width with the primary one on top, each at least 44px tall, and the × gets a 44px target. Opened by a tap, focus goes to the sheet rather than its first field, so the keyboard comes up only when someone taps the field. A dialog opened from a sheet is a sheet too, and the one below recedes. A dialog that refuses to close, say while it saves, springs back when pulled. A control that handles its own drag, such as a crop area or a slider, should carry `data-sheet-no-drag` (an element with `touch-action: none` is skipped too), so dragging it never moves the sheet.

`presentation` on `DialogContent` chooses: `auto` (the default) is the centered dialog under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `dialog` keeps the centered dialog on touch too. Touch follows the device, not the screen width, and `YoujProvider`'s `device` can force it for a part of the page. For a panel that is a swipeable sheet everywhere, use [Drawer](https://www.youj.dev/docs/components/drawer).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | rises 6px and scales up from .96 as it fades in (`yj-dialog`) |
| Exit | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the same path back, faster |
| Scrim in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | opacity (`yj-backdrop`) |
| Scrim out | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |
| Parent recedes | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | 0.875rem down and 6% smaller per nested level, under a dimming wash |
| Parent returns | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | when the nested dialog closes |
| Touch: enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the sheet slides up from the bottom edge (`yj-sheet-bottom`) |
| Touch: pull |  | 1:1 | the sheet follows the finger and the scrim thins |
| Touch: release | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | past a quarter of its height or on a flick it leaves (a flick twice as fast); otherwise it springs back |

**Reduced motion:** Opens and closes instantly. A parent under a nested dialog takes its receded place and dims at once. On touch the sheet appears and leaves at once, and a pull still tracks the finger.

The presets run on CSS transitions, not keyframes, so closing a dialog halfway through its entrance reverses from where it is. The popup is centered by the viewport's layout, not by a `-50%` translate, so its text stays sharp at every height.

#### Reduced motion

The dialog and its scrim appear and disappear at once, with no rise, scale or fade. Focus handling and the scrim are unchanged, so the dialog behaves the same, only without motion. Portaled content follows the preview's Reduced motion switch because `DialogContent` spreads `useYoujScope()` on its portal.

### Accessibility

- The popup has `role="dialog"` and `aria-modal`. `DialogTitle` names it and `DialogDescription` describes it, through `aria-labelledby` and `aria-describedby`. Always render a title, even a visually hidden one.
- Focus moves into the dialog when it opens: to the first field or button, or to the dialog itself when that control is below the fold or the dialog was opened by a tap. Pass `initialFocus` to choose another element.
- Focus is trapped while the dialog is open. Tab and Shift+Tab cycle through its controls, and the page behind is inert.
- Escape, a press on the scrim and the × button close it. Focus then returns to the trigger, or to the element that had it before the dialog opened.
- The × button is named "Close" for screen readers.

---

# Alert Dialog

> Ask for confirmation before a destructive or hard-to-reverse action.

Source: https://www.youj.dev/docs/components/alert-dialog

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ConfirmDialog } from '@youj/react'
import { TrashIcon } from '@youj/icons'
import { IllustrationWarehouse } from '@youj/illustrations'
import { LoaderOffshoot } from '@youj/loaders/offshoot'

// Stands in for the request to your API.
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function AlertDialogDemo() {
  const [open, setOpen] = useState(false)
  const [deleted, setDeleted] = useState(false)
  const [deleting, setDeleting] = useState(false)

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface shadow-xs">
      <div className="border-b border-line px-4 py-3">
        <span className="text-ui font-semibold text-fg">Danger zone</span>
      </div>
      <div className="flex items-center gap-4 p-4">
        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
          <span className="text-ui font-medium text-fg">Delete this project</span>
          <span role="status" className="text-ui-sm text-fg-muted">
            {deleted ? 'orion and its 214 deployments were deleted.' : 'Removes orion with its deployments and domains.'}
          </span>
        </div>
        <Button variant="danger" size="sm" disabled={deleted} focusableWhenDisabled onClick={() => setOpen(true)}>
          <TrashIcon />
          {deleted ? 'Deleted' : 'Delete…'}
        </Button>
      </div>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        icon={<TrashIcon />}
        title="Delete orion?"
        description="Its 214 deployments, 3 domains and every environment variable go with it. This can’t be undone."
        confirmLabel="Delete project"
        pendingLabel="Deleting orion"
        challenge="orion"
        onConfirm={async () => {
          // A promise keeps the dialog open, and busy, until the work lands.
          setDeleting(true)
          await wait(1200)
          setDeleting(false)
          setDeleted(true)
        }}
      >
        {/* Decorative: the warehouse, and while it's deleting a loader in its place (the button already announces the wait). */}
        <div className="grid h-28 place-items-center rounded-lg">
          {deleting ? <LoaderOffshoot size={72} label={null} /> : <IllustrationWarehouse unit={10} />}
        </div>
      </ConfirmDialog>
    </div>
  )
}
```

A danger-zone row whose Delete button opens a confirmation that names the project and runs the deletion while it waits.

### When the work fails

```tsx
'use client'

import { useState } from 'react'
import { Badge, Button, ConfirmDialog } from '@youj/react'
import { GlobeIcon } from '@youj/icons'
import { LoaderOutpost } from '@youj/loaders/outpost'

// Stands in for the request to your API, which refuses this one.
const removeDomain = () =>
  new Promise<void>((_, reject) =>
    setTimeout(() => reject(new Error('acme.dev still has 2 aliases: www.acme.dev and docs.acme.dev. Remove them first.')), 900),
  )

export default function AlertDialogFailure() {
  const [open, setOpen] = useState(false)
  const [removing, setRemoving] = useState(false)

return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <GlobeIcon size={16} className="text-fg-muted" />
      <div className="flex min-w-0 flex-1 flex-col gap-0.5">
        <span className="flex items-center gap-2 text-ui font-medium text-fg">
          acme.dev
          <Badge variant="success">Valid</Badge>
        </span>
        <span className="text-ui-sm text-fg-muted">Production · 2 aliases</span>
      </div>
      <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
        Remove
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        // While the request runs, traffic moves off the domain in the badge. The dialog announces the wait itself.
        icon={removing ? <LoaderOutpost size={28} label={null} /> : <GlobeIcon />}
        title="Remove acme.dev?"
        description="Requests to acme.dev stop reaching orion right away."
        confirmLabel="Remove domain"
        pendingLabel="Removing acme.dev"
        // A rejected promise keeps the dialog open and shows the error's message.
        onConfirm={() => {
          setRemoving(true)
          return removeDomain().finally(() => setRemoving(false))
        }}
      />
    </div>
  )
}
```

A confirmation whose work rejects, so the dialog stays open and shows the error.

If the promise rejects, the dialog stays open, the confirm button settles back, and the error's message appears as an alert above the actions, beside the choice that caused it. The typed challenge is kept, so trying again takes one press. The phrase and the error clear when the dialog closes.

### Type to confirm

```tsx
'use client'

import { useState } from 'react'
import { Button, ConfirmDialog } from '@youj/react'
import { TrashIcon } from '@youj/icons'

// Stands in for the request to your API.
const deleteProject = () => new Promise<void>((resolve) => setTimeout(resolve, 1000))

export default function AlertDialogTypeToConfirm() {
  const [open, setOpen] = useState(false)
  const [deleted, setDeleted] = useState(false)

return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="flex min-w-0 flex-1 flex-col gap-0.5">
        <span className="font-mono text-ui font-medium text-fg">acme/orion</span>
        <span className="text-ui-sm text-fg-muted">{deleted ? 'Deleted' : '12 deployments · 3 domains'}</span>
      </div>
      <Button variant="danger" size="sm" disabled={deleted} onClick={() => setOpen(true)}>
        Delete project
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        icon={<TrashIcon />}
        title="Delete acme/orion?"
        description="This can’t be undone."
        // What will be lost, with counts.
        consequences={['12 deployments and their logs', '3 custom domains', '48 environment variables', 'Access for 7 members']}
        confirmLabel="Delete project"
        pendingLabel="Deleting acme/orion"
        // The phrase to type: shown in a copyable chip, matched exactly (case-sensitive, trimmed).
        challenge="acme/orion"
        onConfirm={() => deleteProject().then(() => setDeleted(true))}
      />
    </div>
  )
}
```

Deleting a project: the consequences with counts, the phrase in a copyable chip, and a confirm that stays disabled until it is typed exactly.

Pass `challenge` for a high-impact delete of a named thing (a project, workspace, repository or account). The phrase shows in a chip with a copy button; the field arms the danger button only on an exact match, case-sensitive, ignoring spaces at either end. Pasting is allowed. Enter does nothing until it matches. `consequences` lists what will be lost, with counts, so the person reads what they are about to do.

```tsx
<ConfirmDialog
  open={open}
  onOpenChange={setOpen}
  destructive
  title="Delete acme/orion?"
  consequences={['12 deployments and their logs', '3 custom domains', 'Access for 7 members']}
  confirmLabel="Delete project"
  challenge="acme/orion"
  onConfirm={() => deleteProject(id)}
/>
```

### Delete account

```tsx
'use client'

import { useRef, useState } from 'react'
import { Button, ConfirmDialog } from '@youj/react'
import { TrashIcon } from '@youj/icons'

export default function AlertDialogDeleteAccount() {
  const [open, setOpen] = useState(false)
  const attempts = useRef(0)

return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="flex min-w-0 flex-1 flex-col gap-0.5">
        <span className="text-ui font-medium text-fg">Delete account</span>
        <span className="text-ui-sm text-fg-muted">Removes you and everything you own.</span>
      </div>
      <Button variant="danger" size="sm" onClick={() => setOpen(true)}>
        Delete account
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        icon={<TrashIcon />}
        title="Delete your account?"
        description="Your workspaces, repositories and billing history are deleted for good."
        consequences={['3 workspaces you own', '24 repositories', 'Your subscription is cancelled']}
        confirmLabel="Delete account"
        pendingLabel="Deleting account"
        challenge="delete my account"
        // The first try fails, so the dialog stays open with the reason and the typed phrase; the second one lands.
        onConfirm={() =>
          new Promise<void>((resolve, reject) =>
            setTimeout(() => {
              attempts.current += 1
              if (attempts.current === 1) reject(new Error('You still own workspace “Acme”. Transfer it, then try again.'))
              else resolve()
            }, 1000),
          )
        }
      />
    </div>
  )
}
```

An async delete whose first attempt fails: the dialog stays open with the reason and the typed phrase, and the second attempt lands.

### Plain confirm

```tsx
'use client'

import { useState } from 'react'
import { Button, ConfirmDialog } from '@youj/react'
import { KeyIcon } from '@youj/icons'

export default function AlertDialogPlain() {
  const [open, setOpen] = useState(false)
  const [revoked, setRevoked] = useState(false)

return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <KeyIcon size={16} className="text-fg-muted" />
      <div className="flex min-w-0 flex-1 flex-col gap-0.5">
        <span className="text-ui font-medium text-fg">Deploy key</span>
        <span className="text-ui-sm text-fg-muted">{revoked ? 'Revoked' : 'Last used 2 hours ago'}</span>
      </div>
      <Button variant="outline" size="sm" disabled={revoked} onClick={() => setOpen(true)}>
        Revoke
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        icon={<KeyIcon />}
        title="Revoke this key?"
        description="Deploys that use it start failing immediately."
        // No `challenge`: the plain tier. Focus starts on Cancel.
        consequences={['2 pipelines use this key']}
        confirmLabel="Revoke key"
        onConfirm={() => setRevoked(true)}
      />
    </div>
  )
}
```

The plain tier: no `challenge`, so no typing. Focus starts on Cancel. Use it where the action is serious but narrow.

### Composing the parts

```tsx
'use client'

import { useState } from 'react'
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
} from '@youj/react'
import { RocketIcon } from '@youj/icons'
import { IllustrationDocuments, IllustrationNewsletter } from '@youj/illustrations'

export default function AlertDialogCompose() {
  const [publishOpen, setPublishOpen] = useState(false)
  const [discardOpen, setDiscardOpen] = useState(false)
  const [status, setStatus] = useState('Release notes · 3 unsaved changes')

return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex flex-wrap justify-center gap-2">
        {/* The default size: an icon badge beside the title, actions in the footer band. */}
        <AlertDialog open={publishOpen} onOpenChange={setPublishOpen}>
          <AlertDialogTrigger render={<Button />}>
            <RocketIcon />
            Publish…
          </AlertDialogTrigger>
          <AlertDialogContent>
            {/* Decorative: with no title the scene is hidden from assistive tech. */}
            <div className="grid place-items-center rounded-lg py-1">
              <IllustrationNewsletter unit={10} />
            </div>
            <AlertDialogHeader>
              <AlertDialogMedia>
                <RocketIcon />
              </AlertDialogMedia>
              <AlertDialogTitle>Publish the release notes?</AlertDialogTitle>
              <AlertDialogDescription>They go out to 1,240 subscribers and appear on the changelog.</AlertDialogDescription>
            </AlertDialogHeader>
            <AlertDialogFooter>
              <AlertDialogCancel>Not yet</AlertDialogCancel>
              <AlertDialogAction
                onClick={() => {
                  setStatus('Release notes published')
                  setPublishOpen(false)
                }}
              >
                Publish
              </AlertDialogAction>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialog>

{/* size="sm": a short question, centered over two equal buttons. */}
        <AlertDialog open={discardOpen} onOpenChange={setDiscardOpen}>
          <AlertDialogTrigger render={<Button variant="outline" />}>Close editor</AlertDialogTrigger>
          <AlertDialogContent size="sm">
            <AlertDialogHeader>
              <IllustrationDocuments unit={7} className="-my-2" />
              <AlertDialogTitle>Discard changes?</AlertDialogTitle>
              <AlertDialogDescription>Your edits to the release notes haven’t been saved.</AlertDialogDescription>
            </AlertDialogHeader>
            <AlertDialogFooter>
              <AlertDialogCancel>Keep editing</AlertDialogCancel>
              <AlertDialogAction
                variant="danger"
                onClick={() => {
                  setStatus('Editor closed, changes discarded')
                  setDiscardOpen(false)
                }}
              >
                Discard
              </AlertDialogAction>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialog>
      </div>
      <p role="status" className="text-ui-sm text-fg-muted">
        {status}
      </p>
    </div>
  )
}
```

Alert dialogs built from the parts, in the default and `sm` sizes.

`AlertDialogContent` comes in two sizes. The default puts an `AlertDialogMedia` badge beside the title and the actions in a band along the bottom. `size="sm"` centers a short question over two equal buttons. `AlertDialogCancel` closes the dialog and is an outline button by default. `AlertDialogAction` is a [Button](https://www.youj.dev/docs/components/button) and doesn't close anything by itself, so close the dialog from its handler.

### Async actions

```tsx
'use client'

import { useState } from 'react'
import type { AsyncState } from '@youj/motion'
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
  Field,
  FieldLabel,
  Switch,
} from '@youj/react'
import { HistoryIcon } from '@youj/icons'
import { LoaderOffshoot } from '@youj/loaders/offshoot'

// Stands in for the request to your API.
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function AlertDialogActionDemo() {
  const [open, setOpen] = useState(false)
  const [state, setState] = useState<AsyncState>('idle')
  const [live, setLive] = useState('4f2a91c')
  const [failNext, setFailNext] = useState(false)

async function rollBack() {
    await wait(1200)
    if (failNext) throw new Error('The build for 3f9c2a1 has expired')
    setLive('3f9c2a1')
  }

return (
    <div className="flex w-full max-w-md flex-col gap-4 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="flex items-center gap-3">
        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
          <span className="text-ui font-medium text-fg">Production</span>
          <span className="font-mono text-ui-sm text-fg-muted">acme.dev · {live}</span>
        </div>
        {/* While the rollback runs, the dialog can't be dismissed. */}
        <AlertDialog open={open} onOpenChange={(next) => state !== 'pending' && setOpen(next)}>
          <AlertDialogTrigger
            render={<Button variant="outline" size="sm" disabled={live === '3f9c2a1'} focusableWhenDisabled />}
          >
            <HistoryIcon />
            Roll back
          </AlertDialogTrigger>
          <AlertDialogContent>
            <AlertDialogHeader>
              {/* While it runs, the badge plays the commit history; the action's label announces the wait. */}
              <AlertDialogMedia>{state === 'pending' ? <LoaderOffshoot size={28} label={null} /> : <HistoryIcon />}</AlertDialogMedia>
              <AlertDialogTitle>Roll back production?</AlertDialogTitle>
              <AlertDialogDescription>acme.dev serves 3f9c2a1, from yesterday, until the next promotion.</AlertDialogDescription>
            </AlertDialogHeader>
            <AlertDialogFooter>
              <AlertDialogCancel disabled={state === 'pending'}>Cancel</AlertDialogCancel>
              <AlertDialogAction
                onAction={rollBack}
                pendingLabel="Rolling back…"
                successLabel="Rolled back"
                errorLabel="Rollback failed"
                onActionStateChange={(next) => {
                  // Close once the success has shown and settled. After an error, stay open to retry.
                  if (next === 'idle' && state === 'success') setOpen(false)
                  setState(next)
                }}
              >
                Roll back to 3f9c2a1
              </AlertDialogAction>
            </AlertDialogFooter>
          </AlertDialogContent>
        </AlertDialog>
      </div>
      <Field orientation="horizontal" className="border-t border-line pt-3">
        <Switch checked={failNext} onCheckedChange={setFailNext} />
        <FieldLabel className="font-normal text-fg-muted">Make the next rollback fail</FieldLabel>
      </Field>
    </div>
  )
}
```

A confirm button that runs its own action and plays the whole lifecycle on the button.

Because `AlertDialogAction` is a Button that becomes an [Async Button](https://www.youj.dev/docs/components/button#async-actions) when you pass `onAction` or `status`, it takes `onAction`, and the action's whole lifecycle plays on the button itself. The label morphs to a spinner and `pendingLabel`, then to a drawn check and `successLabel`, or shakes to a cross and `errorLabel`. Close the dialog once success has shown. After an error, keep it open so the person can try again. Flip the switch in the preview to see the failure path.

```tsx
<AlertDialog
  open={open}
  // The dialog can't be dismissed while the work runs.
  onOpenChange={(next) => state !== 'pending' && setOpen(next)}
>
  …
  <AlertDialogAction
    onAction={rollBack}
    pendingLabel="Rolling back…"
    successLabel="Rolled back"
    errorLabel="Rollback failed"
    onActionStateChange={(next) => {
      if (next === 'idle' && state === 'success') setOpen(false)
      setState(next)
    }}
  >
    Roll back to 3f9c2a1
  </AlertDialogAction>
</AlertDialog>
```

Reach for `ConfirmDialog` first. It holds the dialog through the work and shows failures as text, which suits most confirmations. `onAction` suits a dialog where the result belongs on the button.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add alert-dialog
```

It brings `async-button`, `button`, `dialog`, `field`, `icon-check`, `icon-copy`, `input-group`, `youj-core`, `youj-labels-alert-dialog`, `youj-labels-code-block`, `youj-ui-core` with it.

The copy is 29 registry items, about 10,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `collapse`, `dialog`, `field`, `icon-check`, `icon-copy`, `icon-engine`, `icon-loader-ring` and 8 more.

Use Alert Dialog before deleting a project, revoking a key or discarding unsaved work. Unlike [Dialog](https://www.youj.dev/docs/components/dialog), it stays open when you press outside. Reserve confirmation for actions that are hard to reverse. For reversible actions, offer Undo in a [Toast](https://www.youj.dev/docs/components/toast).

`ConfirmDialog` is the whole pattern in one component. Its confirm button says what it does, it stays open while async work runs, and it can ask for a typed phrase before a wide destructive action.

```tsx
import { useState } from 'react'
import { Button, ConfirmDialog } from '@youj/react'
import { TrashIcon } from '@youj/icons'

export function DeleteProject({ project }: { project: Project }) {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Button variant="danger" onClick={() => setOpen(true)}>
        Delete…
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        destructive
        icon={<TrashIcon />}
        title={`Delete ${project.name}?`}
        description="Its deployments and domains go with it. This can’t be undone."
        confirmLabel="Delete project"
        challenge={project.name}
        onConfirm={() => deleteProject(project.id)}
      />
    </>
  )
}
```

`destructive` here is a boolean on `ConfirmDialog`; the trigger [Button](https://www.youj.dev/docs/components/button) takes `variant="danger"`.

To lay one out by hand, compose the parts:

```tsx
import { useState } from 'react'
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
} from '@youj/react'

const [open, setOpen] = useState(false)

<AlertDialog open={open} onOpenChange={setOpen}>
  <AlertDialogTrigger render={<Button variant="outline" />}>Close editor</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Discard changes?</AlertDialogTitle>
      <AlertDialogDescription>Your edits haven’t been saved.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Keep editing</AlertDialogCancel>
      <AlertDialogAction
        variant="danger"
        // The action doesn't close the dialog by itself.
        onClick={() => {
          discard()
          setOpen(false)
        }}
      >
        Discard
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

### Confirm and challenge

Name the action on the button: "Delete project" or "Delete 12 projects", never "OK" or "Yes". The label is the last thing people read before they commit.

`challenge` arms the confirm only once the exact phrase is typed, shown in a copyable chip above the field, and a check draws itself in the field when it matches. Reserve it for actions that are destructive and wide, like a bulk delete or anything with a name. On a small, common action it's friction that people learn to rush.

`onConfirm` decides how the dialog closes:

- A plain function runs and the dialog closes.
- A function that returns a promise keeps the dialog open while it runs. The confirm button shows a spinner and announces `pendingLabel`, Cancel and Escape are held, and the dialog closes when the promise resolves.
- `loading` forces the busy state, for work that something else drives.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### ConfirmDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `confirmLabel` (required) | `string` |  | What confirming does, in its own words: "Delete 12 projects". Never "OK". |
| `cancelLabel` | `string` | `"Cancel"` |  |
| `onConfirm` (required) | `() => unknown` |  | Return a promise to keep the dialog open while the work runs: it closes when the promise resolves, and stays open with the error's message when it rejects, so the failure shows next to the choice that caused it. |
| `destructive` | `boolean` | `false` | A destructive confirm button and icon badge. |
| `icon` | `ReactNode` |  | The icon in the badge beside the title. |
| `challenge` | `string` |  | Escalates the confirm: it arms only once this exact phrase is typed. Reserve it for actions that are destructive and wide (many rows, or something named). |
| `challengeLabel` | `ReactNode` |  | The challenge field's label. Default: "Type this phrase to confirm", with the phrase in a copyable chip above the field. |
| `consequences` | `ReactNode[]` |  | What will be lost, as a list under the description: counts, names. |
| `pendingLabel` | `string` | `"Working"` | Announced while an async confirm runs. |
| `loading` | `boolean` | `false` | Forces the loading state, for work driven elsewhere. An async `onConfirm` sets it by itself. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void)` |  | Where focus goes once the dialog has closed: an element or ref, or a function that picks one (return `false` to leave focus where it is, say after moving it yourself). Default: back to whatever had focus when it opened. Base UI's `finalFocus`. |
| `onOpenChangeComplete` | `(open: boolean) => void` |  | Runs when the open or close animation has finished. Base UI's `onOpenChangeComplete`. |
| `children` | `ReactNode` |  | Extra content between the description and the challenge, such as what will be affected. |

#### AlertDialogContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'default' \| 'sm'` | `'default'` | `sm` centers a short question over two equal buttons. |

Also takes the props of `AlertDialogPrimitive.Popup.Props`.

#### AlertDialogAction

`AlertDialogAction` takes every [Button](https://www.youj.dev/docs/components/button) prop, including the async ones.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'danger' \| 'ghost' \| 'outline' \| 'link' \| 'secondary'` |  | `default \| secondary \| outline \| ghost \| danger \| link`. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the button plays `tap` as it's pressed. `false` keeps this one silent. |
| `size` | `'default' \| 'sm' \| 'lg' \| 'xs' \| 'icon' \| 'icon-xs' \| 'icon-sm' \| 'icon-lg'` |  |  |

#### AlertDialogMedia

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'danger'` |  |  |

`AlertDialogCancel` takes Base UI's `AlertDialog.Close` props plus Button's `variant` (default `outline`) and `size`. `AlertDialog`, `AlertDialogTrigger`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogOverlay` and `AlertDialogPortal` pass their props through to Base UI. `AlertDialogHeader` and `AlertDialogFooter` are plain `div`s.

### Touch

On a touch device an alert dialog stays a centered alert, the way a phone's own alerts are. Unlike [Dialog](https://www.youj.dev/docs/components/dialog), it doesn't become a sheet and can't be pulled away: it's asking a question, and a swipe isn't an answer. Its actions stack at full width with the primary one on top, each at least 44px tall, and show the same press feedback as every button. The small size keeps its two buttons side by side. Nothing in it depends on hover.

Opened by a tap, focus goes to the alert itself rather than to Cancel or a challenge field, so the on-screen keyboard comes up only when someone taps the field.

### Motion

**Reduced motion:** Opens and closes instantly. The check appears drawn, spinners hold still, and an async label swaps without a morph or a shake, with its pending text in place of the spinner.

#### Reduced motion

The dialog appears and leaves at once. Everything that reports progress still does, without moving: the challenge's check appears already drawn, a pending confirm shows a still spinner, and `onAction` swaps its label for text, with no morph and no shake.

### Accessibility

- The popup has `role="alertdialog"`. `AlertDialogTitle` names it and `AlertDialogDescription` describes it, so screen readers read the question and its consequence together.
- In `ConfirmDialog`, focus starts on the least destructive control: Cancel, or the challenge field when there is one. When you compose the parts, focus starts on the first focusable control in the popup, so keep `AlertDialogCancel` before the action, as in the snippets. Enter from the field confirms once the phrase matches. Opened by a tap, focus starts on the alert itself.
- A press outside neither closes the dialog nor moves focus. Escape cancels, unless async work is running. Focus returns to the element that opened it.
- While a confirm runs, the button keeps focus and sets `aria-busy`, and `pendingLabel` is announced. A failure is announced assertively through `role="alert"`. A matching phrase is announced as "Phrase matches".
- The media badge is decorative (`aria-hidden`), so put the meaning in the title.

---

# Share Dialog

> Share a document, board or file with people and by link: invite, see who has access and set what the link allows.

Source: https://www.youj.dev/docs/components/share-dialog

## Examples

### Share a document

```tsx
'use client'

import { useState } from 'react'
import { ShareIcon } from '@youj/icons'
import { Button, ShareDialog, type SharePerson } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

const suggestions = [
  { id: 'katherine', name: 'Katherine Johnson', email: 'katherine@acme.com' },
  { id: 'margaret', name: 'Margaret Hamilton', email: 'margaret@acme.com' },
  { id: 'dorothy', name: 'Dorothy Vaughan', email: 'dorothy@acme.com' },
  { id: 'design', name: 'Design team', members: 12 },
  { id: 'eng', name: 'Engineering', members: 48 },
]

export default function ShareDialogDemo() {
  const [people, setPeople] = useState<SharePerson[]>([
    { id: 'ada', name: 'Ada Lovelace', email: 'ada@acme.com', role: 'editor', owner: true },
    { id: 'grace', name: 'Grace Hopper', email: 'grace@acme.com', role: 'editor' },
    { id: 'alan', name: 'Alan Turing', email: 'alan@acme.com', role: 'commenter' },
    { id: 'mary', name: 'Mary Jackson', email: 'mary@partner.io', role: 'viewer', pending: true },
  ])

return (
    <ShareDialog
      trigger={
        <Button variant="outline">
          <ShareIcon />
          Share
        </Button>
      }
      resource="Q3 roadmap"
      link="https://acme.test/docs/q3-roadmap"
      organization="Acme"
      people={people}
      suggestions={suggestions}
      onInvite={async ({ recipients, role }) => {
        await wait(900)
        setPeople((current) => [
          ...current,
          ...recipients.map((r, i) => ({ id: `${r.id ?? r.email}-${current.length + i}`, name: r.name, email: r.email, role, pending: true })),
        ])
      }}
      onRoleChange={async (person, role) => {
        await wait(500)
        setPeople((current) => current.map((p) => (p.id === person.id ? { ...p, role } : p)))
      }}
      onRemove={async (person) => {
        await wait(500)
        setPeople((current) => current.filter((p) => p.id !== person.id))
      }}
      onResend={() => wait(700)}
    />
  )
}
```

A roadmap shared with an editor, a commenter and a pending invitation. Type an address or pick a person or group, choose a role and send.

The dialog is Google-Drive-style sharing in one window. Everyone's role can change from their row, access can be removed, and a pending invitation is marked and can be resent or cancelled. Each action waits for your handler and fails on its own row, so nothing closes while something is wrong.

### Organization link

```tsx
'use client'

import { useState } from 'react'
import { ShareIcon } from '@youj/icons'
import { Button, ShareDialog, type ShareAccess, type SharePerson } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function ShareDialogOrganization() {
  const [access, setAccess] = useState<ShareAccess>({ scope: 'organization', role: 'commenter' })

return (
    <ShareDialog
      trigger={
        <Button variant="outline">
          <ShareIcon />
          Share
        </Button>
      }
      resource="Hiring plan"
      link="https://acme.test/docs/hiring-plan"
      organization="Acme"
      people={people}
      access={access}
      onAccessChange={async (next) => {
        await wait(600)
        setAccess(next)
      }}
    />
  )
}
```

A document anyone at the company can comment on, and no one outside it can open.

General access offers `Restricted`, `Anyone at <organization>` (only when you pass `organization`) and `Anyone with the link`. The two open ones take a role for the people who arrive by the link. A change is applied once your `onAccessChange` resolves; if it rejects, the old value stays and its message shows under the setting.

### Read-only viewer

```tsx
'use client'

import { ShareIcon } from '@youj/icons'
import { Button, ShareDialog, type SharePerson } from '@youj/react'

const people: SharePerson[] = [
  { id: 'ada', name: 'Ada Lovelace', email: 'ada@acme.com', role: 'editor', owner: true },
  { id: 'grace', name: 'Grace Hopper', email: 'grace@acme.com', role: 'editor' },
  { id: 'alan', name: 'Alan Turing', email: 'alan@acme.com', role: 'commenter' },
  { id: 'you', name: 'You', email: 'you@acme.com', role: 'viewer' },
]

export default function ShareDialogReadOnly() {
  return (
    <ShareDialog
      readOnly
      trigger={
        <Button variant="outline">
          <ShareIcon />
          Share
        </Button>
      }
      resource="Board minutes"
      link="https://acme.test/docs/board-minutes"
      organization="Acme"
      people={people}
      defaultAccess={{ scope: 'organization', role: 'viewer' }}
    />
  )
}
```

A viewer who may see who has access but can change nothing.

`readOnly` removes the invite field, turns every role select into plain text and drops the remove buttons. Copy link stays: the viewer can still pass the link on, within what general access allows.

### Share with a preview

```tsx
'use client'

import { useState } from 'react'
import { ShareIcon } from '@youj/icons'
import { Button, ShareDialog, type ShareAccess, type SharePerson } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function ShareDialogWithPreview() {
  const [people, setPeople] = useState<SharePerson[]>([
    { id: 'ada', name: 'Ada Lovelace', email: 'ada@acme.com', role: 'editor', owner: true },
    { id: 'grace', name: 'Grace Hopper', email: 'grace@acme.com', role: 'editor' },
    { id: 'alan', name: 'Alan Turing', email: 'alan@acme.com', role: 'commenter' },
  ])
  const [access, setAccess] = useState<ShareAccess>({ scope: 'restricted', role: 'viewer' })

return (
    <ShareDialog
      trigger={
        <Button variant="outline">
          <ShareIcon />
          Share
        </Button>
      }
      resource="Q3 roadmap"
      link="https://acme.test/docs/q3-roadmap"
      organization="Acme"
      preview={{ title: 'Q3 roadmap.pdf', description: 'Updated 2 days ago · 3.4 MB' }}
      accessLayout="switches"
      people={people}
      suggestions={suggestions}
      access={access}
      onAccessChange={async (next) => {
        await wait(500)
        setAccess(next)
      }}
      onInvite={async ({ recipients, role }) => {
        await wait(900)
        setPeople((current) => [
          ...current,
          ...recipients.map((r, i) => ({ id: `${r.id ?? r.email}-${current.length + i}`, name: r.name, email: r.email, role, pending: true })),
        ])
      }}
      onRoleChange={async (person, role) => {
        await wait(500)
        setPeople((current) => current.map((p) => (p.id === person.id ? { ...p, role } : p)))
      }}
      onRemove={async (person) => {
        await wait(500)
        setPeople((current) => current.filter((p) => p.id !== person.id))
      }}
    />
  )
}
```

A file shared from its own screen: a card with its name and one line of detail sits above the invite field, and general access is a short list of switches.

`preview` takes `{ title, description?, thumbnail? }`; without a `thumbnail` the card shows a document icon. `accessLayout="switches"` is the compact general access for a narrower dialog: no message field, and one row per way in, each a title, a line and a Switch on the same edge. **Only people invited** carries the role invitations start on (so the invite field loses its own role menu) and its switch stays on until you turn another row on. **Anyone at `<organization>`** and **Anyone with the link** open the document when on, with their own role menu beside the switch; turning one off goes back to invited people only. `onAccessChange` and the rest work as in the default layout.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add share-dialog
```

It brings `async-button`, `avatar`, `badge`, `button`, `dialog`, `icon-building`, `icon-file-text`, `icon-globe`, `icon-link`, `icon-lock`, `icon-x`, `input`, `presence-list`, `select`, `skeleton`, `switch`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-share-dialog`, `youj-presets`, `youj-ui-core` with it.

The copy is 42 registry items, about 11,700 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `avatar`, `badge`, `button`, `collapse`, `dialog`, `field`, `icon-building`, `icon-check` and 22 more.

Use a Share Dialog where someone shares one thing with others: a document, a board, a file or a folder. For inviting people to a whole workspace, use the [Team members](https://www.youj.dev/docs/blocks/billing-and-team#team-members) block; for an ordinary short task in a modal, a [Dialog](https://www.youj.dev/docs/components/dialog).

It is a component with a data contract, not a page: you own the list of people, so each handler updates your data and the dialog shows what you pass back.

```tsx
'use client'

import { useState } from 'react'
import { Button, ShareDialog, type SharePerson } from '@youj/react'

export function ShareRoadmap({ initial }: { initial: SharePerson[] }) {
  const [people, setPeople] = useState(initial)

return (
    <ShareDialog
      trigger={<Button variant="outline">Share</Button>}
      resource="Q3 roadmap"
      link="https://acme.test/docs/q3-roadmap"
      organization="Acme"
      people={people}
      suggestions={directory}
      onInvite={async ({ recipients, role, message }) => {
        const invited = await api.invite(recipients, role, message)
        setPeople((current) => [...current, ...invited])
      }}
      onRoleChange={async (person, role) => {
        await api.setRole(person.id, role)
        setPeople((current) => current.map((p) => (p.id === person.id ? { ...p, role } : p)))
      }}
      onRemove={async (person) => {
        await api.remove(person.id)
        setPeople((current) => current.filter((p) => p.id !== person.id))
      }}
      onAccessChange={(access) => api.setAccess(access)}
    />
  )
}
```

Every handler may return a promise. Resolve and update `people`; reject with an `Error` and its message shows next to the action, with the dialog still open. Roles default to Viewer, Commenter and Editor; pass `roles` for your own (`{ value, label }`). Pass `loading` while the list is on its way and the people area shows skeleton rows in the same space.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `trigger` | `ReactElement` |  | The element that opens the dialog, pressed to open it. |
| `resource` (required) | `string` |  | The name of what is shared; it's the dialog's title. |
| `link` (required) | `string` |  | The address `Copy link` puts on the clipboard. |
| `roles` | `ShareRole[]` |  | Default: Viewer, Commenter and Editor. |
| `defaultInviteRole` | `string` |  | The role the invite starts on. Default: the first role. |
| `people` (required) | `SharePerson[]` |  | Everyone with access, the owner and pending invitations included. |
| `loading` | `boolean` |  | The list is on its way: skeleton rows instead of people. |
| `suggestions` | `ShareSuggestion[]` | `[]` | People and groups the invite field offers. Those already in `people` are left out. |
| `organization` | `string` |  | The organization's name; it adds `Anyone at …` to general access. |
| `preview` | `SharePreview` |  | Shows the thing being shared as a card above the invite field. |
| `accessLayout` | `'select' \| 'switches'` | `'select'` | How general access is laid out. `select` (default): one menu for who can open the link, with a role beside it. `switches`: compact rows with a Switch each, the invite role on the "Only people invited" row, and no message field. |
| `access` | `ShareAccess` |  |  |
| `defaultAccess` | `ShareAccess` | `{ scope: 'restricted', role: 'viewer' }` |  |
| `onAccessChange` | `(access: ShareAccess) => Promise<unknown> \| unknown` |  | Called when someone changes general access; resolve to apply it. Rejecting keeps the old value and shows the message. |
| `readOnly` | `boolean` |  | The viewer may look but not change anything: no invite field, no role or access selects, no remove. Copy link stays. |
| `onInvite` | `(invite: ShareInvite) => Promise<unknown> \| unknown` |  | Sends the invitation; resolve when it's out and add the people to `people`. Reject to show the message and keep the chips. |
| `onRoleChange` | `(person: SharePerson, role: string) => Promise<unknown> \| unknown` |  |  |
| `onRemove` | `(person: SharePerson) => Promise<unknown> \| unknown` |  | Removes someone's access. |
| `onResend` | `(person: SharePerson) => Promise<unknown> \| unknown` |  |  |
| `onCancelInvite` | `(person: SharePerson) => Promise<unknown> \| unknown` | ``onRemove`` | Cancels a pending invitation. |
| `onCopyLink` | `() => void` |  | Called after the link was copied. |
| `className` | `string` |  |  |

#### Invite field

Type an address and press Enter or a comma (a semicolon works too); a pasted list is split into one chip each. Suggestions open on focus and filter as you type; people already in `people` are left out, and a group suggestion (one with `members`) shows its size. An address that isn't valid, or belongs to someone who already has access, stays as a danger chip with its reason and blocks Send until it is removed. Backspace on an empty field takes the last chip back. Send is an [Async Button](https://www.youj.dev/docs/components/button#async-button): `onInvite` receives `{ recipients, role, message }`, and on success the chips and message clear.

#### Data attributes

The preview card is `share-dialog-preview`. The invite, people and general access areas carry `data-slot` values `share-dialog-invite`, `share-dialog-people` and `share-dialog-access`; the chip field is `share-dialog-recipients`, and an invalid chip carries `data-invalid`.

### Labels

Every string is a core label (`shareDialog…`) in every built-in language, so the provider's `locale` or `labels` (see [Internationalization](https://www.youj.dev/docs/guides/i18n)) rewrites them. The roles' names are labels too (`shareDialogViewer`, `shareDialogCommenter`, `shareDialogEditor`); your own `roles` bring their own names. The organization, the resource and people's names are yours and arrive inside the sentences.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open and close |  |  | the dialog’s own rise and scrim, as any Dialog |
| A person added or removed | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | their row fades into its slot and the rows below glide |
| Send and Copy link |  |  | the Async Button’s pending, success and error states |

**Reduced motion:** Rows appear and leave at once and the buttons change without morphing; every message is still shown and announced.

### Accessibility

- The dialog is named by its title (`Share “<resource>”`) and focus opens in the invite field, so people can type straight away. In `readOnly`, where there's no field, focus starts on the first control as in any dialog.
- The invite field is an ARIA combobox over a listbox of suggestions: ArrowDown and ArrowUp move through them, Enter chooses, and Escape closes the list before a second Escape closes the dialog. Each chip's remove button is named after its person (`Remove Ada`).
- An invalid chip says why in text (read with the chip) and in an alert under the field, which the field points to with `aria-describedby` and `aria-invalid`.
- The people list is a named list inside a fixed-height scroll region; each role select is named after its person (`Role for Grace Hopper`) and each icon button says what it does and to whom (`Cancel invitation for Alan Turing`).
- While loading, the area is `aria-busy` and says `Loading people…`.
- A polite live region announces invitations sent, access removed, a role changed, general access changed and the link copied. A failure is an alert on the row, setting or button it belongs to.

---

# Export Dialog

> Choose a date range, a format and the columns, see what the export holds, then run it and watch it finish or arrive by email.

Source: https://www.youj.dev/docs/components/export-dialog

## Examples

### Payments export

```tsx
'use client'

import { differenceInCalendarDays } from 'date-fns'
import { DownloadIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { ExportDialog, type ExportRequest } from '@youj/react/date'

const COLUMNS = [
  { id: 'id', label: 'Payment ID' },
  { id: 'created', label: 'Created' },
  { id: 'customer', label: 'Customer' },
  { id: 'email', label: 'Email' },
  { id: 'description', label: 'Description' },
  { id: 'amount', label: 'Amount' },
  { id: 'fee', label: 'Fee' },
  { id: 'net', label: 'Net' },
  { id: 'currency', label: 'Currency' },
  { id: 'status', label: 'Status' },
  { id: 'method', label: 'Payment method' },
  { id: 'refunded', label: 'Refunded' },
]

const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))

// Stands in for a count query on your API: about 59 payments a day, 44 euros each.
async function paymentsSummary({ from, to }: ExportRequest) {
  await wait(450)
  const count = Math.round((differenceInCalendarDays(to, from) + 1) * 58.9)
  return { count, total: new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }).format(count * 44.3) }
}

export default function ExportDialogDemo() {
  return (
    <ExportDialog
      title="Export payments"
      trigger={
        <Button variant="outline">
          <DownloadIcon />
          Export
        </Button>
      }
      columns={COLUMNS}
      summary={paymentsSummary}
      countLabel={(count) => `${count.toLocaleString('en-US')} payments`}
      // Stands in for the request that builds the file.
      onExport={() => wait(1200)}
    />
  )
}
```

A payments export: a summary that follows the range, the ranges with their days, and the file's options.

The summary at the top says what the choice holds ("412 payments", "€18,240") and which days. It is a polite status region: when you pick another range it keeps the old figures, dims them while your `summary` function answers, and announces the new ones. Each range in the list shows the days it stands for, computed from today, so "Last 7 days" reads "Sep 23 – 29" and can be checked at a glance.

Export is an [Async Button](https://www.youj.dev/docs/components/button#async-button): it works, then says Done, or Failed with the reason under it. While it works the choices are locked, and changing any of them afterwards clears the outcome.

### Large export, emailed

```tsx
'use client'

import { differenceInCalendarDays } from 'date-fns'
import { DownloadIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { ExportDialog, type ExportRequest } from '@youj/react/date'

const COLUMNS = [
  { id: 'id', label: 'Payment ID' },
  { id: 'created', label: 'Created' },
  { id: 'customer', label: 'Customer' },
  { id: 'amount', label: 'Amount' },
  { id: 'status', label: 'Status' },
  { id: 'method', label: 'Payment method' },
]

const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))

async function paymentsSummary({ from, to }: ExportRequest) {
  await wait(450)
  const count = Math.round((differenceInCalendarDays(to, from) + 1) * 58.9)
  return { count, total: new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }).format(count * 44.3) }
}

export default function ExportDialogEmailed() {
  return (
    <ExportDialog
      title="Export payments"
      trigger={
        <Button variant="outline">
          <DownloadIcon />
          Export a year
        </Button>
      }
      columns={COLUMNS}
      presets={['last30Days', 'lastMonth', 'yearToDate']}
      defaultValue={{ period: 'yearToDate' }}
      formats={[
        { value: 'csv', label: 'CSV' },
        { value: 'xlsx', label: 'XLSX' },
      ]}
      summary={paymentsSummary}
      countLabel={(count) => `${count.toLocaleString('en-US')} payments`}
      // Too much to build while the dialog waits: answer with `emailed` and the dialog says it will arrive by email.
      onExport={async ({ from, to }) => {
        await wait(900)
        return differenceInCalendarDays(to, from) > 90 ? { emailed: true, email: 'finance@northwind.example' } : undefined
      }}
    />
  )
}
```

A year of payments is too much to build while the dialog waits.

When `onExport` resolves `{ emailed: true }` the button says Queued and the dialog says "We’ll email it to you when it’s ready", naming the address when you pass `email`. The note is a polite status region, so it is read out. Nothing else changes: the person can close the dialog, and the file arrives where you said it would.

### Custom range

```tsx
'use client'

import { useState } from 'react'
import { differenceInCalendarDays, startOfDay, subDays } from 'date-fns'
import { DownloadIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { ExportDialog, type ExportDialogValue, type ExportRequest } from '@youj/react/date'

const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))

export default function ExportDialogCustom() {
  const today = startOfDay(new Date())
  // The app owns the choice, so the dialog opens on the range it was left on.
  const [value, setValue] = useState<ExportDialogValue>({
    period: 'custom',
    customRange: { from: subDays(today, 20), to: subDays(today, 6) },
    format: 'csv',
    timeZone: 'local',
    columns: COLUMNS.map((column) => column.id),
  })
  return (
    <ExportDialog
      title="Export payments"
      trigger={
        <Button variant="outline">
          <DownloadIcon />
          Export a custom range
        </Button>
      }
      columns={COLUMNS}
      value={value}
      onValueChange={setValue}
      summary={paymentsSummary}
      countLabel={(count) => `${count.toLocaleString('en-US')} payments`}
      onExport={() => wait(1200)}
    />
  )
}
```

Custom opens the Date Range Picker inline, and the dialog grows to fit it.

Choosing Custom reveals the picker under its row, with a smooth height change and no scroll box: a form that scrolls hides its last field. Until both ends are chosen the summary asks for them and Export stays off. This example keeps the choice in the app (`value` and `onValueChange`), so the dialog opens on the range it was left on.

## Installation & usage

```bash
pnpm add @youj/react date-fns react-day-picker
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add export-dialog
```

It brings `async-button`, `button`, `checkbox`, `collapse`, `date-range-picker`, `dialog`, `icon-chevron-down`, `popover`, `radio-group`, `segmented-control`, `select`, `use-controllable-state`, `use-now`, `youj-core`, `youj-labels-export-dialog`, `youj-presets`, `youj-ui-core` with it.

The copy is 50 registry items, about 13,000 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `calendar`, `checkbox`, `collapse`, `date-picker`, `date-range-picker`, `dialog`, `field` and 26 more.

Use an Export Dialog when a person leaves a list or report with a file: it asks the three questions an export needs (which days, which format, which columns) in one place and shows the result of the choice before anything runs. For a dialog of your own content use a [Dialog](https://www.youj.dev/docs/components/dialog); for the range field alone, a [Date Range Picker](https://www.youj.dev/docs/components/date-range-picker).

```tsx
'use client'

import { Button } from '@youj/react'
import { ExportDialog } from '@youj/react/date'

const COLUMNS = [
  { id: 'id', label: 'Payment ID' },
  { id: 'amount', label: 'Amount' },
  { id: 'status', label: 'Status' },
]

export function ExportPayments() {
  return (
    <ExportDialog
      title="Export payments"
      trigger={<Button variant="outline">Export</Button>}
      columns={COLUMNS}
      summary={async ({ from, to }) => {
        const { count, total } = await countPayments(from, to)
        return { count, total: formatEuros(total) }
      }}
      countLabel={(count) => `${count} payments`}
      onExport={async (request) => {
        const job = await startExport(request)
        return job.large ? { emailed: true, email: job.email } : undefined
      }}
    />
  )
}
```

`onExport` receives what was chosen: `{ period, from, to, format, timeZone, columns }`, with `from` and `to` as the first and last day (start of day, local time, both included). Resolve for done, resolve `{ emailed: true }` for an export that will arrive by email, and reject or throw for failed; the error's message is shown. `timeZone` is the value of the option chosen (`local` or `utc` by default): your export applies it.

`summary` gets the same request without waiting for the person to press anything, once when the dialog opens and again when the range or the time zone changes. A late answer to a range that was since left is dropped. Without `summary` the panel shows the days alone.

It lives in the date entry, `@youj/react/date`, with the Date Range Picker it is built on.

### Date ranges

`presets` is a list of ids (`today`, `yesterday`, `last7Days`, `last30Days`, `thisMonth`, `lastMonth`, `yearToDate`), shown in that order with the provider’s names for them. `custom={false}` leaves out Custom. The range behind each id is a pure function you can use yourself:

```ts
import { presetRange } from '@youj/react/date'

presetRange('last7Days', new Date(2026, 8, 29), 'en-US')
// { from: Sep 23, to: Sep 29, text: 'Sep 23 – 29' }
```

`text` is how the locale writes the range, with the year only when the range is not in the current one. The clock is the second argument, so a range never depends on when it runs: pass `now` to the dialog to fix it in tests and stories.

### Format, time zone and columns

`formats` is a list of `{ value, label }` (CSV, XLSX and JSON by default), shown as a select, and the first is chosen. `timeZones` is a pair, shown as a two-option switch: your local zone and UTC by default. `columns` is every column the file can hold, `{ id, label }`; the button next to Columns says "All 12", "8 of 12" or "None", and its popover has a checkbox per column with All and None above them. With no column chosen, Export is off.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the dialog is open (controlled). |
| `defaultOpen` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `trigger` | `ReactElement` |  | The element that opens it, rendered as the trigger: `trigger={<Button>Export</Button>}`. |
| `title` | `ReactNode` | `"Export data"` |  |
| `description` | `ReactNode` |  |  |
| `presets` | `('today' \| 'yesterday' \| 'last7Days' \| 'last30Days' \| 'thisMonth' \| 'lastMonth' \| 'yearToDate')[]` | `DEFAULT_PRESETS` | The date ranges offered, in order. |
| `custom` | `boolean` | `true` | Offer the Custom range. |
| `formats` | `ExportOption[]` | `DEFAULT_FORMATS` | The file formats. |
| `timeZones` | `readonly [ExportOption, ExportOption]` |  | The two time zones the switch offers. Default your local one and UTC. |
| `columns` (required) | `ExportColumn[]` |  | Every column the file can hold. |
| `value` | `ExportDialogValue` |  | The choice (controlled). |
| `defaultValue` | `Partial<ExportDialogValue>` |  | The choice at first (uncontrolled): the first preset, CSV, the first time zone and every column. |
| `onValueChange` | `(value: ExportDialogValue) => void` |  |  |
| `summary` | `(request: ExportRequest) => ExportSummary \| Promise<ExportSummary>` |  | What the chosen range holds, asked again when the range or the time zone changes. Without it the summary shows the period alone. |
| `countLabel` | `(count: number) => string` |  | The count line: `(n) => `${n} payments``. Default "412 rows", in the provider's language. |
| `onExport` (required) | `(request: ExportRequest) => ExportResult \| void \| Promise<ExportResult \| void>` |  | Runs the export. Resolve for done (or `{ emailed: true }` when it will arrive by email), reject or throw for failed. |
| `now` | `Date` |  | Today, for the presets. Default the moment it mounted in the browser (never read while rendering on the server). |
| `locale` | `string` |  | Default the provider's locale. |
| `className` | `string` |  |  |

#### Data attributes

The dialog carries `data-slot="export-dialog"`. The summary is `export-dialog-summary` and carries `data-yj-pending` while your `summary` function is answering. The columns button is `export-dialog-columns`. The rest are the [Dialog](https://www.youj.dev/docs/components/dialog)’s, the [Radio Group](https://www.youj.dev/docs/components/radio-group)’s, the [Select](https://www.youj.dev/docs/components/select)’s and the [Async Button](https://www.youj.dev/docs/components/button#async-button)’s own.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open |  |  | the dialog rises and fades in over its scrim, as every Dialog does |
| Custom range | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the picker’s row grows open and the dialog grows with it; choosing a preset folds it away |
| Summary updating | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the old figures dim while the new ones are asked for, then take their place |
| Outcome note | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | grows open under the options when an export is queued or fails |
| Export button |  |  | the Async Button’s pending, success and error states |

**Reduced motion:** The dialog and the picker’s row appear at once, the figures change without dimming and the note shows without growing.

### Accessibility

- Focus starts on the chosen date range. The ranges are a radio group named "Date range": the arrow keys move and choose, Tab goes on to the options. Each radio is named by its range and described by its days ("Last 7 days", "Sep 23 – 29").
- Choosing Custom does not move focus; Tab reaches the start and end fields, which are named "Start date" and "End date", and the calendar button opens the range picker.
- The summary is a `status` region, so a changed count, total or period is announced politely, and `aria-busy` while it is being asked for.
- The columns button is named by its row ("Columns") and its text ("All 12"); its popover is a labelled group of checkboxes, with the count repeated as a status line above them.
- The outcome is announced twice over: a queued export politely ("We’ll email it to you when it’s ready"), a failure assertively with its message. The Async Button announces working and done as it always does.
- While an export runs, the choices and Cancel are disabled, and Escape closes the dialog only when it is not running. On a touch screen the dialog is a bottom sheet, like every Dialog, and focus starts on the sheet so the keyboard stays down.

---

# Sheet

> Open settings, filters or details in a panel that slides from a screen edge.

Source: https://www.youj.dev/docs/components/sheet

## Examples

### Demo

```tsx
'use client'

import { useState, type FormEvent } from 'react'
import {
  Button,
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  Input,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  Sheet,
  SheetBody,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
  Switch,
} from '@youj/react'
import { SlidersIcon } from '@youj/icons'
import { IllustrationServerRack, LineGrid } from '@youj/illustrations'

const regions = { fra1: 'Frankfurt (fra1)', iad1: 'Washington, D.C. (iad1)', sfo1: 'San Francisco (sfo1)', hnd1: 'Tokyo (hnd1)' }

export default function SheetDemo() {
  const [open, setOpen] = useState(false)
  const [saving, setSaving] = useState(false)
  const [status, setStatus] = useState('Production · fra1')

function save(event: FormEvent) {
    event.preventDefault()
    setSaving(true)
    // Stands in for the request to your API.
    setTimeout(() => {
      setSaving(false)
      setOpen(false)
      setStatus('Settings saved · applies to the next deployment')
    }, 900)
  }

return (
    <div className="flex w-full max-w-sm items-center justify-between gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="flex min-w-0 flex-col">
        <span className="text-ui font-semibold text-fg">orion</span>
        <span role="status" className="truncate text-ui-sm text-fg-muted">
          {status}
        </span>
      </div>
      <Sheet open={open} onOpenChange={(next) => !saving && setOpen(next)}>
        <SheetTrigger render={<Button variant="outline" size="sm" />}>
          <SlidersIcon />
          Settings
        </SheetTrigger>
        <SheetContent>
          {/* The form wraps header, body and footer, so the footer's Save submits it. */}
          <form onSubmit={save} className="flex min-h-0 flex-1 flex-col">
            <SheetHeader>
              <SheetTitle>Project settings</SheetTitle>
              <SheetDescription>Changes apply to the next deployment.</SheetDescription>
            </SheetHeader>
            <SheetBody>
              {/* Decorative: with no title the scene is hidden from assistive tech. */}
              <div className="relative isolate grid shrink-0 place-items-center overflow-hidden rounded-lg border border-line py-2">
                <LineGrid gap={16} />
                <IllustrationServerRack unit={10} />
              </div>
              <FieldGroup>
                <Field>
                  <FieldLabel>Project name</FieldLabel>
                  <Input defaultValue="orion" readOnly={saving} />
                </Field>
                <Field>
                  <FieldLabel>Build command</FieldLabel>
                  <Input defaultValue="pnpm build" readOnly={saving} className="font-mono" />
                  <FieldDescription>Runs in the project root after install.</FieldDescription>
                </Field>
                <Field>
                  <FieldLabel>Function region</FieldLabel>
                  <Select items={regions} defaultValue="fra1">
                    <SelectTrigger className="w-full">
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      {Object.entries(regions).map(([value, label]) => (
                        <SelectItem key={value} value={value}>
                          {label}
                        </SelectItem>
                      ))}
                    </SelectContent>
                  </Select>
                </Field>
                <Field orientation="horizontal">
                  <FieldContent>
                    <FieldLabel>Preview comments</FieldLabel>
                    <FieldDescription>Reviewers can comment on preview deployments.</FieldDescription>
                  </FieldContent>
                  <Switch defaultChecked />
                </Field>
                <Field orientation="horizontal">
                  <FieldContent>
                    <FieldLabel>Protect previews</FieldLabel>
                    <FieldDescription>Only members can open preview links.</FieldDescription>
                  </FieldContent>
                  <Switch />
                </Field>
              </FieldGroup>
            </SheetBody>
            <SheetFooter>
              <SheetClose render={<Button variant="outline" disabled={saving} />}>Cancel</SheetClose>
              <Button type="submit" loading={saving} loadingLabel="Saving">
                Save changes
              </Button>
            </SheetFooter>
          </form>
        </SheetContent>
      </Sheet>
    </div>
  )
}
```

A project card whose Settings button opens a side sheet with a form that saves after a moment.

### Sides

```tsx
'use client'

import { IllustrationMap } from '@youj/illustrations'
import { Button, Sheet, SheetBody, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger, type SheetSide } from '@youj/react'

// `start` and `end` follow the writing direction: in a right-to-left page they swap edges.
const SIDES: { side: SheetSide; label: string }[] = [
  { side: 'top', label: 'Top' },
  { side: 'bottom', label: 'Bottom' },
  { side: 'left', label: 'Left' },
  { side: 'right', label: 'Right' },
  { side: 'start', label: 'Start' },
  { side: 'end', label: 'End' },
]

export default function SheetSides() {
  return (
    <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">
      {SIDES.map(({ side, label }) => (
        <Sheet key={side}>
          <SheetTrigger render={<Button variant="outline" className="w-28" />}>{label}</SheetTrigger>
          <SheetContent side={side}>
            <SheetHeader>
              <SheetTitle>{label}</SheetTitle>
              <SheetDescription>
                Slides in from the {side === 'start' || side === 'end' ? `${side} edge of the writing direction` : `${side} edge`} and
                leaves the way it came.
              </SheetDescription>
            </SheetHeader>
            <SheetBody>
              <div className="flex items-center gap-4">
                {/* Decorative: with no title the scene is hidden from assistive tech. */}
                <IllustrationMap unit={9} className="-my-4 -mx-2 shrink-0" />
                <p className="text-ui text-fg-muted">Press Escape, the scrim or × to close it.</p>
              </div>
            </SheetBody>
          </SheetContent>
        </Sheet>
      ))}
    </div>
  )
}
```

A sheet for each side, from top to end.

`side` picks the edge the sheet slides from: `top`, `right`, `bottom`, `left`, `start` or `end`. The default is `end`. Side sheets fill the height and are up to 24rem wide, leaving a 2.5rem strip of the page visible on a phone. Top and bottom sheets fill the width and stop at 85% of the height.

`start` and `end` follow the writing direction: in a right-to-left page, an `end` sheet comes in from the left. Prefer them to `left` and `right` for anything that follows the reading order, such as navigation or details, and keep the physical sides for things tied to the screen itself.

### Floating

```tsx
'use client'

import { useState } from 'react'
import { BanknoteIcon, CalendarCheckIcon, CircleDashedIcon, CircleUserIcon } from '@youj/icons'
import { IllustrationHandshake } from '@youj/illustrations'
import {
  Button,
  PropertyDate,
  PropertyList,
  PropertyListItem,
  PropertyMoney,
  PropertyPerson,
  PropertyStatus,
  ItemPager,
  Sheet,
  SheetBody,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from '@youj/react'

const deals = [
  { company: 'Orrery Labs', email: 'partnerships@orrerylabs.com', owner: 'Noor Haddad', stage: 'Proposal', tone: 'warning', closes: '2026-11-30', value: 324_000 },
  { company: 'Fernhill Bank', email: 'vendors@fernhillbank.com', owner: 'Tomás Reyes', stage: 'Negotiation', tone: 'accent', closes: '2026-12-12', value: 118_500 },
  { company: 'Quayside Foods', email: 'it@quaysidefoods.com', owner: 'Mei Tanaka', stage: 'Qualified', tone: 'accent', closes: '2027-01-20', value: 46_000 },
]

export default function FloatingSheet() {
  const [index, setIndex] = useState(0)
  const deal = deals[index]!
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Open deal</SheetTrigger>
      <SheetContent variant="floating" backdrop="blur">
        <SheetHeader>
          <ItemPager index={index} total={deals.length} onIndexChange={setIndex} shortcuts="global" className="-ms-1 mb-2" />
          <SheetTitle>{deal.company}</SheetTitle>
          <SheetDescription>{deal.email}</SheetDescription>
        </SheetHeader>
        <SheetBody>
          {/* Decorative: with no title the scene is hidden from assistive tech. */}
          <div className="grid shrink-0 place-items-center rounded-lg py-1">
            <IllustrationHandshake unit={10} />
          </div>
          <PropertyList>
            <PropertyListItem icon={<CircleUserIcon />} label="Owner">
              <PropertyPerson name={deal.owner} />
            </PropertyListItem>
            <PropertyListItem icon={<CircleDashedIcon />} label="Stage">
              <PropertyStatus tone={deal.tone}>{deal.stage}</PropertyStatus>
            </PropertyListItem>
            <PropertyListItem icon={<CalendarCheckIcon />} label="Closes">
              <PropertyDate value={deal.closes} />
            </PropertyListItem>
            <PropertyListItem icon={<BanknoteIcon />} label="Value">
              <PropertyMoney value={deal.value} />
            </PropertyListItem>
          </PropertyList>
        </SheetBody>
      </SheetContent>
    </Sheet>
  )
}
```

A floating sheet for a record, with a Item Pager and a Property List.

`variant="floating"` lifts the sheet off its edge: it sits 12px in from every side, takes the theme's panel radius and the largest shadow, and reads as a card over the page rather than a strip of it. Use it for a record opened from a list, where the list should stay in view behind it. `backdrop="blur"` also blurs the page a little under a thinner scrim. Both work on every side; side sheets are up to 28rem wide, top and bottom ones a centered 42rem column.

The [Item Pager](https://www.youj.dev/docs/components/item-pager) and [Property List](https://www.youj.dev/docs/components/property-list) in this preview are the pieces a record drawer is built from. On touch a floating sheet becomes the bottom sheet a Dialog becomes there (see Touch below).

### Scrolling content

```tsx
'use client'

import { Badge, Button, Sheet, SheetBody, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger } from '@youj/react'
import { TerminalIcon } from '@youj/icons'
import { IllustrationDeploy } from '@youj/illustrations'

const LOG = [
  ['0.0s', 'Cloning github.com/acme/orion (branch: main, commit: 4f2a91c)'],
  ['0.4s', 'Restored build cache from the previous deployment'],
  ['0.6s', 'Running "pnpm install --frozen-lockfile"'],
  ['6.1s', 'Packages: +312, done in 5.4s'],
  ['6.2s', 'Running "pnpm build"'],
  ['6.9s', '▲ Next.js 16.3.6'],
  ['7.0s', 'Creating an optimized production build…'],
  ['14.8s', '✓ Compiled successfully'],
  ['15.1s', 'Linting and checking validity of types…'],
  ['19.6s', 'Collecting page data…'],
  ['21.2s', 'Generating static pages (0/48)'],
  ['23.9s', 'Generating static pages (48/48)'],
  ['24.3s', 'Finalizing page optimization…'],
  ['24.9s', 'Route (app): 48 routes, 31 static, 17 dynamic'],
  ['25.2s', 'First Load JS shared by all: 102 kB'],
  ['25.6s', 'Build completed in 19.4s'],
  ['26.0s', 'Uploading 1.4 MB of static assets'],
  ['27.3s', 'Deploying 17 functions to fra1'],
  ['31.8s', 'Assigning orion.acme.dev'],
  ['32.0s', 'Deployment ready'],
]

export default function SheetLogs() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>
        <TerminalIcon />
        Build logs
      </SheetTrigger>
      <SheetContent side="bottom" className="max-h-[45dvh]">
        <SheetHeader className="flex-row items-center gap-4">
          {/* Decorative: with no title the scene is hidden from assistive tech. */}
          <IllustrationDeploy unit={7} className="-my-4 -mx-2 shrink-0" />
          <div className="flex min-w-0 flex-col gap-1.5">
            <div className="flex items-center gap-2">
              <SheetTitle>Build logs</SheetTitle>
              <Badge variant="success">Ready</Badge>
            </div>
            <SheetDescription>orion · main · 4f2a91c, built in 32s</SheetDescription>
          </div>
        </SheetHeader>
        {/* Nothing in the body is focusable, so once it overflows it becomes a tab stop and scrolls with the keyboard. */}
        <SheetBody role="region" aria-label="Log output" className="gap-0 font-mono text-ui-sm">
          {LOG.map(([time, line]) => (
            <p key={time} className="flex gap-4 py-0.5">
              <span className="w-10 shrink-0 text-end text-fg-muted tabular-nums">{time}</span>
              <span className="text-fg">{line}</span>
            </p>
          ))}
        </SheetBody>
      </SheetContent>
    </Sheet>
  )
}
```

A sheet of logs that scrolls in its body while the header and footer stay put.

Content taller than the sheet scrolls inside `SheetBody`, while the header and footer hold still. If nothing in the body can take focus, the body makes itself a tab stop once it overflows, so a keyboard can still scroll it. Give it a `role` and an `aria-label` when it's a region worth naming, as the log below does.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add sheet
```

It brings `button`, `dialog`, `presentation`, `youj-core`, `youj-labels-sheet`, `youj-presets`, `youj-ui-core` with it.

The copy is 14 registry items, about 8,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `dialog`, `icon-engine`, `icon-loader-ring`, `presentation`, `spinner`.

Use Sheet for settings, filters, row details or logs that need more room than a [Dialog](https://www.youj.dev/docs/components/dialog). It is modal, so keep it to one task. Use a [Popover](https://www.youj.dev/docs/components/popover) for quick choices anchored to a button, or a [Drawer](https://www.youj.dev/docs/components/drawer) for swipe dismissal.

```tsx
import {
  Button,
  Sheet,
  SheetBody,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from '@youj/react'

export function FiltersSheet() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Filters</SheetTrigger>
      <SheetContent side="end">
        <SheetHeader>
          <SheetTitle>Filters</SheetTitle>
          <SheetDescription>Narrow the deployments list.</SheetDescription>
        </SheetHeader>
        <SheetBody>
          <DeploymentFilters />
        </SheetBody>
        <SheetFooter>
          <SheetClose render={<Button variant="outline" />}>Cancel</SheetClose>
          <Button>Apply</Button>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  )
}
```

A sheet is a column: `SheetHeader` and `SheetFooter` stay put while `SheetBody` scrolls between them. `SheetContent` renders the portal, the scrim and the panel, with a × button in its top corner. `Sheet` is Base UI's Dialog root, so `open`, `onOpenChange` and `modal` work as Base UI documents them.

For a form, wrap the header, body and footer in the `<form>` and give it `flex min-h-0 flex-1 flex-col`, so the body still scrolls and the footer's submit button belongs to the form. The Demo story does this, and it ignores close requests while the save runs.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

`SheetContent` adds four props to Base UI's `Dialog.Popup`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left' \| 'start' \| 'end'` | `'end'` | The edge it slides from. `start` / `end` follow the writing direction. |
| `showCloseButton` | `boolean` | `true` | Renders the × button in the top corner. |
| `variant` | `'docked' \| 'floating'` | `'docked'` | `docked` sits flush on its edge. `floating` is inset from every edge, rounded and raised, and a bottom sheet on touch. |
| `backdrop` | `'dim' \| 'blur'` | `'dim'` | The page behind: `dim` washes it with the scrim, `blur` also blurs it a little. |

Also takes the props of `SheetPrimitive.Popup.Props`.

`Sheet`, `SheetTrigger`, `SheetClose`, `SheetTitle` and `SheetDescription` pass their props through to Base UI's Dialog parts. `SheetHeader`, `SheetBody` and `SheetFooter` are `div`s.

### Touch

On a touch device a side sheet covers the screen's full width, up to 28rem on a tablet, so on a phone it reads as a page laid over the app rather than a panel with a sliver of page beside it. The × gets a 44px target, the content clears the notch and the home indicator, and the footer's actions share its width at 44px tall.

A floating sheet is different on touch: it becomes the bottom sheet a [Dialog](https://www.youj.dev/docs/components/dialog) becomes there, with a grab handle, its body scrolling up to 90% of the screen, and pulled down to dismiss. Its header, body and footer keep their layout.

A docked sheet doesn't follow the finger. For a panel people pull away, which is what a bottom sheet on a phone usually wants, use [Drawer](https://www.youj.dev/docs/components/drawer). A [Dialog](https://www.youj.dev/docs/components/dialog) already becomes a pull-to-dismiss bottom sheet on touch.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | slides fully in from its edge (`yj-sheet-*`) |
| Exit | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | slides back off the same edge |
| Scrim in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | opacity (`yj-backdrop`) |
| Scrim out | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |

**Reduced motion:** The sheet and its scrim appear and disappear at once, with no slide.

A floating sheet travels past its 12px gap too (`--yj-sheet-gap`), so nothing of it is left at the edge. With `backdrop="blur"` the blur is static and fades in with the scrim's opacity.

Only `transform` moves, so the slide never triggers layout. It runs on a CSS transition, so closing a sheet halfway in sends it back from where it is.

#### Reduced motion

The sheet is in place the moment it opens and gone the moment it closes, and the scrim does the same. Nothing else changes: focus, scrolling and dismissal behave exactly as they do with motion.

### Accessibility

- A sheet is a modal dialog: `role="dialog"`, named by `SheetTitle` and described by `SheetDescription`. Always render a title.
- Focus moves to the first control in the sheet when it opens, and stays inside it until it closes. The page behind is hidden from assistive technology and doesn't scroll.
- Escape, a press on the scrim and the × button (named "Close") close it, and focus returns to the trigger.
- The scrolling body becomes a tab stop only when it overflows with nothing focusable inside, so it never adds a pointless stop.

---

# Drawer

> Open a panel from a screen edge and swipe it away.

Source: https://www.youj.dev/docs/components/drawer

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  Badge,
  Button,
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@youj/react'
import { CopyIcon, ExternalLinkIcon, GitBranchIcon, RefreshIcon, RocketIcon, TrashIcon } from '@youj/icons'
import { IllustrationCloud } from '@youj/illustrations'

const ACTIONS = [
  { label: 'Promote to production', Icon: RocketIcon },
  { label: 'Redeploy', Icon: RefreshIcon },
  { label: 'Copy URL', Icon: CopyIcon },
  { label: 'Open deployment', Icon: ExternalLinkIcon },
]

export default function DrawerDemo() {
  const [last, setLast] = useState('')

return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex items-center gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
          <span className="truncate font-mono text-ui-sm text-fg">orion-git-feat-search.acme.dev</span>
          <span className="flex items-center gap-1.5 text-ui-sm text-fg-muted">
            <GitBranchIcon size={14} /> feat/search · 4m ago
          </span>
        </div>
        {/* A bottom sheet: swipe it down, or drag the handle, to dismiss it. */}
        <Drawer>
          <DrawerTrigger render={<Button variant="outline" size="sm" />}>Actions</DrawerTrigger>
          <DrawerContent>
            <DrawerHeader className="flex-row items-center gap-4">
              {/* Decorative: with no title the scene is hidden from assistive tech. */}
              <IllustrationCloud unit={9} className="-my-4 -mx-2 shrink-0" />
              <div className="flex min-w-0 flex-col gap-1">
                <div className="flex items-center gap-2">
                  <DrawerTitle>Preview deployment</DrawerTitle>
                  <Badge variant="secondary">Ready</Badge>
                </div>
                <DrawerDescription>feat/search, built in 41s from 3f9c2a1.</DrawerDescription>
              </div>
            </DrawerHeader>
            <div className="flex flex-col px-3">
              {ACTIONS.map(({ label, Icon }) => (
                <DrawerClose
                  key={label}
                  onClick={() => setLast(label)}
                  render={<Button variant="ghost" className="h-control-lg justify-start gap-3 px-2 text-ui-lg text-fg" />}
                >
                  <Icon className="text-fg-muted" />
                  {label}
                </DrawerClose>
              ))}
            </div>
            <DrawerFooter>
              <DrawerClose onClick={() => setLast('Delete deployment')} render={<Button variant="danger" className="h-control-lg" />}>
                <TrashIcon />
                Delete deployment
              </DrawerClose>
            </DrawerFooter>
          </DrawerContent>
        </Drawer>
      </div>
      <p role="status" className="h-4 text-ui-sm text-fg-muted">
        {last && `Chose “${last}”`}
      </p>
    </div>
  )
}
```

A bottom drawer of deployment actions that can be swiped down or dismissed by its handle.

### Swiping

```tsx
'use client'

import { Button, Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, DrawerTrigger } from '@youj/react'
import { ActivityIcon } from '@youj/icons'
import { IllustrationCommunity, LineGrid } from '@youj/illustrations'

const PEOPLE = ['Ana Lima', 'Kenji Sato', 'Priya Raman', 'Jonas Weber']
const EVENTS = ['deployed feat/search', 'commented on a preview', 'promoted 4f2a91c to production', 'rolled back production']

// A day of activity: long enough to scroll inside the drawer.
const ACTIVITY = Array.from({ length: 24 }, (_, i) => ({
  id: i,
  who: PEOPLE[i % PEOPLE.length],
  what: EVENTS[(i * 3) % EVENTS.length],
  when: `${i * 7 + 2}m ago`,
}))

export default function DrawerActivity() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline" />}>
        <ActivityIcon />
        Activity
      </DrawerTrigger>
      {/* Capped at 80% of the screen: the list scrolls inside, and a swipe down from its top still dismisses. */}
      <DrawerContent className="max-h-[80dvh]">
        <DrawerHeader>
          {/* Decorative: with no title the scene is hidden from assistive tech. */}
          <div className="relative isolate mb-2 grid place-items-center overflow-hidden rounded-lg border border-line py-1">
            <LineGrid gap={16} />
            <IllustrationCommunity unit={9} />
          </div>
          <DrawerTitle>Activity</DrawerTitle>
          <DrawerDescription>Everything that happened on orion today.</DrawerDescription>
        </DrawerHeader>
        <ul className="flex flex-col px-5 pb-5">
          {ACTIVITY.map((item) => (
            <li key={item.id} className="flex items-center justify-between gap-3 border-b border-line py-2.5 last:border-b-0">
              <span className="text-ui">
                <span className="font-medium text-fg">{item.who}</span> <span className="text-fg-muted">{item.what}</span>
              </span>
              <span className="shrink-0 text-ui-sm text-fg-muted tabular-nums">{item.when}</span>
            </li>
          ))}
        </ul>
      </DrawerContent>
    </Drawer>
  )
}
```

A drawer with a scrollable activity list that can be swiped away.

The panel tracks the finger as it's dragged toward its edge. Let go past the threshold and it leaves. A flick leaves faster than a slow drag, and a short drag springs back into place. The scrim thins as the panel is pulled away, so the page underneath shows through in proportion. With a mouse, drag the handle or the panel's chrome.

The panel bleeds 3rem past its edge, so pulling it the other way never opens a gap. Scrollable content scrolls first, and a swipe from the top of the list still dismisses, as in the preview.

### Directions

```tsx
'use client'

import {
  Button,
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
  type DrawerDirection,
} from '@youj/react'
import { ArrowDownIcon, ArrowLeftIcon, ArrowRightIcon, ArrowUpIcon } from '@youj/icons'
import { IllustrationCompass } from '@youj/illustrations'

// `swipeDirection` is the way the drawer leaves: a "down" drawer sits on the bottom edge.
const DIRECTIONS: { direction: DrawerDirection; edge: string; Icon: typeof ArrowDownIcon }[] = [
  { direction: 'down', edge: 'bottom', Icon: ArrowDownIcon },
  { direction: 'up', edge: 'top', Icon: ArrowUpIcon },
  { direction: 'left', edge: 'left', Icon: ArrowLeftIcon },
  { direction: 'right', edge: 'right', Icon: ArrowRightIcon },
]

export default function DrawerDirections() {
  return (
    <div className="grid grid-cols-2 gap-2">
      {DIRECTIONS.map(({ direction, edge, Icon }) => (
        <Drawer key={direction} swipeDirection={direction}>
          <DrawerTrigger render={<Button variant="outline" className="w-32" />}>
            <Icon />
            Swipe {direction}
          </DrawerTrigger>
          <DrawerContent>
            <DrawerHeader>
              <DrawerTitle>From the {edge} edge</DrawerTitle>
              <DrawerDescription>Swipe it {direction} to dismiss it, or press Escape.</DrawerDescription>
            </DrawerHeader>
            {/* Decorative: with no title the scene is hidden from assistive tech. */}
            <IllustrationCompass unit={9} className="mx-auto" />
            <DrawerFooter>
              <DrawerClose render={<Button variant="outline" />}>Close</DrawerClose>
            </DrawerFooter>
          </DrawerContent>
        </Drawer>
      ))}
    </div>
  )
}
```

A drawer for each swipe direction.

`swipeDirection` is the direction that dismisses the drawer, so it also sets the edge the drawer sits on. `down`, the default, makes a bottom sheet. `up` hangs from the top, and `left` and `right` make side panels, which have no handle.

`showHandle={false}` removes the grab handle from a top or bottom drawer. Keep it when the drawer can be swiped, because it's the visible sign that it can.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add drawer
```

It brings `dialog`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

The copy is 13 registry items, about 8,000 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `dialog`, `icon-engine`, `icon-loader-ring`, `presentation`, `spinner`.

Use Drawer for action sheets, pickers and short forms on touch screens. Like [Sheet](https://www.youj.dev/docs/components/sheet), it is modal, with the addition of swipe dismissal. For mouse-driven layouts, consider a [Dialog](https://www.youj.dev/docs/components/dialog), Sheet or [Popover](https://www.youj.dev/docs/components/popover).

```tsx
import {
  Button,
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@youj/react'

export function DeploymentActions() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline" />}>Actions</DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Preview deployment</DrawerTitle>
          <DrawerDescription>feat/search, built in 41s.</DrawerDescription>
        </DrawerHeader>
        <DeploymentActionList />
        <DrawerFooter>
          <DrawerClose render={<Button variant="outline" />}>Cancel</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  )
}
```

`DrawerContent` renders the portal, the scrim, a viewport and the panel. A top or bottom drawer is a centered column up to 36rem wide, full width on a phone, with a grab handle. Its footer stacks actions at full width, as touch sheets do. `Drawer` is Base UI's Drawer root, so `open`, `onOpenChange`, `modal` and `swipeDirection` work as Base UI documents them.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

`DrawerContent` adds one prop to Base UI's `Drawer.Popup`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showHandle` | `boolean` | `true` | The grab handle on a top or bottom drawer. |

Also takes the props of `DrawerPrimitive.Popup.Props`.

`Drawer` sets `swipeDirection` to `down` by default and passes every other Base UI root prop through. `DrawerTrigger`, `DrawerClose`, `DrawerTitle` and `DrawerDescription` pass their props through to Base UI. `DrawerHeader` and `DrawerFooter` are `div`s.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | slides in from its edge (`yj-sheet-*`) |
| Exit | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | slides off its edge; a flick shortens it |
| Swipe |  | no transition while dragging | follows the finger exactly |
| Scrim in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | opacity (`yj-backdrop`) |
| Scrim out | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | thins with the swipe progress, and leaves faster after a flick |

**Reduced motion:** Opens and closes instantly. A swipe still tracks the finger, because that motion is the person's own, and a released swipe dismisses at once.

After a swipe, the exit duration is multiplied by the swipe's strength, a factor from 0.1 to 1 that Base UI derives from how fast the panel was released. A hard flick leaves sooner than a slow drag that is let go.

#### Reduced motion

The drawer appears and leaves without sliding, and the scrim with it. Dragging still moves the panel under the finger, because that movement is direct manipulation, not animation. Everything else, from focus to dismissal, is unchanged.

### Accessibility

- A drawer is a modal dialog: `role="dialog"`, named by `DrawerTitle` and described by `DrawerDescription`.
- Swiping is never the only way out. Escape, a press on the scrim and any `DrawerClose` close it too, and focus returns to the trigger.
- Focus moves into the drawer when it opens and is trapped there until it closes.
- The grab handle is decorative (`aria-hidden`). When the panel itself scrolls with nothing focusable inside, it becomes a tab stop so the keyboard can scroll it.

---

# Popover

> Show a small task or extra detail in a panel anchored to a control.

Source: https://www.youj.dev/docs/components/popover

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState, type FormEvent } from 'react'
import { motion } from 'motion/react'
import { useYouj } from '@youj/core'
import { MorphLabel, useMorphRoot } from '@youj/motion'
import { CheckIcon, LinkIcon, UserPlusIcon } from '@youj/icons'
import { IllustrationTeam } from '@youj/illustrations'
import {
  Avatar,
  AvatarFallback,
  Button,
  Input,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from '@youj/react'

const TEAM = [
  { name: 'Ana Lima', email: 'ana@youj.dev', role: 'Owner' },
  { name: 'Kenji Sato', email: 'kenji@youj.dev', role: 'Editor' },
]

const DEPLOYS = [
  { message: 'Stream search results from the edge', sha: '4f2a91c', age: '2m', ready: false },
  { message: 'Tighten cache headers on /docs', sha: '9b1e03d', age: '1h', ready: true },
  { message: 'New pricing page', sha: 'c7d42e8', age: '3h', ready: true },
  { message: 'Bump the build image', sha: '51aa6f2', age: '1d', ready: true },
  { message: 'OG images for the blog', sha: 'e08b7c1', age: '2d', ready: true },
  { message: 'Rotate the analytics key', sha: '2d9f4b0', age: '3d', ready: true },
]

const initials = (name: string) => name.split(/[\s@.]/).map((part) => part[0]).slice(0, 2).join('')

function CopyLink() {
  const k = useYouj()
  const morph = useMorphRoot(6)
  const [copied, setCopied] = useState(false)
  useEffect(() => {
    if (!copied) return
    // How long "Copied" holds comes from the motion tokens too.
    const timer = setTimeout(() => setCopied(false), k.ms('deliberate') * 3)
    return () => clearTimeout(timer)
  }, [copied, k])

return (
    <Button
      variant="outline"
      size="sm"
      render={<motion.button {...morph} />}
      className="overflow-hidden"
      onClick={() => navigator.clipboard?.writeText('https://youj.io/join/youj-web').then(() => setCopied(true))}
    >
      <MorphLabel value={copied ? 'copied' : 'copy'} contentClassName="gap-1.5">
        {copied ? (
          <>
            <CheckIcon trigger="mount" size={14} strokeWidth={2} /> Copied
          </>
        ) : (
          <>
            <LinkIcon size={14} /> Copy link
          </>
        )}
      </MorphLabel>
    </Button>
  )
}

export default function PopoverDemo() {
  const [people, setPeople] = useState(TEAM)

const invite = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault()
    const form = event.currentTarget
    const email = new FormData(form).get('email')?.toString().trim()
    if (!email) return
    setPeople((list) => [...list, { name: email, email, role: 'Invited' }])
    form.reset()
  }

return (
    <div className="h-[26rem] w-full max-w-lg overflow-hidden rounded-xl border border-line bg-surface shadow-xs">
      <div className="flex items-center justify-between gap-3 border-b border-line px-4 py-3">
        <div className="min-w-0">
          <p className="truncate text-ui font-medium text-fg">youj-web</p>
          <p className="truncate text-ui-sm text-fg-muted">Production · youj.io</p>
        </div>
        <Popover>
          <PopoverTrigger render={<Button variant="outline" size="sm" />}>
            <UserPlusIcon />
            Share
          </PopoverTrigger>
          <PopoverContent align="end" className="w-80">
            <div className="flex items-center gap-3">
              {/* Decorative: with no title the scene is hidden from assistive tech. */}
              <IllustrationTeam unit={7} className="-my-3 -mx-2 shrink-0" />
              <PopoverHeader>
                <PopoverTitle>Share youj-web</PopoverTitle>
                <PopoverDescription>Invite people by email, or send the link.</PopoverDescription>
              </PopoverHeader>
            </div>
            <form onSubmit={invite} className="flex gap-2">
              <Input name="email" type="email" required aria-label="Email address" placeholder="name@youj.dev" />
              <Button type="submit">Invite</Button>
            </form>
            <ul aria-label="People with access" className="flex flex-col gap-0.5">
              {people.map((person) => (
                <li key={person.email} className="flex items-center gap-2.5 py-1">
                  <Avatar size="sm">
                    <AvatarFallback>{initials(person.name)}</AvatarFallback>
                  </Avatar>
                  <span className="min-w-0 flex-1 truncate text-ui text-fg">{person.name}</span>
                  <span className="text-ui-sm text-fg-muted">{person.role}</span>
                </li>
              ))}
            </ul>
            <div className="-mx-4 flex items-center justify-between gap-3 border-t border-line px-4 pt-3">
              <span className="text-ui-sm text-fg-muted">Anyone on the team can view.</span>
              <CopyLink />
            </div>
          </PopoverContent>
        </Popover>
      </div>
      <ul aria-label="Recent deployments" className="divide-y divide-line">
        {DEPLOYS.map((deploy) => (
          <li key={deploy.sha} className="flex items-center gap-3 px-4 py-3">
            <span aria-hidden className={`size-2 shrink-0 rounded-full ${deploy.ready ? 'bg-success' : 'bg-warning'}`} />
            <span className="sr-only">{deploy.ready ? 'Ready:' : 'Building:'}</span>
            <span className="min-w-0 flex-1 truncate text-ui text-fg">{deploy.message}</span>
            <span className="font-mono text-ui-sm text-fg-muted">{deploy.sha}</span>
            <span className="w-14 text-end text-ui-sm text-fg-muted">{deploy.age}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

A project header with a Share button that opens a popover for inviting teammates, aligned to the end of the trigger.

### Placement

```tsx
'use client'

import { Button, Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger } from '@youj/react'

const SIDES = ['top', 'right', 'bottom', 'left'] as const

export default function PopoverPlacement() {
  return (
    <div className="grid grid-cols-2 gap-3">
      {SIDES.map((side) => (
        <Popover key={side}>
          <PopoverTrigger render={<Button variant="outline" className="w-28 capitalize" />}>{side}</PopoverTrigger>
          {/* It grows out of the edge that touches the trigger, and flips when that side runs out of room. */}
          <PopoverContent side={side} className="w-56">
            <PopoverHeader>
              <PopoverTitle className="capitalize">{side}</PopoverTitle>
              <PopoverDescription>The popup's origin follows the side it opens on.</PopoverDescription>
            </PopoverHeader>
          </PopoverContent>
        </Popover>
      ))}
    </div>
  )
}
```

One popover on each side of its trigger.

The popup opens on `side` (`bottom` by default) and aligns to the trigger with `align` (`center`). It sits `sideOffset` px away (6), keeps `collisionPadding` px from the viewport edge (8), and flips to the opposite side when it runs out of room. It always grows out of the edge that touches the trigger, including after a flip.

The popup is 18rem wide by default and never wider than the space available. Size it with `className`, as the share panel in the Demo story does with `w-80`.

### Open on hover

```tsx
'use client'

import { InfoIcon } from '@youj/icons'
import { Button, Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, Progress } from '@youj/react'

export default function PopoverInfotip() {
  return (
    <div className="w-full max-w-xs rounded-xl border border-line bg-surface p-4 shadow-xs">
      <div className="flex items-center gap-1">
        <span className="text-ui font-medium text-fg">Build minutes</span>
        <Popover>
          {/* Opens on hover as well as on press, so touch and keyboard users reach the same text. */}
          <PopoverTrigger openOnHover render={<Button variant="ghost" size="icon-xs" aria-label="About build minutes" />}>
            <InfoIcon />
          </PopoverTrigger>
          <PopoverContent side="top" className="w-64">
            <PopoverHeader>
              <PopoverTitle className="text-ui">How minutes are counted</PopoverTitle>
              <PopoverDescription>
                Every build counts from install to upload, rounded up to the minute. The allowance resets on the 1st.
              </PopoverDescription>
            </PopoverHeader>
          </PopoverContent>
        </Popover>
        <span className="ms-auto font-mono text-ui-sm text-fg-muted tabular-nums">1,240 / 6,000</span>
      </div>
      <Progress value={21} aria-label="Build minutes used" className="mt-3" />
    </div>
  )
}
```

An info icon that opens a popover on hover and on press.

An info icon that explains a figure is a popover, not a tooltip. `openOnHover` on the trigger opens it after a short rest (Base UI's `delay`, 300ms), and a press still opens it, so touch and keyboard users reach the same text. Opened with a press, it's a dialog like any other popover, and screen readers read its title and description.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add popover
```

It brings `presentation`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Popover for a small task or detail tied to a control, such as sharing, filters or a quick setting. The page stays usable by default. Use a [Dialog](https://www.youj.dev/docs/components/dialog) when the task must be completed or dismissed first. Use a [Tooltip](https://www.youj.dev/docs/components/tooltip) for a short visual label.

```tsx
import { Button, Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger } from '@youj/react'

export function SharePopover() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Share</PopoverTrigger>
      <PopoverContent align="end">
        <PopoverHeader>
          <PopoverTitle>Share youj-web</PopoverTitle>
          <PopoverDescription>Invite teammates by email.</PopoverDescription>
        </PopoverHeader>
        <InviteForm />
      </PopoverContent>
    </Popover>
  )
}
```

`PopoverTrigger` renders a button. Pass `render` to use your own [Button](https://www.youj.dev/docs/components/button) and keep its variants. `PopoverContent` brings the portal, the positioner and the popup in one part, so placement props go straight on it. `PopoverClose` closes the popover from inside, for a Done or Cancel button.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### PopoverContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | Where the portal renders. Default: the provider's portal container, else document.body. |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |

`Popover` takes Base UI's root props (`open`, `defaultOpen`, `onOpenChange`, `modal`), and `PopoverTrigger` takes the trigger's (`openOnHover`, `delay`, `closeDelay`, `render`). `PopoverHeader`, `PopoverTitle`, `PopoverDescription` and `PopoverClose` add no props of their own.

### Touch

On a touch device the popover is a bottom sheet. It rises from the bottom of the screen over a scrim, spans the screen's width and has a grab handle. Pull it down, tap outside it or press Escape to close it, and focus returns to the trigger. Your content and its horizontal padding stay the same; placement props (`side`, `align`, offsets) don't apply, since a finger would cover anything anchored to the trigger. A field inside raises the on-screen keyboard, and the sheet moves up to stay above it.

On touch, `Popover` is modal unless you pass `modal`, so the page under the sheet doesn't scroll. A control inside that handles its own drag, such as a slider or a canvas, can carry `data-sheet-no-drag` so dragging it never pulls the sheet away.

`presentation` on `PopoverContent` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the anchored popover on touch too. Touch follows the device, not the screen width, and `YoujProvider`'s `device` can force it for a part of the page.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, from the anchor point (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) | gets out of the way faster than it arrived |
| Keyboard open, Escape close |  | 0ms | Base UI sets `data-instant` |

**Reduced motion:** The popover appears and disappears at once. Focus handling, placement and content are unchanged.

The popup's `transform-origin` is the point Base UI anchors it to, so it scales out of the trigger, not out of its own center. It animates on transitions, not keyframes, so reopening a popover while it closes reverses it from where it is.

#### Reduced motion

The popover appears in place and closes at once. Its portal carries the nearest `YoujProvider`'s settings, so a provider set to `reducedMotion="always"` reaches it even though it renders outside the provider's DOM.

### Accessibility

- The popup is a `dialog`, named by `PopoverTitle` and described by `PopoverDescription`. The trigger carries `aria-expanded` and `aria-haspopup="dialog"`.
- Opening moves focus to the first focusable element inside, or to the popup itself. Closing returns focus to the trigger.
- Under a mouse or trackpad it isn't modal by default: the rest of the page stays usable, and a press outside closes the popover. Pass `modal` to `Popover` to trap focus and lock scrolling instead. On touch it's modal unless you pass `modal={false}`.

| Key | Action |
| --- | --- |
| `Enter` / `Space` | Opens or closes the popover from the trigger. |
| `Tab` | Moves through the popover's content. |
| `Escape` | Closes the popover and returns focus to the trigger. |

---

# Tooltip

> Show a short visual label on hover or keyboard focus.

Source: https://www.youj.dev/docs/components/tooltip

## Examples

### Demo

```tsx
'use client'

import { Fragment } from 'react'
import {
  BoldIcon,
  CodeIcon,
  ItalicIcon,
  LinkIcon,
  ListIcon,
  ListOrderedIcon,
  QuoteIcon,
  StrikethroughIcon,
  type YoujIconComponent,
} from '@youj/icons'
import { Kbd, KbdGroup, Separator, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@youj/react'

interface Tool {
  label: string
  Icon: YoujIconComponent
  keys: string[]
  pressed?: boolean
}

const GROUPS: Tool[][] = [
  [
    { label: 'Bold', Icon: BoldIcon, keys: ['⌘', 'B'], pressed: true },
    { label: 'Italic', Icon: ItalicIcon, keys: ['⌘', 'I'] },
    { label: 'Strikethrough', Icon: StrikethroughIcon, keys: ['⌘', '⇧', 'X'] },
    { label: 'Inline code', Icon: CodeIcon, keys: ['⌘', 'E'] },
  ],
  [
    { label: 'Link', Icon: LinkIcon, keys: ['⌘', 'K'] },
    { label: 'Quote', Icon: QuoteIcon, keys: ['⌘', '⇧', '.'] },
  ],
  [
    { label: 'Bulleted list', Icon: ListIcon, keys: ['⌘', '⇧', '8'] },
    { label: 'Numbered list', Icon: ListOrderedIcon, keys: ['⌘', '⇧', '7'] },
  ],
]

export default function TooltipDemo() {
  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface shadow-xs">
      {/* One provider for the toolbar: rest on one button, then sweep across the rest. */}
      <TooltipProvider>
        <div role="group" aria-label="Formatting" className="flex flex-wrap items-center gap-0.5 border-b border-line p-1.5">
          {GROUPS.map((group, i) => (
            <Fragment key={group[0]!.label}>
              {i > 0 && <Separator orientation="vertical" className="mx-1 h-5 self-center" />}
              {group.map(({ label, Icon, keys, pressed }) => (
                <Tooltip key={label}>
                  {/* The tooltip is visual only: the button keeps a matching aria-label. */}
                  <TooltipTrigger render={<Toggle size="sm" aria-label={label} defaultPressed={pressed} />}>
                    <Icon />
                  </TooltipTrigger>
                  <TooltipContent>
                    {label}
                    <KbdGroup>
                      {keys.map((key) => (
                        <Kbd key={key}>{key}</Kbd>
                      ))}
                    </KbdGroup>
                  </TooltipContent>
                </Tooltip>
              ))}
            </Fragment>
          ))}
        </div>
      </TooltipProvider>
      <p className="px-4 py-3.5 text-ui leading-6 text-fg-muted">
        Release notes for <span className="font-semibold text-fg">2.4</span>: previews build twice as fast, and
        comments sync with your issue tracker.
      </p>
    </div>
  )
}
```

A formatting toolbar whose buttons show a name and keyboard shortcut, with neighbors opening at once after the first.

Wrap a toolbar, or your whole app, in one `TooltipProvider`. The first tooltip waits for the pointer to rest (500ms here, Base UI's `delay`). Once one is showing, its neighbors open at once and skip their entrance, so sweeping across a toolbar reads as one continuous label. Moving on within 400ms (the provider's `timeout`) keeps the group warm. Try it on the formatting toolbar above.

Tooltips can hold a [Kbd](https://www.youj.dev/docs/components/kbd) or a `KbdGroup`. The keycaps pick up the tooltip's colors in both modes.

### Sides

```tsx
'use client'

import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@youj/react'

const SIDES = ['top', 'right', 'bottom', 'left'] as const

export default function TooltipSides() {
  return (
    <TooltipProvider>
      <div className="grid grid-cols-2 gap-3">
        {SIDES.map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline" className="w-28 capitalize" />}>{side}</TooltipTrigger>
            {/* Each side drifts 3px in from the trigger. */}
            <TooltipContent side={side}>Opens on the {side}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}
```

A tooltip on each side of its trigger.

`side` picks the edge (`top` by default) and `align` the alignment along it. The tooltip drifts 3px in from the trigger, so its motion always points back at the control it names, and it flips when the preferred side runs out of room. Logical sides, `inline-start` and `inline-end`, follow the writing direction.

### Disabled controls

```tsx
'use client'

import { useId } from 'react'
import { RocketIcon } from '@youj/icons'
import { Button, Tooltip, TooltipContent, TooltipTrigger } from '@youj/react'

const REASON = 'Promote is available once the build finishes'

export default function TooltipDisabled() {
  const reason = useId()
  return (
    <div className="flex w-full max-w-sm items-center justify-between gap-4 rounded-xl border border-line bg-surface px-4 py-3 shadow-xs">
      <div className="min-w-0">
        <p className="truncate text-ui font-medium text-fg">Stream search results from the edge</p>
        <p className="text-ui-sm text-fg-muted">Building · 1m 12s</p>
      </div>
      <Tooltip>
        {/* Still focusable, so keyboard users get the reason too. Presses do nothing. */}
        <TooltipTrigger
          render={
            <Button
              disabled
              focusableWhenDisabled
              aria-describedby={reason}
              className="cursor-not-allowed data-disabled:pointer-events-auto"
            />
          }
        >
          <RocketIcon />
          Promote
        </TooltipTrigger>
        <TooltipContent>{REASON}</TooltipContent>
      </Tooltip>
      {/* Tooltips aren't announced, so the reason is also a description screen readers read. */}
      <span id={reason} className="sr-only">
        {REASON}
      </span>
    </div>
  )
}
```

A disabled button that still explains itself in a tooltip.

A disabled button that explains itself should stay focusable, or keyboard users never reach the reason. Pass `focusableWhenDisabled` to the [Button](https://www.youj.dev/docs/components/button) and let it take pointer events back so hover works too. Presses still do nothing. The tooltip isn't announced, so the example also points `aria-describedby` at the same sentence for screen readers.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tooltip
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Tooltip to show an icon-only control’s name or keyboard shortcut. It is visual only: it does not open on touch (unless you turn on `longPress`) and screen readers do not read it. Give the control its own accessible name and keep essential information visible. For an explanation people can open, use a [Popover](https://www.youj.dev/docs/components/popover) with `openOnHover`. For a link preview, use a [Hover Card](https://www.youj.dev/docs/components/hover-card).

```tsx
import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@youj/react'
import { ArchiveIcon } from '@youj/icons'

export function ArchiveButton() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Archive" />}>
          <ArchiveIcon />
        </TooltipTrigger>
        <TooltipContent>Archive</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

Give an icon-only trigger an `aria-label` that matches the tooltip text. The tooltip doesn't name or describe its trigger, so the label is what assistive technology reads.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### TooltipContent

Takes the props of `TooltipPrimitive.Popup.Props`, `Pick<TooltipPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' | 'collisionPadding'>`.

`TooltipProvider` passes through to Base UI's provider (`delay`, which defaults to 500 here, `closeDelay` and `timeout`). `Tooltip` takes the root props (`open`, `defaultOpen`, `onOpenChange`, `disabled`) and `longPress`, and `TooltipTrigger` takes the trigger's (`delay`, `closeDelay`, `closeOnClick`, `render`).

### Touch

Touch has no hover, so a tooltip doesn't open there. A tap is a press, and Base UI opens a tooltip on focus only when the focus comes from a keyboard, so a tap never leaves one stuck on screen. Anything a tooltip says must therefore reach people another way: an icon-only control needs an `aria-label`, and anything people need in order to act (why a control is disabled, a limit, a warning) belongs in visible text next to the control. On a phone, prefer a visible label under an icon when there's room for one.

`longPress` on `Tooltip` adds what Android does for icon buttons: holding the trigger for half a second shows the tooltip, and that press doesn't activate the control. The tooltip hides 1.5 seconds after the finger lifts or at the next touch anywhere, and a finger that moves, as in a scroll, cancels it. Keyboard shortcuts inside it are left out on touch. It helps someone who wonders what an icon means; it doesn't replace the label.

```tsx
<Tooltip longPress>
  <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Archive" />}>
    <ArchiveIcon />
  </TooltipTrigger>
  <TooltipContent>Archive</TooltipContent>
</Tooltip>
```

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Show | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | 3px drift from the trigger, scale .97 → 1, fade (`yj-tooltip`) |
| Hide | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Neighbor in a group, keyboard focus, Escape |  | 0ms | Base UI sets `data-instant` |
| Open delay |  | 500ms in a provider | hover intent, not motion: Speed leaves it alone |
| Long press (touch, `longPress`) |  | 500ms, 1.5s | how long to hold, then how long it stays after the finger lifts |

**Reduced motion:** Tooltips appear and disappear at once, with no drift. Delays are unchanged.

#### Reduced motion

Tooltips appear in place, without the drift or the fade, and hide at once. Hover delays stay the same, because they measure intent rather than animate anything.

### Accessibility

- Tooltips are visual only. Base UI doesn't describe the trigger with them, so the trigger's own name (its text or `aria-label`) must carry the meaning.
- Keyboard focus opens the tooltip without waiting for the delay. Hover opens it after the delay.
- They don't open on touch, since there's no way to reveal them before tapping. With `longPress`, holding the trigger shows one, and that press doesn't activate the control.

| Key | Action |
| --- | --- |
| `Tab` | Focusing a trigger shows its tooltip. |
| `Escape` | Hides the tooltip and leaves focus on the trigger. |

---

# Hover Card

> Preview a link’s destination on hover or keyboard focus.

Source: https://www.youj.dev/docs/components/hover-card

## Examples

### Demo

```tsx
'use client'

import { CalendarIcon, CheckCircleIcon, ClockIcon, GitMergeIcon } from '@youj/icons'
import { Avatar, AvatarBadge, AvatarFallback, Badge, HoverCard, HoverCardContent, HoverCardTrigger } from '@youj/react'

const link =
  'rounded-sm font-medium text-fg underline decoration-line-strong underline-offset-3 transition-[text-decoration-color] yj-duration-fast ease-standard hover:decoration-fg data-popup-open:decoration-fg focus-ring'

function PullRequestPreview() {
  return (
    <HoverCard>
      <HoverCardTrigger href="#pull-1284" className={link}>
        #1284
      </HoverCardTrigger>
      <HoverCardContent className="w-80">
        <div className="flex items-start gap-2.5">
          <GitMergeIcon size={16} className="mt-0.5 text-accent-text" />
          <div className="flex min-w-0 flex-col gap-1">
            <span className="text-ui font-semibold text-fg">Stream search results from the edge</span>
            <span className="text-ui-sm text-fg-muted">youj/web #1284 · merged 12 minutes ago</span>
          </div>
        </div>
        <div className="flex flex-wrap gap-1.5">
          <Badge variant="secondary">feat/search</Badge>
          <Badge variant="secondary">+412 −96</Badge>
        </div>
        <div className="flex items-center gap-2 border-t border-line pt-3 text-ui-sm text-fg-muted">
          <CheckCircleIcon size={14} className="text-success" />
          14 checks passed
        </div>
      </HoverCardContent>
    </HoverCard>
  )
}

function PersonPreview() {
  return (
    <HoverCard>
      <HoverCardTrigger href="#priya" className={link}>
        @priya
      </HoverCardTrigger>
      <HoverCardContent>
        <div className="flex items-center gap-3">
          <Avatar size="lg">
            <AvatarFallback>PR</AvatarFallback>
            <AvatarBadge />
          </Avatar>
          <div className="flex min-w-0 flex-col">
            <span className="text-ui-lg font-semibold text-fg">Priya Raman</span>
            <span className="text-ui-sm text-fg-muted">@priya · Platform lead</span>
          </div>
        </div>
        <p className="text-ui text-fg-muted">Owns deploys, the edge runtime and anything that pages at 3am.</p>
        <div className="flex flex-col gap-1.5 text-ui-sm text-fg-muted">
          <span className="flex items-center gap-2">
            <ClockIcon size={14} /> 14:32 in Lisbon
          </span>
          <span className="flex items-center gap-2">
            <CalendarIcon size={14} /> Joined March 2023
          </span>
        </div>
      </HoverCardContent>
    </HoverCard>
  )
}

const EARLIER = [
  { who: 'Ana Lima', initials: 'AL', what: 'opened a preview for the new pricing page.', when: 'Preview · 1 hour ago' },
  { who: 'Priya Raman', initials: 'PR', what: 'rotated the analytics key.', when: 'Settings · 3 hours ago' },
]

export default function HoverCardDemo() {
  return (
    <ul aria-label="Activity" className="w-full max-w-md divide-y divide-line rounded-xl border border-line bg-surface shadow-xs">
      <li className="flex gap-3 p-4">
        <Avatar size="sm">
          <AvatarFallback>KS</AvatarFallback>
        </Avatar>
        <div className="flex min-w-0 flex-col gap-1">
          <p className="text-ui leading-6 text-fg-muted">
            <span className="font-medium text-fg">Kenji Sato</span> promoted <PullRequestPreview /> to production.
            Thanks <PersonPreview /> for the review.
          </p>
          <span className="text-ui-sm text-fg-muted">Production · 8 minutes ago</span>
        </div>
      </li>
      {EARLIER.map((item) => (
        <li key={item.who} className="flex gap-3 p-4">
          <Avatar size="sm">
            <AvatarFallback>{item.initials}</AvatarFallback>
          </Avatar>
          <div className="flex min-w-0 flex-col gap-1">
            <p className="text-ui leading-6 text-fg-muted">
              <span className="font-medium text-fg">{item.who}</span> {item.what}
            </p>
            <span className="text-ui-sm text-fg-muted">{item.when}</span>
          </div>
        </li>
      ))}
    </ul>
  )
}
```

A pull request link that previews its title, labels and checks when hovered or focused.

The card opens after the pointer rests on the link for 500ms and closes 250ms after it leaves both the link and the card, so the pointer can travel onto the card without losing it. Passing over a row of links doesn't flash a card for each. Tune `delay` and `closeDelay` on the trigger. They measure intent, not motion, so the Speed control leaves them alone.

### In lists

```tsx
'use client'

import { GitBranchIcon, GitCommitIcon } from '@youj/icons'
import { Avatar, AvatarFallback, Badge, HoverCard, HoverCardContent, HoverCardTrigger } from '@youj/react'

const DEPLOYS = [
  { sha: '4f2a91c', message: 'Stream search results from the edge', author: 'Priya Raman', initials: 'PR', branch: 'feat/search', age: '2m', files: 12 },
  { sha: '9b1e03d', message: 'Tighten cache headers on /docs', author: 'Kenji Sato', initials: 'KS', branch: 'main', age: '1h', files: 3 },
  { sha: 'c7d42e8', message: 'New pricing page', author: 'Ana Lima', initials: 'AL', branch: 'feat/pricing', age: '3h', files: 21 },
]

export default function HoverCardCommits() {
  return (
    <ul aria-label="Deployments" className="w-full max-w-md divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface shadow-xs">
      {DEPLOYS.map((deploy) => (
        <li key={deploy.sha} className="flex items-center gap-3 px-4 py-3">
          <span className="min-w-0 flex-1 truncate text-ui text-fg">{deploy.message}</span>
          <HoverCard>
            <HoverCardTrigger
              href={`#commit-${deploy.sha}`}
              className="rounded-sm font-mono text-ui-sm text-fg-muted underline-offset-3 hover:text-fg hover:underline data-popup-open:text-fg focus-ring"
            >
              {deploy.sha}
            </HoverCardTrigger>
            {/* A hover card previews; the commit page it links to holds the same facts. */}
            <HoverCardContent side="top" align="end">
              <div className="flex items-start gap-2.5">
                <GitCommitIcon size={16} className="mt-0.5 text-fg-muted" />
                <div className="flex min-w-0 flex-col gap-0.5">
                  <span className="text-ui font-semibold text-fg">{deploy.message}</span>
                  <span className="font-mono text-ui-sm text-fg-muted">{deploy.sha}</span>
                </div>
              </div>
              <div className="flex items-center justify-between gap-3">
                <span className="flex min-w-0 items-center gap-2 text-ui-sm text-fg-muted">
                  <Avatar size="sm">
                    <AvatarFallback>{deploy.initials}</AvatarFallback>
                  </Avatar>
                  <span className="truncate">
                    {deploy.author} · {deploy.age} ago
                  </span>
                </span>
                <Badge variant="secondary">
                  <GitBranchIcon /> {deploy.branch}
                </Badge>
              </div>
              <p className="text-ui-sm text-fg-muted">{deploy.files} files changed</p>
            </HoverCardContent>
          </HoverCard>
        </li>
      ))}
    </ul>
  )
}
```

A list of commits where each hash previews its commit.

A list of references is where hover cards earn their keep: each commit hash previews its commit, and the list stays dense. Here the card opens above the row (`side="top"`), aligned to the end of the hash.

### On avatars

```tsx
'use client'

import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, HoverCard, HoverCardContent, HoverCardTrigger } from '@youj/react'

const VIEWERS = [
  { handle: 'ana', name: 'Ana Lima', initials: 'AL', role: 'Design', page: '/pricing' },
  { handle: 'kenji', name: 'Kenji Sato', initials: 'KS', role: 'Frontend', page: '/pricing' },
  { handle: 'priya', name: 'Priya Raman', initials: 'PR', role: 'Platform', page: '/docs/deploys' },
]

export default function HoverCardPresence() {
  return (
    <div className="flex w-full max-w-sm items-center justify-between rounded-xl border border-line bg-surface px-4 py-3 shadow-xs">
      <span className="text-ui text-fg-muted">Viewing this preview</span>
      <AvatarGroup>
        {VIEWERS.map((viewer) => (
          <HoverCard key={viewer.handle}>
            {/* The avatar shows initials, so the link carries the person's name. */}
            <HoverCardTrigger href={`#${viewer.handle}`} aria-label={viewer.name} className="rounded-full focus-ring">
              <Avatar className="ring-2 ring-surface">
                <AvatarFallback>{viewer.initials}</AvatarFallback>
                <AvatarBadge />
              </Avatar>
            </HoverCardTrigger>
            <HoverCardContent side="top" className="w-60 flex-row items-center">
              <Avatar size="lg">
                <AvatarFallback>{viewer.initials}</AvatarFallback>
              </Avatar>
              <div className="flex min-w-0 flex-col">
                <span className="text-ui font-semibold text-fg">{viewer.name}</span>
                <span className="text-ui-sm text-fg-muted">{viewer.role}</span>
                <span className="truncate font-mono text-ui-sm text-fg-muted">{viewer.page}</span>
              </div>
            </HoverCardContent>
          </HoverCard>
        ))}
        <AvatarGroupCount>
          <span aria-hidden>+2</span>
          <span className="sr-only">and 2 more</span>
        </AvatarGroupCount>
      </AvatarGroup>
    </div>
  )
}
```

A row of avatars that each preview a person.

An avatar with initials doesn't say who it is. Make each one a link with the person's name as its `aria-label`, and let the card say the rest.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add hover-card
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a hover card to let people peek at a link's destination without leaving the page: mentions, references, commit hashes. It's a visual shortcut for sighted pointer, touch and keyboard users, and the link stays the real interface, so everything in the card must also be at its destination. Keep controls out of the card. For content people open on purpose, including on touch, use a [Popover](https://www.youj.dev/docs/components/popover). For a one-line label, use a [Tooltip](https://www.youj.dev/docs/components/tooltip).

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@youj/react'

export function Mention() {
  return (
    <HoverCard>
      <HoverCardTrigger href="/people/priya">@priya</HoverCardTrigger>
      <HoverCardContent>
        <PersonSummary handle="priya" />
      </HoverCardContent>
    </HoverCard>
  )
}
```

`HoverCardTrigger` renders an `<a>`, so it stays a plain link: it navigates on click and reads as a link to assistive technology. Style it like the links around it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### HoverCardContent

Takes the props of `PreviewCardPrimitive.Popup.Props`, `Pick<PreviewCardPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' | 'collisionPadding'>`.

`HoverCardTrigger` passes through to Base UI's preview card trigger. Here it defaults `delay` to 500 and `closeDelay` to 250, and takes `href` and the other link attributes. `HoverCard` takes the root props (`open`, `defaultOpen`, `onOpenChange`).

### Touch

Touch has no hover, so on a touch device a tap on the link opens its card instead of following the link. A second tap on the link follows it and closes the card, and a tap anywhere else closes the card without leaving the page. Base UI's preview card doesn't respond to touch on its own; `HoverCardTrigger` adds this. On a phone the card is still a preview: a screen reader user never sees it, so keep everything in it at the destination too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, out of the link (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Keyboard focus, Escape |  | 0ms | Base UI sets `data-instant` |
| Open and close delays |  | 500ms, 250ms | hover intent, not motion |

**Reduced motion:** The card appears and disappears at once. The delays stay the same.

#### Reduced motion

The card appears in place when the delay ends and closes at once. The delays are kept, because they separate a glance from a pass-by rather than animate anything.

### Accessibility

- The trigger is an ordinary link, and it's the only accessible interface. The card isn't announced, and its content isn't in the tab order.
- Keyboard focus on the link opens the card, so keyboard users get the same preview. `Escape` closes it and leaves focus on the link.
- On touch, the first tap on the link shows the card and the second follows the link. The card's content isn't navigable by touch, keyboard or screen reader, which is why it must repeat what the destination says.

| Key | Action |
| --- | --- |
| `Tab` | Focusing the link opens its card. |
| `Enter` | Follows the link. |
| `Escape` | Closes the card and keeps focus on the link. |

---

# Tour

> Walk people through a screen one element at a time, with a spotlight and a card beside it.

Source: https://www.youj.dev/docs/components/tour

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { DownloadIcon, HomeIcon, SearchIcon, SettingsIcon, UsersIcon } from '@youj/icons'
import { Button, Input, Tour, type TourStep } from '@youj/react'

const steps: TourStep[] = [
  { target: '#tour-demo-nav', title: 'Everything in one place', body: 'Your overview, customers and settings live in the sidebar.', placement: 'inline-end' },
  { target: '#tour-demo-search', title: 'Find any order', body: 'Search by number, customer or amount.' },
  { target: '#tour-demo-kpis', title: 'Today at a glance', body: 'Revenue and orders against the same day last week.' },
  { target: '#tour-demo-export', title: 'Take it with you', body: 'Export the orders you see as CSV.', placement: 'top' },
]

export default function TourDemo() {
  // The tour renders inside this frame: `contain: paint` makes it the box the scrim covers.
  const [frame, setFrame] = useState<HTMLDivElement | null>(null)
  const [open, setOpen] = useState(false)
  return (
    <div ref={setFrame} className="relative flex h-[380px] w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-canvas text-fg [contain:paint]">
      <nav id="tour-demo-nav" className="flex w-40 shrink-0 flex-col gap-1 border-e border-line bg-surface p-3">
        <div className="mb-2 px-2 font-semibold">Northwind</div>
        {[
          { icon: HomeIcon, label: 'Overview' },
          { icon: UsersIcon, label: 'Customers' },
          { icon: SettingsIcon, label: 'Settings' },
        ].map(({ icon: Icon, label }) => (
          <span key={label} className="flex items-center gap-2 rounded-md px-2 py-1.5 text-ui text-fg-muted first:bg-selected first:text-fg">
            <Icon className="size-4" />
            {label}
          </span>
        ))}
      </nav>
      <div className="flex min-w-0 flex-1 flex-col gap-4 p-4">
        <div className="flex items-center gap-2">
          <div className="relative min-w-0 flex-1">
            <SearchIcon className="pointer-events-none absolute start-2.5 top-1/2 size-4 -translate-y-1/2 text-fg-subtle" />
            <Input id="tour-demo-search" className="ps-8" placeholder="Search orders" aria-label="Search orders" />
          </div>
          <Button onClick={() => setOpen(true)}>Take the tour</Button>
        </div>
        <div id="tour-demo-kpis" className="grid grid-cols-2 gap-3">
          {[
            ['Revenue', '$48.2k'],
            ['Orders', '1,284'],
          ].map(([label, value]) => (
            <div key={label} className="rounded-lg border border-line bg-surface p-3">
              <div className="text-ui-sm text-fg-muted">{label}</div>
              <div className="text-xl font-semibold tabular-nums">{value}</div>
            </div>
          ))}
        </div>
        <div className="mt-auto flex justify-end">
          <Button id="tour-demo-export" variant="outline" size="sm">
            <DownloadIcon />
            Export
          </Button>
        </div>
      </div>
      <Tour steps={steps} open={open} onOpenChange={setOpen} container={frame} />
    </div>
  )
}
```

A first-run tour of a small dashboard: the sidebar, search, the figures and Export, one at a time.

Each step dims the page and cuts a rounded hole over its target, with a card beside it: the step's title and text, the count ("2 of 4") and dots, Back, Next (Done on the last step) and Skip. Between steps the hole glides to the next target. The arrow keys go Back and Next, and Escape skips.

### New feature beacon

```tsx
'use client'

import { useState } from 'react'
import { BellIcon } from '@youj/icons'
import { Button, Tour, TourBeacon } from '@youj/react'

export default function TourBeaconDemo() {
  const [frame, setFrame] = useState<HTMLDivElement | null>(null)
  const [open, setOpen] = useState(false)
  const [seen, setSeen] = useState(false)
  return (
    <div ref={setFrame} className="relative flex h-[300px] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-line bg-canvas text-fg [contain:paint]">
      <header className="flex items-center gap-2 border-b border-line bg-surface px-4 py-3">
        <span className="font-semibold">Payouts</span>
        <span className="relative ms-auto">
          <Button id="tour-beacon-bell" variant="outline" size="icon" aria-label="Notifications">
            <BellIcon />
          </Button>
          {!seen && <TourBeacon className="absolute -end-2 -top-2" label="What’s new: notifications" onClick={() => setOpen(true)} />}
        </span>
      </header>
      <p className="m-auto max-w-xs text-center text-ui text-fg-muted">
        {seen ? 'Seen. The beacon is gone until the next new thing.' : 'A beacon marks what’s new. Click the dot by the bell.'}
      </p>
      <Tour
        container={frame}
        open={open}
        onOpenChange={setOpen}
        onComplete={() => setSeen(true)}
        onSkip={() => setSeen(true)}
        allowInteraction
        steps={[{ target: '#tour-beacon-bell', title: 'New: notifications', body: 'Get told when a payout lands or a refund goes out. The bell works while this is open.' }]}
      />
    </div>
  )
}
```

A pulsing dot beside a new control starts a one-step tour about it, and goes away once it has been seen.

`TourBeacon` is a small button: a dot with a ring that swells out of it and fades. Put it where you want attention and open a tour from its `onClick`. Here the tour sets `allowInteraction`, so the bell under the spotlight can be clicked while the card is open.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tour
```

It brings `button`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-tour`, `youj-presets`, `youj-ui-core` with it.

Use a Tour to show someone around a screen they haven't used before, or a few new things on one they have. Keep it short: three to five steps, each about one thing they can see. For one new control a [Popover](https://www.youj.dev/docs/components/popover) or a TourBeacon with a one-step tour is enough.

```tsx
import { useState } from 'react'
import { Button, Tour, type TourStep } from '@youj/react'

const steps: TourStep[] = [
  { target: '#search', title: 'Find any order', body: 'Search by number, customer or amount.' },
  { target: '#filters', title: 'Narrow the list', body: 'Filter by status, channel or date.' },
  { target: '#export', title: 'Take it with you', body: 'Export what you see as CSV.', placement: 'top' },
]

export function OrdersTour() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Button onClick={() => setOpen(true)}>Take the tour</Button>
      <Tour steps={steps} open={open} onOpenChange={setOpen} onComplete={markSeen} onSkip={markSeen} />
    </>
  )
}
```

A step's `target` is a CSS selector (the first match on the page) or a ref. A step whose target isn't on the page, or is hidden, is skipped in the direction you were going. `placement` puts the card on a side of the target (`bottom` by default; `top`, `inline-start` or `inline-end`), and it flips when there's no room. `action` adds your own content under the text, such as a link or a button that does the thing.

`open` and `step` can each be controlled (`onOpenChange`, `onStepChange`), or left to the tour with `defaultOpen` and `defaultStep`; an uncontrolled tour starts again from `defaultStep` each time it opens. `onComplete` runs when Done is pressed, `onSkip` with the step index when Skip or Escape ends it early.

To keep the tour inside part of the page, as these previews do, pass that element as `container` and give it `contain: paint` (or a `transform`), so the scrim covers it rather than the window.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Tour

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `TourStep[]` |  |  |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `step` | `number` |  | Controlled step index. |
| `defaultStep` | `number` | `0` |  |
| `onStepChange` | `(step: number) => void` |  |  |
| `onComplete` | `() => void` |  | Runs when Done is pressed on the last step (or Next runs past the last step that can be shown). |
| `onSkip` | `(step: number) => void` |  | Runs when the tour is left early, by Skip or Escape, with the step it was on. |
| `allowInteraction` | `boolean` | `false` | Clicks reach the spotlighted element, and focus is not trapped in the card, so the target can be used. |
| `dismissible` | `boolean` | `true` | Skip and Escape end the tour. With false the only ways out are Done and your own controls. |
| `spotlightPadding` | `number` | `6` | Room around the target inside the cut-out, in px. |
| `container` | `HTMLElement \| null` |  | Where the scrim and card render. Default: the provider's portal container, else `document.body`. An element of your own keeps the tour inside it; it must be a positioning context for `fixed` children (give it a `transform` or `contain: paint`). |
| `className` | `string` |  | The card's classes. |

#### TourBeacon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | The button's accessible name. Default: the `tourStart` label ("Start the tour"). |

Also takes the props of `ComponentProps<'button'>`.

`TourBeacon` also takes a button's props (`onClick`, `className`…).

#### Data attributes

The card is `data-slot="tour"`, the scrim `data-slot="tour-scrim"` and the outline around the hole `data-slot="tour-spotlight"`. In the card, `tour-count`, `tour-title`, `tour-body` and `tour-dots` mark the parts, and the current dot carries `data-state="active"`. The beacon is `data-slot="tour-beacon"`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Glide | `spring.smooth` | 0.36s, bounce 0 | the hole moves and resizes from the last target to the next, following it live while the page scrolls it into view |
| Card | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the next step’s text fades in, rising 4px, where the card lands |
| Open, close | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the scrim fades (`yj-backdrop`) and the card opens with `yj-pop` |
| Scroll |  |  | a target off screen scrolls to the middle smoothly |
| Beacon | `duration.deliberate`, `ease.exit` | 560ms; cubic-bezier(0.4, 0, 1, 1) | a ring swells out of the dot and fades, repeating while it is on screen |

**Reduced motion:** The hole moves to each target at once and scrolling is instant; only the card's text fades. The beacon's ring rests still around the dot.

#### Reduced motion

Every step lands at once, so nothing glides or slides; what changes is still shown, and announced.

### Accessibility

- The card is a dialog named by the step's title and described by its text, followed by a hint on the keys. Focus moves into it (to Next) when the tour opens and stays in it while the tour runs.
- ← and → go Back and Next (swapped in right-to-left), Tab moves between the buttons, and Escape skips the tour when it's `dismissible`.
- Each new step is announced politely: "Step 2 of 4: Find any order".
- The spotlighted element is described by the step's text (`aria-describedby`) while it's shown, and its own description is put back afterwards.
- With `allowInteraction`, clicks reach the spotlighted element and focus isn't held in the card, so the element can be used from the keyboard too.
- The count and the dots say the same thing; the dots are hidden from assistive technology.
- `TourBeacon` is a button named "Start the tour" by default; pass `label` to say what it's about.

---

# Sheet Presentation

> Present an overlay as a bottom sheet on touch and keep the popover under a pointer.

Source: https://www.youj.dev/docs/components/presentation

Menus, selects and pickers are popovers under a mouse. Under a thumb they are bottom sheets: they rise from the bottom edge where the hand already is, rows are 48px, and a pull down dismisses them. Dropdown Menu, Select, Popover, Combobox, Multi-select, Command, Context Menu and the date and color pickers do this on their own. This page is for building your own overlay the same way.

The same Base UI primitive drives both presentations, so roles, focus order, typeahead, controlled state and events do not change. Only the placement, the surface and the way it is dismissed do.

## Installation

```bash
pnpm add @youj/react
```

```tsx
import { SheetHandle, SheetLayer } from '@youj/react'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add presentation
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

## Examples

### Choosing the presentation

Every overlay in the library takes `presentation` on its content part.

| Value | Behavior |
|---|---|
| `auto` (default) | A sheet on touch, a popover under a pointer. |
| `sheet` | Always a sheet. |
| `popover` | Always a popover, also on touch. |

`auto` follows the device: the primary pointer, or the `device` you set on [`YoujProvider` or `ThemeScope`](https://www.youj.dev/docs/guides/touch-mode). It never follows the width of the window. A narrow desktop window is not touch, and a wide tablet is.

### Building a sheet

`useSheetPresentation` tells a component which branch to render. The sheet branch keeps Base UI's `Portal`, `Positioner` and `Popup`, and changes only their classes and one wrapper. The class strings are internal to the package, not exports of `@youj/react`: run `npx @youj/cli add presentation` and import them from your copy.

Install `@base-ui/react` in your app (`pnpm add @base-ui/react`) to import its primitives directly, as pnpm won't resolve it through Youj.

```tsx
import type { ReactNode } from 'react'
import { Menu } from '@base-ui/react/menu'
import { useYoujScope, usePortalContainer } from '@youj/core'
import { SheetHandle, SheetLayer, useSheetPresentation, type OverlayPresentation } from '@youj/react'
import { sheetPopupClass, sheetPositionerClass, sheetScrimClass } from '@/components/ui/presentation'

function ActionsContent({ children, presentation = 'auto' }: { children: ReactNode; presentation?: OverlayPresentation }) {
  const scope = useYoujScope()
  const container = usePortalContainer()
  const sheet = useSheetPresentation(presentation)
  if (!sheet) return <PopoverBranch>{children}</PopoverBranch>
  return (
    <Menu.Portal container={container} {...scope}>
      <SheetLayer>
        <Menu.Backdrop data-sheet-scrim="" className={sheetScrimClass} />
        <Menu.Positioner className={sheetPositionerClass}>
          <Menu.Popup data-sheet-popup="" className={sheetPopupClass}>
            <SheetHandle />
            {children}
          </Menu.Popup>
        </Menu.Positioner>
      </SheetLayer>
    </Menu.Portal>
  )
}
```

| Export | What it is |
|---|---|
| `useSheetPresentation(presentation)` | `true` when the overlay should be a sheet. |
| `SheetLayer` | Wraps the scrim and the popup. It owns no box and carries the drag. |
| `SheetHandle` | The grab handle. Decorative: Escape still dismisses. |
| `sheetPositionerClass`, `sheetPopupClass`, `sheetScrimClass` | In your copy of `presentation`: the classes for the positioner, the popup and the scrim. |
| `sheetRowClass`, `sheetLabelClass` | In your copy: a 48px row with a press state, and a group caption that lines up with it. |

Put `touch:hidden` on keyboard-shortcut hints, and use the `touch:` and `fine:` variants for anything else that only makes sense for one input.

### Dismissing

A sheet is dismissed the ways a popover is (Escape, a press outside) and by pulling it down. The sheet follows the finger from the handle, or from anywhere on it once its list is scrolled to the top. A flick, or a drag past a quarter of its height, dismisses it; a shorter drag springs back, and the scrim thins as it leaves. Dismissal sends the same Escape the keyboard would, so focus returns to the trigger.

Mark an element that has its own drag, such as a color area or a slider, with `data-sheet-no-drag`. A drag that starts inside it never moves the sheet.

### Sheets with a text field

The on-screen keyboard covers the bottom of a bottom sheet, and the viewport units do not shrink for it on iOS. These helpers follow `window.visualViewport` instead.

| Export | What it does |
|---|---|
| `useVisualViewportInset()` | Tracks the visible area and writes `--yj-sheet-inset` and `--yj-sheet-visible` on the popup. |
| `sheetKeyboardClass` | Lifts the sheet onto the keyboard and caps its height to what is visible. |
| `useKeyboardSheet()` | Combines the two, keeps the sheet's tallest height while the list filters, and focuses the sheet instead of the field when it opens by touch. |
| `primeKeyboard()` | Call it inside the tap that opens a search sheet. iOS only raises the keyboard for a focus that happens in that tap, so it focuses a hidden field first. It does nothing elsewhere. |

## Reference

### Reduced motion

With reduced motion the sheet appears and leaves instantly, and a drag still tracks the finger.

### Accessibility

The primitive keeps its roles and its focus management. The handle is `aria-hidden`: pulling down is a shortcut for Escape, never the only way out.

---

# Dropdown Menu

> Open a menu of actions or options from a button.

Source: https://www.youj.dev/docs/components/dropdown-menu

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  ArchiveIcon,
  ArrowUpRightIcon,
  CopyIcon,
  FolderIcon,
  LinkIcon,
  MoreHorizontalIcon,
  PencilIcon,
  PinIcon,
  ShareIcon,
  TrashIcon,
} from '@youj/icons'
import {
  Badge,
  Button,
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from '@youj/react'

const TEAMS = ['Design', 'Platform', 'Growth', 'Infrastructure']

export default function DropdownMenuDemo() {
  const [pinned, setPinned] = useState(true)
  const [log, setLog] = useState('')
  const [open, setOpen] = useState(false)

return (
    <div className="flex h-[25rem] w-full max-w-sm flex-col gap-3">
      <div className="flex items-start gap-3 rounded-xl border border-line bg-surface p-4 shadow-xs">
        <span className="grid size-9 shrink-0 place-items-center rounded-lg bg-accent-subtle font-mono text-ui-sm font-semibold text-accent-text">
          KW
        </span>
        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
          <span className="flex items-center gap-2">
            <span className="truncate text-ui font-semibold text-fg">youj-web</span>
            {pinned && <Badge variant="secondary">Pinned</Badge>}
          </span>
          <span className="truncate text-ui-sm text-fg-muted">youj.io · updated 2h ago</span>
        </div>
        <DropdownMenu open={open} onOpenChange={setOpen}>
          <DropdownMenuTrigger render={<Button variant="ghost" size="icon-sm" className="-me-1.5 -mt-1" aria-label="Project actions" />}>
            {/* A state icon: its dots become a close mark while the menu is open. */}
            <MoreHorizontalIcon active={open} />
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end" className="w-56">
            <DropdownMenuGroup>
              <DropdownMenuItem onClick={() => setLog('Opened youj-web')}>
                <ArrowUpRightIcon />
                Open
                <DropdownMenuShortcut>⌘O</DropdownMenuShortcut>
              </DropdownMenuItem>
              <DropdownMenuItem onClick={() => setLog('Renaming youj-web')}>
                <PencilIcon />
                Rename
                <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
              </DropdownMenuItem>
              <DropdownMenuItem onClick={() => setLog('Duplicated youj-web')}>
                <CopyIcon />
                Duplicate
                <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
              </DropdownMenuItem>
              <DropdownMenuItem onClick={() => setLog('Copied the project link')}>
                <LinkIcon />
                Copy link
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuSub>
              <DropdownMenuSubTrigger>
                <FolderIcon />
                Move to
              </DropdownMenuSubTrigger>
              <DropdownMenuSubContent>
                <DropdownMenuLabel>Teams</DropdownMenuLabel>
                {TEAMS.map((team) => (
                  <DropdownMenuItem key={team} onClick={() => setLog(`Moved to ${team}`)}>
                    {team}
                  </DropdownMenuItem>
                ))}
              </DropdownMenuSubContent>
            </DropdownMenuSub>
            <DropdownMenuSub>
              <DropdownMenuSubTrigger>
                <ShareIcon />
                Share
              </DropdownMenuSubTrigger>
              <DropdownMenuSubContent>
                <DropdownMenuItem onClick={() => setLog('Invite sent')}>Invite people…</DropdownMenuItem>
                <DropdownMenuItem onClick={() => setLog('Embed code copied')}>Copy embed code</DropdownMenuItem>
                <DropdownMenuItem disabled>Publish to web</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuSub>
            {/* Checkbox and radio items keep the menu open while you toggle them. */}
            <DropdownMenuCheckboxItem checked={pinned} onCheckedChange={setPinned}>
              <PinIcon />
              Pin to sidebar
            </DropdownMenuCheckboxItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem onClick={() => setLog('Archived youj-web')}>
              <ArchiveIcon />
              Archive
            </DropdownMenuItem>
            <DropdownMenuItem variant="danger" onClick={() => setLog('Deleted youj-web')}>
              <TrashIcon />
              Delete project
              <DropdownMenuShortcut>⌘⌫</DropdownMenuShortcut>
            </DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </div>
      <p role="status" className="h-5 px-1 text-ui-sm text-fg-muted">
        {log}
      </p>
    </div>
  )
}
```

A project card with an actions menu of items, groups, shortcuts, a submenu and a danger row.

- **Items** run an action. `variant="danger"` tints the row red, for deleting, revoking and leaving. `disabled` keeps a row visible but out of reach.
- **Groups and labels.** `DropdownMenuGroup` gathers related rows, and a `DropdownMenuLabel` inside a group names it for screen readers. Outside a group, a label is a plain caption.
- **Separators** divide groups. The highlight glides across them rather than blinking out.
- **Submenus.** `DropdownMenuSub` holds a `DropdownMenuSubTrigger` row and a `DropdownMenuSubContent`, which opens beside the row with its first item level with it.
- **Inset.** `inset` on a row or label indents it to line up with rows that have an icon.

### Checkbox and radio items

```tsx
'use client'

import { useState } from 'react'
import { SlidersIcon } from '@youj/icons'
import {
  Button,
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from '@youj/react'

type Shown = { previews: boolean; branches: boolean; compact: boolean }

export default function DropdownMenuOptions() {
  const [sort, setSort] = useState('updated')
  const [shown, setShown] = useState<Shown>({ previews: true, branches: false, compact: false })
  const toggle = (key: keyof Shown) => (checked: boolean) => setShown((s) => ({ ...s, [key]: checked }))

return (
    <div className="flex h-80 w-full max-w-sm flex-col items-start gap-3">
      <DropdownMenu>
        <DropdownMenuTrigger render={<Button variant="outline" size="sm" />}>
          <SlidersIcon />
          Display
        </DropdownMenuTrigger>
        <DropdownMenuContent className="w-52">
          {/* A label inside a radio group names the group for screen readers. */}
          <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
            <DropdownMenuLabel>Sort by</DropdownMenuLabel>
            <DropdownMenuRadioItem value="name">Name</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="updated">Last deployed</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="created">Date created</DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
          <DropdownMenuSeparator />
          <DropdownMenuGroup>
            <DropdownMenuLabel>Show</DropdownMenuLabel>
            <DropdownMenuCheckboxItem checked={shown.previews} onCheckedChange={toggle('previews')}>
              Preview deployments
            </DropdownMenuCheckboxItem>
            <DropdownMenuCheckboxItem checked={shown.branches} onCheckedChange={toggle('branches')}>
              Branch names
            </DropdownMenuCheckboxItem>
            <DropdownMenuCheckboxItem checked={shown.compact} onCheckedChange={toggle('compact')}>
              Compact rows
            </DropdownMenuCheckboxItem>
          </DropdownMenuGroup>
        </DropdownMenuContent>
      </DropdownMenu>
      <p className="px-1 text-ui-sm text-fg-muted">
        Sorted by {sort === 'updated' ? 'last deployed' : sort === 'created' ? 'date created' : 'name'}
        {shown.previews ? ', with previews' : ''}
        {shown.branches ? ', with branches' : ''}
        {shown.compact ? ', compact' : ''}.
      </p>
    </div>
  )
}
```

A menu with checkbox settings and a radio group, which stays open while they change.

`DropdownMenuCheckboxItem` toggles a setting and `DropdownMenuRadioGroup` with `DropdownMenuRadioItem` picks one option. Both keep the menu open, so several settings can change in one visit. A check draws itself in when a row turns on.

### Account menu

```tsx
'use client'

import { useState } from 'react'
import { KeyboardIcon, LogOutIcon, SettingsIcon, ThemeIcon, UserIcon } from '@youj/icons'
import {
  Avatar,
  AvatarFallback,
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from '@youj/react'

export default function DropdownMenuAccount() {
  const [theme, setTheme] = useState('system')

return (
    <div className="flex h-80 w-full max-w-sm flex-col items-end">
      <DropdownMenu>
        <DropdownMenuTrigger
          render={<Button variant="ghost" className="h-auto gap-2 py-1 ps-1 pe-2" aria-label="Ana Lima, account menu" />}
        >
          <Avatar size="sm">
            <AvatarFallback>AL</AvatarFallback>
          </Avatar>
          <span className="text-ui font-medium text-fg">Ana Lima</span>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end" className="w-60">
          <div className="flex flex-col px-2 pt-1.5 pb-2">
            <span className="text-ui font-medium text-fg">Ana Lima</span>
            <span className="text-ui-sm text-fg-muted">ana@youj.dev</span>
          </div>
          <DropdownMenuSeparator />
          <DropdownMenuItem>
            <UserIcon />
            Profile
            <DropdownMenuShortcut>⌘⇧P</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <SettingsIcon />
            Settings
            <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <KeyboardIcon />
            Keyboard shortcuts
            <DropdownMenuShortcut>?</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>
              <ThemeIcon active={theme === 'dark'} />
              Theme
            </DropdownMenuSubTrigger>
            <DropdownMenuSubContent>
              <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
                <DropdownMenuRadioItem value="light">Light</DropdownMenuRadioItem>
                <DropdownMenuRadioItem value="dark">Dark</DropdownMenuRadioItem>
                <DropdownMenuRadioItem value="system">System</DropdownMenuRadioItem>
              </DropdownMenuRadioGroup>
            </DropdownMenuSubContent>
          </DropdownMenuSub>
          <DropdownMenuSeparator />
          {/* No icon on this row: `inset` lines its label up with the rows above. */}
          <DropdownMenuItem inset>Changelog</DropdownMenuItem>
          <DropdownMenuItem>
            <LogOutIcon />
            Sign out
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  )
}
```

An account menu built from an avatar trigger, a header and a Theme submenu.

The trigger can be any button: here an avatar and a name. The header is plain content, and the Theme submenu holds a radio group. The `inset` row lines up with the icon rows above it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dropdown-menu
```

It brings `icon-check`, `icon-chevron-right`, `presentation`, `sliding-indicator`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

The copy is 9 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `icon-check`, `icon-chevron-right`, `icon-engine`, `presentation`, `sliding-indicator`.

Use Dropdown Menu for actions such as open, rename or delete, and for view settings. Use [Select](https://www.youj.dev/docs/components/select) to choose a value, or [Command](https://www.youj.dev/docs/components/command) to search a long list. You can also offer the same actions in a [Context Menu](https://www.youj.dev/docs/components/context-menu), while keeping the dropdown as a visible way to reach them.

```tsx
import { useState } from 'react'
import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuTrigger } from '@youj/react'
import { MoreHorizontalIcon, PencilIcon, TrashIcon } from '@youj/icons'

export function ProjectActions() {
  const [open, setOpen] = useState(false)
  return (
    <DropdownMenu open={open} onOpenChange={setOpen}>
      <DropdownMenuTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Project actions" />}>
        <MoreHorizontalIcon active={open} />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuItem onClick={rename}>
          <PencilIcon />
          Rename
          <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="danger" onClick={remove}>
          <TrashIcon />
          Delete project
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

`MoreHorizontalIcon` is a state icon: driven by the menu's `open` state, its dots become a close mark while the menu is open and return when it closes. Run an item's action from `onClick`. It fires for pointer and keyboard alike, then the menu closes. A leading icon is muted until its row is highlighted. [Youj icons](https://www.youj.dev/docs/icons) also play their choreography then, because a menu item is their trigger. `DropdownMenuShortcut` shows a row's shortcut, trailing and muted. It's a label only, so bind the keys yourself.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### DropdownMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | Where the portal renders. Default: document.body. |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |

#### DropdownMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` |  | Indents the label to line up with rows that have an icon. |
| `variant` | `'default' \| 'danger'` | `'default'` | `danger` tints the row red: deleting, revoking, leaving. |
| `onSelect` | `'onSelect is the DOM text-selection event and never fires on a menu item: use onClick'` |  |  |

Also takes the props of `MenuPrimitive.Item.Props`.

`DropdownMenu` takes Base UI's root props (`open`, `defaultOpen`, `onOpenChange`, `modal`, which is on by default), and `DropdownMenuTrigger` takes the trigger's (`openOnHover`, `delay`, `render`). `DropdownMenuCheckboxItem` takes `checked`, `defaultChecked` and `onCheckedChange`, and `DropdownMenuRadioGroup` takes `value`, `defaultValue` and `onValueChange`. Rows and labels take `inset`, rows take `disabled`, and `closeOnClick` changes whether choosing an item closes the menu (on for items, off for checkbox and radio items). `DropdownMenuSubContent` takes the same placement props as the content, opening on `inline-end` by default.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, out of the trigger (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Highlight | `spring.smooth` | 0.36s, bounce 0 | one `SlidingIndicator` per popup glides between rows |
| Highlight across a separator | `duration.fast` | 140ms | holds its row this long before it lets go |
| Destructive wash | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | red tint on the highlighted row |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws in when a row turns on |
| Keyboard open, Escape close |  | 0ms | Base UI sets `data-instant` |

**Reduced motion:** The menu appears at once, the highlight jumps from row to row, and checks appear already drawn.

Rows paint nothing themselves on hover. A single highlight per popup follows Base UI's highlighted row, so moving quickly down a menu reads as one traveling surface, and a mid-glide change of direction retargets it with its velocity. In forced-colors mode the fill is dropped and the highlighted row gets an outline.

#### Reduced motion

The menu opens and closes at once and the highlight moves without gliding. Checks are drawn as soon as a row turns on. Rows, keyboard behavior and focus handling don't change.

### Accessibility

- The trigger has `aria-haspopup="menu"` and `aria-expanded`, and the popup is a `menu`. Rows are `menuitem`, `menuitemcheckbox` or `menuitemradio`, with `aria-checked` where they hold state.
- A label inside a group names the group. Radio items sit in a `group`, so the choice is announced with its name.
- Focus moves into the menu when it opens and returns to the trigger when it closes. While open, the menu is modal: the page doesn't scroll and outside presses only close it.
- The popup itself is a tab stop, so a menu long enough to scroll is reachable from the keyboard. `Tab` closes the menu.

| Key | Action |
| --- | --- |
| `Enter` / `Space` / `↓` | Opens the menu from the trigger and focuses the first row. |
| `↑` | Opens the menu from the trigger and focuses the last row. |
| `↑` / `↓` | Moves between rows. |
| `Home` / `End` | Jumps to the first or last row. |
| Letters | Jump to the next row that starts with them (typeahead). |
| `Enter` / `Space` | Runs the row, or toggles a checkbox or radio row. |
| `→` / `←` | Opens a submenu on its first row, or closes it back onto its row. Mirrored in right-to-left layouts. |
| `Escape` | Closes the menu and returns focus to the trigger. |

---

# Context Menu

> Open actions for an item with right-click, long press or Shift+F10.

Source: https://www.youj.dev/docs/components/context-menu

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  ClipboardIcon,
  CodeXmlIcon,
  CopyIcon,
  DownloadIcon,
  FileTextIcon,
  FolderIcon,
  ImageIcon,
  MoreHorizontalIcon,
  PencilIcon,
  TrashIcon,
  type YoujIconComponent,
} from '@youj/icons'
import {
  Button,
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuTrigger,
} from '@youj/react'

const FILES: { name: string; Icon: YoujIconComponent; size: string }[] = [
  { name: 'middleware.ts', Icon: CodeXmlIcon, size: '2.1 KB' },
  { name: 'og-image.png', Icon: ImageIcon, size: '184 KB' },
  { name: 'youj.config.ts', Icon: CodeXmlIcon, size: '412 B' },
  { name: 'CHANGELOG.md', Icon: FileTextIcon, size: '9.8 KB' },
]
const FOLDERS = ['app', 'components', 'lib', 'public']

/* One set of rows for both menus: the context menu and the visible ⋯ button offer the same actions. */
function FileActions({ name, onAction }: { name: string; onAction: (action: string) => void }) {
  return (
    <>
      <ContextMenuGroup>
        <ContextMenuLabel className="font-mono tracking-normal normal-case">{name}</ContextMenuLabel>
        <ContextMenuItem onClick={() => onAction(`Renaming ${name}`)}>
          <PencilIcon />
          Rename
          <ContextMenuShortcut>F2</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem onClick={() => onAction(`Duplicated ${name}`)}>
          <CopyIcon />
          Duplicate
          <ContextMenuShortcut>⌘D</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem onClick={() => onAction(`Copied the path of ${name}`)}>
          <ClipboardIcon />
          Copy path
        </ContextMenuItem>
      </ContextMenuGroup>
      <ContextMenuSeparator />
      <ContextMenuSub>
        <ContextMenuSubTrigger>
          <FolderIcon />
          Move to
        </ContextMenuSubTrigger>
        <ContextMenuSubContent>
          {FOLDERS.map((folder) => (
            <ContextMenuItem key={folder} className="font-mono text-ui-sm" onClick={() => onAction(`Moved ${name} to /${folder}`)}>
              /{folder}
            </ContextMenuItem>
          ))}
        </ContextMenuSubContent>
      </ContextMenuSub>
      <ContextMenuItem onClick={() => onAction(`Downloading ${name}`)}>
        <DownloadIcon />
        Download
      </ContextMenuItem>
      <ContextMenuSeparator />
      <ContextMenuItem variant="danger" onClick={() => onAction(`Deleted ${name}`)}>
        <TrashIcon />
        Delete
        <ContextMenuShortcut>⌘⌫</ContextMenuShortcut>
      </ContextMenuItem>
    </>
  )
}

function FileRow({ file, onAction }: { file: (typeof FILES)[number]; onAction: (action: string) => void }) {
  const [open, setOpen] = useState(false)
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex h-11 items-center gap-3 px-3 transition-[background-color] yj-duration-fast ease-standard hover:bg-hover data-popup-open:bg-hover">
        <file.Icon size={16} className="text-fg-muted" />
        {/* Something focusable inside the trigger: Shift+F10 or the Menu key opens the menu from it. */}
        <a
          href={`#${file.name}`}
          onClick={(event) => {
            event.preventDefault()
            onAction(`Opened ${file.name}`)
          }}
          className="min-w-0 flex-1 truncate rounded-sm font-mono text-ui-sm text-fg focus-ring"
        >
          {file.name}
        </a>
        <span className="w-16 text-end text-ui-sm text-fg-muted tabular-nums">{file.size}</span>
        <DropdownMenu open={open} onOpenChange={setOpen}>
          <DropdownMenuTrigger render={<Button variant="ghost" size="icon-sm" aria-label={`Actions for ${file.name}`} />}>
            <MoreHorizontalIcon active={open} />
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end" className="w-56">
            <FileActions name={file.name} onAction={onAction} />
          </DropdownMenuContent>
        </DropdownMenu>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-56">
        <FileActions name={file.name} onAction={onAction} />
      </ContextMenuContent>
    </ContextMenu>
  )
}

export default function ContextMenuDemo() {
  const [log, setLog] = useState('Right-click a file, or focus its name and press Shift+F10.')
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <ul aria-label="Files" className="overflow-hidden rounded-xl border border-line bg-surface shadow-xs">
        {FILES.map((file) => (
          <li key={file.name} className="border-b border-line last:border-b-0">
            <FileRow file={file} onAction={setLog} />
          </li>
        ))}
      </ul>
      <p role="status" className="px-1 text-ui-sm text-fg-muted">
        {log}
      </p>
    </div>
  )
}
```

A file list where right-clicking a row, or pressing its more button, opens the same actions.

### Anywhere on a surface

```tsx
'use client'

import { useState } from 'react'
import { cn } from '@youj/core'
import { ClipboardIcon, FileTextIcon, LayoutGridIcon } from '@youj/icons'
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from '@youj/react'

export default function ContextMenuCanvas() {
  const [grid, setGrid] = useState(true)
  const [snap, setSnap] = useState(false)
  const [zoom, setZoom] = useState('100')
  const [notes, setNotes] = useState(0)

return (
    <ContextMenu>
      {/* The menu opens at the pointer, wherever on the canvas the right-click lands. */}
      <ContextMenuTrigger
        render={<section aria-label="Canvas" tabIndex={0} />}
        className={cn(
          'relative flex h-60 w-full max-w-lg flex-col justify-end rounded-xl border border-dashed border-line bg-surface p-4 focus-ring',
          grid && 'bg-[radial-gradient(var(--color-line-strong)_1px,transparent_1px)] bg-size-[16px_16px]',
        )}
      >
        <p className="text-ui-sm text-fg-muted">
          {notes === 0 ? 'Right-click anywhere on the canvas.' : `${notes} ${notes === 1 ? 'note' : 'notes'} added.`} Zoom {zoom}%
          {snap ? ', snapping to the grid' : ''}.
        </p>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-56">
        <ContextMenuItem onClick={() => setNotes((n) => n + 1)}>
          <FileTextIcon />
          Add note
          <ContextMenuShortcut>N</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          <LayoutGridIcon />
          Add frame
          <ContextMenuShortcut>F</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem disabled>
          <ClipboardIcon />
          Paste
          <ContextMenuShortcut>⌘V</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuCheckboxItem checked={grid} onCheckedChange={setGrid}>
          Show grid
        </ContextMenuCheckboxItem>
        <ContextMenuCheckboxItem checked={snap} onCheckedChange={setSnap}>
          Snap to grid
        </ContextMenuCheckboxItem>
        <ContextMenuSeparator />
        <ContextMenuRadioGroup value={zoom} onValueChange={setZoom}>
          <ContextMenuLabel>Zoom</ContextMenuLabel>
          {['50', '100', '200'].map((level) => (
            <ContextMenuRadioItem key={level} value={level}>
              {level}%
            </ContextMenuRadioItem>
          ))}
        </ContextMenuRadioGroup>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

A canvas where a right-click opens the menu at the pointer.

The menu opens at the exact point of the right-click, a few pixels under the pointer, and flips to stay in the viewport. On a canvas, that point is the natural place for the new note. Checkbox and radio rows keep the menu open while settings change.

### Submenus

```tsx
'use client'

import { useState } from 'react'
import { FlagIcon, TagIcon, UserIcon } from '@youj/icons'
import {
  Badge,
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from '@youj/react'

const STATUSES = ['Backlog', 'Todo', 'In progress', 'Done']
const PEOPLE = ['Ana Lima', 'Kenji Sato', 'Priya Raman']
const LABELS = ['Bug', 'Performance', 'Edge runtime']

export default function ContextMenuIssue() {
  const [status, setStatus] = useState('In progress')
  const [assignee, setAssignee] = useState('Priya Raman')
  const [labels, setLabels] = useState(['Performance'])
  const toggle = (label: string) => (on: boolean) =>
    setLabels((list) => (on ? [...list, label] : list.filter((l) => l !== label)))

return (
    <ContextMenu>
      <ContextMenuTrigger className="w-full max-w-xs">
        <a
          href="#KIN-830"
          className="flex flex-col gap-2 rounded-xl border border-line bg-surface p-3.5 shadow-xs transition-[border-color] yj-duration-fast ease-standard hover:border-line-control focus-ring"
        >
          <span className="font-mono text-ui-sm text-fg-muted">KIN-830</span>
          <span className="text-ui font-medium text-fg">Cold starts regress on the edge runtime</span>
          <span className="flex flex-wrap items-center gap-1.5">
            <Badge variant="outline">{status}</Badge>
            {labels.map((label) => (
              <Badge key={label} variant="secondary">
                {label}
              </Badge>
            ))}
            <span className="ms-auto text-ui-sm text-fg-muted">{assignee}</span>
          </span>
        </a>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-52">
        <ContextMenuSub>
          <ContextMenuSubTrigger>
            <FlagIcon />
            Status
          </ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuRadioGroup value={status} onValueChange={setStatus}>
              {STATUSES.map((s) => (
                <ContextMenuRadioItem key={s} value={s}>
                  {s}
                </ContextMenuRadioItem>
              ))}
            </ContextMenuRadioGroup>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSub>
          <ContextMenuSubTrigger>
            <UserIcon />
            Assignee
          </ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuRadioGroup value={assignee} onValueChange={setAssignee}>
              {PEOPLE.map((person) => (
                <ContextMenuRadioItem key={person} value={person}>
                  {person}
                </ContextMenuRadioItem>
              ))}
            </ContextMenuRadioGroup>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSub>
          <ContextMenuSubTrigger>
            <TagIcon />
            Labels
          </ContextMenuSubTrigger>
          <ContextMenuSubContent>
            {LABELS.map((label) => (
              <ContextMenuCheckboxItem key={label} checked={labels.includes(label)} onCheckedChange={toggle(label)}>
                {label}
              </ContextMenuCheckboxItem>
            ))}
          </ContextMenuSubContent>
        </ContextMenuSub>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

An issue row whose menu has submenus for status, assignee and labels.

Submenus suit properties with several values: status, assignee, labels. Each opens beside its row, with a radio group for one-of-many and checkbox rows for tags.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add context-menu
```

It brings `dropdown-menu`, `presentation`, `youj-core`, `youj-ui-core` with it.

The copy is 10 registry items, about 8,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `dropdown-menu`, `icon-check`, `icon-chevron-right`, `icon-engine`, `presentation`, `sliding-indicator`.

Use a context menu as a shortcut to actions people can already reach another way: a file's rename and delete, a canvas's paste and zoom. It's easy to miss, and it's awkward on touch and for assistive technology, so give the same actions a visible control too. The file rows above pair each context menu with a ⋯ [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) built from the same rows. Don't make it the only way to do anything.

```tsx
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger } from '@youj/react'

export function FileRow({ file }: { file: File }) {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex items-center gap-3">
        <a href={file.url}>{file.name}</a>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuItem onClick={() => rename(file)}>Rename</ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem variant="danger" onClick={() => remove(file)}>
          Delete
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

`ContextMenuTrigger` is the area that opens the menu. Put something focusable in it, like the file's link in the Demo story, so the keyboard can open the menu too. The rows are the [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu)'s under other names (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuSub`…), so one set of rows can serve both menus, and they look and move the same.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### ContextMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | Where the portal renders. Default: document.body. |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popup at the pointer and a bottom sheet on touch; force either one. |

Base UI places the popup at the pointer unless you pass `side`, `align` or their offsets. `ContextMenu` takes the root props (`open`, `defaultOpen`, `onOpenChange`, `disabled`). The rows take the same props as the [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu#props)'s: `variant` and `inset` on items, `checked` on checkbox items, `value` on radio groups.

### Touch

On a touch device, pressing and holding the trigger for half a second opens the menu as the same action sheet `DropdownMenu` uses: it rises from the bottom of the screen with a grab handle, rows are 48px and shortcut hints are hidden. Pull it down, tap outside it or press Escape to close it. Base UI's trigger handles the long press itself, because iOS Safari never sends a `contextmenu` event. If the finger moves first, the press is canceled, so a list of triggers still scrolls. It also turns off the browser's own long-press callout and text selection on the trigger.

A long press is easy to miss on a phone, so make sure the same actions are reachable from a visible button too.

`presentation` on `ContextMenuContent` chooses: `auto` (the default) is a menu at the pointer under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the menu at the finger on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, out of the point it opened at (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Highlight | `spring.smooth` | 0.36s, bounce 0 | one `SlidingIndicator` per popup glides between rows |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws in when a row turns on |
| Keyboard open, Escape close |  | 0ms | Base UI sets `data-instant` |

**Reduced motion:** The menu appears at once, the highlight jumps from row to row, and checks appear already drawn.

Because the popup's `transform-origin` is the pointer's position, the menu grows out of the spot you clicked rather than out of a corner.

#### Reduced motion

The menu appears in place at the pointer and closes at once, and the highlight moves without gliding. Everything else behaves the same.

### Accessibility

- The menu is a `menu` with `menuitem`, `menuitemcheckbox` and `menuitemradio` rows, exactly like the dropdown menu, with the same keyboard support once open.
- `Shift+F10` and the `Menu` key open it from a focused element inside the trigger, just under that element. Browsers only send those keys as a `contextmenu` event on some platforms, so the trigger sends one itself.
- On touch, a long press opens it.
- Focus moves into the menu and returns to where it was when the menu closes.

| Key | Action |
| --- | --- |
| `Shift+F10` / `Menu` | Opens the menu from the focused element inside the trigger. |
| `↑` / `↓`, `Home` / `End` | Move between rows. Letters jump by typeahead. |
| `Enter` / `Space` | Runs the row, or toggles a checkbox or radio row. |
| `→` / `←` | Opens or closes a submenu. |
| `Escape` | Closes the menu. |

---

# Radial Menu

> A ring of actions that fans out around the pointer: hold, drag toward one and let go.

Source: https://www.youj.dev/docs/components/radial-menu

## Examples

### Canvas tools

```tsx
'use client'

import { useState } from 'react'
import { CodeIcon, FrameIcon, PenToolIcon, ShapesIcon, TypeIcon } from '@youj/icons'
import { RadialMenu, type RadialMenuItem } from '@youj/react'

const tools: RadialMenuItem[] = [
  { id: 'frame', label: 'Frame', icon: <FrameIcon /> },
  { id: 'text', label: 'Text', icon: <TypeIcon /> },
  { id: 'shape', label: 'Shape', icon: <ShapesIcon /> },
  { id: 'pen', label: 'Pen', icon: <PenToolIcon /> },
  { id: 'code', label: 'Code', icon: <CodeIcon /> },
]

export default function RadialMenuDemo() {
  // The ring renders inside this frame: `contain: paint` makes it the box the ring stays within.
  const [frame, setFrame] = useState<HTMLDivElement | null>(null)
  const [tool, setTool] = useState(tools[0] as RadialMenuItem)
  return (
    <div ref={setFrame} className="flex h-[380px] w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-line bg-canvas text-fg [contain:paint]">
      <header className="flex items-center gap-2 border-b border-line bg-surface px-4 py-2.5 text-ui">
        <span className="font-semibold">Landing page</span>
        <span className="ms-auto flex items-center gap-2 text-fg-muted">
          <span className="grid size-6 place-items-center rounded-md bg-selected text-fg [&_svg]:size-4">{tool.icon}</span>
          {tool.label}
        </span>
      </header>
      <RadialMenu
        items={tools}
        onSelect={setTool}
        container={frame}
        startAngle={-72}
        label="Tools"
        aria-label="Canvas. Press and hold, or press Enter, to pick a tool."
        className="relative flex-1 bg-well"
      >
        <div aria-hidden className="pointer-events-none absolute inset-0 m-auto h-32 w-56 rounded-lg border border-line bg-surface shadow-sm" />
        <p aria-hidden className="pointer-events-none absolute inset-x-0 bottom-4 text-center text-ui-sm text-fg-subtle">
          Press and hold anywhere, drag to a tool, let go
        </p>
      </RadialMenu>
    </div>
  )
}
```

A design canvas where pressing and holding anywhere opens a ring of tools around the pointer.

Drag toward a tool and let go to pick it, in one gesture. The slot is chosen by direction, as in a pie menu, so the pointer only has to head the right way. Letting go in the middle leaves the ring open, so you can click a tool instead. A quick click does nothing, so the canvas keeps its own clicks.

### Arc at an edge

```tsx
'use client'

import { useState } from 'react'
import { CopyIcon, LinkIcon, PencilIcon, ShareIcon, TrashIcon } from '@youj/icons'
import { RadialMenu, type RadialMenuItem } from '@youj/react'

const actions: RadialMenuItem[] = [
  { id: 'rename', label: 'Rename', icon: <PencilIcon /> },
  { id: 'copy', label: 'Duplicate', icon: <CopyIcon /> },
  { id: 'link', label: 'Copy link', icon: <LinkIcon /> },
  { id: 'share', label: 'Share', icon: <ShareIcon /> },
  { id: 'delete', label: 'Delete', icon: <TrashIcon /> },
]

export default function RadialMenuArc() {
  const [frame, setFrame] = useState<HTMLDivElement | null>(null)
  const [picked, setPicked] = useState<string | null>(null)
  return (
    <div ref={setFrame} className="flex h-[340px] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-line bg-canvas text-fg [contain:paint]">
      <p className="m-auto text-ui text-fg-muted">{picked ? `Picked ${picked}` : 'Click the button in the bar below'}</p>
      <footer className="flex justify-center border-t border-line bg-surface py-3">
        <RadialMenu
          items={actions}
          trigger="click"
          startAngle={-90}
          sweep={180}
          radius={96}
          container={frame}
          onSelect={(item) => setPicked(item.label)}
          label="Actions"
          aria-label="Actions"
          className="grid size-11 place-items-center rounded-full bg-accent text-ui-lg font-semibold text-on-accent shadow-md"
        >
          +
        </RadialMenu>
      </footer>
    </div>
  )
}
```

A button in a bottom bar whose actions fan upward in a half ring.

`startAngle={-90}` and `sweep={180}` make the arc run from the start side, over the top, to the end side. A full ring opened near an edge does this by itself: it shifts inward, and if it would have to move far from the pointer it becomes a half ring facing away from the edge.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add radial-menu
```

It brings `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-radial-menu`, `youj-presets`, `youj-ui-core` with it.

Use a radial menu for a handful of actions people repeat often on a surface: tools on a canvas, quick actions on a card. Directions are quick to learn and fast to repeat, but only up to about eight slots; for more, or for actions that need words, use a [Context Menu](https://www.youj.dev/docs/components/context-menu) or a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu). Like any gesture-only menu, give the same actions a visible control too.

```tsx
import { CodeIcon, FrameIcon, PenToolIcon, ShapesIcon, TypeIcon } from '@youj/icons'
import { RadialMenu, type RadialMenuItem } from '@youj/react'

export function Canvas({ onTool }: { onTool: (id: string) => void }) {
  return (
    <RadialMenu items={tools} onSelect={(item) => onTool(item.id)} label="Tools" aria-label="Canvas" className="h-96">
      {/* the canvas */}
    </RadialMenu>
  )
}
```

`RadialMenu` renders the trigger itself: a `div` with your `children`, `className` and props, or your own element through `render` (`render={<Button />}`). `trigger` says how a pointer opens it: `hold` (the default) after a press held still, `click`, or `contextmenu` for a right-click, where holding the button down and letting go on a slot picks it too. From the keyboard, Enter, Space, the context menu key and Shift+F10 open it on any trigger, centered on the trigger.

Each item is `{ id, label, icon, onSelect?, disabled? }`. The item's own `onSelect` runs first, then the menu's `onSelect` with the item. `open` can be controlled (`onOpenChange`), `radius` sets the distance to the slots (crowded slots push it out), `holdDelay` the hold in ms, and `sound={false}` silences its cues.

To keep the ring inside part of the page, as these previews do, pass that element as `container` and give it `contain: paint` (or a `transform`).

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `RadialMenuItem[]` |  |  |
| `trigger` | `'hold' \| 'click' \| 'contextmenu'` | `'hold'` | How a pointer opens it: a held press (default), a click, or a right-click. The keyboard opens it in every mode. |
| `radius` | `number` | `84` | Distance from the center to the slots' centers, in px. |
| `startAngle` | `number` | `0` | Where the first slot sits, in degrees: 0 is up, 90 is the inline end side. |
| `sweep` | `number` | `360` | How much of the circle the slots span, in degrees: 360 is a full ring, less is an arc whose ends hold a slot each. |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `onSelect` | `(item: RadialMenuItem) => void` |  | Runs with the chosen item, after the item's own `onSelect`. |
| `label` | `string` |  | The ring's accessible name. Default: the `actions` label. |
| `holdDelay` | `number` |  | How long a press is held before the ring opens, in ms. Default: the slow token. |
| `disabled` | `boolean` | `false` | The trigger opens nothing. |
| `sound` | `boolean` | `true` | Play the kit's cues: open, a tick per slot passed, select and close. |
| `container` | `HTMLElement \| null` |  | Where the ring renders. Default: the provider's portal container, else `document.body`. It must be a positioning context for `fixed` children. |

Also takes the props of `useRender.ComponentProps<'div'>`.

`RadialMenu` also takes a `div`'s props (or those of the element you `render`) for the trigger.

#### Data attributes

The trigger is `data-slot="radial-menu-trigger"` with `data-state` (`open` or `closed`), `data-yj-trigger` (its `trigger`) and `data-disabled`. The ring is `data-slot="radial-menu"` inside `radial-menu-layer`, the middle `radial-menu-hub`, and each slot `radial-menu-item` with `data-highlighted` while it's aimed at or focused and `data-disabled` when it can't be chosen.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fan out | `spring.smooth`, `stagger.tight` | 0.36s, bounce 0; 24ms step | the slots spring out from the center to the ring, one after another |
| Hub | `spring.snappy` | 0.2s, bounce 0 | the middle pops in and names the highlighted action; the name fades up as it changes |
| Highlight | `spring.snappy` | 0.2s, bounce 0 | the slot aimed at grows and fills with the accent, and an accent arc on the hub turns to point at it |
| Collapse | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the slots fall back into the center in reverse order and fade |

**Reduced motion:** The ring is there at once and gone at once; the highlight and the hub's label still change.

#### Sound

With sound on in the provider, the ring plays `open`, a `tick` for each slot it passes, `select` when an action is chosen and `close` when it's dismissed. `sound={false}` silences it.

### Accessibility

- The trigger is a button (`aria-haspopup="menu"`, `aria-expanded`) unless you render your own element. Name it with `aria-label` when its content doesn't say what it is.
- The ring is a `menu` named by `label` (default "Actions") and described by a hint on the keys; each slot is a `menuitem` named by its label.
- Focus moves into the ring when it opens: onto the first slot from the keyboard, onto the ring from a pointer. Focus follows the highlight, so pointer and keyboard share one place.
- ← and → (swapped in right-to-left) and ↑ and ↓ go around the ring, skipping disabled slots; Home and End go to the first and last. Enter or Space chooses.
- Escape, Tab or a click outside closes the ring and returns focus to the trigger.
- The chosen action is announced politely: "Pen chosen".
- In right-to-left the ring is mirrored, so the slots run counterclockwise from the start.

---

# Command

> Search and choose commands or options inline, in a popover or in a dialog.

Source: https://www.youj.dev/docs/components/command

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  CreditCardIcon,
  FilePlusIcon,
  GitBranchIcon,
  GlobeIcon,
  InboxIcon,
  RocketIcon,
  SettingsIcon,
  UserIcon,
} from '@youj/icons'
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from '@youj/react/command'

export default function CommandDemo() {
  const [ran, setRan] = useState('')

return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Command label="Command menu" className="rounded-xl border border-line shadow-md">
        <CommandInput placeholder="Type a command or search…" />
        <CommandList className="[--command-list-max:18rem]">
          <CommandEmpty>No commands match.</CommandEmpty>
          <CommandGroup heading="Project">
            <CommandItem onSelect={() => setRan('Deploy to production')}>
              <RocketIcon />
              Deploy to production
              <CommandShortcut>⌘⇧D</CommandShortcut>
            </CommandItem>
            <CommandItem onSelect={() => setRan('Create preview branch')}>
              <GitBranchIcon />
              Create preview branch
              <CommandShortcut>B</CommandShortcut>
            </CommandItem>
            <CommandItem onSelect={() => setRan('Add domain')}>
              <GlobeIcon />
              Add domain
            </CommandItem>
            <CommandItem onSelect={() => setRan('New environment variable')}>
              <FilePlusIcon />
              New environment variable
              <CommandShortcut>E</CommandShortcut>
            </CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="Go to">
            <CommandItem onSelect={() => setRan('Go to inbox')}>
              <InboxIcon />
              Inbox
              <CommandShortcut>G I</CommandShortcut>
            </CommandItem>
            <CommandItem onSelect={() => setRan('Go to profile')}>
              <UserIcon />
              Profile
              <CommandShortcut>G P</CommandShortcut>
            </CommandItem>
            <CommandItem onSelect={() => setRan('Go to billing')}>
              <CreditCardIcon />
              Billing
            </CommandItem>
            {/* Disabled rows stay visible and are skipped by the arrows. */}
            <CommandItem disabled>
              <SettingsIcon />
              Team settings
              <CommandShortcut>Owners</CommandShortcut>
            </CommandItem>
          </CommandGroup>
        </CommandList>
      </Command>
      <p role="status" className="h-5 px-1 text-ui-sm text-fg-muted">
        {ran && `Ran “${ran}”`}
      </p>
    </div>
  )
}
```

A command menu with grouped actions and shortcuts; choosing one reports what ran below.

### In a popover

```tsx
'use client'

import { useState } from 'react'
import { AlertTriangleIcon, BanIcon, CheckCircleIcon, ClockIcon, LoaderDotsIcon, PlusIcon } from '@youj/icons'
import {
  Badge,
  Button,
  Popover,
  PopoverContent,
  PopoverTrigger,
  Separator,
} from '@youj/react'
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from '@youj/react/command'

const STATUSES = [
  { value: 'ready', label: 'Ready', Icon: CheckCircleIcon, count: 64 },
  { value: 'building', label: 'Building', Icon: LoaderDotsIcon, count: 2 },
  { value: 'queued', label: 'Queued', Icon: ClockIcon, count: 5 },
  { value: 'error', label: 'Error', Icon: AlertTriangleIcon, count: 3 },
  { value: 'canceled', label: 'Canceled', Icon: BanIcon, count: 1 },
]

export default function CommandFilter() {
  const [selected, setSelected] = useState(new Set(['building', 'error']))
  const toggle = (value: string) =>
    setSelected((current) => {
      const next = new Set(current)
      if (next.has(value)) next.delete(value)
      else next.add(value)
      return next
    })

return (
    <div className="flex h-80 w-full max-w-md items-start">
      <Popover>
        {/* shape: dashed, an add slot (as the data table's filter buttons) */}
        <PopoverTrigger render={<Button variant="outline" size="sm" className="border-dashed" />}>
          <PlusIcon />
          Status
          {selected.size > 0 && (
            <>
              <Separator orientation="vertical" className="mx-0.5 h-4 self-center" />
              <Badge variant="secondary">{selected.size} selected</Badge>
            </>
          )}
        </PopoverTrigger>
        {/* A faceted filter: the shape a data table toolbar uses. */}
        <PopoverContent align="start" aria-label="Filter by status" className="w-56 gap-0 p-0">
          <Command label="Filter by status">
            <CommandInput placeholder="Status" />
            <CommandList>
              <CommandEmpty>No status found.</CommandEmpty>
              <CommandGroup>
                {STATUSES.map(({ value, label, Icon, count }) => (
                  <CommandItem key={value} value={label} checked={selected.has(value)} onSelect={() => toggle(value)}>
                    {/* Loader icons loop by default. In a list, they play on hover like the rest. */}
                    <Icon trigger="hover" />
                    {label}
                    <span className="ms-auto font-mono text-ui-xs text-fg-muted tabular-nums">{count}</span>
                  </CommandItem>
                ))}
              </CommandGroup>
              {selected.size > 0 && (
                <>
                  <CommandSeparator />
                  <CommandGroup>
                    <CommandItem onSelect={() => setSelected(new Set())} className="justify-center">
                      Clear filters
                    </CommandItem>
                  </CommandGroup>
                </>
              )}
            </CommandList>
          </Command>
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

A status filter: Command inside a Popover, with checked rows you can toggle.

Command in a Popover makes a picker or a faceted filter, the shape a data table toolbar uses. Give rows a `checked` state and each gets a trailing check that draws itself in, plus `aria-checked` for assistive technology, so the list works as a multi-select.

### Results from a server

```tsx
'use client'

import { useEffect, useState } from 'react'
import { UserIcon } from '@youj/icons'
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandLoading } from '@youj/react/command'

const DIRECTORY = ['Ana Lima', 'Amara Okafor', 'Jonas Weber', 'Kenji Sato', 'Lucía Torres', 'Mateo Rossi', 'Priya Raman', 'Sara Lindqvist']

/* Stands in for a request to your API. */
function searchPeople(query: string) {
  return new Promise<string[]>((resolve) =>
    setTimeout(() => resolve(DIRECTORY.filter((name) => name.toLowerCase().includes(query.toLowerCase()))), 600),
  )
}

export default function CommandAsync() {
  const [search, setSearch] = useState('')
  const [results, setResults] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const [assigned, setAssigned] = useState('')

useEffect(() => {
    if (!search) {
      setResults([])
      setLoading(false)
      return
    }
    let live = true
    setLoading(true)
    searchPeople(search).then((found) => {
      if (!live) return
      setResults(found)
      setLoading(false)
    })
    return () => {
      live = false
    }
  }, [search])

return (
    <div className="flex min-h-80 w-full max-w-xs flex-col gap-3">
      {/* The results arrive already matched, so cmdk's own filtering is off. */}
      <Command label="Assign to" shouldFilter={false} className="rounded-xl border border-line shadow-md">
        <CommandInput value={search} onValueChange={setSearch} placeholder="Search people (try “a”)…" />
        <CommandList>
          {loading && <CommandLoading label="Searching the directory…" />}
          <CommandEmpty>{search ? `Nobody called “${search}”.` : 'Start typing to search.'}</CommandEmpty>
          {!loading && results.length > 0 && (
            <CommandGroup heading="People">
              {results.map((name) => (
                <CommandItem key={name} value={name} onSelect={() => setAssigned(name)}>
                  <UserIcon />
                  {name}
                </CommandItem>
              ))}
            </CommandGroup>
          )}
        </CommandList>
      </Command>
      <p role="status" className="h-5 px-1 text-ui-sm text-fg-muted">
        {assigned && `Assigned KIN-830 to ${assigned}`}
      </p>
    </div>
  )
}
```

Results that arrive from a request, with a loading row while it runs.

When results come from a request, turn off cmdk's filtering with `shouldFilter={false}`, control the search, and show a `CommandLoading` row while the request runs. `CommandEmpty` waits while a loading row is shown, since nothing having arrived yet isn't the same as no results.

### In a dialog

```tsx
'use client'

import { useState } from 'react'
import { FilePlusIcon, FilterIcon, InboxIcon, SearchIcon } from '@youj/icons'
import { Button } from '@youj/react'
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandShortcut,
} from '@youj/react/command'

export default function CommandInDialog() {
  const [open, setOpen] = useState(false)

return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)} className="w-64 justify-start text-fg-muted">
        <SearchIcon />
        Search commands…
      </Button>
      {/* Hung from the top third of the screen, so the input stays put while the list grows and shrinks. */}
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Type a command or search…" wrapperClassName="h-12 px-4" className="text-ui-lg" />
          <CommandList className="[--command-list-max:22rem]">
            <CommandEmpty>No results.</CommandEmpty>
            <CommandGroup heading="Suggestions">
              <CommandItem onSelect={() => setOpen(false)}>
                <FilePlusIcon />
                Create issue
                <CommandShortcut>C</CommandShortcut>
              </CommandItem>
              <CommandItem onSelect={() => setOpen(false)}>
                <FilterIcon />
                Filter issues
                <CommandShortcut>F</CommandShortcut>
              </CommandItem>
              <CommandItem onSelect={() => setOpen(false)}>
                <InboxIcon />
                Go to inbox
                <CommandShortcut>G I</CommandShortcut>
              </CommandItem>
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </>
  )
}
```

A command palette in a dialog, opened from a button.

`CommandDialog` puts a Command in a [Dialog](https://www.youj.dev/docs/components/dialog) that hangs from the top third of the screen, so the input never moves as the list grows and shrinks. It's named "Command palette" for screen readers unless you pass a `title`. This one opens from a button: this site already uses ⌘K (Ctrl K on Windows and Linux) for its own search. For the full palette, with pages and a global shortcut, use [Command Palette](https://www.youj.dev/docs/components/command-palette).

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add command
```

It brings `checkbox`, `dialog`, `icon-check`, `icon-search`, `presentation`, `sliding-indicator`, `spinner`, `youj-core`, `youj-labels-command`, `youj-presets`, `youj-ui-core` with it.

The copy is 22 registry items, about 9,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `checkbox`, `collapse`, `dialog`, `field`, `icon-check`, `icon-engine`, `icon-loader-ring`, `icon-search`, `label` and 4 more.

Requires `cmdk`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/command`.

Use Command to search a list of actions or options. Place it inline, in a [Popover](https://www.youj.dev/docs/components/popover), or in `CommandDialog`. Use [Command Palette](https://www.youj.dev/docs/components/command-palette) for an app-wide shortcut with nested pages and back navigation. For short lists, use [Select](https://www.youj.dev/docs/components/select) or [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu).

```tsx
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from '@youj/react/command'

export function CommandMenu() {
  return (
    <Command label="Command menu" className="rounded-xl border">
      <CommandInput placeholder="Type a command or search…" />
      <CommandList>
        <CommandEmpty>No commands match.</CommandEmpty>
        <CommandGroup heading="Project">
          <CommandItem onSelect={deploy}>
            Deploy to production
            <CommandShortcut>⌘⇧D</CommandShortcut>
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Go to">
          <CommandItem onSelect={openInbox}>Inbox</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}
```

Command is [cmdk](https://cmdk.paco.me), restyled. Typing filters and ranks the rows and keeps the first match active. `onSelect` runs on click and on `Enter`. A row's `value` is what the search matches (its text by default), and `keywords` add more terms. `label` names the search field for screen readers ("Search" by default). Arrow keys wrap around from the last row to the first.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### CommandItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean \| 'mixed'` |  | For multi-select lists (a filter): a trailing check that draws in, and aria-checked on the option. `'mixed'` is for a "select all" row over a partial selection. Leave undefined for plain commands. |
| `indicator` | `'check' \| 'checkbox'` | `'check'` | How `checked` shows: a trailing check (default) or a leading checkbox. |

Also takes the props of `ComponentProps<typeof CommandPrimitive.Item>`.

#### CommandInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapperClassName` | `string` |  |  |
| `expanded` | `boolean` |  | Whether the list is showing. Leave unset when it always is (cmdk's default). |

#### CommandLoading

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Loading…"` | Announced politely while the row is shown, and shown when there are no children. |

Also takes the props of `ComponentProps<'div'>`.

#### CommandSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alwaysRender` | `boolean` |  |  |

#### CommandDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Command palette"` | Names the dialog for screen readers. |
| `description` | `string` |  | Describes the dialog for screen readers. |
| `className` | `string` |  |  |
| `showCloseButton` | `boolean` | `false` |  |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a dialog under a pointer and a tall bottom sheet on touch; force either one. |
| `autoFocusField` | `boolean` |  | Whether the search field takes focus on open. By default it does when opened from a keyboard or a mouse, and not when opened by a touch, so the on-screen keyboard doesn't cover the list before it is seen. Pass true when the dialog is opened to type in (a search button); on iOS also call `primeKeyboard()` in that button's tap handler, or iOS won't raise the keyboard for a focus that comes after the tap. |
| `children` (required) | `ReactNode` |  |  |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), opening plays `open` and closing `close`. `false` keeps this dialog silent. |

`Command` passes its props to cmdk's root: `label`, `shouldFilter`, `filter`, `value` and `onValueChange` for the active row, and `loop`, which is on here. `CommandList`, `CommandGroup` (`heading`), `CommandEmpty` and `CommandShortcut` take cmdk's or plain element props.

### Touch

Inside a bottom sheet (a Combobox, a MultiSelect or a `CommandDialog` on touch) the parts restyle themselves: the search row becomes a filled search field that stays at the top while the list scrolls under it, rows are 48px with 16px text, and `CommandShortcut` hints are hidden. The highlight only shows while the field has focus, when Enter would pick it; otherwise a row darkens under the finger.

On a touch device `CommandDialog` is a tall bottom sheet instead of a dialog in the middle of the screen. Its height stays the same as results change, and while the on-screen keyboard is up the sheet sits on top of it, so the search field stays visible. Pull it down, tap outside it or press Escape to close it. It opens with the list in view and the keyboard down. If it opens from a search button, where people expect to type right away, pass `autoFocusField`. iOS only raises the keyboard for a focus that happens during the tap itself, and the field appears a moment later, so also call `primeKeyboard()` from `@youj/react` in that button's handler before you open the dialog.

`presentation` on `CommandDialog` chooses: `auto` (the default) is a dialog under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the dialog on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Active row | `spring.smooth` | 0.36s, bounce 0 | one `SlidingIndicator` glides between rows and retargets while a key repeats |
| List height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | eases as results come and go, up to `--command-list-max` |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | `checked` rows, draws in |
| Dialog open | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | `CommandDialog`, rise and scale (`yj-dialog`) |
| Dialog close | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |

**Reduced motion:** The highlight jumps to the active row, the list snaps to its new height, checks appear drawn and the dialog appears at once.

While you type, the highlight stays still: filtering keeps the first result active, so only the list around it changes height. The list is capped at 20rem by default and scrolls past that. Change the cap with the `--command-list-max` custom property on `CommandList`, as the examples above do.

#### Reduced motion

The active row's highlight jumps instead of gliding, and the list snaps to its new height. Checks appear already drawn, and `CommandDialog` opens and closes at once. Filtering, announcements and keyboard behavior don't change.

### Accessibility

- The input is a `combobox` that controls a `listbox`. The active row is tracked with `aria-activedescendant`, so focus stays in the input while you move through the results.
- Groups are `group`s named by their headings. Separators, the loading row and the highlight are hidden from assistive technology, because a listbox may only contain options and groups.
- The list keeps a status region beside it. It announces "no results" and the loading label, which the listbox itself can't.
- `CommandDialog` is a named dialog that focuses the input when it opens and returns focus to its trigger when it closes.

| Key | Action |
| --- | --- |
| `↑` / `↓` | Moves the active row, wrapping at the ends. Disabled rows are skipped. |
| `Home` / `End` | Jumps to the first or last row. |
| `Ctrl+N` / `Ctrl+P` | Next and previous row, for Emacs and Vim habits. |
| `Enter` | Runs the active row. |
| `Escape` | Closes `CommandDialog`. |

---

# Tabs

> Switch between related panels of content in the same space.

Source: https://www.youj.dev/docs/components/tabs

## Examples

### Demo

```tsx
'use client'

import { Badge, Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'

const STATS = [
  { label: 'Requests (24h)', value: '1.28M', delta: '+8.2%' },
  { label: 'p95 latency', value: '82 ms', delta: '−6 ms' },
  { label: 'Error rate', value: '0.02%' },
]

const DEPLOYS = [
  { id: 'dpl_8f2a', branch: 'main', message: 'Tighten the pricing grid on mobile', age: '4m', ready: true },
  { id: 'dpl_77c1', branch: 'feat/onboarding', message: 'Copy pass on the welcome step', age: '38m', ready: true },
  { id: 'dpl_65d0', branch: 'fix/og-image', message: 'Regenerate the OG image at 2x', age: '2h', ready: false },
]

// A day of traffic, one bar per hour.
const TRAFFIC = Array.from({ length: 24 }, (_, i) => 30 + Math.round(60 * Math.abs(Math.sin(i * 0.45))))

export default function TabsDemo() {
  return (
    <div className="@container w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-canvas">
      <p className="flex items-center gap-2 px-5 pt-4 text-ui text-fg-muted">
        acme <span aria-hidden>/</span> <span className="font-medium text-fg">web</span>
      </p>
      <Tabs defaultValue="overview" className="mt-1.5 gap-0">
        <TabsList inset aria-label="Project" className="[--tabs-inset:--spacing(5)]">
          <TabsTrigger value="overview">Overview</TabsTrigger>
          <TabsTrigger value="deployments">
            Deployments
            <Badge variant="secondary" className="px-1.5 tabular-nums">
              12
            </Badge>
          </TabsTrigger>
          <TabsTrigger value="analytics">Analytics</TabsTrigger>
          <TabsTrigger value="logs">Logs</TabsTrigger>
          <TabsTrigger value="settings">Settings</TabsTrigger>
        </TabsList>
        <div className="min-h-44 bg-surface p-5">
          <TabsContent value="overview">
            <div className="grid gap-3 @md:grid-cols-3">
              {STATS.map((stat) => (
                <div key={stat.label} className="rounded-lg border border-line bg-canvas px-4 py-3">
                  <p className="text-ui-sm text-fg-muted">{stat.label}</p>
                  <p className="mt-1 text-xl font-semibold tracking-tight text-fg tabular-nums">{stat.value}</p>
                  {stat.delta && <p className="text-ui-sm text-success-text tabular-nums">{stat.delta}</p>}
                </div>
              ))}
            </div>
          </TabsContent>
          <TabsContent value="deployments">
            <ul className="divide-y divide-line rounded-lg border border-line bg-canvas">
              {DEPLOYS.map((deploy) => (
                <li key={deploy.id} className="flex items-center gap-3 px-4 py-2.5 text-ui">
                  <span aria-hidden className={`size-2 shrink-0 rounded-full ${deploy.ready ? 'bg-success' : 'bg-danger'}`} />
                  <span className="sr-only">{deploy.ready ? 'Ready' : 'Failed'}:</span>
                  <span className="min-w-0 flex-1 truncate text-fg">{deploy.message}</span>
                  <span className="hidden font-mono text-ui-sm text-fg-muted @md:inline">{deploy.branch}</span>
                  <span className="w-8 text-end text-ui-sm text-fg-muted tabular-nums">{deploy.age}</span>
                </li>
              ))}
            </ul>
          </TabsContent>
          <TabsContent value="analytics">
            <div role="img" aria-label="Requests per hour over the last 24 hours" className="flex h-32 items-end gap-1">
              {TRAFFIC.map((height, hour) => (
                <span key={hour} className="flex-1 rounded-sm bg-accent-line" style={{ height: `${height}%` }} />
              ))}
            </div>
          </TabsContent>
          <TabsContent value="logs">
            <pre dir="ltr" className="overflow-x-auto rounded-lg bg-band px-3 py-2.5 font-mono text-ui-sm leading-6 text-fg-muted">
              {'12:04:11  GET   /api/pricing   200   38ms\n12:04:12  GET   /              200   12ms\n12:04:15  POST  /api/checkout  201  211ms'}
            </pre>
          </TabsContent>
          <TabsContent value="settings">
            <p className="text-fg-muted">Build command, output directory and environment variables for web.</p>
          </TabsContent>
        </div>
      </Tabs>
    </div>
  )
}
```

A project page with Overview, Deployments and Analytics tabs on a full-bleed list.

A list that runs edge to edge, like the one under a project's name in the Demo story, still wants its tabs on the content's inset. Pass `inset` and set the inset with `--tabs-inset` on the list. Inside a Card it defaults to the card's own inset, and elsewhere to 1rem.

```tsx
<TabsList inset aria-label="Project" className="[--tabs-inset:--spacing(5)]">
```

Underline tabs line their labels up with the inset, and their hairline still spans the row. A track lines its edge up with the inset instead, which is how pill tabs behave. Don't pad the list for this. A pill list in the Bezel style resets its padding and is a track just wide enough for its tabs. For split tabs that share the row, give the list `flex-1` and each trigger `flex-1`.

### Pill

```tsx
'use client'

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'
import { TerminalIcon } from '@youj/icons'

const COMMANDS = {
  pnpm: 'pnpm add @youj/react',
  npm: 'npm install @youj/react',
  yarn: 'yarn add @youj/react',
  bun: 'bun add @youj/react',
}

export default function TabsPill() {
  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <Tabs defaultValue="pnpm" className="gap-0">
        <div className="flex items-center justify-between gap-3 border-b border-line py-2 ps-3 pe-2">
          <span className="flex items-center gap-2 text-ui text-fg-muted">
            <TerminalIcon size={16} />
            Install
          </span>
          {/* A raised key in a recessed track: the segmented look, for short labels. */}
          <TabsList variant="pill" aria-label="Package manager">
            {Object.keys(COMMANDS).map((manager) => (
              <TabsTrigger key={manager} value={manager} className="font-mono text-ui-sm">
                {manager}
              </TabsTrigger>
            ))}
          </TabsList>
        </div>
        {Object.entries(COMMANDS).map(([manager, command]) => (
          <TabsContent key={manager} value={manager} className="px-4 py-4">
            <code className="font-mono text-ui text-fg">
              <span className="text-fg-muted select-none">$ </span>
              {command}
            </code>
          </TabsContent>
        ))}
      </Tabs>
    </div>
  )
}
```

Tabs in the pill variant, a recessed track with a raised key.

`variant="pill"` raises a key out of a recessed track. It suits a few short labels in a toolbar or a card header.

### Vertical

```tsx
'use client'

import { Button, Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'
import { CreditCardIcon, KeyIcon, PlugIcon, SettingsIcon, ShieldCheckIcon, UsersIcon } from '@youj/icons'

const SECTIONS = [
  { value: 'general', label: 'General', Icon: SettingsIcon, body: 'Workspace name, URL and default region.' },
  { value: 'members', label: 'Members', Icon: UsersIcon, body: '8 members and 1 pending invite. Roles decide who can deploy.' },
  { value: 'billing', label: 'Billing', Icon: CreditCardIcon, body: 'Pro plan, renews on the 1st. Usage alerts at 80%.' },
  { value: 'security', label: 'Security', Icon: ShieldCheckIcon, body: 'SAML SSO, enforced two-factor sign-in and the audit log.' },
  { value: 'integrations', label: 'Integrations', Icon: PlugIcon, body: 'GitHub, Slack and Linear are connected.' },
  { value: 'tokens', label: 'API tokens', Icon: KeyIcon, body: '3 active tokens. The oldest expires in 12 days.' },
]

export default function TabsVertical() {
  return (
    <div className="@container w-full max-w-2xl">
      {/* Vertical tabs use ↑ ↓. Below the container's lg width the list stacks above the panel. */}
      <Tabs defaultValue="members" orientation="vertical" className="flex-col gap-4 @lg:flex-row @lg:gap-6">
        <TabsList aria-label="Settings" className="w-full @lg:w-44">
          {SECTIONS.map(({ value, label, Icon }) => (
            <TabsTrigger key={value} value={value}>
              <Icon size={16} />
              {label}
            </TabsTrigger>
          ))}
        </TabsList>
        {SECTIONS.map(({ value, label, body }) => (
          <TabsContent key={value} value={value} className="rounded-xl border border-line bg-surface p-5">
            <p className="text-ui-lg font-semibold text-fg">{label}</p>
            <p className="mt-1.5 text-fg-muted">{body}</p>
            <Button variant="outline" size="sm" className="mt-4">
              Manage {label.toLowerCase()}
            </Button>
          </TabsContent>
        ))}
      </Tabs>
    </div>
  )
}
```

A vertical tab list beside its panels, for a settings page.

Set `orientation="vertical"` on `Tabs` to stack the list beside its panels. The arrow keys become ↑ and ↓, and the underline becomes a bar on the list's start edge. It suits settings pages with more sections than fit across.

### Many tabs

```tsx
'use client'

import { useState } from 'react'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'
import { FileTextIcon } from '@youj/icons'

const FILES = [
  'page.tsx',
  'layout.tsx',
  'pricing-grid.tsx',
  'checkout-button.tsx',
  'use-subscription.ts',
  'stripe.server.ts',
  'plans.json',
  'globals.css',
  'middleware.ts',
  'next.config.ts',
  'README.md',
  'package.json',
]

export default function TabsOverflow() {
  const [file, setFile] = useState('pricing-grid.tsx')

return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      {/* Twelve tabs in a narrow editor: the list scrolls, its edges fade, and the selected tab scrolls into view. */}
      <Tabs value={file} onValueChange={(value) => setFile(value as string)} className="gap-0">
        <TabsList inset aria-label="Open files" className="[--tabs-inset:--spacing(4)]">
          {FILES.map((name) => (
            <TabsTrigger key={name} value={name} className="font-mono text-ui-sm">
              <FileTextIcon size={16} className="text-fg-muted" />
              {name}
            </TabsTrigger>
          ))}
        </TabsList>
        {FILES.map((name) => (
          <TabsContent key={name} value={name} className="px-4 py-4">
            <pre dir="ltr" className="font-mono text-ui-sm leading-6 text-fg-muted">
              {`// app/(marketing)/pricing/${name}\n// Last edited by Priya Raman, 2 hours ago`}
            </pre>
          </TabsContent>
        ))}
      </Tabs>
    </div>
  )
}
```

A tab list that scrolls when it runs out of room.

A horizontal list that runs out of room scrolls without a scrollbar. Its edges fade in proportion to how far there is left to scroll, chevrons appear for pointer users, and a newly selected tab scrolls itself into view. Keyboard users keep pressing the arrow keys.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tabs
```

It brings `icon-chevron-left`, `icon-chevron-right`, `sliding-indicator`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Tabs for related views, such as a project’s overview, deployments and settings. Each tab shows its own panel. To choose a value or filter, use a segmented [Toggle Group](https://www.youj.dev/docs/components/toggle-group). To navigate between pages, use links in a [Sidebar](https://www.youj.dev/docs/components/sidebar) or [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu).

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'

export function ProjectTabs() {
  return (
    <Tabs defaultValue="overview">
      <TabsList aria-label="Project">
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="deployments">Deployments</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">…</TabsContent>
      <TabsContent value="deployments">…</TabsContent>
      <TabsContent value="settings">…</TabsContent>
    </Tabs>
  )
}
```

Each `TabsTrigger` selects the `TabsContent` with the same `value`. Name the list with `aria-label` or `aria-labelledby`, so screen readers announce what the tabs switch between. To control the selection, pass `value` and `onValueChange` to `Tabs`.

The default `underline` list is plain labels on a hairline: muted until hovered, the selected one in full ink over a 2px accent bar that glides between tabs. It looks the same in every component style. Move across the tabs in the Demo story, or Tab into them and press ← and →.

### Selection and focus

By default the arrow keys move focus and select in one step (`activateOnFocus`), which the ARIA Authoring Practices recommend when panels show without delay. If a panel fetches data or takes a while to render, turn it off: the arrows then only move focus, and Enter or Space selects.

```tsx
<TabsList aria-label="Reports" activateOnFocus={false}>
```

A disabled tab stays focusable, so people can discover it, but it's never selected.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### TabsList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'underline' \| 'pill'` | `'underline'` |  |
| `activateOnFocus` | `boolean` | `true` | Selection follows focus as the arrow keys move. |
| `inset` | `boolean` | `false` | For a horizontal list that spans its container, edge to edge: keep the tabs on the content's inset, `--tabs-inset` (set it on the list; default the card's `--card-spacing`, else 1rem). Underline tabs line their labels up with it and their hairline still spans; a track (pill tabs) lines its edge up with it. |

Also takes the props of `TabsPrimitive.List.Props`.

#### Tabs, TabsTrigger and TabsContent

These pass their props through to Base UI's `Tabs.Root`, `Tabs.Tab` and `Tabs.Panel`. The ones you'll use most:

| Part | Prop | Type | Default |
| --- | --- | --- | --- |
| `Tabs` | `defaultValue` | `any` | `0` |
| `Tabs` | `value`, `onValueChange` | `any`, `(value, details) => void` | – |
| `Tabs` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
| `TabsTrigger` | `value` (required) | `any` | – |
| `TabsTrigger` | `disabled` | `boolean` | `false` |
| `TabsContent` | `value` (required) | `any` | – |
| `TabsContent` | `keepMounted` | `boolean` | `false` |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Indicator | `spring.smooth` | 0.36s, bounce 0 | glides to the selected tab, transform only |
| Panel | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades in with a 4px drift from the side the selection moved to |
| Tab color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |

**Reduced motion:** The indicator jumps to the selected tab, panels appear without a fade or drift, and a long list scrolls to the selected tab without smoothing.

The outgoing panel hides at once, so two panels never share the space. A new selection mid-glide retargets the indicator from where it is, keeping its velocity. Resizes, font loads and right-to-left layouts re-place the indicator without animating.

#### Reduced motion

Selection works exactly the same. The indicator jumps instead of gliding, the panel appears without its fade and drift, and a long list jumps to the selected tab instead of scrolling smoothly. Switch on Reduced motion in any preview to compare.

### Accessibility

- The list is a `tablist`, named by its `aria-label`. Each trigger is a `tab` with `aria-selected`, and each panel is a `tabpanel` labeled by its tab.
- The list is one tab stop. Tab moves from the selected tab into the panel.
- The indicators and the scroll chevrons are hidden from assistive technology. The chevrons are pointer-only and never take focus, because the focused tab scrolls itself into view.

| Key | Action |
| --- | --- |
| ← → | Move to the previous or next tab and select it. Focus loops at the ends. |
| ↑ ↓ | The same, in a vertical list. |
| Home / End | Move to the first or last tab. |
| Enter / Space | Select the focused tab, when `activateOnFocus` is off. |
| Tab | Leave the list for the panel. |

---

# Accordion

> Expand and collapse sections to show the content you need.

Source: https://www.youj.dev/docs/components/accordion

## Examples

### Demo

```tsx
'use client'

import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@youj/react'

const FAQ = [
  {
    id: 'seats',
    question: 'What counts as a seat?',
    answer:
      'Anyone who can sign in to the workspace. Guests who only view shared links are free, and seats are prorated to the day when someone joins or leaves.',
  },
  {
    id: 'plans',
    question: 'Can I change plans mid-cycle?',
    answer: 'Yes. Upgrades apply at once and are prorated. Downgrades take effect at the end of the billing period, so you keep what you paid for.',
  },
  {
    id: 'limits',
    question: 'What happens if we go over a usage limit?',
    answer:
      'Nothing breaks. Billing contacts get an email at 80% and 100%, and overage is billed at the same unit price. Set a spend limit to pause new deployments instead.',
  },
  {
    id: 'open-source',
    question: 'Do you offer discounts for open source?',
    answer: 'Public, non-commercial projects get the Pro plan free. Apply from Settings → Billing with a link to the repository.',
  },
]

export default function AccordionDemo() {
  return (
    <div className="w-full max-w-xl">
      {/* Each trigger is an h3, so the section that holds them gets an h2. */}
      <h2 className="mb-1 text-ui-lg font-semibold text-fg">Billing questions</h2>
      {/* One open at a time. hiddenUntilFound lets the browser's find-in-page open a closed answer. */}
      <Accordion defaultValue={['seats']} hiddenUntilFound>
        {FAQ.map(({ id, question, answer }) => (
          <AccordionItem key={id} value={id}>
            <AccordionTrigger>{question}</AccordionTrigger>
            <AccordionContent>{answer}</AccordionContent>
          </AccordionItem>
        ))}
      </Accordion>
    </div>
  )
}
```

A set of frequently asked questions where opening one item closes the others.

### Several open at once

```tsx
'use client'

import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Badge } from '@youj/react'
import { AlertTriangleIcon, CheckCircleIcon, LoaderRingIcon } from '@youj/icons'

const CHECKS = [
  { id: 'build', title: 'Build', status: 'passed', detail: 'Compiled 214 modules in 18.4s. Output: 1.9 MB, 312 KB gzipped.' },
  { id: 'types', title: 'Type check', status: 'passed', detail: 'No errors in 1,208 files.' },
  {
    id: 'bundle',
    title: 'Bundle size',
    status: 'warning',
    detail: 'The pricing route grew by 38 KB (+12%). Most of it is date-fns/locale, imported in pricing-grid.tsx.',
  },
  { id: 'e2e', title: 'End-to-end tests', status: 'running', detail: '41 of 96 specs done on 4 workers.' },
] as const

const STATUS = {
  passed: { Icon: CheckCircleIcon, tone: 'text-success', badge: 'success', label: 'Passed' },
  warning: { Icon: AlertTriangleIcon, tone: 'text-warning', badge: 'warning', label: 'Warning' },
  running: { Icon: LoaderRingIcon, tone: 'text-fg-muted', badge: 'secondary', label: 'Running' },
} as const

export default function AccordionMultiple() {
  return (
    <div className="w-full max-w-xl rounded-xl border border-line bg-surface px-4">
      {/* `multiple` keeps several open. The running check is disabled until it finishes. */}
      <Accordion multiple defaultValue={['bundle']}>
        {CHECKS.map((check) => {
          const { Icon, tone, badge, label } = STATUS[check.status]
          return (
            <AccordionItem key={check.id} value={check.id} disabled={check.status === 'running'}>
              <AccordionTrigger>
                <span className="flex items-center gap-2.5">
                  <Icon size={16} className={tone} />
                  {check.title}
                </span>
                <Badge variant={badge} className="ms-auto">
                  {label}
                </Badge>
              </AccordionTrigger>
              <AccordionContent className="ps-6.5">{check.detail}</AccordionContent>
            </AccordionItem>
          )
        })}
      </Accordion>
    </div>
  )
}
```

Build checks that can stay open together, with one disabled while it runs.

With `multiple`, items open and close independently. Here the build checks can all stay open for comparison, and the running check is `disabled` until it finishes.

A trigger can hold more than its label. Put icons, badges or counts inside it and they become part of the trigger's accessible name, so keep them short.

### Controlled

```tsx
'use client'

import { useState } from 'react'
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Button } from '@youj/react'
import { ChevronsUpDownIcon } from '@youj/icons'

const ENVIRONMENTS = [
  {
    id: 'production',
    name: 'Production',
    variables: [
      ['DATABASE_URL', 'Encrypted'],
      ['STRIPE_SECRET_KEY', 'Encrypted'],
      ['NEXT_PUBLIC_SITE_URL', 'https://acme.com'],
    ],
  },
  {
    id: 'preview',
    name: 'Preview',
    variables: [
      ['DATABASE_URL', 'Encrypted'],
      ['NEXT_PUBLIC_SITE_URL', 'https://preview.acme.com'],
    ],
  },
  {
    id: 'development',
    name: 'Development',
    variables: [
      ['DATABASE_URL', 'postgres://localhost:5432/acme'],
      ['NEXT_PUBLIC_SITE_URL', 'http://localhost:3000'],
    ],
  },
]

export default function AccordionControlled() {
  // The open items are your state, so anything can change them: here, one button opens or closes them all.
  const [open, setOpen] = useState<string[]>(['production'])
  const allOpen = open.length === ENVIRONMENTS.length

return (
    <div className="w-full max-w-xl overflow-hidden rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-3 border-b border-line py-2 ps-4 pe-2">
        <p className="text-ui font-medium text-fg">Environment variables</p>
        <Button variant="ghost" size="sm" onClick={() => setOpen(allOpen ? [] : ENVIRONMENTS.map((env) => env.id))}>
          <ChevronsUpDownIcon size={16} active={allOpen} />
          {allOpen ? 'Collapse all' : 'Expand all'}
        </Button>
      </div>
      <Accordion multiple value={open} onValueChange={setOpen} className="px-4">
        {ENVIRONMENTS.map((env) => (
          <AccordionItem key={env.id} value={env.id}>
            <AccordionTrigger>
              {env.name}
              <span className="ms-auto text-ui-sm font-normal text-fg-muted">{env.variables.length} variables</span>
            </AccordionTrigger>
            <AccordionContent>
              <ul className="flex flex-col gap-1.5 font-mono text-ui-sm">
                {env.variables.map(([key, value]) => (
                  <li key={key} className="flex items-baseline justify-between gap-4">
                    <span className="text-fg">{key}</span>
                    <span className="min-w-0 truncate text-fg-muted">{value}</span>
                  </li>
                ))}
              </ul>
            </AccordionContent>
          </AccordionItem>
        ))}
      </Accordion>
    </div>
  )
}
```

One button that expands or collapses every environment, driven by the accordion's value.

Pass `value` and `onValueChange` to keep the open items in your own state, so anything on the page can open or close them. Here one button expands or collapses every environment, and its label and icon follow along. Keep `multiple` on, or opening one item by hand closes the rest.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add accordion
```

It brings `collapsible`, `youj-presets`, `youj-ui-core` with it.

Use Accordion for sections people open as needed, such as FAQs or groups of settings. Keep essential content and side-by-side comparisons visible. Use [Collapsible](https://www.youj.dev/docs/components/collapsible) for a single section, or [Tabs](https://www.youj.dev/docs/components/tabs) for related views.

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@youj/react'

export function Faq() {
  return (
    <Accordion defaultValue={['seats']}>
      <AccordionItem value="seats">
        <AccordionTrigger>What counts as a seat?</AccordionTrigger>
        <AccordionContent>Anyone who can sign in to the workspace.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="plans">
        <AccordionTrigger>Can I change plans mid-cycle?</AccordionTrigger>
        <AccordionContent>Yes. Upgrades apply at once and are prorated.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

Give each item a `value`. The accordion's value is always an array of the open items' values, so `defaultValue={['seats']}` opens one item and `defaultValue={[]}` opens none. Pass `value` and `onValueChange` to control it. Opening an item closes the others unless you set `multiple`.

### Find in page

`hiddenUntilFound` keeps closed panels in the document with `hidden="until-found"`, so the browser's find-in-page can search their text and open the panel that matches. Try ⌘F or Ctrl+F for "prorated" in the Demo story. Without it, closed panels are unmounted, unless you set `keepMounted` to keep them in the DOM, hidden.

```tsx
<Accordion hiddenUntilFound>…</Accordion>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

Every part passes its props through to the Base UI part of the same name: `Accordion.Root`, `Accordion.Item`, `Accordion.Trigger` and `Accordion.Panel`. The ones you'll use most:

| Part | Prop | Type | Default |
| --- | --- | --- | --- |
| `Accordion` | `defaultValue` | `any[]` | – |
| `Accordion` | `value`, `onValueChange` | `any[]`, `(value, details) => void` | – |
| `Accordion` | `multiple` | `boolean` | `false` |
| `Accordion` | `hiddenUntilFound` | `boolean` | `false` |
| `Accordion` | `keepMounted` | `boolean` | `false` |
| `Accordion` | `disabled` | `boolean` | `false` |
| `AccordionItem` | `value` | `any` | – |
| `AccordionItem` | `disabled` | `boolean` | `false` |
| `AccordionItem` | `onOpenChange` | `(open, details) => void` | – |
| `AccordionTrigger` | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` |

Takes the props of `AccordionPrimitive.Root.Props`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Panel | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height to the measured size, then `auto`, with a fade |
| Chevron | `spring.snappy` | 0.2s, bounce 0 | turns over as the item opens |
| Chevron color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | on trigger hover |

**Reduced motion:** Panels open and close at once, and the chevron flips without turning.

The panel wears the `yj-collapse` [preset](https://www.youj.dev/docs/motion/presets). A toggle mid-way reverses from the current height, so fast clicking never jumps. The panel clips while it moves, which is why the content's padding and focus rings sit inside it.

#### Reduced motion

Panels still open and close, the same way, but at once: the height doesn't ease and the content doesn't fade. The chevron flips to its new direction without turning.

### Accessibility

- Each trigger is a `button` inside a heading (`h3` by default; set `headingLevel` on `AccordionTrigger` to match your outline, such as `2` straight under a page's `h1`), with `aria-expanded` and `aria-controls`. Each panel is a `region` labeled by its trigger.
- Tab moves between triggers, and Enter or Space toggles one. Base UI follows the updated ARIA Authoring Practices here, which dropped arrow-key navigation for accordions.
- A disabled item's trigger doesn't toggle.
- The chevron is decorative. The open state is announced through `aria-expanded`.

---

# Collapsible

> Show or hide a section of content from a single control.

Source: https://www.youj.dev/docs/components/collapsible

## Examples

### Demo

```tsx
'use client'

import {
  Button,
  Collapsible,
  CollapsibleChevron,
  CollapsibleContent,
  CollapsibleTrigger,
  Field,
  FieldDescription,
  FieldLabel,
  Input,
  Switch,
} from '@youj/react'

export default function CollapsibleDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4 rounded-xl border border-line bg-surface p-5">
      <Field>
        <FieldLabel>Build command</FieldLabel>
        <Input defaultValue="pnpm build" className="font-mono" />
      </Field>
      <Collapsible>
        {/* The trigger is a Button, composed through `render`. The chevron reads its aria-expanded. */}
        <CollapsibleTrigger render={<Button variant="ghost" size="sm" className="-ms-2.5" />}>
          Advanced settings
          <CollapsibleChevron />
        </CollapsibleTrigger>
        <CollapsibleContent>
          {/* The panel clips while it moves, so padding and focus rings live inside it. */}
          <div className="flex flex-col gap-4 px-0.5 pt-3 pb-0.5">
            <Field>
              <FieldLabel>Output directory</FieldLabel>
              <Input defaultValue=".next" className="font-mono" />
              <FieldDescription>Relative to the project root.</FieldDescription>
            </Field>
            <Field orientation="horizontal">
              <Switch defaultChecked />
              <FieldLabel>Skip the build when nothing changed</FieldLabel>
            </Field>
          </div>
        </CollapsibleContent>
      </Collapsible>
    </div>
  )
}
```

A build command field with an Advanced settings section that grows open.

### Show more

```tsx
'use client'

import { useState } from 'react'
import { Button, Collapsible, CollapsibleChevron, CollapsibleContent, CollapsibleTrigger } from '@youj/react'
import { FileTextIcon, FolderIcon } from '@youj/icons'

const FILES = ['page.tsx', 'layout.tsx', 'pricing-grid.tsx', 'checkout-button.tsx', 'use-subscription.ts', 'stripe.server.ts', 'plans.json']

function File({ name }: { name: string }) {
  return (
    <li className="flex items-center gap-2.5 px-3 py-2">
      <FileTextIcon size={16} className="text-fg-muted" />
      <span className="font-mono text-ui-sm text-fg">{name}</span>
    </li>
  )
}

export default function CollapsibleShowMore() {
  const [open, setOpen] = useState(false)

return (
    <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-surface">
      <p className="flex items-center gap-2 border-b border-line px-3 py-2.5 text-ui font-medium text-fg">
        <FolderIcon size={16} className="text-fg-muted" />
        app/(marketing)/pricing
      </p>
      <ul className="divide-y divide-line">
        {FILES.slice(0, 3).map((name) => (
          <File key={name} name={name} />
        ))}
      </ul>
      {/* The rest of the list grows in below the first three. */}
      <CollapsibleContent>
        <ul className="divide-y divide-line border-t border-line">
          {FILES.slice(3).map((name) => (
            <File key={name} name={name} />
          ))}
        </ul>
      </CollapsibleContent>
      <div className="border-t border-line p-1.5">
        <CollapsibleTrigger render={<Button variant="ghost" size="sm" className="w-full" />}>
          {open ? 'Show less' : `Show ${FILES.length - 3} more`}
          <CollapsibleChevron />
        </CollapsibleTrigger>
      </div>
    </Collapsible>
  )
}
```

A file list that shows three rows and grows to show the rest, with a trigger label that follows the state.

Controlled, the trigger's label can follow the state. Here the first three files stay visible and the rest of the list grows in below them.

### Nesting

```tsx
'use client'

import { useState } from 'react'
import { Collapsible, CollapsibleChevron, CollapsibleContent, CollapsibleTrigger } from '@youj/react'
import { FileTextIcon, FolderIcon, GitBranchIcon } from '@youj/icons'

type Entry = { name: string; open?: boolean; children?: Entry[] }

const SOURCE: Entry[] = [
  {
    name: 'app',
    open: true,
    children: [
      {
        name: '(marketing)',
        open: true,
        children: [{ name: 'pricing', children: [{ name: 'page.tsx' }, { name: 'pricing-grid.tsx' }] }, { name: 'page.tsx' }],
      },
      { name: 'dashboard', children: [{ name: 'layout.tsx' }, { name: 'page.tsx' }] },
      { name: 'layout.tsx' },
    ],
  },
  { name: 'components', children: [{ name: 'checkout-button.tsx' }, { name: 'plan-toggle.tsx' }] },
  { name: 'lib', children: [{ name: 'stripe.server.ts' }] },
  { name: 'package.json' },
]

const row = 'flex h-7 w-full items-center gap-2 rounded-md px-2 font-mono text-ui-sm text-fg'

function Folder({ entry }: { entry: Entry }) {
  const [open, setOpen] = useState(entry.open ?? false)
  return (
    // Each folder is its own Collapsible: opening one never closes another.
    <Collapsible open={open} onOpenChange={setOpen} render={<li />}>
      {/* An inset ring: the panels around nested folders clip their content. */}
      <CollapsibleTrigger
        className={`${row} transition-colors yj-duration-fast ease-standard hover:bg-hover focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus focus-visible:outline-solid`}
      >
        <FolderIcon size={16} active={open} className="text-fg-muted" />
        {entry.name}
        <CollapsibleChevron size={14} className="ms-auto text-fg-muted" />
      </CollapsibleTrigger>
      <CollapsibleContent>
        <Entries entries={entry.children ?? []} className="ms-[15px] border-s border-line ps-1 pt-0.5" />
      </CollapsibleContent>
    </Collapsible>
  )
}

function Entries({ entries, className }: { entries: Entry[]; className: string }) {
  return (
    <ul className={`flex flex-col gap-0.5 ${className}`}>
      {entries.map((entry) =>
        entry.children ? (
          <Folder key={entry.name} entry={entry} />
        ) : (
          <li key={entry.name} className={row}>
            <FileTextIcon size={16} className="text-fg-muted" />
            {entry.name}
          </li>
        ),
      )}
    </ul>
  )
}

export default function CollapsibleNested() {
  return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-surface">
      <p className="flex items-center gap-2 border-b border-line px-3 py-2.5 text-ui font-medium text-fg">
        <GitBranchIcon size={16} className="text-fg-muted" />
        acme/web
        <span className="ms-auto font-mono text-ui-sm font-normal text-fg-muted">main</span>
      </p>
      <Entries entries={SOURCE} className="p-1.5" />
    </div>
  )
}
```

A folder tree where each folder is its own Collapsible.

Each folder in this tree is its own `Collapsible`, nested in its parent's panel, so opening one never closes another. Its `open` state also opens the folder icon. It's a list of disclosure buttons, not an ARIA tree: Tab moves between the folders, and Enter or Space toggles one.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add collapsible
```

It brings `icon-chevron-down`, `youj-presets`, `youj-ui-core` with it.

Use it to keep secondary content out of the way until someone asks for it: advanced settings, the rest of a long list, details under a summary. For a stack of sections, use an [Accordion](https://www.youj.dev/docs/components/accordion). For content that should float over the page instead of pushing it down, use a [Popover](https://www.youj.dev/docs/components/popover).

```tsx
import { Button, Collapsible, CollapsibleChevron, CollapsibleContent, CollapsibleTrigger } from '@youj/react'

export function AdvancedSettings() {
  return (
    <Collapsible>
      <CollapsibleTrigger render={<Button variant="ghost" size="sm" />}>
        Advanced settings
        <CollapsibleChevron />
      </CollapsibleTrigger>
      <CollapsibleContent>
        <div className="pt-3">…</div>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

`CollapsibleTrigger` renders a plain button by default. Compose it with any button through `render`, as in the Demo story, and it keeps its look while gaining the disclosure behavior. Pass `defaultOpen` to start open, or `open` and `onOpenChange` to control it.

### The chevron

`CollapsibleChevron` is Youj's chevron icon, turned over while its trigger is expanded. It reads `aria-expanded` from the nearest trigger around it, so it works in any disclosure without wiring: a collapsible, an accordion, a navigation menu or a sidebar group, including triggers composed through `render`. It mounts in its real state, so an open section doesn't turn over on first paint. `size` sets it in pixels.

```tsx
<CollapsibleTrigger>
  Filters
  <CollapsibleChevron size={14} className="text-fg-muted" />
</CollapsibleTrigger>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### CollapsibleChevron

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `16` | Rendered size in px. |
| `className` | `string` |  |  |

#### Collapsible, CollapsibleTrigger and CollapsibleContent

These pass their props through to Base UI's `Collapsible.Root`, `Collapsible.Trigger` and `Collapsible.Panel`. The ones you'll use most:

| Part | Prop | Type | Default |
| --- | --- | --- | --- |
| `Collapsible` | `defaultOpen` | `boolean` | `false` |
| `Collapsible` | `open`, `onOpenChange` | `boolean`, `(open, details) => void` | – |
| `Collapsible` | `disabled` | `boolean` | `false` |
| `CollapsibleTrigger` | `render` | `ReactElement \| (props, state) => ReactElement` | – |
| `CollapsibleContent` | `keepMounted` | `boolean` | `false` |
| `CollapsibleContent` | `hiddenUntilFound` | `boolean` | `false` |

### Motion

**Reduced motion:** The panel opens and closes at once, and the chevron flips without turning.

The panel wears the `yj-collapse` [preset](https://www.youj.dev/docs/motion/presets): the height eases between zero and the measured size, then settles on `auto` so the content can still grow. A toggle mid-way reverses from the current height. The panel clips while it moves, so keep padding and focus rings inside it, as the examples do.

#### Reduced motion

The section still opens and closes, but at once: no height easing and no fade. The chevron flips without turning.

### Accessibility

- The trigger is a `button` with `aria-expanded`, and `aria-controls` pointing at the panel.
- Enter and Space toggle it. Closed content is removed from the tab order, and from the document unless you pass `keepMounted` or `hiddenUntilFound`.
- The chevron is decorative. The state is announced through `aria-expanded`, so a label that changes ("Show 4 more", "Show less") is optional.

---

# Anchor Nav

> Navigate a long page with a table of contents that highlights the current section.

Source: https://www.youj.dev/docs/components/anchor-nav

## Examples

### Demo

```tsx
'use client'

import { useRef } from 'react'
import { AnchorNav, type AnchorNavItem } from '@youj/react'

// Section ids must be unique on the page, so they carry a prefix.
const ITEMS: AnchorNavItem[] = [
  { id: 'guide-overview', label: 'Overview' },
  { id: 'guide-install', label: 'Installation' },
  { id: 'guide-npm', label: 'From npm', depth: 1 },
  { id: 'guide-registry', label: 'From the registry', depth: 1 },
  { id: 'guide-theming', label: 'Theming' },
  { id: 'guide-motion', label: 'Motion' },
  { id: 'guide-faq', label: 'FAQ' },
]

export default function AnchorNavDemo() {
  // The sections scroll inside this frame. On a docs page, leave scrollContainer out and it follows the window.
  const scroller = useRef<HTMLDivElement>(null)

return (
    <div className="grid w-full max-w-2xl grid-cols-[minmax(0,1fr)_10.5rem] overflow-hidden rounded-xl border border-line bg-canvas shadow-xs max-sm:grid-cols-1">
      <div ref={scroller} role="region" aria-label="Sections" tabIndex={0} className="h-[22rem] overflow-y-auto px-5 py-4 focus-visible:outline-2 focus-visible:outline-focus">
        {ITEMS.map((item, i) => (
          <section
            key={item.id}
            id={item.id}
            className="flex flex-col gap-2 rounded-md pb-8 outline-none focus-visible:outline-2 focus-visible:outline-focus"
          >
            <p className={item.depth ? 'text-ui font-semibold text-fg' : 'text-ui-lg font-semibold tracking-tight text-fg'}>
              {item.label}
            </p>
            {Array.from({ length: i % 3 === 0 ? 2 : 1 }, (_, p) => (
              <p key={p} className="text-ui leading-relaxed text-fg-muted">
                Components compose from Base UI primitives and move through motion tokens, so Speed and reduced motion reach
                everything: overlays, indicators and the height of a list.
              </p>
            ))}
          </section>
        ))}
        <div className="h-40" />
      </div>
      <div className="border-s border-line p-4 max-sm:hidden">
        <AnchorNav items={ITEMS} scrollContainer={scroller} />
      </div>
    </div>
  )
}
```

A guide with its section list beside it; the current section is marked as you scroll.

### Sticky headers

```tsx
'use client'

import { useRef } from 'react'
import { AnchorNav, type AnchorNavItem } from '@youj/react'

const ITEMS: AnchorNavItem[] = [
  { id: 'release-highlights', label: 'Highlights' },
  { id: 'release-breaking', label: 'Breaking changes' },
  { id: 'release-fixes', label: 'Fixes' },
  { id: 'release-upgrade', label: 'Upgrading' },
]

/** The sticky bar's height: a chosen section lands just below it, and the reading line starts there. */
const HEADER = 48

export default function AnchorNavOffset() {
  const scroller = useRef<HTMLDivElement>(null)

return (
    <div className="grid w-full max-w-2xl grid-cols-[minmax(0,1fr)_10.5rem] overflow-hidden rounded-xl border border-line bg-canvas shadow-xs max-sm:grid-cols-1">
      <div ref={scroller} className="relative h-[20rem] overflow-y-auto">
        <div
          className="sticky top-0 z-10 flex items-center border-b border-line bg-canvas/85 youj-allow-glass px-5 text-ui font-medium text-fg [backdrop-filter:blur(12px)]"
          style={{ height: HEADER }}
        >
          Release notes · 2.4
        </div>
        <div className="px-5 pt-4">
          {ITEMS.map((item) => (
            <section key={item.id} id={item.id} className="flex flex-col gap-2 rounded-md pb-10 outline-none focus-visible:outline-2 focus-visible:outline-focus">
              <p className="text-ui-lg font-semibold tracking-tight text-fg">{item.label}</p>
              <p className="text-ui leading-relaxed text-fg-muted">
                Choose a link: the section lands under the bar instead of behind it, because the offset keeps that much room
                above it.
              </p>
            </section>
          ))}
          <div className="h-48" />
        </div>
      </div>
      <div className="border-s border-line p-4 max-sm:hidden">
        <AnchorNav items={ITEMS} title="Contents" scrollContainer={scroller} offset={HEADER + 16} />
      </div>
    </div>
  )
}
```

A page under a sticky header, with an offset that keeps a chosen section clear of it.

A sticky header covers the top of the page, so a section that scrolls to the very top lands behind it. `offset` is the space kept above a chosen section, and the reading line starts below it too. Set it to the header's height plus a little air.

`title` is the caption above the list. It defaults to "On this page", and `null` removes it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add anchor-nav
```

It brings `sliding-indicator`, `youj-core`, `youj-labels-anchor-nav`, `youj-presets`, `youj-ui-core` with it.

Use it beside a long page people read and come back to: a guide, a policy, release notes, a settings page with many groups. It shows where the reader is and takes them to any section in one click. It's a scrollspy over one page. To move between pages, use a [Sidebar](https://www.youj.dev/docs/components/sidebar) or [Tabs](https://www.youj.dev/docs/components/tabs), and for a flow of steps, a [Stepper Nav](https://www.youj.dev/docs/components/stepper-nav).

```tsx
import { AnchorNav, type AnchorNavItem } from '@youj/react'

const items: AnchorNavItem[] = [
  { id: 'overview', label: 'Overview' },
  { id: 'install', label: 'Installation' },
  { id: 'npm', label: 'From npm', depth: 1 },
  { id: 'theming', label: 'Theming' },
]

export function Guide() {
  return (
    <div className="grid gap-10 lg:grid-cols-[1fr_14rem]">
      <article>
        <section id="overview">…</section>
        <section id="install">…</section>
      </article>
      <aside className="hidden lg:block">
        <AnchorNav items={items} className="sticky top-20" offset={64} />
      </aside>
    </div>
  )
}
```

Each item points at the `id` of a section on the page, and `depth` indents a sub-section (up to two levels). The section in view is the last one whose top has passed a reading line a quarter of the way down the window. At the very bottom of the page, the last section counts as in view, even if it's too short to reach the line.

Choosing a link scrolls smoothly to its section, moves focus there without scrolling again, and puts its id in the URL. While that scroll runs, the bar goes straight to the destination instead of stepping through every section on the way. A wheel or touch mid-scroll hands control back to the reader. The page tracks the window by default. Pass `scrollContainer` when the sections scroll inside an element, as in the previews.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `AnchorNavItem[]` |  |  |
| `title` | `ReactNode` |  | A caption above the list. Default "On this page"; `null` for none. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls the sections. Default: the page. |
| `offset` | `number` | `16` | Space kept above a section: where a chosen one lands (clear a sticky header with it). |

Also takes the props of `ComponentProps<'nav'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Current bar | `spring.smooth` | 0.36s, bounce 0 | one Sliding Indicator on the list’s start edge glides to the section in view |
| Link color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the current link and hovered links turn to ink |
| Scroll to a section |  | native smooth | the browser’s smooth scroll; the bar goes straight to the destination |

**Reduced motion:** The page jumps to the chosen section and the bar jumps with it.

#### Reduced motion

The page jumps straight to the chosen section instead of scrolling, and the bar moves at once. Focus, the URL and the tracking work the same.

### Accessibility

- It's a `nav` landmark named by `title` ("On this page"), or by `aria-label` when there's no text title.
- The link for the section in view carries `aria-current="location"`, so screen readers announce it as the current location.
- Following a link moves focus to the section (giving it `tabindex="-1"` if it can't take focus), so the next Tab continues from there and a screen reader starts reading it. Give sections a visible focus style.
- The links are plain anchors with `href="#id"`: ⌘-click or middle-click opens them the browser's way, and they work before the page hydrates.

---

# Breadcrumb

> Show where a page sits in your site and link back to its parent pages.

Source: https://www.youj.dev/docs/components/breadcrumb

## Examples

### Demo

```tsx
'use client'

import type { MouseEvent } from 'react'
import {
  Badge,
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@youj/react'
import { GitBranchIcon } from '@youj/icons'

// In an app these are router links. Here they stay on the page.
const stay = (event: MouseEvent) => event.preventDefault()

export default function BreadcrumbDemo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3 rounded-xl border border-line bg-surface p-5">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="/acme" onClick={stay}>
              <span aria-hidden className="grid size-4 place-items-center rounded-[4px] bg-fg text-[9px] font-bold text-canvas">
                A
              </span>
              Acme
            </BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbLink href="/acme/web" onClick={stay}>
              web
            </BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbLink href="/acme/web/deployments" onClick={stay}>
              Deployments
            </BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbPage className="font-mono text-ui-sm">dpl_8f2a91c</BreadcrumbPage>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
      <div className="flex flex-wrap items-center gap-3">
        <p className="text-xl font-semibold tracking-tight text-fg">Tighten the pricing grid on mobile</p>
        <Badge variant="success">Ready</Badge>
      </div>
      <p className="flex items-center gap-1.5 text-ui text-fg-muted">
        <GitBranchIcon size={14} />
        main · 4 minutes ago by Ada Lovelace
      </p>
    </div>
  )
}
```

A path from an organization down to a deployment, ending on the current page.

### Long paths

```tsx
'use client'

import { Fragment, type MouseEvent } from 'react'
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@youj/react'

const PATH = ['Acme', 'Engineering', 'Platform', 'Services', 'Billing API', 'Environments', 'Production']

const stay = (event: MouseEvent) => event.preventDefault()

export default function BreadcrumbCollapsed() {
  return (
    <div className="w-full max-w-2xl rounded-xl border border-line bg-surface px-5 py-4">
      {/* Seven levels, four shown: the root, then the page and its parent. Press the ellipsis to unfold the rest. */}
      <Breadcrumb aria-label="Service breadcrumb">
        <BreadcrumbList maxItems={4}>
          {PATH.map((name, i) =>
            i === PATH.length - 1 ? (
              <BreadcrumbItem key={name}>
                <BreadcrumbPage>{name}</BreadcrumbPage>
              </BreadcrumbItem>
            ) : (
              // Each crumb and the separator after it fold as one unit.
              <Fragment key={name}>
                <BreadcrumbItem>
                  <BreadcrumbLink href={`/${PATH.slice(0, i + 1).join('/').toLowerCase()}`} onClick={stay}>
                    {name}
                  </BreadcrumbLink>
                </BreadcrumbItem>
                <BreadcrumbSeparator />
              </Fragment>
            ),
          )}
        </BreadcrumbList>
      </Breadcrumb>
    </div>
  )
}
```

A long path folded into an ellipsis button that unfolds the hidden crumbs.

Give the list `maxItems` and a path longer than that folds its middle crumbs into an ellipsis button, named for what it holds ("Show 3 more"). Pressing it unfolds the crumbs in place and moves focus to the first one it revealed. `itemsBeforeCollapse` (default 1) and `itemsAfterCollapse` (default 2, the page and its parent) choose what stays visible. A new path starts folded again.

When crumbs come from data, return each crumb with the separator after it, in a fragment or a small component, and the list folds them as one unit.

### Separators

```tsx
'use client'

import type { MouseEvent } from 'react'
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@youj/react'
import { ChevronRightIcon, HomeIcon } from '@youj/icons'

const stay = (event: MouseEvent) => event.preventDefault()

export default function BreadcrumbSeparatorExample() {
  return (
    <Breadcrumb aria-label="Docs breadcrumb">
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs" onClick={stay} aria-label="Docs home">
            <HomeIcon size={14} />
          </BreadcrumbLink>
        </BreadcrumbItem>
        {/* Any mark can separate crumbs. It stays hidden from assistive technology. */}
        <BreadcrumbSeparator>
          <ChevronRightIcon trigger="none" />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          {/* A static ellipsis: a gap the app chose not to show. */}
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <ChevronRightIcon trigger="none" />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs/components" onClick={stay}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <ChevronRightIcon trigger="none" />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>Marketing site redesign</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

A chevron in place of the default separator, and a static ellipsis.

`BreadcrumbSeparator` draws a slanted hairline by default. Pass any mark as its children instead, such as a chevron. A static `BreadcrumbEllipsis` marks a gap the app decided not to show, and it isn't interactive.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add breadcrumb
```

It brings `icon-ellipsis`, `youj-core`, `youj-labels-breadcrumb`, `youj-presets`, `youj-ui-core` with it.

Use a breadcrumb when pages nest several levels deep, like a workspace, a project, a section and an item, and people need to step back up. Don't use it as the main navigation, on a flat site, or to show progress through the steps of a task. It describes where a page lives, not how someone got there.

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@youj/react'

export function DeploymentBreadcrumb() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/acme">Acme</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/acme/web">web</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Deployments</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

The current page is a `BreadcrumbPage`: plain text marked `aria-current="page"`, not a link to itself. Crumbs can lead with an icon or a logo, and labels longer than 12rem truncate with an ellipsis. The full text stays in the link's accessible name.

To render your router's link, pass it through `render`. It keeps the crumb's look and focus ring:

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

<BreadcrumbLink render={<Link href="/acme/web" />}>web</BreadcrumbLink>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### BreadcrumbList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxItems` | `number` |  | Collapse the middle crumbs when there are more than this many. |
| `itemsBeforeCollapse` | `number` | `1` | Crumbs kept before the ellipsis. |
| `itemsAfterCollapse` | `number` | `2` | Crumbs kept after the ellipsis. |

Also takes the props of `ComponentProps<'ol'>`.

#### Other parts

`Breadcrumb` is a `nav`, `BreadcrumbItem` and `BreadcrumbSeparator` are `li` elements, and `BreadcrumbPage` is a `span`. Each takes the props of its element. `BreadcrumbLink` and `BreadcrumbEllipsis` also take `render`, to swap the element they render.

Takes the props of `useRender.ComponentProps<'a'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Unfold, width | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | each folded crumb grows from zero, so the ones after it glide aside |
| Unfold, fade | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | each crumb fades in once its width is under way |
| Fade offset | `stagger.base` | 40ms step | from a crumb’s width to its fade |
| Cascade | `stagger.tight` | 24ms step | from one unfolding crumb to the next |
| Link color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | on hover |

**Reduced motion:** Folded crumbs appear at once, in place. Links change color without easing.

A crumb clips only while it grows. Once it has unfolded, the clip comes off, so its focus ring has room.

#### Reduced motion

The folded crumbs appear at once when the ellipsis is pressed, and focus still moves to the first of them. Nothing else changes.

### Accessibility

- `Breadcrumb` is a `nav` landmark named "Breadcrumb". If a page has more than one, give each its own `aria-label`.
- The crumbs are an ordered list. Separators are `role="presentation"` and `aria-hidden`, so the list announces only the crumbs.
- The current page carries `aria-current="page"` and isn't a link.
- The fold is a real button named for the crumbs it holds. It unfolds on Enter or Space, and focus moves to the first crumb it reveals, so keyboard users don't lose their place.
- An icon-only crumb needs an `aria-label`, like the home link in the separators example.

---

# Pagination

> Move through pages of results and show the current page.

Source: https://www.youj.dev/docs/components/pagination

## Examples

### Demo

```tsx
'use client'

import { useState, type MouseEvent } from 'react'
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  paginationRange,
} from '@youj/react'

const PER_PAGE = 5
const TOTAL = 320
const PAGES = Math.ceil(TOTAL / PER_PAGE)
const ACTORS = ['Ada Lovelace', 'Grace Hopper', 'Priya Raman', 'Kenji Sato', 'Sara Okafor']
const ACTIONS = ['deployed', 'rolled back', 'renamed', 'rotated a token for', 'changed the domain of']
const PROJECTS = ['web', 'docs', 'api-gateway', 'billing', 'status-page']

// A page of the audit log, derived from its number so every page is stable.
function events(page: number) {
  return Array.from({ length: PER_PAGE }, (_, j) => {
    const i = (page - 1) * PER_PAGE + j
    return { id: i, actor: ACTORS[(i * 7) % 5]!, action: ACTIONS[(i * 3) % 5]!, project: PROJECTS[(i * 2 + 1) % 5]!, age: `${page + j}h` }
  })
}

export default function PaginationDemo() {
  const [page, setPage] = useState(3)
  // Real hrefs keep the pages linkable. On click, page in place instead.
  const go = (next: number) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(Math.min(Math.max(next, 1), PAGES))
  }
  const first = (page - 1) * PER_PAGE + 1

return (
    <div className="@container w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-surface">
      <ul className="divide-y divide-line">
        {events(page).map((event) => (
          <li key={event.id} className="flex items-center gap-3 px-4 py-2.5 text-ui">
            <span className="min-w-0 flex-1 truncate text-fg-muted">
              <span className="font-medium text-fg">{event.actor}</span> {event.action}{' '}
              <span className="font-mono text-ui-sm text-fg">{event.project}</span>
            </span>
            <span className="text-ui-sm text-fg-muted tabular-nums">{event.age}</span>
          </li>
        ))}
      </ul>
      <div className="flex flex-col items-center gap-2 border-t border-line px-4 py-2.5 @lg:flex-row @lg:justify-between">
        <p className="shrink-0 text-ui-sm text-fg-muted tabular-nums">
          Showing {first}–{first + PER_PAGE - 1} of {TOTAL}
        </p>
        <Pagination aria-label="Audit log pages" className="mx-0 w-auto">
          <PaginationContent>
            <PaginationItem>
              <PaginationPrevious href={`?page=${page - 1}`} disabled={page === 1} onClick={go(page - 1)} />
            </PaginationItem>
            {paginationRange(page, PAGES).map((item) =>
              typeof item === 'number' ? (
                <PaginationItem key={item}>
                  <PaginationLink href={`?page=${item}`} isActive={item === page} aria-label={`Page ${item}`} onClick={go(item)}>
                    {item}
                  </PaginationLink>
                </PaginationItem>
              ) : (
                <PaginationItem key={item}>
                  <PaginationEllipsis />
                </PaginationItem>
              ),
            )}
            <PaginationItem>
              <PaginationNext href={`?page=${page + 1}`} disabled={page === PAGES} onClick={go(page + 1)} />
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      </div>
    </div>
  )
}
```

An activity log of 320 events paged five at a time, with numbered links and previous and next.

On the first page, `PaginationPrevious` takes `disabled`, and on the last page `PaginationNext` does. A disabled link renders without an `href` and with `aria-disabled`, so it can't be followed, but it stays in the tab order: paging onto the last page with Enter keeps focus on Next instead of dropping it. Below the `sm` breakpoint, Previous and Next drop their text and keep their chevrons. Change the text with `text`.

### Page ranges

```tsx
'use client'

export default function PaginationRange() {
  return (
    <div className="flex flex-col gap-6">
      {/* Few pages: every page shows. */}
      <Pager label="Release pages" pageCount={5} initial={2} />
      {/* Many: the first and last stay around the current page. No siblings beside it (the default is one each side), so it fits a phone. */}
      <Pager label="Invoice pages" pageCount={240} initial={120} siblings={0} />
    </div>
  )
}
```

Page numbers built from `paginationRange`, with ellipses for the gaps.

`paginationRange(page, pageCount, siblings = 1)` returns the items to render: the first and last pages, `siblings` pages either side of the current one, and `'start-ellipsis'` or `'end-ellipsis'` for the gaps. When every page fits, it returns them all. Once pages are skipped, it always returns 5 + 2 × `siblings` items, so the control keeps its width while you page and the key never chases a moving target.

```ts
paginationRange(10, 20) // [1, 'start-ellipsis', 9, 10, 11, 'end-ellipsis', 20]
paginationRange(120, 240, 2) // [1, 'start-ellipsis', 118, 119, 120, 121, 122, 'end-ellipsis', 240]
```

### Previous and next

```tsx
'use client'

import { useState, type MouseEvent } from 'react'
import { Pagination, PaginationContent, PaginationItem, PaginationNext, PaginationPrevious } from '@youj/react'

const PER_PAGE = 3
const RELEASES = [
  { version: '2.4.0', title: 'Faster cold starts for Functions', date: 'Sep 24' },
  { version: '2.3.2', title: 'Preview comments on renamed branches', date: 'Sep 17' },
  { version: '2.3.1', title: 'Spend limits per project', date: 'Sep 10' },
  { version: '2.3.0', title: 'Instant rollback from the CLI', date: 'Sep 3' },
  { version: '2.2.4', title: 'A region picker for storage', date: 'Aug 27' },
  { version: '2.2.3', title: 'Audit log export as CSV', date: 'Aug 20' },
  { version: '2.2.2', title: 'Custom domains on preview deployments', date: 'Aug 13' },
  { version: '2.2.1', title: 'Two-factor sign-in on every plan', date: 'Aug 6' },
  { version: '2.2.0', title: 'A build cache shared across branches', date: 'Jul 30' },
  { version: '2.1.2', title: 'Webhooks retry with backoff', date: 'Jul 23' },
  { version: '2.1.1', title: 'Search logs by request ID', date: 'Jul 16' },
  { version: '2.1.0', title: 'Environment variables per branch', date: 'Jul 9' },
]
const PAGES = Math.ceil(RELEASES.length / PER_PAGE)

export default function PaginationCompact() {
  const [page, setPage] = useState(2)
  const go = (next: number) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(Math.min(Math.max(next, 1), PAGES))
  }

return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <ul className="divide-y divide-line">
        {RELEASES.slice((page - 1) * PER_PAGE, page * PER_PAGE).map((release) => (
          <li key={release.version} className="flex items-baseline gap-3 px-4 py-2.5 text-ui">
            <span className="w-11 shrink-0 font-mono text-ui-sm text-fg-muted">{release.version}</span>
            <span className="min-w-0 flex-1 truncate text-fg">{release.title}</span>
            <span className="shrink-0 text-ui-sm text-fg-muted tabular-nums">{release.date}</span>
          </li>
        ))}
      </ul>
      <Pagination aria-label="Changelog pages" className="border-t border-line px-2 py-1.5">
        <PaginationContent className="w-full justify-between">
          <PaginationItem>
            {/* A relabeled edge gets a name that starts with its visible text. */}
            <PaginationPrevious href={`?page=${page - 1}`} text="Newer" aria-label="Newer releases" disabled={page === 1} onClick={go(page - 1)} />
          </PaginationItem>
          {/* Paging in place: the new position is announced. */}
          <PaginationItem aria-live="polite" className="text-ui-sm text-fg-muted tabular-nums">
            Page {page} of {PAGES}
          </PaginationItem>
          <PaginationItem>
            <PaginationNext href={`?page=${page + 1}`} text="Older" aria-label="Older releases" disabled={page === PAGES} onClick={go(page + 1)} />
          </PaginationItem>
        </PaginationContent>
      </Pagination>
    </div>
  )
}
```

Pagination with only previous and next, for places with no room for page numbers.

Leave the page numbers out when there's no room for them, as in a card footer, or when the total isn't known, as with a cursor-based API. When `text` relabels an edge, give it an `aria-label` that starts with the same word, so what people hear matches what they see. With no page marked current, the raised key stays hidden.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add pagination
```

It brings `button`, `icon-chevron-left`, `icon-chevron-right`, `icon-ellipsis`, `sliding-indicator`, `youj-core`, `youj-labels-pagination`, `youj-presets`, `youj-ui-core` with it.

The copy is 15 registry items, about 7,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-chevron-left`, `icon-chevron-right`, `icon-ellipsis`, `icon-engine`, `icon-loader-ring`, `sliding-indicator`, `spinner`.

Use pagination when position matters: tables, logs and search results that people come back to, share by URL, or count through. Don't use it for a feed people skim, where infinite scroll or a "Load more" button reads better, or for a list short enough to show whole.

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  paginationRange,
} from '@youj/react'

export function Pager({ page, pageCount }: { page: number; pageCount: number }) {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href={`?page=${page - 1}`} disabled={page === 1} />
        </PaginationItem>
        {paginationRange(page, pageCount).map((item) =>
          typeof item === 'number' ? (
            <PaginationItem key={item}>
              <PaginationLink href={`?page=${item}`} isActive={item === page} aria-label={`Page ${item}`}>
                {item}
              </PaginationLink>
            </PaginationItem>
          ) : (
            <PaginationItem key={item}>
              <PaginationEllipsis />
            </PaginationItem>
          ),
        )}
        <PaginationItem>
          <PaginationNext href={`?page=${page + 1}`} disabled={page === pageCount} />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}
```

Every page is a real link, so pages can be bookmarked, shared and opened in a new tab. To page without a navigation, handle `onClick`, call `event.preventDefault()` and update your state, as the Demo story does. The raised key under the current page is one indicator for the whole control, and it glides to whichever link has `isActive`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### PaginationLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` |  |  |
| `disabled` | `boolean` |  | The edge of the range: aria-disabled, no href and inert to clicks, but still focusable, so paging onto the last page with Enter keeps focus on the control instead of dropping it to the body. |
| `size` | `'default' \| 'icon'` | `'icon'` |  |

#### PaginationPrevious and PaginationNext

They take every `PaginationLink` prop, and `text` for the label beside the chevron.

#### Other parts

`Pagination` is a `nav` named "Pagination", `PaginationContent` a `ul`, `PaginationItem` an `li` and `PaginationEllipsis` a `span`. Each takes the props of its element.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Current page | `spring.smooth` | 0.36s, bounce 0 | the raised key glides to the new page, transform only |
| Previous and Next | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the chevron nudges 2px toward where it goes, on hover |
| Hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | color and background |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | scales to 0.97 while held |

**Reduced motion:** The key jumps to the new page, the chevrons shift without easing, and links don't scale on press.

In right-to-left layouts the chevrons point, and nudge, the other way.

#### Reduced motion

Paging works the same. The raised key jumps to the new page instead of gliding, the chevrons shift without easing, and links don't scale on press.

### Accessibility

- `Pagination` is a `nav` landmark. Its default name is "Pagination"; give it a more specific `aria-label` ("Invoice pages") when a page has more than one.
- The current page's link carries `aria-current="page"`.
- Give number links an `aria-label` such as "Page 3", so they're announced as pages, not bare numbers. Previous and Next are named "Go to previous page" and "Go to next page".
- Ellipses and the raised key are hidden from assistive technology. The numbers either side of a gap already say pages were skipped.
- Tab moves through the links, and Enter follows one. A disabled Previous or Next is still a Tab stop, announced as unavailable, so focus never falls back to the page.

---

# Item Pager

> Step to the next or previous record of a list from its detail panel.

Source: https://www.youj.dev/docs/components/item-pager

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ItemPager } from '@youj/react'

const tickets = [
  { id: 'SUP-2041', title: 'Exports time out above 50k rows', requester: 'Lumen Freight' },
  { id: 'SUP-2042', title: 'SSO login loops on Safari', requester: 'Fernhill Bank' },
  { id: 'SUP-2043', title: 'Invoice PDF shows the wrong VAT number', requester: 'Quayside Foods' },
  { id: 'SUP-2044', title: 'Webhook retries arrive out of order', requester: 'Orrery Labs' },
]

export default function ItemPagerDemo() {
  const [index, setIndex] = useState(1)
  const ticket = tickets[index]!
  return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-overlay shadow-sm">
      <div className="flex h-12 items-center gap-2 border-b border-line px-3">
        <ItemPager index={index} total={tickets.length} onIndexChange={setIndex} />
        <Button variant="outline" size="xs" className="ms-auto">
          Assign
        </Button>
      </div>
      <div className="flex flex-col gap-1 p-4">
        <span className="font-mono text-ui-sm text-fg-muted">{ticket.id}</span>
        <span className="text-ui font-medium">{ticket.title}</span>
        <span className="text-ui-sm text-fg-muted">{ticket.requester}</span>
      </div>
    </div>
  )
}
```

A item pager in a drawer header, moving through four support tickets.

### Shortcuts

```tsx
'use client'

import { useState } from 'react'
import { Input, Kbd, ItemPager } from '@youj/react'

const names = ['Lumen Freight', 'Orrery Labs', 'Fernhill Bank', 'Quayside Foods', 'Brightwater Health']

export default function ItemPagerShortcuts() {
  const [index, setIndex] = useState(0)
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <ItemPager index={index} total={names.length} onIndexChange={setIndex} shortcuts="global" />
        <span className="truncate text-ui font-medium">{names[index]}</span>
      </div>
      <p className="text-ui-sm text-fg-muted">
        Press <Kbd>J</Kbd> or <Kbd>K</Kbd> anywhere on the page. In the field below they type instead.
      </p>
      <Input aria-label="Note" placeholder="Type a note…" />
    </div>
  )
}
```

Keyboard shortcuts for stepping between records.

By default J, K and the arrow keys step while focus is in the stepper. `shortcuts="global"` also listens for J and K on the whole page, which is what an open record drawer wants. Keys typed into a field, a combobox or editable text stay there. `shortcuts="none"` turns keys off. The buttons' tooltips show the keys.

The page-wide arrows are left alone: they scroll the page and move through lists.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add item-pager
```

It brings `button`, `icon-chevron-down`, `icon-chevron-up`, `kbd`, `tooltip`, `youj-core`, `youj-labels-item-pager`, `youj-ui-core` with it.

The copy is 15 registry items, about 7,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-chevron-down`, `icon-chevron-up`, `icon-engine`, `icon-loader-ring`, `kbd`, `spinner`, `tooltip`.

Use a item pager in the header of a detail panel or drawer that shows one row of a list: a deal, a ticket, a message. ↓ opens the next row, ↑ the previous one, and "2 of 4" says where you are, so people work through a list without closing the panel. To move between pages of results, use [Pagination](https://www.youj.dev/docs/components/pagination). For the steps of a process, use a [Stepper](https://www.youj.dev/docs/components/stepper).

```tsx
'use client'

import { useState } from 'react'
import { ItemPager } from '@youj/react'

export function TicketHeader({ tickets }: { tickets: Ticket[] }) {
  const [index, setIndex] = useState(0)
  return <ItemPager index={index} total={tickets.length} onIndexChange={setIndex} />
}
```

`index` counts from 0 and the position shows it from 1. The stepper owns no state: `onIndexChange` receives the index to open, and you show that record. It never steps past either end.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` (required) | `number` |  | The open record's index in the list, from 0. |
| `total` (required) | `number` |  | How many records the list has. |
| `onIndexChange` (required) | `(index: number) => void` |  | Called with the index to open: one up or one down. |
| `shortcuts` | `'focus' \| 'global' \| 'none'` | `'focus'` | Where the keys step: `focus`, J, K, ↓ and ↑ while focus is in the stepper; `global`, also J and K anywhere on the page but a field; `none`, never. |
| `locale` | `string` |  | Formats the position. Default: the app's locale (YoujProvider's `locale`). |

Also takes the props of `ComponentProps<'div'>`.

Other props go to the `div` that groups the buttons and the position. The position is formatted with `locale`, or the app's locale from `YoujProvider`.

### Labels

The group's name and the buttons' names are `records`, `previousRecord` and `nextRecord` in `YoujProvider`'s `labels`; the position is `recordOf(position, total)`, which receives both numbers already formatted. All fourteen built-in locales translate them.

### Accessibility

- It is a `group` named "Records" with two buttons, "Next record" and "Previous record", each with `aria-keyshortcuts`.
- At either end the button is disabled but stays focusable (`aria-disabled`), so stepping onto the last record with the keyboard keeps focus where it was.
- The position is a polite live region: "6 of 48" is announced as it changes.
- The keys don't steal typing: in a field, J and K type.

---

# Navigation Menu

> Organize site navigation into panels of related links.

Source: https://www.youj.dev/docs/components/navigation-menu

## Examples

### Demo

```tsx
'use client'

import type { MouseEvent, ReactNode } from 'react'
import {
  Button,
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from '@youj/react'
import { BarChartIcon, BookmarkIcon, CpuIcon, DatabaseIcon, RocketIcon, ShieldCheckIcon, SparklesIcon } from '@youj/icons'

// In a site these are real routes. Here they stay on the page.
const stay = (event: MouseEvent) => event.preventDefault()

export default function NavigationMenuDemo() {
  return (
    <div className="@container w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-canvas">
      <header className="flex items-center justify-between gap-4 border-b border-line px-4 py-2.5">
        <a href="/" onClick={stay} className="rounded-md text-ui-lg font-semibold tracking-tight text-fg focus-ring">
          Acme
        </a>
        <NavigationMenu aria-label="Site">
          <NavigationMenuList>
            <NavigationMenuItem value="products">
              <NavigationMenuTrigger>Products</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="grid w-[calc(100vw-2rem)] max-w-[520px] gap-0.5 sm:grid-cols-2">
                  <li>
                    <Feature href="/deployments" icon={<RocketIcon size={16} />} title="Deployments">
                      Push to preview, promote to production.
                    </Feature>
                  </li>
                  <li>
                    <Feature href="/analytics" icon={<BarChartIcon size={16} />} title="Analytics">
                      Real traffic, no cookies, no sampling.
                    </Feature>
                  </li>
                  <li>
                    <Feature href="/storage" icon={<DatabaseIcon size={16} />} title="Storage">
                      Blobs, KV and Postgres beside your code.
                    </Feature>
                  </li>
                  <li>
                    <Feature href="/functions" icon={<CpuIcon size={16} />} title="Functions">
                      Server code that scales to zero.
                    </Feature>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="resources">
              <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
              <NavigationMenuContent>
                <ul className="flex w-[calc(100vw-2rem)] max-w-[300px] flex-col gap-0.5">
                  <li>
                    <Feature href="/changelog" icon={<SparklesIcon size={16} />} title="Changelog">
                      What shipped this week.
                    </Feature>
                  </li>
                  <li>
                    <Feature href="/security" icon={<ShieldCheckIcon size={16} />} title="Security">
                      SOC 2, pen tests and the trust center.
                    </Feature>
                  </li>
                  <li>
                    <Feature href="/docs/blocks/templates" icon={<BookmarkIcon size={16} />} title="Templates">
                      Start from something that works.
                    </Feature>
                  </li>
                </ul>
              </NavigationMenuContent>
            </NavigationMenuItem>
            {/* Plain links sit beside the triggers with the same look. */}
            <NavigationMenuItem className="hidden @lg:block">
              <NavigationMenuLink href="/pricing" onClick={stay} className={navigationMenuTriggerStyle()}>
                Pricing
              </NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
        <Button size="sm" className="hidden @md:inline-flex">
          Sign up
        </Button>
      </header>
      <div className="flex flex-col items-center gap-2 px-6 py-14 text-center">
        <p className="text-2xl font-semibold tracking-tight text-fg">Ship the web, faster.</p>
        <p className="max-w-sm text-ui-lg text-fg-muted">Move across the menu: the pill follows you, and the panel morphs between sizes.</p>
      </div>
    </div>
  )
}
```

A site header whose triggers open panels of feature cards in one shared popup.

The popup is one surface for every panel. It grows out of the first trigger you open, then slides to the next one while its box morphs to the new panel's size, and the panels trade places: the incoming one arrives from the side you moved toward, and the outgoing one drifts the other way. Move across the triggers in the preview to see it, or set it to ¼ speed.

Panels can hold anything: feature cards with icons, as in the Demo story, or columns of plain links. The popup renders in a portal, and it carries the provider's scope, so Speed and reduced motion reach it.

### The current page

```tsx
'use client'

import type { MouseEvent } from 'react'
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from '@youj/react'

const stay = (event: MouseEvent) => event.preventDefault()

const COMPONENTS = {
  Navigation: ['Tabs', 'Breadcrumb', 'Pagination', 'Sidebar'],
  Overlays: ['Dialog', 'Popover', 'Tooltip', 'Toast'],
}
// The page this header sits on.
const CURRENT = 'Tabs'

export default function NavigationMenuCurrent() {
  return (
    <div className="w-full max-w-xl rounded-xl border border-line bg-canvas px-3 py-2">
      {/* align="center" centers each panel under its trigger. */}
      <NavigationMenu aria-label="Documentation" align="center" className="mx-auto">
        <NavigationMenuList>
          <NavigationMenuItem>
            <NavigationMenuLink href="/docs" onClick={stay} className={navigationMenuTriggerStyle()}>
              Guides
            </NavigationMenuLink>
          </NavigationMenuItem>
          <NavigationMenuItem value="components">
            <NavigationMenuTrigger>Components</NavigationMenuTrigger>
            <NavigationMenuContent>
              <div className="grid w-[calc(100vw-2rem)] max-w-[360px] grid-cols-2 gap-x-2 p-1">
                {Object.entries(COMPONENTS).map(([group, names]) => (
                  <div key={group} className="flex flex-col">
                    <p className="px-2.5 pt-1.5 pb-1 text-ui-xs font-medium tracking-wide text-fg-muted uppercase">{group}</p>
                    {names.map((name) => (
                      // `active` marks the current page: aria-current="page" and a highlight.
                      <NavigationMenuLink
                        key={name}
                        href={`/docs/${name.toLowerCase()}`}
                        onClick={stay}
                        active={name === CURRENT}
                        closeOnClick
                        className="py-1.5 text-fg-muted hover:text-fg data-active:font-medium data-active:text-fg"
                      >
                        {name}
                      </NavigationMenuLink>
                    ))}
                  </div>
                ))}
              </div>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="/changelog" onClick={stay} className={navigationMenuTriggerStyle()}>
              Changelog
            </NavigationMenuLink>
          </NavigationMenuItem>
        </NavigationMenuList>
      </NavigationMenu>
    </div>
  )
}
```

A menu with the current page marked.

Mark the link to the page you're on with `active`. It gets `aria-current="page"` and the highlight. `align` places each panel under its trigger: `start` (the default), `center` or `end`.

### A featured link

```tsx
'use client'

// In a site these are real routes. Here they stay on the page.
const stay = (event: MouseEvent) => event.preventDefault()

const DOCS = [
  { href: '/docs', title: 'Documentation', body: 'Guides, concepts and recipes.' },
  { href: '/docs/api', title: 'API reference', body: 'Every endpoint, with examples.' },
  { href: '/docs/cli', title: 'CLI', body: 'Deploy and roll back from your terminal.' },
]

export default function NavigationMenuFeatured() {
  return (
    <div className="w-full max-w-xl rounded-xl border border-line bg-canvas px-3 py-2">
      <NavigationMenu aria-label="Primary" className="mx-auto">
        <NavigationMenuList>
          <NavigationMenuItem value="developers">
            <NavigationMenuTrigger>Developers</NavigationMenuTrigger>
            <NavigationMenuContent>
              {/* A grid: the featured link spans every row beside the others, and stacks above them on a phone. */}
              <div className="grid w-[calc(100vw-2rem)] max-w-[460px] gap-0.5 sm:grid-cols-[11rem_1fr]">
                <NavigationMenuLink
                  href="/docs/quickstart"
                  onClick={stay}
                  closeOnClick
                  className="flex-col gap-1 bg-accent-subtle p-4 hover:bg-accent-subtle focus-visible:bg-accent-subtle sm:row-span-3"
                >
                  <span className="mb-auto grid size-10 place-items-center rounded-lg border border-line bg-canvas text-accent shadow-xs">
                    <RocketIcon size={20} className="size-5" />
                  </span>
                  <span className="mt-4 font-medium text-fg">Quickstart</span>
                  <span className="text-ui-sm text-fg-muted">Deploy a template and ship your first change in a minute.</span>
                </NavigationMenuLink>
                {DOCS.map((doc) => (
                  <NavigationMenuLink key={doc.href} href={doc.href} onClick={stay} closeOnClick className="flex-col gap-0.5">
                    <span className="font-medium text-fg">{doc.title}</span>
                    <span className="text-ui-sm text-fg-muted">{doc.body}</span>
                  </NavigationMenuLink>
                ))}
              </div>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="/customers" onClick={stay} className={navigationMenuTriggerStyle()}>
              Customers
            </NavigationMenuLink>
          </NavigationMenuItem>
          <NavigationMenuItem>
            <NavigationMenuLink href="/pricing" onClick={stay} className={navigationMenuTriggerStyle()}>
              Pricing
            </NavigationMenuLink>
          </NavigationMenuItem>
        </NavigationMenuList>
      </NavigationMenu>
    </div>
  )
}
```

A Developers panel laid out as a grid, with a featured quickstart link beside text links.

A panel's layout is yours. This one is a grid: the quickstart link spans the panel's full height beside three text links, and stacks above them below the `sm` breakpoint. Open Developers to see it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add navigation-menu
```

It brings `collapsible`, `sliding-indicator`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use it for a site's main navigation when destinations group into a few sections worth previewing, like products, solutions and resources. Don't use it for actions or options, which belong in a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu), or for an app's own navigation, where a [Sidebar](https://www.youj.dev/docs/components/sidebar) or [Tabs](https://www.youj.dev/docs/components/tabs) keep every destination in view. On narrow screens, move the links into a [Sheet](https://www.youj.dev/docs/components/sheet) instead.

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from '@youj/react'

export function SiteNav() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem value="products">
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-[520px] grid-cols-2 gap-0.5">
              <li>
                <NavigationMenuLink href="/deployments">Deployments</NavigationMenuLink>
              </li>
              <li>
                <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="/pricing" className={navigationMenuTriggerStyle()}>
            Pricing
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

Each `NavigationMenuItem` holds either a trigger and its content, or a plain link. Give a plain link `navigationMenuTriggerStyle()` so it matches the triggers beside it. Set a width on each panel's content: the popup measures it, and morphs between panel sizes as you move from trigger to trigger. Add `closeOnClick` to links that should close the menu when followed.

`navigationMenuTriggerStyle()` comes from a client module, so a header that calls it is a Client Component: start the file with `'use client'`. In Next.js, render the framework's link through `render` so navigation stays client-side and prefetches:

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

<NavigationMenuLink render={<Link href="/pricing" />} className={navigationMenuTriggerStyle()}>
  Pricing
</NavigationMenuLink>
```

#### A header with a mobile menu

Show the menu from `md` up. Below it, a Sheet opens from a menu button, holding the same links. Size the Sheet to its content with a width class (`w-64` here, which the Sheet's default width yields to):

```tsx
'use client'

import Link from 'next/link'
import {
  Button,
  NavigationMenu,
  NavigationMenuLink,
  NavigationMenuItem,
  NavigationMenuList,
  Sheet,
  SheetClose,
  SheetContent,
  SheetTitle,
  SheetTrigger,
  navigationMenuTriggerStyle,
} from '@youj/react'

const links = [
  { href: '/features', label: 'Features' },
  { href: '/pricing', label: 'Pricing' },
  { href: '/about', label: 'About' },
]

export function SiteHeader() {
  return (
    <header className="flex items-center justify-between gap-4 border-b border-line px-4 py-3">
      <Link href="/" className="font-semibold">
        Acme
      </Link>

<NavigationMenu aria-label="Main" className="hidden md:flex">
        <NavigationMenuList>
          {links.map((link) => (
            <NavigationMenuItem key={link.href}>
              <NavigationMenuLink render={<Link href={link.href} />} className={navigationMenuTriggerStyle()}>
                {link.label}
              </NavigationMenuLink>
            </NavigationMenuItem>
          ))}
        </NavigationMenuList>
      </NavigationMenu>

<Sheet>
        <SheetTrigger render={<Button variant="outline" className="md:hidden" />}>Menu</SheetTrigger>
        <SheetContent className="w-64">
          <SheetTitle>Menu</SheetTitle>
          <nav aria-label="Mobile" className="flex flex-col gap-1 p-4">
            {links.map((link) => (
              <SheetClose key={link.href} nativeButton={false} render={<Link href={link.href} />} className="rounded-md px-3 py-2 text-ui hover:bg-hover">
                {link.label}
              </SheetClose>
            ))}
          </nav>
        </SheetContent>
      </Sheet>
    </header>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

Every part passes its props through to the Base UI part of the same name. `NavigationMenu` also takes the popup's placement: `align`, `alignOffset`, `side` and `sideOffset`. The ones you'll use most:

| Part | Prop | Type | Default |
| --- | --- | --- | --- |
| `NavigationMenu` | `align` | `'start' \| 'center' \| 'end'` | `'start'` |
| `NavigationMenu` | `alignOffset`, `side`, `sideOffset` | `number`, `'top' \| 'bottom' \| …`, `number` | `0`, `'bottom'`, `8` |
| `NavigationMenu` | `value`, `defaultValue`, `onValueChange` | the open item's `value` | – |
| `NavigationMenu` | `delay` | `number`, ms before opening on hover | `50` |
| `NavigationMenu` | `closeDelay` | `number`, ms before closing | `50` |
| `NavigationMenuItem` | `value` | `any` | – |
| `NavigationMenuTrigger` | `disabled` | `boolean` | `false` |
| `NavigationMenuLink` | `active` | `boolean` | `false` |
| `NavigationMenuLink` | `closeOnClick` | `boolean` | `false` |
| `NavigationMenuContent` | `keepMounted` | `boolean` | `false` |

Takes the props of `NavigationMenuPrimitive.Root.Props`, `Pick<NavigationMenuPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' | 'collisionPadding'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Hover pill | `spring.smooth` | 0.36s, bounce 0 | glides between triggers and links with the pointer and keyboard focus |
| Popup in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scales from 0.96 and fades, out of the trigger |
| Popup out | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Popup between triggers | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | slides to the next trigger and morphs to its panel size |
| Panels trade places | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | 24px drift and fade, away from the way you moved |
| Chevron | `spring.snappy` | 0.2s, bounce 0 | turns over while its panel is open |
| Trigger color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |

**Reduced motion:** The popup and its panels appear, resize and swap at once. The pill jumps and the chevron flips.

In right-to-left layouts the pill, the popup's slide and the panels' drift all mirror.

#### Reduced motion

The menu works the same, without movement: panels appear and swap in place, the popup takes its new size at once, the pill jumps to the item under the pointer or focus, and the chevron flips instead of turning.

### Accessibility

- `NavigationMenu` is a `nav` landmark. Name it with `aria-label` ("Main"), and give each navigation landmark on a page a different name.
- Triggers are buttons with `aria-expanded`. Their chevron is decorative.
- The current page's link carries `aria-current="page"` when you set `active`.
- The hover pill is hidden from assistive technology.

| Key | Action |
| --- | --- |
| Tab | Move between triggers and links, and into an open panel. |
| Enter / Space / ↓ | Open the focused trigger's panel. |
| Escape | Close the panel and return focus to its trigger. |

---

# Stepper

> Show progress through a sequence, including completed, current, upcoming and failed steps.

Source: https://www.youj.dev/docs/components/stepper

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, Card, CardContent, Stepper, type StepperStep } from '@youj/react'

const CHECKOUT: StepperStep[] = [
  { id: 'cart', title: 'Cart' },
  { id: 'shipping', title: 'Shipping' },
  { id: 'payment', title: 'Payment' },
  { id: 'review', title: 'Review' },
]

export default function StepperDemo() {
  const [current, setCurrent] = useState(1)
  const done = current === CHECKOUT.length

return (
    <Card className="w-full max-w-xl">
      <CardContent className="flex flex-col gap-6">
        {/* Done steps are buttons: press one to go back to it. */}
        <Stepper steps={CHECKOUT} current={current} onStepClick={setCurrent} aria-label="Checkout" />
        <div className="flex items-center justify-between gap-2">
          <p className="text-ui-sm text-fg-muted" aria-live="polite">
            {done ? 'Order placed.' : `Step ${current + 1} of ${CHECKOUT.length}`}
          </p>
          <div className="flex gap-2">
            <Button variant="ghost" onClick={() => setCurrent((c) => Math.max(0, c - 1))} disabled={current === 0}>
              Back
            </Button>
            {done ? (
              <Button variant="outline" onClick={() => setCurrent(0)}>
                Start over
              </Button>
            ) : (
              <Button onClick={() => setCurrent((c) => c + 1)}>{current === CHECKOUT.length - 1 ? 'Place order' : 'Continue'}</Button>
            )}
          </div>
        </div>
      </CardContent>
    </Card>
  )
}
```

A four-step checkout stepper with Back and Continue buttons; done steps can be pressed to go back.

### Vertical

```tsx
'use client'

import { useState } from 'react'
import { Button, Card, CardContent, Stepper, type StepperStep } from '@youj/react'

const ONBOARDING: StepperStep[] = [
  { id: 'account', title: 'Create account', description: 'Name and email' },
  { id: 'workspace', title: 'Workspace', description: 'Name and URL' },
  { id: 'integrations', title: 'Integrations', description: 'GitHub, Slack', optional: true },
  { id: 'invite', title: 'Invite team', description: 'Up to 10 seats' },
]

export default function StepperVertical() {
  const [current, setCurrent] = useState(2)

return (
    <Card className="w-80">
      <CardContent className="flex flex-col gap-5">
        <Stepper steps={ONBOARDING} current={current} orientation="vertical" onStepClick={setCurrent} aria-label="Setup" />
        <Button variant="outline" size="sm" className="self-start" onClick={() => setCurrent((c) => (c + 1) % (ONBOARDING.length + 1))}>
          {current === ONBOARDING.length ? 'Start over' : 'Next step'}
        </Button>
      </CardContent>
    </Card>
  )
}
```

A vertical stepper with descriptions.

`orientation="vertical"` stacks the steps with their descriptions, for a sidebar beside the flow. The connector fills downwards.

A step's `description` sits under its title, and `optional` adds "Optional" to it.

### States

```tsx
'use client'

import { Stepper, type StepperStep } from '@youj/react'

const CHECKOUT: StepperStep[] = [
  { id: 'cart', title: 'Cart' },
  { id: 'shipping', title: 'Shipping' },
  { id: 'payment', title: 'Payment' },
  { id: 'review', title: 'Review' },
]

const DECLINED = CHECKOUT.map((step) => (step.id === 'payment' ? { ...step, invalid: true, description: 'Card declined' } : step))

export default function StepperStates() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-8">
      <Stepper steps={CHECKOUT} current={0} aria-label="Checkout, not started" />
      <Stepper steps={DECLINED} current={2} aria-label="Checkout, payment failed" />
      <Stepper steps={CHECKOUT} current={CHECKOUT.length} aria-label="Checkout, all steps complete" />
    </div>
  )
}
```

Steps showing an error and every step complete.

A step with `error` shows a warning mark and a danger title, whatever its position, so a failed validation stays visible after the person moves on. The last row shows every step complete.

On narrow screens, `compact` hides the titles and descriptions below the `sm` breakpoint and leaves the discs and connectors. The titles are still read out, so the steps keep their names.

### Detour

```tsx
'use client'

import { useState } from 'react'
import { Button, Stepper, type StepperStep } from '@youj/react'

const ROUTE: StepperStep[] = [
  { id: 'depot', title: 'Harbor depot', description: '09:48' },
  { id: 'yard', title: 'North yard', description: '10:41' },
  { id: 'ridge', title: 'Ridge road', description: 'Speed −24%', invalid: true },
  { id: 'junction', title: 'Ridge junction', description: '12:55' },
  { id: 'summit', title: 'Summit DC', description: 'ETA 15:49' },
]

export default function StepperDetour() {
  const [proposed, setProposed] = useState(true)
  return (
    <div className="flex w-full max-w-2xl flex-col gap-6">
      <Stepper steps={ROUTE} current={2} aria-label="Route" detour={proposed ? { from: 1, to: 3, label: 'River road detour', detail: '−31 min' } : undefined} />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setProposed((on) => !on)}>
        {proposed ? 'Dismiss detour' : 'Propose detour'}
      </Button>
    </div>
  )
}
```

A horizontal stepper with a detour drawn over the steps it bypasses.

`detour` draws a rerouted stretch on a horizontal stepper: a dotted arc in the accent leaves the step at `from`, passes over the steps it bypasses and lands on the step at `to`, with its `label` and `detail` riding the top. Bypassed steps carry `data-bypassed`. It's measured from the discs, so it follows resizes and RTL; a vertical stepper ignores it.

### Flagged

```tsx
'use client'

import { Stepper, type StepperStep } from '@youj/react'

const LAUNCH_PLAN: StepperStep[] = [
  { id: 'scope', title: 'Scope', description: 'Oct 2' },
  { id: 'design', title: 'Design', description: 'By Oct 9' },
  { id: 'security', title: 'Security', description: 'By Oct 16' },
  { id: 'freeze', title: 'Freeze', description: 'Oct 23' },
  { id: 'submit', title: 'Submission', description: 'Oct 30, deadline', flagged: true },
  { id: 'launch', title: 'Launch', description: 'Nov 12' },
]

export default function StepperFlagged() {
  return <Stepper steps={LAUNCH_PLAN} current={1} aria-label="Launch plan" className="w-full max-w-4xl" />
}
```

A launch plan as dated milestones, with the submission deadline flagged.

`flagged` calls a step out without failing it: until it's done, its disc wears a flag and its description takes the danger ink, and the disc carries `data-yj-flagged`. The flag is decorative, so put the reason in the `description` ("Oct 30, deadline"), which is read with the title. Use `invalid` instead when the step has actually gone wrong.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stepper
```

It brings `icon-alert-triangle`, `icon-check`, `icon-flag`, `icon-route`, `youj-core`, `youj-labels-stepper`, `youj-presets`, `youj-ui-core` with it.

Use a stepper to show progress through a fixed sequence people move through in order: checkout, onboarding, a setup flow. It shows state, it doesn't hold the steps' content. For a flow that shows one step at a time with Back and Continue built in, use a [Wizard](https://www.youj.dev/docs/components/wizard), which draws its own stepper. For a flow that spans pages, with steps as links, use [Stepper Nav](https://www.youj.dev/docs/components/stepper-nav). For progress that has no named steps, use a [Progress](https://www.youj.dev/docs/components/progress) bar.

```tsx
import { Stepper, type StepperStep } from '@youj/react'

const steps: StepperStep[] = [
  { id: 'cart', title: 'Cart' },
  { id: 'shipping', title: 'Shipping' },
  { id: 'payment', title: 'Payment' },
  { id: 'review', title: 'Review' },
]

export function CheckoutProgress({ current }: { current: number }) {
  return <Stepper steps={steps} current={current} aria-label="Checkout" />
}
```

`current` is the index of the step in progress. Steps before it are complete, and `current={steps.length}` marks every step done. The current step's disc is the solid one, in the accent; done steps step back to a tint with their check, and upcoming ones are outlined. Pass `onStepClick` and done steps, and the current one, become buttons that go back to them. Upcoming steps stay inert, so the stepper can't skip ahead of the flow's own validation.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `readonly StepperStep[]` |  |  |
| `current` (required) | `number` |  | Index of the current step. Steps before it are complete; `steps.length` means all are done. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
| `onStepClick` | `(index: number) => void` |  | Makes done steps (and the current one) buttons that go back to them. |
| `stepHref` | `(index: number) => string \| undefined` |  | Makes done steps (and the current one) links to their pages instead, for flows that span pages. `onStepClick` still fires on click. |
| `compact` | `boolean` | `false` | Hides titles and descriptions below the `sm` breakpoint (horizontal only), leaving the discs and connectors. |
| `detour` | `StepperDetour` |  | A rerouted stretch, drawn as an arc from one step over the ones it bypasses to the step it rejoins. Horizontal only. |

Also takes the props of `ComponentProps<'ol'>`.

#### Steps

Each entry in `steps` is a `StepperStep`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | A stable key. |
| `title` (required) | `ReactNode` |  | The step's name. |
| `description` | `ReactNode` |  | A second line under the title. |
| `optional` | `boolean` |  | Adds "Optional" under the title. |
| `invalid` | `boolean` |  | Marks the step as failed (e.g. its validation did not pass). |
| `flagged` | `boolean` |  | Calls a step out without failing it (a deadline, a milestone to watch): until it's done its disc wears a flag and its description the danger ink. The flag is decorative, so say why in the description. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Connector fill | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | scales from the inline start (or down) when the step before it is done, and drains back if you return |
| Disc | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | background, border and ring change as the step changes state |
| Title color | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) |  |
| Check and warning marks |  |  | Youj icons draw on when they mount |
| Detour | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | the arc draws from the step it leaves, and its label rises in as the line arrives |

**Reduced motion:** Connectors fill and drain at once, and marks appear without drawing.

The fill is a transform on a Motion value, so going back mid-fill drains from where the fill is instead of restarting.

#### Reduced motion

Connectors fill and drain instantly, discs change color at once, the check and warning marks appear without drawing and a detour is drawn in place. The state reads exactly the same.

### Accessibility

- The stepper is an ordered list named "Progress" by default. Name it after the flow with `aria-label`.
- The current step has `aria-current="step"`, and every step's state is written out after its title for screen readers: "Payment, has an error".
- With `onStepClick`, the done steps and the current one are real buttons, and with `stepHref` they're links. Upcoming steps aren't focusable.
- The discs, connectors and marks are decorative (`aria-hidden`); the text carries the state.
- A detour's label is read after the step it leaves, with where it rejoins ("Detour, rejoins at step 4", `stepDetour` in the labels).

---

# Menubar

> Group app commands in familiar menus such as File, Edit and View.

Source: https://www.youj.dev/docs/components/menubar

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from '@youj/react'

export default function MenubarDemo() {
  const [ruler, setRuler] = useState(true)
  const [wordCount, setWordCount] = useState(false)
  const [zoom, setZoom] = useState('100')

return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New document <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Open… <MenubarShortcut>⌘O</MenubarShortcut>
          </MenubarItem>
          <MenubarSub>
            <MenubarSubTrigger>Open recent</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>Q3 planning.md</MenubarItem>
              <MenubarItem>Launch checklist.md</MenubarItem>
              <MenubarItem>Interview notes.md</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Save <MenubarShortcut>⌘S</MenubarShortcut>
          </MenubarItem>
          <MenubarItem disabled>
            Save as template <MenubarShortcut>⇧⌘S</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Undo <MenubarShortcut>⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            Copy <MenubarShortcut>⌘C</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Paste <MenubarShortcut>⌘V</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem variant="danger">Delete document</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarGroup>
            <MenubarLabel>Show</MenubarLabel>
            <MenubarCheckboxItem checked={ruler} onCheckedChange={setRuler}>
              Ruler
            </MenubarCheckboxItem>
            <MenubarCheckboxItem checked={wordCount} onCheckedChange={setWordCount}>
              Word count
            </MenubarCheckboxItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarRadioGroup value={zoom} onValueChange={setZoom}>
            <MenubarLabel>Zoom</MenubarLabel>
            <MenubarRadioItem value="75">75%</MenubarRadioItem>
            <MenubarRadioItem value="100">100%</MenubarRadioItem>
            <MenubarRadioItem value="125">125%</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Help</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Keyboard shortcuts</MenubarItem>
          <MenubarItem>What’s new</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

A document menu bar with File, Edit and View menus, including a submenu, checkbox items and a radio group.

Once a menu is open, the bar behaves like a desktop menu bar: hovering another trigger, or pressing `←` or `→`, closes the open menu and opens its neighbor without another click. The open trigger is marked by one [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator), so the mark glides along the bar as you scrub, and retargets if you change direction mid-glide. With no menu open, triggers light up on hover on their own.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add menubar
```

It brings `dropdown-menu`, `sliding-indicator`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a menubar for the command surface of a document-style app: an editor, a design tool, an IDE in the browser, where people expect menus they can scrub across. For one menu behind a button, use a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu). For site navigation between pages, use a [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu).

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from '@youj/react'

export function EditorMenubar() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New document <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Print…</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Undo</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

Each `MenubarMenu` is a menu whose trigger sits in the bar. Its content takes everything a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) does, under Menubar names: `MenubarItem` (with `variant="danger"` and `inset`), `MenubarCheckboxItem`, `MenubarRadioGroup` and `MenubarRadioItem`, `MenubarLabel`, `MenubarGroup`, `MenubarSeparator`, `MenubarShortcut`, and submenus with `MenubarSub`, `MenubarSubTrigger` and `MenubarSubContent`. The API matches shadcn/ui's Menubar, so its examples paste in.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Menubar

Takes the props of `MenubarPrimitive.Props`.

Base UI's Menubar takes `orientation` (`'horizontal'` by default, which sets the arrow keys), `loopFocus` (default `true`), `modal` and `disabled`.

#### MenubarContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | Where the portal renders. Default: document.body. |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` |  | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |

It defaults to `align="start"` with the first row under the trigger's label, `sideOffset={6}`, and takes Dropdown Menu's `side`, `align`, `alignOffset`, `collisionPadding` and `container`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open-menu mark | `spring.smooth` | 0.36s, bounce 0 | glides to the trigger whose menu opened |
| Mark appears and leaves | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | when the first menu opens and the last one closes |
| Menu opens | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | yj-pop from the trigger, as Dropdown Menu |
| Row highlight | `spring.smooth` | 0.36s, bounce 0 | one highlight glides between rows, as Dropdown Menu |

**Reduced motion:** The mark jumps to the open trigger, menus appear without the pop, and the row highlight jumps.

#### Reduced motion

The mark moves straight to the open trigger, menus open in place and rows highlight without gliding. Which menu is open reads exactly the same.

### Accessibility

- The bar is a `menubar` and each trigger a `menuitem` with `aria-haspopup` and `aria-expanded`. It's a single tab stop; `←` and `→` move between triggers and wrap, mirrored in right-to-left layouts.
- `↓`, `Enter` or `Space` opens a menu and focuses its first row; inside, the arrow keys, typeahead, `Home` and `End` work as in any menu. `Escape` closes it and returns focus to its trigger.
- The gliding mark is decorative (`aria-hidden`). In forced-colors mode the open trigger gets an outline instead.

---

# Bottom Tab Bar

> Keep a phone layout’s main destinations within reach at the bottom of the screen.

Source: https://www.youj.dev/docs/components/bottom-tab-bar

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { BellIcon, HomeIcon, InboxIcon, SearchIcon, UserIcon } from '@youj/icons'
import { BottomTabBar, BottomTabBarItem } from '@youj/react'

const TABS = [
  { id: 'home', label: 'Home', icon: <HomeIcon size={20} strokeWidth={1.75} /> },
  { id: 'search', label: 'Search', icon: <SearchIcon size={20} strokeWidth={1.75} /> },
  { id: 'inbox', label: 'Inbox', icon: <InboxIcon size={20} strokeWidth={1.75} />, badge: 3 },
  { id: 'activity', label: 'Activity', icon: <BellIcon size={20} strokeWidth={1.75} />, badge: true },
  { id: 'profile', label: 'Profile', icon: <UserIcon size={20} strokeWidth={1.75} /> },
]

export default function BottomTabBarDemo() {
  const [current, setCurrent] = useState('home')
  return (
    // A phone-sized frame. In an app the bar is fixed to the viewport: leave out className="absolute".
    <div className="relative h-[30rem] w-[22.5rem] max-w-full overflow-hidden rounded-[2rem] border border-line bg-canvas shadow-lg">
      <div className="flex flex-col gap-3 p-5 pt-10">
        <p className="text-2xl font-semibold tracking-tight text-fg capitalize">{current}</p>
        {Array.from({ length: 4 }, (_, i) => (
          <div key={i} className="h-16 rounded-xl border border-line bg-surface" />
        ))}
      </div>
      <BottomTabBar className="absolute">
        {TABS.map((tab) => (
          <BottomTabBarItem
            key={tab.id}
            href={`#${tab.id}`}
            icon={tab.icon}
            label={tab.label}
            badge={tab.badge}
            active={current === tab.id}
            onClick={(event) => {
              event.preventDefault()
              setCurrent(tab.id)
            }}
          />
        ))}
      </BottomTabBar>
    </div>
  )
}
```

A phone-sized screen with five tabs, a count on Inbox and a dot on Activity.

### Badges

```tsx
'use client'

import { useState } from 'react'
import { CalendarIcon, HomeIcon, MessageIcon } from '@youj/icons'
import { BottomTabBar, BottomTabBarItem, Button } from '@youj/react'

export default function BottomTabBarBadges() {
  const [current, setCurrent] = useState('today')
  const [unread, setUnread] = useState(128)
  const [invite, setInvite] = useState(true)
  const tabs = [
    { id: 'today', label: 'Today', icon: <HomeIcon size={20} strokeWidth={1.75} /> },
    // A count reads "Messages, 128 unread"; past 99 it shows 99+.
    { id: 'messages', label: 'Messages', icon: <MessageIcon size={20} strokeWidth={1.75} />, badge: unread, badgeLabel: `${unread} unread` },
    // `true` is a dot: something new, no count.
    { id: 'calendar', label: 'Calendar', icon: <CalendarIcon size={20} strokeWidth={1.75} />, badge: invite, badgeLabel: 'new invite' },
  ]

return (
    <div className="relative h-[20rem] w-[22.5rem] max-w-full overflow-hidden rounded-[2rem] border border-line bg-canvas shadow-lg">
      <div className="flex flex-col items-start gap-2 p-5 pt-10">
        <Button size="sm" variant="outline" onClick={() => setUnread((n) => (n > 0 ? 0 : 128))}>
          {unread > 0 ? 'Read all messages' : 'Receive 128 messages'}
        </Button>
        <Button size="sm" variant="outline" onClick={() => setInvite((v) => !v)}>
          {invite ? 'Open the invite' : 'Get an invite'}
        </Button>
      </div>
      <BottomTabBar className="absolute" aria-label="Sections">
        {tabs.map((tab) => (
          <BottomTabBarItem
            key={tab.id}
            href={`#${tab.id}`}
            icon={tab.icon}
            label={tab.label}
            badge={tab.badge}
            badgeLabel={tab.badgeLabel}
            active={current === tab.id}
            onClick={(event) => {
              event.preventDefault()
              setCurrent(tab.id)
            }}
          />
        ))}
      </BottomTabBar>
    </div>
  )
}
```

Tabs with a count, a dot and no badge.

`badge` counts what's waiting. A number shows as a count (99+ past 99), `true` shows a dot, and `0` or `false` shows nothing. Screen readers hear the badge after the label: "Inbox, 3 new" by default, or your own words with `badgeLabel`.

Keep badges for things that need the person, like unread messages or an invitation. A badge on every tab stops meaning anything.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add bottom-tab-bar
```

It brings `sliding-indicator`, `youj-core`, `youj-labels-bottom-tab-bar`, `youj-presets`, `youj-ui-core` with it.

Use it for the three to five top-level destinations of a phone layout: the places people switch between all day, within reach of the thumb. Each tab goes to a page, so the tabs are links. To switch panels of content inside one page, use [Tabs](https://www.youj.dev/docs/components/tabs). On wide screens the same destinations belong in an [App Header](https://www.youj.dev/docs/components/app-header) or a [Sidebar](https://www.youj.dev/docs/components/sidebar), so render the bar only below your phone breakpoint.

```tsx
import { BottomTabBar, BottomTabBarItem } from '@youj/react'
import { HomeIcon, InboxIcon, SearchIcon, UserIcon } from '@youj/icons'

export function PhoneNav({ pathname }: { pathname: string }) {
  return (
    <BottomTabBar className="md:hidden">
      <BottomTabBarItem href="/" icon={<HomeIcon />} label="Home" active={pathname === '/'} />
      <BottomTabBarItem href="/search" icon={<SearchIcon />} label="Search" active={pathname === '/search'} />
      <BottomTabBarItem href="/inbox" icon={<InboxIcon />} label="Inbox" badge={3} active={pathname === '/inbox'} />
      <BottomTabBarItem href="/me" icon={<UserIcon />} label="Profile" active={pathname === '/me'} />
    </BottomTabBar>
  )
}
```

The bar is fixed to the bottom of the viewport and pads itself by the safe-area insets, so it clears the home indicator and the rounded corners on its own. For that to work, the page needs `viewport-fit=cover` in its viewport meta tag. Give the page's content bottom padding as tall as the bar, so nothing ends up hidden behind it. The previews pass `className="absolute"` to place it inside a phone frame instead.

Each `BottomTabBarItem` renders an `<a>`. Pass `render` for a router's link, for example `render={<Link href="/inbox" />}`. Mark the current destination with `active`: its icon sits on a pill, which glides from tab to tab on the `smooth` spring, and its icon and label turn to ink.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` (required) | `ReactNode` |  |  |
| `label` (required) | `ReactNode` |  |  |
| `active` | `boolean` | `false` | The current destination. |
| `badge` | `number \| boolean` |  | A count (99+ past 99) or `true` for a dot. |
| `badgeLabel` | `string` |  | How the badge is read after the label. Default "N new", or "new" for a dot. |

Also takes the props of `useRender.ComponentProps<'a'>`.

`BottomTabBar` is a `nav` and takes its props. Its `aria-label` defaults to "Primary".

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Current pill | `spring.smooth` | 0.36s, bounce 0 | one Sliding Indicator glides to the current tab, hugging its icon |
| Label and icon color | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | to ink on the current tab, and on hover |
| Icon |  | per icon | a Youj icon plays its own motion on hover and keyboard focus |

**Reduced motion:** The pill jumps to the new tab, colors change at once, and icons stay still.

#### Reduced motion

The pill moves to the new tab at once instead of gliding, and the icons don't play. Colors change instantly. Navigation and focus work the same.

### Accessibility

- The bar is a `nav` landmark named "Primary". Rename it with `aria-label` if the page has another primary navigation.
- Tabs are links in a list, so Tab reaches each one and the browser's own link handling applies: open in a new tab, copy the address, and so on. The current tab carries `aria-current="page"`.
- The badge is hidden from assistive technology and read as text after the label, so "Inbox, 3 new" is one name.
- The focus ring draws around the icon's pill, where the eye already is. Each tab is at least 56px tall.

---

# Dock

> Navigate with a row of icons that magnify under the pointer or keyboard focus.

Source: https://www.youj.dev/docs/components/dock

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CompassIcon, HomeIcon, ImageIcon, MailIcon, MessageIcon, MusicIcon, SettingsIcon, TerminalIcon } from '@youj/icons'
import { Dock, type DockItem } from '@youj/motion/interactions'

// Youj icons play their own choreography when their dock button is hovered or focused.
const APPS: DockItem[] = [
  { id: 'home', label: 'Home', icon: <HomeIcon /> },
  { id: 'browser', label: 'Browser', icon: <CompassIcon /> },
  { id: 'mail', label: 'Mail', icon: <MailIcon /> },
  { id: 'messages', label: 'Messages', icon: <MessageIcon /> },
  { id: 'photos', label: 'Photos', icon: <ImageIcon /> },
  { id: 'music', label: 'Music', icon: <MusicIcon /> },
  { id: 'terminal', label: 'Terminal', icon: <TerminalIcon /> },
  { id: 'settings', label: 'Settings', icon: <SettingsIcon /> },
]

export default function DockDemo() {
  const [app, setApp] = useState('mail')
  const current = APPS.find((a) => a.id === app)

return (
    <div className="flex h-64 w-full flex-col items-center justify-between pt-6 pb-3">
      <p className="text-sm text-fg-muted">
        <span className="font-medium text-fg">{current?.label}</span> is open
      </p>
      {/* Eight icons are wider than a phone: the dock scrolls inside its own frame, with room above for the lens and tooltip. */}
      <div className="-mt-12 max-w-full overflow-x-auto px-2 pt-12 [scrollbar-width:none]">
        <Dock items={APPS} value={app} onValueChange={setApp} size={44} label="Applications" />
      </div>
    </div>
  )
}
```

A row of eight app icons that magnify under the pointer or keyboard focus, with a dot on the open app.

### How it moves

```tsx
'use client'

import { useState } from 'react'
import { BoldIcon, CodeIcon, ItalicIcon, LinkIcon, ListIcon, QuoteIcon } from '@youj/icons'
import { Dock, type DockItem } from '@youj/motion/interactions'

const TOOLS: DockItem[] = [
  { id: 'bold', label: 'Bold', icon: <BoldIcon /> },
  { id: 'italic', label: 'Italic', icon: <ItalicIcon /> },
  { id: 'link', label: 'Link', icon: <LinkIcon /> },
  { id: 'quote', label: 'Quote', icon: <QuoteIcon /> },
  { id: 'list', label: 'List', icon: <ListIcon /> },
  { id: 'code', label: 'Code', icon: <CodeIcon /> },
]

// The same six tools, with two lenses: a quiet one for a dense toolbar, and the default.
const LENSES = [
  { name: 'Toolbar', props: { size: 32, magnification: 1.3, distance: 90 }, note: 'size 32 · magnification 1.3 · distance 90' },
  { name: 'Default', props: {}, note: 'size 48 · magnification 1.6 · distance 140' },
]

export default function DockLens() {
  const [tool, setTool] = useState('bold')

return (
    <div className="flex w-full flex-col items-center gap-10 py-4">
      {LENSES.map(({ name, props, note }) => (
        <figure key={name} className="flex flex-col items-center gap-3">
          <Dock items={TOOLS} value={tool} onValueChange={setTool} label={`${name} formatting`} {...props} />
          <figcaption className="font-mono text-[11px] text-fg-muted">{note}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

A dock with its lens shaped by `size`, `magnification` and `distance`.

One spring smooths the pointer's position and a second fades the effect in and out. Each icon's scale and offset is a pure function of those two values, so neighbors can never disagree about where they are, and the point under the cursor stays under the cursor while the row grows around it. Icons grow up from their baseline, and the backplate widens with them through a `clip-path` inset. Nothing triggers layout.

Shape the lens with three props: `size` is the resting icon size, `magnification` the peak scale under the pointer, and `distance` how far, in pixels, the effect reaches. A dense toolbar wants a small, quiet lens, and an app launcher can afford the default.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dock
```

It brings `youj-core`, `youj-labels-dock` with it.

Use it for a short row of destinations people return to, where the row itself is a signature of the product: a launcher, a portfolio's sections, a creative tool's modes. Keep it to about five to ten items that are recognizable by icon alone. Don't use it for primary app navigation with text labels, or for more items than fit on a phone. A [Sidebar](https://www.youj.dev/docs/components/sidebar) or [Tabs](https://www.youj.dev/docs/components/tabs) serve those better.

```tsx
import { useState } from 'react'
import { HomeIcon, LayersIcon, MailIcon } from '@youj/icons'
import { Dock, type DockItem } from '@youj/motion/interactions'

const items: DockItem[] = [
  { id: 'home', label: 'Home', icon: <HomeIcon /> },
  { id: 'mail', label: 'Mail', icon: <MailIcon /> },
  { id: 'docs', label: 'Docs', icon: <LayersIcon />, href: '/docs' },
]

export function AppDock() {
  const [active, setActive] = useState('home')
  return <Dock items={items} value={active} onValueChange={setActive} />
}
```

Items render as buttons, or as links when they have an `href`. The item whose `id` matches `value` gets a dot, which travels to the next active item.

```ts
interface DockItem {
  id: string
  label: string // accessible name and tooltip
  icon: ReactNode
  href?: string // render as a link
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `DockItem[]` |  |  |
| `value` | `string` |  | The active item's id; it gets the indicator dot. |
| `onValueChange` | `(id: string) => void` |  |  |
| `size` | `number` | `48` | Resting icon size in px. In a container too narrow for the row, the icons shrink to fit it, to no less than 28. |
| `magnification` | `number` | `1.6` | Peak scale under the pointer. |
| `distance` | `number` | `140` | How far the magnification reaches, in px from the pointer. |
| `label` | `string` | `"Dock"` | Accessible name of the toolbar. |
| `className` | `string` |  |  |

### Keyboard

The dock is a single tab stop (`role="toolbar"`). The arrow keys move focus, `Home` and `End` jump to the ends, and `Enter` or `Space` activates. Keyboard focus magnifies exactly like the pointer, and shows the same tooltip. Tab into the preview and try it.

> **Icons that answer back:** The demo uses Youj's [animated icons](https://www.youj.dev/docs/icons). Each one plays its own choreography when its dock button is hovered or focused, with no wiring: icons listen to their closest interactive parent.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Magnification | `spring.snappy` | 0.2s, bounce 0 | pointer position and effect strength |
| Active indicator | `spring.smooth` | 0.36s, bounce 0 | travels between items |
| Tooltip in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) |  |
| Tooltip out | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |

**Reduced motion:** Icons stay at their resting size. Tooltips and the active indicator change instantly.

#### Reduced motion

The lens is off: every icon stays at its resting size, under the pointer and under keyboard focus alike. Tooltips still appear on hover and focus, and the active dot still marks the current item, but both change instantly instead of traveling. The dock stays a complete, labeled toolbar.

### Accessibility

- It's a `toolbar` with a roving tab stop, named by `label` (default "Dock").
- Each item's accessible name is its `label`. Tooltips are visual only, because the name is already on the button.
- The active item carries `aria-current`.
- Touch input doesn't magnify: on a phone, the dock is a plain row of buttons.

---

# Alert

> Show a message that needs attention within the page, with optional dismissal.

Source: https://www.youj.dev/docs/components/alert

## Examples

### Demo

```tsx
'use client'

import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
  Badge,
  Button,
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Progress,
  ProgressLabel,
  ProgressValue,
} from '@youj/react'

export default function AlertDemo() {
  return (
    <div className="flex w-full max-w-xl flex-col">
      {/* The gap is the alert's own margin, so it collapses away with the alert. */}
      <Alert variant="warning" dismissible className="mb-4">
        <AlertTitle>You’ve used 82% of this month’s bandwidth</AlertTitle>
        <AlertDescription>
          At 100% we keep serving traffic and bill overage at $0.15 per GB. Raise the limit or upgrade to avoid surprises.
        </AlertDescription>
        <AlertAction>
          <Button size="sm">Upgrade to Pro</Button>
          <Button size="sm" variant="ghost">
            Set a spend limit
          </Button>
        </AlertAction>
      </Alert>
      <Card size="sm">
        <CardHeader>
          <CardTitle>Hobby plan</CardTitle>
          <CardDescription>1 concurrent build · community support</CardDescription>
          <CardAction>
            <Badge variant="secondary">Current</Badge>
          </CardAction>
        </CardHeader>
        <CardContent>
          <Progress value={82} getAriaValueText={() => '82 of 100 GB'}>
            <ProgressLabel>Bandwidth</ProgressLabel>
            <ProgressValue>{() => '82 of 100 GB'}</ProgressValue>
          </Progress>
        </CardContent>
      </Card>
    </div>
  )
}
```

A dismissible bandwidth warning with two actions; the card below glides up when it goes.

### Severity

```tsx
'use client'

import { Alert, AlertDescription, AlertTitle } from '@youj/react'

export default function AlertVariants() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Alert variant="info">
        <AlertTitle>Scheduled maintenance on October 3</AlertTitle>
        <AlertDescription>The dashboard is read-only from 02:00 to 02:20 UTC. Deployments keep serving.</AlertDescription>
      </Alert>
      <Alert variant="success">
        <AlertTitle>youj.io is verified</AlertTitle>
        <AlertDescription>DNS records match. HTTPS certificates are issued automatically.</AlertDescription>
      </Alert>
      <Alert variant="warning">
        <AlertDescription>Your API token “CI deploys” expires in 3 days.</AlertDescription>
      </Alert>
      <Alert variant="danger">
        <AlertTitle>Payment failed</AlertTitle>
        <AlertDescription>
          The card ending 4242 was declined. <a href="#billing">Update your payment method</a> to keep deploying.
        </AlertDescription>
      </Alert>
    </div>
  )
}
```

The four severities.

`variant` is `info`, the default, `success`, `warning` or `danger`. Each tints the surface and brings its own [Youj icon](https://www.youj.dev/docs/icons), which plays once as the alert appears. Info draws its stem and drops the dot, success draws its ring and check, warning rocks on its base, and danger shakes.

`danger` is the same name [Button](https://www.youj.dev/docs/components/button), [Badge](https://www.youj.dev/docs/components/badge), the menu items and the charts and meters (`tone`) use, and it is the name of the color role (`--yj-danger`), so one word means "failed, or can't be undone" everywhere.

Links in the title or description are underlined in the foreground color, so they read as links on every tint.

### Dismissing

```tsx
'use client'

import { useState } from 'react'
import { Alert, AlertDescription, AlertTitle, Button } from '@youj/react'

const NOTICES = [
  { id: 'maintenance', variant: 'info', title: 'Maintenance on October 3', body: 'Read-only from 02:00 to 02:20 UTC.' },
  { id: 'domain', variant: 'success', title: 'youj.io is verified', body: 'Certificates are issued automatically.' },
  { id: 'token', variant: 'warning', title: 'A token expires in 3 days', body: '“CI deploys” stops working on Friday.' },
  { id: 'payment', variant: 'danger', title: 'Payment failed', body: 'Update the card ending 4242.' },
] as const

export default function AlertDismissible() {
  const [open, setOpen] = useState<Record<string, boolean>>({})

return (
    <div className="flex w-full max-w-md flex-col">
      {/* Each alert's spacing is its own margin, so it collapses with it and leaves no gap behind. */}
      {NOTICES.map((notice) => (
        <Alert
          key={notice.id}
          variant={notice.variant}
          className="mb-2"
          open={open[notice.id] ?? true}
          onOpenChange={(next) => setOpen((all) => ({ ...all, [notice.id]: next }))}
        >
          <AlertTitle>{notice.title}</AlertTitle>
          <AlertDescription>{notice.body}</AlertDescription>
        </Alert>
      ))}
      <Button variant="outline" size="sm" className="mt-2 self-start" onClick={() => setOpen({})}>
        Bring them back
      </Button>
    </div>
  )
}
```

A set of alerts you can dismiss, with a button that resets them.

`dismissible` adds a dismiss button in the corner. The alert collapses through [Collapse](https://www.youj.dev/docs/motion/collapse): its height eases to zero while the content fades out faster, so what follows glides up instead of jumping. If focus was inside the alert, it moves on to the next focusable element rather than dropping to the top of the page.

Passing `onOpenChange` also makes an alert dismissible. Control it with `open` to remember the choice or to bring the alert back.

```tsx
import { useState } from 'react'
import { Alert, AlertDescription } from '@youj/react'

export function MaintenanceAlert() {
  const [open, setOpen] = useState(true)
  return (
    <Alert variant="info" open={open} onOpenChange={setOpen}>
      <AlertDescription>Maintenance on October 3, from 02:00 to 02:20 UTC.</AlertDescription>
    </Alert>
  )
}
```

Give an alert its spacing as a margin on the alert itself, such as `className="mb-4"`, rather than as a gap on its parent. The margin collapses with the alert, so no empty gap is left behind.

### Icons

```tsx
'use client'

import { RocketIcon } from '@youj/icons'
import { Alert, AlertAction, AlertDescription, AlertTitle, Button } from '@youj/react'

export default function AlertIcons() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      {/* A custom icon plays on mount like the built-in ones, in the variant's color. */}
      <Alert variant="info" icon={<RocketIcon trigger="mount" />}>
        <AlertTitle>Preview comments are here</AlertTitle>
        <AlertDescription>Reviewers can pin feedback to any element of a preview deployment.</AlertDescription>
        <AlertAction>
          <Button size="sm" variant="outline">
            Try it on a preview
          </Button>
        </AlertAction>
      </Alert>
      <Alert variant="success" icon={false}>
        <AlertDescription>Build cache restored: 312 packages in 1.8 seconds.</AlertDescription>
      </Alert>
    </div>
  )
}
```

An alert with a custom icon that plays on mount, and one with the icon removed.

`icon` replaces the variant's icon with any node, and `icon={false}` removes it. A Youj icon with `trigger="mount"` plays as the alert appears, like the built-in ones. Any icon takes the variant's color.

### Insight

```tsx
'use client'

import { Alert, AlertDescription } from '@youj/react'
import { ArrowRightIcon, SparklesIcon } from '@youj/icons'

const INSIGHTS = [
  { text: 'Preview builds are up 18% this week.', quiet: false },
  { text: 'Cache hits fell to 71% after Tuesday’s lockfile change.', quiet: true },
]

export default function AlertInsight() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      {INSIGHTS.map(({ text, quiet }) => (
        <Alert
          key={text}
          icon={<SparklesIcon />}
          className={quiet ? 'items-center border-line-subtle bg-band [--alert-icon:var(--color-accent)]' : 'items-center'}
        >
          <AlertDescription className="flex flex-wrap items-center gap-x-3 gap-y-1">
            <span className="flex-1 text-fg">{text}</span>
            <a href="#insight" className="inline-flex items-center gap-1 font-medium no-underline! hover:underline!">
              See why
              <ArrowRightIcon className="size-3.5 rtl:-scale-x-100" />
            </a>
          </AlertDescription>
        </Alert>
      ))}
    </div>
  )
}
```

One-line insights under a figure, each with a link to the reasoning.

A sparkle in place of the severity icon and a link at the row's end make an alert an inline insight. Lay the text and the link out in the `AlertDescription`. The second row sits on the band (`bg-band`, with `--alert-icon` set to keep the sparkle in the accent), for a panel that already carries color.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add alert
```

It brings `button`, `collapse`, `icon-alert-triangle`, `icon-check-circle`, `icon-info`, `icon-octagon-alert`, `icon-x`, `youj-core`, `youj-labels-alert`, `youj-ui-core` with it.

The copy is 17 registry items, about 7,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `icon-alert-triangle`, `icon-check-circle`, `icon-engine`, `icon-info`, `icon-loader-ring`, `icon-octagon-alert`, `icon-x`, `spinner`.

Use Alert for a condition that stays on the page until resolved or dismissed, such as a usage limit or failed payment. Use [Toast](https://www.youj.dev/docs/components/toast) for brief feedback, or [Alert Dialog](https://www.youj.dev/docs/components/alert-dialog) for a decision that must be made before continuing.

```tsx
import { Alert, AlertAction, AlertDescription, AlertTitle, Button } from '@youj/react'

export function BandwidthAlert() {
  return (
    <Alert variant="warning" dismissible>
      <AlertTitle>You’ve used 82% of this month’s bandwidth</AlertTitle>
      <AlertDescription>Raise the limit or upgrade to avoid overage.</AlertDescription>
      <AlertAction>
        <Button size="sm">Upgrade</Button>
      </AlertAction>
    </Alert>
  )
}
```

The title is optional. A lone `AlertDescription` is enough for a one-line notice. `AlertAction` sets a button or two, or a link, under the message.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `AlertVariant \| null` | `'info'` | The severity: `info`, `success`, `warning` or `danger`, the name Button, Badge and the menus use. |
| `icon` | `ReactNode \| false` |  | Replace the variant's icon, or `false` for none. |
| `dismissible` | `boolean` |  | Show a dismiss button. Implied by `onOpenChange`. |
| `open` | `boolean` |  | Controlled visibility. |
| `defaultOpen` | `boolean` | `true` | Uncontrolled initial visibility. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with `false` when dismissed. |
| `dismissLabel` | `string` | `"Dismiss"` | Accessible name of the dismiss button. |

Also takes the props of `ComponentProps<'div'>`.

`AlertTitle`, `AlertDescription` and `AlertAction` take the props of a `div`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Icon |  | each icon’s own choreography | plays once as the alert mounts |
| Dismiss, height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | what follows glides up |
| Dismiss, content | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades out ahead of the height |
| Reopen | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height and content together |

**Reduced motion:** Icons appear at rest. A dismissed alert leaves at once, and a reopened one appears at once.

An alert that mounts appears in place without expanding. Only its icon plays. The collapse animates height on purpose, because the content below has to move with it.

#### Reduced motion

The icon appears in its resting pose. A dismissed alert leaves at once, and the content below moves up in the same frame. The severity, the tint and the message don't change.

### Accessibility

- Warning and danger alerts have `role="alert"`, so screen readers announce them at once, interrupting. Info and success alerts have `role="status"` and wait for a pause. Pass `role` to override, such as `role="status"` on a danger alert that isn't urgent.
- Screen readers announce an alert when it's added to the page. One that renders with the page is read in place, with the rest of the content.
- The dismiss button is named by `dismissLabel`, "Dismiss" by default. With several alerts on screen, name each one, like `dismissLabel="Dismiss payment alert"`.
- When a dismissed alert collapses, focus inside it moves to the next focusable element, or to the previous one at the end of the page. It never falls to the body.
- The icon is decorative. The title and description carry the message.

---

# Banner

> Show an announcement across the top of your app, with an action link and optional dismissal.

Source: https://www.youj.dev/docs/components/banner

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Badge, Banner, BannerAction, BannerTitle, Button } from '@youj/react'

export default function BannerDemo() {
  const [open, setOpen] = useState(true)

return (
    <div className="w-full overflow-hidden rounded-xl border border-line bg-canvas">
      <Banner variant="inverse" open={open} onOpenChange={setOpen}>
        <Badge variant="outline" className="hidden border-current/30 text-current sm:inline-flex">
          New
        </Badge>
        <BannerTitle>
          <strong>Deploy previews</strong> <span>now comment on every pull request.</span>
        </BannerTitle>
        <BannerAction href="#changelog">Read the changelog</BannerAction>
      </Banner>
      {/* The page under the banner glides up when it's dismissed. */}
      <div className="flex h-12 items-center justify-between border-b border-line px-4">
        <span className="text-ui font-semibold text-fg">Northwind</span>
        <Button size="sm">Sign in</Button>
      </div>
      <div className="p-4">
        <Button variant="outline" size="sm" disabled={open} onClick={() => setOpen(true)}>
          Show the banner again
        </Button>
      </div>
    </div>
  )
}
```

A dismissible inverse banner above a page; the page glides up when it's dismissed.

`dismissible` adds a dismiss button at the end, outside the flow, so the message stays centered on the page. The banner collapses through [Collapse](https://www.youj.dev/docs/motion/collapse): its height eases to zero while the content fades out faster, and the page below glides up. If focus was inside the banner, it moves on to the next focusable element.

Passing `onOpenChange` also makes a banner dismissible. Control it with `open` to remember the choice, for example in local storage, so a dismissed announcement stays dismissed. Starting closed and opening after mount keeps the server render and the first client render the same, and the banner expands into place:

```tsx
import { useEffect, useState } from 'react'
import { Banner, BannerTitle } from '@youj/react'

export function PreviewsBanner() {
  const [open, setOpen] = useState(false)
  useEffect(() => setOpen(localStorage.getItem('banner:previews') !== 'dismissed'), [])

return (
    <Banner
      open={open}
      onOpenChange={(next) => {
        setOpen(next)
        if (!next) localStorage.setItem('banner:previews', 'dismissed')
      }}
    >
      <BannerTitle>Deploy previews now comment on every pull request.</BannerTitle>
    </Banner>
  )
}
```

### Looks

```tsx
'use client'

import { AlertTriangleIcon, SparklesIcon } from '@youj/icons'
import { Banner, BannerAction, BannerTitle } from '@youj/react'

export default function BannerVariants() {
  return (
    <div className="flex w-full flex-col gap-3">
      <Banner aria-label="Release" dismissible>
        <BannerTitle>
          <strong>Youj 1.0</strong> <span>is here.</span>
        </BannerTitle>
        <BannerAction href="#notes">See what’s new</BannerAction>
      </Banner>
      <Banner aria-label="Event" variant="inverse" dismissible>
        <BannerTitle>Join us for Ship Week, October 6–10.</BannerTitle>
        <BannerAction href="#register">Register</BannerAction>
      </Banner>
      <Banner aria-label="Trial" variant="accent" icon={<SparklesIcon trigger="mount" />} dismissible>
        <BannerTitle>
          <strong>Pro trial:</strong> <span>12 days left.</span>
        </BannerTitle>
        <BannerAction href="#upgrade">Upgrade</BannerAction>
      </Banner>
      <Banner aria-label="Maintenance" variant="warning" icon={<AlertTriangleIcon trigger="mount" className="text-warning-text" />}>
        <BannerTitle>
          <strong>Scheduled maintenance</strong> <span>Sunday 02:00–02:30 UTC. Deploys will queue.</span>
        </BannerTitle>
      </Banner>
    </div>
  )
}
```

Banners in several looks, one with an icon.

`variant` is `default`, a recessed strip with a hairline; `inverse`, the foreground ink; `accent`, the theme's accent; or `warning`, an amber tint for maintenance and incidents. `icon` puts an icon before the message: a Youj icon with `trigger="mount"` plays once as the banner appears.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add banner
```

It brings `button`, `collapse`, `icon-arrow-right`, `icon-x`, `youj-core`, `youj-labels-banner`, `youj-presets`, `youj-ui-core` with it.

Use a banner for news that concerns the whole product rather than one part of the page: a launch, an event, a trial running out, a maintenance window. It sits above everything, full bleed, and says one thing. For something that belongs to a section of the page, use an [Alert](https://www.youj.dev/docs/components/alert). For feedback on something the user just did, use a [Toast](https://www.youj.dev/docs/components/toast).

```tsx
import { Banner, BannerAction, BannerTitle } from '@youj/react'

export function LaunchBanner() {
  return (
    <Banner variant="inverse" dismissible>
      <BannerTitle>
        <strong>Deploy previews</strong> <span>now comment on every pull request.</span>
      </BannerTitle>
      <BannerAction href="/changelog">Read the changelog</BannerAction>
    </Banner>
  )
}
```

`BannerTitle` holds the message. A `<strong>` inside it leads in, and a `<span>` after it is set a step quieter. `BannerAction` is a link whose arrow nudges out and back on hover or focus. Anything else you put in the banner, like a badge, sits in the same centered row.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | A leading icon or badge, before the message. |
| `dismissible` | `boolean` |  | Show a dismiss button. Implied by `onOpenChange`. |
| `open` | `boolean` |  | Controlled visibility. |
| `defaultOpen` | `boolean` | `true` | Uncontrolled initial visibility. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with `false` when dismissed. |
| `dismissLabel` | `string` | `"Dismiss announcement"` | Accessible name of the dismiss button. |
| `variant` | `'default' \| 'accent' \| 'warning' \| 'inverse'` | `'default'` |  |

Also takes the props of `ComponentProps<'div'>`, `VariantProps<typeof bannerVariants>`.

`BannerTitle` takes the props of a `p`, and `BannerAction` those of an `a`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Action arrow |  | the arrow icon’s own nudge | on hover or focus of the link |
| Dismiss, height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the page below glides up |
| Dismiss, content | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades out ahead of the height |
| Reopen | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height and content together |
| Link underline | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) |  |

**Reduced motion:** A dismissed banner leaves at once and a reopened one appears at once. The arrow and any mount icon hold still.

A banner that renders with the page appears in place, without expanding. Reversing mid-collapse (setting `open` back to `true`) opens from the current height.

#### Reduced motion

A dismissed banner leaves at once and the page below moves up in the same frame. The action's arrow and any mount icon stay at rest. The look and the message don't change.

### Accessibility

- The banner is a `region` landmark named "Announcement", so screen-reader users can find it or skip it. Pass `aria-label` to name it better, like "Maintenance".
- It isn't a live region: a banner that renders with the page is read in place. If one appears later and has to be heard, announce it yourself.
- The dismiss button is named by `dismissLabel`, "Dismiss announcement" by default.
- When a dismissed banner collapses, focus inside it moves to the next focusable element, never to the body.
- The icon is decorative. The message carries the meaning.

---

# Session Timeout

> Warn people before an inactive session signs out: a live countdown, Stay signed in, and a signed-out page when time runs out.

Source: https://www.youj.dev/docs/components/session-timeout

## Examples

### Bank account

```tsx
'use client'

import { useState } from 'react'
import { Button, SessionSignedOut, SessionTimeout } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

function Account({ onSimulate }: { onSimulate: () => void }) {
  return (
    <div className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <p className="text-ui-sm text-fg-muted">Current account</p>
      <p className="mt-1 text-2xl font-semibold tracking-tight text-fg tabular-nums">£4,218.60</p>
      <p className="mt-3 text-ui-sm text-fg-muted">The timers here are shortened: 20 seconds idle, warned 10 seconds before. Real sessions use minutes.</p>
      <Button variant="outline" size="sm" className="mt-4" onClick={onSimulate}>
        Simulate idle
      </Button>
    </div>
  )
}

export default function SessionTimeoutDemo() {
  // Signing in again starts a new session: here, by remounting.
  const [session, setSession] = useState(0)
  return (
    <SessionTimeout
      key={session}
      timeout={20_000}
      warnBefore={10_000}
      channel="docs-session-timeout-demo"
      onExtend={() => wait(800)}
      signedOut={<SessionSignedOut className="min-h-[340px] w-full" onSignIn={() => setSession((n) => n + 1)} />}
    >
      {({ simulateIdle }) => <Account onSimulate={simulateIdle} />}
    </SessionTimeout>
  )
}
```

A banking session with shortened timers. Press Simulate idle, or leave the page alone for 10 seconds.

After `timeout` without activity the warning opens `warnBefore` early with a live countdown ("You'll be signed out in 0:09"), **Stay signed in** and **Sign out now**. Stay signed in awaits `onExtend`, so a failed renewal keeps the warning up. If nobody answers, `onTimeout` fires and the app is replaced by the signed-out page: nothing from the session stays on screen.

### Hook only

```tsx
'use client'

import { Banner, BannerTitle, Button, useSessionTimeout } from '@youj/react'

const clock = (seconds: number) => `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`

export default function SessionTimeoutHook() {
  // The clock without the dialog: draw the warning yourself, here as a banner over the page.
  const session = useSessionTimeout({ timeout: 20_000, warnBefore: 10_000, channel: false })
  return (
    <div className="w-full max-w-lg overflow-hidden rounded-xl border border-line bg-surface">
      {session.status === 'warning' && (
        <Banner variant="warning">
          <BannerTitle>
            <strong>Signing out in {clock(session.secondsLeft)}.</strong>
          </BannerTitle>
          <Button size="sm" onClick={() => void session.extend()}>
            Stay signed in
          </Button>
        </Banner>
      )}
      {session.status === 'signedOut' && (
        <Banner variant="inverse">
          <BannerTitle>You've been signed out.</BannerTitle>
          <Button size="sm" variant="outline" onClick={session.reset}>
            Sign in again
          </Button>
        </Banner>
      )}
      <div className="flex items-center justify-between gap-3 p-5">
        <p className="text-ui text-fg">
          Status: <span className="font-medium">{session.status}</span>
        </p>
        <Button variant="outline" size="sm" onClick={session.simulateIdle}>
          Simulate idle
        </Button>
      </div>
    </div>
  )
}
```

`useSessionTimeout` is the clock without the dialog, drawing the warning as a banner.

It returns `status` (`active`, `warning` or `signedOut`), `secondsLeft`, `extend`, `signOut`, `reset` and `simulateIdle`, for an app that wants its own warning.

### Signed out

```tsx
'use client'

import { SessionSignedOut } from '@youj/react'

export default function SessionTimeoutSignedOut() {
  return (
    <SessionSignedOut
      className="min-h-[340px] w-full"
      title="Your session has ended"
      description="For your safety we close your NHS account after 15 minutes of inactivity. Nothing you entered was saved."
      signInLabel="Sign in to your account"
      onSignIn={() => {}}
    />
  )
}
```

The page a session ends on, with its own copy.

`SessionSignedOut` stands alone too: a warning band, the reason and a Sign in again button. Focus lands on its heading, since the dialog the person was in has just gone.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add session-timeout
```

It brings `alert-dialog`, `async-button`, `banner`, `button`, `use-announcer`, `youj-core`, `youj-labels-session-timeout`, `youj-ui-core` with it.

The copy is 36 registry items, about 10,800 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `alert-dialog`, `async-button`, `async-feedback`, `banner`, `button`, `collapse`, `dialog`, `field`, `icon-arrow-right`, `icon-check` and 13 more.

Use a Session Timeout where a session is sensitive enough to end by itself (banking, admin consoles, health records) and the person must be told before it does. Wrap the app: the signed-out page replaces it once the session ends.

```tsx
'use client'

import { SessionTimeout } from '@youj/react'

export function Shell({ children }: { children: React.ReactNode }) {
  return (
    <SessionTimeout
      timeout={15 * 60_000}
      warnBefore={2 * 60_000}
      onExtend={() => fetch('/api/session/extend', { method: 'POST' })}
      onTimeout={() => fetch('/api/session/end', { method: 'POST' })}
      onSignOut={() => fetch('/api/session/end', { method: 'POST' })}
      onSignIn={() => location.assign('/sign-in')}
    >
      {children}
    </SessionTimeout>
  )
}
```

`warnBefore` defaults to 2 minutes, as the UK government's session-timeout pattern recommends. `onTimeout` fires when inactivity ends the session and `onSignOut` when the person chooses **Sign out now**; both usually end the session on the server. The clock only knows about the page: renewing the session server-side stays in `onExtend`.

**What counts as activity.** Pointer, key, scroll and a tab being shown again, throttled to once a `throttle` (1 second). Narrow it with `events`. Once the warning is up activity is ignored: only Stay signed in extends, so a stray mouse move can't hide a sign-out the person hasn't read.

**Hidden tabs.** The clock stores the time of the last activity and works out what is left from `Date.now()`, never by counting ticks. A tab that was asleep past the deadline signs out the moment it wakes.

**Several tabs.** Tabs on the same `channel` share one clock over a BroadcastChannel: activity or Stay signed in in any tab resets all of them, and a sign-out in one signs out the rest (without calling `onTimeout` again; the tab that ended it did). Give each app its own `channel`, or pass `false` to keep tabs apart. Where BroadcastChannel isn't available each tab times out on its own.

**The page as a function.** `children` may be a function of the session (`status`, `secondsLeft`, `extend`, `simulateIdle`…), for a header that shows the time left or a button that simulates idling in a demo.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((session: SessionTimeoutState) => ReactNode)` |  | The app, or a function of the session (`status`, `secondsLeft`, `extend`, `simulateIdle`…). Replaced by the signed-out page once the session ends, so nothing stays on screen. |
| `onSignIn` | `() => unknown` |  | Called by the signed-out page's Sign in again button: go to your sign-in. |
| `signedOut` | `ReactNode \| false` |  | Replaces the signed-out page. `false` shows none. |
| `timeout` (required) | `number` |  | How long a session may sit without activity before it ends, in ms. |
| `warnBefore` | `number` |  | How long before the end the warning starts, in ms. Default 120000 (2 minutes). |
| `events` | `SessionActivityEvent[]` |  | What counts as activity. Default all four; `visibility` counts the tab being shown again. |
| `throttle` | `number` | `1000` | Activity is noted at most this often, in ms. |
| `enabled` | `boolean` | `true` | Turn the clock off, say while the person is signed out. |
| `channel` | `string \| false` | ``youj-session-timeout`` | The BroadcastChannel name that ties tabs together. Give each app its own. `false` keeps tabs apart. |
| `onWarn` | `() => void` |  | Fires once when the warning starts. |
| `onExtend` | `() => unknown` |  | "Stay signed in": renew the session on the server. Awaited; if it rejects the warning stays up. |
| `onTimeout` | `() => void` |  | Fires once when the session ends because of inactivity: sign out here. |
| `onSignOut` | `() => unknown` |  | Fires when the person chooses "Sign out now". Awaited. |

#### Signed out

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSignIn` | `() => unknown` |  | Called by the Sign in again button. |
| `title` | `ReactNode` | `"You've been signed out"` | Heading. |
| `description` | `ReactNode` |  | Explanation under the heading. |
| `signInLabel` | `string` | `"Sign in again"` | The button's label. |

Also takes the props of `ComponentProps<'section'>`.

#### Data attributes

The warning dialog is an Alert Dialog; its content carries `data-slot="session-timeout-dialog"`, with `session-timeout-countdown` (the visible line), `session-timeout-sign-out` and `session-timeout-stay` on its parts. The hidden live region is `session-timeout-announcer`. The signed-out page is `session-signed-out`, its button `session-sign-in`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Warning opens and closes | `duration.normal`, `ease.enter` | undefinedms; cubic-bezier(0.16, 1, 0.3, 1) | the Alert Dialog’s own pop over a fading scrim |
| Countdown |  |  | the digits change once a second, with no animation of their own |
| Stay signed in |  |  | an Async Button: spinner, then a check, while `onExtend` runs |

**Reduced motion:** The dialog appears at once, and the visible line is a static phrase (“2 minutes”) that changes only when it is spoken, instead of a ticking clock.

#### Reduced motion

The visible countdown is static: it shows the same phrase screen readers hear, updated at the start, each minute and at 30 and 15 seconds.

### Accessibility

Follows the GOV.UK and DWP session-timeout guidance.

- The warning is an `alertdialog` named by its title. Focus moves into it, onto **Stay signed in**, and returns to where it was once the person stays.
- **Escape means stay signed in**, not dismiss into nowhere. The dialog doesn't close on a press outside.
- The ticking line is hidden from screen readers. The dialog's description says the time as it opens ("2 minutes"), and a polite live region speaks it again each minute and at 30 and 15 seconds, never every second.
- Times are spoken as words in the person's language ("1 minute, 42 seconds") and shown as a clock ("1:42").
- When the session ends, focus moves to the signed-out page's heading, and **Sign in again** is a button.
- The words (title, warning, reason, both buttons, the signed-out page) are Youj labels in every built-in locale; pass `labels` to the provider to change them.

---

# Toast

> Show brief notifications with swipe dismissal, triggered from anywhere in your app.

Source: https://www.youj.dev/docs/components/toast

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import {
  Button,
  Field,
  FieldLabel,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  toast,
  Toaster,
  type ToasterPosition,
} from '@youj/react'
import { ArchiveIcon, LinkIcon, RocketIcon } from '@youj/icons'
import { IllustrationDeploy, IllustrationLightning } from '@youj/illustrations'
import { LoaderBuild } from '@youj/loaders/build'

const POSITIONS: Record<ToasterPosition, string> = {
  'top-start': 'Top start',
  'top-center': 'Top center',
  'top-end': 'Top end',
  'bottom-start': 'Bottom start',
  'bottom-center': 'Bottom center',
  'bottom-end': 'Bottom end',
}

// Stands in for a deployment.
const build = () => new Promise<{ url: string; seconds: number }>((resolve) => setTimeout(() => resolve({ url: 'orion.acme.dev', seconds: 41 }), 1800))

function deploy() {
  toast
    .promise(build(), {
      // Each step brings its own media: a loader while it builds, then the scene once it's live.
      loading: { title: 'Deploying orion…', description: 'Building main at 4f2a91c', media: <LoaderBuild label={null} /> },
      success: (result) => ({
        title: 'Deployed to production',
        description: `${result.url} is live, built in ${result.seconds}s`,
        media: <IllustrationDeploy />,
        action: { label: 'Visit', onClick: () => {} },
      }),
      error: { title: 'Deployment failed', media: <IllustrationLightning /> },
    })
    .catch(() => {})
}

function archive() {
  toast('Archived 3 issues', {
    description: 'ORI-812, ORI-815 and ORI-821 moved to the archive.',
    action: { label: 'Undo', onClick: () => toast.success('Restored 3 issues') },
  })
}

export default function ToastDemo() {
  const [position, setPosition] = useState<ToasterPosition>('bottom-end')
  // The queue behind toast() is app-wide. This demo's Toaster leaves with the page, so its toasts do too.
  useEffect(() => () => toast.dismiss(), [])

return (
    <div className="flex w-full max-w-md flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-xs">
      <div className="flex flex-col gap-1">
        <span className="text-ui-lg font-semibold text-fg">orion</span>
        <span className="text-ui-sm text-fg-muted">Toasts appear in the corner of the window.</span>
      </div>
      <div className="flex flex-wrap gap-2">
        <Button onClick={deploy}>
          <RocketIcon />
          Deploy
        </Button>
        <Button variant="outline" onClick={archive}>
          <ArchiveIcon />
          Archive 3 issues
        </Button>
        <Button
          variant="outline"
          onClick={() =>
            toast.success('Invite link copied', {
              description: 'Anyone at Acme with the link can join orion.',
              media: <LinkIcon trigger="mount" />,
            })
          }
        >
          <LinkIcon />
          Copy invite link
        </Button>
      </div>
      <Field orientation="horizontal" className="justify-between border-t border-line pt-4">
        <FieldLabel>Position</FieldLabel>
        <Select items={POSITIONS} value={position} onValueChange={(value) => value && setPosition(value)}>
          <SelectTrigger size="sm" className="w-40">
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            {Object.entries(POSITIONS).map(([value, label]) => (
              <SelectItem key={value} value={value}>
                {label}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      </Field>
      {/* One Toaster renders every toast() in the app, so it belongs in your root layout. */}
      <Toaster position={position} />
    </div>
  )
}
```

Mount one `Toaster` in your root layout, inside `YoujProvider`. Then import `toast` from `@youj/react` and call it from any client component:

```tsx title="app/layout.tsx"
import { Toaster } from '@youj/react'

// inside <YoujProvider>, after {children}
<Toaster />
```

```tsx title="app/save-button.tsx"
'use client'
import { Button, toast } from '@youj/react'

export function SaveButton() {
  return <Button onClick={() => toast.success('Saved')}>Save</Button>
}
```

A project panel whose Deploy and Archive buttons raise toasts. Deploy shows a loader while it builds and the deploy scene once it's live.

A toast can carry one `action`, such as Undo or Retry. Pressing it runs `onClick` and dismisses that toast only. When an action can be reversed, do it straight away and offer Undo, instead of asking first. "Archive 3 issues" in the demo works this way.

```tsx
toast('Archived 3 issues', {
  description: 'ORI-812, ORI-815 and ORI-821 moved to the archive.',
  action: { label: 'Undo', onClick: () => restore(issues) },
})
```

`position` sets the corner or edge the stack grows from: `top-start`, `top-center`, `top-end`, `bottom-start`, `bottom-center` or `bottom-end`, the default. `start` and `end` follow the writing direction. Top positions stack down from the top edge and swipe up. Try each one with the Position menu in the demo.

**Beside a floating bar.** The bars that float over a page's foot sit at the bottom center: a data table's selection bar does, and so does an [Action island](https://www.youj.dev/docs/components/action-island) placed there. Keep toasts in a corner (`bottom-end`, the default, or `top-end`): an "Archived 3 issues" toast then lands beside the bar that raised it instead of over it. Avoid `bottom-center` on those pages. On a phone the stack is nearly the screen's width, so lift it clear of the bar there with a class; `className` reaches the stack's fixed frame:

```tsx
<Toaster position="bottom-end" className="max-sm:bottom-20" />
```

### Media

```tsx
'use client'

import { Button, toast } from '@youj/react'
import { BellIcon } from '@youj/icons'
import { IllustrationBackups, IllustrationSearch } from '@youj/illustrations'
import { LoaderWinnow } from '@youj/loaders/winnow'

// An index that builds for a while: a loader while it runs, then a scene once it's ready.
function reindex() {
  const id = toast('Indexing orion…', { description: '1,204 issues, 38 projects', media: <LoaderWinnow label={null} />, timeout: 0 })
  setTimeout(() => toast.success('Search index ready', { id, description: 'Search now covers every issue in orion.', media: <IllustrationSearch />, timeout: 5000 }), 2600)
}

// No Toaster here: the app's one Toaster renders these. On this page, that's the one in the first preview.
export default function ToastMedia() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button
        variant="outline"
        onClick={() => toast('Backup complete', { description: '12.4 GB of orion saved to eu-west.', media: <IllustrationBackups /> })}
      >
        Illustration
      </Button>
      <Button variant="outline" onClick={reindex}>
        Loader
      </Button>
      <Button
        variant="outline"
        onClick={() => toast('Reminder set', { description: 'We’ll nudge you about ORI-830 at 9:00 tomorrow.', media: <BellIcon trigger="mount" /> })}
      >
        Animated icon
      </Button>
    </div>
  )
}
```

Three buttons: a toast with an illustration, one with a loader that becomes an illustration, and one with an animated icon.

`media` puts a visual at the toast's start, in place of the status icon. Import it from the package that owns it and pass the element: an illustration from `@youj/illustrations`, a loader from `@youj/loaders/<id>` or an animated icon from `@youj/icons`.

```tsx
import { IllustrationBackups } from '@youj/illustrations'
import { LoaderWinnow } from '@youj/loaders/winnow'
import { BellIcon } from '@youj/icons'

toast('Backup complete', { media: <IllustrationBackups /> })
toast('Indexing orion…', { media: <LoaderWinnow label={null} />, timeout: 0 })
toast('Reminder set', { media: <BellIcon trigger="mount" /> })
```

The media sits on a small recessed stage that fits each kind without a size from you: a scene fills it, a loader keeps its proportions inside it, and an icon sits at half its size. The stage lands just after the toast, and when the media changes, by `toast.update` or a call with the same `id`, the new media crossfades in over the old. A typed toast with media, such as `toast.success`, shows its status as a small badge on the stage's corner.

The stage is decorative and hidden from assistive technology, so the title still has to say what happened. Pass loaders `label={null}`: the toast already announces the wait.

### Types

```tsx
'use client'

import { Button, toast } from '@youj/react'

// No Toaster here: the app's one Toaster renders these. On this page, that's the one in the first preview.
export default function ToastTypes() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button variant="outline" onClick={() => toast('Grace commented on ORI-812', { description: '“Ship it once the flag is on.”' })}>
        Default
      </Button>
      <Button variant="outline" onClick={() => toast.success('orion deployed', { description: 'orion.acme.dev, built in 38s' })}>
        Success
      </Button>
      <Button variant="outline" onClick={() => toast.info('Maintenance tonight', { description: 'From 02:00 to 02:30 UTC, deploys wait in a queue.' })}>
        Info
      </Button>
      <Button variant="outline" onClick={() => toast.warning('Build minutes at 90%', { description: 'Upgrade to keep deploying this month.' })}>
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.error('Couldn’t reach the build server', {
            description: 'We’ll retry in 30 seconds.',
            action: { label: 'Retry now', onClick: () => toast.success('Build server reached') },
          })
        }
      >
        Error
      </Button>
    </div>
  )
}
```

Buttons for the default, success, info, warning and error toasts.

`toast()` shows a plain toast. `toast.success`, `toast.info`, `toast.warning` and `toast.error` add a status icon, which plays once as the toast lands.

### Promise toasts

```tsx
'use client'

import { Button, toast } from '@youj/react'
import { RocketIcon } from '@youj/icons'
import { IllustrationDeploy, IllustrationLightning } from '@youj/illustrations'
import { LoaderBuild } from '@youj/loaders/build'

// Stands in for a deployment, which fails when the build has type errors.
const build = (fail: boolean) =>
  new Promise<{ url: string }>((resolve, reject) =>
    setTimeout(() => (fail ? reject(new Error('2 type errors in app/search/page.tsx')) : resolve({ url: 'orion.acme.dev' })), 1800),
  )

function deploy(fail: boolean) {
  toast
    .promise(build(fail), {
      // Each step can bring its own media; the toast crossfades from one to the next.
      loading: { title: 'Deploying orion…', description: 'Building main at 4f2a91c', media: <LoaderBuild label={null} /> },
      success: (result) => ({ title: 'Deployed to production', description: `${result.url} is live`, media: <IllustrationDeploy /> }),
      error: (error) => ({
        title: 'Deployment failed',
        media: <IllustrationLightning />,
        description: error instanceof Error ? error.message : 'Something went wrong.',
        action: { label: 'View logs', onClick: () => {} },
      }),
    })
    // toast.promise passes the work's outcome through, so a rejection still needs a catch.
    .catch(() => {})
}

// No Toaster here: the app's one Toaster renders these. On this page, that's the one in the first preview.
export default function ToastPromise() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button onClick={() => deploy(false)}>
        <RocketIcon />
        Deploy
      </Button>
      <Button variant="outline" onClick={() => deploy(true)}>
        Deploy a failing build
      </Button>
    </div>
  )
}
```

A Deploy button and a failing Deploy button, each following a promise in one toast.

`toast.promise(work, { loading, success, error })` follows a promise in one toast. It stays up while the work runs, then its first line morphs: the spinner becomes a drawn check, or a cross that shakes. `success` and `error` can be functions of the result or the error, and every step can carry its own description and action.

Each step can carry its own `media`, so a loader can run while the work does and an illustration land when it's done. The stage crossfades from one to the next, and a step without `media` shows none.

```tsx
toast.promise(deploy(), {
  loading: { title: 'Deploying orion…', media: <LoaderBuild label={null} /> },
  success: { title: 'Deployed to production', media: <IllustrationDeploy /> },
  error: { title: 'Deployment failed', media: <IllustrationLightning /> },
})
```

`toast.promise` returns a promise that settles the way the work does, so handle its rejection.

### Updating a toast

```tsx
'use client'

import { Button, toast } from '@youj/react'
import { UploadIcon } from '@youj/icons'

const FILES = ['launch-video.mp4', 'poster.png', 'captions.vtt']

// Stands in for an upload that reports progress file by file.
function upload() {
  // timeout: 0 keeps the toast up while the work runs.
  const id = toast(`Uploading ${FILES.length} files`, { description: `0 of ${FILES.length}: ${FILES[0]}`, timeout: 0 })
  FILES.forEach((_, i) => {
    setTimeout(() => {
      const done = i + 1
      if (done < FILES.length) {
        // update() changes the toast in place.
        toast.update(id, { description: `${done} of ${FILES.length}: ${FILES[done]}` })
      } else {
        // The same id upserts: the toast becomes a success and its timer starts again.
        toast.success(`Uploaded ${FILES.length} files`, { id, description: 'Attached to the v4.14 release notes.', timeout: 5000 })
      }
    }, (i + 1) * 900)
  })
}

// No Toaster here: the app's one Toaster renders these. On this page, that's the one in the first preview.
export default function ToastUpdate() {
  return (
    <Button variant="outline" onClick={upload}>
      <UploadIcon />
      Upload 3 files
    </Button>
  )
}
```

An upload button whose toast updates in place as the files finish.

`toast.update(id, { title, description, … })` changes a toast in place. Calling a toast function again with an existing `id` updates it the same way, can change its type, and restarts its timer. Use `timeout: 0` to keep a toast up while the work runs.

### Stacking

```tsx
'use client'

import { Button, toast } from '@youj/react'
import { BellIcon } from '@youj/icons'

const BURST = [
  () => toast.success('orion deployed', { description: 'orion.acme.dev, built in 38s' }),
  () => toast('Grace commented on ORI-812', { description: '“Ship it once the flag is on.”' }),
  () => toast.warning('Build minutes at 90%'),
  () => toast('Ana assigned you ORI-830', { description: 'Stream search results from the edge' }),
  () => toast.info('New region: Tokyo (hnd1)'),
]

// Five in quick succession, as a busy morning would send them.
function sendBurst() {
  BURST.forEach((send, i) => setTimeout(send, i * 180))
}

// No Toaster here: the app's one Toaster renders these. On this page, that's the one in the first preview.
export default function ToastStack() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      <Button onClick={sendBurst}>
        <BellIcon />
        Send 5 notifications
      </Button>
      <Button variant="outline" onClick={() => toast.dismiss()}>
        Dismiss all
      </Button>
    </div>
  )
}
```

A button that sends five notifications, and one that dismisses them all.

New toasts come in at the front of the stack. Each toast behind the front one peeks out by 12px, 5% smaller than the one before, with its text hidden. Hover or focus the stack to spread it out with gaps between, which also pauses every timer. `limit` (default 3) sets how many show at once, and older toasts wait, hidden, for room.

Swipe a toast toward the edge it sits on to dismiss it. In a corner, a swipe sideways toward the nearer side works too. The toast leaves from where the finger let go, and the toasts behind step up.

## Installation & usage

```bash
pnpm add @youj/react
```

```tsx
import { PromiseOptions, Toaster, ToastOptions } from '@youj/react'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add toast
```

It brings `async-feedback`, `button`, `icon-alert-triangle`, `icon-check-circle`, `icon-circle-x`, `icon-info`, `icon-x`, `spinner`, `youj-core`, `youj-labels-toast`, `youj-presets`, `youj-ui-core` with it.

The copy is 19 registry items, about 8,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `button`, `icon-alert-triangle`, `icon-check-circle`, `icon-circle-x`, `icon-engine`, `icon-info`, `icon-loader-ring`, `icon-x`, `morph-label` and 1 more.

Use Toast to confirm an action or report a background task’s result, such as a copied link or completed deploy. Toasts dismiss automatically. Put essential information in an [Alert](https://www.youj.dev/docs/components/alert), or use an [Alert Dialog](https://www.youj.dev/docs/components/alert-dialog) when you need a response. Avoid repeating feedback already visible on the page.

In the Next.js App Router, render this from a Client Component, a file that starts with `'use client'`: a toast's `action.onClick` is a function, and `toast()` runs from event handlers, which a Server Component can't have. [Server rendering](https://www.youj.dev/docs/guides/ssr) has the rest.

Render one `Toaster` near the root of the app, inside `YoujProvider` so toasts follow its Speed and reduced-motion settings. Then call `toast()` from anywhere: event handlers, data hooks, code outside React.

```tsx title="app/layout.tsx"
import { basalt, YoujProvider, themeProps } from '@youj/core'
import { ThemeScript, Toaster } from '@youj/react'
import './globals.css'

// The layout from Installation, with a Toaster added: keep its font lines and the className on <html>.
export default function RootLayout({ children }: LayoutProps<'/'>) {
  return (
    <html lang="en" suppressHydrationWarning {...themeProps(basalt)}>
      <head>
        <ThemeScript />
      </head>
      <body>
        <YoujProvider theme={basalt}>
          {children}
          <Toaster />
        </YoujProvider>
      </body>
    </html>
  )
}
```

```tsx
import { toast } from '@youj/react'

toast.success('Invite link copied', { description: 'Anyone at Acme with the link can join orion.' })
```

`toast()` and its typed helpers return the toast's id. Only one `Toaster` renders at a time. If a second one mounts, for example in a layout and again in a page, it shows nothing until the first unmounts, so each toast appears and is announced once. On this page, the Toaster in the demo renders the toasts from every preview, so its Speed and Reduced motion controls apply to all of them.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Toaster

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `'top-start' \| 'top-center' \| 'top-end' \| 'bottom-start' \| 'bottom-center' \| 'bottom-end'` | `'bottom-end'` | The corner or edge the stack grows from; start and end follow the writing direction. |
| `limit` | `number` | `3` | How many toasts show at once; older ones wait, hidden. |
| `timeout` | `number` | `5000` | Default 5000. |
| `className` | `string` |  |  |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), toasts sound as they arrive. `false` keeps them silent. |

`timeout` is the default time on screen, in milliseconds, for every toast. `0` keeps toasts until they're dismissed.

#### toast()

| Call | Returns | Does |
| --- | --- | --- |
| `toast(title, options?)` | the id | Shows a plain toast. |
| `toast.success(title, options?)` | the id | Adds a success icon. `toast.info`, `toast.warning` and `toast.error` work the same way. |
| `toast.promise(work, steps)` | a promise | Shows `steps.loading` until `work` settles, then `steps.success` or `steps.error`. |
| `toast.update(id, changes)` | nothing | Changes the title or any option of a toast in place. |
| `toast.dismiss(id?)` | nothing | Closes one toast, or every toast when called without an id. |

#### Options

Every toast call takes these, and so does each step of `toast.promise`. A step can also be a plain string, which becomes its title.

| Option | Type | Default | Does |
| --- | --- | --- | --- |
| `id` | `string` | generated | Names the toast. A call with an existing id updates that toast in place and restarts its timer. |
| `description` | `ReactNode` |  | The second line. |
| `timeout` | `number` | the Toaster's | Time on screen in milliseconds. `0` keeps it until it's dismissed. |
| `priority` | `'low'` or `'high'` | `'low'` | `'high'` interrupts: the toast is announced assertively, through an alert. |
| `action` | `{ label, onClick }` |  | A button in the toast. Pressing it runs `onClick` and dismisses the toast. |
| `media` | `ReactNode` |  | A visual at the toast's start in place of the status icon: an illustration, a loader or an animated icon. Decorative, so the title still carries the message. |
| `onClose` | `() => void` |  | Called when the toast starts to close. |
| `onRemove` | `() => void` |  | Called once it has left and is removed. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | rises in from beyond the edge (`yj-toast`) |
| Stack and spread | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the toasts behind step back, or spread out on hover |
| Height | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the stack fits the front toast |
| Text behind | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | fades out behind the front toast (`yj-toast-content`) |
| Exit | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | back past the edge as it fades, or on in the swipe direction |
| Promise headline | `spring.snappy` | 0.2s, bounce 0 | spinner to check or cross, with the width |
| Media lands | `spring.settle` | 0.45s, bounce 0.3 | the stage grows in just after the toast |
| Media changes | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the new media fades and grows in over the old |
| Error shake | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | 4, 3 and 2px, then home |

**Reduced motion:** Toasts appear and leave in place, and the stack changes shape at once. A swipe still tracks the finger. Status icons appear already drawn, a pending promise toast shows its title without a spinner, and media appears and changes in place. A loader in the media shows its still frame.

#### Reduced motion

Toasts appear and leave in place, with no rise, slide or fade, and the stack collapses and spreads without moving. A swipe still moves the toast under the finger, because that motion is the person's own. Status icons hold their drawn pose, and a promise toast swaps its line without a morph or a shake.

### Accessibility

- The Toaster is a polite live region named "Notifications". New toasts, and the steps of a promise toast, are announced without moving focus.
- `priority: 'high'` makes a toast interrupt. Base UI speaks it through an assertive alert and hides the toast itself from assistive technology until it's focused. Keep it for the rare toast that can't wait.
- F6 moves focus to the notifications and pauses their timers, and Shift+Tab from there goes back to where you were. Each toast is a tab stop, its buttons follow it, and Escape dismisses the focused toast.
- Timers pause while the stack is hovered or focused, and while the window is in the background, so a toast doesn't disappear while someone reads it.
- `media` is hidden from assistive technology, along with its status badge. The title and description carry the message, and a toast's type is announced the same way with or without media.
- The × button, named "Dismiss", shows once the stack is spread, like the rest of the stack's controls. Toasts past the `limit` are hidden and inert until there's room.

---

# Progress

> Show how far a task has progressed, or that work is still running.

Source: https://www.youj.dev/docs/components/progress

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { FileTextIcon, FilmIcon, ImageIcon } from '@youj/icons'
import { Button, Progress, ProgressLabel, ProgressValue } from '@youj/react'

// Uneven chunks, like a real network. The spring turns each step into a glide.
const FILES = [
  { name: 'brand-guidelines.pdf', Icon: FileTextIcon, chunks: [9, 4, 12, 7, 3, 10] },
  { name: 'hero@2x.png', Icon: ImageIcon, chunks: [14, 18, 6, 21, 11] },
  { name: 'launch-film.mp4', Icon: FilmIcon, chunks: [3, 1, 4, 2, 5, 2] },
]

const uploaded = (chunks: number[], tick: number) =>
  Math.min(100, Array.from({ length: tick }, (_, i) => chunks[i % chunks.length]!).reduce((sum, n) => sum + n, 0))

export default function ProgressDemo() {
  const [tick, setTick] = useState(0)
  const values = FILES.map((file) => uploaded(file.chunks, tick))
  const done = values.every((v) => v === 100)

useEffect(() => {
    if (done) return
    const id = setInterval(() => setTick((t) => t + 1), 420)
    return () => clearInterval(id)
  }, [done])

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-2">
      {FILES.map(({ name, Icon }, i) => (
        <div key={name} className="flex items-center gap-3 rounded-lg px-3 py-2.5">
          <span className="grid size-8 shrink-0 place-items-center rounded-md bg-band text-fg-muted">
            <Icon size={16} />
          </span>
          <Progress value={values[i]!} className="gap-y-1.5">
            <ProgressLabel className="min-w-0 truncate">{name}</ProgressLabel>
            <ProgressValue />
          </Progress>
        </div>
      ))}
      <div className="flex items-center justify-between border-t border-line px-3 pt-2.5 pb-1">
        <p role="status" className="text-ui-sm text-fg-muted">
          {done ? 'All files uploaded.' : ''}
        </p>
        <Button size="sm" variant="ghost" onClick={() => setTick(0)}>
          Restart
        </Button>
      </div>
    </div>
  )
}
```

File uploads that advance chunk by chunk, each with a name and a percentage.

### Parts and states

```tsx
'use client'

import { Progress, ProgressLabel, ProgressValue } from '@youj/react'

export default function ProgressStates() {
  return (
    <div className="grid w-full max-w-lg gap-x-8 gap-y-6 sm:grid-cols-2">
      <Progress value={37}>
        <ProgressLabel>Build minutes</ProgressLabel>
        <ProgressValue />
      </Progress>
      <Progress value={100}>
        <ProgressLabel>Migration</ProgressLabel>
        <ProgressValue />
      </Progress>
      {/* A null value is indeterminate: a band sweeps the track until the work can be measured. */}
      <Progress value={null}>
        <ProgressLabel>Preparing the build</ProgressLabel>
      </Progress>
      {/* `format` shapes the value; the readout and the spoken text both add the total. */}
      <Progress
        value={7.4}
        max={10}
        format={{ style: 'unit', unit: 'gigabyte', maximumFractionDigits: 1 }}
        locale="en-US"
        getAriaValueText={(formatted) => `${formatted} of 10 GB`}
      >
        <ProgressLabel>Storage</ProgressLabel>
        <ProgressValue>{(formatted) => `${formatted} of 10 GB`}</ProgressValue>
      </Progress>
    </div>
  )
}
```

A determinate bar, a finished one, an indeterminate one and one with a custom format.

`value` runs from `min` to `max`, 0 to 100 by default. `ProgressValue` shows the percentage, or takes a function to write its own text. `format` takes `Intl.NumberFormat` options for both the readout and the spoken value, and `getAriaValueText` lets the spoken text say more, such as the total.

The bar fills in the accent in Classic and in a neutral ink in the [Bezel look](https://www.youj.dev/docs/looks), which keeps the accent for emphasis. A `tone` (`accent`, `neutral`, `success`, `warning` or `danger`) pins the fill in every style. `size` (`sm`, `default` or `lg`) sets the bar's thickness.

`Progress` renders its own track and indicator after its children, so a label and a readout sit above the bar. `ProgressTrack` and `ProgressIndicator` are exported for building your own bar inside Base UI's `Progress.Root`. They need that root, so they don't work outside it.

### Switching to indeterminate

```tsx
'use client'

import { useEffect, useState } from 'react'
import { RocketIcon } from '@youj/icons'
import { Button, Progress, ProgressLabel, ProgressValue } from '@youj/react'

// The upload reports uneven chunks that add up to 100. Finalizing reports nothing until it's live.
const CHUNKS = [9, 14, 6, 17, 11, 8, 19, 16]
const STEP_MS = 420
const FINALIZE_MS = 2400

const LABELS = { uploading: 'Uploading 1,284 files', finalizing: 'Finalizing', live: 'Live on youj.io' }

export default function ProgressPhases() {
  const [run, setRun] = useState(0)
  const [phase, setPhase] = useState<keyof typeof LABELS>('uploading')
  const [uploaded, setUploaded] = useState(0)

useEffect(() => {
    const timers = CHUNKS.map((_, i) =>
      setTimeout(() => setUploaded(CHUNKS.slice(0, i + 1).reduce((sum, n) => sum + n, 0)), (i + 1) * STEP_MS),
    )
    const uploadedAt = (CHUNKS.length + 1) * STEP_MS
    timers.push(setTimeout(() => setPhase('finalizing'), uploadedAt))
    timers.push(setTimeout(() => setPhase('live'), uploadedAt + FINALIZE_MS))
    return () => timers.forEach(clearTimeout)
  }, [run])

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <div className="flex items-center gap-3">
        <span className="grid size-8 shrink-0 place-items-center rounded-md bg-band text-fg-muted">
          <RocketIcon size={16} />
        </span>
        <div className="min-w-0 flex-1">
          <p className="truncate text-ui font-medium text-fg">youj-web</p>
          <p className="truncate text-ui-sm text-fg-muted">Production · 4f2a91c</p>
        </div>
        <Button
          size="sm"
          variant="outline"
          disabled={phase !== 'live'}
          focusableWhenDisabled
          onClick={() => {
            setPhase('uploading')
            setUploaded(0)
            setRun((r) => r + 1)
          }}
        >
          Redeploy
        </Button>
      </div>
      {/* The upload can be measured and finalizing can't, so it's null until the deploy is live. */}
      <Progress value={phase === 'finalizing' ? null : uploaded} className="mt-4">
        <ProgressLabel>{LABELS[phase]}</ProgressLabel>
        <ProgressValue />
      </Progress>
      <p role="status" className="sr-only">
        {phase === 'live' ? 'Deployed to production.' : ''}
      </p>
    </div>
  )
}
```

A deploy that uploads in chunks, then finalizes on an indeterminate bar, then goes live.

Pass `null` as soon as what's left can't be measured, like a deploy finalizing after its files upload. The bar hands over to the sweep, and `ProgressValue` shows nothing until there's a number again.

### Ticks

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Progress, ProgressLabel, ProgressValue } from '@youj/react'

// A render that measures its frames, then finalizes with no number to show.
const STEPS = [4, 9, 6, 12, 3, 8, 11, 5, 7, 10, 6, 9, 10]

export default function ProgressTicks() {
  const [step, setStep] = useState(0)
  const rendered = Math.min(100, STEPS.slice(0, step).reduce((sum, n) => sum + n, 0))

useEffect(() => {
    const id = setInterval(() => setStep((s) => (s > STEPS.length + 4 ? 0 : s + 1)), 480)
    return () => clearInterval(id)
  }, [])

return (
    <div className="grid w-full max-w-md gap-6 rounded-xl border border-line bg-surface p-5">
      <Progress variant="ticks" value={rendered}>
        <ProgressLabel>Rendering frames</ProgressLabel>
        <ProgressValue />
      </Progress>
      {/* Indeterminate: a wave of lit ticks travels until there is a number. */}
      <Progress variant="ticks" size="sm" ticks={56} tone="neutral" value={rendered < 100 ? null : 100}>
        <ProgressLabel>{rendered < 100 ? 'Waiting to encode' : 'Encoded'}</ProgressLabel>
      </Progress>
    </div>
  )
}
```

A render whose frames light up as fine ticks, and an encode step waiting on a traveling wave.

`variant="ticks"` draws the track as a row of fine vertical ticks, like a ruler or a level meter. They light from the inline start as the value grows; the tick at the edge lights partway and the next few warm up a little before the edge reaches them. With `value={null}` a wave of lit ticks travels from the start to the end, then rests. `ticks` sets how many there are (40 by default), and `size` sets their length. Everything else is the same progress: the role, the value, the label and the readout.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add progress
```

It brings `youj-core`, `youj-ui-core` with it.

Use Progress for measurable work, such as an upload or migration. Pass `value={null}` when progress is not yet known. Use a [Spinner](https://www.youj.dev/docs/components/spinner) for short, unmeasured waits, or a [Slider](https://www.youj.dev/docs/components/slider) for values people adjust themselves.

```tsx
import { Progress, ProgressLabel, ProgressValue } from '@youj/react'

export function Upload({ percent }: { percent: number }) {
  return (
    <Progress value={percent}>
      <ProgressLabel>Uploading hero@2x.png</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

`Progress` renders the track and the bar for you. Put a `ProgressLabel` and a `ProgressValue` inside it: they share the first line, and the track wraps below them. Without a visible label, give `Progress` an `aria-label`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Progress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger'` |  | The fill. Unset, the component style decides: the accent in Classic, a neutral ink in Bezel (which keeps the accent for emphasis). A tone pins it in every style. |
| `variant` | `'default' \| 'ticks'` | `'default'` | `ticks` draws the track as a row of fine vertical ticks that light from the start. |
| `size` | `Extract<Size, 'sm' \| 'default' \| 'lg'>` | `'default'` | The track's height: the bar's thickness, or the ticks' length. |
| `ticks` | `number` | `40` | How many ticks the `ticks` variant draws. |

Also takes the props of `ProgressPrimitive.Root.Props`.

It takes Base UI's `value` (a number, or `null` for indeterminate), `min`, `max`, `format`, `locale` and `getAriaValueText`.

| Data attribute | Values |
| --- | --- |
| `data-variant` | `default`, `ticks` |
| `data-size` | `sm`, `default`, `lg` |
| `data-tone` | `accent`, `neutral`, `success`, `warning`, `danger` (unset: the style decides) |
| `data-indeterminate`, `data-progressing`, `data-complete` | Base UI's state |

#### ProgressValue

Takes the props of `ProgressPrimitive.Value.Props`.

Its children can be a function of the formatted value and the raw value, `(formatted, value) => ReactNode`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Value change | `spring.smooth` | 0.36s, bounce 0 | the bar scales along its length, retargeting mid-glide |
| Indeterminate sweep | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1); × 2 per sweep | a 40% band crosses the track, on a loop |

**Reduced motion:** New values jump into place, and the indeterminate band becomes still stripes.

#### Ticks

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Value change | `spring.smooth` | 0.36s, bounce 0 | the lit count follows the value; the edge tick lights partway and the next three warm up |
| Indeterminate wave | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1); × 2 per loop | each tick warms quickly and fades slowly, its turn later along the row, so a wave crosses in 70% of the loop and rests |

**Reduced motion:** The lit count jumps to each value, and indeterminate shows every other tick lit, still.

The ticks only change opacity. They light from the inline start, so under right-to-left they fill and the wave travels from the right.

#### Bar

The bar stays full width and scales on its X axis, so only transform animates. A burst of updates retargets the spring with its velocity intact instead of restarting a tween, which is why the uneven upload chunks in the demo read as one steady glide. It fills from the inline start, so under right-to-left it fills from the right.

#### Reduced motion

The bar jumps to each new value instead of gliding, and the indeterminate sweep becomes still diagonal stripes across the track. The ticks light at once, and their indeterminate wave becomes every other tick lit, still. The amount done and the "still working" state both stay visible.

### Accessibility

- It's a `progressbar` with `aria-valuenow` and a formatted `aria-valuetext`, named by its `ProgressLabel` or `aria-label`.
- Indeterminate progress has no `aria-valuenow`, which tells assistive technology the amount isn't known.
- The ticks are decorative and hidden from assistive tech; the progressbar's value says the same thing.
- Screen readers don't reliably announce each change. When the work finishes, say so in a polite status, as "All files uploaded." does in the demo.

---

# Spinner

> Show that work is running during a short wait.

Source: https://www.youj.dev/docs/components/spinner

## Examples

### Demo

```tsx
'use client'

import { Button, Spinner } from '@youj/react'

export default function SpinnerDemo() {
  return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-xl border border-line bg-surface px-4 py-3">
      {/* The row's own status line announces the wait, so the spinner stays silent. */}
      <Spinner label={null} className="text-fg-muted" />
      <div className="min-w-0 flex-1">
        <p className="truncate text-ui font-medium text-fg">Importing 1,204 issues</p>
        <p className="truncate text-ui-sm text-fg-muted">From GitHub · about a minute left</p>
      </div>
      <Button variant="ghost" size="sm">
        Cancel
      </Button>
      <span role="status" className="sr-only">
        Importing issues from GitHub
      </span>
    </div>
  )
}
```

An import row with a spinner, a status line and a Cancel button.

### Sizes and color

```tsx
'use client'

import { Spinner } from '@youj/react'

const SIZES = [12, 16, 20, 24, 32]

export default function SpinnerSizes() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-8">
      {SIZES.map((size) => (
        <figure key={size} className="flex flex-col items-center gap-3">
          {/* The stroke holds at 1.5px up to 24px, then grows with the ring. */}
          <Spinner size={size} label={null} />
          <figcaption className="font-mono text-xs text-fg-muted">{size}px</figcaption>
        </figure>
      ))}
      <figure className="flex flex-col items-center gap-3">
        <span className="grid size-8 place-items-center rounded-md bg-accent text-on-accent">
          <Spinner label={null} />
        </span>
        <figcaption className="font-mono text-xs text-fg-muted">on accent</figcaption>
      </figure>
      <figure className="flex flex-col items-center gap-3">
        <Spinner label={null} className="text-fg-muted" />
        <figcaption className="font-mono text-xs text-fg-muted">muted</figcaption>
      </figure>
    </div>
  )
}
```

The ring at several sizes, on an accent surface and in a muted color.

`size` sets the ring's width and height in pixels, and defaults to 16. The stroke holds at 1.5px up to 24px, then grows with the ring. The spinner draws in `currentColor`, so it takes the color of the text around it, on any surface.

### In a row

```tsx
'use client'

import { CheckCircleIcon } from '@youj/icons'
import { Spinner } from '@youj/react'

export default function SpinnerInline() {
  return (
    <ul className="w-full max-w-md divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface">
      <li className="flex items-center gap-3 px-4 py-3">
        <span className="min-w-0 flex-1 truncate font-mono text-ui text-fg">youj.io</span>
        <span className="inline-flex items-center gap-1.5 text-ui-sm text-success-text">
          <CheckCircleIcon size={14} />
          Valid configuration
        </span>
      </li>
      <li className="flex items-center gap-3 px-4 py-3">
        <span className="min-w-0 flex-1 truncate font-mono text-ui text-fg">docs.youj.io</span>
        <span className="inline-flex items-center gap-1.5 text-ui-sm text-fg-muted">
          {/* On its own, the spinner announces its label politely. */}
          <Spinner size={14} label="Checking DNS for docs.youj.io" />
          <span aria-hidden>Checking DNS</span>
        </span>
      </li>
    </ul>
  )
}
```

A domains list where a small spinner marks the domain being checked.

Next to the thing that's waiting, a small spinner can carry the status on its own. Here its label names the domain it's checking, and the short visible text is hidden from assistive technology so it isn't read twice.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add spinner
```

It brings `icon-loader-ring`, `youj-core`, `youj-labels-spinner`, `youj-ui-core` with it.

Use a spinner for a wait of a few seconds whose length you can't measure: a sync, a lookup, a check. If you know how far along the work is, use [Progress](https://www.youj.dev/docs/components/progress). If you know the shape of what's loading, a [Skeleton](https://www.youj.dev/docs/components/skeleton) holds its place. On a button, use the button's own `loading` state instead of placing a spinner inside it.

```tsx
import { Spinner } from '@youj/react'

export function Syncing() {
  return <Spinner label="Syncing issues" />
}
```

On its own, a spinner announces its `label` politely. The default is "Loading". Inside something that already announces the wait, such as a loading Button or an `aria-busy` region with its own status, pass `label={null}` to keep it silent: two announcements for one wait are worse than none.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string \| null` |  | Announced politely. Pass `null` when the surrounding thing already announces the wait (a loading Button, an aria-busy region): two announcements for one wait are worse than none. |
| `size` | `number` | `16` | Rendered size in px. |

Also takes the props of `ComponentProps<'span'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Turn | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1); × 1.25 per turn | a constant-rate rotation |
| Arc | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1); × 2.2 per breath | the arc breathes between 12% and 60% of the ring |

**Reduced motion:** A still quarter arc on a faint track. The label is still announced.

The turn and the breath run on different periods, so the loop never visibly repeats. It's Youj's `LoaderRingIcon`, so it follows the Speed control and pauses when it's offscreen or the tab is hidden.

#### Reduced motion

The ring stops turning and holds a quarter arc on a faint track, which still reads as "in progress". The spoken label doesn't change.

### Accessibility

- With a `label`, the spinner is a `status` role holding the label as visually hidden text, so the wait is announced politely.
- With `label={null}` it has no role, and its ring is `aria-hidden`.
- Say what's happening, not just that something is. "Checking DNS for docs.youj.io" is better than "Loading".

---

# Skeleton

> Reserve space for content while it loads.

Source: https://www.youj.dev/docs/components/skeleton

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ContentSwap } from '@youj/motion'
import { Avatar, AvatarFallback, Badge, Button, Skeleton } from '@youj/react'

const MEMBERS = [
  { name: 'Ana Lima', email: 'ana@youj.dev', role: 'Owner', initials: 'AL' },
  { name: 'Jonas Weber', email: 'jonas@youj.dev', role: 'Admin', initials: 'JW' },
  { name: 'Priya Raman', email: 'priya@youj.dev', role: 'Member', initials: 'PR' },
]

const row = 'flex h-16 items-center gap-3 px-4 [&+&]:border-t [&+&]:border-line'

/* Shaped like the rows it stands in for, so nothing shifts when they land. */
function MembersSkeleton() {
  return MEMBERS.map((member) => (
    <div key={member.email} className={row}>
      <Skeleton className="size-8 rounded-full" />
      <div className="flex flex-1 flex-col gap-2">
        <Skeleton className="h-3 w-28" />
        <Skeleton className="h-2.5 w-36" />
      </div>
      <Skeleton className="h-5 w-14 rounded-full" />
    </div>
  ))
}

export default function SkeletonDemo() {
  const [loading, setLoading] = useState(true)

useEffect(() => {
    if (!loading) return
    const timer = setTimeout(() => setLoading(false), 2200)
    return () => clearTimeout(timer)
  }, [loading])

return (
    <div className="w-full max-w-md">
      <div className="mb-3 flex items-center justify-between">
        <p className="text-ui-lg font-medium text-fg">Members</p>
        <Button size="sm" variant="outline" onClick={() => setLoading(true)}>
          Reload
        </Button>
      </div>
      {/* ContentSwap sets aria-busy, announces the wait once, and morphs the height between the two. */}
      <ContentSwap
        loading={loading}
        fallback={<MembersSkeleton />}
        loadingLabel="Loading members"
        className="overflow-hidden rounded-xl border border-line bg-surface"
      >
        {MEMBERS.map((member) => (
          <div key={member.email} className={row}>
            <Avatar aria-hidden>
              <AvatarFallback>{member.initials}</AvatarFallback>
            </Avatar>
            <div className="min-w-0 flex-1">
              <p className="truncate text-ui font-medium text-fg">{member.name}</p>
              <p className="truncate text-ui-sm text-fg-muted">{member.email}</p>
            </div>
            <Badge variant="secondary">{member.role}</Badge>
          </div>
        ))}
      </ContentSwap>
    </div>
  )
}
```

A Members list that loads for about two seconds and resolves into content; Reload runs it again.

Pair skeletons with motion's [Content Swap](https://www.youj.dev/docs/motion/content-swap), as the demo does. The skeleton drops away quickly, the content resolves into focus a step later, and the box morphs between the two heights, so the page below moves instead of jumping. ContentSwap also marks the region `aria-busy` and announces the wait once. Press Reload to watch it go both ways.

```tsx
import { ContentSwap } from '@youj/motion'

<ContentSwap loading={isLoading} fallback={<MembersSkeleton />} loadingLabel="Loading members">
  <MemberList members={data} />
</ContentSwap>
```

### Shapes

```tsx
'use client'

import { Skeleton } from '@youj/react'

export default function SkeletonShapes() {
  return (
    // One region waits, so it carries aria-busy. The skeletons themselves are hidden from assistive tech.
    <div aria-busy className="grid w-full max-w-lg gap-4 sm:grid-cols-2">
      <div className="rounded-xl border border-line bg-surface p-4">
        <div className="flex items-center gap-3">
          <Skeleton className="size-10 rounded-full" />
          <div className="grid flex-1 gap-2">
            <Skeleton className="h-3.5 w-3/5" />
            <Skeleton className="h-3 w-2/5" />
          </div>
        </div>
        <div className="mt-4 grid gap-2">
          <Skeleton className="h-3 w-full" />
          <Skeleton className="h-3 w-11/12" />
          <Skeleton className="h-3 w-4/5" />
        </div>
      </div>
      <div className="rounded-xl border border-line bg-surface p-4">
        <Skeleton className="aspect-video w-full rounded-lg" />
        <div className="mt-4 flex items-center justify-between gap-3">
          <Skeleton className="h-3.5 w-1/2" />
          <Skeleton className="h-5 w-12 rounded-full" />
        </div>
      </div>
    </div>
  )
}
```

Skeletons for a profile card and other shapes, sized to the content they stand in for.

Match the real content's geometry: the avatar's size, the line heights, the width a title usually takes. Vary line widths so a paragraph reads as text rather than a grid of bars.

### One skeleton per request

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ContentSwap } from '@youj/motion'
import { RefreshIcon } from '@youj/icons'
import { Button, Skeleton } from '@youj/react'

// Each tile has its own query, and each one answers in its own time.
const STATS = [
  { label: 'Requests', value: '1.28M', change: '+12% from yesterday', latency: 600 },
  { label: 'Bandwidth', value: '48.2 GB', change: '+4% from yesterday', latency: 1400 },
  { label: 'Error rate', value: '0.03%', change: 'Same as yesterday', latency: 2300 },
]

function StatSkeleton() {
  return (
    <>
      <div className="flex h-8 items-center">
        <Skeleton className="h-6 w-20" />
      </div>
      <div className="flex h-4 items-center">
        <Skeleton className="h-3 w-28 max-w-full" />
      </div>
    </>
  )
}

export default function SkeletonStats() {
  const [run, setRun] = useState(0)
  // The refresh each tile last answered. A tile waits until it has answered the latest one.
  const [answered, setAnswered] = useState<Record<string, number>>({})
  const waiting = STATS.some((stat) => answered[stat.label] !== run)

useEffect(() => {
    const timers = STATS.map((stat) =>
      setTimeout(() => setAnswered((prev) => ({ ...prev, [stat.label]: run })), stat.latency),
    )
    return () => timers.forEach(clearTimeout)
  }, [run])

return (
    <div className="@container w-full max-w-xl">
      <div className="mb-3 flex items-center justify-between">
        <p className="text-ui-lg font-medium text-fg">Last 24 hours</p>
        <Button size="sm" variant="outline" onClick={() => setRun((r) => r + 1)}>
          <RefreshIcon />
          Refresh
        </Button>
      </div>
      <div className="grid gap-3 @md:grid-cols-3">
        {STATS.map((stat) => (
          <div key={stat.label} className="rounded-xl border border-line bg-surface p-4">
            {/* Known before the data, so the label stays real. Only the numbers wait. */}
            <p className="text-ui-sm text-fg-muted">{stat.label}</p>
            <ContentSwap loading={answered[stat.label] !== run} fallback={<StatSkeleton />} className="mt-1">
              <p className="text-2xl font-semibold tracking-tight text-fg tabular-nums">{stat.value}</p>
              <p className="truncate text-ui-sm text-fg-muted">{stat.change}</p>
            </ContentSwap>
          </div>
        ))}
      </div>
      <p role="status" className="sr-only">
        {waiting ? 'Loading the last 24 hours' : ''}
      </p>
    </div>
  )
}
```

Stat tiles that each resolve when their own request answers.

When a view fills in from several requests, give each region its own skeleton and ContentSwap, so each one resolves as soon as its data arrives instead of waiting for the slowest. Anything you know before the data, like these labels, stays real. Only the numbers wait.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add skeleton
```

It brings `youj-core`, `youj-ui-core` with it.

Use Skeleton when you know the shape of the loading content, such as rows, a profile or a card. Use a [Spinner](https://www.youj.dev/docs/components/spinner) for short waits without a known layout, or [Progress](https://www.youj.dev/docs/components/progress) for measurable work.

A skeleton is a block. Size and round it with classes to match the content it stands in for.

```tsx
import { Skeleton } from '@youj/react'

export function ProfileSkeleton() {
  return (
    <div className="flex items-center gap-3">
      <Skeleton className="size-10 rounded-full" />
      <div className="grid flex-1 gap-2">
        <Skeleton className="h-3.5 w-3/5" />
        <Skeleton className="h-3 w-2/5" />
      </div>
    </div>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

Takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Shimmer | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1); × 3 per cycle | a band of light crosses in the first 60% of each cycle, then rests |

**Reduced motion:** The band is gone and the blocks hold still.

The cycle is three `deliberate` beats, so the band reads as a calm pulse rather than a constant wash. It follows the Speed control, and it runs the other way under right-to-left.

#### Reduced motion

The traveling band is removed and each block is a still, recessed shape. The layout still shows where content will land.

### Accessibility

- Skeletons are `aria-hidden`: a pile of empty blocks means nothing to a screen reader.
- Put `aria-busy` on the region they stand in for, and announce the wait once in a polite status, such as "Loading members". ContentSwap does both with `loadingLabel`.
- Don't leave skeletons up once the content has failed. Swap them for an error with a way to retry.

---

# Async Feedback

> Show and announce pending, success and error states on the control that starts the work.

Source: https://www.youj.dev/docs/components/async-feedback

## Examples

### Demo

```tsx
'use client'

import { useId, useState } from 'react'
import { motion } from 'motion/react'
import { cn } from '@youj/core'
import { AsyncAnnouncer, AsyncFeedback, useAsyncAction, useMorphRoot } from '@youj/motion'
import { SendIcon } from '@youj/icons'
import { Input, Label, Switch } from '@youj/react'

const LABELS = { pendingLabel: 'Sending…', successLabel: 'Invited', errorLabel: 'Couldn’t send' }

// A stand-in for your API: it settles after a moment, and fails when asked to.
const sendInvite = (fail: boolean) => new Promise<void>((resolve, reject) => setTimeout(fail ? reject : resolve, 1400))

export default function AsyncFeedbackDemo() {
  const id = useId()
  const [email, setEmail] = useState('priya@northwind.dev')
  const [fail, setFail] = useState(false)
  const { state, run } = useAsyncAction(() => sendInvite(fail))
  const morph = useMorphRoot(8)

return (
    <div className="w-full max-w-md overflow-hidden rounded-2xl border border-line bg-surface">
      <div className="flex flex-col gap-1.5 px-5 pt-4 pb-5">
        <p className="text-sm font-medium text-fg">Invite a teammate</p>
        <p className="mb-3 text-xs text-fg-muted">They’ll get an email with a link to join northwind.</p>
        <Label htmlFor={`${id}-email`}>Email</Label>
        <Input id={`${id}-email`} type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      </div>
      <div className="flex items-center justify-between gap-3 border-t border-line bg-canvas px-5 py-3">
        <span className="flex items-center gap-2">
          <Switch id={`${id}-fail`} size="sm" checked={fail} onCheckedChange={setFail} />
          <Label htmlFor={`${id}-fail`} className="text-xs font-normal text-fg-muted">
            Fail the next request
          </Label>
        </span>
        {/* The box morphs to each label's width on the same spring as the label. */}
        <motion.button
          type="button"
          {...morph}
          onClick={run}
          aria-busy={state === 'pending' || undefined}
          className={cn(
            'relative inline-flex h-8 shrink-0 items-center justify-center overflow-hidden bg-fg px-3 text-[13px] font-medium text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas',
            (state === 'success' || state === 'error') && 'text-on-accent',
          )}
        >
          <AsyncFeedback state={state} {...LABELS}>
            <SendIcon size={14} />
            Send invite
          </AsyncFeedback>
        </motion.button>
        {/* Outside the button: a button flattens its content, so its own live region would go unheard. */}
        <AsyncAnnouncer state={state} {...LABELS} />
      </div>
    </div>
  )
}
```

An invite form with a fail switch, whose action button shows the outcome.

`useAsyncAction(onAction)` returns the current `state` and a `run` function.

- Resolve for success, and reject or throw for an error. A synchronous throw counts as an error, and a plain return value counts as success.
- `run` is ignored while an action is in flight and while a success is showing. The guard is set synchronously, so a double click within one frame can't start two actions. After an error, `run` retries at once.
- It never updates after the component unmounts, and it clears its reset timer.
- `onStateChange` fires on every change, so the rest of the UI can follow: a status dot, a toast, a refetch.

### The four states

```tsx
'use client'

import { motion } from 'motion/react'
import { cn } from '@youj/core'
import { AsyncFeedback, useMorphRoot, type AsyncState } from '@youj/motion'
import { CloudUploadIcon } from '@youj/icons'

const STATES: AsyncState[] = ['idle', 'pending', 'success', 'error']

function Specimen({ state }: { state: AsyncState }) {
  const morph = useMorphRoot(8)
  return (
    <figure className="flex flex-col items-center gap-2.5">
      {/* A static picture of each state, so it isn't a button. Press Replay to draw the marks again. */}
      <motion.span
        {...morph}
        className={cn(
          'relative inline-flex h-8 items-center overflow-hidden border border-line bg-surface px-3 text-[13px] font-medium text-fg',
          (state === 'success' || state === 'error') && 'border-transparent text-on-accent',
        )}
      >
        <AsyncFeedback state={state} pendingLabel="Publishing…" successLabel="Published" errorLabel="Couldn’t publish">
          <CloudUploadIcon size={14} />
          Publish
        </AsyncFeedback>
      </motion.span>
      <figcaption className="font-mono text-xs text-fg-muted">{state}</figcaption>
    </figure>
  )
}

export default function AsyncFeedbackStates() {
  return (
    <div className="grid grid-cols-2 gap-x-10 gap-y-6 sm:flex sm:justify-center">
      {STATES.map((state) => (
        <Specimen key={state} state={state} />
      ))}
    </div>
  )
}
```

The four states side by side.

`idle` shows your content. `pending` swaps it for a spinner. `success` draws a check beside `successLabel` and washes the surface in the success color. `error` draws a cross beside `errorLabel` over the danger color and shakes once, with a decaying 4, 3 and 2 px amplitude. Press Replay to draw the marks again.

Each swap is a crossfade through [MorphLabel](https://www.youj.dev/docs/motion/morph-label): the outgoing state blurs and shrinks a touch while the incoming one resolves, and the box morphs to the new width on the same spring. After `resetAfter` milliseconds (three `deliberate` durations by default) the control returns to `idle`.

### Marks and tint

```tsx
'use client'

import { useState } from 'react'
import { motion } from 'motion/react'
import { AsyncAnnouncer, AsyncFeedback, useAsyncAction, useMorphRoot } from '@youj/motion'
import { CheckCircleIcon, LoaderDotsIcon, RefreshIcon } from '@youj/icons'

const LABELS = { pendingLabel: 'Syncing…', successLabel: 'Synced', errorLabel: 'Sync failed' }

// A stand-in for your API.
const syncRepository = () => new Promise<void>((resolve) => setTimeout(resolve, 1200))

export default function AsyncFeedbackMarks() {
  const [lastSync, setLastSync] = useState('12 minutes ago')
  const { state, run } = useAsyncAction(async () => {
    await syncRepository()
    setLastSync('just now')
  })
  const morph = useMorphRoot(8)

return (
    <div className="flex w-full max-w-md items-center justify-between gap-4 rounded-xl border border-line bg-surface px-4 py-3">
      <div className="min-w-0">
        <p className="truncate text-sm font-medium text-fg">northwind/web</p>
        <p className="text-xs text-fg-muted">Last synced {lastSync}</p>
      </div>
      {/* A quiet secondary control: its own marks, and no tint. */}
      <motion.button
        type="button"
        {...morph}
        onClick={run}
        aria-busy={state === 'pending' || undefined}
        className="relative inline-flex h-8 shrink-0 items-center overflow-hidden border border-line bg-surface px-3 text-[13px] font-medium text-fg outline-none hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent"
      >
        <AsyncFeedback
          state={state}
          {...LABELS}
          tint={false}
          icons={{
            pending: <LoaderDotsIcon size={16} />,
            success: <CheckCircleIcon size={15} trigger="mount" className="text-success" />,
          }}
        >
          <RefreshIcon size={14} />
          Sync
        </AsyncFeedback>
      </motion.button>
      <AsyncAnnouncer state={state} {...LABELS} />
    </div>
  )
}
```

A quiet sync control with its own marks and no tint.

Replace any of the three marks with `icons`, and turn the colored wash off with `tint={false}` for quieter, secondary controls. The tint needs a `relative overflow-hidden` parent, so it stays inside the control's shape.

```tsx
import { CheckCircleIcon, LoaderDotsIcon, RefreshIcon } from '@youj/icons'

<AsyncFeedback
  state={state}
  tint={false}
  icons={{ pending: <LoaderDotsIcon size={16} />, success: <CheckCircleIcon trigger="mount" size={15} /> }}
>
  <RefreshIcon size={14} />
  Sync
</AsyncFeedback>
```

The default pending mark is a quarter arc on a faint track, turning at a constant rate. For a spinner of your own, use [Spinner](https://www.youj.dev/docs/components/spinner).

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add async-feedback
```

It brings `youj-core`, `youj-presets`, `morph-label`, `youj-labels-async-feedback` with it.

Use it when a control starts work that takes a moment and ends in an outcome people need to know: sending, saving, publishing, syncing. The control itself shows the state, so nobody has to look elsewhere for the result. Don't use it for work that finishes instantly, and don't use it for long jobs with progress to report. Show a [Progress](https://www.youj.dev/docs/components/progress) bar for those. For a finished button, use the UI [Button](https://www.youj.dev/docs/components/button)'s `onAction`, which is built on this.

Three pieces make an async control. `useAsyncAction` runs the work and reports its state, `AsyncFeedback` is what the control shows, and `AsyncAnnouncer` says it out loud. Put the feedback inside a `useMorphRoot` box so the control's width morphs with its label.

```tsx
import { motion } from 'motion/react'
import { AsyncAnnouncer, AsyncFeedback, useAsyncAction, useMorphRoot } from '@youj/motion'

const labels = { pendingLabel: 'Sending…', successLabel: 'Invited', errorLabel: 'Couldn’t send' }

export function InviteButton({ onInvite }: { onInvite: () => Promise<unknown> }) {
  const { state, run } = useAsyncAction(onInvite)
  const morph = useMorphRoot(8) // the button's corner radius, in px

return (
    <>
      <motion.button
        type="button"
        {...morph}
        onClick={run}
        aria-busy={state === 'pending' || undefined}
        className="relative inline-flex h-8 items-center overflow-hidden bg-fg px-3 text-canvas"
      >
        <AsyncFeedback state={state} {...labels}>
          Send invite
        </AsyncFeedback>
      </motion.button>
      <AsyncAnnouncer state={state} {...labels} />
    </>
  )
}
```

With a Base UI button, pass the motion element through `render`: `<ButtonPrimitive render={<motion.button {...morph} />} …>`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### AsyncFeedback

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'pending' \| 'success' \| 'error'` |  |  |
| `children` (required) | `ReactNode` |  | What the control shows at rest. |
| `pendingLabel` | `string` |  | Shown instead of the spinner when motion is reduced. Default: the `working` label, "Working…". |
| `successLabel` | `string` |  | Shown next to the check. Default: the `done` label, "Done". |
| `errorLabel` | `string` |  | Shown next to the cross. Default: the `failed` label, "Failed". |
| `icons` | `Partial<Record<'pending' \| 'success' \| 'error', ReactNode>>` |  | Replace the spinner, check or cross. |
| `tint` | `boolean` | `true` | Wash the surface in success / danger while settled. Needs a `relative overflow-hidden` parent. |

#### AsyncAnnouncer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'pending' \| 'success' \| 'error'` |  |  |
| `pendingLabel` | `string` |  | Default: the `working` label, "Working…". |
| `successLabel` | `string` |  | Default: the `done` label, "Done". |
| `errorLabel` | `string` |  | Default: the `failed` label, "Failed". |

#### useAsyncAction

```ts
function useAsyncAction(onAction: () => unknown, options?: AsyncActionOptions): { state: AsyncState; run: () => void }

type AsyncState = 'idle' | 'pending' | 'success' | 'error'
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `resetAfter` | `number` |  | How long success and error hold before returning to idle, in ms. Defaults to three `deliberate` durations. |
| `onStateChange` | `(state: AsyncState) => void` |  | Fires on every state change. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Label swap | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | crossfade with a touch of blur and scale |
| Width morph | `spring.snappy` | 0.2s, bounce 0 | the `useMorphRoot` box |
| Spinner | `ease.linear` | cubic-bezier(0, 0, 1, 1); deliberate × 1.25 | one turn |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the stroke draws, then settles |
| Check settle | `spring.settle` | 0.45s, bounce 0.3 | scale, after a `base` delay |
| Cross | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | two strokes, the second two `base` steps later |
| Error shake | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | 4, 3, 2 px and home |
| Tint | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | success or danger wash, `opacity` |
| Hold |  | 3 × deliberate | success and error, before idle, unless `resetAfter` is set |

**Reduced motion:** A text label (`pendingLabel`) replaces the spinner. Swaps and tints are instant, the marks appear already drawn, and errors don't shake.

Success earns the one overshoot in the system: the check settles on the `settle` spring. Errors stay level. The shake is a short, decaying nudge, never a bounce.

#### Reduced motion

The control still walks through all four states, and every state still has its words. `pendingLabel` replaces the spinner, so the pending state is readable without motion, and success and error appear with their marks already drawn. Swaps and tints change instantly and nothing shakes.

### Accessibility

- Render `AsyncAnnouncer` next to the control, never inside it. A button flattens its content into one accessible name, so a live region inside it isn't announced.
- The announcer speaks pending and success politely (`role="status"`) and errors assertively (`role="alert"`), so a failure interrupts and a success doesn't.
- Set `aria-busy` on the control while it's pending, as above. The control keeps focus throughout, so keyboard users don't lose their place.
- The outgoing label is hidden from assistive technology while it fades, so the control's name is never two labels at once. The spinner, the marks and the tints are `aria-hidden`; while pending, the name is `pendingLabel` ("Working…" by default), visually hidden beside the spinner. If you replace `icons.pending`, include the label in it. Keep `AsyncAnnouncer` beside the control so the state is still spoken.

---

# Empty State

> Explain why a view is empty and help people take the next step.

Source: https://www.youj.dev/docs/components/empty-state

## Examples

### Demo

```tsx
'use client'

import { PlusIcon, UploadIcon } from '@youj/icons'
import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@youj/react'

export default function EmptyStateDemo() {
  return (
    <div className="w-full max-w-xl rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-4 border-b border-line px-5 py-3">
        <p className="text-ui font-medium text-fg">Deployments</p>
        <p className="font-mono text-ui-sm text-fg-muted">youj / web</p>
      </div>
      {/* Hover the header: the plates open and the icon plays. */}
      <Empty className="py-12">
        <EmptyHeader>
          <EmptyMedia variant="icon">
            <UploadIcon />
          </EmptyMedia>
          <EmptyTitle>No deployments yet</EmptyTitle>
          <EmptyDescription>
            Push to a connected branch, or deploy from your machine with the CLI. Previews appear here as they build.
          </EmptyDescription>
        </EmptyHeader>
        <EmptyContent>
          <Button>
            <PlusIcon />
            Import project
          </Button>
          <Button variant="outline">Deploy from the CLI</Button>
        </EmptyContent>
      </Empty>
    </div>
  )
}
```

A deployments panel with an empty state; hover its header to open the plates and play the icon.

The component is `Empty`, with its parts `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription` and `EmptyContent`; there is no `EmptyState` export. For a chat that has no messages yet, [Chat Empty State](https://www.youj.dev/docs/components/chat/empty-state) is built on it.

`EmptyMedia variant="icon"` sets an icon on a tile over two plates. The plates fan out as the empty state appears and open a little further while the header is hovered. The header is also the trigger group for [Youj icons](https://www.youj.dev/docs/icons), so an animated icon on the tile plays while the header is hovered, not only when the pointer is on the icon. The default variant is a plain slot for your own illustration or image.

### No results

```tsx
'use client'

import { useRef, useState } from 'react'
import { SearchIcon } from '@youj/icons'
import {
  Button,
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from '@youj/react'

const ISSUES = [
  { id: 'KIN-214', title: 'Preview URLs expire too early' },
  { id: 'KIN-209', title: 'Build cache misses in monorepos' },
  { id: 'KIN-198', title: 'Invite emails land in spam' },
  { id: 'KIN-187', title: 'Usage chart skips the last day' },
]

export default function EmptyStateNoResults() {
  const [query, setQuery] = useState('webhook retries')
  const input = useRef<HTMLInputElement>(null)
  const term = query.trim().toLowerCase()
  const matches = ISSUES.filter((issue) => issue.title.toLowerCase().includes(term))

const clear = () => {
    setQuery('')
    // The button leaves with the empty state, so hand focus back to the search.
    input.current?.focus()
  }

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface">
      <div className="border-b border-line p-3">
        <InputGroup>
          <InputGroupAddon>
            <SearchIcon />
          </InputGroupAddon>
          <InputGroupInput ref={input} value={query} onValueChange={setQuery} aria-label="Search issues" placeholder="Search issues" />
        </InputGroup>
      </div>
      {/* The count is announced; the list and the empty state themselves stay out of the live region. */}
      <p role="status" className="sr-only">
        {matches.length ? `${matches.length} ${matches.length === 1 ? 'issue' : 'issues'}` : `No issues match ${query.trim()}`}
      </p>
      {matches.length ? (
        <ul className="py-1">
          {matches.map((issue) => (
            <li key={issue.id} className="flex items-center gap-3 px-4 py-2 text-ui">
              <span className="font-mono text-ui-sm text-fg-muted">{issue.id}</span>
              <span className="truncate text-fg">{issue.title}</span>
            </li>
          ))}
        </ul>
      ) : (
        <Empty className="py-10">
          <EmptyHeader>
            <EmptyMedia variant="icon">
              <SearchIcon />
            </EmptyMedia>
            <EmptyTitle>No issues match “{query.trim()}”</EmptyTitle>
            <EmptyDescription>Check the spelling, or clear the search to see every open issue.</EmptyDescription>
          </EmptyHeader>
          <EmptyContent>
            <Button variant="outline" size="sm" onClick={clear}>
              Clear search
            </Button>
          </EmptyContent>
        </Empty>
      )}
    </div>
  )
}
```

A search for "webhook retries" that matches nothing, with an empty state that echoes the query.

When a search or filter matches nothing, echo the query in the title so people can see what they asked for, and offer the way out.

The swap between the list and the empty state is silent, so the example announces the result count in a polite live region. Clearing the search removes the button that had focus, so it hands focus back to the search field.

### Errors

```tsx
'use client'

import { AlertTriangleIcon } from '@youj/icons'
import { AsyncButton, buttonVariants, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@youj/react'

// The API is down for this demo, so every retry fails after a realistic wait.
const retry = () => new Promise((_, reject) => setTimeout(() => reject(new Error('Gateway timeout')), 1200))

export default function EmptyStateError() {
  return (
    <Empty className="w-full max-w-md border border-line bg-surface">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <AlertTriangleIcon className="text-warning" />
        </EmptyMedia>
        <EmptyTitle>Couldn’t load deployments</EmptyTitle>
        <EmptyDescription>The API timed out after 10 seconds. Your deployments are fine; only this list failed to load.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        {/* onAction shows the whole attempt in place: Retrying…, then the outcome. */}
        <AsyncButton variant="outline" onAction={retry} pendingLabel="Retrying…" errorLabel="Still failing">
          Try again
        </AsyncButton>
        {/* Navigation stays a link, dressed as a button. */}
        <a href="#status" className={buttonVariants({ variant: 'ghost' })}>
          View status page
        </a>
      </EmptyContent>
    </Empty>
  )
}
```

An error empty state whose retry shows its attempt in place.

When a region fails to load, say what failed and what didn't, and offer a retry. An [Async Button](https://www.youj.dev/docs/components/button#async-actions) with `onAction` shows the attempt in place, from pending to the outcome.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add empty
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use an empty state wherever a list, table or panel can be empty: before the first item exists, when a search matches nothing, and when the content failed to load. Show it where the content would be, so the page keeps its shape and people know where things will appear. Keep full-page failures, like a missing route, for an error page.

```tsx
import { InboxIcon } from '@youj/icons'
import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@youj/react'

export function NoIssues() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <InboxIcon />
        </EmptyMedia>
        <EmptyTitle>No open issues</EmptyTitle>
        <EmptyDescription>Issues you create or are assigned will land here.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button>New issue</Button>
      </EmptyContent>
    </Empty>
  )
}
```

`Empty` centers its content and fills the space it's given. `EmptyHeader` holds the media, the title and the description. `EmptyContent` holds the actions, outside the header. An empty state with nothing to do next, like an inbox at zero, leaves `EmptyContent` out.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'icon'` | `'default'` |  |

`Empty`, `EmptyHeader`, `EmptyTitle` and `EmptyContent` take the props of a `div`, and `EmptyDescription` takes those of a `p`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Plates fan out | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | from a neat stack as the media appears |
| Header hover | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the plates open a few degrees further |
| Icon |  | the icon’s own choreography | plays while the header is hovered |

**Reduced motion:** The plates rest fanned and still, and icons hold their resting pose on hover.

The plates rotate about their own bottom corners, so the pair splays like cards in a hand. Only `rotate` and `translate` change.

#### Reduced motion

The plates appear already fanned and don't move on hover, and icons inside hold their resting pose. The layout and the message are the same.

### Accessibility

- The plates and the icon are decorative and hidden from assistive technology. The title and description carry the message.
- `EmptyTitle` is a `div`, so it isn't part of the page's outline. When the empty state stands in for a whole panel or page, put a heading inside it, such as `<EmptyTitle><h2>No deployments yet</h2></EmptyTitle>`.
- An empty state that replaces content after a search or filter appears without an announcement. Report the change in a polite live region, and keep focus on a control that still exists.
- Actions sit outside the header, so their icons play only with their own buttons.

---

# Card

> Group related content and actions on a card, with optional lift or lighting effects.

Source: https://www.youj.dev/docs/components/card

## Examples

### Demo

```tsx
'use client'

import { MoreHorizontalIcon } from '@youj/icons'
import {
  Button,
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Progress,
  ProgressLabel,
  ProgressValue,
} from '@youj/react'

const USAGE = [
  { label: 'Bandwidth', value: 812, max: 1000, unit: 'GB' },
  { label: 'Build minutes', value: 2140, max: 6000, unit: 'min' },
  { label: 'Storage', value: 7.4, max: 10, unit: 'GB' },
]

const amount = (value: number, max: number, unit: string) => `${value.toLocaleString('en-US')} of ${max.toLocaleString('en-US')} ${unit}`

export default function CardDemo() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Usage this cycle</CardTitle>
        <CardDescription>Resets in 12 days, on October 1.</CardDescription>
        <CardAction>
          <Button variant="ghost" size="icon-sm" aria-label="Usage options">
            <MoreHorizontalIcon />
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        {USAGE.map(({ label, value, max, unit }) => (
          <Progress key={label} value={value} max={max} getAriaValueText={() => amount(value, max, unit)}>
            <ProgressLabel>{label}</ProgressLabel>
            <ProgressValue>{() => amount(value, max, unit)}</ProgressValue>
          </Progress>
        ))}
      </CardContent>
      <CardFooter className="justify-between gap-4">
        <span className="text-ui-sm text-fg-muted">Pro plan · $20 per month</span>
        <Button size="sm">Upgrade</Button>
      </CardFooter>
    </Card>
  )
}
```

A usage card with an action in its header, progress bars in its content and a footer.

`variant="inset"` is for the [Bezel look](https://www.youj.dev/docs/looks): the card becomes a shell that carries the head, with everything under it in a well inset at the concentric radius. Classic draws it as the default card, so the choice is safe to leave in place when you switch styles.

### Panel

```tsx
'use client'

import {
  Badge,
  Button,
  Card,
  CardAction,
  CardContent,
  CardHeader,
  CardTitle,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from '@youj/react'
import { InfoIcon, MoreHorizontalIcon } from '@youj/icons'

const QUEUES = [
  { name: 'Preview builds', minutes: '1,284', share: '46%' },
  { name: 'Production', minutes: '812', share: '29%' },
  { name: 'Scheduled jobs', minutes: '503', share: '18%' },
  { name: 'Docs', minutes: '196', share: '7%' },
]

export default function CardPanel() {
  return (
    <TooltipProvider>
      <Card variant="panel" className="w-full max-w-sm">
        <CardHeader>
          <CardTitle>
            Build minutes
            <Tooltip>
              <TooltipTrigger render={<Button variant="ghost" size="icon-xs" aria-label="About build minutes" />}>
                <InfoIcon />
              </TooltipTrigger>
              <TooltipContent>Minutes billed this cycle, by queue.</TooltipContent>
            </Tooltip>
          </CardTitle>
          <CardAction>
            <Button variant="outline" size="icon-xs" aria-label="Build minutes options">
              <MoreHorizontalIcon />
            </Button>
          </CardAction>
        </CardHeader>
        <CardContent className="flex flex-col gap-3">
          <div className="flex items-baseline gap-2">
            <span className="text-3xl font-medium tracking-tight tabular-nums">2,795</span>
            <Badge variant="success">−8% vs last cycle</Badge>
          </div>
          <ul className="divide-y divide-dashed divide-line">
            {QUEUES.map((queue) => (
              <li key={queue.name} className="flex items-center gap-3 py-2">
                <span className="flex-1">{queue.name}</span>
                <span className="font-medium tabular-nums">{queue.minutes}</span>
                <span className="w-9 text-end text-ui-sm text-fg-muted tabular-nums">{queue.share}</span>
              </li>
            ))}
          </ul>
        </CardContent>
      </Card>
    </TooltipProvider>
  )
}
```

A dashboard panel: build minutes by queue, under a slim header strip.

`variant="panel"` turns the header into one slim line: the `CardTitle` in the theme's label face (mono capitals in Bezel), room in the title for an info tip, and the `CardAction` at the end for a menu button. Everything under it sits on a raised surface inset in the shell. It draws the same way in every look.

### Size

```tsx
'use client'

import { Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardProps } from '@youj/react'

const VARIABLES = ['DATABASE_URL', 'STRIPE_SECRET_KEY', 'RESEND_API_KEY']

function EnvironmentCard({ size }: { size: CardProps['size'] }) {
  return (
    <Card size={size} className="h-full">
      <CardHeader>
        <CardTitle>Environment variables</CardTitle>
        <CardDescription>Encrypted, and read at build time.</CardDescription>
        <CardAction>
          <Button variant="outline" size="sm">
            Edit
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <ul className="flex flex-col gap-1.5 font-mono text-ui-sm">
          {VARIABLES.map((name) => (
            <li key={name} className="flex items-center justify-between gap-3">
              <span className="truncate text-fg">{name}</span>
              <span className="text-fg-muted">
                <span aria-hidden>••••••</span>
                <span className="sr-only">value hidden</span>
              </span>
            </li>
          ))}
        </ul>
      </CardContent>
      <CardFooter>
        <span className="text-ui-sm text-fg-muted">Production · updated 3 days ago</span>
      </CardFooter>
    </Card>
  )
}

export default function CardSizes() {
  return (
    <div className="@container w-full max-w-2xl">
      <div className="grid items-start gap-4 @lg:grid-cols-2">
        {(['default', 'sm'] as const).map((size) => (
          <figure key={size} className="flex flex-col gap-2">
            <figcaption className="font-mono text-ui-xs text-fg-muted">size="{size}"</figcaption>
            <EnvironmentCard size={size} />
          </figure>
        ))}
      </div>
    </div>
  )
}
```

Default and small cards.

`size="sm"` tightens the card's spacing from 20px to 16px and sets the title one step smaller. Use it in dense grids and sidebars.

### Lift

```tsx
'use client'

import { ExternalLinkIcon, GitBranchIcon } from '@youj/icons'
import { Badge, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from '@youj/react'

const PROJECTS = [
  { name: 'web', domain: 'youj.io', branch: 'main', updated: '4m ago', ready: true },
  { name: 'dashboard', domain: 'app.youj.io', branch: 'release/2.4', updated: '1h ago', ready: false },
  { name: 'docs', domain: 'docs.youj.io', branch: 'main', updated: '2h ago', ready: true },
  { name: 'api', domain: 'api.youj.io', branch: 'main', updated: '1d ago', ready: true },
]

export default function CardLift() {
  return (
    <div className="@container w-full max-w-xl">
      <ul className="grid gap-3 @md:grid-cols-2">
        {PROJECTS.map((project) => (
          <li key={project.name}>
            {/* data-yj-trigger: the icons inside play while the card is hovered or focused. */}
            <Card lift size="sm" className="h-full" data-yj-trigger="">
              <CardHeader>
                <CardTitle>
                  {/* A stretched link: the whole card is the target, and the link is its one tab stop. */}
                  <a href={`#${project.name}`} className="rounded-sm after:absolute after:inset-0 after:rounded-xl focus-visible:outline-none">
                    {project.name}
                  </a>
                </CardTitle>
                <CardDescription className="flex items-center gap-1">
                  {project.domain}
                  <ExternalLinkIcon size={12} />
                </CardDescription>
                <CardAction>
                  <Badge variant={project.ready ? 'success' : 'warning'}>{project.ready ? 'Ready' : 'Building'}</Badge>
                </CardAction>
              </CardHeader>
              <CardContent className="flex items-center gap-1.5 text-ui-sm text-fg-muted">
                <GitBranchIcon size={14} />
                <span className="truncate font-mono">{project.branch}</span>
                <span aria-hidden>·</span>
                <span className="shrink-0">{project.updated}</span>
              </CardContent>
            </Card>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

Cards that lift on hover and keyboard focus.

For a card that is one big target, like a project in a grid, `lift` raises the card 2px on hover or keyboard focus and deepens its shadow. Pressing sets it back down. Make the title a stretched link, so the whole card responds to the pointer while the link stays the card's only tab stop. The card wears the link's focus ring.

```tsx
<Card lift>
  <CardHeader>
    <CardTitle>
      <a href="/projects/web" className="after:absolute after:inset-0 after:rounded-xl focus-visible:outline-none">
        web
      </a>
    </CardTitle>
  </CardHeader>
</Card>
```

The demo cards also carry `data-yj-trigger=""`, which you add yourself (Card doesn't set it), so the [Youj icons](https://www.youj.dev/docs/icons) inside them play while a card is hovered or focused, not only when the pointer lands on an icon.

### Spotlight

```tsx
'use client'

import { SpotlightGroup } from '@youj/motion'
import { GitPullRequestIcon, KanbanIcon, MessagesIcon } from '@youj/icons'
import { Badge, Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@youj/react'

const INTEGRATIONS = [
  { name: 'GitHub', Icon: GitPullRequestIcon, description: 'Deploy every push and comment on pull requests.', connected: true },
  { name: 'Slack', Icon: MessagesIcon, description: 'Post deploy and incident alerts to a channel.', connected: false },
  { name: 'Linear', Icon: KanbanIcon, description: 'Link each deployment to the issues it ships.', connected: false },
]

export default function CardSpotlight() {
  return (
    <div className="@container w-full max-w-2xl">
      {/* One light for the whole group: a neighbor's edge glows as the pointer nears it. */}
      <SpotlightGroup radius={240} className="grid gap-3 @lg:grid-cols-3">
        {INTEGRATIONS.map(({ name, Icon, description, connected }) => (
          <Card key={name} spotlight size="sm">
            <CardHeader>
              <span className="mb-2 grid size-9 place-items-center rounded-lg border border-line bg-band text-fg">
                <Icon size={16} strokeWidth={1.75} />
              </span>
              <CardTitle className="flex items-center gap-2">
                {name}
                {connected && <Badge variant="success">Connected</Badge>}
              </CardTitle>
              <CardDescription>{description}</CardDescription>
            </CardHeader>
            <CardContent className="mt-auto">
              <Button variant={connected ? 'outline' : 'secondary'} size="sm" className="w-full">
                {connected ? 'Configure' : `Connect ${name}`}
              </Button>
            </CardContent>
          </Card>
        ))}
      </SpotlightGroup>
    </div>
  )
}
```

Cards lit by a spotlight that follows the pointer.

`spotlight` lights the card with the [Spotlight](https://www.youj.dev/docs/components/spotlight) effect. A soft glow follows the pointer across the surface, and the border brightens where the light passes over it. Put several cards in a `SpotlightGroup` from `@youj/motion` and they share one light, so a neighbor's nearest edge glows as the pointer approaches it.

Tab through the buttons: keyboard focus parks the light on the focused card and glides it from card to card. Touch input doesn't move the light. Save the effect for a few cards that deserve attention, like integrations or plans, not every card in an app.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add card
```

It brings `spotlight`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Card to group content and actions for a project, integration or usage summary. Use headings and spacing for sections that do not need a separate surface. Reserve `lift` and `spotlight` for cards that are themselves interactive.

```tsx
import { Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@youj/react'

export function UsageCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Usage this cycle</CardTitle>
        <CardDescription>Resets in 12 days, on October 1.</CardDescription>
        <CardAction>
          <Button variant="outline" size="sm">
            Details
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent>{/* meters, a chart, a list */}</CardContent>
      <CardFooter>
        <Button size="sm">Upgrade</Button>
      </CardFooter>
    </Card>
  )
}
```

`CardHeader` sets the title and description in a grid. A `CardAction` inside it takes its own column at the end and spans both rows, so a long title wraps without pushing the action down. `CardContent` shares the header's inset. `CardFooter` is recessed onto the muted surface, with a hairline above it and the card's inner radius below. An image as the card's first child runs edge to edge, with its top corners rounded to match.

### Cards of equal height

A card is a flex column, and grid items stretch to the row's height, so cards in a grid are already as tall as the tallest. To keep the footers on one line, push each footer to the bottom with `mt-auto`. If a wrapper sits between the grid and the card, such as a link, give the wrapper `h-full` and the Card `h-full` too:

```tsx
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
  {plans.map((plan) => (
    <Card key={plan.name} className="h-full">
      <CardHeader>
        <CardTitle>{plan.name}</CardTitle>
        <CardDescription>{plan.summary}</CardDescription>
      </CardHeader>
      <CardContent>{plan.features}</CardContent>
      <CardFooter className="mt-auto">
        <Button className="w-full">Choose {plan.name}</Button>
      </CardFooter>
    </Card>
  ))}
</div>
```

### A featured card

Mark the card to look at first, such as the recommended plan, with a ring in the accent color. A `Badge` in the header names why:

```tsx
<Card className="ring-2 ring-accent">
  <CardHeader>
    <CardTitle>Pro</CardTitle>
    <CardAction>
      <Badge>Most popular</Badge>
    </CardAction>
  </CardHeader>
  {/* … */}
</Card>
```

### With a form

To submit what a card holds, wrap its parts in a `<form>` inside the card, so the footer's button submits it:

```tsx
import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Field, FieldLabel, Input } from '@youj/react'

export function ProjectNameCard({ onSave }: { onSave: (name: string) => void }) {
  return (
    <Card>
      <form
        onSubmit={(event) => {
          event.preventDefault()
          onSave(String(new FormData(event.currentTarget).get('name')))
        }}
      >
        <CardHeader>
          <CardTitle>Project name</CardTitle>
          <CardDescription>Shown in the sidebar and in links.</CardDescription>
        </CardHeader>
        <CardContent>
          <Field>
            <FieldLabel htmlFor="project-name">Name</FieldLabel>
            <Input id="project-name" name="name" defaultValue="Orion" />
          </Field>
        </CardContent>
        <CardFooter>
          <Button type="submit" size="sm">
            Save
          </Button>
        </CardFooter>
      </form>
    </Card>
  )
}
```

The card lays out a `<form>` that is its direct child as if it weren't there (`display: contents`), so the parts keep the card's spacing and Bezel's header band, dividers and section shading. Without that, the form would be the card's only child: the gap between parts would go, and Bezel's rules, which style the card's own children, would miss the header and footer. Put the form directly in the card, around the parts. A form nested deeper, or another wrapper element, isn't looked through. Card has no `render` prop, so it can't render as the form itself.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'default' \| 'sm'` | `'default'` |  |
| `variant` | `'default' \| 'inset' \| 'panel'` | `'default'` | `inset`: in the Bezel style, a shell carrying the head, with the rest in a well inside it at the concentric radius. Classic draws it as the default card. `panel`: in every style, a slim header strip (the title as a small label, an info tip, a menu button) over the content on a raised surface inset in the shell. |
| `lift` | `boolean` | `false` | Rise on hover and focus: for cards that are one big target. |
| `spotlight` | `boolean` | `false` | Light the card with motion's Spotlight effect. |

Also takes the props of `ComponentProps<'div'>`.

`CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent` and `CardFooter` take the props of a `div`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lift | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | rise 2px, deeper shadow, on hover and focus |
| Press | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | sets the card back down |
| Spotlight in and out | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the glow and the lit edge fade |
| Spotlight tracking |  | every animation frame | the light follows the pointer |
| Focus glide | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the light moves to the focused card |

**Reduced motion:** Lift drops the rise and changes the shadow and border at once. Spotlight stops tracking and shows a static accent border on hover and focus.

The light is a radial gradient moved with `transform`, and the lit edge is the same gradient masked to a 1px ring, so tracking never triggers layout.

#### Reduced motion

A lifting card stays in place. Its shadow and border still change on hover and focus, at once. A spotlight card doesn't track the pointer. Hovering or focusing it shows a static accent border instead, so it still answers.

### Accessibility

- A card is a `div` with no role. Give a set of cards list semantics by rendering them in a `ul`, one card per `li`.
- `CardTitle` is a `div`, so it doesn't appear in the page's outline. When a card titles a section, put a heading inside it, such as `<CardTitle><h2>Usage this cycle</h2></CardTitle>`. The heading keeps the card's type.
- A lifting card needs one real target. A stretched link gives it a name, link semantics and a single tab stop. Keep other controls out of a stretched-link card, or lift them above the link's overlay with `relative z-10`.
- Spotlight's light layers are `aria-hidden`. The card's content and tab order don't change.

---

# Separator

> Separate groups of content with a horizontal or vertical line.

Source: https://www.youj.dev/docs/components/separator

## Examples

### Demo

```tsx
'use client'

import { Separator } from '@youj/react'

export default function SeparatorDemo() {
  return (
    <div className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <p className="text-ui-lg font-medium text-fg">youj-web</p>
      <p className="mt-1 text-ui text-fg-muted">The marketing site and docs, deployed from main.</p>
      <Separator className="my-4" />
      {/* Vertical separators stretch to the height of their row. */}
      <div className="flex h-5 items-center gap-3 text-ui text-fg-muted">
        <span>Deployments</span>
        <Separator orientation="vertical" />
        <span>Domains</span>
        <Separator orientation="vertical" />
        <span>Settings</span>
      </div>
    </div>
  )
}
```

A separator under a project title, and vertical separators between its links.

### In toolbars and forms

```tsx
'use client'

import { BoldIcon, CodeIcon, ItalicIcon, LinkIcon, UnderlineIcon } from '@youj/icons'
import { Button, FieldSeparator, Separator } from '@youj/react'

export default function SeparatorToolbar() {
  return (
    <div className="flex w-full max-w-xs flex-col items-center gap-8">
      {/* Groups of related tools, split by vertical hairlines. */}
      <div role="group" aria-label="Formatting" className="flex h-control items-center gap-1 rounded-lg border border-line bg-surface px-1">
        <Button variant="ghost" size="icon-sm" aria-label="Bold">
          <BoldIcon />
        </Button>
        <Button variant="ghost" size="icon-sm" aria-label="Italic">
          <ItalicIcon />
        </Button>
        <Button variant="ghost" size="icon-sm" aria-label="Underline">
          <UnderlineIcon />
        </Button>
        <Separator orientation="vertical" className="mx-1 my-1.5" />
        <Button variant="ghost" size="icon-sm" aria-label="Link">
          <LinkIcon />
        </Button>
        <Button variant="ghost" size="icon-sm" aria-label="Code">
          <CodeIcon />
        </Button>
      </div>

{/* A labelled break between two ways in. */}
      <div className="grid w-full gap-4">
        <Button variant="outline">Continue with GitHub</Button>
        <FieldSeparator>or</FieldSeparator>
        <Button variant="outline">Continue with email</Button>
      </div>
    </div>
  )
}
```

Separators in a toolbar and in a form.

A vertical separator splits a row of tools into groups. `FieldSeparator`, from Field, centers a word on the line for a labeled break.

### Responsive layouts

```tsx
'use client'

import { Separator } from '@youj/react'

export default function SeparatorResponsive() {
  return (
    <div className="@container w-full max-w-xl">
      <div className="flex flex-col gap-4 rounded-xl border border-line bg-surface p-4 @md:flex-row @md:gap-5">
        <Detail label="Source" value="New pricing page" note="main · 4f2a91c · Ana Lima" />
        {/* One line per layout. The hidden one leaves the accessibility tree, so what's announced matches what's drawn. */}
        <Separator className="@md:hidden" />
        <Separator orientation="vertical" className="hidden @md:block" />
        <Detail label="Domains" value="youj.io" note="www.youj.io redirects here" />
      </div>
    </div>
  )
}

function Detail({ label, value, note }: { label: string; value: string; note: string }) {
  return (
    <div className="min-w-0 flex-1">
      <p className="text-ui-sm text-fg-muted">{label}</p>
      <p className="mt-1 truncate text-ui font-medium text-fg">{value}</p>
      <p className="truncate text-ui-sm text-fg-muted">{note}</p>
    </div>
  )
}
```

A separator that turns with its layout.

When groups sit side by side on wide screens and stack on narrow ones, the line has to turn with them, and so does the `aria-orientation` it exposes. Render one separator of each orientation and show the one that matches, at the same breakpoint as the layout. A hidden separator leaves the accessibility tree too, so only the visible one is announced.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add separator
```

It brings `youj-ui-core` with it.

Use Separator when spacing alone does not clearly distinguish groups of content. For a labeled break in a form, such as “or” between sign-in methods, use `FieldSeparator`.

```tsx
import { Separator } from '@youj/react'

export function Section() {
  return (
    <div>
      <p>Deployments</p>
      <Separator className="my-4" />
      <p>Domains</p>
    </div>
  )
}
```

It draws a 1px line in the border token and spans its container. `orientation="vertical"` draws it down instead, and it stretches to the height of its row, so a flex row of links needs no fixed height on the line.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

Takes the props of `SeparatorPrimitive.Props`.

`orientation` is `horizontal` or `vertical`, and defaults to `horizontal`.

### Reduced motion

Separator is static. Nothing changes under reduced motion.

### Accessibility

- It's a `separator` role with `aria-orientation`, from Base UI, so assistive technology hears the break between groups.
- A purely visual line inside a single group, such as a divider between list rows, doesn't need to be announced. Draw it with a border instead.

---

# Scroll Area

> Contain scrolling content with slim scrollbars and fading edges that show more is available.

Source: https://www.youj.dev/docs/components/scroll-area

## Examples

### Demo

```tsx
'use client'

import { useId } from 'react'
import { Badge, ScrollArea } from '@youj/react'

const RELEASES = [
  { version: '2.4.0', date: 'Sep 24', title: 'Preview comments', note: 'Reviewers pin feedback to any element of a preview.' },
  { version: '2.3.2', date: 'Sep 17', title: 'Faster cold starts', note: 'Functions boot 38% faster in every region.' },
  { version: '2.3.1', date: 'Sep 11', title: 'Spend limits', note: 'Pause overage before it happens, per project.' },
  { version: '2.3.0', date: 'Sep 3', title: 'Monorepo caching', note: 'Unchanged packages skip the build entirely.' },
  { version: '2.2.4', date: 'Aug 27', title: 'Audit log export', note: 'Stream team events to your own storage.' },
  { version: '2.2.3', date: 'Aug 20', title: 'Custom 404 pages', note: 'Serve your own page for missing routes.' },
  { version: '2.2.0', date: 'Aug 12', title: 'Edge config', note: 'Read feature flags in under a millisecond.' },
  { version: '2.1.0', date: 'Jul 30', title: 'Branch protection', note: 'Require checks before a branch can deploy.' },
  { version: '2.0.0', date: 'Jul 15', title: 'The new dashboard', note: 'Every project, deployment and log in one place.' },
]

export default function ScrollAreaDemo() {
  const titleId = useId()

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between border-b border-line px-4 py-3">
        <p id={titleId} className="text-ui font-medium text-fg">
          Changelog
        </p>
        <Badge variant="secondary">{RELEASES.length} releases</Badge>
      </div>
      {/* Scroll it: the top edge starts to fade as you leave the start, the bottom one clears at the end. */}
      <ScrollArea aria-labelledby={titleId} className="h-72 rounded-b-xl">
        <ol className="flex flex-col py-1">
          {RELEASES.map((release) => (
            <li key={release.version} className="grid grid-cols-[4.5rem_1fr] gap-x-3 px-4 py-2.5">
              <span className="font-mono text-ui-sm leading-5 text-fg-muted">v{release.version}</span>
              <span className="text-ui leading-5 font-medium text-fg">{release.title}</span>
              <span className="text-ui-sm text-fg-muted">{release.date}</span>
              <span className="text-ui-sm text-fg-muted">{release.note}</span>
            </li>
          ))}
        </ol>
      </ScrollArea>
    </div>
  )
}
```

A list of releases in a fixed-height Scroll Area, with slim scrollbars and fading edges.

Each edge with more to scroll fades out over 24px, by how far there is left to go on that side. At the start only the bottom edge fades. Scroll down and the top fade grows in, then the bottom one clears as you reach the end. The fades come straight from Base UI's overflow values, so they track the scroll exactly instead of switching on.

`fade={false}` turns them off, for content with edges of its own, like a table with a sticky header.

### Horizontal

```tsx
'use client'

import { useId } from 'react'
import { Badge, ScrollArea } from '@youj/react'

const REGIONS = [
  { code: 'iad1', city: 'Washington, D.C.', latency: 18, primary: true },
  { code: 'sfo1', city: 'San Francisco', latency: 64 },
  { code: 'gru1', city: 'São Paulo', latency: 121 },
  { code: 'fra1', city: 'Frankfurt', latency: 92 },
  { code: 'cdg1', city: 'Paris', latency: 88 },
  { code: 'bom1', city: 'Mumbai', latency: 187 },
  { code: 'hnd1', city: 'Tokyo', latency: 162 },
  { code: 'syd1', city: 'Sydney', latency: 204 },
]

export default function ScrollAreaHorizontal() {
  const titleId = useId()

return (
    <div className="w-full max-w-lg">
      <p id={titleId} className="mb-2 text-ui font-medium text-fg">
        Function regions
      </p>
      {/* Shift and the wheel, a trackpad, or focus the strip and use the arrow keys. */}
      <ScrollArea orientation="horizontal" aria-labelledby={titleId} className="rounded-xl border border-line bg-surface">
        <ul className="flex w-max gap-2 p-3">
          {REGIONS.map((region) => (
            <li key={region.code} className="flex w-36 shrink-0 flex-col gap-1 rounded-lg border border-line bg-canvas px-3 py-2.5">
              <span className="flex items-center justify-between gap-2">
                <span className="font-mono text-ui-sm text-fg">{region.code}</span>
                {region.primary && <Badge>Primary</Badge>}
              </span>
              <span className="truncate text-ui-sm text-fg-muted">{region.city}</span>
              <span className="font-mono text-ui-xs text-fg-muted tabular-nums">{region.latency} ms</span>
            </li>
          ))}
        </ul>
      </ScrollArea>
    </div>
  )
}
```

A strip that scrolls horizontally.

`orientation="horizontal"` renders a horizontal scrollbar and fades the side edges. Give the content `w-max` so it can grow past the viewport.

### Both axes

```tsx
'use client'

import { ScrollArea } from '@youj/react'

const STEPS = ['resolve', 'install', 'compile', 'bundle', 'optimize', 'upload']

// A deterministic build log, wider and taller than its box.
const LOG = Array.from({ length: 28 }, (_, i) => {
  const seconds = 130 + i * 2 // from 14:02:10
  const time = `14:${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`
  const level = i % 9 === 5 ? 'WARN' : 'INFO'
  const step = STEPS[i % STEPS.length]
  return `${time}  ${level}  step=${step} worker=${(i % 4) + 1} cache=${i % 3 ? 'hit' : 'miss'} route=/api/v2/projects/web/deployments/${(4096 + i * 37).toString(16)} took=${12 + ((i * 13) % 90)}ms`
})

export default function ScrollAreaBoth() {
  return (
    <ScrollArea orientation="both" aria-label="Build log" className="h-64 w-full max-w-xl rounded-xl border border-line bg-surface">
      <pre className="w-max p-4 font-mono text-ui-sm leading-6 text-fg-muted">{LOG.join('\n')}</pre>
    </ScrollArea>
  )
}
```

A region that scrolls on both axes.

`orientation="both"` renders both scrollbars and the corner where they meet. The two fades intersect, so each axis fades its own edges.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add scroll-area
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Scroll Area for a fixed-size region, such as a feed, build log or strip of items. Let main content scroll with the page. Avoid nested scrolling for long forms or content people must read in full.

```tsx
import { ScrollArea } from '@youj/react'

export function Activity() {
  return (
    <ScrollArea aria-label="Activity" className="h-72">
      <ActivityList />
    </ScrollArea>
  )
}
```

Give it a height, or a width for horizontal scrolling. Scrolling is native: the wheel, touch, and the keyboard once the viewport has focus. The scrollbars overlay the content, appear while you hover or scroll, and fade away after.

### Native scrollbars

`ui.css` gives the browser's own scrollbars the same thumb, on a transparent track. The page's bar is thin, and every other native bar takes the theme's colors, scopes included. Add `yj-scrollbar` to an element that scrolls natively, like a code panel or a long list, to make its bar thin and bring the thumb up to 3:1 contrast while the pointer or focus is on it.

```tsx
<pre className="max-h-80 overflow-auto yj-scrollbar">{source}</pre>
```

It sets only `scrollbar-width` and `scrollbar-color`, so bars that macOS overlays stay overlays, and hovering changes the color, never the layout. The thumb colors are the `--ui-scrollbar-thumb`, `--ui-scrollbar-thumb-hover` and `--ui-scrollbar-thumb-active` tokens. Set `scrollbar-color: auto` on an element to hand its bars back to the platform.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which scrollbars to render. |
| `fade` | `boolean` | `true` | Fade the edges that have more to scroll. |
| `viewportClassName` | `string` |  | Classes for the viewport (the element that scrolls). |

Also takes the props of `ScrollAreaPrimitive.Root.Props`.

`ScrollBar`, the bar and its thumb, is exported for custom compositions and takes Base UI's scrollbar props, such as `orientation`. `ScrollArea` already renders the bars its `orientation` needs.

### Styling the viewport

`className` styles the root, the element that has the size, border and radius. `viewportClassName` reaches the element that actually scrolls, for padding that should scroll with the content or for scroll snapping.

```tsx
<ScrollArea orientation="horizontal" viewportClassName="snap-x snap-mandatory" className="w-full">
  <ul className="flex w-max gap-3 p-3">{slides}</ul>
</ScrollArea>
```

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Scrollbar in, on hover | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | `opacity` |
| Scrollbar in, while scrolling | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | appears almost at once |
| Scrollbar out | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | after hovering or scrolling stops |
| Thumb | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | widens from 6px to 8px and firms up on hover and press |
| Native thumb (yj-scrollbar) | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | firms up while the pointer or focus is on the region |
| Edge fades |  | tied to scroll, no timing | follow the scroll position |

**Reduced motion:** Scrollbars appear and leave at once, and thumbs change at once. Scrolling and the edge fades don't change.

#### Reduced motion

The scrollbars appear and disappear at once, and thumbs change width and color at once. Scrolling itself, and the edge fades that follow it, are unchanged: they move only as you scroll.

### Accessibility

- The viewport is a tab stop only when it can scroll, so a short list adds nothing to the tab order. Once it has focus, the arrow keys, Page Up, Page Down, Home and End scroll it.
- Name it with `aria-label` or `aria-labelledby`. The name goes on the viewport, which becomes a `region`, so screen reader users can find it and hear what it holds. Without a name it adds no landmark.
- The focus ring is drawn by the root, outside the viewport, so the edge fades can't hide it.
- The scrollbars are for the pointer. Keyboard and screen reader users scroll the viewport directly.

---

# Resizable

> Let people resize or collapse panels with a pointer or keyboard, and save the layout.

Source: https://www.youj.dev/docs/components/resizable

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { FileCode2, Files, GitBranch, Search, Settings, TerminalSquare } from 'lucide-react'
import { Badge, Button, ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@youj/react'

const NAV = [
  { icon: Files, label: 'Explorer', active: true },
  { icon: Search, label: 'Search' },
  { icon: GitBranch, label: 'Source control', badge: '3' },
  { icon: Settings, label: 'Settings' },
]

const CODE = `export function App({ sprint }: Props) {
  const [cards, setCards] = useState(sprint.cards)
  return (
    <YoujProvider>
      <Board cards={cards} onMove={save} />
    </YoujProvider>
  )
}`

export default function ResizableDemo() {
  const [collapsed, setCollapsed] = useState(false)

return (
    <div className="h-[400px] w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-surface shadow-sm">
      <ResizablePanelGroup orientation="horizontal">
        {/* Dragged past its minimum, the sidebar snaps shut to an icon rail. */}
        <ResizablePanel
          id="sidebar"
          defaultSize="28%"
          minSize="10rem"
          maxSize="45%"
          collapsible
          collapsedSize="3rem"
          onCollapsedChange={setCollapsed}
          className="bg-transparent"
        >
          <nav aria-label="Workspace" className="flex h-full flex-col gap-0.5 p-1.5">
            {NAV.map(({ icon: Icon, label, active, badge }) => (
              <Button
                key={label}
                variant="ghost"
                size={collapsed ? 'icon-sm' : 'sm'}
                aria-label={collapsed ? label : undefined}
                aria-current={active ? 'page' : undefined}
                className={collapsed ? 'mx-auto' : 'justify-start aria-[current=page]:bg-hover aria-[current=page]:text-fg'}
              >
                <Icon />
                {!collapsed && <span className="truncate">{label}</span>}
                {!collapsed && badge && (
                  <Badge variant="secondary" className="ms-auto">
                    {badge}
                  </Badge>
                )}
              </Button>
            ))}
          </nav>
        </ResizablePanel>
        <ResizableHandle aria-label="Resize sidebar" />
        <ResizablePanel id="main" minSize="40%">
          <ResizablePanelGroup orientation="vertical">
            <ResizablePanel id="editor" defaultSize="66%" minSize="25%">
              <div className="flex h-full min-w-0 flex-col">
                <div className="flex h-9 shrink-0 items-center gap-1.5 border-b border-line px-3 text-ui-sm text-fg">
                  <FileCode2 className="size-3.5 text-accent-text" />
                  app.tsx
                </div>
                <pre className="min-h-0 flex-1 overflow-auto p-3 font-mono text-ui-sm leading-6 whitespace-pre text-fg">{CODE}</pre>
              </div>
            </ResizablePanel>
            <ResizableHandle withHandle aria-label="Resize terminal" />
            <ResizablePanel id="terminal" defaultSize="34%" minSize="4rem" collapsible>
              <div className="flex h-full min-h-0 flex-col">
                <div className="flex h-8 shrink-0 items-center gap-2 border-b border-line px-3 text-ui-sm text-fg-muted">
                  <TerminalSquare className="size-3.5" />
                  <span className="font-medium text-fg">Terminal</span>
                  pnpm dev
                </div>
                <p className="p-3 font-mono text-ui-sm text-fg-muted">
                  <span className="text-success-text">✓</span> Ready in 412ms
                </p>
              </div>
            </ResizablePanel>
          </ResizablePanelGroup>
        </ResizablePanel>
      </ResizablePanelGroup>
    </div>
  )
}
```

An editor workspace: a sidebar that snaps shut to an icon rail when dragged past its minimum, beside a code panel and a terminal.

A `collapsible` panel snaps shut when it's dragged below its `minSize`, to `collapsedSize` (zero by default), and snaps open again when dragged back. Enter on its separator collapses or restores it. `onCollapsedChange` tells you when it changes, and the panel carries `data-collapsed` while shut, so what's inside can switch to a compact layout, like the demo's icon rail.

### Vertical

```tsx
'use client'

import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@youj/react'

export default function ResizableVertical() {
  return (
    <div className="h-[320px] w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <ResizablePanelGroup orientation="vertical">
        <ResizablePanel defaultSize="60%" minSize="20%" maxSize="80%">
          <div className="grid h-full place-items-center text-ui text-fg-muted">Preview</div>
        </ResizablePanel>
        <ResizableHandle withHandle aria-label="Resize console" />
        <ResizablePanel minSize="20%">
          <div className="grid h-full place-items-center text-ui text-fg-muted">Console</div>
        </ResizablePanel>
      </ResizablePanelGroup>
    </div>
  )
}
```

A vertical group with a grip on its separator.

`orientation="vertical"` stacks the panels. `withHandle` adds a grip to the separator, for layouts where the line alone doesn't read as something to drag. Its dots fuse into bars while it's held.

### Persisting a layout

```tsx
'use client'

import { Fragment, useEffect, useState } from 'react'
import { Button, ResizableHandle, ResizablePanel, ResizablePanelGroup, type ResizableLayout } from '@youj/react'

const KEY = 'mail:layout'
const PANELS = ['inbox', 'thread', 'details'] as const

function readLayout(): ResizableLayout | undefined {
  try {
    const raw = localStorage.getItem(KEY)
    return raw ? (JSON.parse(raw) as ResizableLayout) : undefined
  } catch {
    return undefined
  }
}

export default function ResizablePersisted() {
  const [layout, setLayout] = useState<ResizableLayout>()
  // Storage is read after hydration, so the server and first client render agree; the group mounts with what was saved.
  const [ready, setReady] = useState(false)
  useEffect(() => {
    setLayout(readLayout())
    setReady(true)
  }, [])

return (
    <div className="flex h-[300px] w-full max-w-2xl flex-col gap-3">
      <div className="flex items-center gap-2 text-ui-sm text-fg-muted">
        Saved
        <code className="rounded-sm bg-band px-1.5 py-0.5 font-mono text-fg">
          {layout ? Object.entries(layout).map(([id, size]) => `${id} ${size.toFixed(0)}%`).join(' · ') : 'nothing yet'}
        </code>
        <Button
          variant="ghost"
          size="xs"
          className="ms-auto"
          onClick={() => {
            try {
              localStorage.removeItem(KEY)
            } catch {
              // Storage is blocked: there's nothing to forget.
            }
            setLayout(undefined)
          }}
        >
          Forget
        </Button>
      </div>
      <div className="min-h-0 flex-1 overflow-hidden rounded-xl border border-line bg-surface">
        {/* onLayoutChanged fires once a drag or key press settles, not on every pointer move. */}
        {ready && (
          <ResizablePanelGroup
            orientation="horizontal"
            defaultLayout={layout}
            onLayoutChanged={(next) => {
              setLayout(next)
              try {
                localStorage.setItem(KEY, JSON.stringify(next))
              } catch {
                // Storage is blocked: the layout just isn't remembered.
              }
            }}
          >
            {PANELS.map((id, i) => (
              <Fragment key={id}>
                {i > 0 && <ResizableHandle withHandle />}
                <ResizablePanel id={id} minSize="15%">
                  <div className="grid h-full place-items-center text-ui text-fg-muted capitalize">{id}</div>
                </ResizablePanel>
              </Fragment>
            ))}
          </ResizablePanelGroup>
        )}
      </div>
    </div>
  )
}
```

A layout that is saved and comes back after a reload.

`onLayoutChanged` fires once a drag or key press settles, not on every pointer move, so it's safe to save from. Pass the saved layout back as `defaultLayout`. Resize the panels, reload the page and they come back as you left them.

Read storage after hydration, as the example does, so the server and the first client render agree.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add resizable
```

It brings `icon-grip`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

It's shadcn's resizable on react-resizable-panels 4, which installs with it and owns the behavior: pointer and touch drags, limits, collapsing and the keyboard separator.

Use resizable panels for workspaces where people decide how much room each part gets: an editor and its terminal, a mail list and its reading pane, a board and a detail panel. Drag the sidebar past its minimum and it snaps shut to an icon rail. For a sidebar that opens and closes but never resizes, use the [Sidebar](https://www.youj.dev/docs/components/sidebar). For content that overflows a fixed box, use a [Scroll Area](https://www.youj.dev/docs/components/scroll-area).

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@youj/react'

export function Mail() {
  return (
    <ResizablePanelGroup orientation="horizontal">
      <ResizablePanel id="list" defaultSize="32%" minSize="16rem">
        <MessageList />
      </ResizablePanel>
      <ResizableHandle aria-label="Resize message list" />
      <ResizablePanel id="thread" minSize="40%">
        <Thread />
      </ResizablePanel>
    </ResizablePanelGroup>
  )
}
```

The group fills its parent, so give the parent a height. Sizes take pixels as numbers, or strings in `%`, `px` or `rem`. Groups nest: put a vertical group inside a panel of a horizontal one, as the demo's editor and terminal do.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  | Fires when a collapsible panel collapses or re-opens (by drag, keyboard or the imperative API). |

Also takes the props of `ResizablePrimitive.PanelProps`.

#### ResizableHandle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `withHandle` | `boolean` |  | Show a grip on the line. Use it where the separator isn't otherwise obvious. |

Also takes the props of `ResizablePrimitive.SeparatorProps`.

`ResizablePanelGroup` takes react-resizable-panels' `Group` props: `orientation`, `defaultLayout`, `onLayoutChange`, `onLayoutChanged` and `groupRef`. `ResizablePanel` also takes the library's `Panel` props, such as `defaultSize`, `minSize`, `maxSize`, `collapsible`, `collapsedSize` and `panelRef`, whose handle (`ResizablePanelHandle`) can `collapse()`, `expand()` and `resize()` from code.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Keyboard and imperative resize | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the panels glide (`flex-grow`), including Enter to collapse or restore |
| Pointer drag |  | pointer-driven | follows the pointer exactly, snap included |
| Separator wakes | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the 1px line grows a 3px rail after a beat of hover, so crossing it doesn't flash |
| Dragged or focused | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the rail turns the ring color at once |
| Grip | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | scales to 1.1 while held, and its dots fuse into bars (GripIcon) |

**Reduced motion:** Every resize is instant, and the grip doesn't scale while held.

#### Reduced motion

Keyboard, Enter and imperative resizes jump to their new sizes, and the grip holds its size while held. Dragging is unchanged, because it follows the pointer either way.

### Accessibility

- Each separator is a focusable `role="separator"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`, and an orientation. Name it with `aria-label` ("Resize sidebar") when its purpose isn't obvious from the layout.
- Arrow keys resize in 5% steps, Home and End go to the limits, and Enter collapses or restores a collapsible panel. F6 moves to the next separator.
- A double-click on the separator resets the panels to their default sizes.
- The visible line is 1px, but the hit area is 27px wide, and 37px on touch screens.
- Focus shows as the accent rail, the same as a drag.

---

# Inspector Panel

> One property group of a design tool's side panel: a header with its switches and actions, and rows of fields.

Source: https://www.youj.dev/docs/components/inspector-panel

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ColorOpacityField, InspectorPanel, InspectorRow, ScrubNumberField } from '@youj/react'

const TYPES = [
  { value: 'drop', label: 'Drop shadow' },
  { value: 'inner', label: 'Inner shadow' },
]

export default function InspectorPanelDemo() {
  const [type, setType] = useState('drop')
  const [enabled, setEnabled] = useState(true)
  const [visible, setVisible] = useState(true)
  return (
    <div className="w-full max-w-sm">
      <InspectorPanel
        title={TYPES.find((t) => t.value === type)!.label}
        types={TYPES}
        type={type}
        onTypeChange={setType}
        enabled={enabled}
        onEnabledChange={setEnabled}
        visible={visible}
        onVisibleChange={setVisible}
        onAdd={() => {}}
        onRemove={() => {}}
      >
        <InspectorRow label="Position">
          <ScrubNumberField size="sm" aria-label="X" label="X" defaultValue={0} />
          <ScrubNumberField size="sm" aria-label="Y" label="Y" defaultValue={8} />
        </InspectorRow>
        <InspectorRow label="Blur">
          <ScrubNumberField size="sm" aria-label="Blur" label="B" defaultValue={24} min={0} />
        </InspectorRow>
        <InspectorRow label="Color">
          <ColorOpacityField size="sm" aria-label="Color" defaultValue={{ color: '#1d2a6b', opacity: 45 }} />
        </InspectorRow>
      </InspectorPanel>
    </div>
  )
}
```

A shadow group with every part of the header.

The header holds, from the left: a checkbox that switches the group on or off, the title (a menu when you give it `types`), and on the right an eye, a plus, a trash and a chevron. Each appears when its props are given. Switched off, the body dims and every field in it is disabled. The chevron folds the body away.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add inspector-panel
```

It brings `button`, `checkbox`, `collapsible`, `dropdown-menu`, `icon-chevron-down`, `icon-eye`, `icon-plus`, `icon-trash`, `use-controllable-state`, `youj-core`, `youj-labels-inspector`, `youj-presets`, `youj-ui-core` with it.

The copy is 27 registry items, about 9,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `checkbox`, `collapse`, `collapsible`, `dropdown-menu`, `field`, `icon-check`, `icon-chevron-down`, `icon-chevron-right`, `icon-engine` and 10 more.

Use it to build the side panel of an editor: one panel per property group, stacked. The body is rows; a row is a label on the left and one or two fields on a two-column grid. [Scrub Number Field](https://www.youj.dev/docs/components/scrub-number-field) and [Color Opacity Field](https://www.youj.dev/docs/components/color-opacity-field) are made for it, and any other field fits. For the whole panel with a live preview, see the [Effects inspector](https://www.youj.dev/docs/blocks/forms-and-inputs#effects-inspector) block.

```tsx
import { InspectorPanel, InspectorRow, ScrubNumberField } from '@youj/react'

export function BlurPanel({ blur, onBlur }: { blur: number; onBlur: (blur: number) => void }) {
  return (
    <InspectorPanel title="Layer blur" enabled onEnabledChange={() => {}} onRemove={() => {}}>
      <InspectorRow label="Amount">
        <ScrubNumberField size="sm" aria-label="Amount" label="A" unit="px" min={0} value={blur} onValueChange={onBlur} />
      </InspectorRow>
    </InspectorPanel>
  )
}
```

The state is yours: `enabled`, `visible` and `type` are controlled, and `open` follows `defaultOpen` until you control it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` |  | The group's name. It names the section, and the remove button ("Remove Drop shadow"). |
| `enabled` | `boolean` |  | The checkbox in front of the title (controlled). Leave it out for no checkbox. |
| `onEnabledChange` | `(enabled: boolean) => void` |  |  |
| `types` | `InspectorPanelType[]` |  | Turns the title into a menu of these kinds. |
| `type` | `string` |  | The chosen kind's value. |
| `onTypeChange` | `(type: string) => void` |  |  |
| `visible` | `boolean` |  | The eye's state (controlled): false is hidden. Leave it out for no eye. |
| `onVisibleChange` | `(visible: boolean) => void` |  |  |
| `onAdd` | `() => void` |  | Shows a plus button. |
| `onRemove` | `() => void` |  | Shows a trash button. |
| `actions` | `ReactNode` |  | Header actions placed before the eye, plus and trash buttons. |
| `open` | `boolean` |  | Whether the body is open (controlled). |
| `defaultOpen` | `boolean` | `true` | Whether the body starts open (uncontrolled). |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `children` | `ReactNode` |  |  |

Also takes the props of `ComponentProps<'div'>`.

#### Inspector Row

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  | The row's name, on the left. |
| `children` (required) | `ReactNode` |  | One or two fields: two share the width. |

Also takes the props of `ComponentProps<'div'>`.

#### Data attributes

The panel carries `data-slot="inspector-panel"`, `data-yj-enabled` and `data-yj-visible` (`true` or `false`, when their props are given) and Base UI's `data-open` while the body is open. The header is `inspector-panel-header`, the type menu's trigger `inspector-panel-type`, and the body `inspector-panel-body`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fold and unfold | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the body eases between zero and its height while its content fades |
| Switched off | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the body dims |

**Reduced motion:** The body opens and closes at once, and dims without a fade.

#### Reduced motion

Folding and dimming happen at once; the chevron turns over without a spring.

### Accessibility

- The panel is a `section` named by its title. A row's fields are a `group` named by the row's label.
- The checkbox is named "Enable" followed by the title. The eye says what it will do ("Hide", or "Show" while hidden) and is a toggle (`aria-pressed`). The plus is "Add", the trash "Remove" and the title, and the chevron "Collapse" or "Expand" with `aria-expanded`. All of these are translated through the labels.
- With `types`, the title is a menu button named "Change type" and the title. Arrow keys move through the kinds, Enter picks one and Escape closes it.
- Switched off, the body is a disabled `fieldset`, so nothing in it is reachable until the checkbox is on again.

---

# Aspect Ratio

> Keep media at a fixed aspect ratio and reserve its space before it loads.

Source: https://www.youj.dev/docs/components/aspect-ratio

## Examples

### Demo

```tsx
'use client'

import { MusicIcon, PlayIcon } from '@youj/icons'
import { AspectRatio, Skeleton } from '@youj/react'

export default function AspectRatioDemo() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-[2fr_1fr_1fr] items-start gap-4">
      <figure className="flex flex-col gap-2">
        <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg border border-line">
          <div className="grid size-full place-items-center bg-linear-to-br from-accent/30 via-band to-canvas">
            <span className="grid size-12 place-items-center rounded-full bg-canvas text-fg shadow-md">
              <PlayIcon size={20} />
            </span>
          </div>
        </AspectRatio>
        <figcaption className="text-ui-sm text-fg-muted">16 / 9 · Video</figcaption>
      </figure>
      <figure className="flex flex-col gap-2">
        <AspectRatio ratio={1} className="overflow-hidden rounded-lg border border-line">
          <div className="grid size-full place-items-center bg-linear-to-tr from-fg/15 to-band text-fg-muted">
            <MusicIcon size={24} />
          </div>
        </AspectRatio>
        <figcaption className="text-ui-sm text-fg-muted">1 · Cover</figcaption>
      </figure>
      <figure className="flex flex-col gap-2">
        {/* The box holds its shape before anything loads, so nothing below it moves. */}
        <AspectRatio ratio={4 / 5} className="overflow-hidden rounded-lg">
          <Skeleton className="size-full rounded-none" />
        </AspectRatio>
        <figcaption className="text-ui-sm text-fg-muted">4 / 5 · Loading</figcaption>
      </figure>
    </div>
  )
}
```

Placeholders for media at different ratios, each captioned with its ratio.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add aspect-ratio
```

It brings `youj-ui-core` with it.

Use an aspect ratio around images, video, embeds and their placeholders in fluid layouts. The box reserves its height from its width before the media arrives, so nothing below it jumps when it does.

```tsx
import { AspectRatio } from '@youj/react'

export function Thumbnail() {
  return (
    <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg">
      <img src="/keynote.jpg" alt="The keynote stage" className="size-full object-cover" />
    </AspectRatio>
  )
}
```

`ratio` is width over height as a number: `16 / 9`, `1`, `4 / 5`. It's the CSS `aspect-ratio` property, so it needs no JavaScript and renders the same on the server. Give the child `size-full` (and `object-cover` for media) to fill the box. The API matches shadcn/ui's Aspect Ratio.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` (required) | `number` |  | Width over height, as a number: `16 / 9`, `1`, `4 / 5`. |

### Reduced motion

Aspect Ratio is static. Nothing changes under reduced motion.

### Accessibility

- The box is a plain `div` with no role. Give the media inside it its own text alternative: `alt` on an image, a `title` on an iframe.

---

# Typography

> Use consistent headings, body text, quotes, code and lists.

Source: https://www.youj.dev/docs/components/typography

## Examples

### Demo

```tsx
'use client'

import {
  TypographyBlockquote,
  TypographyH1,
  TypographyH2,
  TypographyH3,
  TypographyInlineCode,
  TypographyLead,
  TypographyList,
  TypographyMuted,
  TypographyP,
} from '@youj/react'

export default function TypographyDemo() {
  return (
    <article className="w-full max-w-xl">
      <TypographyMuted>Changelog · September 2026</TypographyMuted>
      <TypographyH1 className="mt-2">Deploys that explain themselves</TypographyH1>
      <TypographyLead className="mt-3">Every deploy now carries its own story: what changed, who approved it, and how to take it back.</TypographyLead>
      <TypographyH2>What’s new</TypographyH2>
      <TypographyP>
        The deploy page opens on a timeline. Each step records its duration and its logs. Read the <a href="#guide">migration guide</a> if you
        pinned the old layout.
      </TypographyP>
      <TypographyList>
        <li>Build output streams as it happens, with warnings folded.</li>
        <li>
          Rollbacks keep their environment: <TypographyInlineCode>deploy rollback --keep-env</TypographyInlineCode>.
        </li>
      </TypographyList>
      <TypographyH3>Upgrading</TypographyH3>
      <TypographyList ordered>
        <li>Update the CLI to 4.2 or later.</li>
        <li>Run one deploy from a clean checkout.</li>
      </TypographyList>
      <TypographyBlockquote>“We cut our incident reviews in half. The deploy already told us what happened.”</TypographyBlockquote>
    </article>
  )
}
```

A changelog entry set with the typography components.

### The set

```tsx
'use client'

import type { ReactNode } from 'react'
import {
  TypographyH1,
  TypographyH2,
  TypographyH3,
  TypographyH4,
  TypographyInlineCode,
  TypographyLarge,
  TypographyLead,
  TypographyMuted,
  TypographyP,
  TypographySmall,
} from '@youj/react'

const SCALE: [string, ReactNode][] = [
  ['H1', <TypographyH1 key="h1">Taxing Laughter</TypographyH1>],
  ['H2', <TypographyH2 key="h2">The People of the Kingdom</TypographyH2>],
  ['H3', <TypographyH3 key="h3">The Joke Tax</TypographyH3>],
  ['H4', <TypographyH4 key="h4">People stopped telling jokes</TypographyH4>],
  ['P', <TypographyP key="p">The king, seeing how much happier his subjects were, realized the error of his ways.</TypographyP>],
  ['Lead', <TypographyLead key="lead">A modal dialog that interrupts the user with important content.</TypographyLead>],
  ['Large', <TypographyLarge key="large">Are you absolutely sure?</TypographyLarge>],
  ['Small', <TypographySmall key="small">Email address</TypographySmall>],
  ['Muted', <TypographyMuted key="muted">Enter your email address.</TypographyMuted>],
  ['InlineCode', <TypographyInlineCode key="code">@youj/react</TypographyInlineCode>],
]

export default function TypographyScale() {
  return (
    <div className="grid w-full max-w-xl grid-cols-[6.5rem_minmax(0,1fr)] items-baseline gap-x-5 gap-y-5">
      {SCALE.map(([name, node]) => (
        <div key={name} className="contents">
          <span className="font-mono text-ui-xs text-fg-muted">{name}</span>
          {/* The set's own top margins are for running text; a specimen sits flush. */}
          <div className="min-w-0 [&>*]:mt-0!">{node}</div>
        </div>
      ))}
    </div>
  )
}
```

The set as specimens, each name beside a sample.

| Component | Element | For |
| --- | --- | --- |
| `TypographyH1`–`TypographyH4` | `h1`–`h4` | Page and section titles. Plain headings, with no rule: add `border-b border-line pb-2` to a section title that wants one. |
| `TypographyP` | `p` | Body copy: 15px on a 28px line height. |
| `TypographyLead` | `p` | The paragraph under a title, larger and quieter. |
| `TypographyLarge` | `div` | Emphasis that isn't a heading: a price, a callout's first line. |
| `TypographySmall` | `small` | A label or caption that still reads as content. |
| `TypographyMuted` | `p` | Helper copy and metadata. |
| `TypographyBlockquote` | `blockquote` | A quotation, set off by a rule on the start side. |
| `TypographyInlineCode` | `code` | Code inside a sentence. For blocks, use [Code Block](https://www.youj.dev/docs/components/code-block). |
| `TypographyList` | `ul`, or `ol` with `ordered` | Square markers, or numbers counted in mono. |

Vertical rhythm comes from a top margin on everything but the first child, as in shadcn, so a heading or paragraph that opens a card sits flush. Links inside `P`, `Lead`, `Muted`, `Blockquote` and `List` underline in a quiet tint of the accent that fills in on hover.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add typography
```

It brings `youj-presets`, `youj-ui-core` with it.

Use the typography set for text you write into a page by hand: a changelog entry, an empty state's explanation, a settings section's intro, a marketing page. It follows [shadcn's typography](https://ui.shadcn.com/docs/components/typography), but as components you import rather than class lists you copy, so every page picks up the theme's type and a fix lands everywhere.

For long-form content that comes from Markdown or a CMS, style the container instead of wrapping every element. The docs site does that with a `.prose` stylesheet built on the same values.

```tsx
import { TypographyH1, TypographyLead, TypographyList, TypographyP } from '@youj/react'

export function Intro() {
  return (
    <>
      <TypographyH1>Deploys that explain themselves</TypographyH1>
      <TypographyLead>Every deploy now carries its own story.</TypographyLead>
      <TypographyP>
        Read the <a href="/guide">migration guide</a> if you pinned the old layout.
      </TypographyP>
      <TypographyList>
        <li>Build output streams as it happens.</li>
        <li>Rollbacks keep their environment.</li>
      </TypographyList>
    </>
  )
}
```

Each piece renders the element it names (`h1` to `h4`, `p`, `blockquote`, `code`, `ul` or `ol`) and takes that element's props, so `id`, `className` and ARIA pass straight through. Pick the heading for the outline, not the size: restyle it with `className` if the page needs a different look.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Eyebrow

`Eyebrow` is the short label over a figure, a group or a section: "Month-to-date spend", "Included usage", "Status". It's a `span` of small muted text, and your classes win, so a label you move to it keeps the look it had. Naming it is what lets a [look](https://www.youj.dev/docs/looks) give every label the same voice: in Bezel they're mono capitals. Pass `render` for another element, such as a section's heading.

An `Eyebrow` is inline and carries no margin, and a heading that opens a container sits flush, so the two touch until you space them. Stack them with a gap, as a hero does:

```tsx
<div className="flex flex-col gap-2">
  <Eyebrow>New in 2.0</Eyebrow>
  <TypographyH1>Deploys that explain themselves</TypographyH1>
</div>
```

```tsx
import { Eyebrow } from '@youj/react'

<Eyebrow>Month-to-date spend</Eyebrow>
<Eyebrow render={<h2 id="usage" />} className="text-ui-lg font-semibold text-fg">
  Included usage
</Eyebrow>
```

### Props

#### TypographyList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ordered` | `false` |  |  |

Every other piece takes the props of its element.

### Motion

Typography doesn't move. The one exception is a link's underline color, which eases to the accent on hover over `fast` with the `standard` ease.

#### Reduced motion

Nothing changes: a link's underline color change isn't motion.

### Accessibility

- The headings are real heading elements, so the page outline and screen-reader heading navigation follow them. Don't skip levels for looks; restyle instead.
- `TypographyList` is a real `ul` or `ol`, so most screen readers announce it as a list with its item count. Safari with VoiceOver drops list semantics from lists without visible markers, so pass `role="list"` where that matters. The square markers and mono numbers are drawn with CSS and aren't read.
- Links keep the focus ring every control has.
- Body and muted text meet WCAG AA contrast on the theme's backgrounds, in both modes.

---

# Code Block

> Display highlighted code with a file name or language, optional line numbers and a copy button.

Source: https://www.youj.dev/docs/components/code-block

## Examples

### Demo

```tsx
'use client'

import { CodeBlock } from '@youj/react'

const CODE = `'use client'

import { AsyncButton } from '@youj/react'

export function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
  // Speed and reduced motion reach every animation
  return (
    <AsyncButton onAction={onSave} pendingLabel="Saving…">
      Save changes
    </AsyncButton>
  )
}`

export default function CodeBlockDemo() {
  return (
    <div className="w-full max-w-2xl">
      <CodeBlock code={CODE} language="tsx" filename="components/save-button.tsx" lineNumbers />
    </div>
  )
}
```

A TSX snippet with a filename and line numbers.

The copy button copies `code` exactly. Its name and tooltip are `copyLabel`, "Copy code" by default. Pass `actions` to put your own controls in its place, such as a run button next to a copy button of your own.

### Languages

```tsx
'use client'

import { CodeBlock } from '@youj/react'

export default function CodeBlockLanguages() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <CodeBlock code="pnpm dlx @youj/cli@latest init" language="sh" />
      <CodeBlock
        language="diff"
        code={`- import { Check } from 'lucide-react'
+ import { CheckIcon } from '@youj/icons'`}
      />
      <CodeBlock
        language="json"
        filename="components.json"
        code={`{
  "style": "base-nova",
  "registries": { "@youj": "https://www.youj.dev/r/{name}.json" }
}`}
      />
    </div>
  )
}
```

Three blocks: a shell command, a diff and a JSON file.

Highlighting is a small built-in tokenizer: TypeScript and JavaScript (with JSX), C-like languages (Go, Rust, Java, C#, Swift, Kotlin, PHP), Python, Ruby, shell, JSON, CSS, HTML and XML, SQL, YAML and diffs. Anything else shows as plain text. It produces tokens, never HTML, so code from a user or a model can't inject markup. The colors are theme tokens, so they follow the theme in both modes.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add code-block
```

It brings `async-feedback`, `button`, `icon-copy`, `scroll-area`, `tooltip`, `youj-core`, `youj-labels-code-block`, `youj-ui-core` with it.

The copy is 17 registry items, about 8,300 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `button`, `icon-copy`, `icon-engine`, `icon-loader-ring`, `morph-label`, `scroll-area`, `spinner`, `tooltip`.

Use a code block to show code someone will read or copy: an install command, a config file, a snippet in a changelog or an empty state. It's the same block the [Chat](https://www.youj.dev/docs/components/chat) renders for fenced code in a model's answer. For code inside a sentence, use [Typography](https://www.youj.dev/docs/components/typography)'s `TypographyInlineCode`.

```tsx
import { CodeBlock } from '@youj/react'

export function InstallCommand() {
  return <CodeBlock code="pnpm dlx @youj/cli@latest init" language="sh" />
}
```

The header shows `filename` when you pass one, with the `language` value beside it as written (`ts`, `sh`), or else that value alone, or `text`. Long lines scroll sideways instead of wrapping, so indentation stays true; the scrollbar appears only when it's needed. `lineNumbers` adds a gutter that holds still while the code scrolls.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` (required) | `string` |  | The source to show and copy. |
| `language` | `string` | `''` | Language for highlighting and the header label: `ts`, `tsx`, `js`, `json`, `css`, `html`, `sh`, `py`, `go`, `rust`, `sql`, `yaml`, `diff`… Anything else is plain text. |
| `filename` | `string` |  | A file name for the header, in place of the language. |
| `lineNumbers` | `boolean` | `false` | Number the lines in a gutter that stays put while the code scrolls. |
| `copyLabel` | `string` | `"Copy code"` | The copy button's name and tooltip. |
| `actions` | `ReactNode` |  | Replaces the header's copy button, e.g. with your own actions. |
| `tail` | `ReactNode` |  | Drawn at the end of the code, inside it: the caret of a streaming answer, say. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the copy button plays `tap` and a copy `success`. `false` keeps it silent. |

Also takes the props of `ComponentProps<'figure'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Copied |  | the copy icon’s own choreography | the back sheet tucks behind the front one and a check is written on it |
| Back to rest |  | 3 × deliberate | after a beat |

**Reduced motion:** The icon swaps to the check at once and back again, with no drawing.

#### Reduced motion

The copy icon swaps straight to its check and back. Everything else is the same.

### Accessibility

- The block is a `figure` whose `figcaption` holds the file name or language and the copy button.
- The code sits in a scroll region named by the file name, or "TypeScript code" and so on, so a keyboard user can scroll a long line.
- The copy button is named by `copyLabel`. Its tooltip says "Copied" after a copy, and the result is announced politely. A clipboard that refuses (no permission, an insecure page) is announced as "Couldn’t copy", not faked.
- Line numbers are decorative (`aria-hidden`) and can't be selected, so copying by hand takes only the code.

---

# Diff Viewer

> Show the difference between two versions of a file, unified or side by side, with what changed inside each line marked.

Source: https://www.youj.dev/docs/components/diff-viewer

## Examples

### Demo

```tsx
'use client'

import { DiffViewer } from '@youj/react'

const BEFORE = `name: deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-22.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test
`

const AFTER = `name: deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test -- --coverage
`

export default function DiffViewerDemo() {
  return (
    <div className="w-full max-w-2xl">
      <DiffViewer before={BEFORE} after={AFTER} filename=".github/workflows/deploy.yml" language="yaml" />
    </div>
  )
}
```

A CI workflow moved to a newer runner and Node, and run on pull requests too.

Pass `before` and `after` and the diff is computed in the component (Myers' algorithm, line by line). Inside each pair of removed and added lines, the words that changed take a stronger tint. Press J and K (or Alt+↓ and Alt+↑) anywhere in the diff to step through the changes.

### Split view

```tsx
'use client'

import { DiffViewer } from '@youj/react'

const BEFORE = `export async function GET(request: Request) {
  const session = await auth()
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

const { searchParams } = new URL(request.url)
  const page = Number(searchParams.get('page') ?? 1)
  const limit = 20

const invoices = await db.invoice.findMany({
    where: { teamId: session.teamId },
    skip: (page - 1) * limit,
    take: limit,
  })
  return NextResponse.json({ invoices, page })
}
`

const AFTER = `const query = z.object({
  page: z.coerce.number().int().min(1).default(1),
  status: z.enum(['draft', 'open', 'paid', 'void']).optional(),
})

export async function GET(request: Request) {
  const session = await auth()
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

const { searchParams } = new URL(request.url)
  const { page, status } = query.parse(Object.fromEntries(searchParams))
  const limit = 25

const invoices = await db.invoice.findMany({
    where: { teamId: session.teamId, ...(status && { status }) },
    skip: (page - 1) * limit,
    take: limit,
  })
  return NextResponse.json({ invoices, page, status })
}
`

export default function DiffViewerSplit() {
  return (
    <div className="w-full max-w-4xl">
      <DiffViewer before={BEFORE} after={AFTER} filename="app/api/invoices/route.ts" language="ts" defaultView="split" />
    </div>
  )
}
```

One file of a pull request, side by side: before on one side, after on the other, each removal paired with its addition.

The split view always wraps long lines, so both sides stay in view. In the unified view, the wrap button chooses between wrapping and scrolling sideways.

### Patch input

```tsx
'use client'

import { DiffViewer } from '@youj/react'

const PATCH = `diff --git a/src/lib/format.ts b/src/lib/format.ts
--- a/src/lib/format.ts
+++ b/src/lib/format.ts
@@ -12,7 +12,8 @@ const units = ['B', 'KB', 'MB', 'GB', 'TB']
 export function formatBytes(bytes: number) {
   if (bytes === 0) return '0 B'
-  const i = Math.floor(Math.log(bytes) / Math.log(1024))
-  return (bytes / Math.pow(1024, i)).toFixed(1) + ' ' + units[i]
+  const i = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)))
+  const value = bytes / 1024 ** i
+  return \`\${value.toFixed(value < 10 && i > 0 ? 1 : 0)} \${units[i]}\`
 }

export function formatDuration(ms: number) {
@@ -48,6 +49,6 @@ export function formatRelative(date: Date, now: Date) {
   const seconds = Math.round((date.getTime() - now.getTime()) / 1000)
   const unit = pickUnit(seconds)
-  return rtf.format(seconds / UNIT_SECONDS[unit], unit)
+  return rtf.format(Math.round(seconds / UNIT_SECONDS[unit]), unit)
 }
`

export default function DiffViewerPatch() {
  return (
    <div className="w-full max-w-3xl">
      <DiffViewer patch={PATCH} language="ts" />
    </div>
  )
}
```

A unified diff as `git diff` prints it. Each hunk opens on its `@@` header, and the file name comes from the patch.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add diff-viewer
```

It brings `async-feedback`, `button`, `code-block`, `icon-chevron-down`, `icon-chevron-up`, `icon-chevrons-up-down`, `icon-copy`, `icon-file-code`, `icon-wrap-text`, `segmented-control`, `toggle`, `tooltip`, `use-controllable-state`, `youj-core`, `youj-labels-diff-viewer`, `youj-presets`, `youj-ui-core` with it.

The copy is 29 registry items, about 10,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `button`, `code-block`, `icon-chevron-down`, `icon-chevron-up`, `icon-chevrons-up-down`, `icon-copy`, `icon-engine`, `icon-file-code`, `icon-loader-ring` and 10 more.

Use a diff viewer wherever someone reviews a change to code or config: a pull request, a deploy's changes, a config history, an AI edit waiting for approval. For a snippet that isn't a change, use [Code Block](https://www.youj.dev/docs/components/code-block).

```tsx
import { DiffViewer } from '@youj/react'

export function ConfigChange({ previous, current }: { previous: string; current: string }) {
  return <DiffViewer before={previous} after={current} filename="config/app.json" language="json" />
}
```

- **Two versions or a patch.** `before` and `after` are compared line by line. Line endings don't count (CRLF reads as LF), but a missing newline at the end of the file does, as in git. Or pass `patch`, a unified diff; only its first file is shown, and the lines between its hunks can't be opened because the patch doesn't carry them.
- **Highlighting** is CodeBlock's built-in tokenizer, so `language` takes the same values (`ts`, `tsx`, `json`, `yaml`, `css`, `py`, `go`…). It produces tokens, never HTML.
- **Unchanged lines** fold beyond `context` lines on each side of a change (3 by default) into a row that opens in place. `context={Infinity}` shows every line.
- **View and wrap** are `view`/`defaultView`/`onViewChange` and `wrap`/`defaultWrap`/`onWrapChange`, so an app can remember them.
- **Copy** copies `after`, or the patch when you passed one.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `before` | `string` |  | The old version of the file. With `after`; leave both out to pass a `patch`. |
| `after` | `string` |  | The new version of the file. |
| `patch` | `string` |  | A unified diff (`git diff` output) to show instead of `before`/`after`. Only its first file is shown, and the lines between hunks can't be opened. |
| `language` | `string` | `''` | Language for highlighting, as CodeBlock takes it: `ts`, `tsx`, `json`, `css`, `py`, `go`, `yaml`… Anything else is plain text. |
| `filename` | `string` |  | The file's path for the header. A patch names its own when this is left out. |
| `view` | `'unified' \| 'split'` |  | `unified` (one column, removals over additions) or `split` (before and after side by side), controlled. |
| `defaultView` | `'unified' \| 'split'` | `'unified'` | The view at first, uncontrolled. |
| `onViewChange` | `(view: DiffView) => void` |  |  |
| `wrap` | `boolean` |  | Wrap long lines instead of scrolling sideways, controlled. The split view always wraps. |
| `defaultWrap` | `boolean` | `false` | Wrap at first, uncontrolled. |
| `onWrapChange` | `(wrap: boolean) => void` |  |  |
| `context` | `number` | `3` | Unchanged lines kept on each side of a change; longer runs fold. `Infinity` shows every line. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the view switch, wrap toggle and copy sound as the rest of the kit does. `false` keeps it silent. |

Also takes the props of `ComponentProps<'figure'>`.

#### Data attributes

The root carries `data-yj-view` (`unified` or `split`) and `data-yj-wrap` when lines wrap. Each line's code cell carries `data-yj-line` (`add`, `del` or `context`), and the row of the change you stepped to carries `data-yj-current`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Step to a change |  | smooth scroll | the change glides to the middle of the view and an accent bar marks its first line |
| View switch | `spring.smooth` | 0.36s, bounce 0 | the segmented control’s indicator glides to the pressed view |
| Copied |  | 3 × deliberate | the copy icon’s check, then back to rest after a beat |

**Reduced motion:** Stepping jumps to the change, the view indicator moves at once and the copy icon swaps to its check.

#### Reduced motion

Every state shows at once; the diff reads the same.

### Accessibility

- The viewer is a `figure` named by the file name, and the diff is a table whose caption names the file and counts the additions and deletions.
- Each changed line reads its change and number first: "Added line 12: …", "Removed line 9: …". Line numbers and the +/− signs are decorative and can't be selected, so copying by hand takes only the code. In the split view, the columns are headed Before and After.
- The diff is a focusable region. J and K, or Alt+↓ and Alt+↑, step to the next and previous change (described on the region, and as `aria-keyshortcuts`); the header's position, "Change 3 of 7", is announced politely. Previous and Next change are buttons too.
- A folded run is a button, "12 unchanged lines"; opening it keeps focus in the diff.
- The view is a segmented control and wrap a toggle button, each named. Copy announces its result, and a refused clipboard says so.
- On a right-to-left page the header follows the page while the code stays left to right, as code does.

---

# Kbd

> Show keyboard keys and shortcuts as keycaps.

Source: https://www.youj.dev/docs/components/kbd

## Examples

### Demo

```tsx
'use client'

import { ArrowDownIcon, ArrowUpIcon, CornerDownLeftIcon } from '@youj/icons'
import { Kbd, KbdGroup } from '@youj/react'

const SHORTCUTS = [
  { label: 'Command menu', keys: ['⌘', 'K'] },
  { label: 'New deployment', keys: ['D'] },
  { label: 'Search logs', keys: ['/'] },
  { label: 'Toggle sidebar', keys: ['⌘', 'B'] },
  { label: 'Go to settings', keys: ['G', 'S'], sequence: true },
]

export default function KbdDemo() {
  return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-surface">
      <ul className="divide-y divide-line">
        {SHORTCUTS.map((shortcut) => (
          <li key={shortcut.label} className="flex items-center justify-between gap-4 px-4 py-2.5 text-ui text-fg">
            {shortcut.label}
            {/* Nested kbd elements are how HTML spells a key combination. */}
            <KbdGroup>
              {shortcut.keys.map((key, i) => (
                <span key={key} className="inline-flex items-center gap-1">
                  {shortcut.sequence && i > 0 && <span className="font-sans text-ui-xs text-fg-muted">then</span>}
                  <Kbd>{key}</Kbd>
                </span>
              ))}
            </KbdGroup>
          </li>
        ))}
      </ul>
      <div className="flex flex-wrap items-center gap-x-4 gap-y-1 border-t border-line bg-canvas px-4 py-2 text-ui-sm text-fg-muted">
        <span className="inline-flex items-center gap-1.5">
          <KbdGroup>
            <Kbd>
              <ArrowUpIcon aria-label="Up arrow" />
            </Kbd>
            <Kbd>
              <ArrowDownIcon aria-label="Down arrow" />
            </Kbd>
          </KbdGroup>
          navigate
        </span>
        <span className="inline-flex items-center gap-1.5">
          <Kbd>
            <CornerDownLeftIcon aria-label="Enter" />
          </Kbd>
          open
        </span>
        <span className="inline-flex items-center gap-1.5">
          <Kbd>esc</Kbd>
          close
        </span>
      </div>
    </div>
  )
}
```

A shortcut list with key combinations and sequences, and a footer of key hints.

### In buttons and tooltips

```tsx
'use client'

import { SearchIcon, SidebarIcon } from '@youj/icons'
import { Button, Kbd, KbdGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@youj/react'

export default function KbdInContext() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center justify-center gap-3">
        {/* Keycaps inside a button are a visual hint, so they stay out of its accessible name. */}
        <Button variant="outline" className="w-56 justify-start text-fg-muted">
          <SearchIcon />
          Search docs
          <KbdGroup aria-hidden className="ms-auto">
            <Kbd>⌘</Kbd>
            <Kbd>K</Kbd>
          </KbdGroup>
        </Button>

{/* In a tooltip: the keycaps restyle themselves for the tooltip's chip. */}
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Toggle sidebar" />}>
            <SidebarIcon />
          </TooltipTrigger>
          <TooltipContent>
            Toggle sidebar
            <KbdGroup>
              <Kbd>⌘</Kbd>
              <Kbd>B</Kbd>
            </KbdGroup>
          </TooltipContent>
        </Tooltip>

<Button>
          Deploy
          {/* shape: the shortcut rides inside the primary button, in its lettering, not as a key of its own */}
          <Kbd aria-hidden className="border-transparent bg-on-accent/15 youj-allow-tint text-on-accent shadow-none">D</Kbd>
        </Button>
      </div>
    </TooltipProvider>
  )
}
```

Keycaps inside a search button, a tooltip and a Deploy button.

Keycaps sit inside buttons and tooltips at the right size, and an icon inside a keycap shrinks to 12px. In a tooltip they restyle themselves for its chip, in both modes. Hover or focus the middle button to see one.

### In a sentence

```tsx
'use client'

import { TerminalIcon } from '@youj/icons'
import { Kbd, KbdGroup } from '@youj/react'

export default function KbdInline() {
  return (
    <div className="flex w-full max-w-md gap-3 rounded-xl border border-line bg-surface p-4">
      <span className="grid size-8 shrink-0 place-items-center rounded-md bg-band text-fg-muted">
        <TerminalIcon size={16} />
      </span>
      <div className="min-w-0">
        <p className="text-ui font-medium text-fg">Develop locally</p>
        {/* Keycaps sit on the text's baseline. A 24px line leaves room for them, so lines stay evenly spaced. */}
        <p className="mt-1 text-ui leading-6 text-fg-muted">
          Run <code className="rounded-sm bg-band px-1 py-0.5 font-mono text-ui-sm text-fg">youj dev</code> in
          your project. While it runs, press <Kbd>O</Kbd> to open the preview, <Kbd>R</Kbd> to restart with fresh
          environment variables, and{' '}
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <Kbd>C</Kbd>
          </KbdGroup>{' '}
          to stop.
        </p>
      </div>
    </div>
  )
}
```

Keycaps in a sentence of help text.

Keycaps sit on the text's baseline, so keys can go mid-sentence: in help text, onboarding tips and docs. A keycap is 20px tall, the height of a line of UI text. As a direct child of a paragraph, list item, table cell, quote or caption it trims its block margins, so a line with a key is no taller than one without; `leading-6` still gives the keycaps more air.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add kbd
```

It brings `youj-ui-core` with it.

Use `Kbd` wherever you name a key: a shortcut beside a command, a hint in a footer, a step in the docs. It's the right element for keyboard input, not a styled `code` or `span`. Don't use it for arbitrary labels or counts. Those are [Badges](https://www.youj.dev/docs/components/badge).

```tsx
import { Kbd, KbdGroup } from '@youj/react'

export function Shortcut() {
  return (
    <KbdGroup>
      <Kbd>⌘</Kbd>
      <Kbd>K</Kbd>
    </KbdGroup>
  )
}
```

A single key is a `Kbd`. A combination is a `KbdGroup` of `Kbd`s, which is nested `<kbd>` elements, the way HTML spells keys pressed together. For a sequence, like G then S, put the word between the keys, as in the demo.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Kbd

Takes the props of `ComponentProps<'kbd'>`.

#### KbdGroup

Takes the props of `ComponentProps<'kbd'>`.

### Reduced motion

Kbd is static. Nothing changes under reduced motion.

### Accessibility

- `Kbd` renders `<kbd>`, HTML's element for keyboard input. It ignores the pointer, so it never steals a click from the control around it.
- Symbols such as ⌘, ⌥ and ⇧ are read inconsistently. When the shortcut matters, write it out in the surrounding text, or give the icon inside a keycap an `aria-label`, as the arrow keys in the preview do.
- Inside a button, the keycaps are a hint, not part of the button's name. Mark them `aria-hidden`. When the shortcut really works, expose it with `aria-keyshortcuts` on the button.

---

# Avatar

> Show a person or team’s image, with initials while it loads or if it fails.

Source: https://www.youj.dev/docs/components/avatar

## Examples

### Demo

```tsx
'use client'

import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from '@youj/react'

/* Portraits drawn in place as SVG data URIs, so the example needs no network. */
function portrait(hueA: number, hueB: number) {
  const svg = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><defs><linearGradient id='g' x2='1' y2='1'><stop stop-color='hsl(${hueA} 70% 62%)'/><stop offset='1' stop-color='hsl(${hueB} 70% 42%)'/></linearGradient></defs><rect width='64' height='64' fill='url(#g)'/><circle cx='32' cy='26' r='11' fill='white' fill-opacity='.85'/><path d='M12 60c3-12 12-18 20-18s17 6 20 18z' fill='white' fill-opacity='.85'/></svg>`
  return `data:image/svg+xml,${encodeURIComponent(svg)}`
}

const REVIEWERS = [
  { name: 'Priya Raman', initials: 'PR', src: portrait(160, 200) },
  { name: 'Jonas Weber', initials: 'JW', src: portrait(200, 230) },
  { name: 'Sara Okafor', initials: 'SO', src: portrait(20, 350) },
]

export default function AvatarDemo() {
  return (
    <div className="flex w-full max-w-md items-center justify-between gap-4 rounded-xl border border-line bg-surface px-4 py-3">
      <div className="flex min-w-0 items-center gap-3">
        {/* The name is written out beside it, so this avatar and its status dot are decorative. */}
        <Avatar size="lg" aria-hidden>
          <AvatarImage src={portrait(230, 262)} alt="" />
          <AvatarFallback>AL</AvatarFallback>
          <AvatarBadge />
        </Avatar>
        <div className="min-w-0">
          <p className="truncate text-ui font-medium text-fg">Ana Lima</p>
          <p className="truncate text-ui-sm text-fg-muted">Online · Owner</p>
        </div>
      </div>
      <div className="flex shrink-0 items-center gap-2">
        <span className="text-ui-sm text-fg-muted max-sm:sr-only">Reviewers</span>
        <AvatarGroup>
          {REVIEWERS.map((person) => (
            <Avatar key={person.name} size="sm">
              {person.src && <AvatarImage src={person.src} alt={person.name} />}
              {/* Until an image loads, and when there is none, the initials stand in and carry the name. */}
              <AvatarFallback role="img" aria-label={person.name}>
                {person.initials}
              </AvatarFallback>
            </Avatar>
          ))}
          <AvatarGroupCount>
            <span aria-hidden>+4</span>
            <span className="sr-only">and 4 more</span>
          </AvatarGroupCount>
        </AvatarGroup>
      </div>
    </div>
  )
}
```

A member row with a large avatar and status dot, beside a small group of reviewers ending in a +4 count.

### Sizes and status

```tsx
'use client'

import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@youj/react'

function portrait(hueA: number, hueB: number) {
  const svg = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><defs><linearGradient id='g' x2='1' y2='1'><stop stop-color='hsl(${hueA} 70% 62%)'/><stop offset='1' stop-color='hsl(${hueB} 70% 42%)'/></linearGradient></defs><rect width='64' height='64' fill='url(#g)'/><circle cx='32' cy='26' r='11' fill='white' fill-opacity='.85'/><path d='M12 60c3-12 12-18 20-18s17 6 20 18z' fill='white' fill-opacity='.85'/></svg>`
  return `data:image/svg+xml,${encodeURIComponent(svg)}`
}

const SIZES = ['sm', 'default', 'lg'] as const

export default function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-10">
      {SIZES.map((size) => (
        <figure key={size} className="flex flex-col items-center gap-3">
          <div className="flex items-center gap-2">
            <Avatar size={size}>
              <AvatarImage src={portrait(230, 262)} alt="Ana Lima" />
              <AvatarFallback role="img" aria-label="Ana Lima">
                AL
              </AvatarFallback>
            </Avatar>
            {/* No image: the initials show, on the muted disc. */}
            <Avatar size={size}>
              <AvatarFallback role="img" aria-label="Kenji Sato">
                KS
              </AvatarFallback>
            </Avatar>
            <Avatar size={size}>
              <AvatarImage src={portrait(160, 200)} alt="Priya Raman, online" />
              <AvatarFallback role="img" aria-label="Priya Raman, online">
                PR
              </AvatarFallback>
              <AvatarBadge aria-hidden />
            </Avatar>
          </div>
          <figcaption className="font-mono text-xs text-fg-muted">{size}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

Each size with an image, with initials only, and with a status dot.

`size` is `sm` (24px), `default` (32px) or `lg` (40px). `AvatarBadge` adds a status dot on the end-bottom edge, cut out of the page by a ring and sized to the avatar. It's green by default. Recolor it with a class, such as `bg-warning`.

### Groups

```tsx
'use client'

import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from '@youj/react'

const TEAM = [
  { name: 'Ana Lima', initials: 'AL', src: portrait(230, 262) },
  { name: 'Jonas Weber', initials: 'JW', src: portrait(200, 230) },
  { name: 'Priya Raman', initials: 'PR', src: portrait(160, 200) },
  { name: 'Sara Okafor', initials: 'SO', src: portrait(20, 350) },
]

export default function AvatarGroupExample() {
  return (
    <div className="flex w-full max-w-md items-center justify-between gap-4 rounded-xl border border-line bg-surface px-4 py-3">
      <div className="min-w-0">
        <p className="truncate text-ui font-medium text-fg">Design system</p>
        <p className="text-ui-sm text-fg-muted">Shared with 9 people</p>
      </div>
      {/* Overlapping discs, each cut from the page by a ring. The count takes the avatars' size. */}
      <AvatarGroup>
        {TEAM.map((person) => (
          <Avatar key={person.name}>
            <AvatarImage src={person.src} alt={person.name} />
            <AvatarFallback role="img" aria-label={person.name}>
              {person.initials}
            </AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount>
          <span aria-hidden>+5</span>
          <span className="sr-only">and 5 more</span>
        </AvatarGroupCount>
      </AvatarGroup>
    </div>
  )
}
```

A shared-with row where avatars overlap in a group ending in a +5 count.

`AvatarGroup` overlaps its avatars and rings each one in the page color. `AvatarGroupCount` ends the stack with the number of people not shown, at the same size as the avatars beside it.

### Colors

```tsx
'use client'

import { Avatar, AvatarFallback } from '@youj/react'

const PEOPLE = [
  { email: 'mira@example.com', initials: 'MK' },
  { email: 'jonas@example.com', initials: 'JO' },
  { email: 'sana@example.com', initials: 'SN' },
  { email: 'theo@example.com', initials: 'TB' },
  { email: 'lena@example.com', initials: 'LH' },
]

export default function AvatarColors() {
  return (
    <div className="flex items-center gap-2">
      {PEOPLE.map((person) => (
        <Avatar key={person.email}>
          <AvatarFallback colorSeed={person.email}>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}
```

Initials tinted with a colour picked from each person's email.

`colorSeed` on `AvatarFallback` tints the initials with one of the theme's five chart colours, chosen from the seed: pass something stable (a user id or an email) and a person keeps their colour in every list and on every visit. The tint is drawn like the theme's inks, a thin wash with the initials mixed toward the text colour, so it follows the preset and holds contrast in light and dark. `avatarColor(seed)` returns the same colour's name (`chart-1`…`chart-5`) for anything else you want to match, such as a `Badge color`.

```tsx
<AvatarFallback colorSeed={user.email}>{initials}</AvatarFallback>
```

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add avatar
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Avatar for an author, assignee or member. Show the person’s name alongside it when space allows. For a company or project, consider an icon or logo instead of initials.

```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@youj/react'

export function Author() {
  return (
    <Avatar>
      <AvatarImage src="/people/ana.jpg" alt="Ana Lima" />
      <AvatarFallback>AL</AvatarFallback>
    </Avatar>
  )
}
```

The fallback shows until the image has actually loaded, and stays if the image fails, so there's never a broken-image frame. When the image arrives, it fades in over the muted disc.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` |  |

#### AvatarImage

Takes the props of `AvatarPrimitive.Image.Props`.

`AvatarImage` takes an image's `src` and `alt`, and Base UI's `onLoadingStatusChange`. `AvatarFallback` takes Base UI's `delay`, in milliseconds, to hold the initials back briefly on fast connections, and `colorSeed` to tint them with a chart colour picked from the seed. `AvatarBadge`, `AvatarGroup` and `AvatarGroupCount` render plain elements and take their usual attributes.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Image in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | fades in over the fallback once loaded |

**Reduced motion:** The image replaces the fallback at once.

#### Reduced motion

A loaded image replaces the initials at once instead of fading in. Nothing else about the avatar moves.

### Accessibility

- An avatar next to a visible name is decorative. Mark it `aria-hidden` and give its image an empty `alt`, as in the demo, so the name isn't read twice.
- An avatar on its own, such as one in a stack, needs the person's name. Put it in the image's `alt`, and give the fallback `role="img"` and an `aria-label` with the same name, so it reads the same before the image loads or if it fails.
- The status dot is color only. Say the status in text nearby, or include it in the name, as in "Priya Raman, online".
- Give the group count words for screen readers, such as "and 4 more", rather than "+4".

---

# Avatar Stack

> Show a group of people as overlapping avatars, with presence and an expandable list.

Source: https://www.youj.dev/docs/components/avatar-stack

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  AvatarStack,
  Button,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  type AvatarStackUser,
  type Presence,
} from '@youj/react'

/** A generated portrait, so the demo works offline. */
function portrait(hueA: number, hueB: number) {
  const svg = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='hsl(${hueA} 70% 62%)'/><stop offset='1' stop-color='hsl(${hueB} 70% 42%)'/></linearGradient></defs><rect width='64' height='64' fill='url(#g)'/><circle cx='32' cy='26' r='11' fill='white' fill-opacity='.85'/><path d='M12 60c3-12 12-18 20-18s17 6 20 18z' fill='white' fill-opacity='.85'/></svg>`
  return `data:image/svg+xml,${encodeURIComponent(svg)}`
}

const TEAM: AvatarStackUser[] = [
  { id: 'mira', name: 'Mira Chen', src: portrait(230, 262), presence: 'online', description: 'Design lead · Editing' },
  { id: 'jonas', name: 'Jonas Weber', src: portrait(160, 200), presence: 'online', description: 'Frontend' },
  { id: 'priya', name: 'Priya Natarajan', src: portrait(20, 350), presence: 'away', description: 'Platform' },
  { id: 'sam', name: 'Sam Okafor', presence: 'busy', description: 'In a meeting until 15:00' },
  { id: 'ines', name: 'Inès Laurent', src: portrait(290, 320), presence: 'offline', description: 'Research' },
  { id: 'kenji', name: 'Kenji Mori', src: portrait(190, 240), presence: 'online', description: 'Infrastructure' },
  { id: 'ada', name: 'Ada Brooks', presence: 'offline', description: 'Support' },
]

const CYCLE: Presence[] = ['online', 'away', 'busy', 'offline']

export default function AvatarStackDemo() {
  const [users, setUsers] = useState(TEAM)
  const [turn, setTurn] = useState(0)

// Moves one of the first four people to their next status; their dot pops in again.
  const changeStatus = () => {
    setUsers((list) =>
      list.map((user, i) => (i === turn % 4 ? { ...user, presence: CYCLE[(CYCLE.indexOf(user.presence ?? 'online') + 1) % 4] } : user)),
    )
    setTurn((t) => t + 1)
  }

return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Q3 roadmap</CardTitle>
        <CardDescription>Last edited 2 minutes ago by Mira Chen.</CardDescription>
      </CardHeader>
      <CardContent className="flex items-center justify-between gap-4">
        {/* On a card, the rings that cut the overlaps out take the card's colour. */}
        <AvatarStack users={users} label="Collaborators" className="*:data-[slot=avatar]:ring-surface **:data-[slot=avatar-group-count]:ring-surface" />
        <Button variant="outline" size="sm" onClick={changeStatus}>
          Change a status
        </Button>
      </CardContent>
    </Card>
  )
}
```

A roadmap card whose collaborators sit in a stack, with a button that cycles one person's status.

### Sizes and overflow

```tsx
'use client'

import { AvatarStack, type AvatarStackUser } from '@youj/react'

const PEOPLE: AvatarStackUser[] = [
  { id: 'mira', name: 'Mira Chen', presence: 'online' },
  { id: 'jonas', name: 'Jonas Weber', presence: 'online' },
  { id: 'priya', name: 'Priya Natarajan', presence: 'away' },
  { id: 'sam', name: 'Sam Okafor', presence: 'busy' },
  { id: 'ines', name: 'Inès Laurent' },
  { id: 'kenji', name: 'Kenji Mori' },
  { id: 'ada', name: 'Ada Brooks' },
]

export default function AvatarStackSizes() {
  return (
    <div className="grid grid-cols-[auto_auto] items-center gap-x-8 gap-y-5 text-ui-sm text-fg-muted">
      <span>sm, max 5</span>
      <AvatarStack users={PEOPLE} size="sm" max={5} label="Viewers" />
      <span>default, max 4</span>
      <AvatarStack users={PEOPLE} label="Collaborators" />
      <span>lg, max 3</span>
      <AvatarStack users={PEOPLE} size="lg" max={3} label="Owners" />
      <span>fits, no +N</span>
      <AvatarStack users={PEOPLE.slice(0, 3)} label="Reviewers" />
    </div>
  )
}
```

The stack at sm, default and lg with different limits, and one that fits without a +N.

`size` follows the [Avatar](https://www.youj.dev/docs/components/avatar) sizes, and `max` sets how many faces show before "+N". When only one person would be hidden, the stack shows them instead: a "+1" would take the same space as their face.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add avatar-stack
```

It brings `avatar`, `popover`, `scroll-area`, `tooltip`, `youj-core`, `youj-labels-avatar-stack`, `youj-presets`, `youj-ui-core` with it.

The copy is 10 registry items, about 7,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `popover`, `presentation`, `scroll-area`, `tooltip`.

Use an avatar stack to show who is in a document, a project or a call, when the faces matter more than the details. It shows the first `max` people and puts everyone else behind a "+N" button that opens the full list with each person's role and status. For a single person, use an [Avatar](https://www.youj.dev/docs/components/avatar). For a list people manage (roles, removal), use a table or a list, not a stack.

```tsx
import { AvatarStack, type AvatarStackUser } from '@youj/react'

const people: AvatarStackUser[] = [
  { id: 'mira', name: 'Mira Chen', src: '/avatars/mira.jpg', presence: 'online', description: 'Design lead' },
  { id: 'jonas', name: 'Jonas Weber', presence: 'away' },
  // …
]

export function Collaborators() {
  return <AvatarStack users={people} label="Collaborators" />
}
```

Each person needs an `id` and a `name`. Without a `src`, the avatar shows their initials. `presence` adds a status dot (`online`, `away`, `busy` or `offline`), and `description` is the second line in the full list. `label` names the group ("Collaborators: Mira Chen, Jonas Weber and 5 others") and heads the list.

On a card, set the rings that cut the overlaps out to the card's color, as the demo does: `*:data-[slot=avatar]:ring-surface`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `users` (required) | `readonly AvatarStackUser[]` |  |  |
| `max` | `number` | `4` | Avatars shown before "+N". |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` |  |
| `label` | `string` | `"People"` | What the people are, for the group's name and the list heading. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fan out | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | hovering the stack spreads each avatar 3px per position towards the inline end (`translate`) |
| Lift | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the avatar under the pointer rises 2px above its neighbors |
| Presence dot | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | pops in from scale 0 when a status changes |
| Name tooltip |  |  | drifts off the avatar (`yj-tooltip`), after a 200ms hover delay |
| Full list |  |  | scales from "+N" as it fades in (`yj-pop`) |

**Reduced motion:** No fan and no lift; status dots appear without the pop.

Only transforms move, so the stack never reflows the line it sits in.

#### Reduced motion

The stack doesn't fan out on hover, the hovered avatar doesn't lift and status dots appear in place. Tooltips and the list still open, with the overlay presets' reduced behavior.

### Accessibility

- The stack is a `group` named with everyone in it: the first two names and a count of the rest.
- Each avatar shows the person's name and status in a tooltip on hover. Avatars aren't in the tab order, so keyboard and screen reader users get the names from the group's label and the "+N" list.
- "+N" is a button named "Show all 7 collaborators". It opens the list in a Popover, where each status is written out, not only shown as a color.
- Presence dots are decorative; the status text is in the tooltip and the list.

---

# Badge

> Label status, counts and metadata in a compact badge.

Source: https://www.youj.dev/docs/components/badge

## Examples

### Demo

```tsx
'use client'

import { AlertTriangleIcon, CheckIcon, ClockIcon, LoaderRingIcon } from '@youj/icons'
import { Badge } from '@youj/react'

const DEPLOYMENTS = [
  { id: 'dpl_8f2k', branch: 'main', message: 'Tighten cache headers', status: 'Ready', variant: 'success', Icon: CheckIcon },
  { id: 'dpl_7h1c', branch: 'feat/pricing', message: 'New pricing page', status: 'Building', variant: 'default', Icon: LoaderRingIcon },
  { id: 'dpl_6a9x', branch: 'fix/og-images', message: 'OG images for blog posts', status: 'Queued', variant: 'secondary', Icon: ClockIcon },
  { id: 'dpl_5b0q', branch: 'chore/deps', message: 'Bump the build image', status: 'Error', variant: 'danger', Icon: AlertTriangleIcon },
] as const

export default function BadgeDemo() {
  return (
    <ul className="w-full max-w-lg divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface">
      {DEPLOYMENTS.map(({ id, branch, message, status, variant, Icon }) => (
        <li key={id} className="flex items-center gap-3 px-4 py-3">
          <div className="min-w-0 flex-1">
            <p className="truncate text-ui font-medium text-fg">{message}</p>
            <p className="truncate font-mono text-ui-xs text-fg-muted">
              {branch} · {id}
            </p>
          </div>
          {branch === 'main' && <Badge variant="outline">Production</Badge>}
          {/* The badge carries the state; the row carries the content. */}
          <Badge variant={variant}>
            <Icon />
            {status}
          </Badge>
        </li>
      ))}
    </ul>
  )
}
```

A deployments list where each row carries a status badge, and the main branch is also marked Production.

### Variants

```tsx
'use client'

import { Badge } from '@youj/react'

export default function BadgeVariants() {
  return (
    <div className="flex max-w-lg flex-wrap items-center justify-center gap-2">
      <Badge>Default</Badge>
      <Badge variant="solid">Solid</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="success">Success</Badge>
      <Badge variant="warning">Warning</Badge>
      <Badge variant="danger">Destructive</Badge>
    </div>
  )
}
```

Every variant side by side.

Badges are soft by default: a 10% tint of their color, with text in the same hue mixed toward the foreground, so it holds WCAG AA contrast on the tint in both modes. Only `solid` spends the accent at full strength, so save it for the one badge that should lead.

Pick by meaning, not by color: `success`, `warning` and `danger` for outcomes, `secondary` and `outline` for neutral metadata, and `default` for what's new or in progress.

For a live status, put a `BadgeDot` first inside the badge. It takes the badge's text color and is hidden from assistive tech, since the text carries the meaning:

```tsx
import { Badge, BadgeDot } from '@youj/react'

<Badge variant="success">
  <BadgeDot />
  Live
</Badge>
```

### Colors

```tsx
'use client'

import { Badge, BadgeDot } from '@youj/react'

const LABELS = [
  { name: 'Frontend', color: 'chart-1' },
  { name: 'Backend', color: 'chart-2' },
  { name: 'Design', color: 'chart-3' },
  { name: 'Research', color: 'chart-4' },
]

export default function BadgeColors() {
  return (
    <div className="flex flex-col items-center gap-3">
      <div className="flex flex-wrap justify-center gap-2">
        {LABELS.map((label) => (
          <Badge key={label.name} color={label.color}>
            {label.name}
          </Badge>
        ))}
      </div>
      <div className="flex flex-wrap justify-center gap-2">
        {LABELS.map((label) => (
          <Badge key={label.name} variant="outline">
            <BadgeDot color={label.color} />
            {label.name}
          </Badge>
        ))}
      </div>
    </div>
  )
}
```

Label chips in colours of their own: tinted chips, then outline chips with a coloured dot.

`color` gives a chip a colour of its own, for labels people create (Frontend, Design): a theme colour's name (`chart-1`…`chart-5`, `accent`, `info`, `success`, `warning`, `danger`) or any CSS colour (`var(--brand)`). The chip is tinted with it and its text inked from it, the way the variants are, so a theme name holds contrast in both modes; a CSS colour of your own is yours to check. `BadgeDot color` paints only the dot, for a quieter outline chip.

```tsx
<Badge color="chart-3">Design</Badge>
<Badge variant="outline">
  <BadgeDot color="chart-3" />
  Design
</Badge>
```

### Icons and links

```tsx
'use client'

import { ArrowUpRightIcon, BadgeCheckIcon } from '@youj/icons'
import { Badge } from '@youj/react'

export default function BadgeLinks() {
  return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <div className="flex items-center gap-2">
        <p className="text-ui font-medium text-fg">youj-web</p>
        <Badge variant="success">
          <BadgeCheckIcon />
          Verified
        </Badge>
        <Badge variant="secondary" className="ms-auto tabular-nums">
          12 open
        </Badge>
      </div>
      <p className="mt-1.5 text-ui-sm text-fg-muted">Next.js · Updated 4 minutes ago</p>
      <div className="mt-3 flex flex-wrap gap-2">
        {/* `render` swaps the span for a link, which picks up hover and focus. */}
        <Badge variant="outline" render={<a href="#changelog" />}>
          Changelog
          <ArrowUpRightIcon />
        </Badge>
        <Badge variant="outline" render={<a href="#releases" />}>
          v2.4.0
        </Badge>
        <Badge variant="warning">Expires in 3 days</Badge>
      </div>
    </div>
  )
}
```

A project card with a verified badge, a count, link badges and a warning.

A leading or trailing icon sits 12px tall and is pulled 2px toward the edge, so the badge's padding looks even. Pass `render={<a href="…" />}` to make the badge a link. It keeps the badge's look and gains a hover tint and a focus ring. Youj icons inside a link play when the link is hovered or focused.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add badge
```

It brings `icon-x`, `youj-presets`, `youj-ui-core` with it.

Use Badge for short labels such as status, count, version or environment. Keep it non-interactive or make it a link. Use a button for actions, and an [Alert](https://www.youj.dev/docs/components/alert) or [Toast](https://www.youj.dev/docs/components/toast) for longer messages.

```tsx
import { Badge } from '@youj/react'

export function Status() {
  return <Badge variant="success">Ready</Badge>
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'solid' \| 'outline' \| 'secondary'` | `'default'` |  |
| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | `sm` (18px) for a count or tag in a dense row, `lg` (24px) beside a title. |
| `color` | `string` |  | A colour of your own for a label chip, in place of the variant's: a theme colour's name (`chart-1`…`chart-5`, `accent`, `info`, `success`, `warning`, `danger`) or any CSS colour (`var(--brand)`). The chip is tinted with it and its text inked from it. A CSS colour's contrast is yours to check. |

`render` comes from Base UI's `useRender`. It replaces the default `span` with your element and merges the badge's props onto it.

### Reduced motion

Badge doesn't move. A link badge's hover tint is a color change, and it stays under reduced motion.

### Accessibility

- A badge is plain text in a `span`, so it's read in line with its surroundings. Put it where the words make sense in reading order, such as after the item it describes.
- Don't rely on color alone. The label carries the meaning, and an icon can reinforce it.
- A link badge is a real `a` with a visible focus ring. Its text should say where it goes.

---

# Countdown

> Count down to a launch, a sale or a deadline in days, hours, minutes and seconds.

Source: https://www.youj.dev/docs/components/countdown

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Countdown } from '@youj/react'

export default function CountdownDemo() {
  // A fixed moment in a real app, e.g. '2026-10-07T16:00:00Z'. Here: six days out from the first render.
  const [launch] = useState(() => Date.now() + (6 * 24 + 4) * 3_600_000 + 12 * 60_000 + 45_000)
  return <Countdown to={launch} />
}
```

A countdown to a launch six days and four hours away.

### Finishing

```tsx
'use client'

import { useState } from 'react'
import { Badge, Button, Countdown } from '@youj/react'

export default function CountdownComplete() {
  const [to, setTo] = useState(() => Date.now() + 8_000)
  const [live, setLive] = useState(false)
  return (
    <div className="flex flex-col items-center gap-5">
      <Badge variant={live ? 'success' : 'outline'}>
        {live ? 'Doors are open' : 'Doors open soon'}
      </Badge>
      <Countdown to={to} onComplete={() => setLive(true)} className="text-3xl sm:text-4xl" />
      <Button
        size="sm"
        variant="outline"
        onClick={() => {
          setLive(false)
          setTo(Date.now() + 8_000)
        }}
      >
        Restart
      </Button>
    </div>
  )
}
```

A countdown that runs out after 8 seconds, flips a badge to "Doors are open" and can be restarted.

When time runs out the digits settle to muted zeros, the root's `data-state` turns to `complete` and `onComplete` fires once. If `to` has already passed when the component mounts, it fires straight after mount. That makes the callback the place to swap in what comes next: a "We're live" badge, a reload, or the real page.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add countdown
```

It brings `counter`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use Countdown when the moment itself matters: a launch, the end of an offer, a maintenance window closing. Give it the moment as `to`. It works out the rest in the browser, ticks on the second boundary and lands on zero exactly at `to`. For a date people read rather than watch, write it out instead, and for time since something happened use relative text such as "5 min ago".

```tsx
import { Countdown } from '@youj/react'

export function Launch() {
  return <Countdown to="2026-10-07T16:00:00Z" onComplete={() => location.reload()} />
}
```

`to` takes a `Date`, milliseconds since the epoch or an ISO string. Each unit sits in its own tile with its name underneath. The names come from `Intl`, so they follow the locale ("days", "Tage", "jours"). The digits are tabular, so the row never shifts while it counts. Set the size with a text class, such as `className="text-6xl"`: the tiles and gaps scale with it.

Nothing time-based is rendered on the server. The server and hydration renders show held zeros with `data-state="pending"`, and the component reads the clock only once it's mounted, so server markup and the first client render always match. A static page built days ahead shows the right time as soon as it loads.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `to` (required) | `Date \| number \| string` |  | When time runs out: a Date, ms since the epoch, or an ISO string. |
| `onComplete` | `() => void` |  | Called once when time runs out, straight after mount if `to` has already passed. |
| `formatLabel` | `(time: CountdownTime) => string` |  | The text read and announced. Default English, e.g. "6 days, 4 hours left", changing at most once a minute. |
| `locale` | `string` |  | A BCP 47 locale for the digits and unit names. Default: the YoujProvider locale. |
| `labels` | `Partial<Record<'days' \| 'hours' \| 'minutes' \| 'seconds', ReactNode>>` |  | The caption under each unit. Default: the unit's name from Intl in the locale. |
| `paused` | `boolean` | `false` | Stop ticking and hold the last reading, e.g. while it is off screen. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

`formatLabel` receives `{ days, hours, minutes, seconds, total }` and returns the text screen readers hear. Use it to translate that text or to change how coarse it is.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| A digit changes | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the new digit rolls down into its slot from above as the old one falls away and fades |
| The old digit leaves | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | it drops and fades, a little faster than the new one arrives |
| Several digits change | `stagger.tight` | 24ms step | they roll right to left, one step apart, as 10:00 turns to 09:59 |

**Reduced motion:** Digits change in place with no roll.

Each roll is two small Web Animations on transform and opacity, so the component doesn't need the Motion runtime. If a digit changes again before its roll ends, the digit still arriving leaves from where it is instead of jumping.

#### Reduced motion

Digits change in place with no roll or fade. The time left stays exact to the second.

### Accessibility

- The root is a `timer`. The digit tiles are hidden from assistive technology, and one polite live region carries the time as words.
- The spoken text is coarse on purpose: "6 days, 4 hours left" while there are days, hours and minutes under a day, minutes under an hour, then "Under a minute left". It changes at most once a minute, so a screen reader isn't interrupted every second.
- Nothing is announced when the page loads. The region starts announcing after the first reading, and "Time's up" is announced at zero.
- The default spoken text is English. Pass `formatLabel` for other languages. The unit names under the tiles already follow the locale.

---

# Sparkline

> Show a compact trend beside a metric or inside a table row.

Source: https://www.youj.dev/docs/components/sparkline

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, Sparkline } from '@youj/react'

/** A random walk: the next minute of traffic. */
function walk(n: number, start = 40) {
  const out = [start]
  for (let i = 1; i < n; i++) out.push(Math.max(4, out[i - 1]! + (Math.random() - 0.45) * 12))
  return out.map(Math.round)
}

const INITIAL = [38, 42, 40, 47, 45, 51, 49, 56, 54, 60, 58, 63, 61, 67, 70, 72]

export default function SparklineDemo() {
  const [data, setData] = useState(INITIAL)
  const latest = data[data.length - 1]!
  return (
    <div className="flex w-72 flex-col gap-3">
      <div className="flex items-baseline justify-between">
        <span className="text-ui-sm text-fg-muted">Requests per minute</span>
        <span className="text-ui-lg font-semibold text-fg tabular-nums">{latest}</span>
      </div>
      <Sparkline data={data} className="h-14" label={`Requests per minute, now ${latest}`} />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setData((d) => walk(16, d[d.length - 1]))}>
        New data
      </Button>
    </div>
  )
}
```

A requests-per-minute figure with its sparkline, and a button that generates new data.

### In a list

```tsx
'use client'

import { Sparkline } from '@youj/react'

const SERVICES = [
  { name: 'api.acme.dev', trend: [120, 132, 128, 141, 150, 147, 162], color: 'var(--color-chart-1)' },
  { name: 'edge-eu-west', trend: [88, 84, 90, 79, 76, 81, 72], color: 'var(--color-chart-4)' },
  { name: 'cdn-assets', trend: [40, 41, 39, 44, 43, 46, 48], color: 'var(--color-chart-3)' },
]

export default function SparklineRows() {
  return (
    <ul className="w-full max-w-sm divide-y divide-line rounded-xl border border-line bg-surface text-ui">
      {SERVICES.map((row) => (
        <li key={row.name} className="flex items-center gap-4 px-4 py-2.5">
          <span className="flex-1 truncate">{row.name}</span>
          {/* Decorative: the number beside it says what the line shows. */}
          <Sparkline data={row.trend} color={row.color} area={false} className="h-6 w-24" />
          <span className="w-10 text-end text-fg-muted tabular-nums">{row.trend[row.trend.length - 1]}</span>
        </li>
      ))}
    </ul>
  )
}
```

A list of services, each with a trend line and no area wash.

Without `label` a sparkline is decorative and hidden from assistive technology, which is right when the number beside it already says what matters. `area={false}` drops the wash for tight rows, and `color` takes any CSS color, best one of the chart colors.

### Comparable scales

```tsx
'use client'

import { Sparkline } from '@youj/react'

const REGIONS = [
  { name: 'us-east', cpu: [42, 48, 51, 47, 55, 61, 58, 64] },
  { name: 'eu-west', cpu: [18, 21, 19, 24, 22, 26, 25, 27] },
]

/* With `domain`, both lines share one scale, so the quieter region reads as quieter. */
export default function SparklineDomain() {
  return (
    <div className="grid w-full max-w-md gap-4 sm:grid-cols-2">
      {REGIONS.map((region) => (
        <figure key={region.name} className="flex flex-col gap-2 rounded-xl border border-line bg-surface p-3">
          <figcaption className="flex justify-between text-ui-sm">
            <span className="text-fg-muted">{region.name}</span>
            <span className="font-medium text-fg tabular-nums">{region.cpu[region.cpu.length - 1]}% CPU</span>
          </figcaption>
          <Sparkline data={region.cpu} domain={[0, 100]} className="h-12" label={`${region.name} CPU over the last 8 hours, of 100%`} />
        </figure>
      ))}
    </div>
  )
}
```

CPU sparklines for several regions, all on a 0 to 100 domain.

Each sparkline scales to its own range by default, which makes a flat line look as busy as a steep one. Give sparklines that sit side by side the same `domain` so their heights compare.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add sparkline
```

It brings `youj-core`, `youj-ui-core` with it.

Use a sparkline to show the shape of recent values next to the number they lead to: requests per minute beside the current rate, a week of revenue in a KPI, a trend in each row of a list. It has no axes, no tooltip and no legend, so it says "rising" or "falling" and nothing more. When people need to read values off it, use a [Chart](https://www.youj.dev/docs/components/chart). Inside a KPI card, pass it to [Stat Card](https://www.youj.dev/docs/components/stat-card)'s `chart` slot.

```tsx
import { Sparkline } from '@youj/react'

<Sparkline data={[12, 14, 13, 17, 16, 19, 22]} className="h-8 w-32" label="Signups this week, rising" />
```

It stretches to its box, so give it a height (the default is `h-8`) and a width from its container. The stroke keeps its width at any size, and the curve is monotone: it passes through every point and never overshoots one, so a flat stretch stays flat.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly number[]` |  |  |
| `color` | `string` | `'var(--color-chart-1)'` | Any CSS color. |
| `area` | `boolean` | `true` | A wash under the curve. |
| `dot` | `boolean` | `true` | A dot on the latest value. |
| `domain` | `[number, number]` |  | Fixes the value range (e.g. `[0, 100]`), so separate sparklines compare. Default: the data's own range. |
| `label` | `string` |  | Accessible name, e.g. "Revenue, last 30 days, rising". Without it the sparkline is decorative. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | the curve and its wash wipe in from the start when 40% of it scrolls into view, once |
| End dot lands | `spring.settle` | 0.45s, bounce 0.3 | scales in as the line reaches it, 70% of the way through the reveal |
| Data change | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the curve and wash morph point by point; a change mid-morph continues from where it is |
| Dot follows | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | glides to the new latest value |

**Reduced motion:** Drawn in place with its dot, and data changes jump to the new shape.

#### Reduced motion

The line, its wash and the dot are drawn in their final place, with no reveal, and new data replaces the old shape at once.

### Accessibility

- With `label` it's an image (`role="img"`) named by the label. Write the label as the takeaway: "Revenue, last 30 days, rising".
- Without `label` it's `aria-hidden`. Say what it shows in the text beside it.
- A trend reads left to right in every text direction, so the sparkline sets `dir="ltr"` on itself.

---

# Gauge

> Show a score or resource level on a fine half-ring scale, with its value and status.

Source: https://www.youj.dev/docs/components/gauge

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, Gauge, type GaugeThreshold } from '@youj/react'

const INDEX: GaugeThreshold[] = [
  { value: 0, tone: 'danger', label: 'Critical' },
  { value: 50, tone: 'warning', label: 'Strained' },
  { value: 80, tone: 'success', label: 'Nominal' },
]

export default function GaugeDemo() {
  const [index, setIndex] = useState(74)
  return (
    <div className="flex flex-col items-center gap-4">
      <Gauge value={index} size="lg" gradient thresholds={INDEX} label="Health index" />
      <p className="text-ui text-fg-muted">
        <span className="font-mono text-fg">payments-api</span> · 6 h window
      </p>
      <div className="flex gap-2">
        {[38, 74, 91].map((v) => (
          <Button key={v} size="sm" variant={v === index ? 'secondary' : 'outline'} onClick={() => setIndex(v)}>
            {v}
          </Button>
        ))}
      </div>
    </div>
  )
}
```

A health index gauge with zones and a status, and buttons for 38, 74 and 91 that move it.

`gradient` lays the bands under the fill as zones: each band faint in its own tone, split from the next by a hairline gap, so the whole scale reads at once, like the zones on a dial, while the fill keeps the one tone of the band the value is in. Without thresholds the zones are danger, warning and success thirds. Use it for scores where high is good; the band still names the value.

### Thresholds

```tsx
'use client'

import { Gauge, type GaugeThreshold } from '@youj/react'

const LOAD: GaugeThreshold[] = [
  { value: 70, tone: 'warning', label: 'Busy' },
  { value: 90, tone: 'danger', label: 'Saturated' },
]

export default function GaugeThresholds() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-8">
      <Gauge value={34} size="sm" thresholds={LOAD} format={{ style: 'unit', unit: 'percent' }} label="Web" />
      <Gauge value={76} size="default" thresholds={LOAD} format={{ style: 'unit', unit: 'percent' }} label="Workers" />
      <Gauge value={95} size="sm" thresholds={LOAD} format={{ style: 'unit', unit: 'percent' }} label="Database" />
    </div>
  )
}
```

Three load gauges at 34, 76 and 95 percent, in different sizes.

Each threshold starts a band that runs up to the next one. The fill takes the band's `tone`, and the band's `label` becomes the sub-label under the value (pass children to write your own). A value crossing into the next band crossfades the fill to the new tone.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add gauge
```

It brings `youj-core`, `youj-labels-meter`, `youj-presets`, `youj-ui-core` with it.

Use a gauge for a single score between known ends that people read at a glance: a health index, a load, a quota. The value sits in the bowl and the word for its band sits under it, between the range's two ends, so "74, Strained" reads before anyone looks at the arc. The arc is a thin band on a scale of ticks, and a fine needle across the band marks the value. For several resources side by side, use [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter); for a trend, use a [Sparkline](https://www.youj.dev/docs/components/sparkline).

```tsx
import { Gauge } from '@youj/react'

<Gauge
  value={74}
  label="Health index"
  gradient
  thresholds={[
    { value: 0, tone: 'danger', label: 'Critical' },
    { value: 50, tone: 'warning', label: 'Strained' },
    { value: 80, tone: 'success', label: 'Nominal' },
  ]}
/>
```

`min` and `max` default to 0 and 100. `format` takes `Intl.NumberFormat` options, so units and percentages follow the locale. `size` is `sm`, `default` or `lg`; `sm` leaves the range's ends out.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `size` | `Extract<Size, 'sm' \| 'default' \| 'lg'>` | `'default'` | The dial's size: `sm`, `default` or `lg`. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'accent'` | The fill's tone outside any threshold band. |
| `thresholds` | `GaugeThreshold[]` |  | Bands, each from its value up to the next. The fill takes the band's tone. |
| `gradient` | `boolean` | `false` | Lay the bands under the fill as zones: each threshold band faint in its tone (danger, warning and success thirds without thresholds), split by hairline gaps. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the value. Default: whole numbers. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Names the gauge for assistive tech when no visible label points at it. |
| `children` | `ReactNode` |  | The sub-label under the value. Default: the current band's label. |

Also takes the props of `MeterPrimitive.Root.Props`.

### Styling

Every part carries a `data-slot`: `gauge`, `gauge-arc`, `gauge-scale` (the ticks), `gauge-track` (or `gauge-zone` with `gradient`), `gauge-indicator`, `gauge-index`, `gauge-value`, `gauge-footer`, `gauge-min`, `gauge-max` and `gauge-label`. The root also has `data-size` and `data-tone` (a tone, or `gradient`).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `spring.smooth` | 0.36s, bounce 0 | the fill sweeps up from the minimum when 40% of the gauge scrolls into view, once |
| Number and index | `spring.smooth` | 0.36s, bounce 0 | follow the fill frame by frame on the same spring, so they never drift apart |
| New value | `spring.smooth` | 0.36s, bounce 0 | retargets mid-flight with its velocity; pressing quickly never jumps |
| Band change | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the fill crossfades to the new tone |

**Reduced motion:** Drawn at its value, with the index and the number in place; changes jump.

#### Reduced motion

The fill, the needle and the number are drawn at the value, and a new value replaces the old one at once.

### Accessibility

- It's a `meter` (Base UI Meter) with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. Name it with `label`, or point `aria-labelledby` at a visible heading.
- The value is spoken with its band: "74, Strained". A warning or danger band without a label is spoken as "Warning" or "Critical" (translated through `labels`), so color is never the only signal.
- The arc and the animated number are hidden from assistive tech; the meter's value text carries both.
- A dial turns clockwise in every script, so the arc keeps its direction in right-to-left layouts.

---

# Score Ring

> Show a score out of a range as a full ring of ticks lit up to it, with its letter grade in the middle.

Source: https://www.youj.dev/docs/components/score-ring

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ScoreRing, type ScoreGrade } from '@youj/react'

/** Letter grades from F to A, each band in its tone. */
const GRADES: ScoreGrade[] = [
  { from: 0, label: 'F', tone: 'danger' },
  { from: 40, label: 'D', tone: 'warning' },
  { from: 60, label: 'C', tone: 'warning' },
  { from: 75, label: 'B', tone: 'success' },
  { from: 90, label: 'A', tone: 'success' },
]

export default function ScoreRingDemo() {
  const [score, setScore] = useState(77)
  return (
    <div className="flex flex-col items-center gap-5">
      <ScoreRing value={score} grades={GRADES} size="lg" label="Security score" />
      <div className="flex gap-2">
        {[34, 62, 77, 94].map((n) => (
          <Button key={n} size="sm" variant={n === score ? 'default' : 'outline'} onClick={() => setScore(n)} className="tabular-nums">
            {n}
          </Button>
        ))}
      </div>
    </div>
  )
}
```

A security score with letter grades from F to A, and buttons for 34, 62, 77 and 94 that move it. The ring takes the tone of the band the score is in, and the grade in the middle changes with it.

### Without grades, busy

```tsx
'use client'

import { useState } from 'react'
import { ScoreRing, Switch } from '@youj/react'

/** Three scores without grades, so each shows its number, and a scan you can start. */
export default function ScoreRingGrades() {
  const [busy, setBusy] = useState(true)
  return (
    <div className="flex flex-col items-center gap-5">
      <div className="flex items-center gap-6">
        <ScoreRing value={88} size="sm" tone="chart-1" label="Uptime score" />
        <ScoreRing value={64} tone="chart-2" busy={busy} label="Coverage" />
        <ScoreRing value={512} max={850} size="sm" tone="chart-5" label="Credit score" />
      </div>
      <label className="flex items-center gap-2 text-ui text-fg-muted">
        <Switch size="sm" checked={busy} onCheckedChange={setBusy} />
        Scanning
      </label>
    </div>
  )
}
```

Without `grades` the middle shows the score and the ring takes `tone`; `max` sets any range (a credit score out of 850). `busy` circles a soft sweep inside the ring while a scan or a check runs.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add score-ring
```

It brings `youj-core`, `youj-labels-score-ring`, `youj-presets`, `youj-ui-core` with it.

Use a score ring when one score carries a verdict: a security or health score with its letter grade, a compliance rating, a quality bar. The whole ring is the range and the lit ticks are the score, clockwise from the top, so how far round it reaches reads before the number; the tick at the score reaches past the rest. Pair it with the number itself (a [Stat Card](https://www.youj.dev/docs/components/stat-card)'s `StatValue`) when the exact score matters. For a value on a scale with named bands and both ends shown, use a [Gauge](https://www.youj.dev/docs/components/gauge). The [Score overview](https://www.youj.dev/docs/blocks/status-and-health#score-overview) card is built on it.

```tsx
import { ScoreRing, type ScoreGrade } from '@youj/react'

const grades: ScoreGrade[] = [
  { from: 0, label: 'F', tone: 'danger' },
  { from: 60, label: 'C', tone: 'warning' },
  { from: 75, label: 'B', tone: 'success' },
  { from: 90, label: 'A', tone: 'success' },
]

<ScoreRing value={77} grades={grades} label="Security score" />
```

Each grade starts a band at `from` that runs up to the next one, in any order; the ring takes the band's `tone` and shows its `label`. Without grades it shows the score in `tone` (the accent by default). `min` and `max` set the range (0 to 100 by default) and the score is held inside it. `ticks` sets how many make the ring (40 by default), `size` is `sm` (64px), `default` (96px) or `lg` (128px), and `children` replaces what sits in the middle.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `grades` | `readonly ScoreGrade[]` |  | Bands in any order: the ring takes the tone of the one the score is in, and shows its label. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The lit ticks' tone outside any grade. |
| `ticks` | `number` | `40` | How many ticks make the ring. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | The ring's size: `sm` 64px, `default` 96px, `lg` 128px. |
| `busy` | `boolean` | `false` | A soft sweep circles inside the ring, for a scan or a check still running. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the score. Default: whole numbers. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Score". |
| `children` | `ReactNode` |  | The middle. Default: the grade, else the score. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `score-ring`, `score-ring-ticks`, `score-ring-tick`, `score-ring-sweep` and `score-ring-center`. The root has `data-size`, `data-tone` (the band's tone, or `tone`) and `data-yj-busy`; a lit tick has `data-yj-lit`. The lit ticks' color is `--score-ring-tone`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the ticks light one after another up to the score when it scrolls into view |
| New score | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the ticks between the old and the new score relight at once |
| Busy | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1) | a soft sweep turns inside the ring, once every six deliberate beats |

**Reduced motion:** Drawn at its score, with no sweep.

#### Reduced motion

The ring is drawn at its score, a new score lands at once, and `busy` draws no sweep (the ring still says it is busy).

### Accessibility

- A `meter` (your `label`, or the labels' "Score") with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`, and a value text of the score of the maximum, then its grade: "77 of 100, grade B".
- `busy` sets `aria-busy`, so assistive tech knows the reading may change.
- The ticks and the sweep are decorative; the value text says the score. A grade is a letter as well as a tone, never color alone.
- A dial turns clockwise in every script, so the ring keeps its direction under RTL.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Segmented Meter

> Show resource usage in cells, with warning and danger thresholds.

Source: https://www.youj.dev/docs/components/segmented-meter

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, SegmentedMeter, type SegmentedMeterThreshold } from '@youj/react'

const HOT: SegmentedMeterThreshold[] = [{ value: 80, tone: 'warning', label: 'High' }]

export default function SegmentedMeterDemo() {
  const [disk, setDisk] = useState(84)
  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <SegmentedMeter label="Threads" value={47} thresholds={HOT} />
      <SegmentedMeter label="Disk" value={disk} thresholds={HOT} />
      <SegmentedMeter label="Backlog" value={870} max={2400} format={{}} />
      <div className="flex gap-2">
        {[52, 84, 96].map((v) => (
          <Button key={v} size="sm" variant={v === disk ? 'secondary' : 'outline'} onClick={() => setDisk(v)}>
            Disk {v}%
          </Button>
        ))}
      </div>
    </div>
  )
}
```

Threads, Disk and Backlog meters, with buttons that move Disk to 52, 84 or 96 percent.

Each threshold's tone applies to the lit cells from its value up. The leading cell always shows the value's own band, so a value in the danger band is never drawn only in warning. The band's `label` is spoken after the value.

### Score

```tsx
'use client'

import { SegmentedMeter, type SegmentedMeterThreshold } from '@youj/react'

const HEALTH: SegmentedMeterThreshold[] = [
  { value: 0, tone: 'danger', label: 'At risk' },
  { value: 40, tone: 'warning', label: 'Watch' },
  { value: 70, tone: 'success', label: 'Healthy' },
]

const WORKSPACES = [
  { name: 'Northline Studio', score: 96 },
  { name: 'Harbor & Pine', score: 52 },
  { name: 'Fieldnote', score: 81 },
  { name: 'Quarry Labs', score: 18 },
]

export default function SegmentedMeterScore() {
  return (
    <div className="flex w-full max-w-md flex-col rounded-xl border border-line bg-surface">
      {WORKSPACES.map((row) => (
        <div key={row.name} className="flex items-center gap-4 border-b border-line-subtle px-4 py-3 last:border-b-0">
          <span className="min-w-0 flex-1 truncate text-sm">{row.name}</span>
          <span className="w-7 text-end text-sm font-medium tabular-nums">{row.score}</span>
          <SegmentedMeter
            aria-label={`${row.name} health`}
            value={row.score}
            segments={12}
            thresholds={HEALTH}
            colorBy="value"
            showValue={false}
            className="w-36 shrink-0 [&_[data-slot=segmented-meter-cell]]:rounded-full [&_[data-slot=segmented-meter-track]]:h-3 [&_[data-slot=segmented-meter-track]]:gap-1"
          />
        </div>
      ))}
    </div>
  )
}
```

Workspace health scores in a list, each as twelve pips in the color of the band its score falls in.

`colorBy="value"` lights every cell in the value's band instead of the band each cell sits in, so a score reads as one color. Without a visible label, name each meter with `aria-label`.

### Usage by feature

```tsx
'use client'

import { useState, type ReactNode } from 'react'
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Progress,
  SegmentedMeter,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@youj/react'
import { GlobeIcon, ImageIcon, MicIcon, SearchIcon, SparklesIcon } from '@youj/icons'

interface Feature {
  id: string
  name: string
  icon: ReactNode
  used: number
  limit: number
}

const ICON = { size: 16, strokeWidth: 1.75 }
const FEATURES: Feature[] = [
  { id: 'drafting', name: 'Drafting assistant', icon: <SparklesIcon {...ICON} />, used: 2_140, limit: 4_000 },
  { id: 'images', name: 'Image studio', icon: <ImageIcon {...ICON} />, used: 1_720, limit: 2_000 },
  { id: 'voice', name: 'Voice notes', icon: <MicIcon {...ICON} />, used: 310, limit: 1_000 },
  { id: 'search', name: 'Document search', icon: <SearchIcon {...ICON} />, used: 940, limit: 1_000 },
  { id: 'translate', name: 'Translations', icon: <GlobeIcon {...ICON} />, used: 120, limit: 2_500 },
]
const PLAN_CREDITS = 10_000

const FILTERS = [
  { value: 'all', label: 'All features' },
  { value: 'near', label: 'Near limit' },
  { value: 'roomy', label: 'Plenty left' },
]
const SORTS = [
  { value: 'used', label: 'Most used' },
  { value: 'closest', label: 'Closest to limit' },
  { value: 'name', label: 'Name' },
]

/** Amber from 80% of a feature's limit, red from 95%. */
const hot = (limit: number) => [
  { value: limit * 0.8, tone: 'warning' as const, label: 'Near limit' },
  { value: limit * 0.95, tone: 'danger' as const, label: 'Almost out' },
]

const share = (f: Feature) => f.used / f.limit
const SORT_BY: Record<string, (a: Feature, b: Feature) => number> = {
  used: (a, b) => b.used - a.used,
  closest: (a, b) => share(b) - share(a),
  name: (a, b) => a.name.localeCompare(b.name),
}
const KEEP: Record<string, (f: Feature) => boolean> = {
  all: () => true,
  near: (f) => share(f) >= 0.8,
  roomy: (f) => share(f) < 0.5,
}

const number = new Intl.NumberFormat('en-US')

export default function SegmentedMeterUsage() {
  const [filter, setFilter] = useState('all')
  const [sort, setSort] = useState('used')
  const used = FEATURES.reduce((sum, f) => sum + f.used, 0)
  const rows = FEATURES.filter(KEEP[filter]!).sort(SORT_BY[sort]!)
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Credit usage</DialogTrigger>
      <DialogContent showCloseButton={false} className="max-w-lg">
        <DialogHeader>
          <DialogTitle>Credit usage</DialogTitle>
          <DialogDescription>Credits spent this month, by feature.</DialogDescription>
        </DialogHeader>
        <div className="flex flex-col gap-2">
          <div className="flex items-baseline justify-between gap-3">
            <p className="text-3xl font-semibold tracking-tight tabular-nums">
              {number.format(used)} <span className="text-ui font-normal tracking-normal text-fg-muted">/ {number.format(PLAN_CREDITS)} credits</span>
            </p>
            <p className="text-ui-sm text-fg-muted">Resets in 12 days</p>
          </div>
          <Progress aria-label="Credits used this month" value={used} max={PLAN_CREDITS} size="lg" />
        </div>
        <div className="flex items-center justify-between gap-2">
          <Pick label="Filter features" items={FILTERS} value={filter} onChange={setFilter} />
          <Pick label="Sort features" items={SORTS} value={sort} onChange={setSort} />
        </div>
        {/* A fixed height, so filtering swaps the rows without resizing the dialog. */}
        <div className="h-88 overflow-y-auto yj-scrollbar">
          {rows.length === 0 ? (
            <p className="grid h-full place-items-center text-ui text-fg-muted">No features match this filter.</p>
          ) : (
            <ul className="flex flex-col divide-y divide-line-subtle">
              {rows.map((f) => (
                <li key={f.id} className="flex flex-col gap-2.5 py-3.5 first:pt-1 last:pb-1">
                  <div className="flex items-center gap-2.5">
                    <span aria-hidden className="text-fg-muted">
                      {f.icon}
                    </span>
                    <span className="min-w-0 flex-1 truncate text-ui font-medium">{f.name}</span>
                    <span className="text-ui-sm text-fg-muted tabular-nums">
                      {number.format(f.used)} / {number.format(f.limit)}
                    </span>
                  </div>
                  <SegmentedMeter aria-label={`${f.name} usage`} value={f.used} max={f.limit} segments={40} thresholds={hot(f.limit)} showValue={false} className="[&_[data-slot=segmented-meter-track]]:h-2" />
                </li>
              ))}
            </ul>
          )}
        </div>
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Close</DialogClose>
          <Button>Upgrade plan</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

A credit-usage dialog: the month's total over a progress bar with when it resets, a filter and a sort, and a tick meter per feature.

Each row's meter is a `SegmentedMeter` with `thresholds` set from that feature's own limit (amber from 80%, red from 95%), so the tick row shows how close each feature is to running out. The band's `label` is spoken with the value. The list sits in a region of fixed height, so filtering swaps the rows without resizing the dialog.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add segmented-meter
```

It brings `youj-core`, `youj-labels-meter`, `youj-presets`, `youj-ui-core` with it.

Use a segmented meter for usage people compare across a panel: threads, disk, a backlog, seats. The discrete cells make levels countable, and the cells past a threshold light in its tone, so the warning shows exactly where usage crossed the line. For one headline score, use a [Gauge](https://www.youj.dev/docs/components/gauge); for progress through a task, use [Progress](https://www.youj.dev/docs/components/progress).

```tsx
import { SegmentedMeter } from '@youj/react'

<SegmentedMeter label="Disk" value={84} thresholds={[{ value: 80, tone: 'warning', label: 'High' }]} />
<SegmentedMeter label="Backlog" value={870} max={2400} format={{}} />
```

The value on the end side is a percentage of the range by default; pass `format` (`Intl.NumberFormat` options) to show the raw value, as the backlog does. `segments` sets the number of cells (default 40), `tone` the lit cells' tone below every threshold (default `neutral`, the ink) and `showValue={false}` hides the value.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `label` | `ReactNode` |  | The visible name on the start side: "CPU". |
| `segments` | `number` | `40` | How many cells. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'neutral'` | The lit cells' tone below every threshold. |
| `thresholds` | `SegmentedMeterThreshold[]` |  | Bands: cells from a threshold's value up light in its tone. |
| `colorBy` | `'position' \| 'value'` | `'position'` | `position`: each lit cell takes the band it sits in. `value`: every lit cell takes the value's band, as a score does. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the value. Default: a percentage of the range. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `showValue` | `boolean` | `true` | Show the value on the end side. |

Also takes the props of `MeterPrimitive.Root.Props`.

### Styling

Parts: `segmented-meter`, `segmented-meter-header`, `segmented-meter-label`, `segmented-meter-value`, `segmented-meter-track` and `segmented-meter-cell`. Each cell has `data-state` (`on` or `off`) and, when lit, `data-tone`. The label takes the theme's label voice (mono capitals in Basalt).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fill | `duration.deliberate` | 560ms | when half of it scrolls into view the cells light one after another at a constant rate, the whole row spanning the deliberate token |
| Each cell | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades to its tone |
| New value | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | lights or darkens the cells between the edge on screen and the new one, in order |

**Reduced motion:** The cells are lit at once, and a new value relights them in place.

#### Reduced motion

Every cell is lit at once, with no stagger.

### Accessibility

- It's a `meter` (Base UI Meter) named by its visible `label`; without one, give it `aria-label`.
- The value is spoken with its band: "88%, High". A warning or danger band without a label is spoken as "Warning" or "Critical".
- The cells are hidden from assistive tech. They fill from the inline start, so right to left in RTL.

---

# Share Bar

> Show a share of a total in a table cell or list row.

Source: https://www.youj.dev/docs/components/share-bar

## Examples

### Demo

```tsx
'use client'

import { ShareBar, type ShareBarTone } from '@youj/react'

const PLANS: { name: string; mrr: string; share: number; tone: ShareBarTone }[] = [
  { name: 'Business', mrr: '€41,630', share: 0.412, tone: 'accent' },
  { name: 'Team', mrr: '€29,810', share: 0.295, tone: 'chart-2' },
  { name: 'Enterprise', mrr: '€19,390', share: 0.192, tone: 'chart-3' },
  { name: 'Starter', mrr: '€7,960', share: 0.079, tone: 'warning' },
  { name: 'Legacy', mrr: '€2,230', share: 0.022, tone: 'neutral' },
]
const pct = new Intl.NumberFormat('en-US', { style: 'percent', minimumFractionDigits: 1 })

export default function ShareBarDemo() {
  return (
    <ul className="flex w-full max-w-md flex-col divide-y divide-line rounded-xl border border-line bg-surface px-4 text-ui">
      {PLANS.map((row) => (
        <li key={row.name} className="flex items-center gap-4 py-2.5">
          <span className="w-24 truncate">{row.name}</span>
          <span className="w-16 text-end font-mono text-fg-muted tabular-nums">{row.mrr}</span>
          {/* The percentage beside it says the value, so the bar is decorative. */}
          <ShareBar value={row.share} segments={24} tone={row.tone} className="flex-1" />
          <span className="w-12 text-end font-mono tabular-nums">{pct.format(row.share)}</span>
        </li>
      ))}
    </ul>
  )
}
```

A plan list where each row has a revenue figure, a segmented share bar and a percentage.

### Named

```tsx
'use client'

import { useState } from 'react'
import { Button, ShareBar } from '@youj/react'

export default function ShareBarSolid() {
  const [value, setValue] = useState(0.62)
  return (
    <div className="flex w-72 flex-col gap-3">
      {/* Named, so it's a meter: nothing beside it says the value. */}
      <ShareBar value={value} tone="success" label="Pass rate" />
      <ShareBar value={value} segments={24} tone="success" label="Pass rate, in cells" />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setValue(Math.round(Math.random() * 100) / 100)}>
        New value
      </Button>
    </div>
  )
}
```

Two named bars, solid and segmented, at the same value, with a button that picks a new one.

With `label` the bar is a `meter`: screen readers hear its name and the share as a percentage in the provider's locale (or your `valueText`). Without it the bar is decorative and hidden from assistive technology, which is right when the number sits beside it, as it does in a table cell. That's the default because it's the common case: a meter and a visible number would say the same thing twice.

### Ticks

```tsx
'use client'

import { useState } from 'react'
import { ShareBar, type ShareBarTone } from '@youj/react'

const SUITES: { label: string; value: number; tone: ShareBarTone; color: string }[] = [
  { label: 'Passing', value: 34, tone: 'success', color: 'var(--color-success)' },
  { label: 'Flaky', value: 7, tone: 'warning', color: 'var(--color-warning)' },
  { label: 'Failing', value: 3, tone: 'danger', color: 'var(--color-danger)' },
  { label: 'Skipped', value: 12, tone: 'neutral', color: 'var(--color-fg-subtle)' },
]

export default function ShareBarTicks() {
  const [active, setActive] = useState<number | null>(null)
  return (
    <div className="flex w-full max-w-xs flex-col gap-3 rounded-xl border border-line bg-surface p-4 text-ui">
      <div className="flex items-baseline justify-between">
        <span className="font-medium">Test suites</span>
        <span className="font-mono text-ui-sm text-fg-muted tabular-nums">56 suites</span>
      </div>
      <ShareBar parts={SUITES} segments={48} mark="tick" active={active} label="Test suites by result" />
      <ul className="flex flex-wrap gap-x-4 gap-y-1.5 text-ui-sm">
        {SUITES.map((suite, i) => (
          <li key={suite.label} className="flex items-center gap-1.5" onPointerEnter={() => setActive(i)} onPointerLeave={() => setActive(null)}>
            <span aria-hidden className="size-2 rounded-full" style={{ backgroundColor: suite.color }} />
            <span className="font-mono font-medium tabular-nums">{suite.value}</span>
            <span className="text-fg-muted">{suite.label}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

Test suites by result as a run of ticks, over a legend of counts that points at its part.

`mark="tick"` draws each of the `segments` as a hairline on a taller bar, colored by the part it falls in. Hovering a legend entry passes its index to `active`, which quiets the other parts.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add share-bar
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a share bar to show how much of a whole one row takes: a plan's share of revenue, a suite's pass rate, a volume against its size. It's a mark, not a chart: no axis and no tooltip, so put the number beside it. For the shape of values over time use a [Sparkline](https://www.youj.dev/docs/components/sparkline); for how a whole divides into parts at once, a [Treemap](https://www.youj.dev/docs/components/treemap).

```tsx
import { ShareBar } from '@youj/react'

<ShareBar value={0.412} segments={24} tone="accent" />
<ShareBar value={268} max={480} tone="neutral" label="Build minutes used" />
```

`value` is a share from 0 to 1, or a value out of `max`. Without `segments` it's one solid bar; with it, it's a run of that many cells, and the value rounds to whole cells: any share above zero lights at least one, and only a full share lights them all. `tone` takes the accent, a chart color (`chart-1` to `chart-5`), a status (`success`, `warning`, `danger`) or `neutral`. Give it a width from its container; the height is 6px solid and 12px in cells, and a class changes it.

With `parts` the fill is a whole split into its parts, each in its `tone` (the chart colors in order by default), from the inline start; `max` defaults to their sum, so they fill the bar. In cells, each part gets whole cells and any part above zero keeps one. `mark="tick"` draws the segments as hairlines on a taller bar instead of cells. `active` lights one part and quiets the rest: pair the bar with a [Breakdown List](https://www.youj.dev/docs/components/breakdown-list) and pass its `onActiveChange` here, so pointing at a row lights its segment.

```tsx
<ShareBar parts={[{ value: 61_420 }, { value: 38_960 }, { value: 21_310 }]} active={active} />
```

In a table where every row is a share of the same whole, pass the largest share as `max` so the top row fills its bar and the rest compare to it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | The share, 0–1. With `max`, a value out of `max`. With `parts`, default their sum. |
| `max` | `number` |  | What `value` is out of. Default 1, or the parts' sum. |
| `parts` | `readonly ShareBarPart[]` |  | Split the fill into parts, each in its tone, from the inline start. |
| `active` | `number \| null` |  | With `parts`: the part to light; the others quiet. `null` or undefined lights all. |
| `segments` | `number` |  | Draw this many cells instead of one solid bar. |
| `mark` | `'cell' \| 'tick'` | `'cell'` | With `segments`: how each is drawn, a `cell` (default) or a thin `tick` on a taller bar, for a count-like run. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The fill's color: the accent, a chart color, a status or neutral. |
| `label` | `string` |  | Accessible name. With it the bar is a `meter`; without, it is hidden from assistive technology. |
| `valueText` | `string` |  | The value as spoken. Default: the share as a percentage, in the provider's locale. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fill | `spring.smooth` | 0.36s, bounce 0 | the edge travels from empty when half the bar scrolls into view, once; a clip, so cells and rounded ends never stretch |
| New value | `spring.smooth` | 0.36s, bounce 0 | retargets from where the edge is, so a burst of updates glides instead of restarting |

**Reduced motion:** Drawn at its value; a new value jumps.

#### Reduced motion

The bar is drawn at its value, and changes land at once.

### Accessibility

- With `label`, `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a percentage as `aria-valuetext`.
- Without `label` (or `aria-label`, `aria-labelledby`) it's `aria-hidden`: say the value in the text beside it.
- With `parts` and a `label`, the meter speaks each part's share when every part has a `label`: "Online 75%, Away 25%".
- The fill grows from the inline start, so it runs right to left in RTL.

---

# Hatched Bar

> Distinguish pending, projected or baseline amounts from settled values with hatching.

Source: https://www.youj.dev/docs/components/hatched-bar

## Examples

### Demo

```tsx
'use client'

import { Hatch, HatchedBar } from '@youj/react'

const RUNS = [84.1, 86.9, 85.2, 90.4, 88.6, 91.2, 87.9, 90.8, 92.5, 91.7, 90.9, 92.2, 90.7, 93.1]
const GATE = 90
const scale = (rate: number) => (rate - 80) / 20

export default function HatchedBarDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3 text-ui">
      <div className="relative h-32">
        <div aria-hidden className="absolute inset-x-0 border-t border-dashed border-(--color-success)" style={{ bottom: `${scale(GATE) * 100}%` }} />
        <div className="absolute inset-0 flex items-end gap-2">
          {RUNS.map((rate, i) => (
            <HatchedBar
              key={i}
              value={scale(rate)}
              fill={rate < GATE ? 'hatched' : 'solid'}
              tone={i === RUNS.length - 1 ? 'success' : 'neutral'}
              label={`Run ${i + 1}`}
              valueText={`${rate}%`}
              className="h-full w-auto flex-1"
            />
          ))}
        </div>
      </div>
      <div className="flex gap-4 text-ui-sm text-fg-muted">
        <span className="flex items-center gap-1.5">
          <Hatch className="size-3" /> Below the {GATE}% gate
        </span>
        <span className="flex items-center gap-1.5">
          <span aria-hidden className="size-3 rounded-[2px] bg-success" /> Latest run
        </span>
      </div>
    </div>
  )
}
```

Pass-rate bars for a run of builds: those under the gate are hatched, the latest is highlighted, and a dashed line marks the gate.

### A pending segment

```tsx
'use client'

import { Hatch } from '@youj/react'

const QUOTA = 400
const USED = 348
const PENDING = 118

export default function HatchedBarPending() {
  return (
    <div className="flex w-80 flex-col gap-2 text-ui">
      <div className="flex justify-between">
        <span>Quota</span>
        <span className="font-mono text-fg-muted tabular-nums">
          {USED} / {QUOTA} GB
        </span>
      </div>
      {/* Used is solid; what the cleanup will free is hatched inside it. The text below says both. */}
      <div aria-hidden className="flex h-2.5 overflow-hidden rounded-xs bg-well">
        <span className="bg-accent" style={{ width: `${((USED - PENDING) / QUOTA) * 100}%` }} />
        <Hatch tone="accent" className="rounded-none" style={{ width: `${(PENDING / QUOTA) * 100}%` }} />
      </div>
      <p className="text-ui-sm text-fg-muted">{PENDING} GB will be freed by the cleanup.</p>
    </div>
  )
}
```

A quota bar whose last segment is hatched to show what a cleanup will free.

`Hatch` fills whatever box you give it, so a stacked bar can end in what a job is about to free, or what a forecast adds.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add hatched-bar
```

It brings `youj-core`, `youj-ui-core` with it.

A hatch says "not settled": a baseline to compare against, an amount that's pending, projected or reserved, a run that missed its gate. `HatchedBar` is a bar of it that grows to a value, and `Hatch` is the fill on its own, for legend swatches and for a pending segment inside another bar. Keep solid for the actual amount beside it, so the two read as a pair.

```tsx
import { Hatch, HatchedBar } from '@youj/react'

<HatchedBar value={0.64} className="h-32 w-6" label="Projected usage" />
<HatchedBar value={0.72} fill="solid" tone="accent" orientation="horizontal" />
<Hatch className="size-3" />
```

`value` is out of `max` (default 1). A bar grows up from the bottom, or from the inline start when `orientation="horizontal"`; size it with classes. `fill="solid"` draws the settled amount: in `neutral` tone that's a quiet fill, so a colored bar beside it stands out. The hatch is diagonal stripes of the tone over a faint wash of it, so it follows the theme in both modes.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | The bar's length, out of `max`. |
| `max` | `number` | `1` |  |
| `fill` | `'hatched' \| 'solid'` | `'hatched'` | Hatched for a baseline, pending or projected amount; solid for an actual one. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Horizontal grows from the inline start. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'neutral'` |  |
| `label` | `string` |  | Accessible name. With it the bar is a `meter`; without, it is hidden from assistive technology. |
| `valueText` | `string` |  | The value as spoken. Default: the share of `max` as a percentage, in the provider's locale. |

Also takes the props of `ComponentProps<'div'>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'neutral'` | The stripes' color. |

Also takes the props of `ComponentProps<'span'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Grow | `spring.smooth` | 0.36s, bounce 0 | from its base when a third of it scrolls into view, once; a clip, so the stripes never stretch |
| New value | `spring.smooth` | 0.36s, bounce 0 | retargets from where it is |

**Reduced motion:** Drawn at its value; a new value jumps.

#### Reduced motion

Bars are drawn at their value, and changes land at once.

### Accessibility

- With `label` the bar is a `meter` with its orientation, and speaks its share of `max` as a percentage (or your `valueText`). Without, it's hidden from assistive technology.
- `Hatch` is always decorative: say what it marks in a legend or in the text beside it.
- A pattern is not a color, so hatched and solid stay apart in grayscale and for color-blind readers.

---

# Cell Bar

> Show a total built from its periods: a cell per month, each as wide as its amount, settled or projected, against a target.

Source: https://www.youj.dev/docs/components/cell-bar

## Examples

### Demo

```tsx
'use client'

import { CellBar, type CellBarCell } from '@youj/react'

const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
/** Twelve months, the first nine settled and the rest forecast. */
const cellsOf = (values: number[]): CellBarCell[] => values.map((value, i) => ({ label: MONTHS[i]!, value, projected: i >= 9 }))
const usd = (v: number) => `$${Math.round(v).toLocaleString('en-US')}`

/** A made-up bakery's year of ingredients, each against its plan. */
const ROWS = [
  { name: 'Flour', tone: 'warning', plan: 4800, cells: cellsOf([310, 320, 340, 360, 390, 420, 460, 500, 540, 560, 590, 620]) },
  { name: 'Butter', tone: 'success', plan: 4400, cells: cellsOf([420, 410, 390, 360, 330, 300, 280, 270, 260, 255, 250, 245]) },
  { name: 'Sugar', tone: 'neutral', plan: 1500, cells: cellsOf([120, 125, 118, 122, 130, 126, 124, 128, 125, 125, 125, 125]) },
] as const

export default function CellBarDemo() {
  return (
    <div className="grid w-full max-w-lg grid-cols-[5rem_minmax(0,1fr)] items-center gap-x-3 gap-y-4 text-ui">
      {ROWS.map((row) => (
        <div key={row.name} className="contents">
          <span className="text-fg-muted">{row.name}</span>
          <CellBar cells={row.cells} max={6000} target={row.plan} tone={row.tone} formatValue={usd} label={`${row.name}, by month`} />
        </div>
      ))}
    </div>
  )
}
```

A made-up bakery's year of ingredients on one scale, each against its plan. Flour runs past its plan's dashed tick, butter shrinks under it; the last three months of each are forecast, so they are hatched.

### Captions and a named target

```tsx
'use client'

import { CellBar } from '@youj/react'

const usd = (v: number) => `$${Math.round(v).toLocaleString('en-US')}`

export default function CellBarQuarters() {
  return (
    <div className="w-full max-w-lg">
      <CellBar
        cells={[
          { label: 'Q1', value: 4180 },
          { label: 'Q2', value: 4620 },
          { label: 'Q3', value: 5240 },
          { label: 'Q4', value: 5710, projected: true },
        ]}
        target={18400}
        targetLabel="Plan"
        tone="chart-2"
        captions
        formatValue={usd}
        label="Spend by quarter"
      />
    </div>
  )
}
```

`captions` writes each cell's label and amount under it, for a few wide cells like quarters, and `targetLabel` names the tick.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add cell-bar
```

It brings `hatched-bar`, `tooltip`, `youj-core`, `youj-labels-cell-bar`, `youj-presets`, `youj-ui-core` with it.

Use a cell bar where a total's length and its rhythm both matter: spend by month against a budget, hours by week against a plan, a quarter's revenue by month. Rows of them on one `max` compare totals, and each bar still shows how its total grew. For shares of a whole use a [Share Bar](https://www.youj.dev/docs/components/share-bar); for one settled or pending amount, a [Hatched Bar](https://www.youj.dev/docs/components/hatched-bar). The [Plan vs actual](https://www.youj.dev/docs/blocks/rankings-and-breakdowns#plan-vs-actual) card is built on it.

```tsx
import { CellBar } from '@youj/react'

<CellBar
  label="nightly-summarizer, by month"
  cells={[
    { label: 'Aug', value: 980 },
    { label: 'Sep', value: 1060 },
    { label: 'Oct', value: 1120, projected: true },
  ]}
  max={10000}
  target={6240}
  tone="warning"
  formatValue={(v) => `$${v.toLocaleString('en-US')}`}
/>
```

Each cell is as wide as its `value`, with a 2px gap between cells; the bar runs to its total on a scale that ends at `max` (by default the total, or the target if larger). `projected` cells are hatched in the tone. `target` puts a dashed tick on the same scale, and `targetLabel` names it over the tick. `formatValue` writes amounts in the tooltips, captions and summary.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cells` (required) | `readonly CellBarCell[]` |  |  |
| `max` | `number` |  | The scale's end, the same for bars that compare. Default: the cells' total (or the target, if larger). |
| `target` | `number` |  | A plan or budget on the same scale: a dashed tick through the bar. |
| `targetLabel` | `string` |  | Written over the target's tick: "Plan". |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The cells' color. |
| `captions` | `boolean` | `false` | Each cell's label and amount under it, for a few wide cells. |
| `formatValue` | `(value: number) => string` |  | Writes an amount: "$1,240". Default: the locale's number format. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Cell bar". |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `cell-bar`, `cell-bar-track`, `cell-bar-cells`, `cell-bar-cell`, `cell-bar-target`, `cell-bar-target-label`, `cell-bar-captions`, `cell-bar-caption`, `cell-bar-tooltip` and `cell-bar-summary`. The root has `data-tone`, and a projected cell `data-yj-projected`. The tone is `--cell-bar-tone`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `spring.smooth` | 0.36s, bounce 0 | the cells open from the inline start when half the bar scrolls into view (a clip, so they never stretch) |
| Reflow | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | a new amount widens or narrows its cell and the bar |

**Reduced motion:** Drawn at its values; changes land at once.

#### Reduced motion

The cells are drawn at their widths, and a new amount lands at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Cell bar") described by its total, the part that is projected and the target ("$9,710 in all. $3,540 of it projected. Target $6,240.").
- The cells are a list; each is read with its period and amount, and says when it is projected ("Oct: $1,120, projected").
- One tab stop. The arrow keys walk the cells (mirrored in RTL), `Home` and `End` go to the ends, and focus shows the same tooltip as hovering.
- Projected cells are hatched as well as tinted, and the target is a dashed tick, so neither leans on color alone.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Diff Bar

> Compare values from models, runs or periods, with the better result highlighted.

Source: https://www.youj.dev/docs/components/diff-bar

## Examples

### Demo

```tsx
'use client'

import { DiffBar, type DiffBarProps } from '@youj/react'

const PCT: Intl.NumberFormatOptions = { style: 'unit', unit: 'percent', maximumFractionDigits: 1 }

const ROWS: (DiffBarProps & { id: string })[] = [
  { id: 'accuracy', label: 'Accuracy', a: 91.2, b: 92.4, format: PCT },
  { id: 'latency', label: 'Latency p95', a: 1840, b: 910, better: 'lower', format: { style: 'unit', unit: 'millisecond' } },
  { id: 'cost', label: 'Cost / 1K runs', a: 4.1, b: 1.35, better: 'lower', format: { style: 'currency', currency: 'USD' } },
  { id: 'faithfulness', label: 'Faithfulness', a: 88.4, b: 86.9, format: PCT },
  { id: 'toxicity', label: 'Toxicity', a: 0.4, b: 0.4, better: 'lower', format: PCT },
]

export default function DiffBarDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-5 rounded-2xl border border-line bg-surface p-5">
      {ROWS.map(({ id, ...row }) => (
        <DiffBar key={id} {...row} names={['Large', 'Mini']} />
      ))}
    </div>
  )
}
```

Rows comparing Large against Mini, each side growing from a shared center.

### Stacked

```tsx
'use client'

import { Alert, AlertTitle, DiffBar } from '@youj/react'

export default function DiffBarStacked() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4 rounded-2xl border border-line bg-surface p-5">
      <DiffBar
        layout="stacked"
        label="Increase for next year"
        names={['Allowed', 'Quoted']}
        a={18_000}
        b={31_500}
        better="lower"
        segments={0}
        format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}
        by="$13,500"
      />
      <Alert variant="danger">
        <AlertTitle>The quote is $13,500 over the allowance. Push back before the notice date.</AlertTitle>
      </Alert>
    </div>
  )
}
```

What an agreement allows against what was quoted, as two rows on one scale, with the overage in the danger tone.

`layout="stacked"` draws each side as a row from the inline start, named by `names`. Both are lit in `tone` up to the smaller value; past it, the worse side's excess is drawn in danger and its value in the danger ink, so an overage reads at a glance. With `better="higher"` the better side is the longer one and stays in the tone.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add diff-bar
```

It brings `typography`, `youj-core`, `youj-labels-diff-bar`, `youj-presets`, `youj-ui-core` with it.

Use a diff bar to compare two values of one measure: two models on accuracy, this month's latency against last month's, a candidate against production. Each side grows out from a shared center toward its own end, A to the start and B to the end, in cells you can count, and the better side is lit. Stack them and every row shares one center line, so a table of them reads as a verdict at a glance. For one row's share of a whole use a [Share Bar](https://www.youj.dev/docs/components/share-bar); for a baseline beside the actual, a [Hatched Bar](https://www.youj.dev/docs/components/hatched-bar).

```tsx
import { DiffBar, diffWinner } from '@youj/react'

diffWinner(1840, 910, 'lower') // 'b'
```

`better` says which way wins: `higher` (the default) or `lower`. A difference under `tolerance` of the larger value (half a percent by default) is even, and lights neither side. Each side's full length is the larger value, or your `max` when several bars should share a scale. `format` and `locale` set how the values read, `segments` how many cells each side has (14; `0` draws solid bars), and `tone` the lit side's color (the accent, a status or a chart color).

`layout` is `diverging` (the default, out from a shared center) or `stacked` (two rows on one scale, the worse side's excess in danger).

`diffWinner(a, b, better, tolerance)` returns the same verdict (`'a'`, `'b'` or `'even'`), for a chip or a count of wins beside the bars.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `a` (required) | `number` |  | The start side's value. |
| `b` (required) | `number` |  | The end side's value. |
| `max` | `number` |  | Each side's full length. Default: the larger of the two. |
| `better` | `'higher' \| 'lower'` | `'higher'` | Which way is better. |
| `label` | `ReactNode` |  | The measure, shown above the bar: "Accuracy". |
| `names` | `[string, string]` | `['A', 'B']` | The sides' names for the verdict. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the values. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `segments` | `number` | `14` | Cells per side. |
| `tone` | `'accent' \| 'success' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The better side's tone. |
| `tolerance` | `number` | `0.005` | A difference under this share of the larger value is even. |
| `by` | `string` |  | The margin as spoken in the verdict. Default: the relative difference, as a percentage. |
| `showValues` | `boolean` | `true` | Show the values at the ends, each in a column `--diff-bar-value` wide (4.5rem), so stacked bars share one center. |
| `layout` | `'diverging' \| 'stacked'` | `'diverging'` | `diverging` (default): the sides grow out from a shared center. `stacked`: two rows on one scale, named by `names`, the worse side's excess in danger. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `diff-bar` (with `data-winner`, and `data-variant`: `diverging` or `stacked`), `diff-bar-name` (stacked), `diff-bar-label`, `diff-bar-row`, `diff-bar-value` and `diff-bar-track` (each with `data-side`), `diff-bar-cell` (with `data-state`), `diff-bar-bar`, `diff-bar-fill` (stacked: with `data-part`, `shared` or `excess`), `diff-bar-center` and `diff-bar-verdict`. The value columns are `--diff-bar-value` wide (4.5rem), so stacked bars share one center; widen it for longer values.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate` | 560ms | both sides light outward from the center at one constant rate, so the longer side takes longer, once half the bar is in view |
| New value | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | cells light or darken in place |

**Reduced motion:** Drawn at once.

#### Reduced motion

The cells are lit at once, and a new value lands in place.

### Accessibility

- The values are text at the bar's ends, read in order, and a visually hidden verdict follows them: "Mini is better by 51%", or "Even". The margin is relative to the worse side unless you pass `by` ("1.2 points").
- `names` name the sides in the verdict (`['A', 'B']` by default).
- The cells are decorative (`aria-hidden`).
- The start side grows toward the inline start, so the bar mirrors in RTL.
- Its words come from the labels (`diffBetter`, `diffEven`), translated by the language packs.

---

# Carousel

> Browse slides by swiping, dragging or stepping through controls, with optional autoplay.

Source: https://www.youj.dev/docs/components/carousel

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Badge } from '@youj/react'
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  CarouselThumb,
  CarouselThumbs,
  type CarouselApi,
} from '@youj/react/carousel'

// Drawn from theme tokens, so the photos work in both themes and every preset; named so the names hold in every preset too.
const SHOTS = [
  { name: 'Signature', tone: 'var(--color-accent)' },
  { name: 'Moss', tone: 'var(--color-success)' },
  { name: 'Amber', tone: 'var(--color-warning)' },
  { name: 'Clay', tone: 'var(--color-danger)' },
  { name: 'Mono', tone: 'var(--color-fg)' },
]

function Speaker({ tone, small }: { tone: string; small?: boolean }) {
  const body = `color-mix(in oklab, ${tone} 78%, var(--color-surface))`
  const grille = `color-mix(in oklab, ${tone} 55%, var(--color-fg))`
  return (
    <div
      className="grid size-full place-items-center"
      style={{ background: `radial-gradient(120% 90% at 50% 20%, color-mix(in oklab, ${tone} 16%, var(--color-surface)), color-mix(in oklab, ${tone} 6%, var(--color-canvas)) 70%)` }}
    >
      <svg viewBox="0 0 200 160" className={small ? 'w-[80%]' : 'w-[52%]'} aria-hidden>
        <ellipse cx="100" cy="146" rx="58" ry="6" fill="var(--color-fg)" opacity="0.12" />
        <rect x="46" y="14" width="108" height="128" rx="26" fill={body} />
        {Array.from({ length: 42 }, (_, i) => (
          <circle key={i} cx={64 + (i % 7) * 12} cy={48 + Math.floor(i / 7) * 12} r="2.4" fill={grille} opacity="0.8" />
        ))}
      </svg>
    </div>
  )
}

export default function CarouselDemo() {
  const [api, setApi] = useState<CarouselApi>()
  const [current, setCurrent] = useState(0)

return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Carousel
        setApi={setApi}
        onSlideChange={setCurrent}
        opts={{ loop: true }}
        aria-label="Arc speaker photos"
        className="group/gallery overflow-hidden rounded-xl border border-line bg-surface"
      >
        <CarouselContent className="ms-0">
          {SHOTS.map((shot, i) => (
            <CarouselItem key={shot.name} aria-label={`${shot.name}, ${i + 1} of ${SHOTS.length}`} className="aspect-[4/3] ps-0">
              <Speaker tone={shot.tone} />
            </CarouselItem>
          ))}
        </CarouselContent>
        {/* Inside the frame, shown on hover or focus (always on touch). */}
        <CarouselPrevious className="start-3 opacity-0 group-hover/gallery:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100" />
        <CarouselNext className="end-3 opacity-0 group-hover/gallery:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100" />
        <Badge variant="secondary" className="absolute end-3 top-3 bg-canvas/80 youj-allow-glass tabular-nums backdrop-blur">
          {current + 1} / {SHOTS.length}
        </Badge>
        <CarouselThumbs className="border-t border-line bg-canvas px-3 py-3">
          {SHOTS.map((shot, i) => (
            <CarouselThumb key={shot.name} index={i} aria-label={shot.name} className="size-14 border border-line">
              <Speaker tone={shot.tone} small />
            </CarouselThumb>
          ))}
        </CarouselThumbs>
      </Carousel>
      <div className="flex items-center gap-3">
        <span className="text-ui-sm text-fg-muted">
          Color <span className="font-medium text-fg">{SHOTS[current]!.name}</span>
        </span>
        {/* Anything can drive the carousel through its api. */}
        <div role="group" aria-label="Color" className="ms-auto flex gap-2">
          {SHOTS.map((shot, i) => (
            <button
              key={shot.name}
              type="button"
              aria-label={shot.name}
              aria-pressed={i === current}
              onClick={() => api?.scrollTo(i)}
              className="size-6 rounded-full border border-line outline-none focus-ring aria-pressed:ring-2 aria-pressed:ring-focus aria-pressed:ring-offset-2 aria-pressed:ring-offset-canvas"
              style={{ background: `color-mix(in oklab, ${shot.tone} 78%, var(--color-surface))` }}
            />
          ))}
        </div>
      </div>
    </div>
  )
}
```

A carousel of five product shots with a thumbnail strip and Previous and Next buttons.

`CarouselThumbs` holds one `CarouselThumb` per slide, and `CarouselDots` renders one dot per snap. Both wear a [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator) that glides to the current slide, and the thumbnail strip scrolls the current thumbnail into view.

### Autoplay

```tsx
'use client'

import {
  Carousel,
  CarouselAutoplayToggle,
  CarouselCaption,
  CarouselContent,
  CarouselDots,
  CarouselItem,
} from '@youj/react/carousel'

const STORIES = [
  { title: 'Studio sessions', body: 'Recorded live at Arc HQ with three artists and one speaker.', tone: 'var(--color-accent)' },
  { title: 'The acoustic lab', body: 'How a 12mm driver learned to fill a room.', tone: 'var(--color-success)' },
  { title: 'Made to be carried', body: 'Recycled aluminum, one seam, no screws.', tone: 'var(--color-warning)' },
  { title: 'Night mode', body: 'Warmer and quieter after ten, without a tap.', tone: 'var(--color-danger)' },
]

export default function CarouselAutoplay() {
  return (
    <Carousel autoplay={4000} opts={{ loop: true }} aria-label="Featured stories" className="w-full max-w-xl">
      <CarouselContent>
        {STORIES.map((story) => (
          <CarouselItem key={story.title}>
            <div
              className="flex aspect-[21/9] items-end overflow-hidden rounded-xl border border-line p-5"
              style={{
                background: `linear-gradient(135deg, color-mix(in oklab, ${story.tone} 26%, var(--color-surface)), color-mix(in oklab, ${story.tone} 8%, var(--color-canvas)))`,
              }}
            >
              <CarouselCaption className="flex max-w-sm flex-col gap-1">
                <h3 className="text-[19px] leading-7 font-semibold tracking-tight text-fg">{story.title}</h3>
                <p className="text-ui text-fg-muted">{story.body}</p>
              </CarouselCaption>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <div className="mt-3 flex items-center justify-between">
        <CarouselAutoplayToggle />
        <CarouselDots />
        <span className="w-8" />
      </div>
    </Carousel>
  )
}
```

A carousel that advances on a timer, with a play and pause toggle.

`autoplay` advances on a timer: `true` for five seconds a slide, or a number of milliseconds. It pauses while the pointer is over the carousel, while focus is inside it, while it's dragged and while the tab is hidden. `CarouselAutoplayToggle` is its play and pause button, and draws the slide's elapsed time as a ring that fills until the next slide. `CarouselCaption` rises into place as its slide arrives.

Autoplay never starts under reduced motion. The toggle still starts it, because pressing play is a choice.

### Slides per view

```tsx
'use client'

import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@youj/react'
import {
  Carousel,
  CarouselContent,
  CarouselDots,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from '@youj/react/carousel'

const PLANS = [
  { name: 'Starter', for: 'solo builders', price: 0 },
  { name: 'Team', for: 'small teams', price: 12 },
  { name: 'Growth', for: 'growing teams', price: 29 },
  { name: 'Scale', for: 'many teams', price: 59 },
  { name: 'Education', for: 'classrooms', price: 4 },
  { name: 'Non-profit', for: 'charities', price: 6 },
]

export default function CarouselSlidesPerView() {
  return (
    <div className="w-full max-w-xl px-12">
      {/* One card per view on phones, two from sm; each snap moves by a page. */}
      <Carousel opts={{ align: 'start', slidesToScroll: 'auto' }} aria-label="Plans">
        <CarouselContent>
          {PLANS.map((plan) => (
            <CarouselItem key={plan.name} className="sm:basis-1/2">
              <Card className="h-full">
                <CardHeader>
                  <CardTitle>{plan.name}</CardTitle>
                  <CardDescription>For {plan.for}.</CardDescription>
                </CardHeader>
                <CardContent>
                  <p className="text-[22px] font-semibold text-fg tabular-nums">${plan.price}</p>
                </CardContent>
              </Card>
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
        <CarouselDots className="mt-3" />
      </Carousel>
    </div>
  )
}
```

Several slides in view at once.

Give `CarouselItem` a basis to show several slides at once, such as `sm:basis-1/2 lg:basis-1/3`. With `slidesToScroll: 'auto'`, each snap moves by a page, and the dots count pages.

## Installation & usage

```bash
pnpm add @youj/react embla-carousel-react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add carousel
```

It brings `button`, `icon-chevron-left`, `icon-chevron-right`, `icon-play`, `sliding-indicator`, `youj-core`, `youj-labels-carousel`, `youj-presets`, `youj-ui-core` with it.

The copy is 15 registry items, about 8,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-chevron-left`, `icon-chevron-right`, `icon-engine`, `icon-loader-ring`, `icon-play`, `sliding-indicator`, `spinner`.

Requires `embla-carousel-react`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/carousel`.

It's shadcn's carousel on Embla, so swipe, drag, flick and looping use Embla's physics.

Use a carousel when there are more things than fit and seeing one at a time is the point: product photos, a gallery, a few featured stories. Everything after the first slide is easy to miss, so don't put anything people must see on slide three. For content people should scan and compare, lay it out in a grid or a [Scroll Area](https://www.youj.dev/docs/components/scroll-area) instead.

```tsx
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@youj/react/carousel'

export function Photos({ photos }: { photos: Photo[] }) {
  return (
    <Carousel aria-label="Product photos" opts={{ loop: true }}>
      <CarouselContent>
        {photos.map((photo) => (
          <CarouselItem key={photo.id}>
            <img src={photo.src} alt={photo.alt} />
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}
```

`opts` goes to Embla (`loop`, `align`, `slidesToScroll`, `dragFree`…). `setApi` hands you Embla's API, so anything can drive the carousel: the color swatches in the demo call `api.scrollTo(i)`. `onSlideChange` reports the current slide however it changed. The Previous and Next buttons sit outside the slides by default; move them inside with a class, as the demo does.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `opts` | `CarouselOptions` |  |  |
| `plugins` | `CarouselPlugin` |  |  |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
| `setApi` | `(api: CarouselApi) => void` |  |  |
| `autoplay` | `boolean \| number` | `false` | Advance on a timer: `true` for the default dwell (5000), or the dwell per slide in milliseconds. Pauses on hover, focus and drag; never starts under reduced motion. |
| `onSlideChange` | `(index: number) => void` |  | Called when the current slide changes, by any means. |

#### CarouselThumb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` (required) | `number` |  | The snap this thumbnail shows. |
| `children` (required) | `ReactNode` |  |  |

Also takes the props of `ComponentProps<'button'>`.

`CarouselContent`, `CarouselItem`, `CarouselCaption`, `CarouselDots` and `CarouselThumbs` are styled `div`s. `CarouselPrevious`, `CarouselNext` and `CarouselAutoplayToggle` take [Button](https://www.youj.dev/docs/components/button) props, with `variant` and `size` defaulting to `outline` and `icon-sm` (`ghost` for the toggle). `useCarousel()` reads the carousel's state from inside it.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Slide travel | `duration.slow` | 340ms | buttons, dots, thumbnails and arrow keys; Embla's integrator is tuned to land on the token |
| Drag and flick |  | pointer-driven | follows the finger, then Embla's own momentum |
| Dot and thumbnail indicator | `spring.smooth` | 0.36s, bounce 0 | glides to the current slide (SlidingIndicator) |
| Caption | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | rises 8px and fades in after a `loose` stagger as its slide arrives |
| Caption leaves | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Autoplay ring |  | the autoplay interval | draws the dwell; it is the timer |

**Reduced motion:** Buttons, dots and keys jump to the slide; drags still follow the finger. Captions are simply there, and autoplay doesn't start.

A Speed change re-initializes Embla with the new travel, so the Speed control reaches the slides too.

#### Reduced motion

Buttons, dots, thumbnails and keys jump straight to the slide, captions don't rise and autoplay doesn't start on its own. Dragging still follows the finger, because that movement is the person's own.

### Accessibility

- The carousel is a region with `aria-roledescription="carousel"`. Name it with `aria-label`.
- Each slide is a group with `aria-roledescription="slide"`, labeled with its position ("3 of 8") unless you give it an `aria-label` of your own, such as "Moss, 2 of 5".
- With focus inside the carousel (on a slide's control or the arrows), use Left and Right (Up and Down when vertical), Home and End. The arrows flip under RTL, and keys typed into a field inside a slide are left alone.
- A polite live region names the slide that's showing. It's silent while autoplay rotates, so it doesn't talk over the page every few seconds (WAI-ARIA APG).
- Previous and Next stay focusable when disabled at either end, so focus isn't dropped onto the page.
- Dots are buttons named "Slide 3", with `aria-current` on the current one, and each has a 24px hit area.

---

# Track Timeline

> Arrange segments on tracks along a time ruler, and move, trim and snap them by pointer or keyboard, such as video clips.

Source: https://www.youj.dev/docs/components/track-timeline

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { TrackTimeline, formatClipTime, type TimelineClip, type TimelineTrack } from '@youj/react'

// Loudness from 0 to 1, one sample a tenth of a second: from your audio pipeline, or decoded once and stored.
const speech = (seconds: number, seed: number) => Array.from({ length: seconds * 10 }, (_, i) => 0.2 + 0.6 * Math.abs(Math.sin(i * 0.3 * seed) * Math.cos(i * 0.05 + seed)))

// A short interview cut: the host, the guest and a music bed under them.
const TRACKS: TimelineTrack[] = [
  { id: 'host', name: 'Host', caption: 'Mic 1', peaks: speech(30, 1.1) },
  { id: 'guest', name: 'Guest', caption: 'Mic 2', peaks: speech(30, 2.3) },
  { id: 'music', name: 'Music bed', caption: 'Stereo', peaks: speech(30, 0.4) },
]
const CLIPS: TimelineClip[] = [
  { id: 'intro', track: 'host', name: 'intro', start: 0, end: 6 },
  { id: 'question', track: 'host', name: 'question', start: 13, end: 17, offset: 13 },
  { id: 'answer', track: 'guest', name: 'answer', start: 6.5, end: 12.5, offset: 6.5 },
  { id: 'story', track: 'guest', name: 'story', start: 17.5, end: 28, offset: 17.5 },
  { id: 'bed', track: 'music', name: 'bed', start: 0, end: 30, gain: -6 },
]

export default function TrackTimelineDemo() {
  const [clips, setClips] = useState(CLIPS)
  const [tracks, setTracks] = useState(TRACKS)
  const [selected, setSelected] = useState<string | null>('answer')
  const [position, setPosition] = useState(9)
  const clip = clips.find((c) => c.id === selected)
  return (
    <div className="flex w-full max-w-3xl flex-col gap-3">
      <TrackTimeline
        tracks={tracks}
        clips={clips}
        onClipsChange={setClips}
        onTrackChange={(id, change) => setTracks((list) => list.map((t) => (t.id === id ? { ...t, ...change } : t)))}
        duration={30}
        position={position}
        onPositionChange={setPosition}
        value={selected}
        onValueChange={setSelected}
        label="Interview"
      />
      <p className="font-mono text-ui-sm text-fg-muted tabular-nums">
        {clip ? `${clip.name} · ${formatClipTime(clip.start)}–${formatClipTime(clip.end)}` : 'Select a clip.'}
      </p>
    </div>
  )
}
```

A podcast edit on three tracks: Host, Guest and Music bed.

Moves and trims snap within 8px of another clip's edge, the playhead or either end; hold Alt to place freely, or pass `snap={false}`. The timeline opens with the whole of it in view (at least 8px a second); − and + (or Ctrl or ⌘ and the wheel) zoom about the playhead, and `zoom` controls it in pixels per second. Pass `playing` while your player runs: the level strips read each track at the playhead, and the lane turns the page as the playhead nears its end. The [Song Sketch](https://www.youj.dev/docs/blocks/media#track-arranger) block puts it together with a transport, an inspector and simulated playback.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add track-timeline
```

It brings `button`, `icon-minus`, `icon-plus`, `toggle`, `use-announcer`, `use-controllable-state`, `waveform-scrubber`, `youj-core`, `youj-labels-track-timeline`, `youj-presets`, `youj-ui-core` with it.

The copy is 18 registry items, about 8,300 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-engine`, `icon-loader-ring`, `icon-minus`, `icon-plus`, `spinner`, `toggle`, `use-announcer`, `use-controllable-state`, `waveform-scrubber`.

Use a track timeline for an edit made of parts on tracks: a podcast cut, a song sketch, a video's voice-over, a meeting's highlights. Each track is a lane in its chart color with its name, mute and solo keys and a level strip; each clip is a rounded bar holding the slice of the track's sound it plays, drawn from loudness samples you pass (it decodes no audio) and scaled by its gain. Drag a clip to move it, or its edges to trim it. Both snap to the other clips' edges and to the playhead, and a guide shows the edge they caught. A ruler of mono timecodes runs along the top, with the playhead on it. For a single recording's seek bar, use a [Waveform Scrubber](https://www.youj.dev/docs/components/waveform-scrubber).

```tsx
import { TrackTimeline } from '@youj/react'

<TrackTimeline
  tracks={[
    { id: 'host', name: 'Host', caption: 'Mic 1', peaks: hostPeaks },
    { id: 'music', name: 'Music bed', peaks: musicPeaks, muted: true },
  ]}
  clips={clips}
  onClipsChange={setClips}
  onTrackChange={(id, change) => updateTrack(id, change)}
  duration={30}
  position={time}
  onPositionChange={setTime}
  value={selected}
  onValueChange={setSelected}
/>
```

`clips` is controlled: every move and trim reports the whole list through `onClipsChange`. A clip sits from `start` to `end` on its `track`, plays its track's source from `offset`, and scales its wave by `gain` in decibels. A track's `peaks` are its whole source as loudness from 0 to 1, one sample every `resolution` seconds (0.1). A clip never moves into its neighbor on the same track, never trims past its source, and stays at least half a second long. `formatClipTime(seconds, locale)` formats times the way the timeline speaks them (0:12.5).

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tracks` (required) | `readonly TimelineTrack[]` |  |  |
| `clips` (required) | `readonly TimelineClip[]` |  | The clips (controlled): every move and trim reports the whole list. |
| `onClipsChange` | `(clips: TimelineClip[]) => void` |  |  |
| `onTrackChange` | `(id: string, change: { muted?: boolean; solo?: boolean }) => void` |  |  |
| `duration` (required) | `number` |  | The timeline's length, in seconds. |
| `position` | `number` |  | The playhead, in seconds (controlled). |
| `defaultPosition` | `number` | `0` |  |
| `onPositionChange` | `(seconds: number) => void` |  |  |
| `value` | `string \| null` |  | The selected clip's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` |  |
| `onValueChange` | `(id: string \| null) => void` |  |  |
| `zoom` | `number` |  | Pixels per second (controlled). Default: the whole timeline in view, at least 8. |
| `defaultZoom` | `number` |  |  |
| `onZoomChange` | `(pxPerSecond: number) => void` |  |  |
| `resolution` | `number` | `0.1` | Seconds per sample in the tracks' peaks. |
| `snap` | `boolean` | `true` | Snap moves and trims to the other clips' edges and the playhead. |
| `step` | `number` | `0.5` | Seconds an arrow key moves or trims a clip. |
| `playing` | `boolean` | `false` | While playing, the meters read the tracks at the playhead and the lane follows it. |
| `label` | `string` |  | The timeline's accessible name. Default: the labels' "Timeline". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | With sound on, catching a snap point plays `tick`. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `track-timeline` (with `data-dragging`), `track-timeline-heads`, `track-timeline-zoom`, `track-timeline-track-head` (with `data-muted` and `data-solo`), `track-timeline-track-name`, `track-timeline-track-caption`, `track-timeline-mute`, `track-timeline-solo`, `track-timeline-meter`, `track-timeline-lane`, `track-timeline-ruler`, `track-timeline-ruler-control`, `track-timeline-ruler-track`, `track-timeline-time`, `track-timeline-playhead`, `track-timeline-tracks`, `track-timeline-track`, `track-timeline-clip` (with `data-selected` and `data-muted`), `track-timeline-clip-name`, `track-timeline-wave`, `track-timeline-handle` (with `data-edge`), `track-timeline-playhead-line` and `track-timeline-snap`. In [Bezel](https://www.youj.dev/docs/looks) the track captions are mono capital eyebrows and the timecodes and clip names are mono. On a narrow timeline the heads keep the name, the keys and the level strip.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Playing | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | each level strip eases between readings as the playhead passes through the track’s clips |
| Drag and trim |  |  | the clip and its edges follow the pointer, never eased; a snap shows its guide at once |
| Handles | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | a trim handle thickens on hover |

**Reduced motion:** The level strips jump to each reading; everything else was never eased.

#### Reduced motion

The level strips jump to each reading instead of easing. Dragging, trimming and the playhead are unchanged, since they never animate.

### Accessibility

- The timeline is a group named by `label` (default "Timeline"), and each track a group named by the track. Every clip is a button and a tab stop, named by its name, range and track ("answer, 0:06.5 to 0:12.5, Guest") and described by a hint that explains the keys.
- Focusing a clip selects it (`aria-pressed`). Arrow keys move it by `step` (half a second), Shift ten times as far, stopping at the first snap point on the way; the new range is announced. Escape lets go of it.
- The selected clip's edges come next in the tab order, as sliders named "Start of answer" and "End of answer" that trim it from the keyboard.
- The playhead is a slider on the ruler, spoken as the time and the length ("0:09.0 of 0:30.0"). Mute and solo are toggle buttons named with their track ("Mute Guest").
- Time runs left to right in every script, like a tape, so the lane keeps its direction under RTL, the arrow keys included; the heads and their text follow the page.
- With sound on, catching a snap point while dragging plays `tick`.
- Its words come from the labels (`trackTimeline`, `trackTimelineHint`, `trackTimelineClip`, `trackTimelineRange`, `trackTimelineClipStart`, `trackTimelineClipEnd`, `trackTimelineMute`, `trackTimelineSolo`, `trackTimelinePlayhead`, `zoomIn`, `zoomOut`), translated by the language packs.

---

# Annotated Image

> Point at parts of an image with numbered callouts joined by leader lines to their labels.

Source: https://www.youj.dev/docs/components/annotated-image

## Examples

### Demo

```tsx
'use client'

import type { CSSProperties } from 'react'
import { AnnotatedImage, type ImageAnnotation } from '@youj/react'

/* Its rubber, frame and cab stay darker than the box in both themes (`--yj-dark` picks each mix), so it never inverts into a pale cab on pale tires. */
const PALETTE = {
  '--truck-cab': 'color-mix(in oklab, var(--color-fg) calc(78% - 52% * var(--yj-dark)), var(--color-surface))',
  '--truck-rubber': 'color-mix(in oklab, var(--color-fg) calc(100% - 100% * var(--yj-dark)), var(--color-canvas))',
  '--truck-frame': 'color-mix(in oklab, var(--color-fg) calc(70% - 70% * var(--yj-dark)), var(--color-canvas))',
  '--truck-rim': 'color-mix(in oklab, var(--color-fg) calc(26% + 22% * var(--yj-dark)), var(--color-surface))',
} as CSSProperties

/** A flat side view of a refrigerated truck, drawn in the theme's tones: stands in for your photo. */
function Truck() {
  return (
    <svg viewBox="0 0 640 300" role="img" aria-label="Refrigerated truck, side view" style={PALETTE} className="block h-auto w-full bg-[color-mix(in_oklab,var(--color-fg)_4%,var(--color-surface))]">
      <ellipse cx="330" cy="262" rx="290" ry="9" className="fill-well" />
      <rect x="56" y="66" width="384" height="152" rx="10" className="fill-[color-mix(in_oklab,var(--color-fg)_3%,var(--color-surface))] stroke-line-strong" strokeWidth="1.5" />
      {Array.from({ length: 9 }, (_, i) => (
        <line key={i} x1={94 + i * 38} x2={94 + i * 38} y1="74" y2="210" className="stroke-line" strokeWidth="1.5" />
      ))}
      <rect x="442" y="82" width="26" height="72" rx="4" className="fill-(--truck-cab)" />
      <path d="M472 108 L538 108 Q560 108 568 126 L590 168 Q596 178 596 190 L596 222 L472 222 Z" className="fill-(--truck-cab)" />
      <path d="M540 120 L554 120 Q562 120 566 130 L578 160 L540 160 Z" className="fill-[color-mix(in_oklab,var(--color-accent)_30%,var(--color-surface))]" />
      <rect x="482" y="194" width="50" height="18" rx="9" className="fill-(--truck-rim)" />
      <rect x="56" y="218" width="540" height="10" rx="3" className="fill-(--truck-frame)" />
      {[118, 170, 392, 540].map((cx) => (
        <g key={cx}>
          <circle cx={cx} cy="236" r="24" className="fill-(--truck-rubber) stroke-line-strong" strokeWidth="1" />
          <circle cx={cx} cy="236" r="9" className="fill-(--truck-rim)" />
        </g>
      ))}
    </svg>
  )
}

const NOTES: ImageAnnotation[] = [
  { id: 'reefer', x: 62, y: 28, title: 'Reefer unit', detail: '34.1°F · set 34°F' },
  { id: 'load', x: 34, y: 46, title: 'Load', detail: '14 of 26 pallets · 8,420 lb' },
  { id: 'cab', x: 89, y: 44, title: 'Driver', detail: 'On duty 6 h 12 min' },
  { id: 'fuel', x: 71, y: 72, title: 'Fuel', detail: '64% · 412 mi range' },
  { id: 'axles', x: 22, y: 79, title: 'Trailer axles', detail: 'Tire pressure normal' },
]

export default function AnnotatedImageDemo() {
  return (
    <div className="w-full max-w-4xl">
      <AnnotatedImage annotations={NOTES} media={<Truck />} caption="Unit TR-5531 · last reading 2 min ago" />
    </div>
  )
}
```

A refrigerated truck drawn in the theme's tones, with numbered callouts joined by leader lines to labels in the gutters.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add annotated-image
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-annotated-image`, `youj-presets`, `youj-ui-core` with it.

Use an annotated image to say what matters in a picture: a vehicle's sensors, the parts of a product, the regions of a screenshot. Each point carries its number and a leader line runs to its label in the gutter beside the media, so the eye goes from the point along the line to the words. For a sequence of screens to step through, use a [Carousel](https://www.youj.dev/docs/components/carousel).

```tsx
import { AnnotatedImage, type ImageAnnotation } from '@youj/react'

const notes: ImageAnnotation[] = [
  { id: 'reefer', x: 71, y: 34, title: 'Reefer unit', detail: '34.1°F · set 34°F' },
  { id: 'load', x: 40, y: 44, title: 'Load', detail: '14 of 26 pallets' },
]

<AnnotatedImage src="/truck.jpg" alt="Refrigerated truck, side view" annotations={notes} />
```

A point sits at `x` and `y`, from 0 to 100 across and down the media. Its label goes in the gutter on the point's side, or the one `side` names; labels in a gutter keep their order and are nudged apart so they never overlap, and they follow the media as it resizes. Under 40rem of its own width the gutters fold into a numbered list under the media, without lines. Pass `media` instead of `src` for a video, an illustration or a canvas, and `caption` for a line under the figure.

Hovering or focusing a callout, or hovering its label, lights the pair. Pressing a callout pins it: `value`, `defaultValue` and `onValueChange` hold the pinned id, or `null`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `annotations` (required) | `ImageAnnotation[]` |  |  |
| `src` | `string` |  | The image. Leave it out and pass `media` for anything else. |
| `alt` | `string` | `''` | The image's text alternative. |
| `media` | `ReactNode` |  | Your own media in place of the image: a video, an illustration, a canvas. Points are placed over it. |
| `caption` | `ReactNode` |  | Under the figure, as its caption. |
| `value` | `string \| null` |  | The lit annotation's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` | The annotation lit at first. |
| `onValueChange` | `(id: string \| null) => void` |  | Fires when a callout is pressed: its id, or `null` when it's pressed again. |
| `label` | `string` |  | Names the list of labels. Default: the labels' "Annotations". |

Also takes the props of `ComponentProps<'figure'>`.

#### Annotations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `x` (required) | `number` |  | Where the point sits across the media, 0–100 from its left edge. |
| `y` (required) | `number` |  | Where the point sits down the media, 0–100 from its top. |
| `title` (required) | `ReactNode` |  | The label's first line: "Reefer unit". |
| `detail` | `ReactNode` |  | A second line: "34.1°F · set 34°F". |
| `side` | `'left' \| 'right'` |  | The gutter its label sits in. Default: the side its point is on. |

### Styling

Parts: `annotated-image`, `annotated-image-stage` (with `data-layout` `wide` or `stacked`), `annotated-image-media`, `annotated-image-callout`, `annotated-image-lines`, `annotated-image-line`, `annotated-image-labels`, `annotated-image-label` (with `data-side`), `annotated-image-title`, `annotated-image-detail` and `annotated-image-caption`; the lit pair carries `data-active`. The gutters are set by `--annotated-gutter` (between 9rem and 13rem).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Callouts | `spring.snappy` | 0.2s, bounce 0 | pop in one after another as the figure scrolls into view |
| Leader lines | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draw from the point to the label |
| Labels | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fade in as their line lands |
| Resize | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | labels glide to their new places |

**Reduced motion:** Drawn in place; labels jump to their new places.

#### Reduced motion

Callouts, lines and labels are drawn in place, and labels jump when the media resizes.

### Accessibility

- It is a `figure`; `caption` is its `figcaption`. Give the image its `alt`, or your `media` its own name.
- Callouts are buttons in number order, each named by its number and described by its label; pressing one sets `aria-pressed`. They have a wider hit area than the disc.
- The labels are an ordered list named "Annotations" (`annotations` in the labels); the lines are decorative.
- The media never mirrors, so neither do the points; in RTL the labels' text runs right to left in the same gutters.

---

# Image Compare

> Compare two pictures in one frame: drag the divider to reveal one over the other.

Source: https://www.youj.dev/docs/components/image-compare

## Examples

### Demo

```tsx
'use client'

import { Illustration } from '@youj/illustrations'
import { ImageCompare } from '@youj/react'

/* One scene twice: the kit's gray before, the theme's hues after. */
function Scene({ color }: { color?: boolean }) {
  return (
    <div className="grid size-full place-items-center bg-surface py-6">
      <Illustration scene="design-tools" assemble={false} unit={16} {...(color ? { colors: 'theme' as const } : {})} />
    </div>
  )
}

export default function ImageCompareDemo() {
  return (
    <div className="w-full max-w-lg p-4">
      <ImageCompare before={<Scene />} after={<Scene color />} beforeLabel="Mono" afterLabel="Theme" className="aspect-[4/3]" />
    </div>
  )
}
```

One illustration twice: the kit's gray on the start side, the theme's hues past the divider.

Drag the handle, or press anywhere on the picture to spring the divider there and keep dragging. The tags in the corners fade as the divider comes close to them.

### Vertical, on hover

```tsx
'use client'

import { ImageCompare } from '@youj/react'

/* A dusk sky and the same sky graded, drawn as gradients in the theme's colors. */
function Sky({ graded }: { graded?: boolean }) {
  const top = graded ? 'var(--color-chart-4)' : 'var(--color-fg-subtle)'
  const mid = graded ? 'var(--color-accent)' : 'var(--color-fg-muted)'
  const low = graded ? 'var(--color-warning)' : 'var(--color-line-strong)'
  return (
    <div className="relative size-full" style={{ background: `linear-gradient(to bottom, ${top}, ${mid} 55%, ${low})` }}>
      <div className="absolute inset-x-0 bottom-0 h-1/3" style={{ background: `color-mix(in oklab, ${top} 40%, var(--color-canvas))` }} />
    </div>
  )
}

export default function ImageCompareVertical() {
  return (
    <div className="w-full max-w-xs p-4">
      <ImageCompare
        orientation="vertical"
        hover
        before={<Sky />}
        after={<Sky graded />}
        beforeLabel="Original"
        afterLabel="Graded"
        defaultValue={40}
        className="aspect-[3/4]"
      />
    </div>
  )
}
```

A sky before and after grading, stacked, with `orientation="vertical"` and `hover`.

With `hover` the divider follows a mouse across the picture with no press; touch and pen still drag. Vertical puts `before` on top and runs the divider across.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add image-compare
```

It brings `icon-chevrons-left-right`, `icon-chevrons-up-down`, `use-controllable-state`, `youj-core`, `youj-labels-image-compare`, `youj-presets`, `youj-ui-core` with it.

Use an Image Compare to show what changed between two versions of the same picture: an edit, a redesign, a model's output against its input, a site before and after a fix. For pictures to step through one at a time, use a [Carousel](https://www.youj.dev/docs/components/carousel).

```tsx
import { ImageCompare } from '@youj/react'

<ImageCompare
  before={{ src: '/room-before.jpg', alt: 'The room before the renovation' }}
  after={{ src: '/room-after.jpg', alt: 'The room after the renovation' }}
  beforeLabel="Before"
  afterLabel="After"
  className="aspect-video"
/>
```

`before` and `after` take `{ src, alt }` for an image (drawn cover-fit) or any node: an illustration, a canvas, a rendered component. `after` sits underneath and sets the size; `before` is cut off at the divider. Give both the same aspect, or set one on the component with `className`.

The position is a number from 0 to 100: how much of `before` shows. It is uncontrolled with `defaultValue` (50), or controlled with `value` and `onValueChange`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `before` (required) | `ImageCompareSide` |  | Shown on the start side (or the top), up to the divider. A node, or `{ src, alt }` for an image. |
| `after` (required) | `ImageCompareSide` |  | Shown past the divider. A node, or `{ src, alt }` for an image. It sets the component's size. |
| `value` | `number` |  | The divider's position, 0–100: how much of `before` shows. Controlled. |
| `defaultValue` | `number` | `50` | The starting position when uncontrolled. |
| `onValueChange` | `(value: number) => void` |  |  |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | `horizontal` (side by side, the default) or `vertical` (stacked, the divider runs across). |
| `beforeLabel` | `ReactNode` |  | A tag on the `before` side, such as "Before" or "Original". Also names that side in the divider's value text. |
| `afterLabel` | `ReactNode` |  | A tag on the `after` side. |
| `hover` | `boolean` | `false` | The divider follows a mouse without a press. Touch and pen still drag. |
| `disabled` | `boolean` | `false` | Blocks dragging, hovering and keys, and takes the handle out of the tab order. |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), pressing the handle taps and each key step ticks. `false` keeps it silent. |

Also takes the props of `ComponentProps<'div'>`.

#### Data attributes

The root carries `data-orientation` (`horizontal` or `vertical`), plus `data-dragging` while a pointer holds it and `data-disabled` when disabled. Its parts are `image-compare-before`, `image-compare-after`, `image-compare-divider`, `image-compare-handle` and `image-compare-label` (with `data-side`). The drawn position is `--ui--compare`, from 0 to 100.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drag and hover |  |  | the divider follows the pointer 1:1, never eased in time |
| Press to jump | `spring.snappy` | 0.2s, bounce 0 | a press away from the handle springs the divider to the pointer |
| Value from outside | `spring.snappy` | 0.2s, bounce 0 | a new controlled `value` springs the divider there |
| Key step | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | each arrow, Page, Home or End step glides |
| Handle press | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the held handle shrinks to 90% and its shadow tightens |
| Corner tags | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | a tag fades out as the divider comes near it |

**Reduced motion:** Dragging is the same. A press, a key or a new value puts the divider there at once, and the handle and tags change without easing.

#### Reduced motion

Dragging works the same. Presses, keys and new values move the divider at once, and the handle and tags change without easing.

### Accessibility

- The handle is a `slider` (0 to 100) with `aria-orientation`, named "Comparison divider". Its value text says how much of each side shows ("Before 60%, After 40%"), using `beforeLabel` and `afterLabel` when they are strings.
- Arrow keys step by 5 and Page Up and Page Down by 20; Home and End go to either end. Keys move the divider the way it looks: right (left in right-to-left) or down is up the scale.
- A press anywhere on the picture moves focus to the handle, so the keys carry on from there. The handle has a visible focus ring.
- Touch drags along the divider's axis and still scrolls the page across it. Each pointer is captured, so a drag keeps going outside the picture.
- Give each `{ src, alt }` image an `alt` that says what is different about it. `disabled` takes the handle out of the tab order and sets `aria-disabled`.

---

# Image Accordion

> A row of pictures where one opens wide and the rest wait as slim strips, each with a caption.

Source: https://www.youj.dev/docs/components/image-accordion

## Examples

### Demo

```tsx
'use client'

import { ImageAccordion, type ImageAccordionItem } from '@youj/react'

/** Demo photos served by the Youj site; pass your own `src`. */
const PHOTOS = 'https://www.youj.dev/blocks/products'

const PANELS: ImageAccordionItem[] = [
  {
    id: 'ridge',
    media: { src: `${PHOTOS}/kettle-sage.webp`, alt: 'A sage green enamel kettle' },
    title: 'Ridge Kettle',
    description: 'Enamelled steel, for every hob',
  },
  {
    id: 'ritual',
    media: { src: `${PHOTOS}/tea-set.webp`, alt: 'A kettle, a caddy and three cups on a walnut tray' },
    title: 'Ritual Tea Set',
    description: 'Glazed in small batches',
  },
  {
    id: 'vases',
    media: { src: `${PHOTOS}/bud-vases.webp`, alt: 'Three white bud vases in a row' },
    title: 'Bud Vases',
    description: 'Unglazed stoneware, thrown by hand',
  },
  {
    id: 'hearth',
    media: { src: `${PHOTOS}/kettle-cream.webp`, alt: 'A cream stovetop kettle with a walnut grip' },
    title: 'Hearth Kettle',
    description: 'A whistler with a grip that stays cool',
  },
  {
    id: 'mug',
    media: { src: `${PHOTOS}/mug.webp`, alt: 'A white porcelain mug' },
    title: 'Daily Mug',
    description: 'Porcelain that keeps coffee hot',
  },
  {
    id: 'sky',
    media: { src: `${PHOTOS}/kettle-sky.webp`, alt: 'A sky blue enamel kettle' },
    title: 'Ridge Kettle in Sky',
    description: 'The same kettle, in a pale blue',
  },
]

export default function ImageAccordionDemo() {
  return (
    <div className="w-full max-w-3xl">
      <ImageAccordion items={PANELS} />
    </div>
  )
}
```

Six product shots, each `{ src, alt }`. Point at a strip, focus it or tap it to open it; the open panel shows its caption.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add image-accordion
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-image-accordion`, `youj-presets`, `youj-ui-core` with it.

Use an image accordion to show a handful of pictures in the room of one: destinations, product shots, case studies. One panel is open wide with its title and a short line; the others stay visible as strips, so the whole set reads at a glance. For a long sequence to step through, use a [Carousel](https://www.youj.dev/docs/components/carousel).

```tsx
import { ImageAccordion, type ImageAccordionItem } from '@youj/react'

const places: ImageAccordionItem[] = [
  { id: 'coast', media: { src: '/coast.jpg', alt: 'Coast road at sunrise' }, title: 'Coast road', description: 'Morning light over the headland' },
  { id: 'dunes', media: { src: '/dunes.jpg', alt: 'Sand dunes at dusk' }, title: 'Dunes', description: 'Wind-cut ridges at dusk' },
  { id: 'valley', media: <MyIllustration />, title: 'Valley' },
]

<ImageAccordion items={places} />
```

`media` is `{ src, alt }` for an image (it covers the panel) or any node: an illustration, a video, a gradient. The first panel is open at first; `value`, `defaultValue` and `onValueChange` hold the open id.

With `activation="hover"` (the default) a panel opens when the pointer rests on it or it takes focus, and on touch when it's tapped. `activation="click"` opens only on a press, Enter or Space, and hover and the arrow keys just point. `orientation="vertical"` stacks the panels.

The component keeps its size: the panels share its box (`h-80` across, `h-120` stacked), so opening one only moves the split. Set your own height with `className`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ImageAccordionItem[]` |  |  |
| `value` | `string` |  | The open panel's id (controlled). |
| `defaultValue` | `string` |  | The panel open at first. Default: the first. |
| `onValueChange` | `(id: string) => void` |  | Called with the id of the panel that opens. |
| `activation` | `'hover' \| 'click'` | `'hover'` | `hover` opens a panel on hover or focus (a press on touch); `click` only on a press. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Panels side by side (`horizontal`) or stacked (`vertical`). |
| `aria-label` | `string` |  | Names the group. Default: the labels' "Gallery". |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), opening a panel by press or key plays `select`; hovering stays silent. `false` keeps this one silent. |

Also takes the props of `ComponentProps<'div'>`.

#### Items

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `media` (required) | `ReactNode \| { src: string; alt: string }` |  | The picture: `{ src, alt }` for an image, or your own node (an illustration, a video, a gradient). It fills the panel. |
| `title` (required) | `ReactNode` |  | The caption's first line, and the panel's accessible name. |
| `description` | `ReactNode` |  | A short line under the title. |

### Styling

Parts: `image-accordion` (with `data-orientation` `horizontal` or `vertical` and `data-yj-activation` `hover` or `click`), `image-accordion-panel` (with `data-state` `active` or `inactive`), `image-accordion-media`, `image-accordion-caption`, `image-accordion-title` and `image-accordion-description`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Split | `spring.smooth` | 0.36s, bounce 0 | the opening panel widens as the others narrow, retargeting mid-glide |
| Caption | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades up once its panel has started to open |
| Strips | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | sit a little quieter, and brighten under the pointer |

**Reduced motion:** The split and the caption jump.

#### Sound

With sound on (`YoujProvider`'s `sound`), opening a panel by a press or a key plays `select`; hovering stays silent. `sound={false}` keeps one accordion quiet.

#### Reduced motion

The split and the caption jump; nothing glides.

### Accessibility

- It is a `group` named "Gallery" (`imageAccordion` in the labels), or your `aria-label`.
- Each panel is a button named by its title and described by its line; the open one carries `aria-current`. Captions stay in the page for screen readers whichever panel is open.
- The panels are one tab stop. The arrow keys of the orientation move between them (Left and Right across, mirrored in RTL; Up and Down stacked), and Home and End go to the first and last. In hover mode focus opens the panel; in click mode Enter or Space does.
- Give each image its `alt`, or your `media` its own name if it carries meaning.

---

# Capsule Player

> Show what's playing in a capsule, with a seek rail and play, previous and next.

Source: https://www.youj.dev/docs/components/capsule-player

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { CapsulePlayer } from '@youj/react'

const TRACKS = [
  { title: 'Low Tide', subtitle: 'Mara Quell', duration: 222 },
  { title: 'Glass Harbour', subtitle: 'Oda & The Kites', duration: 187 },
]

export default function CapsulePlayerDemo() {
  const [index, setIndex] = useState(0)
  const [playing, setPlaying] = useState(false)
  const [position, setPosition] = useState(72)
  const track = TRACKS[index]!
  // Stands in for an <audio> element's currentTime.
  useEffect(() => {
    if (!playing) return
    const id = setInterval(() => setPosition((p) => Math.min(p + 1, track.duration)), 1000)
    return () => clearInterval(id)
  }, [playing, track.duration])
  const skip = (step: number) => {
    setIndex((i) => (i + step + TRACKS.length) % TRACKS.length)
    setPosition(0)
  }
  return (
    <CapsulePlayer
      {...track}
      artwork={<span className="block size-full" style={{ background: 'conic-gradient(var(--color-chart-1), var(--color-chart-3), var(--color-chart-2), var(--color-chart-1))' }} />}
      playing={playing}
      onPlayingChange={setPlaying}
      position={position}
      onSeek={setPosition}
      onPrevious={() => skip(-1)}
      onNext={() => skip(1)}
    />
  )
}
```

A capsule player with a cover, a title and artist, a seek rail and previous, play and next buttons, over two tracks.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add capsule-player
```

It brings `button`, `capsule`, `icon-play`, `icon-skip-back`, `icon-skip-forward`, `waveform-scrubber`, `youj-core`, `youj-labels-capsule-player`, `youj-presets`, `youj-ui-core` with it.

The copy is 18 registry items, about 7,700 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `capsule`, `icon-engine`, `icon-loader-ring`, `icon-play`, `icon-skip-back`, `icon-skip-forward`, `spinner`, `use-controllable-state`, `waveform-scrubber`.

Use a capsule player as a compact now-playing bar: at the foot of a music app, over a video timeline, in the corner of a podcast page. It shows the cover, the title and artist, a thin progress rail you can seek, the time played, and the transport buttons.

The player has no clock of its own. Pass it the playhead and the length from your audio or video element, and act on its callbacks.

```tsx
import { CapsulePlayer } from '@youj/react'

<CapsulePlayer
  title="Low Tide"
  subtitle="Mara Quell"
  artwork={<img src={cover} alt="" />}
  playing={playing}
  onPlayingChange={(next) => (next ? audio.play() : audio.pause())}
  position={time}
  duration={audio.duration}
  onSeek={(seconds) => (audio.currentTime = seconds)}
  onPrevious={previousTrack}
  onNext={nextTrack}
/>
```

Without `onSeek` the rail only shows progress. Without `onPrevious` or `onNext`, that button is disabled.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` |  |  |
| `subtitle` | `string` |  | The artist, show or source, muted after the title. |
| `artwork` | `ReactNode` |  | Cover art: an <img> or any node, cropped to a disc. Decorative. |
| `playing` (required) | `boolean` |  |  |
| `onPlayingChange` (required) | `(playing: boolean) => void` |  |  |
| `position` (required) | `number` |  | The playhead, in seconds. |
| `duration` (required) | `number` |  | The track's length, in seconds. |
| `onSeek` | `(seconds: number) => void` |  | Seeks to a time in seconds, as the rail is dragged or stepped. Without it the rail only shows progress. |
| `onPrevious` | `() => void` |  | Without it, the previous button is disabled. |
| `onNext` | `() => void` |  | Without it, the next button is disabled. |
| `locale` | `string` |  | Formats the times. Default: the YoujProvider locale. |
| `size` | `'sm' \| 'default'` | ``default`` | `sm` for a dense toolbar; the default lines up with default-size controls. |

### Styling

Parts: `capsule-player` (with `data-playing`), `capsule-player-art`, `capsule-player-title`, `capsule-player-time`, `capsule-player-rail` and `capsule-player-progress`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Play and pause | `spring.snappy` | 0.2s, bounce 0 | the triangle folds into the two pause bars |
| New track | `duration.base`, `ease.emphasized` | 220ms; cubic-bezier(0.6, 0, 0.1, 1) | the new title rises in as the old one leaves upward |
| Rail | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the thumb grows in on hover and focus; the fill follows the time exactly |

**Reduced motion:** The icon and the title change at once.

### Accessibility

- The play button is named for what it does next: "Play", or "Pause" while playing.
- The rail is a slider named "Seek", spoken as the time and the length ("1:12 of 3:40"). The arrow keys move five seconds, and Home and End jump to the ends.
- The cover is decorative.
- The button names come from the labels (`play`, `pause`, `previousTrack`, `nextTrack`, `waveformSeek`, `waveformPosition`), which the language packs translate.

---

# Waveform Scrubber

> Navigate a recording’s waveform with chapters, keyboard controls and clip selection.

Source: https://www.youj.dev/docs/components/waveform-scrubber

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, formatTimecode, WaveformScrubber, type WaveformChapter } from '@youj/react'

const LENGTH = 24 * 60 + 30
const CHAPTERS: WaveformChapter[] = [
  { start: 0, title: 'Intro' },
  { start: 2 * 60 + 40, title: 'Warm-up' },
  { start: 8 * 60 + 15, title: 'Main set' },
  { start: 18 * 60, title: 'Cool-down' },
]
// Loudness from 0 to 1, spread over the recording: from your audio pipeline, or decoded once and stored.
const PEAKS = Array.from({ length: 360 }, (_, i) => 0.35 + 0.5 * Math.abs(Math.sin(i * 0.37) * Math.cos(i * 0.11)))

export default function WaveformScrubberDemo() {
  const [time, setTime] = useState(9 * 60 + 12)
  const [clip, setClip] = useState<[number, number] | null>(null)
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4 rounded-2xl border border-line bg-surface p-6">
      <WaveformScrubber peaks={PEAKS} duration={LENGTH} chapters={CHAPTERS} value={time} onValueChange={setTime} clip={clip} onClipChange={setClip} />
      <div className="flex items-center justify-between gap-3">
        <span className="font-mono text-ui-sm text-fg-muted tabular-nums">
          {clip ? `${formatTimecode(clip[0])}–${formatTimecode(clip[1])}` : formatTimecode(time)}
        </span>
        <Button variant="secondary" size="sm" aria-pressed={!!clip} onClick={() => setClip(clip ? null : [time, Math.min(LENGTH, time + 30)])}>
          {clip ? 'Done' : 'Clip'}
        </Button>
      </div>
    </div>
  )
}
```

A 24-minute recording with four chapters that you can drag to seek, or clip.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add waveform-scrubber
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-waveform-scrubber`, `youj-presets`, `youj-ui-core` with it.

Use a waveform scrubber as the seek bar of a podcast, a voice note, a lecture or a workout recording, anywhere the shape of the sound helps people find their place. The loudness samples you pass become bars: played in ink, the rest dim. Chapter starts are ticks with their titles above, a ruler of minutes runs underneath, and hovering shows the time and chapter under the pointer. Drag anywhere on the wave, or use the keys: a Base UI slider does the work underneath. With `clip` it becomes a range with two accent handles, zoomed to a window round the clip, for sharing a moment. It decodes no audio: bring the samples from your pipeline, or decode a file once and store them.

```tsx
import { WaveformScrubber } from '@youj/react'

<WaveformScrubber
  // Loudness from 0 to 1, spread evenly over the recording.
  peaks={peaks}
  duration={audio.duration}
  value={time}
  onValueChange={setTime}
  onValueCommitted={(t) => (audio.currentTime = t)}
  chapters={[
    { start: 0, title: 'Cold open' },
    { start: 192, title: 'The brief' },
  ]}
/>
```

`duration` is the recording's length in seconds and `value` the playhead. `onValueChange` follows the drag frame by frame; `onValueCommitted` fires when a drag or a key press ends, the moment to seek a real player. The samples are resampled to the bars that fit (one every 5px, or `bars` of them), each bar taking the loudest sample in its slice so short peaks survive; there are never more bars than samples.

`clip` (a `[start, end]` range in seconds) turns the scrubber into two handles in the accent, with `onClipChange` reporting each move. While it clips, the wave zooms to a window round the range with at least a minute either side, and the handles step by the second. `formatTimecode(seconds, locale)` formats times the way the scrubber does (0:42, 12:34, 1:02:10), for the labels around it. The [Podcast](https://www.youj.dev/docs/blocks/media) block puts it together with a player, a speed control and chapter rows.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `peaks` (required) | `readonly number[]` |  | Loudness samples from 0 to 1, spread evenly over the recording; resampled to the bars that fit. |
| `duration` (required) | `number` |  | The recording's length, in seconds. |
| `value` | `number` |  | The playhead, in seconds (controlled). |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `(seconds: number) => void` |  |  |
| `onValueCommitted` | `(seconds: number) => void` |  | When a drag or key press ends: the moment to seek a real player. |
| `chapters` | `readonly WaveformChapter[]` | `[]` |  |
| `clip` | `readonly [number, number]` |  | A range to clip, in seconds (controlled): the handles show and the rest dims. `null` for none. |
| `onClipChange` | `(range: [number, number]) => void` |  |  |
| `step` | `number` | `5` | Seconds per arrow key (a clip's handles move by the second). |
| `bars` | `number` |  | How many bars. Default: as many as fit, one every 5px. |
| `label` | `string` |  | The playhead's accessible name. Default: the labels' "Seek". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `disabled` | `boolean` |  |  |
| `sound` | `boolean` | `true` | With sound on, scrubbing across a chapter start plays `tick`. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `waveform-scrubber` (with `data-clipping`), `waveform-chapters`, `waveform-chapter` (with `data-current`), `waveform-slider`, `waveform-control`, `waveform-track`, `waveform-bars`, `waveform-chapter-tick`, `waveform-range`, `waveform-hover`, `waveform-value`, `waveform-playhead`, `waveform-handle` (with `data-kind`), `waveform-ruler` and `waveform-time`. In Bezel the chapter titles are mono capital eyebrows and the times are mono. In a narrow scrubber only the chapter playing keeps its title.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | the wave rises from its midline as it’s revealed from the start |
| Scrub | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the playhead stays under the finger, never eased; its dot grows while held |

**Reduced motion:** The wave is drawn in place.

#### Reduced motion

The wave is drawn in place from the first frame; scrubbing is unchanged, since it never animates.

### Accessibility

- The playhead is a slider named by `label` (default: the labels' "Seek"), whose value is spoken as the time, the length and the chapter ("12:34 of 42:10, Night shift").
- Arrow keys step by `step` seconds (5), Page Up and Page Down ten times as far, and Home and End jump to the ends. A clip's handles, "Clip start" and "Clip end", step by the second.
- With sound on, crossing into another chapter while scrubbing plays `tick` (`sound={false}` keeps it quiet).
- Time runs left to right in every script, like a tape, so the wave keeps its direction under RTL, the arrow keys included; the text around it follows the page.
- Its words come from the labels (`waveformSeek`, `waveformPosition`, `waveformClipStart`, `waveformClipEnd`), translated by the language packs.

---

# Voice Orb

> Show a voice agent's state and sound as a softly lit sphere in your theme's accent, with rings that carry the voice.

Source: https://www.youj.dev/docs/components/voice-orb

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { VoiceOrb, type VoiceOrbBands, type VoiceOrbState } from '@youj/react'

const TURNS: { state: VoiceOrbState; ms: number; caption: string }[] = [
  { state: 'listening', ms: 3200, caption: 'Listening…' },
  { state: 'thinking', ms: 1800, caption: 'Thinking…' },
  { state: 'speaking', ms: 4000, caption: 'Speaking' },
]

/** A stand-in for a real voice: syllables, phrases and pauses. In an app, measure your audio or pass `audio`. */
function useSimulatedVoice() {
  const [sample, setSample] = useState<{ turn: number; level: number; bands: VoiceOrbBands }>({ turn: 0, level: 0, bands: { low: 0, mid: 0, high: 0 } })
  useEffect(() => {
    let raf = 0
    let last = 0
    const start = performance.now()
    const cycle = TURNS.reduce((sum, t) => sum + t.ms, 0)
    const frame = (now: number) => {
      raf = requestAnimationFrame(frame)
      if (now - last < 33) return
      last = now
      let at = (now - start) % cycle
      let turn = 0
      while (at > TURNS[turn]!.ms) at -= TURNS[turn++]!.ms
      const t = at / 1000
      const syllable = Math.abs(Math.sin(t * 7.3) * Math.sin(t * 3.1 + 1))
      const voiced = TURNS[turn]!.state !== 'thinking'
      const level = voiced ? Math.min(1, Math.max(0, Math.sin(t * 1.4) * 0.5 + 0.6) * (0.2 + 0.8 * syllable)) : 0
      setSample({ turn, level, bands: { low: level * 0.9, mid: level * (0.5 + 0.5 * syllable), high: level * 0.4 } })
    }
    raf = requestAnimationFrame(frame)
    return () => cancelAnimationFrame(raf)
  }, [])
  return sample
}

export default function VoiceOrbDemo() {
  const { turn, level, bands } = useSimulatedVoice()
  const { state, caption } = TURNS[turn]!
  return (
    <div className="flex flex-col items-center gap-2">
      <VoiceOrb state={state} level={level} bands={bands} size="xl" label="Sous-chef" />
      <p className="text-sm text-fg-muted">{caption}</p>
    </div>
  )
}
```

A cooking assistant cycling through listening, thinking and speaking on a simulated voice.

### States

```tsx
'use client'

import { useState } from 'react'
import { SegmentedControl, SegmentedControlItem, Slider, VoiceOrb, type VoiceOrbState } from '@youj/react'

const STATES: VoiceOrbState[] = ['idle', 'listening', 'thinking', 'speaking']

export default function VoiceOrbStates() {
  const [state, setState] = useState<VoiceOrbState>('listening')
  const [level, setLevel] = useState(0.4)
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-6">
      <VoiceOrb state={state} level={level} size="lg" />
      <SegmentedControl value={state} onValueChange={(value) => setState(value as VoiceOrbState)} aria-label="State">
        {STATES.map((s) => (
          <SegmentedControlItem key={s} value={s} className="capitalize">
            {s}
          </SegmentedControlItem>
        ))}
      </SegmentedControl>
      <Slider aria-label="Level" value={level} onValueChange={(value) => setLevel(value as number)} min={0} max={1} step={0.01} className="w-56" />
    </div>
  )
}
```

Pick a state and drag the level, as an app that measures its own audio would set it.

### Palettes

```tsx
'use client'

import { useState } from 'react'
import { basalt, cinnabar, graphite, heather, meadow, seaglass, ThemeScope } from '@youj/core'
import { SegmentedControl, SegmentedControlItem, VoiceOrb } from '@youj/react'

const PRESETS = { basalt, graphite, cinnabar, seaglass, heather, meadow }
type PresetId = keyof typeof PRESETS

export default function VoiceOrbPalettes() {
  const [id, setId] = useState<PresetId>('cinnabar')
  return (
    <div className="flex w-full max-w-lg flex-col items-center gap-5">
      <ThemeScope theme={PRESETS[id]}>
        <div className="grid w-full place-items-center rounded-2xl border border-line bg-canvas p-6 text-fg">
          <VoiceOrb state="thinking" size="xl" />
        </div>
      </ThemeScope>
      <SegmentedControl value={id} onValueChange={(value) => setId(value as PresetId)} aria-label="Theme">
        {Object.keys(PRESETS).map((preset) => (
          <SegmentedControlItem key={preset} value={preset} className="capitalize">
            {preset}
          </SegmentedControlItem>
        ))}
      </SegmentedControl>
    </div>
  )
}
```

The same orb under six presets. Every color comes from the theme's accent.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add voice-orb
```

It brings `use-announcer`, `use-audio-meter`, `youj-core`, `youj-labels-voice-orb`, `youj-presets`, `youj-ui-core` with it.

Use a voice orb as the face of a voice agent: in a call screen, a dictation sheet or an assistant's panel, wherever people talk to software and need to see whether it's listening. The sphere stays round and calm; the sound shows as rings and as its size. `state` says what the agent is doing: `idle` breathes slowly, `listening` draws rings in from the edge and swells with the input, `thinking` turns a gentle swirl inside, and `speaking` sends pulses out with the output. Every change springs, so a state never jumps. For a whole call card with mute, volume and End call, see the [Voice call](https://www.youj.dev/docs/blocks/activity-and-conversations#voice-call) block.

```tsx
import { VoiceOrb } from '@youj/react'

// Your app measures the audio: pass how loud it is, 0 to 1.
<VoiceOrb state={agent.state} level={agent.level} muted={micOff} label="Sous-chef" />

// Or let the orb analyze a source itself.
<VoiceOrb state="listening" audio={micStream} />
<VoiceOrb state="speaking" audio={audioElement} />
```

`level` is the input level while listening and the output level while speaking. Add `bands` (`{ low, mid, high }`, each 0 to 1) to split the work: low swells the sphere, mid drives the rings. Without them every band follows `level`. `muted` says the person's microphone is off: the sphere grays and stops reacting while it listens, and still shows the agent speaking.

The colors are the theme's: a light tint, the accent and a deep shade of it, with `chart-2` as a hint. They are read again whenever the theme or mode changes, so each preset gives its own orb. The halo and rings stay inside the orb's box, with the sphere at 62% of it; `spill` lets them reach half the size again past the box, for a hero or a call screen with room around it.

`audio` takes a `MediaStream` (a microphone or a call), an `<audio>` or `<video>` element, or an `AudioNode` from your own graph, and analyzes it with a Web Audio `AnalyserNode` made only while it is set. It never plays anything and never stops your tracks. A stream gets a silent context of its own, closed on unmount. A node is tapped on its own context, which is left alone. A media element's sound runs through Web Audio from its first use on (the browser allows that once per element), so its context stays with the element and resumes when it plays. While `audio` is set, `level` and `bands` are ignored.

It draws in WebGL2, falls back to a Canvas2D sphere, and to a CSS disc where neither is available. It renders at most two device pixels per CSS pixel and 60 frames a second, and pauses offscreen and in hidden tabs.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `'idle' \| 'listening' \| 'thinking' \| 'speaking'` | `'idle'` | What the agent is doing. |
| `level` | `number` |  | How loud, 0–1, for apps that measure their audio themselves: the input while listening, the output while speaking. Ignored while `audio` is set. |
| `bands` | `VoiceOrbBands` |  | Loudness per band, 0–1: low swells the sphere, mid drives the rings. Default: every band follows `level`. Ignored while `audio` is set. |
| `audio` | `VoiceOrbAudio \| null` |  | A source to analyze instead of `level`: a MediaStream (a microphone, a call), an <audio> or <video> element, or an AudioNode. |
| `muted` | `boolean` | `false` | The person's microphone is off: the sphere grays and stops reacting while listening. |
| `spill` | `boolean` | `false` | Let the halo and rings reach past the box, by half its size again; the sphere keeps its size. |
| `size` | `Extract<Size, 'sm' \| 'default' \| 'lg' \| 'xl'>` | `'default'` |  |
| `label` | `string` |  | The agent's name, spoken with its state ("Ada: Listening"). Default: the labels' "Voice agent". |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `voice-orb` (with `data-state`, `data-size`, `data-yj-muted` and `data-yj-renderer`: `webgl`, `canvas` or `css`), `voice-orb-body` (the image) and `voice-orb-fallback` (the CSS disc, shown until a canvas draws). Sizes are `sm`, `default`, `lg` and `xl`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| State change | `duration.deliberate` | 560ms | breath, flow, rings, swirl, swell and halo spring to the new state with no overshoot |
| Ring | `duration.deliberate` | 560ms; twice the token | out from the sphere while speaking, in from the edge while listening; at most one per fast step |
| Level rises | `duration.instant` | 80ms | the envelope follows a rising level quickly |
| Level falls | `duration.slow` | 340ms | and lets it go more slowly, so speech reads as phrases |

**Reduced motion:** A still sphere that only scales gently with the level; no rings.

#### Reduced motion

The sphere is drawn once and holds still, with no rings; only its size follows the level, up to 8% larger. The clock everywhere runs at 1 / the provider's `timeScale`.

### Accessibility

- The orb is an image named by the agent and its state ("Sous-chef: Listening", "Sous-chef: Listening, microphone off"); `label` names the agent, by default the labels' "Voice agent".
- A change of state is announced politely ("Thinking"); the first state is not.
- It is not focusable and has no controls of its own: put the mic toggle, the End call button and the captions beside it, as the Voice call block does.
- Its words come from the labels (`voiceOrb`, `voiceOrbIdle`, `voiceOrbListening`, `voiceOrbThinking`, `voiceOrbSpeaking`, `voiceOrbMuted`, `voiceOrbState`), translated by the language packs.

---

# Audio Recorder

> Record a voice note or an audio clip, listen back on its waveform, then save it or discard it.

Source: https://www.youj.dev/docs/components/audio-recorder

## Examples

### Voice note

```tsx
'use client'

import { useMemo } from 'react'
import { AudioRecorder } from '@youj/react'
import { simulatedMicrophone } from './simulated-microphone'

/** Stands in for an upload: in an app, send the Blob to your server here. */
const upload = (_blob: Blob) => new Promise((done) => setTimeout(done, 900))

export default function AudioRecorderDemo() {
  const mic = useMemo(() => simulatedMicrophone(), [])
  return (
    <div className="w-full max-w-md">
      <AudioRecorder label="Voice note" getStream={mic} onRecordingComplete={upload} />
    </div>
  )
}
```

A message composer's voice note: record, listen back, then Save. The microphone is a synthesized hum here, and the upload is simulated.

### With time limit

```tsx
'use client'

import { useMemo } from 'react'
import { AudioRecorder } from '@youj/react'
import { simulatedMicrophone } from './simulated-microphone'

export default function AudioRecorderTimeLimit() {
  const mic = useMemo(() => simulatedMicrophone(), [])
  return (
    <div className="w-full max-w-md">
      <AudioRecorder label="Answer" maxDuration={15} getStream={mic} />
    </div>
  )
}
```

`maxDuration={15}`: the ring around stop runs down, turns red for the last ten seconds, and the take stops at the limit.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add audio-recorder
```

It brings `async-button`, `button`, `icon-check`, `icon-mic`, `icon-play`, `icon-trash`, `icon-undo`, `use-announcer`, `use-audio-meter`, `waveform-scrubber`, `youj-core`, `youj-labels-audio-recorder`, `youj-ui-core` with it.

The copy is 26 registry items, about 9,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `icon-check`, `icon-engine`, `icon-loader-ring`, `icon-mic`, `icon-play`, `icon-trash`, `icon-undo` and 6 more.

Use an audio recorder wherever people leave a voice note or a short clip: a message composer, a support form, a spoken answer in a survey. The first press of the record button asks for the microphone. While it records, the sound scrolls past as bars, a timer counts up, and pause and stop sit beside it. A stopped take opens on a [waveform scrubber](https://www.youj.dev/docs/components/waveform-scrubber) with play, its length, discard and **Save**, which hands you the take. The recorder keeps one size through every state: the controls change, the box doesn't.

```tsx
import { AudioRecorder } from '@youj/react'

<AudioRecorder
  maxDuration={60}
  onRecordingComplete={(blob, { duration, mimeType }) => upload(blob, { duration, mimeType })}
/>

// A recording you already have opens on playback.
<AudioRecorder value={savedNote} />
```

It records with `MediaRecorder`, in `mimeType` when the browser supports it and otherwise in the first of WebM with Opus, MP4 and Ogg that it does (Safari records MP4). **Save** is an [async button](https://www.youj.dev/docs/components/button#async-button): it awaits `onRecordingComplete`, which gets the Blob with its `duration` in seconds and its `mimeType`, shows a spinner and then a check with "Saved", and the take becomes read-only: playback only, with a quiet Saved mark where the actions were. If the promise rejects, the button shows the error and the take stays unsaved, so it can be saved again. Pass `saved={false}` to give a saved take back its discard and Save (to re-record, say); `saved` is controlled when you pass it. Nothing plays by itself: playback starts only from the play button.

Discard keeps the take for a few seconds behind an **Undo** link; `onDiscard` fires once the discard is final (the window closes, a new take starts, or the recorder unmounts). A take passed as `value` (a Blob or a URL) opens saved, for playback only.

The microphone, the analyzer and the recorder are released when a take stops and when the recorder unmounts, so the browser's recording indicator goes out. `getStream` replaces the microphone with any `MediaStream` (a chosen device, a tab's audio, or the simulated voice these demos use).

If the browser refuses the microphone, finds none, or can't record at all, the caption says so and what to do, and the record button tries again. A permission refused earlier shows before the first press where the browser reports it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onRecordingComplete` | `(blob: Blob, info: AudioRecordingInfo) => unknown \| Promise<unknown>` |  | Save: the take, its length and type. Awaited: a rejection keeps the take unsaved and shows the error on the button. |
| `maxDuration` | `number` |  | The longest take, in seconds: a ring counts down and recording stops there. |
| `mimeType` | `string` |  | The container to record in, when the browser supports it; otherwise the first of WebM/Opus, MP4 and Ogg that it does. |
| `disabled` | `boolean` |  |  |
| `size` | `Extract<Size, 'sm' \| 'default'>` | `'default'` |  |
| `value` | `Blob \| string \| null` |  | A recording to show, as a Blob or a URL: it opens on playback, saved. |
| `saved` | `boolean` |  | Whether the take is saved, and so read-only (controlled). Default: true once Save succeeds or a `value` opens; `false` gives back discard and Save. |
| `onDiscard` | `() => void` |  | When a discard is final: the Undo window closed, a new take started, or the recorder left. |
| `sound` | `boolean` | `true` | Plays toggleOn and toggleOff around a take, and Save's success or error. |
| `getStream` | `() => Promise<MediaStream>` |  | Where the sound comes from. Default: the microphone through getUserMedia. |
| `label` | `string` |  | The group's name. Default: the labels' "Audio recorder". |
| `locale` | `string` |  | Formats the times. Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

The root `audio-recorder` carries `data-state` (`idle`, `requesting`, `recording`, `paused`, `recorded` or `saved`), `data-size` (`sm` or `default`) and `data-disabled`. Its parts are `audio-recorder-stage` (the live wave, `audio-recorder-wave`, or under reduced motion the meter, `audio-recorder-meter`, then the scrubber), `audio-recorder-controls`, `audio-recorder-primary` (record, stop, play), `audio-recorder-ring`, `audio-recorder-dot`, `audio-recorder-timer`, `audio-recorder-remaining`, `audio-recorder-pause`, `audio-recorder-time`, `audio-recorder-discard`, `audio-recorder-save` (the AsyncButton), `audio-recorder-saved` (the read-only mark), `audio-recorder-caption` and `audio-recorder-error`. A lit meter bar has `data-yj-lit`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Live wave | `duration.instant` | 80ms; every frame | one bar per twentieth of a second, sliding toward the start between samples, so the strip scrolls with the sound |
| Recording dot | `duration.slow` | 340ms | breathes while recording and holds still while paused |
| Countdown ring | `duration.instant` | 80ms; every frame | runs down with the time left; accent, then danger for the last ten seconds |
| Take opens | `duration.deliberate` | 560ms | the scrubber’s bars rise from the midline from the start |

**Reduced motion:** A still level meter that lights up with the sound instead of the scrolling bars; the dot holds still.

#### Reduced motion

The wave doesn't scroll: a row of bars of rising height lights up to the current level, so you can still see that the microphone hears you. The recording dot holds still, and the scrubber's bars are drawn in place.

### Accessibility

- The recorder is a group named by `label` (default "Audio recorder"). Every button is named: Start recording, Stop recording, Pause recording, Resume recording, Play, Pause, Discard recording, Save.
- The record button keeps its place and its focus as it becomes stop and then play, so Space starts a take, stops it and plays it back without moving.
- The recording clock is a `role="timer"` named "Recording time"; it is not announced every second.
- Starting, pausing, stopping (with the take's length), reaching the limit, discarding and restoring are announced politely, as are the microphone messages.
- After a discard, an undo or a save, focus returns to the record or play button.
- Save announces its progress and outcome through the AsyncButton ("Saving…", "Saved").
- The waves are decorative; the scrubber is a slider with the time and length as its value.
- Time runs left to right in every script, like the scrubber; the controls follow the page's direction.
- Its words come from the labels (`audioRecorder…`, with `play`, `pause` and `undo`), translated by the language packs.

---

# Lottie Player

> Play Lottie animations with shared speed controls, theme colors and reduced-motion support.

Source: https://www.youj.dev/docs/components/lottie-player

## Examples

### Demo

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { useYouj } from '@youj/core'
import { LottiePlayer } from '@youj/motion/players'

type Phase = 'idle' | 'processing' | 'paid'

// The loader's slots follow the button's ink: token names, or any CSS color.
const ON_BUTTON = { accent: 'canvas', fg: 'canvas', line: 'color-mix(in oklab, var(--color-canvas) 30%, transparent)' }

export default function LottiePlayerDemo() {
  const k = useYouj()
  const [phase, setPhase] = useState<Phase>('idle')
  const view = useRef<HTMLElement | null>(null)
  const shown = useRef(phase)

// Stands in for the payment request. Timed in tokens, so it follows the Speed control.
  useEffect(() => {
    if (phase !== 'processing') return
    const timer = setTimeout(() => setPhase('paid'), k.ms('deliberate') * 3)
    return () => clearTimeout(timer)
  }, [phase, k])

// When the focused control leaves with its view, keep keyboard focus in the card.
  useEffect(() => {
    if (shown.current === phase) return
    shown.current = phase
    if (document.activeElement === document.body) view.current?.focus()
  }, [phase])

return (
    <div className="w-full max-w-sm overflow-hidden rounded-2xl border border-line bg-surface shadow-sm">
      <div className="flex items-center justify-between border-b border-line px-5 py-3.5 text-sm">
        <span className="font-medium text-fg">Checkout</span>
        <span className="font-mono text-xs text-fg-muted">ORD-20418</span>
      </div>
      {phase === 'paid' ? (
        <div ref={(node) => void (view.current = node)} tabIndex={-1} className="flex flex-col items-center px-6 pt-6 pb-7 text-center outline-none">
          {/* Controlled: it plays once when it mounts, and holds its last frame. */}
          <LottiePlayer src="/samples/success-check.json" playing label="Payment confirmed" className="size-20" />
          <p className="mt-3 text-base font-semibold tracking-tight text-fg">Payment confirmed</p>
          <p className="mt-1 text-sm text-fg-muted">$148.00 charged to Visa ending 4242</p>
          <button
            type="button"
            onClick={() => setPhase('idle')}
            className="mt-5 rounded text-xs font-medium text-fg-muted underline-offset-4 hover:text-fg hover:underline focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            Start over
          </button>
        </div>
      ) : (
        <div className="px-5 pt-4 pb-5 text-sm">
          <dl className="space-y-2.5">
            <div className="flex justify-between">
              <dt className="text-fg-muted">Pro plan, annual</dt>
              <dd className="text-fg">$144.00</dd>
            </div>
            <div className="flex justify-between">
              <dt className="text-fg-muted">Tax</dt>
              <dd className="text-fg">$4.00</dd>
            </div>
            <div className="flex justify-between border-t border-line pt-2.5 font-medium">
              <dt className="text-fg">Total</dt>
              <dd className="text-fg">$148.00</dd>
            </div>
          </dl>
          <button
            ref={(node) => void (view.current = node)}
            type="button"
            aria-disabled={phase === 'processing'}
            onClick={() => phase === 'idle' && setPhase('processing')}
            className="mt-5 flex h-10 w-full items-center justify-center gap-2 rounded-lg bg-fg font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none"
          >
            {phase === 'processing' ? (
              <>
                <LottiePlayer src="/samples/upload-progress.json" autoplay loop slots={ON_BUTTON} className="size-6" />
                Processing
              </>
            ) : (
              'Pay $148.00'
            )}
          </button>
        </div>
      )}
      <p role="status" className="sr-only">
        {phase === 'processing' ? 'Processing payment' : phase === 'paid' ? 'Payment confirmed' : ''}
      </p>
    </div>
  )
}
```

A payment flow in which the animation follows the phase: idle, processing, then paid.

### When it plays

```tsx
'use client'

import { LottiePlayer } from '@youj/motion/players'

export default function LottiePlayerTriggers() {
  return (
    <div className="@container w-full max-w-2xl">
      <div className="grid gap-3 @lg:grid-cols-2">
        {/* playOnHover: forward while the pointer is over it, back in reverse from wherever it got to. */}
        <div className="flex flex-col items-center rounded-xl border border-dashed border-line-strong bg-surface px-5 py-6 text-center">
          <LottiePlayer src="/samples/upload-progress.json" playOnHover className="size-20" />
          <p className="mt-3 text-sm font-medium text-fg">Drop files to upload</p>
          <p className="mt-0.5 text-xs text-fg-muted">Hover the mark to preview it</p>
        </div>
        {/* playOnView: once, the first time it scrolls into view. */}
        <div className="flex flex-col items-center rounded-xl border border-line bg-surface px-5 py-6 text-center">
          <LottiePlayer src="/samples/logo-sting.lottie" playOnView label="Youj" className="h-20 w-36" />
          <p className="mt-3 text-sm font-medium text-fg">Made with Youj</p>
          <p className="mt-0.5 text-xs text-fg-muted">Plays once, when it scrolls into view</p>
        </div>
      </div>
    </div>
  )
}
```

Players started by different triggers.

- `autoplay` plays once the file has loaded and the player is on screen. A finished one-shot doesn't replay when it scrolls back into view.
- `playOnView` waits until the player first scrolls into view, then plays. Use it for illustrations below the fold.
- `playOnHover` plays forward while the pointer is over the player, and back in reverse from wherever it got to when the pointer leaves. Focus inside the player counts as hover.
- `playing` takes over entirely: `true` plays, and `false` pauses. It overrides the three props above while it's defined. A finished run replays only after `playing` has been `false`.
- `loop` repeats, and `segment={[start, end]}` limits playback to a range of frames.

Whatever the trigger, the player pauses while it's offscreen and picks up again when it returns.

### Controlled playback

```tsx
'use client'

import { useEffect, useState } from 'react'
import { useYouj } from '@youj/core'
import { FileTextIcon, UploadIcon } from '@youj/icons'
import { LottiePlayer } from '@youj/motion/players'

const FILES = [
  { name: 'q3-board-deck.pdf', size: '4.2 MB' },
  { name: 'brand-guidelines.pdf', size: '12.8 MB' },
  { name: 'launch-film.mp4', size: '86.1 MB' },
]

export default function LottiePlayerUpload() {
  const k = useYouj()
  const [started, setStarted] = useState(false)
  const [done, setDone] = useState(0)
  const running = started && done < FILES.length
  const finished = started && done === FILES.length

// Stands in for the uploads: one file lands every two deliberate beats.
  useEffect(() => {
    if (!running) return
    const timer = setTimeout(() => setDone((n) => n + 1), k.ms('deliberate') * 2)
    return () => clearTimeout(timer)
  }, [running, done, k])

return (
    <div className="w-full max-w-md rounded-2xl border border-line bg-surface p-2 shadow-sm">
      <ul className="divide-y divide-line">
        {FILES.map((file, i) => {
          const complete = i < done
          return (
            <li key={file.name} className="flex items-center gap-3 px-3 py-2.5">
              <FileTextIcon size={16} className="text-fg-muted" />
              <div className="min-w-0 flex-1">
                <p className="truncate text-sm text-fg">{file.name}</p>
                <p className="text-xs text-fg-muted">{complete ? 'Uploaded' : started ? 'Uploading' : file.size}</p>
              </div>
              {started &&
                (complete ? (
                  <LottiePlayer src="/samples/success-check.json" playing label="Uploaded" className="size-7" />
                ) : (
                  <LottiePlayer src="/samples/upload-progress.json" autoplay loop label="Uploading" className="size-7" />
                ))}
            </li>
          )
        })}
      </ul>
      <div className="mt-2 flex items-center justify-between gap-3 border-t border-line px-3 pt-3 pb-1.5">
        <p role="status" className="text-xs text-fg-muted">
          {started ? `${done} of ${FILES.length} uploaded` : `${FILES.length} files ready`}
        </p>
        <button
          type="button"
          onClick={() => {
            if (running) return
            setDone(0)
            setStarted(!finished)
          }}
          aria-disabled={running}
          className="inline-flex items-center gap-1.5 rounded-lg bg-fg px-3 py-1.5 text-xs font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none aria-disabled:opacity-60"
        >
          <UploadIcon size={14} />
          {finished ? 'Clear' : 'Upload'}
        </button>
      </div>
    </div>
  )
}
```

An upload list whose animations are driven by state.

Drive `playing` from your own state when the animation reports something real. Here, each file gets a looping progress mark while it uploads and a check once it lands. The check is controlled, so it plays exactly once, at the moment the upload finishes.

### Color and theme

```tsx
'use client'

import { useState } from 'react'
import { LottiePlayer } from '@youj/motion/players'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

// The check's color lives in a slot named `success`. Bind it to another token and it recolors in place.
const TOKENS = ['success', 'accent', 'warning', 'danger']

export default function LottiePlayerSlots() {
  const [token, setToken] = useState('success')

return (
    <div className="flex flex-col items-center gap-5">
      <div className="grid size-36 place-items-center rounded-2xl border border-line bg-surface">
        <LottiePlayer src="/samples/success-check.json" autoplay slots={{ success: token }} className="size-24" />
      </div>
      <ToggleGroup variant="segmented" size="sm" aria-label="Slot color" value={[token]} onValueChange={(next) => next[0] && setToken(next[0])}>
        {TOKENS.map((option) => (
          <ToggleGroupItem key={option} value={option} className="px-2.5 font-mono text-xs">
            {option}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
    </div>
  )
}
```

Animations recolored by the theme's tokens.

Lottie files can expose colors as slots. The player binds each color slot to a Youj token, reads the token from computed CSS and sets the slot, so the animation follows your palette and recolors in place when the theme changes, even mid-play.

- A slot whose id is a token name (`success`, `accent`, `fg`, `line`) binds to that token automatically. Youj's own samples are built this way, so they need no mapping.
- `slots` maps any other slot id, or overrides a match, with a token name (`'accent'`, `'fg-muted'`) or any CSS color expression (`'color-mix(in oklab, var(--color-canvas) 30%, transparent)'`).
- `themed={false}` leaves the file's baked colors alone.

Switch between light and dark with the toggle in the header: every player on this page recolors in place.

## Installation & usage

```bash
pnpm add @youj/motion @lottiefiles/dotlottie-react@^0.19.16
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add lottie-player
```

It brings `youj-core`, `player-env` with it.

Use it for illustrated moments a designer animated in After Effects or the Lottie editor: a success mark, a loader with character, an empty-state illustration, a logo sting. For interface motion such as presses, toggles and layout, use Youj's primitives and icons instead. They're lighter, and they respond to input mid-flight.

Give it a file and a size. The player fills its box and keeps the animation's aspect ratio (`fit="contain"`).

```tsx
import { LottiePlayer } from '@youj/motion/players'

export function PaymentConfirmed() {
  return <LottiePlayer src="/animations/success-check.json" autoplay label="Payment confirmed" className="size-20" />
}
```

`src` takes a URL to a `.lottie` or Lottie `.json` file. To bundle the animation instead of fetching it, pass `data`: the parsed JSON, a JSON string or an `ArrayBuffer` of a `.lottie` file.

The examples above play sample files from `/samples/`. `npx @youj/cli add lottie-samples` copies the two `.json` ones into your app's `public/samples/`, so the examples run as they are; `logo-sting.lottie` is binary, so it isn't in the item.

### Layout

`fit` decides how the animation fills the box: `contain` (the default), `cover`, `fill`, `none`, `fit-width` or `fit-height`. `align` places it inside the box as `[x, y]` fractions from 0 to 1, and it's centered by default.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` |  | URL of a `.lottie` or Lottie `.json` file. |
| `data` | `string \| ArrayBuffer \| Record<string, unknown>` |  | Inline animation data, instead of `src`. |
| `autoplay` | `boolean` | `false` | Play once loaded and in view. |
| `loop` | `boolean` | `false` |  |
| `playOnHover` | `boolean` | `false` | Hover (or focus within) plays forward; leaving plays back in reverse from wherever it is. |
| `playOnView` | `boolean` | `false` | Start playing the first time the player scrolls into view. |
| `segment` | `[number, number]` |  | Restrict playback to a frame range, e.g. `[0, 30]`. |
| `playing` | `boolean` |  | Controlled playback. Overrides autoplay / playOnView / playOnHover while defined. |
| `speed` | `number` | `1` | Playback rate before time-scaling. The effective speed is `speed / timeScale`. |
| `posterFrame` | `LottieFrame` | `'last'` | Frame shown when motion is reduced. |
| `slots` | `Record<string, string>` |  | Color slot bindings: slot id → youj color token (`'accent'`, `'fg-muted'`…) or any CSS color expression. Slots whose id is itself a token name bind automatically, so youj samples need no mapping. |
| `themed` | `boolean` | `true` | Follow youj color tokens and live theme changes. |
| `fit` | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'fit-width' \| 'fit-height'` | `'contain'` |  |
| `align` | `[number, number]` |  | Alignment in the box as [x, y] in 0–1. Default centered. |
| `label` | `string` |  | Accessible name. Without it the player is decorative (`aria-hidden`). |
| `onComplete` | `() => void` |  |  |
| `onLoad` | `(player: DotLottie) => void` |  |  |
| `onError` | `(error: Error) => void` |  | A load failed: the file couldn't be fetched, or isn't a Lottie or dotLottie animation. |

Also takes the props of `ComponentProps<'div'>`.

### Performance

The player renders with the dotLottie runtime, which loads its WebAssembly from a CDN the first time a player mounts. To serve it yourself, call `setWasmUrl` from `@lottiefiles/dotlottie-react` before any player mounts. The canvas resizes with its box, and playback pauses while the player is offscreen.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Playback |  | speed ÷ time scale | the file’s own timeline |
| Hover out |  | same rate, reversed | `playOnHover`, reversing from the current frame |

**Reduced motion:** Never plays. It shows the poster frame, by default the last one: the resolved state, such as the finished check.

The timing lives in the file, so the player can't put it on Youj's tokens. It does keep the rest of the contract: the Speed control slows it, reduced motion stops it, and it pauses offscreen. The Youj samples on this page were generated from the motion tokens, so their curves match the rest of the system.

#### Reduced motion

Nothing plays. The player shows `posterFrame`, which defaults to `'last'`, the resolved state: the check fully drawn, the logo complete. Pass `'first'` or a frame number for animations whose last frame isn't the meaningful one. Within a `segment`, `'first'` and `'last'` are the segment's ends. Switch on Reduced motion in any preview above to compare.

### Accessibility

- Without `label`, the player is decorative and `aria-hidden`. With `label`, it's an image (`role="img"`) with that name. Label an animation only when it carries meaning that isn't in the text beside it.
- An animation isn't an announcement. When it marks a change, like a payment going through, announce the change in a live region too. The checkout preview uses `role="status"`.
- Keep focus with the task. When the control that was focused disappears with its view, move focus to the new view. The checkout preview moves it to the confirmation.

---

# Capsule

> Put one row of controls or figures on a floating pill: live stats, a now-playing player, steppers, a search and small toggles.

Source: https://www.youj.dev/docs/components/capsule

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CpuIcon, LayersIcon, MaximizeIcon, ScissorsIcon, WandIcon } from '@youj/icons'
import { Button, Capsule, CapsuleSearch, CapsuleStepper, CapsuleToggle, StatPill } from '@youj/react'

export default function CapsuleDemo() {
  const [tool, setTool] = useState('cut')
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <CapsuleToggle
        aria-label="Tool"
        iconOnly
        value={tool}
        onValueChange={setTool}
        options={[
          { value: 'cut', label: 'Blade', icon: <ScissorsIcon size={16} /> },
          { value: 'layer', label: 'Layers', icon: <LayersIcon size={16} /> },
          { value: 'fx', label: 'Effects', icon: <WandIcon size={16} /> },
        ]}
      />
      <CapsuleStepper label="Tempo" defaultValue={124} min={60} max={200} unit="BPM" />
      <StatPill label="DSP" value={38} unit="%" icon={<CpuIcon />} trend={[22, 30, 26, 35, 31, 38]} />
      <CapsuleSearch shortcut="/" placeholder="Find a sample" />
      {/* A bare capsule holds your own controls. */}
      <Capsule>
        <Button variant="ghost" size="icon" aria-label="Full screen">
          <MaximizeIcon size={16} />
        </Button>
      </Capsule>
    </div>
  )
}
```

Each capsule type in a row: a tool toggle, a stepper, a stat pill, a search, and a bare capsule holding a button.

`Capsule` holds any controls you put in it, and `CapsuleLabel` gives a control a short name. Its height is the control height plus a 4px inset, so the controls inside sit evenly within its rounded ends and the capsule lines up with buttons and fields of its size.

```tsx
import { Button, Capsule, CapsuleLabel } from '@youj/react'

<Capsule>
  <CapsuleLabel>Export</CapsuleLabel>
  <Button size="sm">Render</Button>
</Capsule>
```

`size="sm"` makes a capsule for a dense toolbar.

## Installation & usage

The shell on its own:

```bash
pnpm add @youj/react
```

```tsx
import { Capsule, CapsuleLabel } from '@youj/react'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add capsule
```

It brings `youj-ui-core` with it.

Each member installs the shell with it.

Capsules are for controls that float over what they control: a toolbar over a canvas, a dock over a timeline, vitals in the corner of an editor. Each one is a single row on its own surface, the height of a control plus a small inset, so capsules line up with each other and with buttons and fields of the same size. [Stat Pill](https://www.youj.dev/docs/components/stat-pill), [Capsule Stepper](https://www.youj.dev/docs/components/capsule-stepper), [Capsule Search](https://www.youj.dev/docs/components/capsule-search) and [Capsule Toggle](https://www.youj.dev/docs/components/capsule-toggle) are made on it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default'` | `'default'` | `sm` for a dense toolbar; the default lines up with default-size controls. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Every capsule carries `data-capsule`, and a `data-slot` of its own: `capsule`, `stat-pill`, `capsule-player`, `capsule-stepper-group`, `capsule-search` and `capsule-toggle`. Short names inside use `capsule-label` and units use `capsule-unit`. In Bezel a capsule is a pill lifted on a hairline, with its labels in small mono capitals. A theme with square corners keeps it square. In Classic it's a bordered rounded panel.

---

# Stat Pill

> Show one live figure in a capsule, with its unit and how it's changing.

Source: https://www.youj.dev/docs/components/stat-pill

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ActivityIcon, CpuIcon, HardDriveIcon } from '@youj/icons'
import { StatPill } from '@youj/react'

export default function StatPillDemo() {
  const [load, setLoad] = useState([31, 36, 33, 40, 37, 42])
  useEffect(() => {
    // A new reading every two seconds, like a live feed.
    const id = setInterval(() => setLoad((l) => [...l.slice(-7), 30 + Math.round(Math.random() * 16)]), 2000)
    return () => clearInterval(id)
  }, [])
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <StatPill label="CPU" icon={<CpuIcon />} value={load[load.length - 1]!} unit="%" trend={load} />
      <StatPill label="Latency" icon={<ActivityIcon />} value={42} unit="ms" delta={-6} better="down" />
      <StatPill label="Cache" icon={<HardDriveIcon />} value={2.4} unit="GB" delta={0.3} />
    </div>
  )
}
```

Three pills: a live CPU load with a trend line, a latency that fell by 6 ms, and a cache that grew by 0.3 GB.

`delta` is the change since the last reading. `better` says which way is good, so the change is tinted to match. The default is `up`. Use `down` for latency and errors, and `none` for figures such as loudness, where a change is just news and stays neutral.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stat-pill
```

It brings `capsule`, `counter`, `sparkline`, `youj-core`, `youj-labels-stat-pill`, `youj-ui-core` with it.

Use a stat pill for a figure people glance at while they work: the CPU load in an editor, the latency of a stream, the size of a cache. It shows an icon, the figure's name, the value with its unit, and optionally how it's moving, either a change since the last reading or a small trend line.

```tsx
import { StatPill } from '@youj/react'
import { ActivityIcon } from '@youj/icons'

<StatPill label="Latency" icon={<ActivityIcon />} value={42} unit="ms" delta={-6} better="down" />
```

`format` takes `Intl.NumberFormat` options for the value. Without it, the value keeps its own decimals. `trend` takes recent readings, oldest first, and draws them as a small line with a dot on the latest one.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | What the figure is: the eyebrow before it. Keep it short ("CPU", "Tempo"). |
| `value` (required) | `number` |  |  |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the value: compact notation, fraction digits, percent. Default: the value’s own decimals, so a count never passes through fractions. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `unit` | `ReactNode` |  | Set small and muted after the value: "ms", "fps", "GB". |
| `icon` | `ReactNode` |  | A decorative icon in a disc at the start. |
| `delta` | `number` |  | The change since the last reading, signed, in the value's terms: 4.2 reads "▲ 4.2". |
| `deltaFormat` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the delta. Default: up to one decimal. |
| `better` | `'up' \| 'down' \| 'none'` | `'up'` | Which way is good: `up` (default, a rise is tinted success), `down` (latency, errors: a fall is), or `none` (loudness, temperature: a change is only news, and stays neutral). |
| `trend` | `readonly number[]` |  | Recent readings, oldest first: a word-sized trend with a dot on the latest. |
| `size` | `'sm' \| 'default'` | ``default`` | `sm` for a dense toolbar; the default lines up with default-size controls. |

### Styling

Parts: `stat-pill`, `stat-pill-icon`, `capsule-label`, `stat-pill-value`, `capsule-unit` and `stat-pill-delta` (with `data-direction` and `data-tone`).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| New value | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | counts from where it is to the new value; the first reading is shown as it is |
| New reading | `duration.slow` | 340ms | the trend line morphs point by point and its dot glides to the latest reading |

**Reduced motion:** Values and the trend change at once.

### Accessibility

- The name, value and unit are plain text, so they're read in order.
- The direction of a change is spoken ("Up 4.2"), so it isn't carried by color alone.
- The icon and the trend line are decorative.
- If the figure updates often, don't make it a live region; people can read it when they want.

---

# Capsule Stepper

> Nudge a number up or down with − and + in a capsule.

Source: https://www.youj.dev/docs/components/capsule-stepper

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CapsuleStepper } from '@youj/react'

export default function CapsuleStepperDemo() {
  const [zoom, setZoom] = useState<number | null>(1)
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <CapsuleStepper label="Tempo" defaultValue={124} min={60} max={200} unit="BPM" />
      <CapsuleStepper aria-label="Zoom" value={zoom} onValueChange={setZoom} min={0.25} max={4} step={0.25} format={{ style: 'percent' }} />
    </div>
  )
}
```

A Tempo stepper with a BPM unit, and a Zoom stepper that shows percentages in quarter steps.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add capsule-stepper
```

It brings `button`, `capsule`, `icon-minus`, `icon-plus`, `youj-core`, `youj-labels-capsule-stepper`, `youj-ui-core` with it.

Use a capsule stepper for a number people adjust in small steps rather than type: a tempo, a zoom level, a count of takes. You can still click the number and type one.

```tsx
import { CapsuleStepper } from '@youj/react'

<CapsuleStepper label="Tempo" defaultValue={124} min={60} max={200} unit="BPM" />
```

It's built on Base UI's number field, like [Number Input](https://www.youj.dev/docs/components/number-input). Values are read and written for the locale, kept between `min` and `max`, and step by `step`. Shift with an arrow key steps by `largeStep`. Holding a button keeps stepping, and a button turns off at its end of the range. `format` takes `Intl.NumberFormat` options, such as `{ style: 'percent' }`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` |  |  |
| `defaultValue` | `number \| null` |  |  |
| `onValueChange` | `(value: number \| null) => void` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` | `1` | Per press and ArrowUp/Down. |
| `largeStep` | `number` | `10` | Per Shift+ArrowUp/Down. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options: { maximumFractionDigits: 1 }, { style: 'percent' }… |
| `locale` | `Intl.LocalesArgument` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | A short eyebrow at the start ("Tempo"). It names the field too, unless `aria-label` does. |
| `aria-label` | `string` |  |  |
| `unit` | `string` |  | Set small and muted after the value ("BPM", "×"), and read after it. |
| `size` | `'sm' \| 'default'` | `'default'` |  |
| `disabled` | `boolean` |  |  |
| `readOnly` | `boolean` |  |  |
| `name` | `string` |  |  |
| `id` | `string` |  |  |
| `className` | `string` |  | Classes for the capsule. |
| `ref` | `Ref<HTMLInputElement>` |  |  |

### Styling

Parts: `capsule-stepper`, `capsule-stepper-group` (the capsule), `capsule-stepper-window`, `capsule-stepper-value` and `capsule-unit`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Step | `spring.snappy` | 0.2s, bounce 0 | the new number rolls in from the side it moved, up for more and down for less |

**Reduced motion:** The number changes in place.

### Accessibility

- `label` names the field. Without one, use `aria-label`.
- `unit` is read after the value.
- The buttons are named "Increase" and "Decrease" by the labels, which the language packs translate.

---

# Capsule Search

> A small search capsule with its shortcut on it, which opens when you start searching.

Source: https://www.youj.dev/docs/components/capsule-search

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CapsuleSearch } from '@youj/react'

export default function CapsuleSearchDemo() {
  const [submitted, setSubmitted] = useState('')
  return (
    <div className="flex flex-col items-center gap-3">
      <CapsuleSearch shortcut="/" placeholder="Search samples" onSubmit={setSubmitted} />
      <p className="text-ui-sm text-fg-muted">{submitted ? `Searched for “${submitted}”` : 'Press / to search, Enter to submit.'}</p>
    </div>
  )
}
```

A search capsule with a / shortcut that reports what was submitted when you press Enter.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add capsule-search
```

It brings `button`, `icon-search`, `icon-x`, `kbd`, `morph-label`, `use-controllable-state`, `youj-core`, `youj-labels-capsule-search`, `youj-ui-core` with it.

The copy is 16 registry items, about 7,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-engine`, `icon-loader-ring`, `icon-search`, `icon-x`, `kbd`, `morph-label`, `spinner`, `use-controllable-state`.

Use a capsule search where space is tight but search is always one key away: a toolbar, an editor's top bar, a dock. It waits as a small capsule showing its shortcut. When you press the shortcut or click it, it widens to make room to type.

```tsx
import { CapsuleSearch } from '@youj/react'

<CapsuleSearch shortcut="/" placeholder="Search samples" onValueChange={setQuery} onSubmit={runSearch} />
```

`shortcut` is any single key, such as `/`, or `mod+<key>`, such as `mod+k` for ⌘K on Apple devices and Ctrl K elsewhere. The shortcut works from anywhere on the page, but a plain key is ignored while someone is typing in another field. `width` sets how wide it is at rest and when open. By default that's 11rem and 18rem, and it never grows wider than its container.

It stays open while it holds text. Once there's text, the shortcut hint becomes a clear button. Escape clears the text, and a second Escape leaves the field.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  |  |
| `defaultValue` | `string` | `''` |  |
| `onValueChange` | `(value: string) => void` |  |  |
| `onSubmit` | `(value: string) => void` |  | Runs on Enter with the query. |
| `shortcut` | `string` |  | A key that focuses the field from anywhere: `/`, or `mod+k` (⌘K on Apple, Ctrl K elsewhere). Shown as a hint at rest. |
| `width` | `{ rest: string; open: string }` | `{ rest: '11rem', open: '18rem' }` | Its width at rest and open. |
| `size` | `'sm' \| 'default'` | `'default'` |  |

Also takes the props of `ComponentProps<'input'>`.

### Styling

Parts: `capsule-search` (with `data-open`), `capsule-search-input` and `capsule-search-hint`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open and close | `spring.snappy` | 0.2s, bounce 0 | the capsule widens with its ends kept round and its contents unstretched; a quick focus and blur reverses mid-way |

**Reduced motion:** It opens and closes at once.

### Accessibility

- It's a search box, named "Search" by default. `aria-label` renames it.
- `aria-keyshortcuts` announces the shortcut.
- The clear button is named by the labels' `clear`, which the language packs translate.

---

# Capsule Toggle

> Choose one of two or three options in a capsule.

Source: https://www.youj.dev/docs/components/capsule-toggle

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { LayoutGridIcon, LayoutListIcon } from '@youj/icons'
import { CapsuleToggle } from '@youj/react'

export default function CapsuleToggleDemo() {
  const [monitor, setMonitor] = useState('mix')
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <CapsuleToggle
        label="Monitor"
        value={monitor}
        onValueChange={setMonitor}
        options={[
          { value: 'source', label: 'Source' },
          { value: 'mix', label: 'Mix' },
          { value: 'master', label: 'Master' },
        ]}
      />
      <CapsuleToggle
        aria-label="Layout"
        iconOnly
        defaultValue="grid"
        options={[
          { value: 'grid', label: 'Grid', icon: <LayoutGridIcon size={16} /> },
          { value: 'list', label: 'List', icon: <LayoutListIcon size={16} /> },
        ]}
      />
    </div>
  )
}
```

A labeled three-way Monitor toggle, and an icon-only Layout toggle between grid and list.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add capsule-toggle
```

It brings `capsule`, `segmented-control`, `youj-ui-core` with it.

Use a capsule toggle for a small choice that sits with other floating controls: a monitor source, a layout, a snap setting. It's a [Segmented Control](https://www.youj.dev/docs/components/segmented-control) that uses the capsule as its track, so the selected option glides inside the pill. For more than three options, use a Segmented Control or [Tabs](https://www.youj.dev/docs/components/tabs).

```tsx
import { CapsuleToggle } from '@youj/react'

<CapsuleToggle
  label="Monitor"
  value={monitor}
  onValueChange={setMonitor}
  options={[
    { value: 'source', label: 'Source' },
    { value: 'mix', label: 'Mix' },
    { value: 'master', label: 'Master' },
  ]}
/>
```

`label` puts a short name in front of the options. `iconOnly` shows only each option's `icon`, and its label becomes the option's name.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `readonly CapsuleToggleOption[]` |  | Two or three options. |
| `label` | `string` |  | A short eyebrow at the start ("View"). It names the group too, unless `aria-label` does. |
| `iconOnly` | `boolean` | `false` | Shows only the icons; each option is named by its label. |
| `size` | `'sm' \| 'default'` | `'default'` |  |
| `aria-label` | `string` |  | Names the control for assistive tech, e.g. "View" or "Range". |
| `variant` | `'underline' \| 'pill'` | `'underline'` | `underline` (a bar on a hairline) or `pill` (a raised key in a recessed track). |
| `defaultValue` | `string` |  | The segment pressed at first (uncontrolled). Leave it out to start with none pressed. |
| `value` | `string` |  | The pressed segment's value (controlled). |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), a new choice plays `select`. `false` keeps this one silent. |
| `onValueChange` | `(value: string) => void` |  | Called with the newly pressed segment's value. Never called with an empty value. |

### Styling

Parts: `capsule-toggle`, `capsule-label`, then the segmented control's own `segmented-control`, `segmented-control-item` and `toggle-group-indicator`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Choose | `spring.smooth` | 0.36s, bounce 0 | the selected key glides to the new option, and changes course if you choose again mid-way |

**Reduced motion:** The key jumps to the new option.

### Accessibility

- It's a group named by `label` or `aria-label`, with one tab stop. The arrow keys move between options.
- One option is always selected, and each option says whether it's pressed.
- With sound on, a new choice plays `select`. `sound={false}` turns it off.

---

# Combobox

> Choose a value from a searchable list, with groups and async results.

Source: https://www.youj.dev/docs/components/combobox

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Avatar, AvatarFallback, Field, FieldDescription, FieldLabel } from '@youj/react'
import { Combobox, type ComboboxOption } from '@youj/react/command'

const PEOPLE = [
  { id: 'ada', name: 'Ada Lovelace', team: 'Engineering' },
  { id: 'grace', name: 'Grace Hopper', team: 'Engineering' },
  { id: 'margaret', name: 'Margaret Hamilton', team: 'Engineering' },
  { id: 'alan', name: 'Alan Turing', team: 'Engineering' },
  { id: 'dieter', name: 'Dieter Rams', team: 'Design' },
  { id: 'susan', name: 'Susan Kare', team: 'Design' },
  { id: 'paula', name: 'Paula Scher', team: 'Design' },
  { id: 'katherine', name: 'Katherine Johnson', team: 'Research' },
  { id: 'claude', name: 'Claude Shannon', team: 'Research' },
]

const initials = (name: string) =>
  name
    .split(' ')
    .map((part) => part[0])
    .join('')

const OPTIONS: ComboboxOption[] = PEOPLE.map((person) => ({
  value: person.id,
  label: person.name,
  description: `${person.id}@orion.dev`,
  group: person.team,
  icon: (
    <Avatar size="sm" className="size-5">
      <AvatarFallback className="text-[9px]">{initials(person.name)}</AvatarFallback>
    </Avatar>
  ),
}))

export default function ComboboxDemo() {
  const [owner, setOwner] = useState<string | null>('grace')

return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Owner</FieldLabel>
      <Combobox
        options={OPTIONS}
        value={owner}
        onValueChange={setOwner}
        placeholder="Assign an owner"
        searchPlaceholder="Search people…"
        emptyMessage="Nobody matches."
        clearable
      />
      <FieldDescription>Gets deploy alerts and approves production releases.</FieldDescription>
    </Field>
  )
}
```

An owner field over nine people grouped by team, each with an avatar and an email, and a clear button.

Long labels truncate in the trigger and in the rows, and a row's description gives way before its name. The popup follows the trigger's width. Give it more room with `contentClassName`, for example `w-80`, when the trigger is narrow.

### Async search

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { Combobox, type ComboboxOption } from '@youj/react/command'

const DIRECTORY: ComboboxOption[] = [
  { value: 'ada', label: 'Ada Lovelace', description: 'ada@orion.dev' },
  { value: 'barbara', label: 'Barbara Liskov', description: 'barbara@orion.dev' },
  { value: 'donald', label: 'Donald Knuth', description: 'don@orion.dev' },
  { value: 'edsger', label: 'Edsger Dijkstra', description: 'edsger@orion.dev' },
  { value: 'frances', label: 'Frances Allen', description: 'frances@orion.dev' },
  { value: 'john', label: 'John Backus', description: 'john@orion.dev' },
  { value: 'ken', label: 'Ken Thompson', description: 'ken@orion.dev' },
  { value: 'radia', label: 'Radia Perlman', description: 'radia@orion.dev' },
]

// Stands in for a request to your API.
function searchDirectory(query: string): Promise<ComboboxOption[]> {
  const q = query.trim().toLowerCase()
  return new Promise((resolve) =>
    setTimeout(() => resolve(DIRECTORY.filter((person) => person.label.toLowerCase().includes(q))), 650),
  )
}

export default function ComboboxAsync() {
  const [search, setSearch] = useState('')
  const [results, setResults] = useState<ComboboxOption[]>([])
  const [loading, setLoading] = useState(true)

useEffect(() => {
    let live = true
    setLoading(true)
    searchDirectory(search).then((people) => {
      // A slower, older request never overwrites a newer one.
      if (!live) return
      setResults(people)
      setLoading(false)
    })
    return () => {
      live = false
    }
  }, [search])

return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Reviewer</FieldLabel>
      <Combobox
        options={results}
        onSearchChange={setSearch}
        loading={loading}
        loadingLabel="Searching the directory…"
        placeholder="Find a reviewer"
        searchPlaceholder="Search the directory…"
        emptyMessage={`Nobody called “${search}”.`}
      />
      <FieldDescription>Results come from the company directory.</FieldDescription>
    </Field>
  )
}
```

A reviewer field that searches a directory through a simulated 650 ms request and shows a loading row while it waits.

Pass `onSearchChange` and the built-in filtering turns off: fetch the matches yourself and pass them as `options`. While `loading` is true the list shows a loading row, which is announced, and the empty message waits until the results arrive.

Ignore responses from stale requests, as the example does, so a slow early request can't overwrite a newer one. The chosen option stays displayable in the trigger after it leaves `options`.

### Creating options

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { Combobox, type ComboboxOption } from '@youj/react/command'

const FRAMEWORKS: ComboboxOption[] = [
  { value: 'next', label: 'Next.js' },
  { value: 'remix', label: 'Remix' },
  { value: 'astro', label: 'Astro' },
  { value: 'sveltekit', label: 'SvelteKit' },
  { value: 'nuxt', label: 'Nuxt' },
  { value: 'vite', label: 'Vite (static)' },
]

export default function ComboboxCreate() {
  const [options, setOptions] = useState(FRAMEWORKS)
  const [value, setValue] = useState<string | null>(null)

return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Framework</FieldLabel>
      <Combobox
        options={options}
        value={value}
        onValueChange={setValue}
        placeholder="Pick a framework"
        searchPlaceholder="Search or create…"
        onCreate={(label) => {
          const option = { value: label.toLowerCase().replace(/\W+/g, '-'), label }
          setOptions((current) => [...current, option])
          return option
        }}
      />
      <FieldDescription>Type one that isn’t listed to add it.</FieldDescription>
    </Field>
  )
}
```

A framework field where typing a name that isn't listed offers to add it as a new option.

`onCreate` offers a "Create “…”" row for text that matches no option. Return the new option, or a promise of it, to select it. `createLabel` changes the row's wording.

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add combobox
```

It brings `button`, `command`, `field`, `icon-chevron-down`, `icon-plus`, `icon-x`, `input`, `popover`, `presentation`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-combobox`, `youj-ui-core` with it.

The copy is 31 registry items, about 10,300 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `checkbox`, `collapse`, `command`, `dialog`, `field`, `icon-check`, `icon-chevron-down`, `icon-engine`, `icon-loader-ring` and 12 more.

Requires `cmdk`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/command`.

Use Combobox to choose one value from a list that needs search, such as a directory of people. Use [Multi-select](https://www.youj.dev/docs/components/multi-select) for several values, or [Tag Input](https://www.youj.dev/docs/components/tag-input) for free-form entries. For short lists, use [Select](https://www.youj.dev/docs/components/select) or [Radio Group](https://www.youj.dev/docs/components/radio-group).

```tsx
import { useState } from 'react'
import { Field, FieldLabel } from '@youj/react'
import { Combobox } from '@youj/react/command'

const regions = [
  { value: 'iad1', label: 'Washington, D.C.', group: 'Americas' },
  { value: 'fra1', label: 'Frankfurt', group: 'Europe' },
  { value: 'hnd1', label: 'Tokyo', group: 'Asia Pacific' },
]

export function RegionField() {
  const [region, setRegion] = useState<string | null>('fra1')
  return (
    <Field>
      <FieldLabel>Region</FieldLabel>
      <Combobox options={regions} value={region} onValueChange={setRegion} placeholder="Choose a region" />
    </Field>
  )
}
```

The trigger is a field-styled button with `role="combobox"`, named by the `FieldLabel` around it. It opens a [Popover](https://www.youj.dev/docs/components/popover) holding a [Command](https://www.youj.dev/docs/components/command), so the search, the gliding active row and the list's height all behave like the command menu. Each option has a `value` and a `label`, and can add a `description` (searched too), an `icon`, a `group` heading, extra `keywords` and `disabled`. `onValueChange` hands you the value and the option.

Typing a letter on the closed trigger opens it with that letter already searched. With `clearable`, a clear button sits in the trigger, and Delete or Backspace clears the value from the keyboard.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ComboboxOption[]` |  |  |
| `value` | `string \| null` |  |  |
| `defaultValue` | `string \| null` | `null` |  |
| `onValueChange` | `(value: string \| null, option: ComboboxOption \| null) => void` |  |  |
| `placeholder` | `string` | `"Select…"` | Shown in the trigger when nothing is chosen. |
| `searchPlaceholder` | `string` | `"Search…"` | The search field's placeholder and accessible name. |
| `emptyMessage` | `ReactNode` | `"No results."` | Shown when no row matches. |
| `clearable` | `boolean` | `false` | Shows a clear button (and lets Delete clear) while a value is chosen. |
| `onSearchChange` | `(search: string) => void` |  | Async search: called as the text changes. Built-in filtering turns off; pass the matching `options`. |
| `loading` | `boolean` | `false` | Shows the loading row (async search). |
| `loadingLabel` | `string` | `"Loading…"` | Announced and shown while loading. |
| `onCreate` | `(label: string) => ComboboxOption \| void \| Promise<ComboboxOption \| void>` |  | Offers a "Create" row for text that matches no option. Return (or resolve to) the new option to select it; the Combobox remembers it for display. |
| `createLabel` | `(search: string) => ReactNode` | ``Create “text”`` | The create row's label. |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits the value with a native form. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `contentClassName` | `string` |  | Classes for the popup (its width follows the trigger by default). |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |
| `aria-label` | `string` |  |  |

`ComboboxOption` is `{ value, label, description?, icon?, group?, keywords?, disabled? }`.

### Long lists

Every mounted row costs a registration, a score and a re-render on each keystroke, so past 100 options the Combobox mounts only the 100 best matches, in order of match, and ends them with a note ("Showing 100 of 2,000. Keep typing to narrow the results."). Searching reaches every option. With 2,000 options a keystroke takes about 35 ms where it took about 120 ms, and clearing the search about 0.07 s where it took 0.2 s (Chromium on a laptop, development build; 4x CPU throttling shows the same ratios).

- **Up to 100 options:** everything is mounted and cmdk filters, as before.
- **100 to about 5,000 options:** pass them all. The filter runs on every keystroke over all options, which stays under a few milliseconds per thousand. Define the `options` array outside render, or memoise it, so unchanged rows aren't re-rendered.
- **More than that, or options that live on a server:** use `onSearchChange` and pass the matches. Your results are cut to 100 rows too, so return the best 100 or fewer.

### Touch

On a touch device the list opens as a bottom sheet with a grab handle, the search field at the top and 48px rows. It opens with the list in view and the on-screen keyboard down; tap the field to search. While the keyboard is up, the sheet sits on top of it and is only as tall as the space that's left, so the field stays visible, and it keeps its height as results narrow so the field doesn't jump. A tap on a row picks it and closes the sheet. Pull the sheet down, tap outside it or press Escape to close it without picking, and focus returns to the trigger.

`presentation` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the popover on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the popup grows out of the trigger (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Keyboard open, Escape close |  | 0ms | Base UI sets `data-instant` |
| Chevron | `spring.snappy` | 0.2s, bounce 0 | turns over while open |
| Active row | `spring.smooth` | 0.36s, bounce 0 | one indicator glides between rows |
| List height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | eases as results come and go |
| Chosen row | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | its check draws in |

**Reduced motion:** The popup opens and closes at once, the chevron flips without turning, the highlight jumps to the active row, the list snaps to its height and the check appears drawn.

#### Reduced motion

The popup appears without growing, the chevron flips in place, the active row's highlight jumps instead of gliding, and the list changes height at once. Search, keyboard handling and announcements are unchanged.

### Accessibility

- The trigger has `role="combobox"` and is named by its `FieldLabel`, or by `aria-label` when it has no label. The description and error of its Field describe it, and `aria-invalid` and `aria-required` follow the Field.
- ArrowDown, ArrowUp, Enter or Space opens the list. Typing a character opens it with that character searched. In the list, arrows move, Enter picks and returns focus to the trigger, and Escape closes.
- The chosen row carries `aria-checked` and a drawn check. Groups are labeled by their heading.
- In a long list each row carries `aria-setsize` (all matches) and `aria-posinset`, so assistive tech announces "3 of 2000" rather than "3 of 100"; the note under the rows is announced when the list opens and as the search changes.
- Clearing, from the button or with Delete, is announced ("Selection cleared") and focus stays on the trigger. The clear button is named "Clear selection".
- The loading row is announced politely, and the empty message isn't shown until loading ends, so "No results" is never read out for results that are still coming.
- With `name`, a hidden input submits the value with a native form.

---

# Multi-select

> Choose several values from a searchable list and show them as compact chips.

Source: https://www.youj.dev/docs/components/multi-select

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Avatar, AvatarFallback, Field, FieldDescription, FieldLabel } from '@youj/react'
import { MultiSelect, type MultiSelectOption } from '@youj/react/command'

const initials = (name: string) =>
  name
    .split(' ')
    .map((part) => part[0])
    .join('')

const OPTIONS: MultiSelectOption[] = PEOPLE.map((person) => ({
  value: person.id,
  label: person.name,
  description: `${person.id}@orion.dev`,
  group: person.team,
  icon: (
    <Avatar size="sm" className="size-5">
      <AvatarFallback className="text-[9px]">{initials(person.name)}</AvatarFallback>
    </Avatar>
  ),
}))

export default function MultiSelectDemo() {
  const [members, setMembers] = useState(['ada', 'dieter', 'grace'])

return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Members</FieldLabel>
      <MultiSelect
        options={OPTIONS}
        value={members}
        onValueChange={setMembers}
        placeholder="Add members"
        searchPlaceholder="Search people…"
        emptyMessage="Nobody matches."
      />
      <FieldDescription>Members can deploy previews. Owners approve production.</FieldDescription>
    </Field>
  )
}
```

A members field over nine people grouped by team, with three chosen to start.

### Limits

```tsx
'use client'

import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { MultiSelect, type MultiSelectOption } from '@youj/react/command'

function Dot({ className }: { className: string }) {
  return <span aria-hidden className={`size-2 rounded-full ${className}`} />
}

const LABELS: MultiSelectOption[] = [
  { value: 'bug', label: 'Bug', icon: <Dot className="bg-danger" /> },
  { value: 'feature', label: 'Feature', icon: <Dot className="bg-accent" /> },
  { value: 'perf', label: 'Performance', icon: <Dot className="bg-warning" /> },
  { value: 'docs', label: 'Documentation', icon: <Dot className="bg-success" /> },
  { value: 'design', label: 'Design', icon: <Dot className="bg-fg-muted" /> },
  { value: 'infra', label: 'Infrastructure', icon: <Dot className="bg-fg-subtle" /> },
]

export default function MultiSelectMaxCount() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Labels</FieldLabel>
      <MultiSelect options={LABELS} defaultValue={['bug', 'perf']} maxCount={3} placeholder="Add labels" searchPlaceholder="Search labels…" />
      <FieldDescription>Up to three per issue.</FieldDescription>
    </Field>
  )
}
```

A labels field capped at three.

`maxCount` caps the selection. The count shows under the list, and the remaining rows disable once the limit is reached, which is announced. "Select all" only appears when the limit allows every option.

### Overflow

```tsx
'use client'

import { Field, FieldLabel } from '@youj/react'
import { MultiSelect } from '@youj/react/command'

const REGIONS = [
  { value: 'iad', label: 'Washington, D.C.', group: 'Americas' },
  { value: 'sfo', label: 'San Francisco', group: 'Americas' },
  { value: 'gru', label: 'São Paulo', group: 'Americas' },
  { value: 'fra', label: 'Frankfurt', group: 'Europe' },
  { value: 'lhr', label: 'London', group: 'Europe' },
  { value: 'hnd', label: 'Tokyo', group: 'Asia Pacific' },
  { value: 'syd', label: 'Sydney', group: 'Asia Pacific' },
]

export default function MultiSelectOverflow() {
  return (
    <Field className="w-60">
      <FieldLabel>Regions</FieldLabel>
      {/* The popup can be wider than a narrow field. */}
      <MultiSelect options={REGIONS} defaultValue={['iad', 'sfo', 'fra', 'hnd', 'syd']} contentClassName="w-72" />
    </Field>
  )
}
```

Five regions chosen in a narrow field, with a wider popup.

The chips fill one line. As many as fit are shown, and the rest collapse into "+N", measured again whenever the value or the field's width changes. The popup follows the field's width. A narrow field can give it more room with `contentClassName`.

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add multi-select
```

It brings `badge`, `button`, `command`, `field`, `icon-chevron-down`, `input-group`, `popover`, `presence-list`, `presentation`, `use-announcer`, `use-controllable-state`, `use-resize-measure`, `youj-core`, `youj-labels-button-async`, `youj-labels-multi-select`, `youj-ui-core` with it.

The copy is 37 registry items, about 10,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `badge`, `button`, `checkbox`, `collapse`, `command`, `dialog`, `field`, `icon-check`, `icon-chevron-down`, `icon-engine` and 17 more.

Requires `cmdk`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/command`.

Use a multi-select to pick several items from a known list: members of a project, labels on an issue, regions to deploy to. The values stay visible as chips in the field. For one value from the same list, use a [Combobox](https://www.youj.dev/docs/components/combobox). For values people make up, such as topics or email domains, use a [Tag Input](https://www.youj.dev/docs/components/tag-input). A few options that all fit on screen read better as [Checkboxes](https://www.youj.dev/docs/components/checkbox).

```tsx
import { useState } from 'react'
import { Field, FieldLabel } from '@youj/react'
import { MultiSelect } from '@youj/react/command'

const people = [
  { value: 'ada', label: 'Ada Lovelace', group: 'Engineering' },
  { value: 'grace', label: 'Grace Hopper', group: 'Engineering' },
  { value: 'dieter', label: 'Dieter Rams', group: 'Design' },
]

export function MembersField() {
  const [members, setMembers] = useState<string[]>(['ada'])
  return (
    <Field>
      <FieldLabel>Members</FieldLabel>
      <MultiSelect options={people} value={members} onValueChange={setMembers} placeholder="Add members" />
    </Field>
  )
}
```

The field is an [Input Group](https://www.youj.dev/docs/components/input-group) frame that holds the chosen values as [Badge](https://www.youj.dev/docs/components/badge) chips, each with its own remove button. The trigger beside them has `role="combobox"` and opens a [Command](https://www.youj.dev/docs/components/command) of checkbox rows in a [Popover](https://www.youj.dev/docs/components/popover). Enter toggles a row and the popup stays open, so several values can be picked in one go. Options take the same shape as the Combobox's: `value`, `label`, and optionally `description`, `icon`, `group`, `keywords` and `disabled`.

A "Select all" row leads the list when you aren't searching. Over a partial selection it shows a mixed state. Turn it off with `selectAll={false}`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `MultiSelectOption[]` |  |  |
| `value` | `string[]` |  |  |
| `defaultValue` | `string[]` | `[]` |  |
| `onValueChange` | `(value: string[]) => void` |  |  |
| `placeholder` | `string` | `"Select…"` | Shown when nothing is chosen. |
| `searchPlaceholder` | `string` | `"Search…"` | The search field's placeholder and accessible name. |
| `emptyMessage` | `ReactNode` | `"No results."` | Shown when no row matches. |
| `maxCount` | `number` |  | The most values that can be chosen; further rows disable once it's reached. |
| `selectAll` | `boolean` | `true` | Shows a "Select all" row (when not searching, and when the limit allows all). |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits each value with a native form, under this name. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `contentClassName` | `string` |  | Classes for the popup (its width follows the field by default). |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |
| `aria-label` | `string` |  |  |

`MultiSelectOption` is `{ value, label, description?, icon?, group?, keywords?, disabled? }`.

### Long lists

Every mounted row costs a registration, a score and a re-render on each keystroke, so past 100 options the MultiSelect mounts only the 100 best matches, in order of match, and ends them with a note ("Showing 100 of 2,000. Keep typing to narrow the results."). Searching reaches every option. With 2,000 options a keystroke takes about 35 ms where it took about 265 ms, and clearing the search about 0.05 s where it took 0.36 s (Chromium on a laptop, development build; 4x CPU throttling shows the same ratios).

- **Up to 100 options:** everything is mounted and cmdk filters, as before.
- **100 to about 5,000 options:** pass them all. The filter runs on every keystroke over all options, which stays under a few milliseconds per thousand. Define the `options` array outside render, or memoise it, so unchanged rows aren't re-rendered.
- **More than that:** MultiSelect has no async search; narrow the list before passing it (a first-level filter, a scoped query). "Select all" selects every option, shown or not.

### Touch

On a touch device the list opens as a bottom sheet with a grab handle, a search field and a Done button at the top, and 48px checkbox rows. A tap toggles a row and the sheet stays open; Done, pulling the sheet down, tapping outside it or Escape closes it, and focus returns to the field. The sheet opens with the on-screen keyboard down. Tap the search field to type: the sheet sits on top of the keyboard with the field in view, and it keeps its height as results narrow.

`presentation` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the popover on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Chip enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades down into its slot while the others glide aside (PresenceList) |
| Chip leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades where it stands |
| Chips close the gap | `spring.smooth` | 0.36s, bounce 0 |  |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the popup grows out of the field (`yj-pop`) |
| Chevron | `spring.snappy` | 0.2s, bounce 0 | turns over while open |
| Active row | `spring.smooth` | 0.36s, bounce 0 | one indicator glides between rows |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | a row's checkbox draws its mark |

**Reduced motion:** Chips appear, disappear and reflow in one frame. The popup opens at once, the highlight jumps and the chevron flips in place.

#### Reduced motion

Chips are added, removed and reflowed without fading or gliding, and the popup, the chevron and the active row change at once. Selection, keyboard handling and announcements are unchanged.

### Accessibility

- The trigger has `role="combobox"` and is named by its `FieldLabel`, or by `aria-label`. The Field's description and error describe it.
- ArrowDown, Enter or Space opens the list. In the list, Enter toggles a row and Escape closes. Backspace in an empty search removes the last value.
- On the trigger, Backspace or ArrowLeft moves to the last chip. Arrows move between chips, Backspace or Delete removes the focused chip, and focus lands on its neighbor, so a keyboard user never falls off the field.
- Each chip's remove button is named after its value. Removals, "Select all" and reaching the limit are announced.
- In a long list each row carries `aria-setsize` (all matches) and `aria-posinset`, so assistive tech announces "3 of 2000" rather than "3 of 100"; the note under the rows is announced when the list opens and as the search changes.
- With `name`, each value is submitted with a native form under that name.

---

# Color Picker

> Choose a color with sliders, swatches, hex or OKLCH values, or an eyedropper.

Source: https://www.youj.dev/docs/components/color-picker

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ColorPicker, Field, FieldDescription, FieldLabel } from '@youj/react'

export default function ColorPickerDemo() {
  const [color, setColor] = useState('#3554fc')

return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <Field>
        <FieldLabel>Brand color</FieldLabel>
        <ColorPicker value={color} onValueChange={setColor} aria-label="Brand color" />
        <FieldDescription>Used for buttons, links and focus rings.</FieldDescription>
      </Field>
      <div className="flex items-center gap-3 rounded-lg border border-line p-3">
        <span className="rounded-md px-3 py-1.5 text-ui font-medium text-[white]" style={{ backgroundColor: color }}>
          Preview
        </span>
        <span className="text-ui" style={{ color }}>
          A link in your color
        </span>
      </div>
    </div>
  )
}
```

A brand color field with a live preview of a button and a link in the chosen color.

- **The area** sets saturation across and brightness up and down. Click or drag anywhere in it. The thumb follows the pointer exactly, and glides to a new place when the color changes from a swatch or a field.
- **The hue** is a [Slider](https://www.youj.dev/docs/components/slider) on a spectrum track, from 0 to 359 degrees.
- **The eyedropper** samples any pixel on screen, in browsers that have one. Elsewhere the button isn't shown.
- **The fields** take hex and OKLCH. They commit on Enter or when they lose focus. Something they can't read is marked invalid, and put back on blur.
- **Swatches** default to the theme presets' accents, and the selected one is ringed.

### OKLCH and your own swatches

```tsx
'use client'

import { useState } from 'react'
import { ColorPicker, type Swatch } from '@youj/react'

const LABEL_COLORS: Swatch[] = [
  { value: 'oklch(0.72 0.15 158)', label: 'Mint' },
  { value: 'oklch(0.79 0.14 72)', label: 'Amber' },
  { value: 'oklch(0.68 0.18 24)', label: 'Coral' },
  { value: 'oklch(0.62 0.21 330)', label: 'Orchid' },
  { value: '#111111', label: 'Ink' },
]

export default function ColorPickerOklch() {
  const [value, setValue] = useState('oklch(0.72 0.15 158)')

return (
    <div className="flex flex-col items-start gap-3">
      <ColorPicker value={value} onValueChange={setValue} format="oklch" swatches={LABEL_COLORS} aria-label="Label color" />
      <code className="font-mono text-ui-sm text-fg-muted">{value}</code>
    </div>
  )
}
```

A picker in OKLCH with five label swatches of your own, and the value it holds shown under it.

`format="oklch"` makes `onValueChange` report OKLCH strings, which suit a theme built on perceptual lightness. `swatches` replaces the presets with your own `{ value, label }` pairs, and `swatches={[]}` removes the row.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add color-picker
```

It brings `button`, `icon-chevron-down`, `icon-pipette`, `input`, `input-group`, `popover`, `presentation`, `slider`, `sliding-indicator`, `youj-core`, `youj-labels-color-picker`, `youj-presets`, `youj-ui-core` with it.

The copy is 24 registry items, about 9,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-chevron-down`, `icon-engine`, `icon-loader-ring`, `icon-pipette`, `input`, `input-group`, `label` and 7 more.

Use it when people choose any color: a brand accent, a label, a chart series, a theme. The trigger shows the swatch and hex in the width of a text field, and the popover holds every way in: drag in the area, slide the hue, type a hex or OKLCH value, pick a swatch, or sample the screen with the browser's eyedropper. When the choice is one of a few named colors, a [Toggle Group](https://www.youj.dev/docs/components/toggle-group) or a [Radio Group](https://www.youj.dev/docs/components/radio-group) of swatches is quicker.

```tsx
import { useState } from 'react'
import { ColorPicker, Field, FieldLabel } from '@youj/react'

export function BrandColor() {
  const [color, setColor] = useState('#3554fc')
  return (
    <Field>
      <FieldLabel>Brand color</FieldLabel>
      <ColorPicker value={color} onValueChange={setColor} aria-label="Brand color" />
    </Field>
  )
}
```

`value` takes a hex or OKLCH string. The color is held as hue, saturation and brightness inside, so dragging to gray or black and back keeps the hue you had.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | A hex or OKLCH color string. |
| `defaultValue` | `string` | `palettes[0].accent.light` |  |
| `onValueChange` | `(value: string) => void` |  |  |
| `format` | `'hex' \| 'oklch'` | `'hex'` | What onValueChange reports. |
| `swatches` | `Swatch[]` |  | Default: the theme presets' accents. Pass [] for none. |
| `disabled` | `boolean` |  |  |
| `aria-label` | `string` | `'Color'` | Names the trigger. |
| `id` | `string` |  |  |
| `className` | `string` |  |  |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) is a popover under a pointer and a bottom sheet on touch; force either one. |
| `swatchOnly` | `boolean` |  | The trigger is the swatch alone, for a color that sits inside another control (ColorOpacityField). The hex is still in its name. |

`presetSwatches`, the theme presets' accents, is exported for building on.

### Touch

On a touch device the picker opens in a bottom sheet. The area is taller and its thumb larger, swatches are 44px targets, and the fields use 16px text so the page doesn't zoom. Dragging in the area or along the hue slider changes the color and never pulls the sheet down; pull from the handle or the space around the controls to close it, or tap outside it.

`presentation` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the popover on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Popover opens | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scales from 96% and fades in from the trigger (`yj-pop`) |
| Area thumb | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | glides when the color changes from a swatch or a field; follows a drag 1:1 |
| Swatch ring | `spring.smooth` | 0.36s, bounce 0 | glides to the selected swatch (Sliding Indicator) |
| Hue thumb |  | no easing | tracks the pointer 1:1, as every Slider |
| Popover closes | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |

**Reduced motion:** The area thumb and the swatch ring jump to their new places, and the popover opens at once.

#### Reduced motion

The area thumb and the swatch ring move straight to their new places, and the popover appears without scaling. Dragging, typing and the eyedropper work the same.

### Accessibility

- The trigger reads its label and the current value, such as "Brand color, #3554fc".
- The area is one focusable `slider` thumb whose value text names both axes. ArrowLeft and ArrowRight step saturation, ArrowUp and ArrowDown step brightness, and Shift steps by 10.
- The hue slider is named "Hue" and reads its value in degrees.
- Swatches are toggle buttons in a group named "Swatches", each named by its `label` and marked `aria-pressed` when selected.
- Escape closes the popover and returns focus to the trigger, as every [Popover](https://www.youj.dev/docs/components/popover) does.

---

# Color Opacity Field

> A color and its opacity as one control: a swatch, a hex field and a percentage.

Source: https://www.youj.dev/docs/components/color-opacity-field

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ColorOpacityField, type ColorOpacityValue } from '@youj/react'

export default function ColorOpacityFieldDemo() {
  const [value, setValue] = useState<ColorOpacityValue>({ color: '#4c6fff', opacity: 80 })
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <ColorOpacityField value={value} onValueChange={setValue} />
      <div className="h-12 rounded-lg" style={{ background: `color-mix(in srgb, ${value.color} ${value.opacity}%, transparent)` }} />
    </div>
  )
}
```

A fill color with its opacity, and the color it makes below.

The swatch opens a [Color Picker](https://www.youj.dev/docs/components/color-picker) in a popover. The hex field shows six digits without the `#`; paste or type what you have. The percentage next to it is a [Scrub Number Field](https://www.youj.dev/docs/components/scrub-number-field): drag its drop, type a value, or use the arrow keys.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add color-opacity-field
```

It brings `color-picker`, `icon-droplet`, `input-group`, `scrub-number-field`, `use-controllable-state`, `youj-core`, `youj-labels-color-opacity-field`, `youj-ui-core` with it.

The copy is 29 registry items, about 10,000 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `color-picker`, `field`, `icon-chevron-down`, `icon-droplet`, `icon-engine`, `icon-loader-ring`, `icon-pipette`, `input` and 11 more.

Use it where a color comes with an alpha, as in a shadow, a stroke or a fill. For a color alone, use a [Color Picker](https://www.youj.dev/docs/components/color-picker).

```tsx
import { useState } from 'react'
import { ColorOpacityField, type ColorOpacityValue } from '@youj/react'

export function Fill() {
  const [fill, setFill] = useState<ColorOpacityValue>({ color: '#4c6fff', opacity: 80 })
  return <ColorOpacityField value={fill} onValueChange={setFill} aria-label="Fill" />
}
```

The value is `{ color, opacity }`: `color` is `#rrggbb` and `opacity` runs from 0 to 100. The hex field reads 3, 4, 6 and 8 digits, with or without the `#`: `f80`, `#ff8800`, `ff880080`. The 4- and 8-digit forms carry an alpha, which sets the opacity. A paste that parses is applied at once; typed text commits on Enter or blur, is marked invalid while it isn't a color, and is put back on blur or Escape.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `ColorOpacityValue` |  |  |
| `defaultValue` | `ColorOpacityValue` | `{ color: '#000000', opacity: 100 }` |  |
| `onValueChange` | `(value: ColorOpacityValue) => void` |  |  |
| `size` | `'sm' \| 'default'` | `'default'` | `sm` fits a dense panel. |
| `disabled` | `boolean` |  |  |
| `aria-label` | `string` | `'Color'` | Names the whole group. |
| `id` | `string` |  |  |
| `className` | `string` |  |  |

### Accessibility

- The control is a `group` named by `aria-label` (default "Color"). Inside it, the swatch button says "Color, #4c6fff", the hex field is "Hex color" and the percentage is "Opacity".
- The hex field is a text field: Enter commits, Escape reverts, and invalid text sets `aria-invalid`.
- The opacity is a spinbutton with the keys of a [Scrub Number Field](https://www.youj.dev/docs/components/scrub-number-field#accessibility).
- The popover is the Color Picker's, so it keeps its keyboard support and becomes a sheet on touch.

---

# Currency Swap

> A converter card: what you pay over what you receive, a round button that flips them, the rate and the action. Crypto or plain money.

Source: https://www.youj.dev/docs/components/currency-swap

## Examples

### Swap crypto

```tsx
'use client'

import { CurrencySwap, type CurrencySwapAsset } from '@youj/react'

/* Each coin's own mark, drawn inline. */
const BTC =
  'M23.638 14.904c-1.602 6.43-8.113 10.34-14.542 8.736C2.67 22.05-1.244 15.525.362 9.105 1.962 2.67 8.475-1.243 14.9.358c6.43 1.605 10.342 8.115 8.738 14.548v-.002zm-6.35-4.613c.24-1.59-.974-2.45-2.64-3.03l.54-2.153-1.315-.33-.525 2.107c-.345-.087-.705-.167-1.064-.25l.526-2.127-1.32-.33-.54 2.165c-.285-.067-.565-.132-.84-.2l-1.815-.45-.35 1.407s.975.225.955.236c.535.136.63.486.615.766l-1.477 5.92c-.075.166-.24.406-.614.314.015.02-.96-.24-.96-.24l-.66 1.51 1.71.426.93.242-.54 2.19 1.32.327.54-2.17c.36.1.705.19 1.05.273l-.51 2.154 1.32.33.545-2.19c2.24.427 3.93.257 4.64-1.774.57-1.637-.03-2.58-1.217-3.196.854-.193 1.5-.76 1.68-1.93h.01zm-3.01 4.22c-.404 1.64-3.157.75-4.05.53l.72-2.9c.896.23 3.757.67 3.33 2.37zm.41-4.24c-.37 1.49-2.662.735-3.405.55l.654-2.64c.744.18 3.137.524 2.75 2.084v.006z'

const BitcoinMark = () => (
  <svg viewBox="0 0 24 24" aria-hidden focusable="false">
    <circle cx="12" cy="12" r="11" fill="#fff" />
    <path fill="#F7931A" d={BTC} />
  </svg>
)

const EthereumMark = () => (
  <svg viewBox="0 0 24 24" aria-hidden focusable="false">
    <circle cx="12" cy="12" r="11" fill="#fff" />
    <g transform="translate(5.5 5.5) scale(.54)">
      <path fill="#627EEA" d="M11.944 17.97L4.58 13.62 11.943 24l7.37-10.38-7.372 4.35h.003zM12.056 0L4.69 12.223l7.365 4.354 7.365-4.35L12.056 0z" />
    </g>
  </svg>
)

const SolanaMark = () => (
  <svg viewBox="0 0 24 24" aria-hidden focusable="false">
    <circle cx="12" cy="12" r="11" fill="#fff" />
    <g transform="translate(5.5 5.5) scale(.54)">
      <path fill="#9945FF" d="m23.8764 18.0313-3.962 4.1393a.9201.9201 0 0 1-.306.2106.9407.9407 0 0 1-.367.0742H.4599a.4689.4689 0 0 1-.2522-.0733.4513.4513 0 0 1-.1696-.1962.4375.4375 0 0 1-.0314-.2545.4438.4438 0 0 1 .117-.2298l3.9649-4.1393a.92.92 0 0 1 .3052-.2102.9407.9407 0 0 1 .3658-.0746H23.54a.4692.4692 0 0 1 .2523.0734.4531.4531 0 0 1 .1697.196.438.438 0 0 1 .0313.2547.4442.4442 0 0 1-.1169.2297zm-3.962-8.3355a.9202.9202 0 0 0-.306-.2106.941.941 0 0 0-.367-.0742H.4599a.4687.4687 0 0 0-.2522.0734.4513.4513 0 0 0-.1696.1961.4376.4376 0 0 0-.0314.2546.444.444 0 0 0 .117.2297l3.9649 4.1394a.9204.9204 0 0 0 .3052.2102c.1154.049.24.0744.3658.0746H23.54a.469.469 0 0 0 .2523-.0734.453.453 0 0 0 .1697-.1961.4382.4382 0 0 0 .0313-.2546.4444.4444 0 0 0-.1169-.2297zM.46 6.7225h18.7815a.9411.9411 0 0 0 .367-.0742.9202.9202 0 0 0 .306-.2106l3.962-4.1394a.4442.4442 0 0 0 .117-.2297.4378.4378 0 0 0-.0314-.2546.453.453 0 0 0-.1697-.196.469.469 0 0 0-.2523-.0734H4.7596a.941.941 0 0 0-.3658.0745.9203.9203 0 0 0-.3052.2102L.1246 5.9687a.4438.4438 0 0 0-.1169.2295.4375.4375 0 0 0 .0312.2544.4512.4512 0 0 0 .1692.196.4689.4689 0 0 0 .2518.0739z" />
    </g>
  </svg>
)

const UsdcMark = () => (
  <svg viewBox="0 0 24 24" aria-hidden focusable="false">
    <circle cx="12" cy="12" r="11" fill="#fff" />
    <g transform="translate(5.5 5.5) scale(.54)">
      <path fill="#2775CA" d="M20.788 3.832c-.101-.105-.197-.213-.301-.317-.103-.103-.211-.202-.32-.302A11.903 11.903 0 0 0 12 0a11.926 11.926 0 0 0-8.486 3.514C-1.062 8.09-1.16 15.47 3.213 20.168c.099.108.197.214.3.32.104.103.21.2.317.3A11.92 11.92 0 0 0 12 24c3.206 0 6.22-1.247 8.487-3.512 4.576-4.576 4.673-11.956.301-16.656zm-16.655.301A11.057 11.057 0 0 1 12 .874c2.825 0 5.49 1.048 7.55 2.958l-1.001 1.002A9.646 9.646 0 0 0 12 2.292a9.644 9.644 0 0 0-6.865 2.844A9.644 9.644 0 0 0 2.292 12c0 2.448.9 4.753 2.542 6.549L3.831 19.55C-.201 15.191-.101 8.367 4.133 4.133zm13.798 1.318v.002l-1.015 1.014A7.346 7.346 0 0 0 12 4.589 7.357 7.357 0 0 0 6.761 6.76 7.362 7.362 0 0 0 4.589 12a7.34 7.34 0 0 0 1.877 4.913l-1.014 1.016A8.77 8.77 0 0 1 3.167 12a8.77 8.77 0 0 1 2.588-6.245A8.771 8.771 0 0 1 12 3.167c2.213 0 4.301.809 5.931 2.284zM18.537 12c0 1.745-.681 3.387-1.916 4.622S13.746 18.538 12 18.538a6.491 6.491 0 0 1-4.296-1.621l-.001-.004c-.11-.094-.22-.188-.324-.291a6.027 6.027 0 0 1-.293-.326A6.47 6.47 0 0 1 5.466 12c0-1.746.679-3.387 1.914-4.621A6.488 6.488 0 0 1 12 5.465c1.599 0 3.105.576 4.295 1.62.111.096.224.19.326.295.104.104.2.214.295.324A6.482 6.482 0 0 1 18.537 12zM7.084 17.534h.001A7.349 7.349 0 0 0 12 19.413a7.35 7.35 0 0 0 5.239-2.174A7.354 7.354 0 0 0 19.412 12a7.364 7.364 0 0 0-1.876-4.916l1.013-1.012A8.777 8.777 0 0 1 20.834 12a8.765 8.765 0 0 1-2.589 6.246A8.764 8.764 0 0 1 12 20.834a8.782 8.782 0 0 1-5.93-2.285l1.014-1.015zm12.783 2.333A11.046 11.046 0 0 1 12 23.125a11.042 11.042 0 0 1-7.551-2.957l1.004-1.001a9.64 9.64 0 0 0 6.549 2.542 9.639 9.639 0 0 0 6.865-2.846A9.642 9.642 0 0 0 21.71 12a9.64 9.64 0 0 0-2.543-6.548l1.001-1.002c4.031 4.359 3.935 11.182-.301 15.417z" />
    </g>
  </svg>
)

const assets: CurrencySwapAsset[] = [
  { id: 'btc', symbol: 'BTC', name: 'Bitcoin', price: 64250, icon: <BitcoinMark /> },
  { id: 'eth', symbol: 'ETH', name: 'Ether', price: 3120.4, icon: <EthereumMark /> },
  { id: 'sol', symbol: 'SOL', name: 'Solana', price: 148.22, icon: <SolanaMark /> },
  { id: 'usdc', symbol: 'USDC', name: 'USD Coin', price: 1, decimals: 2, icon: <UsdcMark /> },
]

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function CurrencySwapDemo() {
  return <CurrencySwap assets={assets} defaultAmount={0.25} pendingLabel="Swapping…" successLabel="Swapped" onSubmit={() => wait(1200)} />
}
```

Type an amount, pick the two currencies, and the received amount rolls to its new figure digit by digit. Each side shows its value in `currency` below, and the rate sits under the pair.

The round button between the sides flips them: each side's amount and currency glide into the other's place while the arrows turn half a circle, and the amount you received becomes the amount you pay. Picking the currency the other side already holds flips the pair too.

### Top up a wallet

```tsx
'use client'

import { CurrencySwap, type CurrencySwapAsset } from '@youj/react'

const currencies: CurrencySwapAsset[] = [
  { id: 'eur', symbol: 'EUR', name: 'Euro', price: 1, decimals: 2 },
  { id: 'usd', symbol: 'USD', name: 'US dollar', price: 0.92, decimals: 2 },
  { id: 'gbp', symbol: 'GBP', name: 'Pound sterling', price: 1.17, decimals: 2 },
  { id: 'jpy', symbol: 'JPY', name: 'Japanese yen', price: 0.0061, decimals: 0 },
]

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

/* Topping up a travel wallet: a 0.5% exchange fee comes off through `convert`. */
export default function CurrencySwapCheckout() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex items-baseline justify-between px-1">
        <p className="text-ui font-medium text-fg">Top up travel wallet</p>
        <p className="text-ui-sm text-fg-muted">0.5% fee included</p>
      </div>
      <CurrencySwap
        assets={currencies}
        currency="EUR"
        defaultFrom="eur"
        defaultTo="jpy"
        defaultAmount={300}
        convert={(amount, from, to) => (from.price && to.price ? (amount * from.price * 0.995) / to.price : undefined)}
        submitLabel="Top up"
        pendingLabel="Topping up…"
        successLabel="Added to wallet"
        onSubmit={() => wait(1000)}
      />
    </div>
  )
}
```

Plain currencies in a wallet top-up, with a fee taken off through `convert` and the action renamed with `submitLabel`.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add currency-swap
```

It brings `async-button`, `button`, `counter`, `icon-arrow-up-down`, `select`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-currency-swap`, `youj-ui-core` with it.

The copy is 31 registry items, about 10,300 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `collapse`, `counter`, `field`, `icon-arrow-up-down`, `icon-check`, `icon-chevron-down`, `icon-chevron-up` and 12 more.

Give it the currencies, each with a `price` in `currency` (the value lines' currency, default `USD`), and an `onSubmit`. The rate is `from.price / to.price` unless you pass `rate`: a number is the live quote for the current pair (refresh it when the pair changes), a function is asked per pair. `convert` computes the received amount itself, for fees or slippage.

```tsx
'use client'

import { CurrencySwap, type CurrencySwapAsset } from '@youj/react'

const assets: CurrencySwapAsset[] = [
  { id: 'btc', symbol: 'BTC', name: 'Bitcoin', price: 64250 },
  { id: 'usdc', symbol: 'USDC', name: 'USD Coin', price: 1, decimals: 2 },
]

export function Swap() {
  return (
    <CurrencySwap
      assets={assets}
      defaultAmount={0.25}
      pendingLabel="Swapping…"
      successLabel="Swapped"
      onSubmit={({ from, to, amount }) => placeOrder(from.id, to.id, amount)}
    />
  )
}
```

The pair and the amount are each a value trio: `from`/`defaultFrom`/`onFromChange`, `to`/`defaultTo`/`onToChange` and `amount`/`defaultAmount`/`onAmountChange`. `onSwap` fires on a flip with the new pair. `onSubmit` is awaited as an [Async Button](https://www.youj.dev/docs/components/button#async-button)'s action: resolve for success, reject or throw for an error. Without `onSubmit` there is no action button.

Amounts and values format in the provider's locale (or `locale`). An asset's `decimals` caps its fraction digits; otherwise amounts show 4, or 4 significant digits below 1.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assets` (required) | `CurrencySwapAsset[]` |  | The currencies both pickers offer. At least two. |
| `from` | `string` |  | The id of the currency paid with (controlled). |
| `defaultFrom` | `string` |  | The starting currency paid with. Default: the first asset. |
| `onFromChange` | `(id: string) => void` |  |  |
| `to` | `string` |  | The id of the currency received (controlled). |
| `defaultTo` | `string` |  | The starting currency received. Default: the second asset. |
| `onToChange` | `(id: string) => void` |  |  |
| `amount` | `number \| null` |  | The amount paid, in `from` (controlled). `null` is empty. |
| `defaultAmount` | `number \| null` | `null` |  |
| `onAmountChange` | `(amount: number \| null) => void` |  |  |
| `rate` | `number \| ((from: CurrencySwapAsset, to: CurrencySwapAsset) => number \| undefined)` |  | How many `to` one `from` buys. A number is the quote for the current pair (the app refreshes it when the pair changes); a function is asked per pair. Default: from the assets' prices. |
| `convert` | `(amount: number, from: CurrencySwapAsset, to: CurrencySwapAsset) => number \| undefined` |  | The received amount, for conversions a rate can't express (fees, slippage). Wins over `rate` for the amount; the rate line still reads `rate`. |
| `currency` | `string` | `'USD'` | The currency the value lines are in (ISO 4217). |
| `onSwap` | `(pair: { from: string; to: string }) => void` |  | Fires on a flip, with the new pair. |
| `onSubmit` | `(swap: CurrencySwapSubmit) => unknown` |  | The primary action, awaited as an AsyncButton's `onAction`: resolve for success, reject or throw for an error. Without it there is no action button. |
| `submitLabel` | `ReactNode` | `"Swap"` | The action's label. |
| `pendingLabel` | `string` |  | Shown while `onSubmit` runs, and announced. |
| `successLabel` | `string \| ((result: unknown) => string)` |  | Shown once `onSubmit` resolves, and announced. |
| `errorLabel` | `string \| ((error: unknown) => string)` |  | Shown when `onSubmit` rejects, and announced assertively. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `disabled` | `boolean` | `false` |  |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), a flip sounds `tap` and a new currency `select`; the action sounds as an AsyncButton does. `false` keeps it silent. |

Also takes the props of `ComponentProps<'div'>`.

#### Data attributes

The root carries `data-disabled` when disabled. The parts are named in `data-slot`: `currency-swap-pay` and `currency-swap-receive` (the two sides), `currency-swap-amount` (the field), `currency-swap-received` (the result), `currency-swap-picker` (each currency picker), `currency-swap-mark` (a currency's mark), `currency-swap-value` (each value line), `currency-swap-flip`, `currency-swap-rate` and `currency-swap-submit`. The action is an Async Button with its own `data-state`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Result | `spring.smooth` | 0.36s, bounce 0 | the received amount rolls digit by digit to its new figure (motion’s Counter) |
| Flip | `spring.snappy` | 0.2s, bounce 0 | each side’s amount and currency glide into the other’s place, from a touch smaller |
| Flip button | `spring.snappy` | 0.2s, bounce 0 | the arrows turn half a circle per flip |
| Action |  |  | the button runs the Async Button’s pending, success and error states |

**Reduced motion:** The figure changes and the sides swap at once; the arrows don't turn.

#### Reduced motion

Every change lands at once. The card keeps its size throughout: the pickers have a fixed width, and long figures truncate.

### Accessibility

- The amount is a text field labeled “You pay”; it parses and formats in the locale, and ArrowUp/Down step it.
- Each currency picker is a select named “Currency to pay with” or “Currency to receive”, with typeahead and the arrow keys.
- The flip is a button named “Swap currencies”. Focus stays on it after a flip.
- The result is an `output` labeled “You receive”. Once it rests it is announced politely (“You receive 2,549.9 HYPE”), not on every keystroke.
- The action is an Async Button: pending and success are announced politely, an error assertively.
- With sound on, a flip plays `tap` and a new currency `select`; the action sounds as an Async Button does. `sound={false}` keeps it silent.

Bitcoin, Ethereum, Solana and USDC logos are trademarks of their owners, shown for illustration only.

---

# Date Picker

> Type a date in your locale’s format or choose it from a calendar.

Source: https://www.youj.dev/docs/components/date-picker

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { addDays, format } from 'date-fns'
import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { DatePicker } from '@youj/react/date'

export default function DatePickerDemo() {
  const [date, setDate] = useState<Date | null>(() => addDays(new Date(), 12))

return (
    <Field className="w-full max-w-72">
      <FieldLabel>Due date</FieldLabel>
      <DatePicker value={date} onValueChange={setDate} />
      <FieldDescription>{date ? `Due ${format(date, 'EEEE, MMMM d')}.` : 'No due date.'} Type a date or pick one.</FieldDescription>
    </Field>
  )
}
```

A due date that starts twelve days out, with a description that reads the chosen date back.

Typing a complete date selects it as you go, and on blur or Enter the text settles into the canonical form. It also reads any separator ("9-27-2026"), two-digit years once you leave the field, month names ("Sep 27, 2026"), ISO dates (2026-09-27), and today, tomorrow and yesterday. Text that isn't a date, or falls outside the bounds, marks the field invalid and clears the value.

The calendar button, whose icon tears off a day on hover, opens a [Popover](https://www.youj.dev/docs/components/popover) with the Calendar focused on the chosen day. ArrowDown in the field opens it too. Picking a day closes it and returns focus to the field.

### Bounds

```tsx
'use client'

import { addDays, isWeekend } from 'date-fns'
import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { DatePicker } from '@youj/react/date'

export default function DatePickerBounds() {
  const today = new Date()

return (
    <Field className="w-full max-w-72">
      <FieldLabel>Launch</FieldLabel>
      <DatePicker minDate={today} maxDate={addDays(today, 60)} disabledDates={isWeekend} />
      <FieldDescription>A weekday in the next 60 days. Try typing a Saturday.</FieldDescription>
    </Field>
  )
}
```

A launch date limited to weekdays in the next 60 days.

`minDate` and `maxDate` bound both the calendar and the typing, and `disabledDates` takes react-day-picker matchers, such as date-fns's `isWeekend` or `{ dayOfWeek: [0, 6] }`. A typed date that breaks them is marked invalid instead of being accepted.

### States

```tsx
'use client'

import { Field, FieldError, FieldLabel } from '@youj/react'
import { DatePicker } from '@youj/react/date'

export default function DatePickerStates() {
  return (
    <div className="flex w-full max-w-72 flex-col gap-6">
      <Field invalid required>
        <FieldLabel>Start date</FieldLabel>
        <DatePicker />
        <FieldError>Pick a start date.</FieldError>
      </Field>
      <Field disabled>
        <FieldLabel>Created</FieldLabel>
        <DatePicker defaultValue={new Date(2026, 0, 14)} disabled />
      </Field>
    </div>
  )
}
```

An invalid, required field beside a disabled one.

Inside a [Field](https://www.youj.dev/docs/components/field), `required` and `invalid` reach the input, and `disabled` disables both the input and the calendar button.

### Ghost

```tsx
'use client'

import { DatePicker } from '@youj/react/date'

export default function DatePickerGhost() {
  return (
    <dl className="grid w-full max-w-xs grid-cols-[6rem_1fr] items-center gap-x-3 gap-y-1 text-ui">
      <dt className="text-fg-muted">Start date</dt>
      <dd>
        <DatePicker variant="ghost" size="sm" aria-label="Start date" defaultValue={new Date(2026, 8, 21)} />
      </dd>
      <dt className="text-fg-muted">Due date</dt>
      <dd>
        <DatePicker variant="ghost" size="sm" aria-label="Due date" placeholder="No due date" />
      </dd>
    </dl>
  )
}
```

Start and due dates in a row of properties, each a quiet button.

`variant="ghost"` trades the typed field for a button that shows the date ("Sep 21, 2026") and opens the same calendar: the same look as `SelectTrigger variant="ghost"`, so a row of pickers (status, assignee, dates) reads as one. `size="sm"` matches a small select. Give it an `aria-label`: its accessible name is the label, then the date ("Due date, Sep 21, 2026"), and `placeholder` is what it shows with no date. There's no typing in this variant; use the default field where people enter dates by hand.

```tsx
<DatePicker variant="ghost" size="sm" aria-label="Due date" placeholder="No due date" value={due} onValueChange={setDue} />
```

## Installation & usage

```bash
pnpm add @youj/react date-fns react-day-picker
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add date-picker
```

It brings `calendar`, `icon-calendar`, `input-group`, `popover`, `presentation`, `select`, `use-controllable-state`, `youj-core`, `youj-labels-date-picker`, `youj-ui-core` with it.

The copy is 31 registry items, about 9,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `calendar`, `collapse`, `field`, `icon-calendar`, `icon-check`, `icon-chevron-down`, `icon-chevron-left`, `icon-chevron-right`, `icon-chevron-up` and 13 more.

Requires `date-fns` and `react-day-picker`, [optional dependencies](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/date`.

Use Date Picker for a due date, launch date or birthday. People can type the date or choose it from the calendar. Use [Date Range Picker](https://www.youj.dev/docs/components/date-range-picker) for a start and end, [Calendar](https://www.youj.dev/docs/components/calendar) for an always-visible month, or add [Time Picker](https://www.youj.dev/docs/components/time-picker) for the time of day.

```tsx
import { useState } from 'react'
import { Field, FieldLabel } from '@youj/react'
import { DatePicker } from '@youj/react/date'

export function DueDate() {
  const [date, setDate] = useState<Date | null>(null)
  return (
    <Field>
      <FieldLabel>Due date</FieldLabel>
      <DatePicker value={date} onValueChange={setDate} />
    </Field>
  )
}
```

The field is an [Input Group](https://www.youj.dev/docs/components/input-group) text input in the locale's short format, such as 09/27/2026 in en-US or 27.09.2026 in German, with the order spelled out in the placeholder. The value is a `Date`, or `null` while the field is empty or doesn't hold a date.

Without a `locale`, the picker follows `YoujProvider`'s: `<YoujProvider locale="de-DE">` gives 27.09.2026, German month and day names, and weeks from Monday. The order and names come from `Intl`, and the first day of the week from `Intl.Locale`'s week info where the browser has it (Monday where it doesn't). The same goes for Calendar and Date Range Picker; `dateLocale(tag)` returns the locale they build.

`locale` takes a date-fns locale, which is also react-day-picker's, and wins over the provider's. It sets the field's order and separator, the placeholder, the calendar's month and day names, and the first day of the week, and it lets the field read typed month names in that language ("5. Sept. 2026"), which the Intl-built locale reads only in English.

```tsx
import { de } from 'date-fns/locale'

<DatePicker locale={de} />
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date \| null` |  |  |
| `defaultValue` | `Date \| null` | `null` |  |
| `onValueChange` | `(date: Date \| null) => void` |  |  |
| `locale` | `Locale` |  | A date-fns / react-day-picker locale: order, names, week start, parsing of month names. Default: YoujProvider's `locale`, through Intl (see Calendar's dateLocale). |
| `minDate` | `Date` |  |  |
| `maxDate` | `Date` |  |  |
| `disabledDates` | `Matcher \| Matcher[]` |  | Days that can't be chosen (react-day-picker matchers). |
| `placeholder` | `string` |  | Default: the locale's pattern ("MM/DD/YYYY"). |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits the date (yyyy-MM-dd) with a native form. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) opens the calendar in a popover under a pointer and in a bottom sheet on touch; force either one. |
| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost`: no typed field, a quiet button showing the date that opens the calendar, matching `SelectTrigger variant="ghost"` (for a property row or a table cell). |
| `size` | `'sm' \| 'default'` | `'default'` | The ghost trigger's height, as SelectTrigger's. The field takes its height from the theme. |

The package also exports the helpers the picker uses, for your own parsing and display: `parseDate(text, locale)`, `formatDate(date, locale)`, `datePattern(locale)`, `datePlaceholder(locale)` and `dateAllowed(date, min, max, disabled)`.

### Touch

On a touch device the field is still a text field you can type in, set at 16px so the page doesn't zoom when it's focused. The calendar button has a 44px target and opens the calendar in a bottom sheet with 44px days. Picking a day closes the sheet, and so do pulling it down, tapping outside it and Escape.

`presentation` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the popover on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the calendar grows out of the field (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Month change | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the Calendar's slide from the side it comes from |
| Icon hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the calendar icon tears off a day |

**Reduced motion:** The popover opens and closes at once, the month changes in place and the icon stays still.

#### Reduced motion

The popover and the month change happen at once, and the icon doesn't animate. Typing, parsing and keyboard handling are unchanged.

### Accessibility

- The input is named by its `FieldLabel`, or by `aria-label`, and carries `aria-invalid` when the text isn't an allowed date.
- The calendar button is named "Choose date", and so is the popup. Focus moves into the calendar on the chosen day, and returns to the input when a day is picked or Escape closes it.
- In the calendar, arrows move by day, PageUp and PageDown by month and Home and End by week.
- With `name`, a hidden input submits the date as `yyyy-MM-dd`.

---

# Date Range Picker

> Choose a date range by typing, selecting a preset or using a calendar.

Source: https://www.youj.dev/docs/components/date-range-picker

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { addDays, differenceInCalendarDays, startOfDay } from 'date-fns'
import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { DateRangePicker, type DateRangePickerProps } from '@youj/react/date'

type DateRange = NonNullable<DateRangePickerProps['value']>

export default function DateRangePickerDemo() {
  const today = startOfDay(new Date())
  const [range, setRange] = useState<DateRange | null>({ from: addDays(today, -6), to: today })
  const days = range?.from && range.to ? differenceInCalendarDays(range.to, range.from) + 1 : 0

return (
    <Field className="w-full max-w-80">
      <FieldLabel>Reporting period</FieldLabel>
      <DateRangePicker value={range} onValueChange={setRange} maxDate={today} />
      <FieldDescription>{days ? `Comparing ${days} days of traffic.` : 'Pick a period to compare.'}</FieldDescription>
    </Field>
  )
}
```

A reporting period that starts as the last seven days, with no date after today.

The defaults are Today, Yesterday, Last 7 days, Last 30 days, This month, Last month and Year to date, exported as `dateRangePresets`. The preset matching the current range carries a pill that glides between presets, and choosing one moves the calendar to it with the month slide, so you see the band land. Pass your own list, or `presets={false}` to hide them.

```tsx
import { addDays, startOfWeek } from 'date-fns'
import { dateRangePresets, type DateRangePreset } from '@youj/react/date'

const presets: DateRangePreset[] = [
  { label: 'This sprint', range: (today) => ({ from: startOfWeek(today), to: addDays(startOfWeek(today), 13) }) },
  ...dateRangePresets.slice(2, 4),
]
```

Each preset's `range` receives today at the start of the day, in local time.

### Bounds

```tsx
'use client'

import { Field, FieldDescription, FieldLabel } from '@youj/react'
import { DateRangePicker } from '@youj/react/date'

export default function DateRangePickerPlanning() {
  return (
    <Field className="w-full max-w-80">
      <FieldLabel>Freeze window</FieldLabel>
      <DateRangePicker presets={false} minDate={new Date()} disabledDates={{ dayOfWeek: [0, 6] }} />
      <FieldDescription>No deploys to production between these dates.</FieldDescription>
    </Field>
  )
}
```

A freeze window with the presets off, no past dates and no weekends.

`minDate`, `maxDate` and `disabledDates` bound the calendar, the typing and the presets: a range can't span a disabled day, and a preset that falls outside the bounds is disabled. This one plans ahead, with no weekends and no presets.

## Installation & usage

```bash
pnpm add @youj/react date-fns react-day-picker
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add date-range-picker
```

It brings `button`, `calendar`, `date-picker`, `field`, `icon-calendar`, `input-group`, `popover`, `presentation`, `sliding-indicator`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-labels-date-range-picker`, `youj-labels-file-upload`, `youj-ui-core` with it.

The copy is 36 registry items, about 10,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `calendar`, `collapse`, `date-picker`, `field`, `icon-calendar`, `icon-check`, `icon-chevron-down`, `icon-chevron-left`, `icon-chevron-right` and 16 more.

Requires `date-fns` and `react-day-picker`, [optional dependencies](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/date`.

Use a date range picker for a period: a reporting window, a freeze, a trip, a billing cycle. Presets cover the common spans, and the calendar covers the rest. For a single date, use a [Date Picker](https://www.youj.dev/docs/components/date-picker). When the range is the focus of the page, show a [Calendar](https://www.youj.dev/docs/components/calendar) in `range` mode instead.

```tsx
import { useState } from 'react'
import { Field, FieldLabel } from '@youj/react'
import { DateRangePicker, type DateRange } from '@youj/react/date'

export function ReportingPeriod() {
  const [range, setRange] = useState<DateRange | null>(null)
  return (
    <Field>
      <FieldLabel>Reporting period</FieldLabel>
      <DateRangePicker value={range} onValueChange={setRange} maxDate={new Date()} />
    </Field>
  )
}
```

The field holds two inputs, start and end, under one label. Each reads text the way the [Date Picker](https://www.youj.dev/docs/components/date-picker) does: the locale's order with any separator, month names, ISO dates. An end typed before the start swaps them. The value is react-day-picker's `{ from, to }`, or `null`.

The calendar button opens a [Popover](https://www.youj.dev/docs/components/popover) with presets beside a two-month range Calendar. On a narrow screen it shows one month, with the presets wrapped above it. On touch it's a sheet (see [Touch](#touch)). The footer says how many days are chosen and is announced as it changes. Clicking a day after a full range starts a new one.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `DateRange \| null` |  |  |
| `defaultValue` | `DateRange \| null` | `null` |  |
| `onValueChange` | `(range: DateRange \| null) => void` |  |  |
| `presets` | `false \| DateRangePreset[]` |  | Default: Today, Yesterday, Last 7 / 30 days, This / Last month, Year to date. `false` hides them. |
| `locale` | `Locale` |  | A date-fns / react-day-picker locale. Default: YoujProvider's `locale`, through Intl (see Calendar's dateLocale). |
| `minDate` | `Date` |  |  |
| `maxDate` | `Date` |  |  |
| `disabledDates` | `Matcher \| Matcher[]` |  | Days that can't be chosen (react-day-picker matchers); a range can't span them. |
| `numberOfMonths` | `number` |  | Months side by side. Default 2 (1 on phones). |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits `${name}From` / `${name}To` (yyyy-MM-dd) with a native form. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `startLabel` | `string` |  | Names the start and end fields. Default "Start date" / "End date". |
| `endLabel` | `string` |  |  |
| `presentation` | `'auto' \| 'sheet' \| 'popover'` | `'auto'` | `auto` (the default) opens the calendar in a popover under a pointer and in a bottom sheet on touch; force either one. |

`DateRangePreset` is `{ label: string; range: (today: Date) => { from: Date; to: Date } }`.

### Touch

On a touch device the two fields are still text fields, set at 16px. The calendar button opens a bottom sheet with the presets in one row of 44px chips that scrolls sideways, one month with 44px days, the day count, and a Done button. A range takes two taps, so the sheet stays open until you press Done, pull it down, tap outside it or press Escape.

`presentation` chooses: `auto` (the default) is a popover under a mouse or trackpad and a sheet on touch, `sheet` always uses the sheet, and `popover` keeps the popover on touch too.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the popover grows out of the field (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Preset pill | `spring.smooth` | 0.36s, bounce 0 | glides to the preset matching the range |
| Month change | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | from the arrows or a preset: slides in from the side it comes from |

**Reduced motion:** The pill jumps to its preset, the months swap in place and the popover opens and closes at once.

#### Reduced motion

The preset pill moves without gliding, the calendar changes month in place, and the popover appears at once. Presets, typing and announcements are unchanged.

### Accessibility

- The Field's label names the group, and the two inputs are named by it together with `startLabel` and `endLabel` ("Start date", "End date"). Each carries `aria-invalid` when its text isn't an allowed date.
- The calendar button and the popup are named "Choose dates". Presets are toggle buttons with `aria-pressed`, in a group named "Presets". Focus starts on the presets, or on the calendar when there are none.
- The footer ("7 days: Sep 21, 2026 – Sep 27, 2026") is announced politely as the range changes.
- With `name`, hidden inputs submit `${name}From` and `${name}To` as `yyyy-MM-dd`.

---

# Signature Pad

> Draw or type a signature on one surface, accept it to lock it, and export it as SVG or PNG.

Source: https://www.youj.dev/docs/components/signature-pad

## Examples

### Demo

```tsx
'use client'

import { Field, FieldDescription, SignaturePad, type SignatureValue } from '@youj/react'

/** Stands in for your upload: the Accept button waits for it. */
async function fileSignature(_signature: SignatureValue) {
  await new Promise((resolve) => setTimeout(resolve, 900))
}

export default function SignaturePadDemo() {
  return (
    <Field className="w-full max-w-lg">
      <SignaturePad className="border-0 shadow-none [--signature-inset:0px]" onAccept={fileSignature} />
      <FieldDescription>Dana Whitfield, Head of Operations. Accepting files the signature with the agreement.</FieldDescription>
    </Field>
  )
}
```

An agreement's signature field: sign, then Accept files it, and the signature locks, its line turning green with a small tick.

The pad is one surface: Draw | Sign by typing tabs across the top, the signing area, and a footer with Undo and Clear and the Accept button. Each stroke is one filled path that swells and thins: a pen's own pressure, or for a mouse or a finger a pressure taken from speed (fast is thin). Accept is the kit's AsyncButton: it awaits `onAccept(value)` (spinner), draws its check, and the signature locks: read-only, its line in the success ink with a small tick at the end, its ink settled onto the line. A rejection shows its message on the button and leaves the pad open; Re-sign unlocks a locked signature.

### Sign by typing

```tsx
'use client'

import { Field, FieldLabel, SignaturePad } from '@youj/react'

export default function SignaturePadTypeInstead() {
  return (
    <Field className="w-full max-w-lg">
      <FieldLabel>Signature</FieldLabel>
      <SignaturePad className="border-0 shadow-none [--signature-inset:0px]" defaultValue={{ kind: 'typed', text: 'Dana Whitfield' }} />
    </Field>
  )
}
```

A signature typed rather than drawn, set in a script face.

Sign by typing is the way to sign without a pointer: its tab, or Enter on the focused drawing area. Each mode keeps its own draft, so switching back brings the drawing back. The face is a stack of the script fonts systems ship, ending in `cursive`; pass `typeFont` to use one your app loads.

### In a form

```tsx
'use client'

import { useState, type FormEvent } from 'react'
import { Button, Field, FieldDescription, FieldError, FieldLabel, Input, SignaturePad } from '@youj/react'

export default function SignaturePadForm() {
  const [sent, setSent] = useState('')

const submit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const data = new FormData(e.currentTarget)
    setSent(`${data.get('name')}: ${String(data.get('signature')).slice(0, 28)}…`)
  }

return (
    <form onSubmit={submit} className="flex w-full max-w-lg flex-col gap-4">
      <Field>
        <FieldLabel>Full name</FieldLabel>
        <Input name="name" defaultValue="Dana Whitfield" />
      </Field>
      <Field required>
        <FieldLabel>Signature</FieldLabel>
        <SignaturePad className="border-0 shadow-none [--signature-inset:0px]" name="signature" />
        <FieldDescription>Accept your signature; it is sent with the form as a PNG.</FieldDescription>
        <FieldError match="valueMissing">Sign and accept before you submit.</FieldError>
      </Field>
      <div className="flex items-center gap-3">
        <Button type="submit">Submit</Button>
        {sent && (
          <span role="status" className="truncate font-mono text-ui-xs text-fg-muted">
            {sent}
          </span>
        )}
      </div>
    </form>
  )
}
```

A native form with a required signature: submitting before the signature is accepted stops the form and shows the Field's error.

`name` submits the accepted signature as a PNG data URL with the form, and `required` (or a required Field) blocks submit until a signature is accepted: a draft doesn't count. In a Field the pad takes its label, description and invalid state.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add signature-pad
```

It brings `async-button`, `button`, `field`, `icon-check`, `icon-eraser`, `icon-undo`, `tabs`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-stroke`, `youj-core`, `youj-labels-signature-pad`, `youj-presets`, `youj-ui-core` with it.

The copy is 31 registry items, about 10,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `collapse`, `field`, `icon-check`, `icon-chevron-left`, `icon-chevron-right`, `icon-engine`, `icon-eraser` and 12 more.

Use a Signature Pad where a person consents or confirms by signing: agreements, deliveries, check-ins. Take the signature in `onAccept`: the button waits for it, and the pad locks once it resolves.

```tsx
import { useRef, useState } from 'react'
import { Field, FieldLabel, SignaturePad, type SignaturePadHandle, type SignatureValue } from '@youj/react'

export function Agreement() {
  const pad = useRef<SignaturePadHandle>(null)
  const [signature, setSignature] = useState<SignatureValue | null>(null)
  return (
    <Field>
      <FieldLabel>Signature</FieldLabel>
      <SignaturePad
        ref={pad}
        value={signature}
        onValueChange={setSignature}
        onAccept={() => upload(pad.current!.toSVG())}
      />
    </Field>
  )
}
```

The value is `{ kind: 'drawn', strokes }` or `{ kind: 'typed', text }`, and `null` while the pad is empty. A stroke is a list of `[x, y, pressure]` points, x and y as fractions of the pad's width, so the pad can resize (it keeps `aspectRatio`, 3 by default) and the signature scales with it. The ref's `toSVG()` returns a standalone SVG document and `toDataURL(scale)` a PNG on a transparent ground, both in the ink color of the moment; `clear()` and `undo()` work the pad. `locked`, `defaultLocked` and `onLockedChange` hold the lock from outside, say to show a signature on file already accepted.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `SignatureValue \| null` |  |  |
| `defaultValue` | `SignatureValue \| null` | `null` |  |
| `onValueChange` | `(value: SignatureValue \| null) => void` |  |  |
| `onAccept` | `(value: SignatureValue) => Promise<unknown> \| unknown` |  | Runs when the signer presses Accept, with the signature. The button waits for it (spinner), then shows its check and the pad locks; a rejection shows its message on the button and keeps the pad open. Without it, Accept locks at once. |
| `locked` | `boolean` |  | The signature is accepted and read-only (controlled). |
| `defaultLocked` | `boolean` | `false` | Starts accepted and read-only (uncontrolled). |
| `onLockedChange` | `(locked: boolean) => void` |  | Called with true once a signature is accepted, and false when Re-sign unlocks it. |
| `typeInstead` | `boolean` | `true` | Offers Sign by typing beside Draw, so a signature needs no pointer. |
| `aspectRatio` | `number` | `3` | The signing area's width over its height. |
| `strokeWidth` | `number` | `3` | The pen at full pressure, in pixels on a 500px-wide pad; it scales with the pad. |
| `typeFont` | `string` | `SCRIPT_FONT` | The face a typed signature is set in. |
| `name` | `string` |  | Submits the accepted signature as a PNG data URL with a native form. |
| `required` | `boolean` |  | Blocks a native submit until a signature is accepted. |
| `disabled` | `boolean` |  |  |
| `readOnly` | `boolean` | `false` | Shows the signature without tabs, Undo, Clear or Accept. |
| `label` | `string` |  | The pad's accessible name when no Field label names it. Default: the labels' "Signature". |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the tabs and the Accept outcome sound. `false` keeps this pad silent. |
| `ref` | `Ref<SignaturePadHandle>` |  | The handle: `clear`, `undo`, `toSVG`, `toDataURL`. |

Also takes the props of `ComponentProps<'div'>`.

#### Data attributes

The root carries `data-yj-mode` (`draw` or `type`), and `data-yj-empty`, `data-yj-locked`, `data-disabled` and `data-readonly` when they hold.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Tabs | `spring.smooth` | 0.36s, bounce 0 | the indicator glides between Draw and Sign by typing; the new area fades in (the Tabs motion) |
| Sign here | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the placeholder fades out as the first ink arrives, and back when the pad is cleared |
| Ink |  |  | follows the pointer sample by sample, never eased in time |
| Accept | `spring.snappy` | 0.2s, bounce 0 | the AsyncButton lifecycle: spinner, then a drawn check (or a shake and the error), then Re-sign |
| Accepted | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the signing line eases to the success ink and a small tick draws at its end |
| Settle | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the locked ink eases a touch smaller onto its line |

**Reduced motion:** The tick, the line color, the settle, the tab indicator and the placeholder swap at once. Ink is drawn the same.

#### Reduced motion

Each state shows at once, so the pad reads the same. With sound on, choosing a tab and the Accept outcome sound as the rest of the kit does (`sound={false}` silences the pad).

### Accessibility

- Draw and Sign by typing are tabs: arrow keys move between them, Enter or Space chooses one. Choosing Sign by typing puts the caret in its field.
- The drawing area is a focusable group named by its Field label (or `label`) and described by a hint: draw with a pointer, or press Enter to type the name instead. ⌘Z or Ctrl+Z on it undoes a stroke.
- Sign by typing is a text field, so a signature never needs a pointer: type, then Tab to Accept.
- Undo and Clear are named buttons with tooltips; a clear is announced in a polite live region.
- Accept announces its progress and outcome (an error assertively); once it settles, the lock is announced politely, and the locked pad reads "Signed" with the time. Re-sign's unlock is announced too.
- With `required`, a pad without an accepted signature stops a native submit and moves focus to the pad (or to Accept when there is a draft); the Field's error explains why.

---

# File Upload

> Upload files with clear rules, validation, progress and retry controls.

Source: https://www.youj.dev/docs/components/file-upload

## Examples

### Demo

```tsx
'use client'

import { Card, CardContent, CardDescription, CardHeader, CardTitle, FileUpload, type UploadContext } from '@youj/react'

const MB = 1024 * 1024

// A stand-in for your upload endpoint: irregular progress, every third file
// fails so Retry shows, and removing a file really aborts it.
let attempts = 0
function upload(file: File, { signal, onProgress }: UploadContext) {
  const fails = ++attempts % 3 === 0
  return new Promise<void>((resolve, reject) => {
    let progress = 0
    const timer = setInterval(() => {
      progress = Math.min(100, progress + 6 + Math.random() * 18)
      if (fails && progress > 55) {
        clearInterval(timer)
        reject(new Error('Connection lost'))
        return
      }
      onProgress(progress)
      if (progress >= 100) {
        clearInterval(timer)
        resolve()
      }
    }, 280 + (file.size % 5) * 40)
    signal.addEventListener('abort', () => {
      clearInterval(timer)
      reject(signal.reason)
    })
  })
}

export default function FileUploadDemo() {
  return (
    <Card className="w-full max-w-[440px]">
      <CardHeader>
        <CardTitle>Attachments</CardTitle>
        <CardDescription>Receipts or screenshots.</CardDescription>
      </CardHeader>
      <CardContent>
        <FileUpload accept=".png,.jpg,.jpeg,.pdf" maxSize={5 * MB} maxFiles={6} onUpload={upload} />
      </CardContent>
    </Card>
  )
}
```

A card of attachments that takes PNG, JPEG and PDF files up to 5 MB, six at most, uploaded by a simulated endpoint that fails every third file.

`onUpload(file, { signal, onProgress })` uploads one file. Report progress from 0 to 100 through `onProgress`, resolve when the upload is done, and reject or throw to show the error on the row with a Retry button. Removing a file while it uploads aborts `signal`, so pass it on to `fetch` or your storage client. Try the preview: every third file fails.

Files are checked against `accept` (extensions, MIME types or wildcards like `image/*`), `maxSize` in bytes, `maxFiles` and duplicates. Every rejected file is listed with its reason in one alert that grows in under the zone, so dropping ten files at once gives one explanation and not ten. `multiple={false}` keeps the picker to one file.

### Gallery

```tsx
'use client'

import { FileUpload, type UploadContext } from '@youj/react'

const MB = 1024 * 1024

// A stand-in for your upload endpoint, reporting progress until it's done.
function upload(_file: File, { signal, onProgress }: UploadContext) {
  return new Promise<void>((resolve, reject) => {
    let progress = 0
    const timer = setInterval(() => {
      progress = Math.min(100, progress + 8 + Math.random() * 16)
      onProgress(progress)
      if (progress >= 100) {
        clearInterval(timer)
        resolve()
      }
    }, 260)
    signal.addEventListener('abort', () => {
      clearInterval(timer)
      reject(signal.reason)
    })
  })
}

export default function FileUploadGallery() {
  return (
    <div className="w-full max-w-[460px]">
      <FileUpload variant="gallery" accept="image/*" maxSize={8 * MB} maxFiles={8} onUpload={upload} title="Drop photos or browse" />
    </div>
  )
}
```

The gallery variant for images up to 8 MB, eight at most, with simulated upload progress.

`variant="gallery"` is for images: accepted files become square tiles in a grid with their thumbnails, and once there are files, the zone becomes the last tile.

### Collect for a form

```tsx
'use client'

import { useState } from 'react'
import { Button, FileUpload, formatBytes, type UploadFile } from '@youj/react'

export default function FileUploadCollect() {
  const [files, setFiles] = useState<UploadFile[]>([])
  const [imported, setImported] = useState('')

return (
    <form
      className="flex w-full max-w-[440px] flex-col gap-3"
      onSubmit={(event) => {
        event.preventDefault()
        const file = files[0]?.file
        if (file) setImported(`Importing ${file.name} (${formatBytes(file.size)})…`)
      }}
    >
      {/* Without onUpload, files are only collected, for the form to send later. */}
      <FileUpload
        accept=".csv,.xlsx"
        multiple={false}
        maxFiles={1}
        title="Drop a spreadsheet or browse"
        onFilesChange={(next) => {
          setFiles(next)
          setImported('')
        }}
      />
      <div className="flex items-center justify-between gap-3">
        <p role="status" className="text-ui-sm text-fg-muted">
          {imported}
        </p>
        <Button type="submit" disabled={files.length === 0}>
          Import contacts
        </Button>
      </div>
    </form>
  )
}
```

A single-spreadsheet picker with no upload handler, so the file is only collected and a form button imports it.

Without `onUpload`, files are only collected. Read them from `onFilesChange` and send them with the form, as this import does. `useFileUpload` exposes the same state and rules for a layout of your own, and `useFileDrop` the drop target alone.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add file-upload
```

It brings `button`, `field`, `icon-check`, `icon-file`, `icon-file-text`, `icon-image`, `icon-refresh`, `icon-upload`, `icon-x`, `presence-list`, `progress`, `youj-core`, `youj-labels-file-upload`, `youj-presets`, `youj-ui-core` with it.

The copy is 25 registry items, about 8,800 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `field`, `icon-check`, `icon-engine`, `icon-file`, `icon-file-text`, `icon-image`, `icon-loader-ring`, `icon-refresh` and 8 more.

Use it wherever people attach files: receipts on an expense, screenshots on a bug report, a spreadsheet to import, photos for a listing. The zone states the rules before anyone picks a file, a rejection says which file broke which rule, and each accepted file shows its own progress, a check when it's done, or the error with a Retry. For a single profile photo with cropping, use [Avatar Upload](https://www.youj.dev/docs/components/avatar-upload).

```tsx
import { FileUpload } from '@youj/react'

export function Attachments() {
  return (
    <FileUpload
      accept=".png,.jpg,.jpeg,.pdf"
      maxSize={5 * 1024 * 1024}
      maxFiles={6}
      onUpload={(file, { signal, onProgress }) => uploadToStorage(file, { signal, onProgress })}
    />
  )
}
```

The zone is a button and a drop target: click it, press Enter or Space, or drag files onto it. Its second line is generated from the rules, such as "PNG, JPG or PDF · up to 5 MB each", and `hint` replaces it. `title` sets the main line.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'list' \| 'gallery'` | `'list'` | 'list' (default): rows with progress. 'gallery': a grid of image tiles. |
| `multiple` | `boolean` | `true` | Allow several files. |
| `disabled` | `boolean` | `false` |  |
| `title` | `ReactNode` |  | The zone's main line. |
| `hint` | `ReactNode` |  | Overrides the generated rules line ("PNG or JPG · up to 5 MB each"). |
| `accept` | `string` |  | As the input's `accept`: extensions (`.pdf`), MIME types (`image/png`) or wildcards (`image/*`). |
| `maxSize` | `number` |  | In bytes. |
| `maxFiles` | `number` |  | Total files allowed. |
| `onUpload` | `(file: File, context: UploadContext) => Promise<unknown>` |  | Uploads one file. Resolve when done; reject (or throw) to show the error. Without it, files are only collected. |
| `onFilesChange` | `(files: UploadFile[]) => void` |  |  |

Also takes the props of `ComponentProps<'div'>`.

The `onUpload`, `onFilesChange`, `accept`, `maxSize` and `maxFiles` options are the same for `useFileUpload`. Each file in `onFilesChange` is an `UploadFile`: the `File`, its `status` (`uploading`, `done` or `error`), `progress`, `error` and an image `preview` URL.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drag over | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the zone’s border turns accent and the upload icon lifts |
| File joins | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the row fades in with a 6px drop while the rows below glide (Presence List) |
| Rows make room | `spring.smooth` | 0.36s, bounce 0 |  |
| Progress | `spring.smooth` | 0.36s, bounce 0 | the bar glides to each report, retargeting mid-glide |
| Done | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the row settles into a drawn check |
| Rejections | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the alert grows in under the zone, as a Field error does |
| File removed | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades in place, then the rest close up |

**Reduced motion:** Rows and tiles appear and go at once, progress jumps to each value and the check is already drawn.

#### Reduced motion

Rows and tiles appear and disappear without fading or gliding, progress bars jump to each value and the done check shows already drawn. Drag-over still changes the border.

### Accessibility

- The drop zone is a real button, so Enter and Space open the file picker, and its description reads the rules.
- Every change is announced politely: files added, rejections, each upload finishing or failing, and removals.
- Rejections are listed through a Field error under the zone, one line per file with its reason.
- Each row's buttons are named with the file name: "Cancel upload of receipt.pdf" while it uploads, then "Remove receipt.pdf", and "Retry receipt.pdf" after a failure.
- Focus never drops to the page: removing a row moves focus to the next row's button, or back to the zone when the list empties.

---

# Avatar Upload

> Let people upload and crop a profile photo before saving it.

Source: https://www.youj.dev/docs/components/avatar-upload

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { AvatarUpload } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function AvatarUploadDemo() {
  const [src, setSrc] = useState<string | null>(null)

return (
    <AvatarUpload
      src={src}
      name="Ada Lovelace"
      fallback="AL"
      size={72}
      onSave={async (file) => {
        // Upload the cropped square here; this demo keeps it in the page.
        await wait(900)
        setSrc(URL.createObjectURL(file))
      }}
      onRemove={() => setSrc(null)}
    />
  )
}
```

A 72px avatar whose save handler waits a moment, then shows the cropped photo; its remove handler clears it.

Drag the photo to move it, and zoom from 1 to 4 times with a pinch, the scroll wheel or the Zoom slider. Zoom is anchored on the circle's center. The photo follows the pointer exactly, and pulled past an edge it gives with resistance and springs back on release, so the circle is always filled. A rule-of-thirds grid shows while it moves.

From the keyboard, the arrow keys move the photo, Shift moves it further, `+` and `−` zoom, and `0` resets.

### Sizes and rules

```tsx
'use client'

import { AvatarUpload } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

// The avatar's right margin tops every row up to the 96px column, so the buttons share one left edge.
const SIZES = [
  { size: 48, gutter: '[&>div>:first-child]:me-12' },
  { size: 96, gutter: '' },
]

export default function AvatarUploadSizes() {
  return (
    <div className="flex flex-col gap-6">
      {SIZES.map(({ size, gutter }) => (
        <AvatarUpload key={size} size={size} fallback="KL" className={gutter} onSave={() => wait(600)} />
      ))}
      <AvatarUpload disabled fallback="AL" className="[&>div>:first-child]:me-8" onSave={() => {}} />
    </div>
  )
}
```

The same upload at 48 and 96 pixels, and a disabled one.

`size` sets the avatar's edge in pixels, 64 by default. `accept` defaults to PNG, JPEG and WebP, and `maxSize` to 10 MB. A file that breaks a rule is explained in a Field error under the avatar and never opens the cropper.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add avatar-upload
```

It brings `async-button`, `avatar`, `button`, `dialog`, `field`, `file-upload`, `icon-camera`, `icon-zoom-in`, `icon-zoom-out`, `slider`, `youj-core`, `youj-labels-avatar-upload`, `youj-presets`, `youj-ui-core` with it.

The copy is 40 registry items, about 11,700 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `avatar`, `button`, `collapse`, `dialog`, `field`, `file-upload`, `icon-camera`, `icon-check` and 19 more.

Use it on a profile or account page, wherever one person or workspace has one photo. The avatar itself is the button and a drop target, and a picked image opens a crop dialog, so what's saved is a square that fills the circle instead of a stretched or off-center photo. For attaching files of any kind, or several at once, use [File Upload](https://www.youj.dev/docs/components/file-upload). To only show a photo, use [Avatar](https://www.youj.dev/docs/components/avatar).

```tsx
import { AvatarUpload } from '@youj/react'

export function ProfilePhoto({ user }: { user: User }) {
  return (
    <AvatarUpload
      src={user.avatarUrl}
      name={user.name}
      fallback={user.initials}
      onSave={async (file) => {
        const url = await uploadAvatar(file)
        await updateUser({ avatarUrl: url })
      }}
      onRemove={() => updateUser({ avatarUrl: null })}
    />
  )
}
```

`onSave` receives the crop as a square `File`, `outputSize` pixels on a side (512 by default) in `outputType` (JPEG by default). It runs through AsyncButton's `onAction`: Save shows a spinner, then a drawn check, and the dialog closes itself. Reject to show the error. The saved crop shows at once, until you pass a new `src`. `onRemove` adds a Remove button while there's a photo.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string \| null` |  | The current photo. |
| `fallback` | `ReactNode` |  | Shown when there is no photo (initials). |
| `name` | `string` |  | Names the photo for assistive tech, e.g. the person's name. |
| `onSave` (required) | `(file: File) => unknown` |  | Receives the cropped square image. Resolve when saved; reject to show the error. |
| `onRemove` | `() => unknown` |  | Shows a Remove button while there is a photo. |
| `accept` | `string` | `'image/png,image/jpeg,image/webp'` |  |
| `maxSize` | `number` | `10 * 1024 * 1024` | In bytes. |
| `outputSize` | `number` | `512` | Output edge in px. |
| `outputType` | `'image/jpeg' \| 'image/png' \| 'image/webp'` | `'image/jpeg'` |  |
| `size` | `number` | `64` | Avatar edge in px. |
| `disabled` | `boolean` | `false` |  |
| `className` | `string` |  |  |

`cropRegion` is exported for doing the same crop on a server.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Hover, focus or drag over | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | a scrim and the camera icon rise over the photo |
| Crop dialog | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | opens and closes as every Dialog (`yj-dialog`) |
| Drag |  | no easing | the photo tracks the pointer 1:1, with resistance past an edge |
| Release past an edge | `spring.smooth` | 0.36s, bounce 0 | springs back so the circle stays filled |
| Thirds grid | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades in while the photo moves |
| Save | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | AsyncButton: spinner, then a drawn check |

**Reduced motion:** The photo clamps at the circle's edge instead of springing back, the scrim appears at once and the dialog opens without motion.

#### Reduced motion

The scrim and camera appear at once, the dialog opens without its rise and scale, and the photo stops at the circle's edge instead of springing back. Saving still shows its states.

### Accessibility

- The avatar is a button named "Upload photo", or "Change photo" once there is one, and described by the rules line beside it. An Upload or Change button beside it does the same, for people who don't expect the photo to be clickable.
- The crop area is a focusable group named "Photo position and zoom" with its keyboard instructions as its description.
- The Zoom slider and the zoom buttons are named, and the buttons disable at 1× and 4×.
- The dialog is titled "Crop your photo" and describes how to move and zoom. Removing the photo moves focus back to the avatar.
- A rejected file is explained in a Field error, which is announced.

---

# Multi-Language Input

> Edit translations in one field, with a language picker and a status for each translation.

Source: https://www.youj.dev/docs/components/multi-language-input

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldGroup, FieldLabel, MultiLanguageInput } from '@youj/react'

const LOCALES = ['en', 'fr', 'de', 'ja', 'ar']

export default function MultiLanguageInputDemo() {
  const [name, setName] = useState<Record<string, string>>({
    en: 'Linen overshirt',
    fr: 'Surchemise en lin',
    ja: 'リネンオーバーシャツ',
  })
  const [description, setDescription] = useState<Record<string, string>>({
    en: 'Garment-dyed European linen with horn buttons. Relaxed through the body, cut to wear open over a tee.',
  })

return (
    <FieldGroup className="w-full max-w-[30rem]">
      <Field required>
        <FieldLabel>Product name</FieldLabel>
        <MultiLanguageInput locales={LOCALES} value={name} onValueChange={setName} name="name" />
      </Field>
      <Field>
        <FieldLabel>Description</FieldLabel>
        <MultiLanguageInput locales={LOCALES} value={description} onValueChange={setDescription} multiline />
        <FieldDescription>Shown on the product page. Missing languages fall back to English.</FieldDescription>
      </Field>
    </FieldGroup>
  )
}
```

A product name and a description in five locales, only some of them translated yet.

Each locale has one of five states, shown by shape as well as color:

| Status | Glyph | Means |
| --- | --- | --- |
| Source | diamond | The locale the others are translated from |
| Complete | filled disc with a check | Translated, current, reviewed |
| Missing | hollow ring | No text yet |
| Outdated | half-filled ring | The source changed after it was translated |
| Needs review | dashed ring | Filled by a copy or a machine suggestion (`suggestions`), not checked yet |

Outdated comes from `review`: for each locale, the source text it was translated against (`basis`), plus `unreviewed` for filled text that hasn't been checked yet. Typing sets the basis to the current source. "Mark reviewed" does the same for an outdated or unreviewed locale.

Without a `review` prop, the component keeps this state itself, using the first source text it saw as the basis. Store `review` beside the value (`onReviewChange`) to keep "outdated" across sessions.

`limit` is a soft limit, for every locale or per locale (`{ en: 60, ja: 30 }`). It counts characters the way a reader does: an emoji or an accented letter counts once. It shows a count and turns into an error past the limit. `maxLength` is still the hard cap the browser enforces.

`validate(text, locale)` returns a message for text that isn't valid, and `errors` takes messages per locale from your server. The note under the text and `aria-invalid` both follow the locale being edited.

### Two locales

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, MultiLanguageInput } from '@youj/react'

export default function MultiLanguageInputTwoLocales() {
  return (
    <Field required className="w-full max-w-sm">
      <FieldLabel>Welcome message</FieldLabel>
      <MultiLanguageInput locales={['en', 'fr']} defaultValue={{ en: 'Welcome back' }} />
      <FieldDescription>Open French to copy the English in, then translate it.</FieldDescription>
    </Field>
  )
}
```

A welcome message in English and French, where opening French offers to copy the English in.

With five locales or fewer, every locale is a key, so it reads like tabs. Open an empty locale and it shows the source text as its placeholder, with a "Copy from English" button. A copy puts the caret at the end and flashes the field once. Copied text counts as "to review" until you edit it or mark it reviewed.

### Many locales

```tsx
'use client'

import { Field, FieldDescription, FieldLabel, MultiLanguageInput } from '@youj/react'

// Forty locales a global storefront ships in; English is the source.
const LOCALES = [
  'en', 'en-GB', 'fr', 'fr-CA', 'de', 'es', 'es-419', 'it', 'pt-BR', 'pt-PT',
  'nl', 'sv', 'da', 'nb', 'fi', 'pl', 'cs', 'sk', 'hu', 'ro',
  'bg', 'el', 'tr', 'uk', 'ru', 'ar', 'he', 'fa', 'hi', 'bn',
  'th', 'vi', 'id', 'ms', 'fil', 'ja', 'ko', 'zh-Hans', 'zh-Hant', 'sw',
]

const translated = Object.fromEntries(LOCALES.slice(1, 31).filter((_, i) => i % 6 !== 2).map((code) => [code, `Summer sale (${code})`]))

export default function MultiLanguageInputManyLocales() {
  return (
    <Field required className="w-full max-w-[32rem]">
      <FieldLabel>Campaign headline</FieldLabel>
      <MultiLanguageInput locales={LOCALES} pinned={['en', 'de', 'fr', 'ja']} defaultValue={{ ...translated, en: 'Summer sale: 30% off linen' }} />
      <FieldDescription>Search by name, native name or code: “Deutsch”, “pt-br”, “Brazil”. ⌥⌘↓ jumps to the next language left to translate.</FieldDescription>
    </Field>
  )
}
```

Forty locales with English, German, French and Japanese pinned, and the rest a search away.

With more locales, the source and the `pinned` locales stay as keys. The default pins the source and the required locales. Every other locale is in the picker, whose trigger is the last key, and while a locale from the picker is being edited, the trigger shows it.

The picker lists locales in three groups: pinned, recent, and the rest by region (or by script, with `groupBy="script"` on a wrapping `MultiLanguageProvider`; the field itself doesn't take `groupBy`). Each locale shows its status. "Needs work" keeps only the locales with something missing, outdated or unreviewed.

The keys never overflow: when the field is narrow, pinned keys fold into the picker, and the source and the locale being edited always stay. The arrows and ⌥⌘↓ / ⌥⌘↑ (Ctrl+Alt on Windows and Linux) move to the next or previous locale that needs work. Focus stays in the text, and the new locale is announced.

### One switcher for a whole form

```tsx
'use client'

import { useState } from 'react'
import {
  Field,
  FieldGroup,
  FieldLabel,
  MultiLanguageActions,
  MultiLanguageInput,
  MultiLanguageProvider,
  MultiLanguageSwitcher,
  SegmentedControl,
  SegmentedControlItem,
  useMultiLanguage,
  type MultiLanguageView,
} from '@youj/react'

function ViewToggle() {
  const { view, setView } = useMultiLanguage()
  return (
    <SegmentedControl size="sm" aria-label="View" value={view} onValueChange={(next) => setView(next as MultiLanguageView)}>
      <SegmentedControlItem value="single">Single</SegmentedControlItem>
      <SegmentedControlItem value="side-by-side">Side by side</SegmentedControlItem>
    </SegmentedControl>
  )
}

export default function MultiLanguageInputSideBySide() {
  const [title, setTitle] = useState<Record<string, string>>({ en: 'Linen overshirt', de: 'Leinen-Overshirt', fr: 'Surchemise en lin' })
  const [summary, setSummary] = useState<Record<string, string>>({
    en: 'Garment-dyed European linen with horn buttons. Relaxed through the body, cut to wear open over a tee.',
    de: 'Stückgefärbtes Leinen mit Hornknöpfen. Offen über einem T-Shirt zu tragen.',
  })
  return (
    // One provider: every field below follows one switcher and one status model.
    <MultiLanguageProvider locales={['en', 'de', 'fr', 'es', 'ja']} defaultLocale="de" defaultView="side-by-side">
      <div className="flex w-full max-w-[40rem] flex-col gap-5">
        <div className="flex flex-wrap items-center gap-2 rounded-lg border border-line bg-surface p-1.5">
          <MultiLanguageSwitcher className="min-w-0 flex-1" />
          <ViewToggle />
          <MultiLanguageActions />
        </div>
        <FieldGroup>
          <Field required>
            <FieldLabel>Title</FieldLabel>
            <MultiLanguageInput value={title} onValueChange={setTitle} />
          </Field>
          <Field required>
            <FieldLabel>Summary</FieldLabel>
            {/* German was translated before English gained "European" and "Relaxed through the body". */}
            <MultiLanguageInput
              value={summary}
              onValueChange={setSummary}
              defaultReview={{ de: { basis: 'Garment-dyed linen with horn buttons. Cut to wear open over a tee.' } }}
              multiline
            />
          </Field>
        </FieldGroup>
      </div>
    </MultiLanguageProvider>
  )
}
```

A title and a summary sharing one switcher, a view toggle and actions, in side-by-side view with German selected.

A `MultiLanguageProvider` gives every field inside it one active locale, one status model and one switcher. The status of each locale covers every field in the form, and `useMultiLanguage()` exposes it for your own toolbar.

`MultiLanguageActions` offers three bulk actions for the active locale: fill every empty field from the source, mark all reviewed, or clear the locale (after a confirm). Each one is announced, and `onBulkAction` receives an `undo` so you can offer it in a toast.

With `view="side-by-side"`, each field puts the source beside the translation, and for an outdated one it marks what changed in the source since. Screen readers hear the source as the field's description.

### With Form

```tsx
'use client'

import { zodResolver } from '@hookform/resolvers/zod'
import { useForm } from 'react-hook-form'
import { z } from 'zod'
import { describeLocale, missingTranslations, MultiLanguageInput } from '@youj/react'
import { Form, FormField, FormSubmit } from '@youj/react/form'

const REQUIRED = ['en', 'de', 'fr']
const list = new Intl.ListFormat('en', { type: 'conjunction' })

const schema = z.object({
  // The message names the languages still missing: "Add the title in French."
  title: z.record(z.string(), z.string()).superRefine((value, ctx) => {
    const missing = missingTranslations(value, REQUIRED).map((code) => describeLocale(code, 'en').label)
    if (missing.length) ctx.addIssue({ code: 'custom', message: `Add the title in ${list.format(missing)}.` })
  }),
})

export default function MultiLanguageInputForm() {
  const form = useForm({ resolver: zodResolver(schema), defaultValues: { title: { en: 'Linen overshirt', de: 'Leinen-Overshirt' } } })
  return (
    <Form form={form} onSubmit={() => new Promise((resolve) => setTimeout(resolve, 800))} className="flex w-full max-w-sm flex-col gap-4">
      <FormField name="title" label="Title" required description="English, German and French are required to publish.">
        {(field) => (
          <MultiLanguageInput
            locales={['en', 'de', 'fr', 'ja']}
            requiredLocales={REQUIRED}
            value={field.value}
            onValueChange={field.onChange}
            onBlur={field.onBlur}
            ref={field.ref}
          />
        )}
      </FormField>
      <FormSubmit className="self-start">Save</FormSubmit>
    </Form>
  )
}
```

A required title inside a Form, validated by a schema whose message names the languages still missing.

The value is a plain record, so a react-hook-form schema checks it like any other value. `missingTranslations(value, locales)` returns the locales still empty, for a message that names them. The Field's error describes the control, and a required locale that's still empty says so under its text.

### Right to left

```tsx
'use client'

import { Field, FieldGroup, FieldLabel, MultiLanguageInput } from '@youj/react'

const LOCALES = ['ar', 'he', 'en', 'fr']

export default function MultiLanguageInputRtl() {
  return (
    // An Arabic interface: the switcher mirrors, and each field runs in its own language's direction.
    <div dir="rtl" lang="ar" className="w-full max-w-[28rem]">
      <FieldGroup>
        <Field required>
          <FieldLabel>اسم المنتج</FieldLabel>
          <MultiLanguageInput locales={LOCALES} defaultValue={{ ar: 'قميص علوي من الكتان', en: 'Linen overshirt' }} />
        </Field>
        <Field>
          <FieldLabel>الوصف</FieldLabel>
          <MultiLanguageInput
            locales={LOCALES}
            multiline
            defaultValue={{ ar: 'كتان أوروبي بأزرار من القرن، يُرتدى مفتوحًا فوق قميص قطني.', he: 'פשתן אירופאי עם כפתורי קרן, ללבוש פתוח מעל חולצת טי.' }}
          />
        </Field>
      </FieldGroup>
    </div>
  )
}
```

An Arabic interface, where the switcher mirrors and each field runs in its own language's direction.

In a right-to-left interface, the keys, the picker and the arrows mirror. Each field still runs in its own locale's direction: an English translation inside an Arabic page runs left to right.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add multi-language-input
```

It brings `alert-dialog`, `button`, `dropdown-menu`, `field`, `icon-chevron-down`, `icon-copy`, `icon-eraser`, `icon-more-horizontal`, `icon-search`, `icon-sparkles`, `input-group`, `kbd`, `popover`, `segmented-control`, `sliding-indicator`, `toggle`, `tooltip`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-multi-language-input-provider`, `youj-presets`, `youj-ui-core` with it.

The copy is 47 registry items, about 14,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `alert-dialog`, `async-button`, `async-feedback`, `button`, `collapse`, `dialog`, `dropdown-menu`, `field`, `icon-check`, `icon-chevron-down` and 25 more.

Use it for content you publish in more than one language: a product name, a page title, a description, an email subject. One field holds every language, so a form is as long as it would be in one. The field also shows which translations are missing, out of date or waiting for review.

It scales from two locales to forty. Pinned locales are one-press keys; every other locale is a search away, by its name, its own name, its code or its region. Wrap several fields in a `MultiLanguageProvider` and they share one switcher, one status model and a side-by-side view for translators.

```tsx
import { useState } from 'react'
import { Field, FieldLabel, MultiLanguageInput } from '@youj/react'

export function ProductName() {
  const [name, setName] = useState<Record<string, string>>({ en: 'Linen overshirt' })
  return (
    <Field required>
      <FieldLabel>Product name</FieldLabel>
      <MultiLanguageInput locales={['en', 'fr', 'de']} value={name} onValueChange={setName} name="name" />
    </Field>
  )
}
```

- **The value** is a record of locale to text: `{ en: 'Linen overshirt', fr: 'Surchemise en lin' }`.
- **Locales** are BCP 47 tags (`'en'`, `'pt-BR'`, `'zh-Hans'`). Their names come from `Intl.DisplayNames` in the interface's language, and you can pass `{ code, label }` to name one yourself.
- **Direction and script:** every control carries its locale's `lang` and `dir`. Arabic and Hebrew run right to left, spellcheck and speech follow the language, and Japanese gets Japanese glyphs rather than Chinese ones. Chinese, Japanese, Korean, Devanagari and Thai are set a step larger.
- **The source locale** (`sourceLocale`, the first by default) is the one translations are made from. A required Field requires it, or every locale in `requiredLocales`.
- **Native forms:** with a `name`, the form submits one hidden input per locale: `name[en]`, `name[fr]`, and so on.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### MultiLanguageInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `locales` | `LocaleInput[]` |  | The locales (BCP 47 tags or `{ code, label?, flag?, group? }`). Required on its own; inside a MultiLanguageProvider, the provider's apply. |
| `sourceLocale` | `string` |  | On its own: the locale translations are made from. Default: the first locale. |
| `requiredLocales` | `string[]` |  | Locales a required field must be filled in. Default: the provider's, or the source locale. |
| `locale` | `string` |  | On its own: the locale being edited (controlled). |
| `onLocaleChange` | `(locale: string) => void` |  |  |
| `view` | `'single' \| 'side-by-side'` |  | On its own: 'side-by-side' shows the source beside the translation. |
| `pinned` | `string[]` |  | On its own: locales kept as one-press keys in the switcher. |
| `value` | `TranslationValue` |  |  |
| `defaultValue` | `TranslationValue` |  |  |
| `onValueChange` | `(value: TranslationValue) => void` |  |  |
| `review` | `TranslationReviews` |  | Per locale: the source text it was translated against and whether it's reviewed (controlled). Store it beside the value to keep "outdated" across sessions. |
| `defaultReview` | `TranslationReviews` |  |  |
| `onReviewChange` | `(review: TranslationReviews) => void` |  |  |
| `suggestions` | `Record<string, string>` |  | Machine suggestions per locale, offered in empty locales and filled as "needs review". |
| `multiline` | `boolean` |  | A textarea instead of a single line. |
| `placeholder` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  | Requires the required locales. Default: the surrounding Field's `required`. |
| `name` | `string` |  | Submits one hidden input per locale, `name[code]`. |
| `maxLength` | `number` |  | A hard cap: the browser stops typing past it. |
| `limit` | `number \| Record<string, number>` |  | A soft limit in characters, for every locale or per locale: a count, and an error past it. |
| `validate` | `(text: string, locale: string) => string \| null \| undefined \| false` |  | A message for invalid text in a locale, or nothing. |
| `errors` | `Record<string, string \| undefined>` |  | Errors per locale from your app or server. |
| `ref` | `Ref<HTMLInputElement & HTMLTextAreaElement>` |  | The text control, e.g. react-hook-form's `field.ref`. |
| `onBlur` | `(event: FocusEvent<HTMLInputElement \| HTMLTextAreaElement>) => void` |  |  |
| `aria-label` | `string` |  | Names the field outside a Field (the locale is added: "Title, German"). |

Also takes the props of `ComponentProps<'div'>`.

#### MultiLanguageProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `locales` (required) | `LocaleInput[]` |  | The locales, as BCP 47 tags ('en', 'pt-BR') or `{ code, label?, flag?, group? }`. Their order is the order everywhere. |
| `sourceLocale` | `string` |  | The locale translations are made from. Default: the first locale. |
| `requiredLocales` | `string[]` |  | Locales a required field must be filled in. Default: the source locale. |
| `locale` | `string` |  | The locale being edited (controlled). |
| `defaultLocale` | `string` |  | The locale edited at first (uncontrolled). Default: the source locale. |
| `onLocaleChange` | `(locale: string) => void` |  |  |
| `pinned` | `string[]` |  | Locales kept as one-press keys in the switcher; the rest are a search away. Default: every locale when there are 5 or fewer, else the source and required locales. |
| `view` | `'single' \| 'side-by-side'` |  | 'side-by-side' shows the source beside each translation. |
| `defaultView` | `'single' \| 'side-by-side'` |  |  |
| `onViewChange` | `(view: MultiLanguageView) => void` |  |  |
| `missingOnly` | `boolean` |  | Lists only the locales that need work in the picker. |
| `defaultMissingOnly` | `boolean` |  |  |
| `onMissingOnlyChange` | `(missingOnly: boolean) => void` |  |  |
| `groupBy` | `'region' \| 'script' \| 'none'` | `'region'` | How the picker groups the locales. |
| `displayLocale` | `string` |  | The language locales are named in. Default: the YoujProvider's locale. |
| `onBulkAction` | `(result: BulkResult) => void` |  | After a bulk action: offer an Undo with `result.undo`. |
| `children` (required) | `ReactNode` |  |  |

#### MultiLanguageSwitcher, MultiLanguageProgress and MultiLanguageActions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `stepper` | `boolean` |  | Up and down buttons to the previous and next locale that needs work. Default: with more than three locales. |
| `progress` | `boolean` | `true` | The progress ring and count. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'ring' \| 'bar'` | `'ring'` | 'ring' is compact, for a toolbar; 'bar' also shows what's outdated or waiting for review. |
| `locale` | `string` |  | One locale across the fields. Default: every locale. |
| `showCount` | `boolean` | `variant === 'ring'` | Shows the count: "12/16" beside a ring, a caption with a legend over a bar. |

Also takes the props of `ComponentProps<'div'>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `locale` | `string` |  | The locale the actions apply to. Default: the one being edited. |

#### Helpers

| Export | What it does |
| --- | --- |
| `useMultiLanguage()` | Returns `locale`, `setLocale`, `view`, `setView`, `missingOnly`, `setMissingOnly`, `summaries` (per locale: worst status, and field counts per status), `next()` / `previous()`, and the bulk actions. |
| `missingTranslations(value, locales)` | The locales among `locales` with no text. |
| `translationStatus(value, locale, source, review?)` | One translation's status. |
| `describeLocale(code, displayLocale)` | A locale's name, native name, script, region and direction. |
| `countCharacters(text, locale)` | Characters as a reader counts them (grapheme clusters). |
| `TranslationStatusIcon` | The status glyph on its own, for your own overviews. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Locale switch | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the new text fades up and drifts 6px in from the side it came from (a Web Animation; the next switch cancels it) |
| Keys and picker highlight | `spring.smooth` | 0.36s, bounce 0 | glide to the selected key and the highlighted row |
| Status glyph | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | a changed status pops in |
| Locale complete | `spring.settle` | 0.45s, bounce 0.3 | the disc lands and its check draws |
| Progress ring | `spring.smooth` | 0.36s, bounce 0 | the arc follows the count, and turns to success at 100% |
| Progress bar and meters | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | segments grow and move along the track |
| Copy flash | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the surface tints at once, then fades back |
| Source pane | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades in with a 4px drift as side by side opens |

**Reduced motion:** The text changes in place, keys and highlights jump, statuses appear drawn, meters jump to their value and nothing flashes. Announcements and focus are unchanged.

#### Reduced motion

The text swaps in place, the keys and the picker highlight jump, statuses appear already drawn, and meters show their value at once. Copying doesn't flash. Focus, the caret and every announcement are unchanged.

### Accessibility

- **Names:** every control is named by its Field label and its locale: "Title, German".
- **Descriptions:** it's described by the Field's description and error, the source text in side-by-side view, the note for the locale being edited, and the character count. `aria-invalid` follows the locale being edited.
- **Keys:** the keys are a toggle group named "Language". Each key reads its language and, when there's work, its status ("French, Missing").
- **Picker:** its search is a combobox that drives a grouped listbox through `aria-activedescendant`, so focus stays in the search. An empty result is announced.
- **Announcements:** locale switches from the keyboard shortcut or the picker, copies, suggestions, "mark reviewed" and bulk actions are announced politely.
- **Progress:** the progress ring and bar are progress bars, and their value text reads the whole breakdown ("12 of 16 languages complete, 2 outdated, 2 missing").

| Key | Action |
| --- | --- |
| ← → | Move between the keys. |
| Any letter on the picker key | Opens the picker with that letter searched. |
| ↑ ↓, Enter, Escape (picker) | Move through the locales, pick one, close. |
| ⌥⌘↓ / ⌥⌘↑ (Ctrl+Alt elsewhere) | Next or previous locale that needs work, from anywhere in the field or form. |

---

# Table

> Show rows of data in a plain, accessible table whose rows can move with Presence List.

Source: https://www.youj.dev/docs/components/table

## Examples

### Demo

```tsx
'use client'

import { Badge, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow } from '@youj/react'

const INVOICES = [
  { id: 'INV-2041', customer: 'Northwind Traders', status: 'Paid', amount: 4200 },
  { id: 'INV-2040', customer: 'Brightline Health', status: 'Pending', amount: 1180 },
  { id: 'INV-2039', customer: 'Kestrel Labs', status: 'Paid', amount: 760 },
  { id: 'INV-2038', customer: 'Lattice Freight', status: 'Overdue', amount: 2950 },
] as const

const VARIANT = { Paid: 'success', Pending: 'secondary', Overdue: 'danger' } as const
const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })

export default function TableDemo() {
  const total = INVOICES.reduce((sum, invoice) => sum + invoice.amount, 0)
  return (
    <div className="w-full max-w-2xl rounded-xl border border-line bg-surface">
      <Table aria-label="Invoices">
        <TableHeader>
          <TableRow>
            <TableHead>Invoice</TableHead>
            <TableHead>Customer</TableHead>
            <TableHead>Status</TableHead>
            <TableHead className="text-end">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {INVOICES.map((invoice) => (
            <TableRow key={invoice.id}>
              <TableCell className="font-mono text-ui-sm text-fg-muted">{invoice.id}</TableCell>
              <TableCell className="font-medium">{invoice.customer}</TableCell>
              <TableCell>
                <Badge variant={VARIANT[invoice.status]}>{invoice.status}</Badge>
              </TableCell>
              <TableCell className="text-end tabular-nums">{usd.format(invoice.amount)}</TableCell>
            </TableRow>
          ))}
        </TableBody>
        <TableFooter>
          <TableRow>
            <TableCell colSpan={3}>Total</TableCell>
            <TableCell className="text-end tabular-nums">{usd.format(total)}</TableCell>
          </TableRow>
        </TableFooter>
      </Table>
    </div>
  )
}
```

Four invoices with a status badge, figures aligned on their digits and a total in the footer.

For rows people sort, filter and act on, compose the [Data table kit](https://www.youj.dev/docs/components/data-table) with these parts, or copy in a complete table from [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists).

### Toolbar and paging

```tsx
'use client'

import { useState, type MouseEvent } from 'react'
import {
  Avatar,
  AvatarFallback,
  Badge,
  BadgeDot,
  Button,
  Card,
  CardAction,
  CardContent,
  CardHeader,
  CardTitle,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
  paginationRange,
} from '@youj/react'
import { MoreHorizontalIcon, PlusIcon, SearchIcon } from '@youj/icons'

const STATUS = {
  ready: { label: 'Ready', variant: 'success' },
  building: { label: 'Building', variant: 'warning' },
  canceled: { label: 'Canceled', variant: 'secondary' },
  failed: { label: 'Failed', variant: 'danger' },
} as const

const DEPLOYS = [
  { id: 'DP-7712', author: 'Noor Haddad', branch: 'main', status: 'ready', duration: '1m 42s' },
  { id: 'DP-7711', author: 'Tomás Reyes', branch: 'feat/search-index', status: 'building', duration: '0m 58s' },
  { id: 'DP-7710', author: 'Wen Li', branch: 'fix/token-refresh', status: 'ready', duration: '2m 07s' },
  { id: 'DP-7709', author: 'Ada Okoye', branch: 'chore/deps', status: 'canceled', duration: '0m 12s' },
  { id: 'DP-7708', author: 'Noor Haddad', branch: 'feat/billing-export', status: 'failed', duration: '3m 31s' },
] as const

const PAGES = 42

const initialsOf = (name: string) =>
  name
    .split(/\s+/)
    .map((part) => part[0])
    .join('')
    .slice(0, 2)
    .toUpperCase()

function RowMenu({ label }: { label: string }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" size="icon-xs" aria-label={label} />}>
        <MoreHorizontalIcon />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuItem>View logs</DropdownMenuItem>
        <DropdownMenuItem>Redeploy</DropdownMenuItem>
        <DropdownMenuItem variant="danger">Cancel</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

export default function TableToolbar() {
  const [query, setQuery] = useState('')
  const [page, setPage] = useState(1)
  const rows = DEPLOYS.filter((d) => `${d.id} ${d.author} ${d.branch}`.toLowerCase().includes(query.trim().toLowerCase()))
  const go = (next: number) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(Math.min(Math.max(next, 1), PAGES))
  }
  return (
    <Card variant="panel" className="w-full max-w-3xl">
      <CardHeader>
        <CardTitle>Deployments</CardTitle>
        <CardAction>
          <InputGroup className="w-48">
            <InputGroupAddon>
              <SearchIcon />
            </InputGroupAddon>
            <InputGroupInput aria-label="Search deployments" placeholder="Search…" value={query} onChange={(e) => setQuery(e.target.value)} />
          </InputGroup>
          <Button size="sm" variant="outline">
            <PlusIcon />
            New deploy
          </Button>
          <RowMenu label="Deployment list options" />
        </CardAction>
      </CardHeader>
      <CardContent className="px-0 py-0">
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead className="ps-4">ID</TableHead>
              <TableHead>Author</TableHead>
              <TableHead>Branch</TableHead>
              <TableHead>Status</TableHead>
              <TableHead className="text-end">Duration</TableHead>
              <TableHead className="w-12 pe-4">
                <span className="sr-only">Actions</span>
              </TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {rows.map((d) => (
              <TableRow key={d.id}>
                <TableCell className="ps-4 font-mono text-ui-sm text-fg-muted">{d.id}</TableCell>
                <TableCell>
                  <span className="flex items-center gap-2">
                    <Avatar size="sm">
                      <AvatarFallback>{initialsOf(d.author)}</AvatarFallback>
                    </Avatar>
                    {d.author}
                  </span>
                </TableCell>
                <TableCell className="text-fg-muted">{d.branch}</TableCell>
                <TableCell>
                  <Badge variant={STATUS[d.status].variant}>
                    <BadgeDot />
                    {STATUS[d.status].label}
                  </Badge>
                </TableCell>
                <TableCell className="text-end font-mono tabular-nums">{d.duration}</TableCell>
                <TableCell className="pe-4 text-end">
                  <RowMenu label={`Actions for ${d.id}`} />
                </TableCell>
              </TableRow>
            ))}
            {rows.length === 0 && (
              <TableRow>
                <TableCell colSpan={6} className="h-24 text-center text-fg-muted">
                  No deployments match “{query}” on this page.
                </TableCell>
              </TableRow>
            )}
          </TableBody>
        </Table>
        <div className="flex flex-wrap items-center justify-between gap-3 border-t border-line px-4 py-2.5">
          <span className="text-ui-sm text-fg-muted">Showing {rows.length} of 208 deployments</span>
          <Pagination aria-label="Deployment pages" className="mx-0 w-auto">
            <PaginationContent>
              {paginationRange(page, PAGES).map((item) =>
                typeof item === 'number' ? (
                  <PaginationItem key={item}>
                    <PaginationLink href={`?page=${item}`} isActive={item === page} aria-label={`Page ${item}`} onClick={go(item)}>
                      {item}
                    </PaginationLink>
                  </PaginationItem>
                ) : (
                  <PaginationItem key={item}>
                    <PaginationEllipsis />
                  </PaginationItem>
                ),
              )}
              <PaginationItem>
                <PaginationNext href={`?page=${page + 1}`} disabled={page === PAGES} onClick={go(page + 1)} />
              </PaginationItem>
            </PaginationContent>
          </Pagination>
        </div>
      </CardContent>
    </Card>
  )
}
```

A deployments panel: a toolbar head, status badges with a dot, avatar-initial cells, a menu per row and paging with gaps.

It's composed from parts you already have: a [Card](https://www.youj.dev/docs/components/card) with `variant="panel"` whose `CardAction` holds an [Input Group](https://www.youj.dev/docs/components/input-group) search, a button and a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu); a `BadgeDot` inside each status [Badge](https://www.youj.dev/docs/components/badge); an [Avatar](https://www.youj.dev/docs/components/avatar) with initials as its fallback; and [Pagination](https://www.youj.dev/docs/components/pagination) laid out by `paginationRange`, which keeps the pager's width while you page. Search here filters the rows on the page.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add table
```

It brings `youj-core`, `youj-labels-table`, `youj-presets`, `youj-ui-core` with it.

Use the Table parts for a small, static table: a few rows with no sorting or filtering of their own. Their dividers sit on the cells, not the rows, so rows can move with [Presence List](https://www.youj.dev/docs/motion/presence-list) and take their borders with them.

```tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@youj/react'

<Table aria-label="Domains">
  <TableHeader>
    <TableRow>
      <TableHead>Domain</TableHead>
      <TableHead className="text-end">Redirects</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>acme.dev</TableCell>
      <TableCell className="text-end tabular-nums">2</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Table

Takes the props of `ComponentProps<'table'>`.

### Accessibility

- Name a table with `aria-label` or a `<TableCaption>`; headers are `<th>` cells, so each cell is read with its column.
- A table that scrolls sideways takes a Tab stop of its own and is named, so the keyboard can scroll it.
- Rows that move with Presence List keep their borders, since the dividers sit on the cells.

---

# Data table kit

> The parts a data table is made of, on TanStack Table v9: headers that sort and resize, search and filters with chips, pages, selection, saved views, inline editing, a keyboard grid and CSV.

Source: https://www.youj.dev/docs/components/data-table

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { useLocale } from '@youj/core'
import { Badge, Button, Table, TableBody, TableCell, TableHeader, TableRow } from '@youj/react'
import {
  DataTableColumnFilter,
  DataTableColumnHeader,
  DataTableFilterChips,
  DataTablePagination,
  DataTableSearch,
  DataTableSelectionBar,
  DataTableToolbar,
  DataTableViewOptions,
  createDataTableColumnHelper,
  createSelectColumn,
  dataTableFilterChips,
  useDataTable,
} from '@youj/react/data-table'

type Status = 'todo' | 'in-progress' | 'done' | 'canceled'
interface Task {
  id: string
  title: string
  status: Status
  priority: 'Urgent' | 'High' | 'Medium' | 'Low'
  estimate: number
}

const STATUS = {
  todo: { label: 'Todo', variant: 'secondary' },
  'in-progress': { label: 'In progress', variant: 'default' },
  done: { label: 'Done', variant: 'success' },
  canceled: { label: 'Canceled', variant: 'outline' },
} as const

const TITLES = ['Fix the sign-in redirect', 'Debounce the search query', 'Add passkeys', 'Write the migration guide', 'Cache the read API', 'Dark mode for charts']
const STATUSES = Object.keys(STATUS) as Status[]
const PRIORITIES: Task['priority'][] = ['Urgent', 'High', 'Medium', 'Low']
const TASKS: Task[] = Array.from({ length: 24 }, (_, i) => ({
  id: `TSK-${1040 + i}`,
  title: TITLES[i % TITLES.length]!,
  status: STATUSES[(i * 7) % STATUSES.length]!,
  priority: PRIORITIES[(i * 3) % PRIORITIES.length]!,
  estimate: 1 + ((i * 5) % 13),
}))

const col = createDataTableColumnHelper<Task>()
const columns = [
  createSelectColumn<Task>({ label: (task) => task.id }),
  ...col.columns([
    col.accessor('id', { header: 'Task', size: 110, meta: { cellClassName: 'font-mono text-ui-sm text-fg-muted' } }),
    col.accessor('title', { header: 'Title', size: 280 }),
    col.accessor('status', {
      header: 'Status',
      size: 140,
      cell: (ctx) => <Badge variant={STATUS[ctx.getValue()].variant}>{STATUS[ctx.getValue()].label}</Badge>,
      meta: { filter: { type: 'select', options: STATUSES.map((value) => ({ value, label: STATUS[value].label })) } },
    }),
    col.accessor('priority', { header: 'Priority', size: 120, meta: { filter: { type: 'select' } } }),
    col.accessor('estimate', { header: 'Estimate', size: 110, cell: (ctx) => `${ctx.getValue()} pt`, meta: { numeric: true } }),
  ]),
]

export default function DataTableParts() {
  const locale = useLocale()
  const [rows, setRows] = useState(TASKS)
  // The table keeps its own state (sort, filters, search, selection, pages); pass `state` for any slice you own.
  const table = useDataTable({ data: rows, columns, getRowId: (task) => task.id, initialState: { pagination: { pageIndex: 0, pageSize: 8 } } })
  const selected = Object.keys(table.state.rowSelection)

return (
    <div className="flex w-full flex-col gap-3">
      <DataTableToolbar actions={<DataTableViewOptions table={table} />}>
        <DataTableSearch table={table} placeholder="Search tasks…" />
        <DataTableColumnFilter column={table.getColumn('status')!} />
        <DataTableColumnFilter column={table.getColumn('priority')!} />
      </DataTableToolbar>
      <DataTableFilterChips
        chips={dataTableFilterChips(table, locale)}
        onClearAll={() => {
          table.resetColumnFilters(true)
          table.setGlobalFilter('')
        }}
      />
      <div className="relative overflow-clip rounded-xl border border-line bg-surface">
        <Table aria-label="Tasks">
          <TableHeader>
            {table.getHeaderGroups().map((group) => (
              <TableRow key={group.id}>
                {group.headers.map((header) => (
                  <DataTableColumnHeader key={header.id} header={header} style={{ width: header.getSize() }} />
                ))}
              </TableRow>
            ))}
          </TableHeader>
          <TableBody>
            {table.getRowModel().rows.map((row) => (
              <TableRow key={row.id} data-state={row.getIsSelected() ? 'selected' : undefined}>
                {row.getVisibleCells().map((cell) => (
                  <TableCell key={cell.id} className={cell.column.columnDef.meta?.cellClassName}>
                    <table.FlexRender cell={cell} />
                  </TableCell>
                ))}
              </TableRow>
            ))}
          </TableBody>
        </Table>
        <div className="border-t border-line">
          <DataTablePagination table={table} noun="tasks" />
        </div>
        <DataTableSelectionBar count={selected.length} noun="tasks" onClear={() => table.resetRowSelection()}>
          <Button
            variant="ghost"
            size="sm"
            onClick={() => {
              setRows((list) => list.filter((task) => !selected.includes(task.id)))
              table.resetRowSelection()
            }}
          >
            Delete
          </Button>
        </DataTableSelectionBar>
      </div>
    </div>
  )
}
```

A tasks table built from the kit: a search, two value filters with counts and their chips, headers that sort and open a column menu, the Columns menu, pages, a checkbox column and the bar a selection raises.

The complete tables are blocks: [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists) has a dense data table, a records grid with a rich cell for every kind of value, and tables for contacts, orders, inventory (a spreadsheet), live logs and grouped budgets, all built from these parts. Copy one in when it's close to what you need, or compose the parts yourself as this example does.

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add data-table
```

It brings `alert-dialog`, `badge`, `button`, `checkbox`, `collapse`, `command`, `counter`, `dialog`, `dropdown-menu`, `field`, `icon-arrow-down`, `icon-arrow-left`, `icon-arrow-right`, `icon-arrow-up`, `icon-bookmark`, `icon-calendar`, `icon-chevron-down`, `icon-chevron-left`, `icon-chevron-right`, `icon-chevrons-left`, `icon-chevrons-right`, `icon-circle-plus`, `icon-columns`, `icon-eye-off`, `icon-more-horizontal`, `icon-pin`, `icon-pin-off`, `icon-plus`, `icon-rotate-ccw`, `icon-rows`, `icon-rows-2`, `icon-save`, `icon-search`, `icon-sliders`, `icon-trash`, `icon-x`, `input`, `input-group`, `kbd`, `popover`, `presence-list`, `select`, `separator`, `slider`, `toggle-group`, `youj-core`, `youj-labels-data-table-bulk-bar`, `youj-labels-data-table-columns`, `youj-labels-data-table-confirm`, `youj-labels-data-table-editor`, `youj-labels-data-table-filters`, `youj-labels-data-table-pagination`, `youj-labels-data-table-toolbar`, `youj-labels-data-table-views`, `youj-presets`, `youj-ui-core` with it.

The copy is 80 registry items, about 17,100 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `alert-dialog`, `async-button`, `async-feedback`, `badge`, `button`, `checkbox`, `collapse`, `command`, `counter`, `dialog` and 50 more.

Compose the kit's parts with the [Table](https://www.youj.dev/docs/components/table) parts for rows people sort, filter and act on. They're built on TanStack Table v9, which installs with them. `cmdk` is an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies) the filter menus need, so the kit ships from `@youj/react/data-table`:

With pnpm, npm, Yarn or Bun:

```bash
pnpm add cmdk
npm install cmdk
yarn add cmdk
bun add cmdk
```

`useDataTable` is TanStack's `useTable` with the kit's features (sorting, the toolbar's filters, faceting, pagination, selection and the column features), and every part takes the table it returns. The table keeps its own state; pass `state` and its change callbacks for any slice you own. It also puts each column's alignment in `meta.cellClassName` (a `numeric` column's cells end-aligned in tabular figures, like its header), so give that to each `TableCell`.

```tsx
import { Table, TableBody, TableCell, TableHeader, TableRow } from '@youj/react'
import { useLocale } from '@youj/core'
import {
  DataTableColumnFilter,
  DataTableColumnHeader,
  DataTableFilterChips,
  DataTablePagination,
  DataTableSearch,
  DataTableToolbar,
  DataTableViewOptions,
  createDataTableColumnHelper,
  dataTableFilterChips,
  useDataTable,
} from '@youj/react/data-table'

const col = createDataTableColumnHelper<Task>()
const columns = col.columns([
  col.accessor('title', { header: 'Title' }),
  col.accessor('status', { header: 'Status', meta: { filter: { type: 'select' } } }),
  col.accessor('estimate', { header: 'Estimate', meta: { numeric: true } }),
])

export function Tasks({ tasks }: { tasks: Task[] }) {
  const locale = useLocale()
  const table = useDataTable({ data: tasks, columns, getRowId: (task) => task.id })
  return (
    <>
      <DataTableToolbar actions={<DataTableViewOptions table={table} />}>
        <DataTableSearch table={table} />
        <DataTableColumnFilter column={table.getColumn('status')!} />
      </DataTableToolbar>
      <DataTableFilterChips
        chips={dataTableFilterChips(table, locale)}
        onClearAll={() => {
          table.resetColumnFilters(true)
          table.setGlobalFilter('')
        }}
      />
      <Table aria-label="Tasks">
        <TableHeader>
          {table.getHeaderGroups().map((group) => (
            <TableRow key={group.id}>
              {group.headers.map((header) => <DataTableColumnHeader key={header.id} header={header} />)}
            </TableRow>
          ))}
        </TableHeader>
        <TableBody>
          {table.getRowModel().rows.map((row) => (
            <TableRow key={row.id}>
              {row.getVisibleCells().map((cell) => (
                <TableCell key={cell.id} className={cell.column.columnDef.meta?.cellClassName}>
                  <table.FlexRender cell={cell} />
                </TableCell>
              ))}
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <DataTablePagination table={table} noun="tasks" />
    </>
  )
}
```

The toolbar's search and filters change what the table shows, but they don't list what is in force. `DataTableFilterChips` does: one chip for the search and one per active filter, each removable, and Clear all. It takes the chips from `dataTableFilterChips(table, locale)`, so it needs the table and the locale (`useLocale()`), and it renders nothing while no filter is on.

### Where things come from

The `Table` parts (`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableCell`) come from `@youj/react`. The kit (`useDataTable`, the toolbar, the headers, pagination, selection) comes from `@youj/react/data-table`, so the table's `cmdk` dependency stays out of apps that don't use it. A table imports from both, as the example above does.

### Custom cells and alignment

A column's `cell` renders its value however you like. It receives TanStack's cell context, with `getValue()` and the row's `original`:

```tsx
import { Badge } from '@youj/react'

col.accessor('status', {
  header: 'Status',
  cell: (ctx) => <Badge variant={ctx.getValue() === 'done' ? 'success' : 'neutral'}>{ctx.getValue()}</Badge>,
})
col.accessor('estimate', { header: 'Estimate', cell: (ctx) => `${ctx.getValue()} pt`, meta: { numeric: true } })
```

`meta: { numeric: true }` marks a column of numbers: its header and cells align to the end, so digits line up down the column whatever your `cell` renders. `meta.align` (`'start'`, `'center'` or `'end'`) sets it for any other column.

### Reading the selection

With `createSelectColumn` in the columns, the table keeps the selection by row id (your `getRowId`). Read the selected rows with `table.getSelectedRowModel()`, and clear them with `table.resetRowSelection()`:

```tsx
const selected = table.getSelectedRowModel().rows.map((row) => row.original)

<DataTableSelectionBar count={selected.length} noun="tasks" onClear={() => table.resetRowSelection()}>
  <Button
    variant="ghost"
    size="sm"
    onClick={async () => {
      await deleteTasks(selected.map((task) => task.id))
      table.resetRowSelection()
    }}
  >
    Delete
  </Button>
</DataTableSelectionBar>
```

Put the bar inside the element that frames the table, as its last child, after the pagination. That element needs `position: relative`. The bar rides a zero-height sticky anchor at the frame's lower edge, so it floats over the bottom of the viewport while a long table scrolls and never moves the layout. Keep the pagination row under the rows: the bar settles over it, not over the last row. A table with no pagination needs bottom padding on its frame (`pb-16`) for the same reason.

```tsx
<div className="relative overflow-clip rounded-xl border border-line bg-surface">
  <Table aria-label="Tasks">{/* … */}</Table>
  <div className="border-t border-line">
    <DataTablePagination table={table} noun="tasks" />
  </div>
  <DataTableSelectionBar count={selected.length} onClear={() => table.resetRowSelection()}>
    {/* actions */}
  </DataTableSelectionBar>
</div>
```

### Number and date filters

Besides `select`, a column's `meta.filter` can be a range. `number-range` gives a two-thumb slider with exact bounds, spanning the column's values unless you pass `min` and `max`; `format` writes the bounds in the key and its chip. `date-range` gives presets (Today, Last 7 days…) and two exact days; its column holds dates, or `YYYY-MM-DD` strings.

```tsx
col.accessor('aqi', {
  header: 'AQI',
  meta: { numeric: true, filter: { type: 'number-range', min: 0, max: 300, step: 5 } },
})
col.accessor('date', { header: 'Date', meta: { filter: { type: 'date-range', title: 'Day' } } })
```

Each writes plain JSON (`{ min, max }`, `{ from, to }`), so a saved view or a link can hold it. The date filter's presets read today when it opens, never while the page renders, so a prerendered page is stable.

### Export to CSV

`dataTableToCsv(table, rows)` writes the rows you pass, in the columns on screen, as CSV that spreadsheets read; `downloadCsv(csv, filename)` hands it to the browser. To export everything the filters and search leave, in the order on screen, across every page, pass `table.getSortedRowModel().rows` (`getRowModel()` is only the current page):

```tsx
import { Button } from '@youj/react'
import { dataTableToCsv, downloadCsv } from '@youj/react/data-table'

<Button
  variant="outline"
  size="sm"
  disabled={table.getFilteredRowModel().rows.length === 0}
  onClick={() => downloadCsv(dataTableToCsv(table, table.getSortedRowModel().rows), 'readings.csv')}
>
  Export CSV
</Button>
```

For the selection, pass `table.getSelectedRowModel().rows`. A column's `meta.exportValue` writes its value its own way, and `meta.exportable: false` leaves it out.

### All rows on one page

A short list (a sprint's issues, a board's backlog) doesn't need pages. Pass `paginate: false` and the table shows every row that passes its filters, in order; leave out `DataTablePagination`:

```tsx
const table = useDataTable({ data: issues, columns, getRowId: (issue) => issue.id, paginate: false })
```

The pagination state and its methods still exist (the parts that read them keep working), but `getRowModel()` returns every row. For thousands of rows, keep pages or virtualize the body.

### Editing a cell

The kit has the editor, not the save. Give a column `meta.editor` (`text`, `number` or `select`) and, if it needs one, `meta.validate`; keep which cell is being edited in state; and render `DataTableCellEditor` in that cell (its `TableCell` needs `position: relative`, since the editor lies over it). Its `onCommit` hands you the parsed value: return a reason to keep the editor open with it, or `null` to accept, then save the value however your app saves.

```tsx
import { DataTableCellEditor } from '@youj/react/data-table'

const [editing, setEditing] = useState<{ rowId: string; columnId: string } | null>(null)

<TableCell key={cell.id} className="relative" onDoubleClick={() => meta?.editor && setEditing({ rowId: row.id, columnId: cell.column.id })}>
  <table.FlexRender cell={cell} />
  {meta?.editor && editing?.rowId === row.id && editing.columnId === cell.column.id && (
    <DataTableCellEditor
      editor={meta.editor}
      value={cell.getValue()}
      label={`${dataTableColumnLabel(cell.column)}, ${row.id}`}
      onCommit={(value) => {
        const reason = meta.validate?.(value)
        if (reason) return reason
        setEditing(null)
        void saveTask(row.id, cell.column.id, value)
        return null
      }}
      onTab={(value) => { /* commit, then move to the next editable cell */ return null }}
      onCancel={() => setEditing(null)}
    />
  )}
</TableCell>
```

with `const meta = cell.column.columnDef.meta`. The [Data table](https://www.youj.dev/docs/blocks/tables-and-lists) block wires the whole flow (Enter, F2 or typing to start, Tab to the next cell, an optimistic value that rolls back if the save fails) behind one prop, `onCellEdit`: copy it in when you want that rather than building it.

### Coming from TanStack Table v8

The kit is on TanStack Table v9, and code from v8 examples needs these renames:

| v8 | v9 (and the kit) |
| --- | --- |
| `useReactTable({ getCoreRowModel: getCoreRowModel(), … })` | `useDataTable({ data, columns })`: the features and row models come with it (`dataTableFeatures`) |
| `createColumnHelper<Task>()` | `createDataTableColumnHelper<Task>()` (v9's helper also takes the features: `createColumnHelper<DataTableFeatures, Task>()`) |
| `flexRender(cell.column.columnDef.cell, cell.getContext())` | `<table.FlexRender cell={cell} />` (also `header=` and `footer=`) |
| `sortingFn: 'datetime'` | `sortFn: 'datetime'` (the kit registers `alphanumeric`, `basic`, `datetime` and `text`) |
| `sortingFns`, `filterFns` in the options | registered in the features (`tableFeatures({ sortFns, filterFns })`); the kit's set is in `dataTableFeatures` |
| `table.getState().sorting` | `table.state.sorting` |
| `ColumnDef<Task>` | `DataTableColumnDef<Task>` (v9's `ColumnDef` takes the features first) |

`getSortedRowModel()`, `getFilteredRowModel()` and `getPaginationRowModel()` are gone as options: each is a row model in the features (`sortedRowModel: createSortedRowModel()`), and `useDataTable` includes them. Methods on the table, a column and a row (`table.getRowModel()`, `column.toggleSorting()`, `row.getIsSelected()`) are unchanged.

### Empty and loading states

The kit renders rows; what shows when there are none is yours. Use one `TableRow` with a single cell that spans the columns. While data loads, draw placeholder rows with [Skeleton](https://www.youj.dev/docs/components/skeleton) so the table keeps its size, and when a filter leaves nothing, say so and offer the way out:

```tsx
import { Button, Skeleton, TableBody, TableCell, TableRow } from '@youj/react'

const rows = table.getRowModel().rows
const span = table.getVisibleLeafColumns().length

<TableBody>
  {loading ? (
    Array.from({ length: 5 }, (_, i) => (
      <TableRow key={i}>
        <TableCell colSpan={span}>
          <Skeleton className="h-5 w-full" />
        </TableCell>
      </TableRow>
    ))
  ) : rows.length === 0 ? (
    <TableRow>
      <TableCell colSpan={span} className="h-32 text-center text-fg-muted">
        No tasks match.{' '}
        <Button variant="link" onClick={() => { table.resetColumnFilters(true); table.setGlobalFilter('') }}>
          Clear filters
        </Button>
      </TableCell>
    </TableRow>
  ) : (
    rows.map((row) => /* … */)
  )}
</TableBody>
```

For a table with nothing in it at all, an [Empty State](https://www.youj.dev/docs/components/empty-state) in place of the whole table says more than an empty row.

### A row opens a detail sheet

Keep the open row's id in state, and render a [Sheet](https://www.youj.dev/docs/components/sheet) for it beside the table. Two things make the row safe to click and usable without a mouse:

- **The row's click is a convenience for the pointer.** Ignore it when it began on something interactive inside the row (the select checkbox, a row-actions menu, a link, a status Select), or a click meant for those opens the sheet too. Ignore it too when it came from outside the row's DOM: React bubbles events through portals, so picking an option in a cell's Select or a menu item reaches the row's `onClick` although the popup isn't in the row.
- **The keyboard opens the sheet from a button.** A table row isn't a button and shouldn't pretend to be one. Render the row's id as a real `button` in its cell: it is a Tab stop, Enter and Space open the sheet, and it gives the row an accessible name for what opens.

```tsx
import { Sheet, SheetBody, SheetContent, SheetDescription, SheetHeader, SheetTitle, Table, TableBody, TableCell, TableRow } from '@youj/react'
import { createDataTableColumnHelper, createSelectColumn, useDataTable } from '@youj/react/data-table'
import { useState } from 'react'

const col = createDataTableColumnHelper<Task>()

// What is interactive inside a row: its own controls and the roles Base UI gives its triggers and popups.
const ROW_CONTROLS =
  'button, a[href], input, textarea, select, label, [contenteditable="true"], [role="checkbox"], [role="switch"], [role="combobox"], [role="listbox"], [role="option"], [role="menu"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="slider"], [role="tab"]'

export function Tasks({ tasks }: { tasks: Task[] }) {
  const [openId, setOpenId] = useState<string | null>(null)
  const columns = col.columns([
    createSelectColumn<Task>({ label: (task) => task.id }),
    col.accessor('id', {
      header: 'Task',
      cell: (ctx) => (
        <button type="button" className="font-mono text-ui-sm underline-offset-4 hover:underline" onClick={() => setOpenId(ctx.getValue())}>
          {ctx.getValue()}
        </button>
      ),
    }),
    col.accessor('title', { header: 'Title' }),
  ])
  const table = useDataTable({ data: tasks, columns, getRowId: (task) => task.id })
  const task = tasks.find((t) => t.id === openId)

return (
    <>
      <Table aria-label="Tasks">
        <TableBody>
          {table.getRowModel().rows.map((row) => (
            <TableRow
              key={row.id}
              className="cursor-pointer"
              data-state={row.getIsSelected() ? 'selected' : undefined}
              onClick={(event) => {
                const target = event.target as HTMLElement
                // A popup's option or menu item (portaled out of the row) isn't the row's click.
                if (!event.currentTarget.contains(target)) return
                // Nor is a click on the checkbox, a menu, a link or a select inside the row.
                const control = target.closest(ROW_CONTROLS)
                if (control && event.currentTarget.contains(control)) return
                setOpenId(row.id)
              }}
            >
              {row.getVisibleCells().map((cell) => (
                <TableCell key={cell.id}>
                  <table.FlexRender cell={cell} />
                </TableCell>
              ))}
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <Sheet open={task !== undefined} onOpenChange={(open) => !open && setOpenId(null)}>
        <SheetContent side="end">
          <SheetHeader>
            <SheetTitle>{task?.title}</SheetTitle>
            <SheetDescription>{task?.id}</SheetDescription>
          </SheetHeader>
          <SheetBody>{/* the task's details */}</SheetBody>
        </SheetContent>
      </Sheet>
    </>
  )
}
```

The id button is itself something interactive in the row, so the guard also keeps it from opening the sheet twice. The `closest` match is checked against the row, so a table that sits inside a focusable element or a `[role="tab"]` panel doesn't swallow every row click. The sheet is a modal dialog: it traps focus, closes on Escape and returns focus to the element that had it, which is the id button when the keyboard opened it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### The kit's parts

| Part | Does |
| --- | --- |
| `useDataTable` | TanStack's `useTable` with the kit's features. |
| `createDataTableColumnHelper` | A column helper that types each column's `meta`: `label`, `numeric`, `align`, `grow`, `filter`, `editor`, `skeleton`, `exportValue`. |
| `DataTableColumnHeader` | A header cell (a `<th>`): its label sorts the column (Shift adds it to the sort), a chevron, a right-click or Alt+↓ open its menu (sort, pin, move, hide), and its edge resizes it. |
| `DataTableToolbar` | The row above a table: search and filters at the start, `actions` at the end, each side wrapping on its own. |
| `DataTableSearch` | A search over every column, after a short pause (Enter at once), with / to focus it from anywhere. |
| `DataTableColumnFilter` | The filter a column declares in `meta.filter`: `DataTableFacetedFilter` (values with counts), `DataTableDateRangeFilter` (presets and exact days) or `DataTableNumberRangeFilter` (a two-thumb slider and exact bounds). |
| `DataTableFilterChips` | The filters in force as chips, from `dataTableFilterChips(table, locale)`, and Clear all. |
| `DataTableViewOptions` | The Columns menu: show and hide columns, and reset them. |
| `DataTableDensityToggle` | Compact, standard or comfortable rows. |
| `DataTablePagination` | The range in view, rows per page and the page steps, from a `table` or from values. |
| `createSelectColumn` | A checkbox column: the header's selects the page, each row's its row. |
| `DataTableSelectionBar` | The bar a selection raises over the table's lower edge, with a rolling count, Select all and your actions. |
| `DataTableConfirmAction` | A destructive action that names the count and, from three rows, asks for it to be typed. |
| `createRowActionsColumn`, `DataTableRowActions` | A row's ⋯ menu, named for its row. |
| `DataTableViews` | Saved views: named filters, sort, columns and density, saved and updated through `onViewsChange`. |
| `DataTableCellEditor` | An editor laid over its cell (text, number or select), for inline editing. |
| `useDataTableNavigation` | The ARIA grid's keyboard: one Tab stop, the arrows between cells, Home/End, PageUp/PageDown, and `onActiveChange` when the active cell moves. |
| `dataTableToCsv`, `downloadCsv` | CSV that spreadsheets read: quoted, CRLF, a BOM, and formulas defused. |

### Props

#### DataTableColumnHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `header` (required) | `Header<DataTableFeatures, TData, unknown>` |  | The TanStack header this cell draws: `headerGroup.headers[i]`. |
| `align` | `'start' \| 'center' \| 'end'` |  | Where the label sits. Default: the column's `meta.align`, else `end` for a `meta.numeric` column, else `start`. |
| `menu` | `boolean` | `true` | The column's menu (sort, pin, move, hide) behind a chevron and a right-click. |
| `menuOpen` | `boolean` |  | The menu's open state, controlled: a grid opens it from the keyboard (Alt+↓). |
| `onMenuOpenChange` | `(open: boolean) => void` |  |  |
| `showSortIndex` | `boolean` |  | Number each sorted column by its priority. Default: while more than one column is sorted. |
| `resizable` | `boolean` |  | A handle on the end edge that resizes the column (double-click resets it). Default: when the column can resize. |

Also takes the props of `ComponentProps<'th'>`.

#### DataTableToolbar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `ReactNode` |  | The controls at the end: view options, density, export, a primary action. |

Also takes the props of `ComponentProps<'div'>`.

#### DataTablePagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `table` | `DataTableInstance<TData>` |  | The table to page: its page, page count, row count and setters. Or pass the values below yourself. |
| `pageIndex` | `number` | `table?.atoms.pagination?.get()?.pageIndex ?? 0` |  |
| `pageSize` | `number` | `table?.atoms.pagination?.get()?.pageSize ?? 10` |  |
| `pageCount` | `number` | `table?.getPageCount() ?? 1` |  |
| `rowCount` | `number` | `table?.getRowCount() ?? 0` | Rows behind every page: the range line's total. |
| `pageSizeOptions` | `readonly number[]` | `PAGE_SIZES` | The rows-per-page choices. |
| `onPageChange` | `(pageIndex: number) => void` | `(index) => table?.setPageIndex(index)` |  |
| `onPageSizeChange` | `(pageSize: number) => void` | `(size) => table?.setPageSize(size)` |  |
| `noun` | `string` |  | What the rows are, for the range line: "orders". |
| `className` | `string` |  |  |

#### DataTableSelectionBar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  | How many rows are selected. The bar shows while it's above zero. |
| `total` | `number` |  | Every row the selection could reach (all pages, or the server's total), for "Select all 1,204 orders". |
| `canSelectAll` | `boolean` | `false` | The page is fully selected and more rows exist beyond it: offer every row. |
| `onSelectAll` | `() => void` |  |  |
| `onClear` (required) | `() => void` |  | Clears the selection: the ✕ button, and Escape anywhere in the bar. |
| `noun` | `string` | `"rows"` | What a row is, plural: "orders". |
| `children` | `ReactNode` |  | The selection's actions: buttons, a menu, a DataTableConfirmAction. |
| `className` | `string` |  |  |

#### DataTableConfirmAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | The action, as a verb: "Delete". |
| `count` (required) | `number` |  | How many rows it touches. |
| `noun` | `string` |  | What the rows are: "orders". |
| `icon` | `ReactNode` |  |  |
| `description` | `ReactNode` |  | What happens, in a sentence. Defaults to "This can't be undone." |
| `typeToConfirm` | `boolean` |  | Ask for the count to be typed before it runs. Default: from 3 rows. |
| `onConfirm` (required) | `() => void \| Promise<unknown>` |  | Runs the action. A promise keeps the dialog open and busy until it settles; a rejection is shown. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Sort arrow | `spring.snappy` | 0.2s, bounce 0 | turns to the new direction |
| Sort priority | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | badge in, and out on `instant` |
| Selection bar | `spring.snappy` | 0.2s, bounce 0 | rises and settles, with a rolling count |
| Selection bar leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Filter chips | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | glide in and out; the row eases open and shut |

**Reduced motion:** Every change applies at once: the arrow flips, the bar and the chips appear and leave in place, and the count changes without rolling.

### Accessibility

- `DataTableColumnHeader` is named by its label alone and reports `aria-sort` for the first sorted column. Its menu opens from the keyboard with Alt+↓, Shift+F10 or the context-menu key, and focus returns to the header when it closes.
- Each row checkbox is named for its row ("Select TSK-1041"); the header's says it selects the page and is indeterminate while some rows are.
- The selection bar is a named group, Escape inside it clears the selection, and Clear keeps its name when the bar is narrow.
- Removing a filter chip hands focus to its neighbor, or out of the row when it was the last.
- `useDataTableNavigation` makes a `role="grid"` table one Tab stop with a roving cell, the keyboard model the [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists) blocks share.

---

# Filter Chips

> Build a filter query from editable chips.

Source: https://www.youj.dev/docs/components/filter-chips

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Field, FieldDescription, FieldLabel, FilterChips } from '@youj/react'

const FIELDS = ['label', 'priority', 'assignee', 'repo']

function checkFilter(token: string) {
  const field = /^([a-z]+):\S/.exec(token)?.[1]
  if (!field) return 'Write a filter as field:value, e.g. assignee:me.'
  if (!FIELDS.includes(field)) return `There’s no ${field} filter. Try ${FIELDS.join(', ')}.`
}

export default function FilterChipsDemo() {
  const [query, setQuery] = useState(['label:bug', 'priority:in(p1,p2)'])

return (
    <Field className="w-full max-w-lg">
      <FieldLabel>Issues</FieldLabel>
      <FilterChips value={query} onValueChange={setQuery} validate={checkFilter} />
      <FieldDescription>Type assignee:me and a space. Click a chip to edit it.</FieldDescription>
    </Field>
  )
}
```

An Issues field holding the chips `label:bug` and `priority:in(p1,p2)`, with a hint to type `assignee:me` and a space.

Chips are keyed by their field (the text before the colon), so when a control changes a filter, its chip rewrites itself in place instead of leaving and coming back. Derive `value` from your filters, and parse the tokens back in `onValueChange`: the [Filter panel](https://www.youj.dev/docs/blocks/forms-and-inputs) block's order search does both.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add filter-chips
```

It brings `badge`, `collapse`, `input-group`, `presence-list`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-filter-chips`, `youj-presets`, `youj-ui-core` with it.

Use filter chips where filters also read as text: a log search, an order list, an issue tracker. Each filter is a chip like `priority:in(p1,p2)`, people who think in queries can type them, and the chips can mirror controls elsewhere on the page. For free-form values that aren't a query (topics, email domains), use a [Tag Input](https://www.youj.dev/docs/components/tag-input).

```tsx
import { Field, FieldLabel, FilterChips } from '@youj/react'

export function IssueSearch() {
  const [query, setQuery] = useState(['priority:in(p1,p2)'])
  return (
    <Field>
      <FieldLabel>Issues</FieldLabel>
      <FilterChips
        value={query}
        onValueChange={setQuery}
        validate={(token) => (/^[a-z]+:\S/.test(token) ? undefined : 'Write a filter as field:value.')}
      />
    </Field>
  )
}
```

A token ends at a space, never inside brackets or quotes, so `priority:in(p1, p2)` stays whole. A finished `field:value` becomes a chip as you type the space after it, and Enter adds whatever is typed. A pasted query adds each of its tokens. Click a chip, or focus it and press Enter, and its text returns to the field to edit.

`validate` gets the new token and the current list, and returns a reason to refuse it. A refused token stays in the field: the frame shakes, the border turns destructive, and the reason grows in under it and is read out. A duplicate isn't added; the chip that already holds it flashes.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` |  |  |
| `defaultValue` | `string[]` | `[]` |  |
| `onValueChange` | `(value: string[]) => void` |  |  |
| `validate` | `(token: string, tokens: string[]) => string \| null \| undefined \| void` |  | Returns a reason to reject a token, or nothing to accept it. `tokens` is the current list. |
| `placeholder` | `string` |  | Default: "Add a filter…" (the `queryPlaceholder` label, then `queryAddAnother` once there are chips). |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Also submits each token with a native form, under this name. |
| `id` | `string` |  |  |
| `ref` | `Ref<HTMLInputElement>` |  |  |
| `onBlur` | `() => void` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Chip enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades into its slot while the field makes room (PresenceList) |
| Chip leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades where it stands, then the rest close up |
| Chips reflow | `spring.smooth` | 0.36s, bounce 0 | glide to their new places |
| Refused | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the frame shakes a decaying 4, 3 and 2px |
| Reason | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | grows in under the field (Collapse) |
| Duplicate flash | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the chip that holds it tints at once, then fades back |

**Reduced motion:** No shake and no glide: chips appear and leave in one frame. The duplicate flash and the reason still show, because they carry the message.

#### Reduced motion

A refused token doesn't shake and chips don't glide. The flash and the reason still appear.

### Accessibility

- The field is named by its `FieldLabel`, `aria-label` or `aria-labelledby`, and the chips are a list named "Active filters". A refused token sets `aria-invalid` and is described by its reason, a `role="alert"` message.
- In the field, Backspace when it's empty, or the left arrow at its start, reaches the last chip. On a chip, the arrows move between chips, Home and End jump to the ends, Enter or F2 edits it, Backspace or Delete removes it and focus lands on its neighbor, and Escape returns to the field. Each chip describes these keys.
- Each chip's remove button is named after its filter. Additions, removals and duplicates are announced politely.
- With `name`, each token is submitted with a native form under that name.

---

# Filter Builder

> Compose AND/OR queries from typed rules, with a draft you apply.

Source: https://www.youj.dev/docs/components/filter-builder

## Examples

### Deals list

```tsx
'use client'

import { useState } from 'react'
import { Badge, FilterBuilder, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, matchFilter, type FilterGroup } from '@youj/react'
import { DEALS, DEAL_FIELDS } from './deals'

const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })

const START: FilterGroup = {
  type: 'group',
  combinator: 'and',
  children: [
    { type: 'rule', field: 'stage', operator: 'isNot', value: 'Lost' },
    {
      type: 'group',
      combinator: 'or',
      children: [
        { type: 'rule', field: 'owner', operator: 'is', value: 'Ada' },
        { type: 'rule', field: 'amount', operator: 'gt', value: 100000 },
      ],
    },
  ],
}

export default function FilterBuilderDemo() {
  const [filter, setFilter] = useState(START)
  const rows = DEALS.filter((deal) => matchFilter(deal, filter))

return (
    <div className="flex w-full max-w-3xl flex-col gap-4">
      <FilterBuilder fields={DEAL_FIELDS} value={filter} onValueChange={setFilter} />
      <div className="h-72 overflow-y-auto rounded-xl border border-line bg-surface yj-scrollbar">
        <Table aria-label={`Deals, ${rows.length} of ${DEALS.length}`}>
          <TableHeader>
            <TableRow>
              <TableHead>Deal</TableHead>
              <TableHead>Stage</TableHead>
              <TableHead>Owner</TableHead>
              <TableHead className="text-end">Amount</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {rows.map((deal) => (
              <TableRow key={deal.name}>
                <TableCell className="font-medium">{deal.name}</TableCell>
                <TableCell>
                  <Badge variant="secondary">{deal.stage}</Badge>
                </TableCell>
                <TableCell>{deal.owner}</TableCell>
                <TableCell className="text-end tabular-nums">{usd.format(deal.amount)}</TableCell>
              </TableRow>
            ))}
            {rows.length === 0 && (
              <TableRow>
                <TableCell colSpan={4} className="py-8 text-center text-fg-muted">
                  No deals match.
                </TableCell>
              </TableRow>
            )}
          </TableBody>
        </Table>
      </div>
    </div>
  )
}
```

A CRM deals list. The builder holds "Stage is not Lost and (Owner is Ada or Amount > 100000)": each rule is a sentence of tokens, and a click on one opens its menu or editor. Change a rule and press Apply, and the table narrows.

The list is filtered with `matchFilter(deal, filter)`, in the browser. The filter itself is plain JSON, so the same value can be saved with a view or sent to a server to run there.

### Nested groups

```tsx
'use client'

import { useState } from 'react'
import { FilterBuilder, type FilterField, type FilterGroup } from '@youj/react'

const FIELDS: FilterField[] = [
  { id: 'level', label: 'Level', type: 'select', options: ['debug', 'info', 'warn', 'error'] },
  { id: 'service', label: 'Service', type: 'select', options: ['api', 'billing', 'worker', 'web'] },
  { id: 'message', label: 'Message', type: 'text' },
  { id: 'duration', label: 'Duration (ms)', type: 'number' },
  { id: 'at', label: 'Logged', type: 'date' },
  { id: 'retried', label: 'Retried', type: 'boolean' },
]

const START: FilterGroup = {
  type: 'group',
  combinator: 'or',
  children: [
    { type: 'rule', field: 'level', operator: 'is', value: 'error' },
    {
      type: 'group',
      combinator: 'and',
      children: [
        { type: 'rule', field: 'service', operator: 'isAnyOf', value: ['api', 'billing'] },
        { type: 'rule', field: 'duration', operator: 'between', value: [500, 5000] },
        {
          type: 'group',
          combinator: 'or',
          children: [
            { type: 'rule', field: 'message', operator: 'contains', value: 'timeout' },
            { type: 'rule', field: 'retried', operator: 'isTrue' },
          ],
        },
      ],
    },
  ],
}

export default function FilterBuilderNested() {
  const [filter, setFilter] = useState(START)

return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <FilterBuilder fields={FIELDS} maxDepth={3} value={filter} onValueChange={setFilter} />
      <pre aria-label="Applied filter as JSON" className="max-h-48 overflow-auto rounded-lg border border-line-subtle bg-band p-3 font-mono text-ui-sm yj-scrollbar">
        {JSON.stringify(filter, (key, value) => (key === 'id' ? undefined : value))}
      </pre>
    </div>
  )
}
```

A log filter three groups deep, with the applied value shown as JSON. Each nested group hangs off a guide line with its own Where and and/or column; its menu duplicates it, ungroups it (its rules move up into the parent) or removes it.

`maxDepth` counts the outer group, so the default 2 allows one group inside it and `3` allows this. At the limit a group offers Add filter but not Add group.

### Summary

```tsx
'use client'

import { useState } from 'react'
import { Button, FilterBuilder, describeFilter, type FilterGroup } from '@youj/react'
import { DEAL_FIELDS } from './deals'

const SAVED: Array<{ name: string; filter: FilterGroup }> = [
  {
    name: 'Ada’s open deals',
    filter: {
      type: 'group',
      combinator: 'and',
      children: [
        { type: 'rule', field: 'owner', operator: 'is', value: 'Ada' },
        { type: 'rule', field: 'stage', operator: 'isAnyOf', value: ['Lead', 'Qualified', 'Proposal'] },
      ],
    },
  },
  {
    name: 'Renewals closing soon',
    filter: {
      type: 'group',
      combinator: 'and',
      children: [
        { type: 'rule', field: 'tags', operator: 'hasAny', value: ['renewal'] },
        { type: 'rule', field: 'closes', operator: 'between', value: ['2026-10-01', '2026-11-30'] },
      ],
    },
  },
  {
    name: 'Big or partner',
    filter: {
      type: 'group',
      combinator: 'or',
      children: [
        { type: 'rule', field: 'amount', operator: 'gt', value: 100000 },
        { type: 'rule', field: 'tags', operator: 'hasAny', value: ['partner'] },
      ],
    },
  },
]

export default function FilterBuilderSummary() {
  const [filter, setFilter] = useState(SAVED[0]!.filter)

return (
    <div className="flex w-full max-w-3xl flex-col gap-4">
      <ul aria-label="Saved views" className="flex flex-col divide-y divide-line-subtle rounded-lg border border-line-subtle bg-surface">
        {SAVED.map((saved) => {
          const current = describeFilter(saved.filter, DEAL_FIELDS) === describeFilter(filter, DEAL_FIELDS)
          return (
            <li key={saved.name} className="flex items-center gap-3 px-4 py-2">
              <div className="min-w-0 flex-1">
                <p className="text-ui font-medium">{saved.name}</p>
                <p className="truncate text-ui-sm text-fg-muted">{describeFilter(saved.filter, DEAL_FIELDS)}</p>
              </div>
              <Button variant="ghost" size="sm" disabled={current} onClick={() => setFilter(saved.filter)}>
                {current ? 'Applied' : 'Apply view'}
              </Button>
            </li>
          )
        })}
      </ul>
      <FilterBuilder fields={DEAL_FIELDS} value={filter} onValueChange={setFilter} />
    </div>
  )
}
```

Saved views described with `describeFilter` on their own, and the read-only summary at the top of the builder.

The summary always shows the applied filter, not the draft. "Show as chips" shows each top-level part as a chip in the rules' token style. Pass `summary={false}` to leave it out.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add filter-builder
```

It brings `button`, `dropdown-menu`, `icon-check`, `icon-ellipsis`, `icon-plus`, `icon-x`, `input`, `popover`, `presence-list`, `sliding-indicator`, `toast`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-filter-builder`, `youj-presets`, `youj-ui-core` with it.

The copy is 38 registry items, about 11,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `button`, `collapse`, `dropdown-menu`, `field`, `icon-alert-triangle`, `icon-check`, `icon-check-circle`, `icon-chevron-right`, `icon-circle-x` and 19 more.

Use a Filter Builder where people need to ask real questions of a list: analysts slicing a table, admins finding CRM records, support reading logs. For a few independent filters, use the [Data Table](https://www.youj.dev/docs/components/data-table) toolbar; to type a query as text, use [Filter Chips](https://www.youj.dev/docs/components/filter-chips).

```tsx
import { FilterBuilder, matchFilter, type FilterField, type FilterGroup } from '@youj/react'

const fields: FilterField[] = [
  { id: 'name', label: 'Deal', type: 'text' },
  { id: 'stage', label: 'Stage', type: 'select', options: ['Lead', 'Proposal', 'Won', 'Lost'] },
  { id: 'amount', label: 'Amount', type: 'number' },
  { id: 'closes', label: 'Close date', type: 'date' },
]

export function Deals({ deals }: { deals: Deal[] }) {
  const [filter, setFilter] = useState<FilterGroup>({ type: 'group', combinator: 'and', children: [] })
  return (
    <>
      <FilterBuilder fields={fields} value={filter} onValueChange={setFilter} />
      <DealTable deals={deals.filter((deal) => matchFilter(deal, filter))} />
    </>
  )
}
```

`fields` is the schema: an `id` (the key on a row), a `label`, a `type` (`text`, `number`, `date`, `select`, `multiselect` or `boolean`) and, for the two select types, `options` (strings, or `{ value, label }`). The type decides the operators and the editor:

| Type | Operators |
| --- | --- |
| `text` | is, is not, contains, starts with, is empty, is not empty |
| `number` | is, is not, is greater than, is less than, is between, is empty, is not empty |
| `date` | is, is before, is after, is between, is in the last N days, is empty, is not empty |
| `select` | is, is not, is any of, is empty, is not empty |
| `multiselect` | has any of, has all of, is empty, is not empty |
| `boolean` | is yes, is no |

The value is a `FilterGroup`: `{ type: 'group', combinator: 'and' | 'or', children }`, where a child is a rule (`{ type: 'rule', field, operator, value }`) or another group. Dates are `YYYY-MM-DD` strings. Ids are optional; the builder adds them while editing.

Each rule reads as a sentence of tokens: the field, an operator that suits its type, and the value. A click on a token opens a small menu (a search narrows a list of eight or more) or, for text, numbers and dates, a field; Enter closes it. A new rule opens its field menu, and picking a field or operator that needs a value goes on to the value. The × after a rule, or Delete on any of its tokens, removes it; with a [Toaster](https://www.youj.dev/docs/components/toast) in the app, a toast offers Undo.

`onValueChange` is called when Apply succeeds, with the draft. Reset throws the draft away. While the draft differs from the applied filter, the footer says "Changes not applied". A rule that is missing its value is flagged once it has been left, or when Apply refuses it; the first such rule takes focus.

#### Running the filter

`matchFilter(row, group)` returns whether a row passes. An empty group and a rule that isn't complete yet don't narrow anything. Text compares without case, dates by day, and numbers as numbers. For rows that aren't flat objects, pass `{ get: (row, field) => … }`; `{ now }` fixes what "in the last N days" counts back from.

`describeFilter(group, fields)` writes the filter as a sentence, such as `Stage is not Lost and (Owner is Ada or Amount > 100000)`. It takes the labels as a third argument when you need another language.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` (required) | `FilterField[]` |  | The columns a rule can filter on. |
| `value` | `FilterGroup` |  | The applied filter (controlled). The builder's draft starts from it and returns to it on Reset. |
| `defaultValue` | `FilterGroup` | `EMPTY_FILTER` | The filter applied at first (uncontrolled). |
| `onValueChange` | `(value: FilterGroup) => void` |  | Called with the draft when Apply succeeds. |
| `maxDepth` | `number` | `2` | How many levels of groups nest, the outer one counting as 1. |
| `summary` | `boolean` | `true` | Shows the applied filter as a sentence, or as chips. |
| `aria-label` | `string` | `"Filter"` | Names the outer group. |
| `disabled` | `boolean` | `false` |  |

Also takes the props of `ComponentProps<'div'>`.

#### Data attributes

The root carries `data-slot="filter-builder"` and `data-yj-dirty` while the draft differs from the applied filter. Each group is `data-slot="filter-group"` with `data-yj-depth` (the outer group is 1) and `data-yj-combinator`; its and/or token is `data-slot="filter-combinator"`. Each rule is `data-slot="filter-rule"`, with `data-invalid` while it is flagged; its tokens sit in `data-slot="filter-rule-tokens"`, each `data-slot="filter-token"` with `data-yj-token` (`field`, `operator` or `value`) and `data-popup-open` while its menu is open. The summary's chips are `data-slot="filter-builder-chip"`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Row enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | a rule or group fades in from a few px above while the rows below make room (PresenceList) |
| Row leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades where it stands, then the rest close up |
| Rows reflow | `spring.smooth` | 0.36s, bounce 0 | glide to their new places |
| Token menu opens | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | grows out of its token (yj-pop); instant when opened from the keyboard |
| Menu highlight | `spring.smooth` | 0.36s, bounce 0 | glides between options (Sliding Indicator); keyboard moves land at once |
| Remove button | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades in on hover or focus of its rule |

**Reduced motion:** Rows appear and leave in one frame, with no glide. Menus open at once and the highlight jumps.

#### Reduced motion

Nothing moves; the hint, the flags and the announcements still appear.

### Accessibility

- Every group is a `role="group"` named for its place: the outer one "Filter" (or `aria-label`), the nested ones "Group 2". Every rule is a group too ("Rule 1"). Each token is a button named for what it is and what it holds ("Field: Stage", "Operator: is not", "Value: Lost"), so it is heard with its rule; the and/or token is "Combine rules with: and".
- Tab walks it in reading order: each group's and/or token, each rule's tokens and its remove button, then Add filter, Add group (and a nested group's menu), Reset and Apply. Enter, Space or ArrowDown opens a token. Its menu is a listbox: the arrow keys, Home and End move, a letter jumps, Enter or Space picks, and a search field narrows a long list while the arrows still move. Escape closes and returns focus to the token. The remove button shows on hover and whenever its rule holds focus, and Delete or Backspace on a token removes its rule.
- Adding a rule opens its field menu. Removing a row moves focus to the next row, else the previous, else the group's Add filter, so focus is never lost to the page; Undo puts the row back and focuses it.
- Additions, removals, Apply and Reset are announced politely. A rule flagged as incomplete marks its value token `aria-invalid`, described by "Choose a value", and a refused Apply announces it and focuses the first one.
- The summary is a labelled group; in chips form it is a list.

---

# Property List

> Show a record's properties as rows of icon, label and value, each one editable.

Source: https://www.youj.dev/docs/components/property-list

## Examples

### Demo

```tsx
'use client'

import {
  BanknoteIcon,
  BarChartIcon,
  BriefcaseIcon,
  BuildingIcon,
  CalendarCheckIcon,
  CircleDashedIcon,
  CircleUserIcon,
  HashIcon,
  UserCheckIcon,
} from '@youj/icons'
import {
  PropertyAge,
  PropertyDate,
  PropertyList,
  PropertyListItem,
  PropertyMoney,
  PropertyPerson,
  PropertyProgress,
  PropertyStatus,
  PropertyTag,
  PropertyText,
} from '@youj/react'

// Pass `now` from the server so the age reads the same in the browser.
const NOW = Date.UTC(2026, 9, 5, 9, 30)
const DAY = 86_400_000

export default function PropertyListDemo() {
  return (
    <div className="w-full max-w-md rounded-xl border border-line bg-overlay p-5 shadow-sm">
      <PropertyList>
        <PropertyListItem icon={<CircleUserIcon />} label="Owner">
          <PropertyPerson name="Noor Haddad" />
        </PropertyListItem>
        <PropertyListItem icon={<BriefcaseIcon />} label="Deal">
          <PropertyText>Inference platform expansion</PropertyText>
        </PropertyListItem>
        <PropertyListItem icon={<BuildingIcon />} label="Industry">
          <PropertyTag>AI</PropertyTag>
        </PropertyListItem>
        <PropertyListItem icon={<CircleDashedIcon />} label="Stage">
          <PropertyStatus tone="warning">Proposal</PropertyStatus>
        </PropertyListItem>
        <PropertyListItem icon={<BarChartIcon />} label="Probability">
          <PropertyProgress value={62} />
        </PropertyListItem>
        <PropertyListItem icon={<CalendarCheckIcon />} label="Closes">
          <PropertyDate value="2026-11-30" />
        </PropertyListItem>
        <PropertyListItem icon={<HashIcon />} label="Age">
          <PropertyAge since={NOW - 12 * DAY} now={NOW} />
        </PropertyListItem>
        <PropertyListItem icon={<BanknoteIcon />} label="Value">
          <PropertyMoney value={324_000} />
        </PropertyListItem>
        <PropertyListItem icon={<UserCheckIcon />} label="Last edited by">
          <PropertyPerson name="Tomás Reyes" />
        </PropertyListItem>
      </PropertyList>
    </div>
  )
}
```

A deal's properties: owner, deal, industry, stage, probability, closing date, age, value and last editor, each with an icon and a label.

### Inline edit

```tsx
'use client'

import { useRef, useState, type KeyboardEvent } from 'react'
import { BanknoteIcon, BriefcaseIcon, CircleUserIcon } from '@youj/icons'
import { Input, PropertyList, PropertyListItem, PropertyMoney, PropertyPerson, PropertyText } from '@youj/react'

type Key = 'deal' | 'value'

export default function EditableProperties() {
  const [values, setValues] = useState({ deal: 'Inference platform expansion', value: '324000' })
  const [editing, setEditing] = useState<Key | null>(null)
  const rows = useRef<Partial<Record<Key, HTMLDivElement | null>>>({})
  const done = (key: Key) => {
    setEditing(null)
    // Back to the row's edit button once it is rendered again.
    requestAnimationFrame(() => rows.current[key]?.querySelector('button')?.focus())
  }

// Enter keeps the edit, Escape drops it; either way focus returns to the row's edit button.
  const field = (key: Key, label: string) => (
    <Input
      autoFocus
      aria-label={label}
      defaultValue={values[key]}
      inputMode={key === 'value' ? 'numeric' : undefined}
      className="h-control-sm"
      onBlur={() => setEditing(null)}
      onKeyDown={(event: KeyboardEvent<HTMLInputElement>) => {
        if (event.key === 'Enter') setValues((v) => ({ ...v, [key]: event.currentTarget.value }))
        if (event.key === 'Enter' || event.key === 'Escape') done(key)
      }}
    />
  )

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-overlay p-5 shadow-sm">
      <PropertyList>
        <PropertyListItem icon={<CircleUserIcon />} label="Owner">
          <PropertyPerson name="Noor Haddad" />
        </PropertyListItem>
        <PropertyListItem ref={(el) => void (rows.current.deal = el)} icon={<BriefcaseIcon />} label="Deal" onEdit={editing ? undefined : () => setEditing('deal')}>
          {editing === 'deal' ? field('deal', 'Deal') : <PropertyText>{values.deal}</PropertyText>}
        </PropertyListItem>
        <PropertyListItem ref={(el) => void (rows.current.value = el)} icon={<BanknoteIcon />} label="Value" onEdit={editing ? undefined : () => setEditing('value')}>
          {editing === 'value' ? field('value', 'Value') : <PropertyMoney value={Number(values.value) || 0} />}
        </PropertyListItem>
      </PropertyList>
    </div>
  )
}
```

A deal's properties where an editable row turns into an input in place.

`onEdit` puts an edit button at the end of the row. It shows while the row is hovered or holds focus, and always on touch. What editing means is yours: in the preview, the value turns into a field in place, and Enter keeps it.

The button is in the tab order wherever it is, named "Edit Deal", so a keyboard reaches it like any other control. When the edit ends, send focus back to it.

### Side by side

```tsx
'use client'

import { PropertyList, PropertyListItem, PropertyPerson, PropertyStatus, PropertyTag } from '@youj/react'

export default function PropertyListSideBySide() {
  return (
    <div className="w-64 rounded-xl border border-line bg-surface p-3">
      <PropertyList stack={false} className="[--property-label-width:5.5rem]">
        <PropertyListItem label="Assignee">
          <PropertyPerson name="Mei Tanaka" />
        </PropertyListItem>
        <PropertyListItem label="Status">
          <PropertyStatus tone="success">Shipped</PropertyStatus>
        </PropertyListItem>
        <PropertyListItem label="Label">
          <PropertyTag>Design</PropertyTag>
        </PropertyListItem>
      </PropertyList>
    </div>
  )
}
```

A narrow panel of short properties that keeps each label beside its value.

Below 20rem of its own width a property list stacks each label above its value. `stack={false}` keeps them side by side at any width: right for a narrow side panel of short values (a person, a status, a tag). Narrow the label column to fit with `--property-label-width`.

```tsx
<PropertyList stack={false} className="[--property-label-width:5.5rem]">
```

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add property-list
```

It brings `avatar`, `badge`, `button`, `icon-pencil`, `progress`, `use-now`, `youj-core`, `youj-labels-property-list`, `youj-presets`, `youj-ui-core` with it.

The copy is 17 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `badge`, `button`, `icon-engine`, `icon-loader-ring`, `icon-pencil`, `icon-x`, `progress`, `spinner`, `use-now`.

Use a property list for the fields of one record in a detail panel or a drawer: a deal's owner, stage and value, a ticket's assignee and priority, a file's size and dates. Each row is an icon, a label and a value, and the value is any node. Helpers lay out the common kinds and format them in the app's locale. For many records side by side, use a [data table](https://www.youj.dev/docs/blocks/tables-and-lists). For a form people fill in from scratch, use [Field](https://www.youj.dev/docs/components/field).

```tsx
import { BanknoteIcon, CircleDashedIcon, CircleUserIcon } from '@youj/icons'
import { PropertyList, PropertyListItem, PropertyMoney, PropertyPerson, PropertyStatus } from '@youj/react'

export function DealProperties({ deal }: { deal: Deal }) {
  return (
    <PropertyList>
      <PropertyListItem icon={<CircleUserIcon />} label="Owner">
        <PropertyPerson name={deal.owner.name} src={deal.owner.avatar} />
      </PropertyListItem>
      <PropertyListItem icon={<CircleDashedIcon />} label="Stage">
        <PropertyStatus tone="warning">Proposal</PropertyStatus>
      </PropertyListItem>
      <PropertyListItem icon={<BanknoteIcon />} label="Value">
        <PropertyMoney value={deal.value} currency="USD" />
      </PropertyListItem>
    </PropertyList>
  )
}
```

The label column is 9rem wide and every value starts after it. Set `--property-label-width` on the list (`className="[--property-label-width:--spacing(28)]"`) for shorter or longer labels. A long value truncates on one line; `PropertyText` shows the full text on hover. When the list is narrower than 20rem, each label sits above its value.

| Helper | Shows |
|---|---|
| `PropertyPerson` | an avatar (a photo, or the initials) and the name |
| `PropertyTag` | a quiet Badge; any Badge `variant` passes through |
| `PropertyStatus` | a colored dot and its label; `tone` is `neutral`, `accent`, `success`, `warning`, `danger` or a chart tone |
| `PropertyProgress` | a bar and its percent, named by the row's label |
| `PropertyDate` | a date in a `<time>`; `format` takes `Intl.DateTimeFormat` options |
| `PropertyMoney` | an amount in its `currency`, whole amounts without cents |
| `PropertyAge` | how long since `since`: "12 days", "3 months", "2 years" |
| `PropertyText` | text that truncates |

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### PropertyList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stack` | `boolean` | `true` | Below 20rem of its own width, each row stacks its label above its value. `false` keeps them side by side at any width. |

Also takes the props of `ComponentProps<'dl'>`.

#### PropertyListItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | The label's icon, drawn muted at 16px. |
| `label` (required) | `string` |  | What the value is: "Owner", "Stage". |
| `children` | `ReactNode` |  | The value: text or one of the Property* helpers. |
| `onEdit` | `() => void` |  | Shows an edit button on the row, named "Edit <label>". |

Also takes the props of `ComponentProps<'div'>`.

`PropertyList` is a `dl` and takes its props. `PropertyAge` takes `since` and `now`; pass `now` from the server so the text is the same after hydration. `PropertyDate`, `PropertyMoney` and `PropertyAge` take `locale`, defaulting to the app's.

### Accessibility

- It is a description list: each row is a `dt` and its `dd`, so a screen reader reads every label with its value.
- Icons and the status dot are decorative (`aria-hidden`). The label and the status text carry the meaning.
- `PropertyProgress` is a `progressbar` named by its row's label, with its value as text.
- Edit buttons are named "Edit" and the row's label (`editProperty` in `YoujProvider`'s labels), and stay in the tab order while hidden, showing as soon as they take focus.

---

# Action List

> List what needs doing, one row each, with why, by when and the action that fixes it.

Source: https://www.youj.dev/docs/components/action-list

## Examples

### Demo

```tsx
'use client'

import { CalendarIcon, ChevronRightIcon, CreditCardIcon, ShieldAlertIcon, UsersIcon } from '@youj/icons'
import { ActionList, ActionListItem, Button } from '@youj/react'

export default function ActionListDemo() {
  return (
    <ActionList
      className="w-full max-w-xl rounded-2xl border border-line bg-surface p-5"
      title="Waiting on you"
      count={9}
      headingLevel={2}
      description="From the last 30 days of usage and billing, most urgent first."
      action={
        <Button variant="ghost" size="sm" className="text-fg-muted">
          View all <ChevronRightIcon size={14} className="rtl:-scale-x-100" />
        </Button>
      }
    >
      <ActionListItem
        key="cert"
        icon={<ShieldAlertIcon />}
        tone="danger"
        title="Signing certificate expires soon"
        detail="Webhooks stop verifying when it lapses."
        meta={
          <>
            <CalendarIcon /> Nov 2
          </>
        }
        action={
          <Button variant="secondary" size="sm">
            Rotate key
          </Button>
        }
      />
      <ActionListItem
        key="seats"
        icon={<UsersIcon />}
        tone="warning"
        title="Three seats over the plan"
        detail="Design added three editors; the plan includes 25."
        meta="+€87 / mo"
        action={
          <Button variant="secondary" size="sm">
            Review seats
          </Button>
        }
      />
      <ActionListItem
        key="card"
        icon={<CreditCardIcon />}
        tone="info"
        title="Card on file ends this month"
        detail="Update it before the October invoice."
        meta="Oct 28"
        action={
          <Button variant="secondary" size="sm">
            Update card
          </Button>
        }
      />
    </ActionList>
  )
}
```

A workspace's open problems, most urgent first: each row says why, carries the date or amount that makes it urgent, and offers the one fix.

### Emphasis

```tsx
'use client'

import { KeyIcon, TimerIcon, UserPlusIcon } from '@youj/icons'
import { ActionList, ActionListItem, Button } from '@youj/react'

export default function ActionListSteps() {
  return (
    <ActionList className="w-full max-w-sm rounded-2xl border border-line bg-surface p-4" title="Finish setting up">
      <ActionListItem
        key="keys"
        emphasis
        tone="accent"
        icon={<KeyIcon />}
        title="Create a production key"
        detail="Test keys stop working at launch."
        meta="Do first"
        action={<Button size="sm">Create</Button>}
      />
      <ActionListItem
        key="alert"
        icon={<TimerIcon />}
        title="Set a spend alert"
        detail="So a runaway job pages someone."
        action={
          <Button variant="ghost" size="sm">
            Set
          </Button>
        }
      />
      <ActionListItem
        key="team"
        icon={<UserPlusIcon />}
        title="Invite your on-call"
        detail="Incidents need an owner first."
        action={
          <Button variant="ghost" size="sm">
            Invite
          </Button>
        }
      />
    </ActionList>
  )
}
```

Setup steps with the first set apart as the one to do now.

`emphasis` draws a row as a tinted panel in its `tone`, with the icon on a plain tile. Use it for one row at most: the point is that one thing comes first.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add action-list
```

It brings `presence-list`, `youj-ui-core` with it.

Use an action list where a screen asks someone to do things: alerts that need a decision, setup steps, renewals coming due, reviews waiting. Each row is an icon tile, a title, one line of detail, an optional chip and the row's own action. For a stream of events that only informs, use a [Notification Center](https://www.youj.dev/docs/components/notification-center); for one record's fields, a [Property List](https://www.youj.dev/docs/components/property-list).

```tsx
import { CalendarIcon, ShieldAlertIcon } from '@youj/icons'
import { ActionList, ActionListItem, Button } from '@youj/react'

<ActionList title="Waiting on you" count={9} action={<Button variant="ghost" size="sm">View all</Button>}>
  {alerts.map((alert) => (
    <ActionListItem
      key={alert.id}
      icon={<ShieldAlertIcon />}
      tone="danger"
      title={alert.title}
      detail={alert.detail}
      meta={<><CalendarIcon /> {alert.due}</>}
      action={<Button variant="secondary" size="sm" onClick={() => resolve(alert.id)}>Resolve</Button>}
    />
  ))}
</ActionList>
```

`tone` colors the icon tile (`neutral`, `accent`, `info`, `success`, `warning` or `danger`); the chip takes the same tone unless you pass `metaTone`. `count` sits in a chip beside the title and can be larger than the rows you show, with the header `action` linking to the rest. Key every row by a stable id: the rows are a [PresenceList](https://www.youj.dev/docs/motion/presence-list), so removing one when it is done fades it out and closes the gap.

Below 20rem of its own width, the chip and the action wrap under the text instead of squeezing it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | What the list is: "Waiting on you". Names the section. |
| `description` | `ReactNode` |  | A muted line under the title: where the rows came from, how they're sorted. |
| `count` | `number` |  | How many there are, in a chip beside the title. It can be more than the rows shown. |
| `action` | `ReactNode` |  | At the end of the header: a "View all" link or button. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | The title's heading level. |
| `children` | `ReactNode` |  | ActionListItems, each keyed by a stable id. |

Also takes the props of `ComponentProps<'section'>`.

#### ActionListItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | The row's icon, drawn in a tile in the row's tone. |
| `tone` | `'neutral' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | The tile's (and, with `emphasis`, the row's) tone. |
| `title` (required) | `ReactNode` |  | What to act on: "Contract renews in 12 days". |
| `detail` | `ReactNode` |  | One line of why: who, how much, by when. |
| `meta` | `ReactNode` |  | A chip before the action: the date, amount or state that makes it urgent. Text, optionally led by a small icon. |
| `metaTone` | `'neutral' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` |  | The chip's tone. Default: the row's. |
| `action` | `ReactNode` |  | At the row's end: the row's own action, usually a small Button. |
| `emphasis` | `boolean` | `false` | Sets this row apart as the one to do first: a tinted panel in its tone. |

Also takes the props of `ComponentProps<'li'>`.

### Styling

Parts: `action-list`, `action-list-header`, `action-list-title`, `action-list-count`, `action-list-description`, `action-list-action`, `action-list-items`, `action-list-item` (with `data-tone` and `data-variant`: `default` or `emphasis`), `action-list-icon`, `action-list-item-title`, `action-list-item-detail`, `action-list-meta` (with `data-tone`) and `action-list-item-action`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Row added | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | drops in and fades up |
| Row removed | `duration.fast`, `ease.exit`, `spring.smooth` | 140ms; cubic-bezier(0.4, 0, 1, 1); 0.36s, bounce 0 | fades out; the rows below close the gap |

**Reduced motion:** Rows come and go at once.

#### Reduced motion

Rows are added and removed at once, with no fade or slide.

### Accessibility

- With a `title` it is a `section` named by its heading (`headingLevel`, 3 by default), so it is a landmark region; the rows are a list.
- The icon tile is decorative (`aria-hidden`); the title and detail carry the meaning, and the chip is plain text.
- Name each row's action for what it does ("Rotate key", not "Go"), since a screen reader may reach it out of its row.
- A row on its way out is inert, so focus can't land on it.

---

# Breakdown List

> Show how a total splits: each part's color, name, value and share, keyed to a split bar.

Source: https://www.youj.dev/docs/components/breakdown-list

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { BreakdownList, ShareBar, type BreakdownItem } from '@youj/react'

const CHANNELS: BreakdownItem[] = [
  { label: 'Direct', value: 61_420, tone: 'neutral' },
  { label: 'Partners', value: 38_960 },
  { label: 'Marketplace', value: 21_310 },
  { label: 'Resellers', value: 9_840 },
  { label: 'Other', value: 4_150 },
]
const EUR: Intl.NumberFormatOptions = { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 }

export default function BreakdownListDemo() {
  const [active, setActive] = useState<number | null>(null)
  return (
    <section className="flex w-full max-w-sm flex-col gap-4 rounded-2xl border border-line bg-surface p-5">
      <div className="flex flex-col gap-0.5">
        <span className="text-ui-sm text-fg-muted">Bookings by channel, this quarter</span>
        <span className="font-mono text-2xl font-semibold tracking-tight tabular-nums">€135,680</span>
      </div>
      <ShareBar parts={CHANNELS.map((c) => ({ value: c.value, tone: c.tone }))} active={active} className="h-2" />
      <BreakdownList items={CHANNELS} format={EUR} active={active} onActiveChange={setActive} aria-label="Bookings by channel" />
    </section>
  )
}
```

Bookings by channel under a split Share Bar. Point at a row, or move focus onto it, and its segment lights.

### Two columns

```tsx
'use client'

import { useState } from 'react'
import { BreakdownList, ShareBar, type BreakdownItem } from '@youj/react'

const ACCOUNTS: BreakdownItem[] = [
  { label: 'Money market', detail: 'Northbank ·· 4410', value: 1_920_000, tone: 'success' },
  { label: 'Operating', detail: 'Ledgerline ·· 0182', value: 486_000, tone: 'chart-2' },
  { label: 'Reserve', detail: 'Northbank ·· 7731', value: 702_000, tone: 'chart-4' },
  { label: 'Payroll', detail: 'Ledgerline ·· 2209', value: 268_000, tone: 'warning' },
  { label: 'EU operating', detail: 'Kantor ·· 5520', value: 421_000, tone: 'danger' },
  { label: 'Collections', detail: 'Northbank ·· 9034', value: 133_000, tone: 'neutral' },
]

export default function BreakdownListColumns() {
  const [active, setActive] = useState<number | null>(null)
  return (
    <section className="flex w-full max-w-2xl flex-col gap-4 rounded-2xl border border-line bg-surface p-5">
      <div className="flex items-baseline gap-2">
        <span className="font-mono text-2xl font-semibold tracking-tight tabular-nums">$3.93M</span>
        <span className="text-ui-sm text-fg-muted">across six accounts</span>
      </div>
      <ShareBar parts={ACCOUNTS.map((a) => ({ value: a.value, tone: a.tone }))} active={active} className="h-2.5" />
      <BreakdownList
        items={ACCOUNTS}
        format={{ style: 'currency', currency: 'USD', notation: 'compact', maximumFractionDigits: 2 }}
        marker="bar"
        columns={2}
        active={active}
        onActiveChange={setActive}
        aria-label="Cash by account"
      />
    </section>
  )
}
```

Six accounts in two columns, each with a bar marker and a line of detail.

`columns={2}` sets the rows side by side while each column can be 14rem wide; narrower, they stack in one column. `marker="bar"` draws each marker as a bar the row's height, which reads better beside a two-line row.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add breakdown-list
```

It brings `share-bar`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a breakdown list as the key to a split bar: revenue by category, cash by account, seats by status. Each row is a color marker, a name, a value and its share of the total. For a few parts inside a stat tile use [StatBreakdown](https://www.youj.dev/docs/components/stat-card); for one row's share of a whole, a [Share Bar](https://www.youj.dev/docs/components/share-bar) on its own.

```tsx
import { useState } from 'react'
import { BreakdownList, ShareBar } from '@youj/react'

const [active, setActive] = useState<number | null>(null)

<ShareBar parts={channels.map((c) => ({ value: c.value }))} active={active} />
<BreakdownList items={channels} format={{ style: 'currency', currency: 'EUR' }} active={active} onActiveChange={setActive} />
```

Both take the chart colors in order, so give them the same items and the rows match the segments without naming a tone; a `tone` on an item (the accent, a status, a chart color or `neutral`) colors both when you pass it to both. Shares are out of the items' sum, or your `total`. `variant="tiles"` leads each row with its value in a small panel, for counts; `showShare={false}` drops the percentages.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly BreakdownItem[]` |  |  |
| `total` | `number` |  | What each share is out of. Default: the items' sum. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the values. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `variant` | `'rows' \| 'tiles'` | `'rows'` | `rows` (default) on hairlines, value at the end; `tiles` lead with the value, for counts. |
| `marker` | `'swatch' \| 'bar'` | `'swatch'` | The marker's shape: a square swatch (default) or a bar the row's height. |
| `columns` | `1 \| 2` | `1` | Rows side by side while each column can be 14rem wide. |
| `showShare` | `boolean` | `true` | Show each part's share of the total. |
| `active` | `number \| null` |  | The pointed-at part, controlled. |
| `onActiveChange` | `(index: number \| null) => void` |  | Called with the row hovered or focused, and `null` when the pointer and focus leave. |

Also takes the props of `ComponentProps<'ul'>`.

### Styling

Parts: `breakdown-list` (with `data-variant`: `rows` or `tiles`), `breakdown-list-item` (with `data-index`, and `data-state` `active` or `inactive` while a row is pointed at), `breakdown-list-marker`, `breakdown-list-label`, `breakdown-list-detail`, `breakdown-list-value` and `breakdown-list-share`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Point at a row | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the row takes the hover panel; the paired bar’s other parts quiet |

**Reduced motion:** The same: a color change, nothing moves.

#### Reduced motion

Nothing moves: pointing only changes colors.

### Accessibility

- It is a list; each row reads its name, detail, value and share in order. Name the list with `aria-label` when nothing visible names it.
- The rows are one tab stop. The arrow keys, Home and End move between them, and focus makes a row the active one, so a keyboard lights the bar's segments as a pointer does. Focus leaving the list clears it.
- The markers are decorative (`aria-hidden`); the name says which part is which.

---

# Contribution List

> Explain how a figure got from where it started to where it lands, one signed step per row.

Source: https://www.youj.dev/docs/components/contribution-list

## Examples

### Demo

```tsx
'use client'

import { GlobeIcon, MegaphoneIcon, TagIcon, UsersIcon } from '@youj/icons'
import { ContributionList } from '@youj/react'

export default function ContributionListDemo() {
  return (
    <ContributionList
      className="w-full max-w-lg rounded-2xl border border-line bg-surface p-2"
      aria-label="What moves next week’s signups"
      baseline={{ label: 'A normal week', value: 1_840 }}
      items={[
        { icon: <MegaphoneIcon />, label: 'Launch post', detail: 'Goes out Tuesday to 48k subscribers', value: 310 },
        { icon: <UsersIcon />, label: 'Referral credit', detail: 'Doubled for the week', value: 145 },
        { icon: <GlobeIcon />, label: 'New region', detail: 'Checkout opens in Brazil on Thursday', value: 90 },
        { icon: <TagIcon />, label: 'Price change', detail: 'Starter goes from €9 to €12', value: -120 },
      ]}
      total={{ label: 'Expected next week', detail: 'Range 2,180 to 2,340' }}
    />
  )
}
```

Why next week's signups differ from a normal week: each driver, the line of why, and how many it adds or takes away.

### Falls are good

```tsx
'use client'

import { CloudIcon, CpuIcon, DatabaseIcon, PackageIcon } from '@youj/icons'
import { ContributionList } from '@youj/react'

export default function ContributionListInvert() {
  return (
    <ContributionList
      className="w-full max-w-lg rounded-2xl border border-line bg-surface p-2"
      aria-label="October cost bridge"
      invert
      format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}
      baseline={{ label: 'September bill', value: 18_420 }}
      items={[
        { icon: <CpuIcon />, label: 'Reserved instances', detail: 'Committed for a year from Oct 1', value: -3_150 },
        { icon: <DatabaseIcon />, label: 'Database growth', detail: 'Two read replicas added', value: 1_280 },
        { icon: <CloudIcon />, label: 'Egress', detail: 'Video exports doubled', value: 940 },
        { icon: <PackageIcon />, label: 'Retired staging', detail: 'Three idle clusters removed', value: -1_610 },
      ]}
      total={{ label: 'October forecast' }}
    />
  )
}
```

A cost bridge from one month's bill to the next, where `invert` lights the savings in the good ink.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add contribution-list
```

It brings `youj-core`, `youj-presets`, `youj-ui-core` with it.

Use a contribution list to explain a figure: a forecast against a typical week, this month's bill against last month's, a score against its target. It is a waterfall chart told as a list: the baseline, each step with its sign, and the total, highlighted. For one value against another use a [Diff Bar](https://www.youj.dev/docs/components/diff-bar); for how a total splits into parts, a [Breakdown List](https://www.youj.dev/docs/components/breakdown-list).

```tsx
import { MegaphoneIcon, TagIcon } from '@youj/icons'
import { ContributionList, runningTotals } from '@youj/react'

<ContributionList
  baseline={{ label: 'A normal week', value: 1840 }}
  items={[
    { icon: <MegaphoneIcon />, label: 'Launch post', detail: 'Goes out Tuesday', value: 310 },
    { icon: <TagIcon />, label: 'Price change', detail: 'Starter goes to €12', value: -120 },
  ]}
  total={{ label: 'Expected next week' }}
/>

runningTotals(1840, [{ value: 310 }, { value: -120 }]) // [1840, 2150, 2030]
```

The total's value is never passed: it is the baseline plus every step, so the list always adds up. `runningTotals` gives the same numbers for a headline elsewhere on the page. `format` and `locale` set how every figure reads; the steps always carry their sign.

Beside each value a thin mark shares one scale, from the lowest running total to the highest: the baseline and the total are ticks at their place, and each step is a bar from where the figure was to where it went. Rises take the good ink and falls the bad one; `invert` swaps them where a fall is good news, as with costs. `marks={false}` drops them, and they hide on their own below 28rem.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `baseline` (required) | `ContributionEnd & { value: number }` |  | Where the figure starts: its label and value. |
| `items` (required) | `readonly ContributionStep[]` |  | The steps, in the order they're applied. |
| `total` (required) | `ContributionEnd` |  | The landing row's label. Its value is the baseline plus every step. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for every figure; steps always show their sign. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `invert` | `boolean` | `false` | A fall is good news (costs, latency): falls take the good ink, rises the bad. |
| `marks` | `boolean` | `true` | The waterfall marks beside the values. |

Also takes the props of `ComponentProps<'ol'>`.

### Styling

Parts: `contribution-list`, `contribution-list-baseline`, `contribution-list-item` (with `data-direction`: `up`, `down` or `flat`), `contribution-list-icon`, `contribution-list-label`, `contribution-list-detail`, `contribution-list-mark`, `contribution-list-step`, `contribution-list-value` and `contribution-list-total`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | each step’s bar grows from where the figure was, one after another down the list, once a third of the list is in view |

**Reduced motion:** Drawn at once.

#### Reduced motion

The bars are drawn at their size from the start.

### Accessibility

- It is an ordered list read top to bottom: the baseline, each step with its signed value, then the total. Name it with `aria-label` when no heading does.
- The icons and the marks are decorative (`aria-hidden`); the label, detail and signed value carry the meaning.
- The bars grow from the inline start's side of the scale, so the marks mirror in RTL.

---

# Tree View

> Browse and manage nested data with selection, lazy loading and inline renaming.

Source: https://www.youj.dev/docs/components/tree-view

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Copy, FilePlus, Pencil, Trash2 } from 'lucide-react'
import { ContextMenuItem, ContextMenuSeparator, ContextMenuShortcut, TreeFileIcon, TreeView, type TreeNode } from '@youj/react'

const dir = (id: string, children: TreeNode[]): TreeNode => ({ id, name: id.split('/').pop()!, children })
const file = (id: string, extra: Partial<TreeNode> = {}): TreeNode => ({ id, name: id.split('/').pop()!, ...extra })
const modified = { meta: 'M', description: 'modified' }

const PROJECT: TreeNode[] = [
  dir('src', [
    dir('src/components', [
      dir('src/components/board', [file('src/components/board/board.tsx', modified), file('src/components/board/column.tsx'), file('src/components/board/card.tsx')]),
      file('src/components/sidebar.tsx'),
    ]),
    dir('src/hooks', [file('src/hooks/use-sprint.ts'), file('src/hooks/use-keyboard.ts')]),
    file('src/app.tsx', modified),
    file('src/main.tsx'),
  ]),
  dir('public', [file('public/logo.svg'), file('public/og.png')]),
  // A lazy branch: its children load on first open.
  { id: 'node_modules', name: 'node_modules', hasChildren: true },
  file('package.json'),
  file('README.md'),
]

function update(nodes: TreeNode[], id: string, change: (node: TreeNode) => TreeNode | null): TreeNode[] {
  return nodes.flatMap((node) => {
    if (node.id === id) {
      const next = change(node)
      return next ? [next] : []
    }
    return node.children ? [{ ...node, children: update(node.children, id, change) }] : [node]
  })
}

export default function FileExplorer() {
  const [data, setData] = useState(PROJECT)
  const [opened, setOpened] = useState<TreeNode | null>(null)

return (
    <div className="flex w-full max-w-lg flex-col overflow-hidden rounded-xl border border-line bg-surface sm:flex-row">
      <TreeView
        aria-label="Files"
        data={data}
        defaultExpanded={['src', 'src/components', 'src/components/board']}
        defaultSelected={['src/app.tsx']}
        onAction={setOpened}
        loadChildren={(node) =>
          new Promise((resolve) =>
            setTimeout(() => {
              const packages = ['react', 'motion', '@base-ui'].map((pkg) => dir(`${node.id}/${pkg}`, [file(`${node.id}/${pkg}/package.json`)]))
              setData((d) => update(d, node.id, (n) => ({ ...n, children: packages })))
              resolve(null)
            }, 900),
          )
        }
        onRename={(node, name) => setData((d) => update(d, node.id, (n) => ({ ...n, name })))}
        contextMenu={(node, { rename }) => (
          <>
            <ContextMenuItem onClick={() => setOpened(node)} disabled={node.children !== undefined || node.hasChildren}>
              <FilePlus /> Open
            </ContextMenuItem>
            <ContextMenuItem onClick={rename}>
              <Pencil /> Rename <ContextMenuShortcut>F2</ContextMenuShortcut>
            </ContextMenuItem>
            <ContextMenuItem onClick={() => navigator.clipboard?.writeText(node.id)}>
              <Copy /> Copy path
            </ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem variant="danger" onClick={() => setData((d) => update(d, node.id, () => null))}>
              <Trash2 /> Delete
            </ContextMenuItem>
          </>
        )}
        className="shrink-0 border-b border-line p-1.5 sm:w-56 sm:border-e sm:border-b-0"
      />
      <div className="grid min-w-0 flex-1 place-items-center p-4 text-center text-ui-sm text-fg-muted">
        {opened ? (
          <span className="flex items-center gap-2 text-fg">
            <TreeFileIcon name={opened.name} />
            {opened.id}
          </span>
        ) : (
          'Double-click a file, or press Enter, to open it.'
        )}
      </div>
    </div>
  )
}
```

A file explorer: a project tree with a detail pane, rename, a context menu and packages that load on first open.

In the demo, a click selects and a double click or Enter opens a file through `onAction`. With `onRename`, F2 renames the focused node in place: Enter keeps the new name and Escape drops it. `contextMenu` gives every node a menu, on right-click or Shift+F10, and hands you a `rename` action for it. `node_modules` is lazy: it loads its children the first time it opens.

### Checkbox trees

```tsx
'use client'

import { useState } from 'react'
import { TreeView, type TreeNode } from '@youj/react'

const FOLDERS: TreeNode[] = [
  dir('Workspace', [
    dir('Workspace/Design', [file('Workspace/Design/Brand.fig'), file('Workspace/Design/Icons.fig'), file('Workspace/Design/Motion.fig')]),
    dir('Workspace/Docs', [file('Workspace/Docs/Roadmap.md'), file('Workspace/Docs/Handbook.md')]),
  ]),
  dir('Archive', [file('Archive/2024.txt'), file('Archive/2025.txt', { disabled: true, description: 'locked' })]),
]

const isFile = (id: string) => /\.\w+$/.test(id)

export default function SyncPicker() {
  const [selected, setSelected] = useState<string[]>(['Workspace/Design/Brand.fig', 'Workspace/Docs', 'Workspace/Docs/Roadmap.md', 'Workspace/Docs/Handbook.md'])
  const files = selected.filter(isFile).length
  return (
    <div className="w-full max-w-xs rounded-xl border border-line bg-surface p-2">
      <p className="px-2 pt-1 pb-2 text-ui font-medium text-fg">Choose folders to sync</p>
      <TreeView
        aria-label="Folders to sync"
        data={FOLDERS}
        selectionMode="multiple"
        selected={selected}
        onSelectedChange={setSelected}
        defaultExpanded={['Workspace', 'Workspace/Design']}
      />
      <p className="px-2 pt-2 text-ui-sm text-fg-muted tabular-nums">
        {files} {files === 1 ? 'file' : 'files'} selected
      </p>
    </div>
  )
}
```

A folder picker for syncing, with checkboxes that show a mixed state and a count of selected files.

`selectionMode="multiple"` turns the tree into a checkbox tree. Checking a folder checks everything loaded inside it, and a folder shows mixed when only some of its contents are chosen. Disabled nodes can't be checked themselves.

`selected` then holds every checked id, folders included, so count the leaves when you report a total.

### Lazy branches

```tsx
'use client'

import { useRef, useState } from 'react'
import { TreeView, type TreeNode } from '@youj/react'

function withChildren(nodes: TreeNode[], id: string, children: TreeNode[]): TreeNode[] {
  return nodes.map((n) => (n.id === id ? { ...n, children } : n.children ? { ...n, children: withChildren(n.children, id, children) } : n))
}

/* `packages` loads on first open. `flaky` fails the first time and leaves a
 * retry row; Enter on it tries again, and the second try succeeds. */
export default function LazyTree() {
  const [data, setData] = useState<TreeNode[]>([
    { id: 'packages', name: 'packages', hasChildren: true },
    { id: 'flaky', name: 'flaky', hasChildren: true },
  ])
  const failed = useRef(false)

const load = (node: TreeNode) =>
    new Promise((resolve, reject) =>
      setTimeout(() => {
        if (node.id === 'flaky' && !failed.current) {
          failed.current = true
          reject(new Error('Offline'))
          return
        }
        const children = ['motion', 'ui', 'icons'].map((name) => ({ id: `${node.id}/${name}`, name, hasChildren: true }))
        setData((d) => withChildren(d, node.id, children))
        resolve(null)
      }, 1100),
    )

return (
    <div className="w-full max-w-xs rounded-xl border border-line bg-surface p-2">
      <TreeView aria-label="Repository" data={data} loadChildren={load} />
    </div>
  )
}
```

Two branches that load their children on first open; the flaky one fails once and shows a retry row.

Give a node `hasChildren` and no `children`, and pass `loadChildren`. The first time the branch opens, the tree shows a loading row and calls it. Put the children into `data` and resolve. If the promise rejects, a retry row takes the place of the children; Enter on it tries again. In this preview `flaky` fails once.

### Large trees

```tsx
'use client'

import { useMemo } from 'react'
import { TreeView, type TreeNode } from '@youj/react'

export default function VirtualTree() {
  // 100 folders of 100 files: ten thousand rows, only the ones in view rendered.
  const data = useMemo<TreeNode[]>(
    () =>
      Array.from({ length: 100 }, (_, i) => ({
        id: `dir-${i}`,
        name: `dir-${i}`,
        children: Array.from({ length: 100 }, (_, j) => {
          const name = `file-${String(j).padStart(3, '0')}.ts`
          return { id: `dir-${i}/${name}`, name }
        }),
      })),
    [],
  )
  const expanded = useMemo(() => data.map((d) => d.id), [data])

return (
    <div className="w-full max-w-xs rounded-xl border border-line bg-surface p-1.5">
      <TreeView aria-label="Generated files" data={data} defaultExpanded={expanded} virtual className="h-80" />
    </div>
  )
}
```

A tree of 100 folders with 100 files each, all open, windowed to the rows in view.

`virtual` windows the rows, for trees of thousands of items: only the rows in view are in the page, and the one the keyboard lands on scrolls into view. Give the tree a height.

The virtual tree is a flat list of rows that carry their level, position and set size, so branches open instantly rather than animating their height.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tree-view
```

It brings `checkbox`, `collapse`, `context-menu`, `icon-chevron-right`, `icon-file`, `icon-file-code`, `icon-file-json`, `icon-file-terminal`, `icon-file-text`, `icon-folder`, `icon-image`, `icon-palette`, `input`, `spinner`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-tree-view`, `youj-presets`, `youj-ui-core` with it.

The copy is 31 registry items, about 10,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `checkbox`, `collapse`, `context-menu`, `dropdown-menu`, `field`, `icon-check`, `icon-chevron-right`, `icon-engine`, `icon-file`, `icon-file-code` and 15 more.

Use a tree view for a hierarchy people browse and act on: files in a project, pages in a site, folders to sync, categories and their items. It's a WAI-ARIA tree with one Tab stop and the full keyboard model. For two levels of links in an app's navigation, use a [Sidebar](https://www.youj.dev/docs/components/sidebar). For sections of content that open and close, use an [Accordion](https://www.youj.dev/docs/components/accordion).

```tsx
import { TreeView, type TreeNode } from '@youj/react'

const files: TreeNode[] = [
  {
    id: 'src',
    name: 'src',
    children: [
      { id: 'src/app.tsx', name: 'app.tsx' },
      { id: 'src/main.tsx', name: 'main.tsx' },
    ],
  },
  { id: 'package.json', name: 'package.json' },
]

export function Files() {
  return <TreeView aria-label="Files" data={files} defaultExpanded={['src']} onAction={(node) => openFile(node.id)} />
}
```

A node with `children` is a branch, and one without is a leaf. Folders get icons that open with them and files get icons by type; set `icons={false}` for a plain tree, or give a node its own `icon`. `meta` puts a status letter or a count at the end of the row. It's decorative, so say the same thing in `description`, which is read after the name.

Selection and open branches can each be controlled (`selected`, `expanded`) or left to the tree (`defaultSelected`, `defaultExpanded`).

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `TreeNode[]` |  |  |
| `expanded` | `string[]` |  | Open branches. |
| `defaultExpanded` | `string[]` | `[]` |  |
| `onExpandedChange` | `(ids: string[]) => void` |  |  |
| `selectionMode` | `'single' \| 'multiple'` | `'single'` | `single` selects one item; `multiple` is a checkbox tree with tri-state branches. |
| `selected` | `string[]` |  |  |
| `defaultSelected` | `string[]` | `[]` |  |
| `onSelectedChange` | `(ids: string[]) => void` |  |  |
| `onAction` | `(node: TreeNode) => void` |  | Enter or double-click on a leaf: open the file. |
| `loadChildren` | `(node: TreeNode) => Promise<unknown>` |  | Loads a lazy branch's children. Resolve once `data` holds them; reject to show a retry row. |
| `onRename` | `(node: TreeNode, name: string) => void` |  | Enables F2 / inline rename. Called with the trimmed new name when it changed. |
| `contextMenu` | `(node: TreeNode, actions: TreeViewContextActions) => ReactNode` |  | Context-menu items for a node (ContextMenuItem and friends). |
| `icons` | `boolean` | `true` | File-explorer icons: folders that open, files by type. |
| `virtual` | `boolean` | `false` | Window the rows for large trees. Give the tree a height. |

Also takes the props of `ComponentProps<'ul'>`.

A node (`TreeNode`) has an `id` and a `name`, and optionally `children`, `hasChildren` for a lazy branch, an `icon`, `meta`, a `description` and `disabled`. `TreeFileIcon` and `TreeFolderIcon` are the tree's icons, for use beside it, as the editor tabs in a file explorer would.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Branch opens | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height to auto and opacity (Collapse); closing mid-open reverses from where it is |
| Branch closes | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height on `base`, opacity out on `fast` |
| Chevron |  |  | turns a quarter as the branch opens |
| Folder |  |  | its front panel tips open with the branch |
| Row hover and selection | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | background |

**Reduced motion:** Branches open and close instantly, and the chevron and folder switch state without turning.

#### Reduced motion

Branches appear and disappear at once, with no height animation, and the chevron and folder show their new state without turning or tipping. Everything else, including the loading row and the announcements, is the same.

### Accessibility

- It's a `tree` of `treeitem`s, named by `aria-label`, with `aria-expanded` on branches and `aria-level`, `aria-posinset` and `aria-setsize` on every item.
- One Tab stop: the focused item carries `tabIndex={0}` and the rest `-1`, so Tab moves past the tree in one step.
- Single selection uses `aria-selected`. The checkbox tree uses `aria-checked`, `mixed` included. Disabled items are `aria-disabled`.
- A loading branch is `aria-busy`, and loads are announced: "Loading node_modules", then "node_modules loaded" or "Couldn't load node_modules". Renames are announced too.

| Key | Does |
| --- | --- |
| ↑ ↓ | Move between visible items. |
| → | Opens a closed branch, or moves into an open one. Flipped under right-to-left text. |
| ← | Closes an open branch, or moves out to the parent. |
| Home / End | The first or last visible item. |
| * | Opens every sibling branch. |
| Typing | Jumps to the next item whose name starts with the letters typed. |
| Enter | Opens a file (`onAction`) or toggles a folder. Retries a failed load. |
| Space | Selects the item, or checks it in a checkbox tree. |
| F2 | Renames it, with `onRename`. |
| Shift+F10 | Opens its context menu, with `contextMenu`. |

---

# Sortable List

> Reorder a list by dragging or using the keyboard, with each move announced.

Source: https://www.youj.dev/docs/components/sortable-list

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Badge, SortableList, SortableListHandle, SortableListItem } from '@youj/react'

const PRIORITIES = [
  { id: 'auth', title: 'Passkey sign-in', team: 'Identity' },
  { id: 'billing', title: 'Usage-based billing', team: 'Growth' },
  { id: 'audit', title: 'Audit log export', team: 'Platform' },
  { id: 'search', title: 'Search across workspaces', team: 'Core' },
  { id: 'mobile', title: 'Offline mode on mobile', team: 'Mobile' },
]
const byId = new Map(PRIORITIES.map((p) => [p.id, p]))

export default function SortableListDemo() {
  const [order, setOrder] = useState(PRIORITIES.map((p) => p.id))
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <h2 id="priorities" className="px-1 text-ui-lg font-semibold text-fg">
        Q4 priorities
      </h2>
      <SortableList aria-labelledby="priorities" value={order} onValueChange={setOrder} className="[counter-reset:rank]">
        {order.map((id) => {
          const item = byId.get(id)!
          return (
            <SortableListItem key={id} value={id} textValue={item.title} className="[counter-increment:rank]">
              <SortableListHandle />
              {/* A CSS counter, so the rank follows the row while it's lifted. */}
              <span aria-hidden className="w-4 text-end text-ui-sm text-fg-muted tabular-nums before:content-[counter(rank)]" />
              <span className="min-w-0 flex-1 truncate font-medium">{item.title}</span>
              <Badge variant="secondary">{item.team}</Badge>
            </SortableListItem>
          )
        })}
      </SortableList>
    </div>
  )
}
```

Q4 priorities as a ranked list: each row has a drag handle, a rank counter and a team badge.

### Whole row

```tsx
'use client'

import { SortableList, SortableListItem } from '@youj/react'

const SONGS = ['Intro', 'Midnight City', 'Kids', 'Wait', 'Outro']

export default function SortableListWholeRow() {
  return (
    <SortableList aria-label="Playlist" className="w-full max-w-xs gap-1" onValueChange={(order) => console.log(order)}>
      {SONGS.map((song) => (
        <SortableListItem key={song} value={song} asHandle>
          <span className="flex-1 px-1">{song}</span>
        </SortableListItem>
      ))}
    </SortableList>
  )
}
```

A playlist where the whole row is the handle.

With `asHandle`, the row is its own grip: it takes focus, and a drag can start anywhere on it except its buttons, links and fields. Use it for short rows with nothing else to press. Rows with actions keep a separate `SortableListHandle`, so a press on an action never starts a drag.

On touch screens, a handle doesn't scroll the page, so a list whose rows are all handles can't be scrolled by swiping over it. Prefer a grip in long lists.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add sortable-list
```

It brings `icon-grip`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-sortable-list`, `youj-presets`, `youj-ui-core` with it.

Use a sortable list when the order itself is the data: priorities, a playlist, the steps of a pipeline, the columns of a table. The list owns dragging, focus and announcements; you render what's inside each row. When items also move between groups, use a [Kanban](https://www.youj.dev/docs/components/kanban) board. When people sort by a field rather than by hand, use a [data table](https://www.youj.dev/docs/blocks/tables-and-lists).

Each item has a `value`, and the list's value is those values in order. Control it with `value` and `onValueChange`, and render the items in that order.

```tsx
import { useState } from 'react'
import { SortableList, SortableListHandle, SortableListItem } from '@youj/react'

export function Priorities({ items }: { items: { id: string; title: string }[] }) {
  const [order, setOrder] = useState(items.map((i) => i.id))
  const byId = new Map(items.map((i) => [i.id, i]))
  return (
    <SortableList aria-label="Priorities" value={order} onValueChange={setOrder}>
      {order.map((id) => (
        <SortableListItem key={id} value={id} textValue={byId.get(id)!.title}>
          <SortableListHandle />
          {byId.get(id)!.title}
        </SortableListItem>
      ))}
    </SortableList>
  )
}
```

`onValueChange` fires once, when a row is dropped somewhere new. It doesn't fire on each step of a drag or when a move is canceled, so it's a safe place to save. Without `value`, the list keeps its own order, starting from `defaultValue` or the children's order.

Give each item a `textValue`. Announcements use it ("Picked up Audit log export, position 3 of 5."), and so does the handle's name ("Reorder Audit log export"). Without one, announcements read the row's text.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### SortableList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` |  | The items' values in order (controlled). |
| `defaultValue` | `string[]` |  | The starting order when uncontrolled. Default: the children's order. |
| `onValueChange` | `(value: string[]) => void` |  | Called with the new order when a row is dropped somewhere new. |
| `disabled` | `boolean` | `false` | Turn reordering off; the rows stay as a plain list. |
| `aria-label` | `string` |  | Names the list for assistive tech. |
| `children` | `ReactNode` |  |  |

Also takes the props of `ComponentProps<'ul'>`.

#### SortableListItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  | This item's id in the list's value. |
| `textValue` | `string` |  | What announcements call this item. Default: its text. |
| `asHandle` | `boolean` | `false` | The whole row is the handle: it takes focus and starts a drag from anywhere on it. |

Also takes the props of `ComponentProps<'li'>`.

#### SortableListHandle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Names the handle. Default: "Reorder" plus the item's `textValue`. |

Also takes the props of `ComponentProps<'button'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Neighbors make room | `spring.smooth` | 0.36s, bounce 0 | rows glide aside as the dragged row passes them, and on each keyboard step |
| Drop | `spring.smooth` | 0.36s, bounce 0 | the row settles into its slot from wherever the pointer let go |
| Grip | `spring.snappy` | 0.2s, bounce 0 | its dots fuse into bars while the row is held |
| Lift | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the row scales to 1.015 and gains a shadow and a ring-colored border |

**Reduced motion:** Rows jump to their new places and the lifted row doesn't scale. A pointer drag still follows the pointer.

The dragged row stays in the list (a drag on the row itself with `layout` on its neighbors, the same motion layer the [Kanban](https://www.youj.dev/docs/components/kanban) board uses, not motion's `Reorder`), so screen readers and the DOM order always agree with what's on screen.

#### Reduced motion

Rows move to their new places at once, keyboard moves included, and the lifted row doesn't scale. Dragging with a pointer still follows the pointer, because that movement is the person's own.

### Accessibility

- The list is a `list` of `listitem`s. Name it with `aria-label` or `aria-labelledby`.
- The handles are a single tab stop. `↑` and `↓` move focus between them, and `Home` and `End` jump to the first and last.
- `Space` or `Enter` picks the focused row up. While it's lifted, `↑` and `↓` move it one place, `Home` and `End` move it to either end, `Space` or `Enter` drops it, and `Escape` puts it back. Moving focus away also puts it back.
- A handle is a `<button>` with `aria-pressed` while its row is lifted, and describes these keys through `aria-describedby`.
- A polite live region announces each pick-up, move, drop and cancel with the row's position.
- `Escape` also cancels a pointer drag: the row settles back into its old slot.

---

# Kanban

> Organize cards into columns with drag and keyboard controls, work-in-progress limits and swimlanes.

Source: https://www.youj.dev/docs/components/kanban

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ArrowRight, ArrowUp, Equal, SignalHigh, Trash2 } from 'lucide-react'
import {
  Avatar,
  AvatarFallback,
  Badge,
  ContextMenuItem,
  ContextMenuSeparator,
  Kanban,
  type KanbanCardData,
  type KanbanColumn,
} from '@youj/react'

interface Issue extends KanbanCardData {
  key: string
  priority: 'urgent' | 'high' | 'medium'
  label: string
  assignee: string
}

const COLUMNS: KanbanColumn[] = [
  { id: 'todo', title: 'To do', tone: 'accent' },
  { id: 'doing', title: 'In progress', tone: 'warning', limit: 3 },
  { id: 'review', title: 'In review', tone: 'accent', limit: 2 },
  { id: 'done', title: 'Done', tone: 'success' },
]

const issue = (key: string, column: string, title: string, rest: Partial<Issue> = {}): Issue => ({
  id: key,
  key,
  column,
  title,
  priority: 'medium',
  label: 'Feature',
  assignee: 'LH',
  ...rest,
})

const ISSUES: Issue[] = [
  issue('ENG-188', 'todo', 'Fix login redirect loop on Safari', { priority: 'urgent', label: 'Bug', assignee: 'AR' }),
  issue('ENG-192', 'todo', 'Keyboard shortcuts cheat sheet'),
  issue('ENG-205', 'todo', 'Migrate cron jobs to the queue', { label: 'Infra', assignee: 'JO' }),
  issue('ENG-176', 'doing', 'Inline editing for issue titles', { priority: 'high', assignee: 'MK' }),
  issue('ENG-181', 'doing', 'Dark mode for charts', { label: 'Design', assignee: 'AR' }),
  issue('ENG-170', 'review', 'Bulk-assign from the list view', { assignee: 'LH' }),
  issue('ENG-163', 'done', 'Onboarding checklist', { label: 'Growth', assignee: 'MK' }),
]

const PRIORITY = {
  urgent: { Icon: ArrowUp, label: 'Urgent', className: 'text-danger-text' },
  high: { Icon: SignalHigh, label: 'High priority', className: 'text-warning-text' },
  medium: { Icon: Equal, label: 'Medium priority', className: 'text-fg-muted' },
}

const TONE = { Bug: 'danger', Feature: 'default', Design: 'secondary', Infra: 'warning', Growth: 'success' } as const

/** The inside of a card. The board draws the card itself: its surface, focus ring and drag handling. */
function IssueCard({ issue }: { issue: Issue }) {
  const priority = PRIORITY[issue.priority]
  return (
    <>
      <div className="flex items-center gap-1.5 px-(--card-spacing) text-ui-sm text-fg-muted">
        <priority.Icon aria-label={priority.label} className={`size-3.5 ${priority.className}`} />
        <span className="font-mono tabular-nums">{issue.key}</span>
        <Avatar size="sm" className="ms-auto size-5">
          <AvatarFallback className="text-[10px]">{issue.assignee}</AvatarFallback>
        </Avatar>
      </div>
      <p className="px-(--card-spacing) text-ui leading-snug font-medium text-fg">{issue.title}</p>
      <div className="px-(--card-spacing)">
        <Badge variant={TONE[issue.label as keyof typeof TONE] ?? 'secondary'}>{issue.label}</Badge>
      </div>
    </>
  )
}

export default function SprintBoard() {
  const [cards, setCards] = useState(ISSUES)

const add = ({ column }: { column: string }, title: string) =>
    setCards((list) => {
      const key = `ENG-${230 + list.length}`
      return [...list, issue(key, column, title)]
    })

return (
    <div className="flex h-[480px] w-full flex-col">
      <Kanban
        aria-label="Sprint 24"
        columns={COLUMNS}
        cards={cards}
        renderCard={(card) => <IssueCard issue={card} />}
        onMove={(_, next) => setCards(next)}
        onAddCard={add}
        cardMenu={(card) => (
          <>
            <ContextMenuItem onClick={() => setCards((list) => [...list.filter((c) => c.id !== card.id), { ...card, column: 'done' }])}>
              <ArrowRight /> Move to Done
            </ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem variant="danger" onClick={() => setCards((list) => list.filter((c) => c.id !== card.id))}>
              <Trash2 /> Delete
            </ContextMenuItem>
          </>
        )}
        className="min-h-0 flex-1"
      />
    </div>
  )
}
```

A sprint board of issue cards you drag between columns, with an add-card control and a context menu on each card.

Press a card and move it 4px, or press and hold on touch, and it lifts out of the list into a tilted preview under the pointer. A dashed gap opens where it will land and the cards around it glide aside. Near the edge of the board, or of a long column, it scrolls. Release and the card settles into the gap; Escape puts it back.

From the keyboard the cards are one Tab stop, and the arrow keys walk them. Space picks the focused card up, the arrows move it between positions and columns, and Space or Enter drops it. Every step is announced, as "Picked up Fix login. To do, position 2 of 5."

The demo shows the rest of a column's kit. In progress has a WIP limit of 3: carry a fourth card over it and the count turns to a warning while you hover. `onAddCard` adds a composer at the foot of each column, `cardMenu` gives each card a context menu (right-click, or Shift+F10), and a column's collapse button folds it to a narrow rail. `defaultCollapsed` or a controlled `collapsed` sets which columns start folded.

### Swimlanes

```tsx
'use client'

import { useState } from 'react'
import { Badge, Kanban, type KanbanCardData, type KanbanColumn, type KanbanLane } from '@youj/react'

interface Task extends KanbanCardData {
  points: number
}

const COLUMNS: KanbanColumn[] = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress', limit: 2 },
  { id: 'done', title: 'Done', tone: 'success' },
]

const LANES: KanbanLane[] = [
  { id: 'web', title: 'Web' },
  { id: 'platform', title: 'Platform' },
]

const TASKS: Task[] = [
  { id: 't1', column: 'todo', lane: 'web', title: 'Empty states for settings', points: 3 },
  { id: 't2', column: 'doing', lane: 'web', title: 'Inline title editing', points: 2 },
  { id: 't3', column: 'done', lane: 'web', title: 'Onboarding checklist', points: 3 },
  { id: 't4', column: 'todo', lane: 'platform', title: 'Rate-limit search API', points: 5 },
  { id: 't5', column: 'doing', lane: 'platform', title: 'Stream deploy logs', points: 8 },
  { id: 't6', column: 'done', lane: 'platform', title: 'Postgres 17 upgrade', points: 5 },
]

export default function KanbanSwimlanes() {
  const [cards, setCards] = useState(TASKS)
  return (
    <div className="w-full">
      <Kanban
        aria-label="Sprint 24 by team"
        columns={COLUMNS}
        lanes={LANES}
        cards={cards}
        renderCard={(card) => (
          <div className="flex items-start gap-2 px-(--card-spacing)">
            <p className="flex-1 text-ui leading-snug font-medium text-fg">{card.title}</p>
            <Badge variant="secondary" className="tabular-nums" aria-label={`${card.points} points`}>
              {card.points}
            </Badge>
          </div>
        )}
        onMove={(_, next) => setCards(next)}
      />
    </div>
  )
}
```

A sprint board split into team lanes, each card carrying a points badge.

`lanes` splits the board into rows, one per team or project, and each card's `lane` places it. A move can cross lanes as well as columns. From the keyboard, the up and down arrows step into the next lane at the top and bottom of a cell.

### Selection and people

```tsx
'use client'

import { useState, type KeyboardEvent, type MouseEvent } from 'react'
import { Avatar, AvatarFallback, Kanban, type KanbanCardData, type KanbanColumn, type KanbanLane } from '@youj/react'

const COLUMNS: KanbanColumn[] = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress', limit: 2 },
  { id: 'done', title: 'Done', tone: 'success' },
]

const PEOPLE = [
  { id: 'mk', name: 'Mira Kovac', initials: 'MK' },
  { id: 'jo', name: 'Jonas Ortiz', initials: 'JO' },
  { id: 'sn', name: 'Sana Noor', initials: 'SN' },
]

// A lane per person: an avatar and a name, with `label` naming it in words.
const LANES: KanbanLane[] = PEOPLE.map((person) => ({
  id: person.id,
  label: person.name,
  title: (
    <span className="flex items-center gap-2">
      <Avatar size="sm">
        <AvatarFallback>{person.initials}</AvatarFallback>
      </Avatar>
      {person.name}
    </span>
  ),
}))

// Sana has nothing assigned, so `hideEmptyLanes` leaves her lane out.
const TASKS: KanbanCardData[] = [
  { id: 't1', column: 'todo', lane: 'mk', title: 'Empty states for settings' },
  { id: 't2', column: 'doing', lane: 'mk', title: 'Inline title editing' },
  { id: 't3', column: 'done', lane: 'mk', title: 'Onboarding checklist' },
  { id: 't4', column: 'todo', lane: 'jo', title: 'Rate-limit search API' },
  { id: 't5', column: 'doing', lane: 'jo', title: 'Stream deploy logs' },
]

export default function KanbanSelection() {
  const [cards, setCards] = useState(TASKS)
  const [selected, setSelected] = useState<string[]>([])
  // Click or Enter selects one card; with Shift, ⌘ or Ctrl it adds or removes one.
  const select = (card: KanbanCardData, event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) => {
    const adding = event.shiftKey || event.metaKey || event.ctrlKey
    setSelected((ids) => (adding ? (ids.includes(card.id) ? ids.filter((id) => id !== card.id) : [...ids, card.id]) : [card.id]))
  }
  return (
    <div className="flex w-full flex-col gap-2">
      <p className="text-ui-sm text-fg-muted" aria-live="polite">
        {selected.length} selected
      </p>
      <Kanban
        aria-label="Assignments"
        columns={COLUMNS}
        lanes={LANES}
        hideEmptyLanes
        snap
        cards={cards}
        selectedIds={selected}
        onCardAction={select}
        renderCard={(card) => <p className="px-(--card-spacing) text-ui leading-snug font-medium text-fg">{card.title}</p>}
        onMove={(_, next) => setCards(next)}
      />
    </div>
  )
}
```

A board with a lane per person (an avatar and a name), where a click or Enter selects a card and Shift, ⌘ or Ctrl adds to the selection.

The selection is the app's: keep the ids in state and pass them as `selectedIds`. The board draws those cards selected (the selection fill and an accent edge), adds "selected" to each one's accessible name, and passes `selected` to `renderCard`. `onCardAction` receives the click or the Enter key's event as its second argument, so its modifier keys (`shiftKey`, `metaKey`, `ctrlKey`) decide whether to replace the selection or add to it.

A lane's `title` takes a node, so a person's lane can show their avatar; give it a `label` too, the name in words, for its landmark and the announcements. `hideEmptyLanes` leaves out a lane with no cards (here Sana Noor's), and `snap` makes a swipe land a column at the board's start edge, for phones.

### Saving moves

```tsx
'use client'

import { useState } from 'react'
import { Kanban, Label, Switch, type KanbanCardData, type KanbanColumn, type KanbanMove } from '@youj/react'

const COLUMNS: KanbanColumn[] = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress' },
  { id: 'done', title: 'Done', tone: 'success' },
]

const CARDS: KanbanCardData[] = [
  { id: 'c1', column: 'todo', title: 'Fix login redirect loop' },
  { id: 'c2', column: 'todo', title: 'Keyboard shortcuts sheet' },
  { id: 'c3', column: 'doing', title: 'Dark mode for charts' },
  { id: 'c4', column: 'done', title: 'Onboarding checklist' },
]

export default function KanbanOptimistic() {
  const [cards, setCards] = useState(CARDS)
  const [fail, setFail] = useState(true)

// The board shows the move at once. A rejected promise puts the card back, and says so.
  const save = (_move: KanbanMove, next: KanbanCardData[]) =>
    new Promise<void>((resolve, reject) =>
      setTimeout(() => {
        if (fail) reject(new Error('Conflict'))
        else {
          setCards(next)
          resolve()
        }
      }, 700),
    )

return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex items-center gap-2 px-3">
        <Switch id="kanban-fail" checked={fail} onCheckedChange={setFail} />
        <Label htmlFor="kanban-fail">Fail saves</Label>
      </div>
      <Kanban
        aria-label="Sprint 24"
        columns={COLUMNS}
        cards={cards}
        renderCard={(card) => <p className="px-(--card-spacing) text-ui leading-snug font-medium text-fg">{card.title}</p>}
        onMove={save}
      />
    </div>
  )
}
```

A board whose moves save after 700 ms; the Fail saves switch makes the save reject with a conflict.

Return a promise from `onMove`. The board shows the move at once, and if the promise rejects it puts the card back where it was and says so: "Couldn't move Fix login. It's back in To do." Turn Fail saves off to let the moves stick.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add kanban
```

It brings `badge`, `button`, `card`, `context-menu`, `icon-chevrons-left-right`, `icon-plus`, `icon-sidebar`, `input`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-kanban`, `youj-presets`, `youj-ui-core` with it.

The copy is 31 registry items, about 10,800 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `badge`, `button`, `card`, `collapse`, `context-menu`, `dropdown-menu`, `field`, `icon-check`, `icon-chevron-right`, `icon-chevrons-left-right` and 14 more.

Use a kanban board when work moves through stages and people move it themselves: issues through a sprint, deals through a pipeline, content through review. The board owns the card's surface, focus and dragging; you render what's inside each card. For a read-only list of stages, a [Stepper](https://www.youj.dev/docs/components/stepper) or a [Timeline](https://www.youj.dev/docs/components/timeline) says it with less. For items people sort and filter rather than drag, use a [data table](https://www.youj.dev/docs/blocks/tables-and-lists).

Cards are one flat list, and each names its `column`. A card's position is its order among the cards of its column. `onMove` hands you the move and the whole next list.

```tsx
import { useState } from 'react'
import { Kanban, type KanbanCardData, type KanbanColumn } from '@youj/react'

const columns: KanbanColumn[] = [
  { id: 'todo', title: 'To do' },
  { id: 'doing', title: 'In progress', limit: 3 },
  { id: 'done', title: 'Done', tone: 'success' },
]

export function Board({ initial }: { initial: KanbanCardData[] }) {
  const [cards, setCards] = useState(initial)
  return (
    <Kanban
      aria-label="Sprint 24"
      columns={columns}
      cards={cards}
      renderCard={(card) => <p className="px-(--card-spacing) font-medium">{card.title}</p>}
      onMove={(_, next) => setCards(next)}
    />
  )
}
```

Each card needs an `id`, a `column` and a `title`. The title is what the board announces, so extend `KanbanCardData` with whatever else your cards show. Inside `renderCard`, pad content with `px-(--card-spacing)` so it lines up with the card's own padding.

### Column width and the space beside a sidebar

A column is 18rem wide and never narrower; the board scrolls sideways when its columns don't fit. `fill` lets the columns grow to share any width left over, but it never shrinks them, so five columns need about 92rem (18rem each plus the gaps), and beside a 16rem sidebar the board scrolls below about 110rem of window. That is deliberate: a card narrower than 18rem wraps its title and crowds its badges. To fit more on screen, fold the columns people rarely drag into (Backlog, Done) to 44px rails with `defaultCollapsed`, or split the board with `lanes`. On a phone, `snap` makes the sideways scroll stop at each column.

```tsx
<Kanban fill snap defaultCollapsed={['backlog', 'done']} /* … */ />
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `KanbanColumn[]` |  |  |
| `cards` (required) | `C[]` |  |  |
| `lanes` | `KanbanLane[]` |  | Swimlanes: each card's `lane` names one. |
| `hideEmptyLanes` | `boolean` |  | Hides a lane while it has no cards (the lane a card is leaving stays until the move lands). |
| `renderCard` (required) | `(card: C, state: { lifted: boolean; selected: boolean }) => ReactNode` |  | The inside of a card. The Card itself (surface, focus, drag, the selected look) is the board's. |
| `onMove` | `(move: KanbanMove<C>, next: C[]) => unknown` |  | A card moved. Return a promise to have the board roll the move back if it rejects. |
| `onAddCard` | `(place: { column: string; lane?: string }, title: string) => void` |  | Enables the add-card composer at the foot of each column. |
| `onCardAction` | `(card: C, event: ReactMouseEvent<HTMLElement> \| KeyboardEvent<HTMLElement>) => void` |  | Enter, or a click, on a card. The event carries its modifier keys (Shift, ⌘/Ctrl), for selecting several. |
| `selectedIds` | `ReadonlyArray<string>` |  | The cards the app has selected: the board draws them selected and tells assistive tech. Selection is the app's (see onCardAction). |
| `cardMenu` | `(card: C) => ReactNode` |  | Context-menu items for a card. |
| `collapsed` | `string[]` |  |  |
| `defaultCollapsed` | `string[]` | `[]` |  |
| `onCollapsedChange` | `(ids: string[]) => void` |  |  |
| `fill` | `boolean` |  | Columns grow to share the board's width, each at least its usual 18rem. A collapsed one still folds to a rail. |
| `snap` | `boolean` |  | Horizontal scrolling snaps a column to the board's start edge: for phones, where one column fills the view. Off while a card is dragged. |

Also takes the props of `ComponentProps<'div'>`.

A column (`KanbanColumn`) has an `id`, a `title`, and optionally a WIP `limit` and a `tone` for the dot beside its title. A lane (`KanbanLane`) has an `id`, a `title` (a string or a node) and a `label`, its name in words when the title isn't a string.

`renderCard` receives the card and its state: `lifted` (picked up or dragged) and `selected` (in `selectedIds`).

| Attribute | On | Means |
| --- | --- | --- |
| `data-lifted` | a card | picked up from the keyboard |
| `data-selected` | a card | in `selectedIds` |
| `data-dragging` | the board | a card is being dragged |
| `data-fill`, `data-yj-snap` | the board, its scroller | `fill`, `snap` |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lift | `spring.snappy` | 0.2s, bounce 0 | the preview scales to 1.04 and tilts 2.5°, with a deeper shadow |
| Cards make room | `spring.smooth` | 0.36s, bounce 0 | the cards around the gap glide aside (`layout`) |
| Drop | `spring.smooth` | 0.36s, bounce 0 | the preview settles into the gap, level and at rest size |
| Keyboard move | `spring.smooth` | 0.36s, bounce 0 | the lifted card glides from its old slot to the new one |
| Keyboard lift | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the focused card scales to 1.02 and takes the ring color |
| Column folds | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | width, to a rail and back |

**Reduced motion:** No lift, tilt or scale, and no gliding: a moved card appears in its new place and the others step aside at once.

#### Reduced motion

Cards don't lift or tilt. A dragged card still follows the pointer, but the gap and the cards around it change at once, and on release, or from the keyboard, the card appears in its new place. The announcements are the same.

### Accessibility

- The board is a group with `aria-roledescription="board"`, named by `aria-label`. Columns and lanes are named regions, and each column is a list.
- Cards are buttons with `aria-roledescription="draggable card"`, described by instructions on how to move them. A lifted card is `aria-pressed`. A selected card says so at the end of its name ("Fix login, selected"); the app's own count of the selection belongs in a live region, as the Selection example's is.
- Every pick-up, move, drop, cancel and rollback is announced politely, with the column and the position.
- Column counts are named, including the limit when there is one, and the collapse buttons say which column they fold.

| Key | Does |
| --- | --- |
| Tab | Moves to the board's cards, as one stop. |
| ← → ↑ ↓ | Walk the cards. With a card lifted, move it. Left and right follow the reading direction. |
| Home / End | The first or last card in the column. |
| Space | Picks the card up, or drops it. |
| Enter | Drops a lifted card, or runs `onCardAction` on the focused one (with Shift, ⌘ or Ctrl in its event, to add to a selection). |
| Esc | Cancels the move and puts the card back. |
| Shift+F10 | Opens the card's menu, when there's a `cardMenu`. |

---

# Import mapper

> Bring a CSV into an app: choose a file, match its columns to your fields, fix only the rows with problems and import.

Source: https://www.youj.dev/docs/components/import-mapper

## Examples

### Import a CSV

```tsx
'use client'

import { ImportMapper } from '@youj/react'

export default function ImportMapperPage() {
  return <ImportMapper onDone={() => {}} />
}
```

Bringing a CSV of contacts or orders into the app in two screens and a result. Drop a file (or press Use sample) and you land on the mapping: the file on top, then each of its columns with a sample value and the field it goes to. Confident matches stay quiet; a guess is marked "Check", and a required field with no column says so with a picker for it. Above the button, what needs attention in plain words: Review opens a sheet with only those rows and just the wrong value to fix, or Skip them; duplicates are a question (update, skip or add as new). The button says what will happen ("Import 44 contacts") and stays off only while a required field is unmatched. The result shows what was imported and skipped, with the skipped rows to download.

### In a dialog

```tsx
'use client'

import { ImportMapper } from '@youj/react'

export default function ImportMapperDialog() {
  return (
    <ImportMapper
      variant="dialog"
      copy={{ importMapperTitle: 'Import contacts', importMapperDescription: 'Match the columns of your file to your contact fields.' }}
    />
  )
}
```

The same import in a compact card for a dialog about 500px wide. Pass `variant="dialog"` and it splits the work over two steps with one footer: the file and its columns with the field each goes to, then **Start over** or **Continue**. Continue opens what needs attention (Review and Skip them for the rows with problems, and the question about duplicates) with **Back** and the button that says what will happen. The result and the skipped rows to download are unchanged.

Continue waits while a required field has no column, and that field's picker sits right above the list. Every control in this variant is one height, and the missing field is a plain line rather than a box.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add import-mapper
```

It brings `alert`, `badge`, `button`, `card`, `collapsible`, `file-upload`, `icon-alert-triangle`, `icon-check`, `icon-file-text`, `icon-upload`, `input`, `native-select`, `progress`, `segmented-control`, `sheet`, `use-announcer`, `youj-core`, `youj-labels-import-mapper`, `youj-presets`, `youj-ui-core` with it.

The copy is 51 registry items, about 13,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `alert`, `badge`, `button`, `card`, `collapse`, `collapsible`, `dialog`, `field`, `file-upload`, `icon-alert-triangle` and 30 more.

Use an Import mapper where people bring a file of records into your app: contacts, orders, stock. For a table that only shows data, use the [Data table](https://www.youj.dev/docs/components/data-table); for the other direction, the [Export dialog](https://www.youj.dev/docs/components/export-dialog).

Describe what can be imported with `fields` (an `id`, a `label`, a `type` of `text`, `email`, `number` or `date`, `required`, and `synonyms` the matching also tries), say which one tells whether a record already exists with `keyField` (it is found for you from the first email or required field, and can be changed under More options), and pass the values of it that already exist in `existing`. Nothing leaves the browser until `onImport(rows, context)` is called with the rows to create or update (each has its `row` number, its `values` by field id and an `action`); resolve with the counts if your server's differ, reject to stop with the message shown, and report progress with `context.onProgress(done)`. Without `onImport` a short demo wait stands in, and without `fields` the card shows the demo's six contact fields.

```tsx
<ImportMapper
  fields={[
    { id: 'sku', label: 'SKU', required: true, synonyms: ['item code'] },
    { id: 'qty', label: 'Quantity', type: 'number' },
  ]}
  keyField="sku"
  existing={await loadSkus()}
  onImport={async (rows, { onProgress }) => {
    for (const [i, row] of rows.entries()) {
      await save(row)
      onProgress(i + 1)
    }
  }}
/>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2` instead of the page's `h1`, and no page around it. |
| `variant` | `'page' \| 'dialog'` | `'page'` | `page` (default): one working screen, up to 1024px wide. `dialog`: the compact version for a ~520px dialog: the file and the column list with a footer of Start over / Continue, and a second step for what needs attention before the import. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (1024px at 100% scale; 512px in the dialog variant). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<ImportMapperCopy>` |  | Any of the block's strings, to rewrite or translate. Default: the dictionary's (YoujProvider's `labels`). |
| `locale` | `string` |  | Writes counts and sizes in this locale (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `fields` | `ImportField[]` |  | The fields a CSV column can be imported as. Default: the demo's six contact fields. |
| `keyField` | `string` |  | The field that tells whether a contact already exists. Default: the first email field, else the first required field. |
| `existing` | `readonly string[]` |  | Values of the key field that already exist in your app; a row with one of them is a duplicate. Default: the demo's three, else none. |
| `maxSize` | `number` | `5 * 1024 * 1024` | The largest file, in bytes. |
| `previewRows` | `number` | `100` | The most cards a review lists at once; the counts and the import always cover every row. |
| `sample` | `boolean` |  | Offers a built-in sample file ("Use sample"). Default: true with the demo's fields, else false. |
| `reportName` | `string` | `'import-errors.csv'` | The skipped rows file's name. |
| `onDone` | `() => void` |  | Shows a Done button on the result; called when it is pressed. |
| `onImport` | `(rows: ImportRow[], context: ImportContext) => Promise<ImportResult \| void> \| ImportResult \| void` |  | Receives the rows to create or update. Resolve (optionally with the counts) when they're in; reject to stop with the message shown. Default: a short demo wait. |

Also takes the props of `ComponentProps<'section'>`.

#### The CSV reader

The reader is the component's own and follows RFC 4180: quoted values may hold the delimiter, line breaks and doubled quotes, any line ending works, a byte-order mark is dropped and blank lines are skipped. The delimiter (comma, semicolon or tab) is found for you. Rows with too many or too few values are padded or cut and listed; a quote that never closes keeps you on the drop zone with the line named. Dates are read as `2026-03-14` or as day-first or month-first with slashes; numbers may carry thousands commas.

### Labels

Every string is a core label (`importMapper…`) in every built-in language, so the provider's `locale` or `labels` (see [Internationalization](https://www.youj.dev/docs/guides/i18n)) rewrites them, and `copy` rewrites any of them for one instance. The noun in "Import 44 contacts" is `importMapperItems` (and `importMapperDuplicatesFound`), so rewrite those with `copy` for orders or SKUs. `onDone` adds a Done button to the result.

### Accessibility

- The card is a section named by its title. A screen change (file, mapping, result) crossfades and moves focus to the first thing in the new screen; in the dialog variant, Continue and Back move focus to the control that replaces them. With reduced motion the screens swap at once.
- Each column's field select is named by its column; a guessed match says "Check" in text, and a required field with no column is a status line naming it, with its own picker.
- Counts, skipped rows and the import's progress are announced in a polite live region, and a failure is shown as text.
- Review opens a sheet where each wrong value is an input with its error described on it (`aria-invalid` and `aria-describedby`).

---

# Command Palette

> Find app actions and destinations from a keyboard shortcut, with nested pages and key hints.

Source: https://www.youj.dev/docs/components/command-palette

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  ArrowRightIcon,
  CopyIcon,
  FolderIcon,
  GlobeIcon,
  LayersIcon,
  RocketIcon,
  SearchIcon,
  SettingsIcon,
  UserPlusIcon,
} from '@youj/icons'
import { Button, Kbd, KbdGroup } from '@youj/react'
import {
  CommandGroup,
  CommandItem,
  CommandPalette,
  CommandSeparator,
  CommandShortcut,
  useCommandPalette,
} from '@youj/react/command'

const PROJECTS = [
  { id: 'youj-web', domain: 'youj.io' },
  { id: 'docs', domain: 'docs.youj.io' },
  { id: 'status', domain: 'status.youj.io' },
  { id: 'api', domain: 'api.youj.io' },
]

/* Rows can live in their own components: useCommandPalette() reaches the page stack from anywhere inside. */
function ProjectRows() {
  const { push } = useCommandPalette()
  return (
    <CommandGroup heading="Projects">
      {PROJECTS.map((project) => (
        <CommandItem
          key={project.id}
          value={project.id}
          onSelect={() => push({ id: `project:${project.id}`, label: project.id, placeholder: `Do something in ${project.id}…` })}
        >
          <FolderIcon />
          {project.id}
          <span className="ms-auto font-mono text-ui-xs text-fg-muted">{project.domain}</span>
          <ArrowRightIcon className="size-3.5" />
        </CommandItem>
      ))}
    </CommandGroup>
  )
}

export default function CommandPaletteDemo() {
  const [open, setOpen] = useState(false)
  const [ran, setRan] = useState('')
  const run = (label: string) => {
    setRan(label)
    setOpen(false)
  }

return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <div className="flex h-12 items-center justify-between gap-4 rounded-xl border border-line bg-surface px-3 shadow-xs">
        <span className="text-ui font-semibold text-fg">youj</span>
        <Button variant="outline" size="sm" onClick={() => setOpen(true)} className="w-72 min-w-0 shrink justify-between text-fg-muted">
          <span className="flex min-w-0 items-center gap-2">
            <SearchIcon />
            <span className="truncate">Search or run a command…</span>
          </span>
          <KbdGroup className="max-sm:hidden">
            <Kbd>⌘</Kbd>
            <Kbd>/</Kbd>
          </KbdGroup>
        </Button>
      </div>
      <p role="status" className="h-5 px-1 text-ui-sm text-fg-muted">
        {ran ? `Ran “${ran}”` : 'Press ⌘/ (Ctrl+/ elsewhere), or use the button.'}
      </p>
      {/* ⌘K is taken by this site's search, so this palette listens for ⌘/. */}
      <CommandPalette open={open} onOpenChange={setOpen} shortcut="/">
        {({ page, push }) => {
          if (page?.id === 'projects') return <ProjectRows />
          if (page?.id.startsWith('project:')) {
            return (
              <CommandGroup heading={page.label}>
                <CommandItem onSelect={() => run(`Open ${page.label}`)}>
                  <ArrowRightIcon />
                  Open {page.label}
                </CommandItem>
                <CommandItem onSelect={() => run(`Deploy ${page.label}`)}>
                  <RocketIcon />
                  Deploy to production
                  <CommandShortcut>⌘⇧D</CommandShortcut>
                </CommandItem>
                <CommandItem onSelect={() => run(`Copy the URL of ${page.label}`)}>
                  <CopyIcon />
                  Copy production URL
                </CommandItem>
              </CommandGroup>
            )
          }
          return (
            <>
              <CommandGroup heading="Suggestions">
                <CommandItem onSelect={() => push({ id: 'projects', label: 'Projects', placeholder: 'Search projects…' })}>
                  <LayersIcon />
                  Switch project…
                  <CommandShortcut>⌘P</CommandShortcut>
                </CommandItem>
                <CommandItem onSelect={() => run('Deploy youj-web')}>
                  <RocketIcon />
                  Deploy to production
                </CommandItem>
                <CommandItem onSelect={() => run('Invite a teammate')}>
                  <UserPlusIcon />
                  Invite a teammate
                </CommandItem>
              </CommandGroup>
              <CommandSeparator />
              <CommandGroup heading="Go to">
                <CommandItem onSelect={() => run('Go to domains')}>
                  <GlobeIcon />
                  Domains
                  <CommandShortcut>G D</CommandShortcut>
                </CommandItem>
                <CommandItem onSelect={() => run('Go to settings')}>
                  <SettingsIcon />
                  Settings
                  <CommandShortcut>G S</CommandShortcut>
                </CommandItem>
              </CommandGroup>
            </>
          )
        }}
      </CommandPalette>
    </div>
  )
}
```

A palette with grouped rows, shortcuts and project rows that open a second page of actions.

### Pages

```tsx
'use client'

import { useState } from 'react'
import { ArrowRightIcon, UserIcon, UsersIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { CommandGroup, CommandItem, CommandPalette, type CommandPaletteState } from '@youj/react/command'

const ROLES = ['Owner', 'Editor', 'Viewer']
const TEAM: Record<string, string> = { 'Ana Lima': 'Owner', 'Kenji Sato': 'Editor', 'Priya Raman': 'Editor', 'Sara Lindqvist': 'Viewer' }

export default function CommandPalettePages() {
  const [open, setOpen] = useState(false)
  const [roles, setRoles] = useState(TEAM)

const rows = ({ page, push, pop }: CommandPaletteState) => {
    // Third level: a person's role. Choosing one steps back a page, to the team.
    if (page?.id.startsWith('member:')) {
      const name = page.label
      return (
        <CommandGroup heading={`Role for ${name}`}>
          {ROLES.map((role) => (
            <CommandItem
              key={role}
              value={role}
              checked={roles[name] === role}
              onSelect={() => {
                setRoles((current) => ({ ...current, [name]: role }))
                pop()
              }}
            >
              {role}
            </CommandItem>
          ))}
        </CommandGroup>
      )
    }
    if (page?.id === 'team') {
      return (
        <CommandGroup heading="Members">
          {Object.entries(roles).map(([name, role]) => (
            <CommandItem key={name} value={name} onSelect={() => push({ id: `member:${name}`, label: name, placeholder: 'Choose a role…' })}>
              <UserIcon />
              {name}
              <span className="ms-auto text-ui-sm text-fg-muted">{role}</span>
              <ArrowRightIcon className="size-3.5" />
            </CommandItem>
          ))}
        </CommandGroup>
      )
    }
    return (
      <CommandGroup heading="Workspace">
        <CommandItem onSelect={() => push({ id: 'team', label: 'Team', placeholder: 'Search members…' })}>
          <UsersIcon />
          Manage team…
        </CommandItem>
      </CommandGroup>
    )
  }

return (
    <div className="flex flex-col items-center gap-3">
      <Button variant="outline" onClick={() => setOpen(true)}>
        Manage team
      </Button>
      <p className="text-ui-sm text-fg-muted">
        {Object.entries(roles)
          .map(([name, role]) => `${name.split(' ')[0]}: ${role}`)
          .join(' · ')}
      </p>
      <CommandPalette open={open} onOpenChange={setOpen} shortcut={false}>
        {rows}
      </CommandPalette>
    </div>
  )
}
```

Choosing a team member opens a page of roles, and choosing a role steps back to the team.

A row can open a page with `push({ id, label, placeholder })`. The page's label joins a breadcrumb under the search field and names the field for screen readers. Each page starts with an empty search and its first row active. `Backspace` on an empty search, or `Escape`, steps back one page. The last `Escape` closes the palette, and the next time it opens, it starts from the first page.

Rows in their own components reach the stack with `useCommandPalette()`, which returns the same state as the render function: `page`, `pages`, `search`, `push`, `pop` and `close`. `pop()` steps back one page, and `pop(0)` returns to the first.

Here, choosing a role steps back to the team with `pop()`, so several people can be changed in one visit. `checked` on a row draws a check for the current value.

### Results as you type

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ClockIcon, FlagIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { CommandEmpty, CommandGroup, CommandItem, CommandLoading, CommandPalette } from '@youj/react/command'

const ISSUES = [
  { id: 'KIN-812', title: 'Stream search results from the edge' },
  { id: 'KIN-815', title: 'Highlight matches in search titles' },
  { id: 'KIN-821', title: 'Preview comments sync with the tracker' },
  { id: 'KIN-830', title: 'Cold starts regress on the edge runtime' },
  { id: 'KIN-844', title: 'Audit log filter for deployments' },
]

/* Stands in for a search request to your API. */
const searchIssues = (query: string) =>
  new Promise<typeof ISSUES>((resolve) =>
    setTimeout(() => resolve(ISSUES.filter((i) => `${i.id} ${i.title}`.toLowerCase().includes(query))), 550),
  )

function IssueResults({ search, onOpen }: { search: string; onOpen: (id: string) => void }) {
  const query = search.trim().toLowerCase()
  const [results, setResults] = useState<typeof ISSUES | null>(null)
  useEffect(() => {
    setResults(null)
    if (query.length < 2) return
    let live = true
    searchIssues(query).then((found) => live && setResults(found))
    return () => {
      live = false
    }
  }, [query])

if (query.length < 2) {
    return (
      <CommandGroup heading="Recent">
        {ISSUES.slice(3).map((issue) => (
          <CommandItem key={issue.id} value={issue.id} onSelect={() => onOpen(issue.id)}>
            <ClockIcon />
            <span className="shrink-0 font-mono text-ui-sm whitespace-nowrap text-fg-muted">{issue.id}</span>
            <span className="truncate">{issue.title}</span>
          </CommandItem>
        ))}
      </CommandGroup>
    )
  }
  // "No results" only once the answer is in: nothing having arrived yet isn't the same as nothing found.
  if (!results) return <CommandLoading label="Searching issues…" />
  if (results.length === 0) return <CommandEmpty>Nothing matches “{search}”.</CommandEmpty>
  return (
    <CommandGroup heading="Issues">
      {results.map((issue) => (
        <CommandItem key={issue.id} value={issue.id} onSelect={() => onOpen(issue.id)}>
          <FlagIcon />
          <span className="shrink-0 font-mono text-ui-sm whitespace-nowrap text-fg-muted">{issue.id}</span>
          <span className="truncate">{issue.title}</span>
        </CommandItem>
      ))}
    </CommandGroup>
  )
}

export default function CommandPaletteSearch() {
  const [open, setOpen] = useState(false)
  const [opened, setOpened] = useState('')

return (
    <div className="flex flex-col items-center gap-3">
      <Button variant="outline" onClick={() => setOpen(true)}>
        Search issues
      </Button>
      <p role="status" className="h-5 text-ui-sm text-fg-muted">
        {opened && `Opened ${opened}`}
      </p>
      {/* One palette per page should own a shortcut. This one opens from its button only. */}
      <CommandPalette open={open} onOpenChange={setOpen} shortcut={false} shouldFilter={false} placeholder="Search issues (try “edge”)…">
        {({ search, close }) => (
          <IssueResults
            search={search}
            onOpen={(id) => {
              setOpened(id)
              close()
            }}
          />
        )}
      </CommandPalette>
    </div>
  )
}
```

A search page that shows a loading row while it waits for issues, then the results or an empty message.

The render function receives the live `search`, so a page can fetch results as the user types. Show a `CommandLoading` row while the request runs and a `CommandEmpty` once the answer is in. Pass `shouldFilter={false}` when the results arrive already matched, or pass `search` and `onSearchChange` to control the query yourself.

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add command-palette
```

It brings `command`, `icon-chevron-right`, `kbd`, `presentation`, `youj-core`, `youj-labels-command-palette`, `youj-presets`, `youj-ui-core` with it.

The copy is 26 registry items, about 10,000 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `checkbox`, `collapse`, `command`, `dialog`, `field`, `icon-check`, `icon-chevron-right`, `icon-engine`, `icon-loader-ring` and 7 more.

Requires `cmdk`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/command`.

Use a command palette to put every action and destination in the app one shortcut away, for people who live on the keyboard. It isn't the only way to reach anything: each command should also have a visible home in the interface. For a searchable list inside a page, a picker or a filter, use [Command](https://www.youj.dev/docs/components/command) on its own.

> **Why ⌘/ here:** `CommandPalette` listens for ⌘K (Ctrl+K on Windows and Linux) by default. This site already uses ⌘K for its own search, so the palette in the Demo story listens for ⌘/ instead, and the other examples open from their buttons.

```tsx
import { CommandGroup, CommandItem, CommandPalette } from '@youj/react/command'

export function AppPalette() {
  return (
    <CommandPalette>
      {({ page, push, close }) =>
        page?.id === 'projects' ? (
          <ProjectRows onOpen={close} />
        ) : (
          <CommandGroup heading="Suggestions">
            <CommandItem onSelect={() => push({ id: 'projects', label: 'Projects', placeholder: 'Search projects…' })}>
              Switch project…
            </CommandItem>
            <CommandItem onSelect={() => { deploy(); close() }}>Deploy to production</CommandItem>
          </CommandGroup>
        )
      }
    </CommandPalette>
  )
}
```

Render it once, near the root of the app. It's a [CommandDialog](https://www.youj.dev/docs/components/command#in-a-dialog) with pages: the rows are yours, built from Command's parts (`CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandLoading`…), and `children` can be a function of the palette's state. `shortcut` sets the key that toggles it with ⌘ or Ctrl from anywhere on the page. It's `k` by default, and `false` turns it off. The shortcut steps aside when something else on the page has already handled the keystroke.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `shortcut` | `string \| false` | `'k'` | A key that toggles the palette with ⌘ (Ctrl elsewhere) from anywhere on the page. `false` for none. |
| `placeholder` | `string` |  | The first page's placeholder. |
| `title` | `string` | `"Command palette"` | The dialog's accessible name. |
| `description` | `string` |  | Describes the dialog for screen readers. Default: the built-in "Search for a command to run" (a label, so translated with the rest). |
| `search` | `string` |  | Controlled search, e.g. to fetch results as the user types. |
| `onSearchChange` | `(search: string) => void` |  |  |
| `shouldFilter` | `boolean` |  | Turn off cmdk's filtering when results arrive already matched. |
| `autoFocusField` | `boolean` |  | Whether the search field takes focus on open. By default it does from a keyboard or a mouse and not from a touch (the list shows first). Pass true when a search button opens it to type in; on iOS also call `primeKeyboard()` in that button's tap handler so the keyboard comes up. |
| `className` | `string` |  |  |
| `children` (required) | `ReactNode \| ((state: CommandPaletteState) => ReactNode)` |  | The rows for the current page, or a function of the palette's state. |

`useCommandPalette()` returns `CommandPaletteState` and throws outside a palette. `CommandPalettePage` is `{ id: string; label: string; placeholder?: string }`.

### Touch

On a touch device the palette is a tall bottom sheet. The search field is at the top, rows are 48px, and the footer of keyboard hints is gone. On a page, the breadcrumb is how you go back (its crumbs are big enough to tap). Pulling the sheet down closes the palette from any page, while Escape still steps back one page first. While the on-screen keyboard is up the sheet sits on top of it, so the search field stays visible.

The palette opens with the list in view and the keyboard down. If a search button opens it to type in, pass `autoFocusField`, and on iOS call `primeKeyboard()` from `@youj/react` in the button's tap handler before you open it. iOS only raises the keyboard for a focus that happens during the tap itself.

```tsx
import { primeKeyboard } from '@youj/react'
import { CommandPalette } from '@youj/react/command'

<button
  onClick={() => {
    primeKeyboard()
    setOpen(true)
  }}
>
  Search
</button>
<CommandPalette open={open} onOpenChange={setOpen} autoFocusField>
  …
</CommandPalette>
```

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | rises and scales in from the top third (`yj-dialog`) |
| Close | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Backdrop | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | fades in behind it (`yj-backdrop`) |
| Active row | `spring.smooth` | 0.36s, bounce 0 | glides as you arrow through, and across page changes |
| List height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | eases between pages and result sets |

**Reduced motion:** The palette opens and closes at once, the highlight jumps and the list snaps to each new height. Pages, the breadcrumb and every key work the same.

The palette hangs from the top third of the screen, so the search field never moves while the list below it grows and shrinks between pages.

#### Reduced motion

The dialog appears and disappears without rising or fading, the active row's highlight jumps, and the list snaps between heights. Nothing about pages, search or the keys changes.

### Accessibility

- It's a modal dialog named by `title` ("Command palette" by default). Focus goes to the search field when it opens and returns to where it was when it closes.
- The search field is a combobox over a listbox, as in [Command](https://www.youj.dev/docs/components/command#accessibility). On a page, the field is named after the page.
- Changing page is announced ("Projects page"), and the breadcrumb is for the pointer: `Backspace` and `Escape` walk it from the keyboard.
- The footer spells out the keys, and `Escape` reads Back while there's a page to go back to.

| Key | Action |
| --- | --- |
| `⌘K` / `Ctrl+K` | Toggles the palette, or the key set by `shortcut`. |
| `↑` / `↓` | Moves the active row. |
| `Enter` | Runs the active row, or opens its page. |
| `Backspace` | On an empty search, steps back one page. |
| `Escape` | Steps back one page, then closes the palette. |

---

# Mega Menu

> Group navigation links into columns with captions and a featured card.

Source: https://www.youj.dev/docs/components/mega-menu

## Examples

### Demo

```tsx
'use client'

import {
  BarChartIcon,
  BookmarkIcon,
  CodeIcon,
  DatabaseIcon,
  GlobeIcon,
  RocketIcon,
  ShieldCheckIcon,
  SparklesIcon,
  TerminalIcon,
} from '@youj/icons'
import { MeshGradient } from '@youj/motion/backgrounds'
import {
  MegaMenuContent,
  MegaMenuFeatured,
  MegaMenuGroup,
  MegaMenuLink,
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from '@youj/react'

export default function MegaMenuDemo() {
  return (
    // The bar sits at the top of the stage, so its panels open into the room below.
    <div className="flex h-[22rem] w-full max-w-2xl flex-col">
      <div className="flex items-center gap-4 rounded-xl border border-line bg-canvas px-4 py-2 shadow-xs">
        <span className="text-ui-lg font-semibold tracking-tight text-fg">Northwind</span>
        {/* The top padding keeps a flipped panel clear of a 56px sticky header. */}
        <NavigationMenu aria-label="Main" collisionPadding={{ top: 64, right: 8, bottom: 8, left: 8 }}>
          <NavigationMenuList>
            <NavigationMenuItem value="product">
              <NavigationMenuTrigger>Product</NavigationMenuTrigger>
              <MegaMenuContent
                featured={
                  <MegaMenuFeatured
                    href="#launch"
                    eyebrow="New"
                    title="Northwind 2.0"
                    description="Themes, density and a motion personality per preset."
                    media={<MeshGradient intensity={1.1} interactive={false} className="absolute inset-0" />}
                  />
                }
              >
                <MegaMenuGroup title="Build">
                  <MegaMenuLink href="#deploy" icon={<RocketIcon size={16} />} title="Deployments" description="Git-push to preview, promote to prod." />
                  <MegaMenuLink href="#functions" icon={<TerminalIcon size={16} />} title="Functions" description="Server code that scales to zero." />
                  <MegaMenuLink href="#storage" icon={<DatabaseIcon size={16} />} title="Storage" description="Blobs, KV and Postgres by your code." />
                </MegaMenuGroup>
                <MegaMenuGroup title="Observe">
                  <MegaMenuLink href="#analytics" icon={<BarChartIcon size={16} />} title="Analytics" description="Real traffic, no cookies, no sampling." />
                  <MegaMenuLink href="#firewall" icon={<ShieldCheckIcon size={16} />} title="Firewall" description="Rules that deploy with your code." />
                  <MegaMenuLink href="#edge" icon={<GlobeIcon size={16} />} title="Edge network" description="Cached close to every visitor." />
                </MegaMenuGroup>
              </MegaMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem value="developers">
              <NavigationMenuTrigger>Developers</NavigationMenuTrigger>
              <MegaMenuContent>
                <MegaMenuGroup title="Learn">
                  <MegaMenuLink href="#docs" icon={<BookmarkIcon size={16} />} title="Docs" description="Guides and the API reference." />
                  <MegaMenuLink href="#templates" icon={<SparklesIcon size={16} />} title="Templates" description="Start from something that works." />
                </MegaMenuGroup>
                <MegaMenuGroup title="Tools">
                  <MegaMenuLink href="#cli" icon={<CodeIcon size={16} />} title="CLI" description="Deploy from your terminal." />
                  <MegaMenuLink href="#api" icon={<TerminalIcon size={16} />} title="REST API" description="Everything the dashboard can do." />
                </MegaMenuGroup>
              </MegaMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
              <NavigationMenuLink href="#pricing" className={navigationMenuTriggerStyle()}>
                Pricing
              </NavigationMenuLink>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      </div>
    </div>
  )
}
```

A header navigation whose Product panel arranges grouped links in columns beside a featured card.

### Featured card

```tsx
'use client'

import {
  BookmarkIcon,
  CalendarIcon,
  CodeIcon,
  FileTextIcon,
  MessageIcon,
  UsersIcon,
} from '@youj/icons'
import {
  MegaMenuContent,
  MegaMenuFeatured,
  MegaMenuGroup,
  MegaMenuLink,
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuList,
  NavigationMenuTrigger,
} from '@youj/react'

export default function MegaMenuResources() {
  return (
    // The bar sits at the top of the stage, so its panels open into the room below.
    <div className="flex h-[19rem] w-full max-w-2xl flex-col">
      <div className="flex items-center gap-4 rounded-xl border border-line bg-canvas px-4 py-2 shadow-xs">
        <span className="text-ui-lg font-semibold tracking-tight text-fg">Northwind</span>
        {/* The top padding keeps a flipped panel clear of a 56px sticky header. */}
        <NavigationMenu aria-label="Main" collisionPadding={{ top: 64, right: 8, bottom: 8, left: 8 }}>
          <NavigationMenuList>
            <NavigationMenuItem value="resources">
              <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
              <MegaMenuContent
                featured={
                  // Without `media`, the card's art is a soft wash of the accent.
                  <MegaMenuFeatured
                    href="#changelog"
                    eyebrow="Changelog"
                    title="Branch previews for monorepos"
                    description="Every package in a pull request gets its own URL."
                  />
                }
              >
                <MegaMenuGroup title="Learn">
                  <MegaMenuLink href="#docs" icon={<BookmarkIcon size={16} />} title="Docs" />
                  <MegaMenuLink href="#guides" icon={<FileTextIcon size={16} />} title="Guides" />
                  <MegaMenuLink href="#api" icon={<CodeIcon size={16} />} title="API reference" />
                </MegaMenuGroup>
                <MegaMenuGroup title="Community">
                  <MegaMenuLink href="#forum" icon={<MessageIcon size={16} />} title="Forum" />
                  <MegaMenuLink href="#events" icon={<CalendarIcon size={16} />} title="Events" />
                  <MegaMenuLink href="#experts" icon={<UsersIcon size={16} />} title="Experts" />
                </MegaMenuGroup>
              </MegaMenuContent>
            </NavigationMenuItem>
          </NavigationMenuList>
        </NavigationMenu>
      </div>
    </div>
  )
}
```

A Resources panel with a featured card on one side and grouped links on the other.

`featured` puts one card at the inline end of the panel. `MegaMenuFeatured` is a single link with art on top and copy below: an `eyebrow` ("New", "Changelog"), a `title` and a `description`. The art is decorative, so any [background piece](https://www.youj.dev/docs/components/mesh-gradient) works as `media`. The first preview uses a [Mesh Gradient](https://www.youj.dev/docs/components/mesh-gradient). Without `media`, the card gets a soft wash of the accent.

Keep a panel to two or three columns. Past that the popup gets wider than most windows, and the reader has too many choices to scan.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add mega-menu
```

It brings `navigation-menu`, `youj-presets`, `youj-ui-core` with it.

The copy is 9 registry items, about 7,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `collapsible`, `icon-chevron-down`, `icon-engine`, `navigation-menu`, `sliding-indicator`.

Use a mega menu when a top-level section has more destinations than a plain dropdown holds well: a product with a dozen features, a resources hub, a developer portal. Each panel groups links into captioned columns, and a featured card at the end can carry a launch or a case study. For a handful of links, a [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu) with plain panels is enough. Actions (sign out, delete, switch theme) belong in a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu), not in navigation.

The mega menu parts go inside a [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu): `MegaMenuContent` takes the place of `NavigationMenuContent`.

```tsx
import {
  MegaMenuContent,
  MegaMenuFeatured,
  MegaMenuGroup,
  MegaMenuLink,
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuList,
  NavigationMenuTrigger,
} from '@youj/react'
import { RocketIcon, TerminalIcon } from '@youj/icons'

export function ProductMenu() {
  return (
    <NavigationMenu aria-label="Main">
      <NavigationMenuList>
        <NavigationMenuItem value="product">
          <NavigationMenuTrigger>Product</NavigationMenuTrigger>
          <MegaMenuContent featured={<MegaMenuFeatured href="/blog/2-0" eyebrow="New" title="Northwind 2.0" />}>
            <MegaMenuGroup title="Build">
              <MegaMenuLink href="/deployments" icon={<RocketIcon size={16} />} title="Deployments" description="Git-push to preview, promote to prod." />
              <MegaMenuLink href="/functions" icon={<TerminalIcon size={16} />} title="Functions" description="Server code that scales to zero." />
            </MegaMenuGroup>
          </MegaMenuContent>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

Each `MegaMenuGroup` is a column, 15.5rem wide, under its caption. `MegaMenuLink` is a destination: an icon tile, a title and one line of description. It closes the menu when it's followed. A [Youj icon](https://www.youj.dev/docs/icons) in the tile plays while the link is hovered or focused, with no wiring.

### In a header

A mega menu usually lives in an [App Header](https://www.youj.dev/docs/components/app-header), inside `AppHeaderNav`, which hides it below `md`. Phones get the same destinations as a flat list in `AppHeaderMenu`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### MegaMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `featured` | `ReactNode` |  | A card at the inline end: a launch, a case study, a changelog entry. |

Also takes the props of `ComponentProps<typeof NavigationMenuContent>`.

It takes `NavigationMenuContent`'s props as well.

#### MegaMenuGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | The column's caption. It labels the group for assistive tech. |

Also takes the props of `ComponentProps<'div'>`.

#### MegaMenuLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | A 16px glyph for the tile; a youj icon plays while the link is hovered or focused. |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |

Also takes the props of `ComponentProps<typeof NavigationMenuLink>`.

#### MegaMenuFeatured

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `media` | `ReactNode` |  | Art for the top of the card: an image, a motion background piece. Decorative. |
| `eyebrow` | `ReactNode` |  | A small line above the title, e.g. "New". |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |

Also takes the props of `ComponentProps<typeof NavigationMenuLink>`.

`MegaMenuLink` and `MegaMenuFeatured` are `NavigationMenuLink`s, so `href`, `render` (for a router link), `active` and `closeOnClick` pass through.

### Motion

The motion is the [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu)'s: the panels only add layout.

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Hover pill | `spring.smooth` | 0.36s, bounce 0 | glides between triggers with the pointer and keyboard focus |
| Popup in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | grows out of the trigger: scale from 0.96 and fade |
| Popup out | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Popup between triggers | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | slides to the next trigger and morphs to its panel size |
| Panels trade places | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | 24px drift and fade, away from the way you moved |
| Link tile | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the icon turns to ink, and a Youj icon plays its own motion |
| Featured card border | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | strengthens on hover |

**Reduced motion:** The popup and its panels appear, resize and swap at once, the pill jumps, and link icons don't play.

#### Reduced motion

The panel appears, resizes and swaps with the next one at once, and the hover pill jumps between triggers. Link icons stay still. The menu opens, closes and moves focus exactly as it does with motion.

### Accessibility

- Each column is a `group` labeled by its caption.
- A link is named by its title, and its description is read after it (`aria-describedby`). The featured card is named by its eyebrow and title. Icons and art are hidden from assistive technology.
- Triggers are buttons with `aria-expanded`. The whole menu is a `nav` landmark, named by the `NavigationMenu`'s `aria-label`.

| Key | Action |
| --- | --- |
| Enter / Space / ↓ | Open the focused trigger's panel. |
| Tab | Move through the panel's links, then on to the next trigger. |
| Escape | Close the panel and return focus to its trigger. |

---

# Stepper Nav

> Navigate a flow that spans pages, with links back to completed steps.

Source: https://www.youj.dev/docs/components/stepper-nav

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, StepperNav } from '@youj/react'

const STEPS = [
  { id: 'account', title: 'Account', description: 'Email and password' },
  { id: 'workspace', title: 'Workspace', description: 'Name and URL' },
  { id: 'plan', title: 'Plan', description: 'Pick what fits' },
  { id: 'invite', title: 'Invite', description: 'Bring your team', optional: true },
]

export default function StepperNavDemo() {
  // In an app, `current` comes from the route: /setup/workspace is step 1.
  const [current, setCurrent] = useState(1)
  const done = current === STEPS.length

return (
    <div className="flex w-full max-w-2xl flex-col gap-8">
      <StepperNav aria-label="Setup" steps={STEPS} current={current} href={(i) => `#setup-${STEPS[i]!.id}`} onNavigate={setCurrent} />
      <div className="flex items-center gap-2">
        <Button variant="outline" disabled={current === 0} onClick={() => setCurrent((c) => c - 1)}>
          Back
        </Button>
        <Button disabled={done} onClick={() => setCurrent((c) => c + 1)}>
          {current >= STEPS.length - 1 ? 'Finish' : 'Continue'}
        </Button>
        <span className="ms-auto text-ui-sm text-fg-muted" aria-live="polite">
          {done ? 'All set' : `Step ${current + 1} of ${STEPS.length}`}
        </span>
      </div>
    </div>
  )
}
```

A four-step setup row with Back and Continue buttons; finished steps become links back.

The horizontal row keeps its discs and connectors on narrow screens and drops the titles below `sm`, so four or five steps still fit in one line. The titles stay in the accessible name. Pass `compact={false}` to keep them visible, or switch to `vertical` on phones.

### Vertical

```tsx
'use client'

import { useState } from 'react'
import { Button, StepperNav } from '@youj/react'

const STEPS = [
  { id: 'cart', title: 'Cart', description: '3 items' },
  { id: 'shipping', title: 'Shipping', description: 'Address and speed' },
  { id: 'payment', title: 'Payment', description: 'Card or invoice' },
  { id: 'review', title: 'Review', description: 'Check and place the order' },
]

export default function StepperNavVertical() {
  const [current, setCurrent] = useState(2)

// Side by side from `sm`; on a phone the panel stacks under the list, so neither is squeezed.
  return (
    <div className="flex w-full max-w-lg flex-col gap-5 sm:flex-row sm:gap-8">
      <StepperNav
        aria-label="Checkout"
        orientation="vertical"
        steps={STEPS}
        current={current}
        href={(i) => `#checkout-${STEPS[i]!.id}`}
        onNavigate={setCurrent}
        className="shrink-0 sm:w-52"
      />
      <div className="flex min-w-0 flex-1 flex-col gap-3 rounded-xl border border-line bg-surface p-4">
        <p className="text-ui font-medium text-fg">{STEPS[Math.min(current, STEPS.length - 1)]!.title}</p>
        <p className="text-ui-sm text-fg-muted">Done steps are links back; upcoming ones can't be skipped to.</p>
        <div className="mt-auto flex gap-2">
          <Button size="sm" variant="outline" disabled={current === 0} onClick={() => setCurrent((c) => c - 1)}>
            Back
          </Button>
          <Button size="sm" disabled={current === STEPS.length} onClick={() => setCurrent((c) => c + 1)}>
            {current >= STEPS.length - 1 ? 'Place order' : 'Continue'}
          </Button>
        </div>
      </div>
    </div>
  )
}
```

The same navigation stacked down the side of a checkout, beside the content for the current step.

`orientation="vertical"` stacks the steps down the side of the page, next to the form they describe, with the connectors running between the discs.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stepper-nav
```

It brings `stepper`, `youj-core`, `youj-labels-stepper-nav`, `youj-ui-core` with it.

Use it at the top (or down the side) of a flow where each step is its own page: checkout, onboarding, workspace setup. It shows where the reader is and lets them go back to any step they've done. It doesn't run the flow: validation, saving and what "Continue" does stay with your app, and upcoming steps can't be jumped to. When the steps live on one page and the component should own them, use a [Wizard](https://www.youj.dev/docs/components/wizard). To show progress without links, use a [Stepper](https://www.youj.dev/docs/components/stepper) on its own.

```tsx
import { StepperNav } from '@youj/react'

const steps = [
  { id: 'account', title: 'Account', description: 'Email and password' },
  { id: 'workspace', title: 'Workspace', description: 'Name and URL' },
  { id: 'plan', title: 'Plan' },
  { id: 'invite', title: 'Invite', optional: true },
]

export function SetupProgress({ step }: { step: number }) {
  return <StepperNav aria-label="Setup" steps={steps} current={step} href={(i) => `/setup/${steps[i]!.id}`} />
}
```

`current` is the index of the step the reader is on, usually read from the route. `href` maps a step to its page. The done steps and the current one become links, and the ones ahead stay plain text. Set `current` to `steps.length` once the flow is done, and every step shows its check.

Each step is a [Stepper](https://www.youj.dev/docs/components/stepper) step: a `title`, an optional `description`, `optional` to add "Optional" under the title, and `error` to mark a step that needs another look. `onNavigate` fires as a step link is followed, which is where a client-side router takes over.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `readonly StepperStep[]` |  |  |
| `current` (required) | `number` |  | Index of the current step. |
| `href` (required) | `(index: number) => string` |  | The page of step `index`. Done steps and the current one link to it. |
| `onNavigate` | `(index: number) => void` |  | Fires as a step link is followed, e.g. for client-side routing. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
| `compact` | `boolean` | `true` | Hide titles below `sm` (horizontal only). |

Also takes the props of `ComponentProps<'nav'>`.

### Motion

The motion is Stepper's.

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Connector fills | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | as a step completes, scaling along the line from the finished step |
| Connector drains | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | when you go back, from wherever the fill is |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws in on a finished step |
| Disc and title color | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | upcoming, current, complete or error |

**Reduced motion:** Connectors fill and drain at once, and checks appear already drawn.

#### Reduced motion

The connectors fill and drain at once, and a finished step's check appears already drawn. Colors change instantly. The links, statuses and names are unchanged.

### Accessibility

- It's a `nav` landmark named "Progress" by default. Name it after the flow with `aria-label` ("Setup", "Checkout").
- The steps are an ordered list. The current step carries `aria-current="step"`, and every step's name ends with its status ("Workspace, current step", "Account, completed", "Plan, not started"), so the progress reads the same without the colors.
- Done steps and the current one are links. Upcoming steps aren't focusable, since they can't be reached yet.
- Titles hidden below `sm` are still in the accessible name.

---

# Wizard

> Guide people through a task with step validation and an async finish action.

Source: https://www.youj.dev/docs/components/wizard

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
  Checkbox,
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
  Input,
  Label,
  Textarea,
  Wizard,
  WizardStep,
} from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function WizardDemo() {
  const [name, setName] = useState('')
  const [email, setEmail] = useState('')
  const [touched, setTouched] = useState(false)
  const [slug, setSlug] = useState('acme')
  const [slugError, setSlugError] = useState<string>()
  const nameOk = name.trim().length >= 2
  const emailOk = /^\S+@\S+\.\S+$/.test(email)

return (
    <Card className="w-full max-w-2xl">
      <CardHeader>
        <CardTitle role="heading" aria-level={2}>
          Set up your workspace
        </CardTitle>
        <CardDescription>Four short steps. You can change everything later.</CardDescription>
      </CardHeader>
      <CardContent>
        <Wizard orientation="vertical" onComplete={() => wait(900)} finishLabel="Launch workspace" finishSuccessLabel="Ready">
          <WizardStep
            id="account"
            title="Create your account"
            description="We'll use this to sign you in."
            validate={() => {
              setTouched(true)
              return nameOk && emailOk
            }}
          >
            <div className="grid gap-4">
              <Field invalid={touched && !nameOk}>
                <FieldLabel>Full name</FieldLabel>
                <Input value={name} onChange={(e) => setName(e.target.value)} placeholder="Ada Lovelace" autoComplete="name" />
                {touched && !nameOk && <FieldError>Enter your name.</FieldError>}
              </Field>
              <Field invalid={touched && !emailOk}>
                <FieldLabel>Work email</FieldLabel>
                <Input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="ada@analytical.io" type="email" autoComplete="email" />
                {touched && !emailOk && <FieldError>Enter a valid email address.</FieldError>}
              </Field>
            </div>
          </WizardStep>
          <WizardStep
            id="workspace"
            title="Name your workspace"
            description="The URL is where your team will find you."
            validate={async () => {
              await wait(700)
              const taken = slug.trim().toLowerCase() === 'acme'
              setSlugError(taken ? 'acme is taken. Try another.' : undefined)
              return !taken
            }}
          >
            <Field invalid={Boolean(slugError)}>
              <FieldLabel>Workspace URL</FieldLabel>
              <div className="flex items-center gap-2">
                <span className="text-ui text-fg-muted">youj.app/</span>
                <Input value={slug} onChange={(e) => setSlug(e.target.value)} className="max-w-48" />
              </div>
              <FieldDescription>"acme" is taken in this demo.</FieldDescription>
              {slugError && <FieldError>{slugError}</FieldError>}
            </Field>
          </WizardStep>
          <WizardStep id="integrations" title="Connect your tools" description="Bring in activity from where you already work." optional>
            <div className="grid gap-2">
              {['GitHub', 'Slack', 'Linear'].map((tool) => (
                <Label key={tool} className="flex items-center gap-3 rounded-lg border border-line p-3 has-data-checked:border-accent-line">
                  <Checkbox defaultChecked={tool === 'GitHub'} />
                  <span className="font-medium">{tool}</span>
                </Label>
              ))}
            </div>
          </WizardStep>
          <WizardStep id="invite" title="Invite your team" description="Separate addresses with commas.">
            <Field>
              <FieldLabel>Email addresses</FieldLabel>
              <Textarea placeholder="grace@navy.mil, alan@bletchley.uk" rows={3} />
            </Field>
          </WizardStep>
        </Wizard>
      </CardContent>
    </Card>
  )
}
```

A vertical, four-step workspace setup with required fields, a slug that's checked asynchronously and a final launch button.

The default, horizontal wizard puts a compact stepper above the content; below the `sm` breakpoint it shows only discs. `orientation="vertical"`, as in the Demo story, puts the stepper in a column beside the content from `sm` up, which suits longer flows with descriptions.

### Validation

```tsx
'use client'

import { useState } from 'react'
import { Button, Card, CardContent, Field, FieldLabel, Input, Label, RadioGroup, RadioGroupItem, Wizard, WizardStep } from '@youj/react'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

const DELIVERY = [
  { value: 'email', title: 'Email only', meta: 'Free · instant' },
  { value: 'standard', title: 'Hardware key, standard', meta: '$6 · 3–5 days' },
  { value: 'express', title: 'Hardware key, express', meta: '$18 · next day' },
]

export default function WizardCheckout() {
  const [card, setCard] = useState('')
  const [cardError, setCardError] = useState(false)

return (
    <Card className="w-full max-w-xl">
      <CardContent>
        <Wizard
          finishLabel="Place order"
          finishSuccessLabel="Order placed"
          onComplete={() => wait(1100)}
          footerStart={<Button variant="ghost">Cancel</Button>}
        >
          <WizardStep id="shipping" title="Delivery" description="Licenses arrive by email; hardware keys ship.">
            <RadioGroup defaultValue="email" aria-label="Delivery method" className="grid gap-2">
              {DELIVERY.map((option) => (
                <Label key={option.value} className="flex items-center gap-3 rounded-lg border border-line p-3 has-data-checked:border-accent-line">
                  <RadioGroupItem value={option.value} />
                  <span className="flex-1 font-medium">{option.title}</span>
                  <span className="text-ui-sm text-fg-muted">{option.meta}</span>
                </Label>
              ))}
            </RadioGroup>
          </WizardStep>
          <WizardStep
            id="payment"
            title="Payment"
            description="Try continuing with the field empty."
            validate={() => {
              const ok = card.replace(/\s/g, '').length >= 12
              setCardError(!ok)
              // A string fails the step: it's shown under the step and announced.
              return ok || 'Enter a card number to continue.'
            }}
          >
            <Field invalid={cardError}>
              <FieldLabel>Card number</FieldLabel>
              <Input value={card} onChange={(e) => setCard(e.target.value)} inputMode="numeric" placeholder="4242 4242 4242 4242" autoComplete="cc-number" />
            </Field>
          </WizardStep>
          <WizardStep id="review" title="Review and pay">
            <dl className="grid grid-cols-[1fr_auto] gap-y-1.5 text-ui">
              <dt className="text-fg-muted">Subtotal</dt>
              <dd className="tabular-nums">$348.00</dd>
              <dt className="text-fg-muted">Tax</dt>
              <dd className="tabular-nums">$27.84</dd>
              <dt className="border-t border-line pt-1.5 font-medium">Total</dt>
              <dd className="border-t border-line pt-1.5 font-semibold tabular-nums">$375.84</dd>
            </dl>
          </WizardStep>
        </Wizard>
      </CardContent>
    </Card>
  )
}
```

A checkout wizard where the Payment step blocks Continue until a card number is entered.

`validate` runs when someone leaves a step forwards. Return `true` to move on, `false` to stay (the step's own field errors explain why), or a message, which appears under the step and is announced. It can be async: Continue shows a spinner while it runs. A failed step is marked in the stepper until it passes.

In the Demo story, the workspace name "acme" is taken, which the step finds out after a short async check.

Here, continuing past Payment with an empty card number returns a message instead of `false`. `footerStart` puts a Cancel button at the inline start of the footer, away from the forward actions.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add wizard
```

It brings `async-button`, `button`, `stepper`, `youj-core`, `youj-labels-wizard`, `youj-ui-core` with it.

The copy is 22 registry items, about 8,800 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-button`, `async-feedback`, `button`, `icon-alert-triangle`, `icon-check`, `icon-engine`, `icon-flag`, `icon-loader-ring`, `icon-route`, `morph-label` and 2 more.

Use a wizard when a task is long enough to split but each part depends on the one before: creating a workspace, a checkout, importing data. It draws a [Stepper](https://www.youj.dev/docs/components/stepper), shows one step's content, and handles Back, Continue, Skip and Finish. When every field fits on one screen, a single [Form](https://www.youj.dev/docs/components/form) is quicker to fill in. When people need to compare the steps, don't hide them: lay them out as sections of one page.

```tsx
import { Wizard, WizardStep } from '@youj/react'

export function CreateProject() {
  return (
    <Wizard onComplete={() => createProject(values)} finishLabel="Create project">
      <WizardStep id="name" title="Name" validate={() => values.name.length > 0}>
        <NameFields />
      </WizardStep>
      <WizardStep id="repo" title="Repository" optional>
        <RepoPicker />
      </WizardStep>
      <WizardStep id="review" title="Review">
        <Summary />
      </WizardStep>
    </Wizard>
  )
}
```

Each `WizardStep` is a step: its `title` goes in the stepper and heads the content, and its children show while it's current. The wizard keeps the step index itself, or pass `step` and `onStepChange` to control it. On the last step, Finish runs `onComplete` through the [Button](https://www.youj.dev/docs/components/button)'s `onAction`, so it shows a spinner and then a drawn check with `finishSuccessLabel`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `step` | `number` |  | Controlled current step index. |
| `defaultStep` | `number` | `0` |  |
| `onStepChange` | `(step: number) => void` |  |  |
| `onComplete` | `() => unknown \| Promise<unknown>` |  | Runs when Finish is pressed on the last step (after its validation). Resolve for success. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
| `backLabel` | `string` |  | Labels. |
| `nextLabel` | `string` |  |  |
| `finishLabel` | `string` |  |  |
| `finishSuccessLabel` | `string` |  |  |
| `footerStart` | `ReactNode` |  | Extra content in the footer, at the inline start (e.g. a Cancel button). |
| `headingLevel` | `2 \| 3 \| 4` | `3` | The step title's heading level: 3 under a section or dialog title (the default), 2 straight under a page's h1. |

Also takes the props of `ComponentProps<'div'>`.

#### WizardStep

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `optional` | `boolean` |  | Can be skipped: shows "Optional" and a Skip button. |
| `validate` | `() => ValidationResult \| Promise<ValidationResult>` |  | Runs when leaving the step forwards. Return (or resolve) `false` to stay on it (the step's own field errors explain why), or a message, which is shown under the step and announced. Throwing counts as a failure with the error's message. |
| `children` (required) | `ReactNode` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Step enter | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | drifts 24px in from the side you travel to and fades in |
| Step exit | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | drifts 24px out the other way as it fades |
| Panel height | `spring.smooth` | 0.36s, bounce 0 | glides between the two steps' heights |
| Stepper | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the connector fills or drains, see Stepper |
| Finish | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the button's spinner, then a drawn check |

**Reduced motion:** Steps swap in place and the panel takes its new height at once.

The drift follows the reading direction, so under RTL forwards comes in from the left. The outgoing step is popped out of the layout while it leaves, so rapid Back and Continue presses retarget the height without a jump.

#### Reduced motion

Steps replace each other in place with no drift or fade, and the panel height changes at once. Focus, announcements and validation are unchanged.

### Accessibility

- "Step 2 of 4" above the content is a polite live region that also speaks the step's title, so each move is announced.
- After Back or Continue, focus moves to the new step's heading, so a screen reader starts reading from the top of the step and a keyboard user tabs on into its fields.
- A validation message has `role="alert"`, and the failed step is spoken as "has an error" in the stepper.
- Done steps in the stepper are buttons that go back to them. Later steps can only be reached by Continue, so validation can't be skipped.
- Continue sets `aria-busy` while an async validation runs, and ignores presses until it settles.

---

# App Header

> Bring your app’s navigation, search and account controls into a header that condenses on scroll.

Source: https://www.youj.dev/docs/components/app-header

## Examples

### Demo

```tsx
'use client'

import { useRef, useState } from 'react'
import { BarChartIcon, HomeIcon, KeyboardIcon, RocketIcon, SettingsIcon, UserIcon } from '@youj/icons'
import {
  AccountMenu,
  AppHeader,
  AppHeaderActions,
  AppHeaderBrand,
  AppHeaderMenu,
  AppHeaderMenuLink,
  AppHeaderNav,
  AppHeaderSearch,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuShortcut,
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  navigationMenuTriggerStyle,
} from '@youj/react'
import {
  CommandGroup,
  CommandItem,
  CommandPalette,
  CommandShortcut,
} from '@youj/react/command'

const PAGES = [
  { id: 'overview', label: 'Overview', icon: <HomeIcon size={16} /> },
  { id: 'deployments', label: 'Deployments', icon: <RocketIcon size={16} /> },
  { id: 'analytics', label: 'Analytics', icon: <BarChartIcon size={16} /> },
] as const

type Page = (typeof PAGES)[number]['id']

const DEPLOYS = [
  { branch: 'main', message: 'Tighten the pricing grid on mobile', age: '4m' },
  { branch: 'feat/onboarding', message: 'Copy pass on the welcome step', age: '38m' },
  { branch: 'fix/og-image', message: 'Regenerate the OG image at 2x', age: '2h' },
  { branch: 'main', message: 'Bump the edge cache to 10 minutes', age: '5h' },
  { branch: 'chore/deps', message: 'Update the lockfile', age: '1d' },
  { branch: 'main', message: 'Ship the new billing page', age: '2d' },
]

function Logo() {
  return (
    <svg viewBox="0 0 24 24" aria-hidden className="text-accent">
      <path d="M4 5h4l4 7-4 7H4l4-7z" fill="currentColor" />
      <path d="M12 5h4l4 7-4 7h-4l4-7z" fill="currentColor" opacity={0.45} />
    </svg>
  )
}

export default function AppHeaderDemo() {
  // The header condenses as this frame scrolls under it; in an app, leave scrollContainer out and it follows the page.
  const scroller = useRef<HTMLDivElement>(null)
  const [page, setPage] = useState<Page>('deployments')
  const [palette, setPalette] = useState(false)
  const [theme, setTheme] = useState('basalt')
  const [mode, setMode] = useState<'light' | 'dark' | 'system'>('dark')
  const go = (id: Page) => (event: { preventDefault: () => void }) => {
    event.preventDefault()
    setPage(id)
  }

return (
    <div className="w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-canvas shadow-xs">
      <div ref={scroller} className="h-[26rem] overflow-y-auto">
        <AppHeader scrollContainer={scroller}>
          <AppHeaderBrand href="#" onClick={go('overview')}>
            <Logo />
            Northwind
          </AppHeaderBrand>
          <AppHeaderNav>
            <NavigationMenu aria-label="Main">
              <NavigationMenuList>
                {PAGES.map((p) => (
                  <NavigationMenuItem key={p.id}>
                    <NavigationMenuLink
                      href={`#${p.id}`}
                      active={page === p.id}
                      aria-current={page === p.id ? 'page' : undefined}
                      onClick={go(p.id)}
                      className={navigationMenuTriggerStyle()}
                    >
                      {p.label}
                    </NavigationMenuLink>
                  </NavigationMenuItem>
                ))}
              </NavigationMenuList>
            </NavigationMenu>
          </AppHeaderNav>
          <AppHeaderActions>
            {/* The docs' own search owns ⌘K, so this demo's palette listens for ⌘J. */}
            <AppHeaderSearch shortcut="j" className="md:w-36 lg:w-36" onClick={() => setPalette(true)} />
            <AccountMenu
              user={{ name: 'Ada Lovelace', email: 'ada@northwind.dev' }}
              theme={theme}
              onThemeChange={setTheme}
              colorMode={mode}
              onColorModeChange={setMode}
              onSignOut={() => {}}
            >
              <DropdownMenuGroup>
                <DropdownMenuItem>
                  <UserIcon size={16} strokeWidth={1.75} />
                  Profile
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <SettingsIcon size={16} strokeWidth={1.75} />
                  Settings
                  <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <KeyboardIcon size={16} strokeWidth={1.75} />
                  Keyboard shortcuts
                  <DropdownMenuShortcut>?</DropdownMenuShortcut>
                </DropdownMenuItem>
              </DropdownMenuGroup>
            </AccountMenu>
            <AppHeaderMenu header="Northwind">
              {PAGES.map((p) => (
                <AppHeaderMenuLink key={p.id} href={`#${p.id}`} active={page === p.id} onClick={go(p.id)}>
                  {p.icon} {p.label}
                </AppHeaderMenuLink>
              ))}
            </AppHeaderMenu>
          </AppHeaderActions>
          <CommandPalette open={palette} onOpenChange={setPalette} shortcut="j">
            <CommandGroup heading="Go to">
              {PAGES.map((p) => (
                <CommandItem
                  key={p.id}
                  onSelect={() => {
                    setPage(p.id)
                    setPalette(false)
                  }}
                >
                  {p.icon} {p.label} <CommandShortcut>G {p.label[0]}</CommandShortcut>
                </CommandItem>
              ))}
            </CommandGroup>
          </CommandPalette>
        </AppHeader>

<div className="flex flex-col gap-3 px-5 pt-5 pb-8">
          <p className="text-ui-lg font-semibold tracking-tight text-fg capitalize">{page}</p>
          <p className="text-ui text-fg-muted">Scroll this frame: the bar condenses as the list passes under it.</p>
          <ul className="flex flex-col gap-2">
            {[...DEPLOYS, ...DEPLOYS].map((d, i) => (
              <li key={i} className="flex items-center gap-3 rounded-lg border border-line bg-surface px-3.5 py-3 text-ui">
                <span aria-hidden className="size-2 shrink-0 rounded-full bg-success" />
                <span className="min-w-0 flex-1 truncate text-fg">{d.message}</span>
                <span className="font-mono text-ui-sm text-fg-muted max-sm:hidden">{d.branch}</span>
                <span className="w-8 text-end text-ui-sm text-fg-muted tabular-nums">{d.age}</span>
              </li>
            ))}
          </ul>
        </div>
      </div>
    </div>
  )
}
```

A header with a brand, navigation, a search button that opens a command palette, an account menu and a phone menu, over a scrolling page.

The header is sticky and starts flat, on the page's own background. Once content scrolls under it, it condenses: 8px shorter, a translucent blurred surface, a hairline and a soft shadow, so what passes beneath reads as beneath. It condenses past 24px and relaxes under 8px. That gap keeps it from flickering when someone scrolls back and forth around the threshold, and a reversal mid-transition carries on from where it is.

The bar's height is the control height plus padding, so a compact or comfortable [theme](https://www.youj.dev/docs/theming) scales it with its controls. It tracks the page by default. Pass `scrollContainer` when the content scrolls inside an element, as the preview does, and `condense={false}` to keep it flat.

`AppHeaderSearch` looks like a field, but it's a button: the palette is the field. On wide screens it shows its placeholder and the shortcut, `⌘K` on Apple platforms and `Ctrl K` elsewhere. Below `md` it becomes an icon button. It's named "Search" at every size and announces its shortcut through `aria-keyshortcuts`. Set `shortcut` to the same key as the palette's own `shortcut` (the preview uses `j`, because this site's search already owns `⌘K`), or `false` to hide it.

Below `md`, the hamburger's bars morph into a cross as the sheet slides in from the inline end, and the sheet's own cross lands exactly where the hamburger was. `header` sits at the top of the sheet (the brand, or a [Workspace Switcher](https://www.youj.dev/docs/components/workspace-switcher)) and `footer` is pinned to the bottom. Every `AppHeaderMenuLink` closes the sheet as it's followed, and the sheet closes itself if the window widens past `md`. Open this page on a phone, or narrow the window, to try it.

### Signed out and not sticky

```tsx
'use client'

import { BookmarkIcon, CodeIcon, RocketIcon, SparklesIcon, TerminalIcon, UsersIcon } from '@youj/icons'
import {
  AppHeader,
  AppHeaderActions,
  AppHeaderBrand,
  AppHeaderMenu,
  AppHeaderMenuLink,
  AppHeaderNav,
  Button,
  MegaMenuContent,
  MegaMenuGroup,
  MegaMenuLink,
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  Separator,
  navigationMenuTriggerStyle,
} from '@youj/react'

export default function SignedOutHeader() {
  return (
    <div className="w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-canvas shadow-xs">
      {/* Not sticky: it scrolls away with the page and keeps its surface. */}
      <AppHeader sticky={false}>
        <AppHeaderBrand href="#">
          <Logo />
          Northwind
        </AppHeaderBrand>
        <AppHeaderNav>
          <NavigationMenu aria-label="Main">
            <NavigationMenuList>
              <NavigationMenuItem value="product">
                <NavigationMenuTrigger>Product</NavigationMenuTrigger>
                <MegaMenuContent>
                  <MegaMenuGroup title="Build">
                    <MegaMenuLink href="#deploy" icon={<RocketIcon size={16} />} title="Deployments" description="Git-push to preview, promote to prod." />
                    <MegaMenuLink href="#functions" icon={<TerminalIcon size={16} />} title="Functions" description="Server code that scales to zero." />
                  </MegaMenuGroup>
                  <MegaMenuGroup title="Learn">
                    <MegaMenuLink href="#docs" icon={<BookmarkIcon size={16} />} title="Docs" description="Guides and the API reference." />
                    <MegaMenuLink href="#cli" icon={<CodeIcon size={16} />} title="CLI" description="Deploy from your terminal." />
                  </MegaMenuGroup>
                </MegaMenuContent>
              </NavigationMenuItem>
              <NavigationMenuItem>
                <NavigationMenuLink href="#pricing" className={navigationMenuTriggerStyle()}>
                  Pricing
                </NavigationMenuLink>
              </NavigationMenuItem>
            </NavigationMenuList>
          </NavigationMenu>
        </AppHeaderNav>
        <AppHeaderActions>
          <Button size="sm" variant="ghost" className="max-md:hidden">
            Log in
          </Button>
          <Button size="sm" className="max-md:hidden">
            Sign up
          </Button>
          <AppHeaderMenu
            header="Northwind"
            footer={
              <>
                <Button size="lg">Sign up</Button>
                <Button size="lg" variant="outline">
                  Log in
                </Button>
              </>
            }
          >
            <AppHeaderMenuLink href="#deploy">
              <RocketIcon size={16} /> Deployments
            </AppHeaderMenuLink>
            <AppHeaderMenuLink href="#functions">
              <TerminalIcon size={16} /> Functions
            </AppHeaderMenuLink>
            <Separator className="my-2" />
            <AppHeaderMenuLink href="#customers">
              <UsersIcon size={16} /> Customers
            </AppHeaderMenuLink>
            <AppHeaderMenuLink href="#pricing">
              <SparklesIcon size={16} /> Pricing
            </AppHeaderMenuLink>
          </AppHeaderMenu>
        </AppHeaderActions>
      </AppHeader>
      <div className="flex h-72 flex-col items-center justify-center gap-2 px-6 text-center">
        <p className="text-2xl font-semibold tracking-tight text-fg">Ship the web, faster.</p>
        <p className="max-w-sm text-ui text-fg-muted">Previews for every push, instant rollbacks and analytics that respect your visitors.</p>
      </div>
    </div>
  )
}
```

A header that isn't sticky, with a Mega Menu and sign-up actions for visitors who are signed out.

`sticky={false}` lets the bar scroll away with the page. It keeps its surface from the start, since nothing will pass under it. Here it carries a [Mega Menu](https://www.youj.dev/docs/components/mega-menu) and the sign-up actions, which hide below `md` and reappear in the phone menu's `footer`.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add app-header
```

It brings `button`, `icon-menu`, `icon-search`, `kbd`, `sheet`, `use-mobile`, `youj-core`, `youj-labels-app-header`, `youj-presets`, `youj-ui-core` with it.

The copy is 20 registry items, about 8,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `dialog`, `icon-engine`, `icon-loader-ring`, `icon-menu`, `icon-search`, `kbd`, `presentation`, `sheet`, `spinner` and 1 more.

Use it as the one bar across the top of an app or a marketing site: the logo, the primary navigation (plain links or a [Mega Menu](https://www.youj.dev/docs/components/mega-menu)), a search button for the [Command Palette](https://www.youj.dev/docs/components/command-palette), a few actions and the [Account Menu](https://www.youj.dev/docs/components/account-menu). An app whose navigation lives down the side wants a [Sidebar](https://www.youj.dev/docs/components/sidebar) instead, often with a slimmer header beside it. On phones, where the primary destinations belong under the thumb, pair it with a [Bottom Tab Bar](https://www.youj.dev/docs/components/bottom-tab-bar).

```tsx
import {
  AccountMenu,
  AppHeader,
  AppHeaderActions,
  AppHeaderBrand,
  AppHeaderMenu,
  AppHeaderMenuLink,
  AppHeaderNav,
  AppHeaderSearch,
} from '@youj/react'
import { CommandGroup, CommandItem, CommandPalette } from '@youj/react/command'
import { useState } from 'react'

export function Header() {
  const [palette, setPalette] = useState(false)
  return (
    <AppHeader>
      <AppHeaderBrand href="/">
        <Logo />
        Northwind
      </AppHeaderBrand>
      <AppHeaderNav>
        <MainNavigation />
      </AppHeaderNav>
      <AppHeaderActions>
        <AppHeaderSearch onClick={() => setPalette(true)} />
        <AccountMenu user={user} onSignOut={signOut} />
        <AppHeaderMenu header="Northwind">
          <AppHeaderMenuLink href="/deployments" active>
            Deployments
          </AppHeaderMenuLink>
          <AppHeaderMenuLink href="/analytics">Analytics</AppHeaderMenuLink>
        </AppHeaderMenu>
      </AppHeaderActions>
      <CommandPalette open={palette} onOpenChange={setPalette}>
        <CommandGroup heading="Go to">
          <CommandItem onSelect={() => setPalette(false)}>Deployments</CommandItem>
        </CommandGroup>
      </CommandPalette>
    </AppHeader>
  )
}
```

The parts are slots in one row. `AppHeaderBrand` is a link (pass `render` for your router's link), `AppHeaderNav` holds the wide-screen navigation and hides below `md`, and `AppHeaderActions` pushes everything after it to the inline end. `AppHeaderMenu` is the phone navigation: a hamburger that only shows below `md`, opening a [Sheet](https://www.youj.dev/docs/components/sheet). Put the same destinations in both.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sticky` | `boolean` | `true` | Stays at the top of its scroll container. |
| `condense` | `boolean` | `true` | Condenses once content scrolls under it. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the header. Default: the page. |

Also takes the props of `ComponentProps<'header'>`.

#### AppHeaderSearch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | `"Search…"` | The field-like label. |
| `shortcut` | `string \| false` | `'k'` | The key shown with ⌘ / Ctrl, matching the palette's `shortcut`. |
| `variant` | `'default' \| 'danger' \| 'ghost' \| 'outline' \| 'link' \| 'secondary'` |  | `default \| secondary \| outline \| ghost \| danger \| link`. |
| `loading` | `boolean` |  | Swaps the label for a spinner without changing the button's width, sets aria-busy, and blocks presses while keeping keyboard focus on the button. Pass it (even as `false`) on any button that can load, so its live region exists before the first announcement. Without it, a click handler that returns a promise puts the button in this state until the promise settles; an explicit `loading` (even `false`) wins. For a success or error label after the work, use AsyncButton. |
| `loadingLabel` | `string` | `"Loading"` | Announced when loading starts. |
| `size` | `'default' \| 'sm' \| 'lg' \| 'xs' \| 'icon' \| 'icon-xs' \| 'icon-sm' \| 'icon-lg'` |  |  |
| `sound` | `boolean` | `true` | With sound on (`YoujProvider`’s `sound`), the button plays `tap` as it's pressed. `false` keeps this one silent. |

It takes the rest of [Button](https://www.youj.dev/docs/components/button)'s props, such as `onClick`.

#### AppHeaderMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Menu"` | Names the drawer and its navigation. |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `header` | `ReactNode` |  | Shown above the links, e.g. the brand or a workspace switcher. |
| `footer` | `ReactNode` |  | Pinned to the bottom of the drawer, e.g. sign-in buttons. |
| `className` | `string` |  |  |
| `children` (required) | `ReactNode` |  | The drawer's navigation: AppHeaderMenuLink rows, groups, anything. |

#### AppHeaderMenuLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | The current page. |

Also takes the props of `useRender.ComponentProps<'a'>`.

`AppHeaderBrand` takes an anchor's props and `render`. `AppHeaderNav` and `AppHeaderActions` are `div`s.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Condense | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height 8px shorter, surface, blur, hairline and shadow, together |
| Relax | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the same properties back, from wherever they are |
| Thresholds |  | hysteresis | condenses past 24px, relaxes under 8px |
| Hamburger to cross | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the outer bars slide to the middle as the middle one fades (`MenuIcon`) |
| Cross turns | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | 45° each way, once the bars have met |
| Sheet in | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | from the inline end (`yj-sheet-*`) |
| Sheet out | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Menu link hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | background and text colors |

**Reduced motion:** The bar condenses and relaxes at once. The hamburger swaps to a cross and the sheet appears without sliding.

#### Reduced motion

The bar takes its condensed or relaxed state at once, with no height, blur or shadow transition. On phones the hamburger turns straight into a cross and the sheet appears without sliding in. Focus handling and the thresholds are unchanged.

### Accessibility

- It's a `header` element, so it's the page's banner landmark when it sits outside `main`. Give the navigation inside it its own `aria-label` ("Main").
- The search button is named "Search" at every width, and announces its shortcut with `aria-keyshortcuts` (`Meta+K` or `Control+K`).
- The hamburger is named "Open menu" (from `title`), and the sheet is a modal dialog named by its header. Focus is trapped inside while it's open, Escape closes it, and focus returns to the hamburger. The sheet's cross is named "Close menu".
- The sheet's links sit in a `nav` named by `title`, and the current one carries `aria-current="page"` when you set `active`.
- Every control in the bar meets the control-height target, which grows by 8px on touch screens.

---

# App Page

> Give every page of your app the same header and gutter, so each one starts at the same place.

Source: https://www.youj.dev/docs/components/app-page

## Examples

### Demo

```tsx
'use client'

import { AppPage, Button, Stat, StatDelta, StatGroup, StatValue } from '@youj/react'
import { DownloadIcon, PlusIcon } from '@youj/icons'

const FIGURES = [
  { label: 'Requests', value: 4_820_000, previous: 4_610_000 },
  { label: 'Replicas', value: 9, previous: 8 },
  { label: 'Open incidents', value: 2, previous: 3, invert: true },
]

export default function AppPageDemo() {
  return (
    <AppPage
      title="Capacity"
      description="Forecast demand against what you have provisioned."
      width="fill"
      className="w-full"
      actions={
        <>
          <Button variant="outline">
            <DownloadIcon size={16} /> Export
          </Button>
          <Button>
            <PlusIcon size={16} /> Request quota
          </Button>
        </>
      }
    >
      <StatGroup aria-label="This week" className="grid-cols-1 @xl:grid-cols-3">
        {FIGURES.map((f) => (
          <Stat key={f.label} label={f.label}>
            <StatValue value={f.value} from={f.value} />
            <StatDelta value={(f.value - f.previous) / f.previous} invert={f.invert}>
              vs. last week
            </StatDelta>
          </Stat>
        ))}
      </StatGroup>
    </AppPage>
  )
}
```

A page with its title, a line under it, two actions at the end, and its sections on the page's gutter.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add app-page
```

It brings `youj-ui-core` with it.

Put each page of your app in AppPage, inside your frame's content area. [Build an app frame](https://www.youj.dev/docs/guides/build-an-app-frame) puts the sidebar, top bar, account menu and search around it. The in-app screens use it, so a page of your own sits beside them with the same header and the same edges.

```tsx
import { AppPage, Button } from '@youj/react'

export function Invoices() {
  return (
    <AppPage title="Invoices" description="Everything you've billed this year." actions={<Button>New invoice</Button>} width="fill">
      {/* your sections */}
    </AppPage>
  )
}
```

`width` sets how far the body runs. `page` (the default) stops at 1280px at 100% scale and centers, so a wide screen gets margins. `fill` takes the whole width, for a dashboard, a table, a board or a canvas. `readable` stops at 1024px and centers, for a page that is one form, such as settings. A page of tables, cards or lists fills; cap a field's own width rather than the page's.

The page is a container, so what's inside lays out by the page's width rather than the window's: use `@3xl:` and `@6xl:` in your sections. The gutter is 16px, 24px from a 48rem page and 32px from 72rem; the frame's top bars (see [Build an app frame](https://www.youj.dev/docs/guides/build-an-app-frame#the-ready-made-frame)) follow the same gutter.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | The page's heading. |
| `description` | `ReactNode` |  | A line under the title. |
| `actions` | `ReactNode` |  | The header's buttons, at its end: a primary action, a range control, a menu. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's heading level; your sections' titles sit one below it. |
| `width` | `'page' \| 'fill' \| 'readable'` | `'page'` | How wide the body runs: `page` (1280px at 100% scale, centered), `fill` (all of it) or `readable` (1024px, centered, for a page that is one form). |
| `classNames` | `Partial<Record<'header' \| 'body', string>>` |  | Extra classes for the header and for the body (the padded column that holds the header and your sections). |
| `children` | `ReactNode` |  | The page's sections, stacked on the page's gutter. |

Also takes the props of `ComponentProps<'div'>`.

`data-slot` marks its parts: `app-page`, `app-page-body`, `app-page-header`, `app-page-title`, `app-page-description` and `app-page-actions`.

### Reduced motion

AppPage is static. Nothing changes under reduced motion.

### Accessibility

- The title is an `h1` by default. Set `headingLevel` when the page sits under another heading, and give your sections the level below it.
- AppPage draws no landmark of its own: the frame's `main` holds it. Under a top bar that already names the page, the frame's `AppFrame` (the copy-in `frame-shell`) hides the title visually and keeps it for screen readers, so the page still has its heading.

---

# Sidebar

> Organize your app’s main navigation in a sidebar that collapses to icons or hides.

Source: https://www.youj.dev/docs/components/sidebar

## Examples

### Demo

```tsx
'use client'

import { useState, type CSSProperties, type MouseEvent } from 'react'
import {
  Avatar,
  AvatarFallback,
  Collapsible,
  CollapsibleChevron,
  CollapsibleContent,
  CollapsibleTrigger,
  Kbd,
  KbdGroup,
  Separator,
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
} from '@youj/react'
import { BarChartIcon, FolderIcon, HomeIcon, InboxIcon, MoreHorizontalIcon, PlusIcon, SendIcon, TerminalIcon } from '@youj/icons'

const PLATFORM = [
  { id: 'home', label: 'Home', Icon: HomeIcon },
  { id: 'inbox', label: 'Inbox', Icon: InboxIcon, badge: 3 },
  { id: 'deployments', label: 'Deployments', Icon: SendIcon },
  { id: 'analytics', label: 'Analytics', Icon: BarChartIcon },
  { id: 'logs', label: 'Logs', Icon: TerminalIcon },
]

const PROJECTS = [
  { id: 'web', pages: ['Overview', 'Deployments', 'Settings'] },
  { id: 'docs', pages: ['Overview', 'Deployments'] },
]

export default function SidebarDemo() {
  const [page, setPage] = useState('deployments')
  // In an app these are router links. Here they switch the page in place.
  const go = (next: string) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(next)
  }
  const title = PLATFORM.find((item) => item.id === page)?.label ?? page.replace('/', ' · ')

return (
    // Contained for the preview: in an app, the provider fills the viewport.
    <SidebarProvider className="h-[480px] min-h-0" style={{ '--sidebar-height': '480px' } as CSSProperties}>
      <Sidebar collapsible="icon">
        <SidebarHeader>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton size="lg" tooltip="Acme, Pro plan">
                <span aria-hidden className="grid size-8 shrink-0 place-items-center rounded-md bg-fg text-ui-sm font-semibold text-canvas">
                  A
                </span>
                <span className="flex min-w-0 flex-col leading-tight">
                  <span className="truncate font-semibold text-fg">Acme</span>
                  <span className="truncate text-ui-sm text-fg-muted">Pro plan</span>
                </span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarMenu>
              {PLATFORM.map(({ id, label, Icon, badge }) => (
                <SidebarMenuItem key={id}>
                  <SidebarMenuButton
                    isActive={page === id}
                    tooltip={label}
                    render={<a href={`/${id}`} aria-current={page === id ? 'page' : undefined} onClick={go(id)} />}
                  >
                    <Icon size={16} />
                    <span>{label}</span>
                  </SidebarMenuButton>
                  {badge && <SidebarMenuBadge>{badge}</SidebarMenuBadge>}
                </SidebarMenuItem>
              ))}
            </SidebarMenu>
          </SidebarGroup>
          <SidebarGroup>
            <SidebarGroupLabel>Projects</SidebarGroupLabel>
            <SidebarGroupAction aria-label="New project">
              <PlusIcon />
            </SidebarGroupAction>
            <SidebarGroupContent>
              <SidebarMenu>
                {PROJECTS.map((project, index) => (
                  <Collapsible key={project.id} defaultOpen={index === 0} render={<SidebarMenuItem />}>
                    <CollapsibleTrigger render={<SidebarMenuButton tooltip={project.id} />}>
                      <FolderIcon size={16} />
                      <span>{project.id}</span>
                      <CollapsibleChevron size={14} className="ms-auto text-fg-muted" />
                    </CollapsibleTrigger>
                    {/* Kept mounted, so the current page's key can find its group while it's closed. */}
                    <CollapsibleContent keepMounted>
                      <SidebarMenuSub>
                        {project.pages.map((name) => {
                          const id = `${project.id}/${name.toLowerCase()}`
                          return (
                            <SidebarMenuSubItem key={id}>
                              <SidebarMenuSubButton href={`/${id}`} isActive={page === id} aria-current={page === id ? 'page' : undefined} onClick={go(id)}>
                                <span>{name}</span>
                              </SidebarMenuSubButton>
                            </SidebarMenuSubItem>
                          )
                        })}
                      </SidebarMenuSub>
                    </CollapsibleContent>
                  </Collapsible>
                ))}
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton size="lg" tooltip="Ada Lovelace">
                <Avatar size="sm" className="size-8" aria-hidden>
                  <AvatarFallback>AL</AvatarFallback>
                </Avatar>
                <span className="flex min-w-0 flex-col leading-tight">
                  <span className="truncate font-medium text-fg">Ada Lovelace</span>
                  <span className="truncate text-ui-sm text-fg-muted">ada@acme.dev</span>
                </span>
              </SidebarMenuButton>
              <SidebarMenuAction aria-label="Account options" showOnHover>
                <MoreHorizontalIcon />
              </SidebarMenuAction>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarFooter>
        <SidebarRail />
      </Sidebar>
      {/* In an app this is <SidebarInset>, your page's <main>. The docs page already has one, so this is a div. */}
      <div className="relative flex min-w-0 flex-1 flex-col bg-canvas">
        <header className="flex h-12 shrink-0 items-center gap-2 border-b border-line px-3">
          <SidebarTrigger />
          <Separator orientation="vertical" className="me-1 data-[orientation=vertical]:h-4 data-[orientation=vertical]:self-center" />
          <p className="truncate text-ui font-medium text-fg capitalize">{title}</p>
          <span className="ms-auto hidden items-center gap-1.5 text-ui-sm text-fg-muted sm:inline-flex">
            <KbdGroup>
              <Kbd>⌘</Kbd>
              <Kbd>B</Kbd>
            </KbdGroup>
            toggles the sidebar
          </span>
        </header>
        <div className="grid flex-1 content-start gap-3 p-5 sm:grid-cols-2">
          {['Requests', 'Error rate', 'p95 latency', 'Bandwidth'].map((label, i) => (
            <div key={label} className="rounded-xl border border-line bg-surface p-4">
              <p className="text-ui-sm text-fg-muted">{label}</p>
              <p className="mt-1 text-xl font-semibold tracking-tight text-fg tabular-nums">{['1.28M', '0.02%', '82 ms', '48 GB'][i]}</p>
            </div>
          ))}
        </div>
      </div>
    </SidebarProvider>
  )
}
```

An app sidebar with grouped navigation, nested pages, badges, group actions, a footer and a rail to collapse it.

### Variants

```tsx
'use client'

import { useState, type CSSProperties, type MouseEvent } from 'react'
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
  ToggleGroup,
  ToggleGroupItem,
} from '@youj/react'
import { BarChartIcon, HomeIcon, SendIcon, SettingsIcon } from '@youj/icons'

type Variant = 'sidebar' | 'floating' | 'inset'
type CollapseMode = 'icon' | 'offcanvas'

const PAGES = [
  { id: 'home', label: 'Home', Icon: HomeIcon },
  { id: 'deployments', label: 'Deployments', Icon: SendIcon },
  { id: 'analytics', label: 'Analytics', Icon: BarChartIcon },
  { id: 'settings', label: 'Settings', Icon: SettingsIcon },
]

// SidebarInset's classes: the inset variant raises the page into a panel beside the sidebar.
const inset =
  'relative flex w-full min-w-0 flex-1 flex-col bg-canvas md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ms-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:border md:peer-data-[variant=inset]:border-line md:peer-data-[variant=inset]:bg-surface md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ms-2'

export default function SidebarVariants() {
  const [variant, setVariant] = useState<Variant>('floating')
  const [collapsible, setCollapsible] = useState<CollapseMode>('icon')
  const [page, setPage] = useState('deployments')
  const go = (next: string) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(next)
  }

return (
    <SidebarProvider className="h-[400px] min-h-0" style={{ '--sidebar-height': '400px' } as CSSProperties}>
      <Sidebar variant={variant} collapsible={collapsible}>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Acme</SidebarGroupLabel>
            <SidebarMenu>
              {PAGES.map(({ id, label, Icon }) => (
                <SidebarMenuItem key={id}>
                  <SidebarMenuButton
                    isActive={page === id}
                    tooltip={label}
                    render={<a href={`/${id}`} aria-current={page === id ? 'page' : undefined} onClick={go(id)} />}
                  >
                    <Icon size={16} />
                    <span>{label}</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              ))}
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
      {/* In an app this is <SidebarInset>. The docs page already has a <main>, so this div wears its classes. */}
      <div className={inset}>
        <div className="flex h-12 shrink-0 items-center gap-2 border-b border-line px-3">
          <SidebarTrigger />
          <span className="text-ui font-medium text-fg">Layout</span>
        </div>
        <div className="flex flex-1 flex-col gap-4 p-5">
          <ToggleGroup
            variant="segmented"
            aria-label="Variant"
            value={[variant]}
            onValueChange={(value) => value[0] && setVariant(value[0] as Variant)}
          >
            <ToggleGroupItem value="sidebar">Sidebar</ToggleGroupItem>
            <ToggleGroupItem value="floating">Floating</ToggleGroupItem>
            <ToggleGroupItem value="inset">Inset</ToggleGroupItem>
          </ToggleGroup>
          <ToggleGroup
            variant="segmented"
            aria-label="Collapses to"
            value={[collapsible]}
            onValueChange={(value) => value[0] && setCollapsible(value[0] as CollapseMode)}
          >
            <ToggleGroupItem value="icon">Icons</ToggleGroupItem>
            <ToggleGroupItem value="offcanvas">Off-canvas</ToggleGroupItem>
          </ToggleGroup>
          <p className="max-w-xs text-ui text-fg-muted">Pick a look, then collapse the sidebar with the button above.</p>
        </div>
      </div>
    </SidebarProvider>
  )
}
```

Switch between the sidebar, floating and inset variants and between the icon and off-canvas collapse modes.

`variant="floating"` detaches the sidebar into a rounded panel, and `variant="inset"` raises the page into a panel beside it instead. `side="right"` puts the sidebar on the inline end. `side="left"` is the inline start, so it moves to the right in right-to-left layouts. `surface="glass"` frosts the sidebar (and the phone's sheet) over whatever is behind it, on the kit's `yj-glass`: give the page a backdrop worth frosting, as the [Glass explorer](https://www.youj.dev/create?sidebar=glass) in Create does.

### Collapsed to icons

```tsx
'use client'

import { useState, type CSSProperties, type MouseEvent } from 'react'
import {
  Collapsible,
  CollapsibleChevron,
  CollapsibleContent,
  CollapsibleTrigger,
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
} from '@youj/react'
import { FolderIcon, HomeIcon, SendIcon, SettingsIcon } from '@youj/icons'

const PLATFORM = [
  { label: 'Home', Icon: HomeIcon },
  { label: 'Deployments', Icon: SendIcon },
  { label: 'Settings', Icon: SettingsIcon },
]
const PAGES = ['Overview', 'Deployments', 'Logs']
const REQUESTS = [
  ['12:04:11', 'GET', 200, '/api/pricing', '38ms'],
  ['12:04:12', 'GET', 200, '/', '12ms'],
  ['12:04:15', 'POST', 201, '/api/checkout', '211ms'],
  ['12:04:19', 'GET', 404, '/old-pricing', '4ms'],
  ['12:04:22', 'GET', 200, '/dashboard', '52ms'],
  ['12:04:25', 'POST', 500, '/api/webhooks/stripe', '1.2s'],
  ['12:04:31', 'GET', 200, '/dashboard/usage', '64ms'],
  ['12:04:36', 'GET', 304, '/_next/static/chunks/app.js', '2ms'],
] as const

export default function SidebarCollapsed() {
  const [page, setPage] = useState('web/Logs')
  const go = (next: string) => (event: MouseEvent) => {
    event.preventDefault()
    setPage(next)
  }

return (
    // defaultOpen={false} starts it collapsed to icons. Contained for the preview: in an app, the provider fills the viewport.
    <SidebarProvider defaultOpen={false} className="h-[360px] min-h-0" style={{ '--sidebar-height': '360px' } as CSSProperties}>
      <Sidebar collapsible="icon">
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarMenu>
              {PLATFORM.map(({ label, Icon }) => (
                <SidebarMenuItem key={label}>
                  {/* Collapsed, the tooltip shows the label on hover and focus. */}
                  <SidebarMenuButton
                    isActive={page === label}
                    tooltip={label}
                    render={<a href={`/${label.toLowerCase()}`} aria-current={page === label ? 'page' : undefined} onClick={go(label)} />}
                  >
                    <Icon size={16} />
                    <span>{label}</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              ))}
            </SidebarMenu>
          </SidebarGroup>
          <SidebarGroup>
            <SidebarGroupLabel>Projects</SidebarGroupLabel>
            <SidebarMenu>
              <Collapsible defaultOpen render={<SidebarMenuItem />}>
                {/* Collapsed, the key for a page in this group sits on the group's own item. */}
                <CollapsibleTrigger render={<SidebarMenuButton tooltip="web" />}>
                  <FolderIcon size={16} />
                  <span>web</span>
                  <CollapsibleChevron size={14} className="ms-auto text-fg-muted" />
                </CollapsibleTrigger>
                <CollapsibleContent keepMounted>
                  <SidebarMenuSub>
                    {PAGES.map((name) => (
                      <SidebarMenuSubItem key={name}>
                        <SidebarMenuSubButton
                          href={`/web/${name.toLowerCase()}`}
                          isActive={page === `web/${name}`}
                          aria-current={page === `web/${name}` ? 'page' : undefined}
                          onClick={go(`web/${name}`)}
                        >
                          <span>{name}</span>
                        </SidebarMenuSubButton>
                      </SidebarMenuSubItem>
                    ))}
                  </SidebarMenuSub>
                </CollapsibleContent>
              </Collapsible>
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
        <SidebarRail />
      </Sidebar>
      {/* In an app this is <SidebarInset>, your page's <main>. The docs page already has one, so this is a div. */}
      <div className="relative flex min-w-0 flex-1 flex-col bg-canvas">
        <header className="flex h-12 shrink-0 items-center gap-2 border-b border-line px-3">
          <SidebarTrigger />
          <p className="truncate text-ui font-medium text-fg">{page.replace('/', ' · ')}</p>
        </header>
        <ul className="divide-y divide-line font-mono text-ui-sm">
          {REQUESTS.map(([time, method, status, path, duration]) => (
            <li key={time} className="flex items-center gap-3 px-4 py-2">
              <span className="text-fg-muted tabular-nums">{time}</span>
              <span className="w-9 text-fg">{method}</span>
              <span className={status >= 500 ? 'text-danger-text' : status >= 400 ? 'text-warning-text' : 'text-fg-muted'}>{status}</span>
              <span className="min-w-0 flex-1 truncate text-fg">{path}</span>
              <span className="text-fg-muted tabular-nums">{duration}</span>
            </li>
          ))}
        </ul>
      </div>
    </SidebarProvider>
  )
}
```

A sidebar that starts collapsed to icons beside a page of logs.

Pass `defaultOpen={false}` to start collapsed, for pages that need the width, like logs. Collapsed, each item shows its `tooltip` on hover and focus, and the current page, web's Logs, puts its key on the web item. Expand the sidebar and the key glides down to Logs.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add sidebar
```

It brings `button`, `icon-sidebar`, `input`, `scroll-area`, `separator`, `sheet`, `skeleton`, `sliding-indicator`, `tooltip`, `use-mobile`, `youj-core`, `youj-labels-sidebar`, `youj-presets`, `youj-ui-core` with it.

The copy is 27 registry items, about 10,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `dialog`, `field`, `icon-engine`, `icon-loader-ring`, `icon-sidebar`, `input`, `label`, `presentation` and 8 more.

Use a sidebar for the navigation of an app with many destinations: groups of pages, projects, settings. Collapse it to icons to give the page room, or off the canvas entirely. Don't use it for a marketing site, where a [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu) previews sections from a top bar, or for a handful of views of one thing, where [Tabs](https://www.youj.dev/docs/components/tabs) keep them in place.

```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from '@youj/react'
import { HomeIcon, SendIcon } from '@youj/icons'

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Platform</SidebarGroupLabel>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton isActive tooltip="Home" render={<a href="/" aria-current="page" />}>
                  <HomeIcon size={16} />
                  <span>Home</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
              <SidebarMenuItem>
                <SidebarMenuButton tooltip="Deployments" render={<a href="/deployments" />}>
                  <SendIcon size={16} />
                  <span>Deployments</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
      <SidebarInset>
        <header>
          <SidebarTrigger />
        </header>
        {children}
      </SidebarInset>
    </SidebarProvider>
  )
}
```

[Build an app frame](https://www.youj.dev/docs/guides/build-an-app-frame) puts this sidebar together with a top bar, the account menu and search, in one file. `SidebarProvider` wraps the whole shell and holds the open state. `Sidebar` is the panel, with a `SidebarHeader`, a scrolling `SidebarContent` and a `SidebarFooter`. `SidebarInset` is the page beside it, rendered as your `main`. Menu buttons render links through `render`, so they work with your router's link component.

The previews on this page sit inside a fixed-height frame. In an app, the provider fills the viewport and the sidebar stays in place while the page scrolls.

### Collapsing

`collapsible` decides what collapsing does: `icon` narrows the sidebar to a rail of icons, `offcanvas` (the default) slides it out of view, and `none` keeps it fixed open. The `SidebarTrigger` button, ⌘B or Ctrl+B, and a click on the `SidebarRail` along its edge all toggle it. Collapsing never remounts an item, so keyboard focus stays where it was.

Pass `defaultOpen` to choose the starting state, or `open` and `onOpenChange` to control it. Every toggle also writes a `sidebar_state` cookie, so a server can render the sidebar the way it was left:

```tsx title="app/layout.tsx"
import { cookies } from 'next/headers'

export default async function Layout({ children }: { children: React.ReactNode }) {
  const defaultOpen = (await cookies()).get('sidebar_state')?.value !== 'false'
  return <SidebarProvider defaultOpen={defaultOpen}>{children}</SidebarProvider>
}
```

`useSidebar()` reads the state from anywhere inside the provider: `state` (`'expanded'` or `'collapsed'`), `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile` and `toggleSidebar`.

### The current page

Mark the current page's button with `isActive` and give its link `aria-current="page"`: `isActive` places the key, and `aria-current` tells assistive technology. `SidebarContent`'s `indicator` sets how the key looks: `raised` (the default, the key's plane on a hairline), `fill` (a quiet gray fill, shadcn's look), `mark` (a short accent bar on the inline-start edge) or `none`, when your rows mark the page themselves. A tile that stays raised whatever the page (a workspace switcher, a rail's current area) is `SidebarMenuButton variant="raised"`. There is one key for the whole sidebar, so it glides between groups as the page changes. When the current page sits inside a closed nested group, or the sidebar is down to icons, the key moves to that group's own item. Keep nested panels mounted (`keepMounted` on `CollapsibleContent`, as in the first preview) so the key can find a page in a closed group.

### Menus

- **Nested pages:** wrap an item in a `Collapsible` rendered as the `SidebarMenuItem`, and list its pages in a `SidebarMenuSub` of `SidebarMenuSubButton`s. `CollapsibleChevron` turns with it.
- **Badges:** `SidebarMenuBadge` after a button shows a count or a shortcut on its end edge, every row's on one column. `variant="pill"` sets it on a well, and `tone="danger"` makes it loud, for something failed or overdue.
- **Cards:** `SidebarCard` is a raised card for the sidebar's foot or top (a setup checklist, a plan's meter, an upgrade). It steps aside while the sidebar is folded to icons.
- **Actions:** `SidebarMenuAction` adds a small button beside an item, and `SidebarGroupAction` beside a group's label. `showOnHover` hides an item's action until the item is hovered or focused.
- **Loading:** `SidebarMenuSkeleton` stands in for an item while it loads. Add `showIcon` for a leading icon.
- **Search:** `SidebarInput` is an input sized for the sidebar, and it hides when the sidebar is down to icons.

Labels, badges and actions fade out before the width closes, and fade back in after it returns, so nothing squashes or truncates on the way. Group labels fold away, and nested lists close their height.

#### Nested groups

The `Collapsible` renders as the menu item and its trigger as the item's button, so the group keeps the row's size, key and tooltip:

```tsx
import {
  Collapsible,
  CollapsibleChevron,
  CollapsibleContent,
  CollapsibleTrigger,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
} from '@youj/react'
import { FolderIcon } from '@youj/icons'

export function ProjectNav() {
  return (
    <SidebarMenu>
      <Collapsible defaultOpen render={<SidebarMenuItem />}>
        <CollapsibleTrigger render={<SidebarMenuButton tooltip="web" />}>
          <FolderIcon size={16} />
          <span>web</span>
          <CollapsibleChevron size={14} className="ms-auto text-fg-muted" />
        </CollapsibleTrigger>
        <CollapsibleContent keepMounted>
          <SidebarMenuSub>
            <SidebarMenuSubItem>
              <SidebarMenuSubButton href="/web/deployments" isActive aria-current="page">
                <span>Deployments</span>
              </SidebarMenuSubButton>
            </SidebarMenuSubItem>
            <SidebarMenuSubItem>
              <SidebarMenuSubButton href="/web/logs">
                <span>Logs</span>
              </SidebarMenuSubButton>
            </SidebarMenuSubItem>
          </SidebarMenuSub>
        </CollapsibleContent>
      </Collapsible>
    </SidebarMenu>
  )
}
```

`SidebarMenuSubButton` is a link; pass `render={<Link href="/web/logs" />}` for your router's. `keepMounted` lets the current page's key find a page in a closed group.

#### The account row

For the account at the foot of the sidebar, give [Account Menu](https://www.youj.dev/docs/components/account-menu) a `SidebarMenuButton` as its `trigger`. The whole row (avatar, name, email and chevron) opens the menu, and collapsed to icons it's the avatar alone, named by its tooltip:

```tsx
import { AccountMenu, Avatar, AvatarFallback, SidebarFooter, SidebarMenu, SidebarMenuButton, SidebarMenuItem } from '@youj/react'
import { ChevronsUpDownIcon } from '@youj/icons'

const user = { name: 'Ada Lovelace', email: 'ada@acme.com' }

export function AccountRow({ onSignOut }: { onSignOut: () => void }) {
  return (
    <SidebarFooter>
      <SidebarMenu>
        <SidebarMenuItem>
          <AccountMenu
            user={user}
            onSignOut={onSignOut}
            side="top"
            align="start"
            trigger={
              <SidebarMenuButton size="lg" tooltip={user.name} className="data-popup-open:bg-hover">
                <Avatar size="sm" className="size-8">
                  <AvatarFallback>AL</AvatarFallback>
                </Avatar>
                <span className="flex min-w-0 flex-1 flex-col leading-tight">
                  <span className="truncate font-medium text-fg">{user.name}</span>
                  <span className="truncate text-ui-sm text-fg-muted">{user.email}</span>
                </span>
                <ChevronsUpDownIcon size={14} className="ms-auto text-fg-muted" />
              </SidebarMenuButton>
            }
          />
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarFooter>
  )
}
```

Building your frame in [Create](https://www.youj.dev/create)? Its account card is this row, with the standard menu rows and the menu opening to the side when the sidebar is down to icons.

#### Header text on the icon rail

Collapsed to icons, a `SidebarMenuButton` shows only its first child: the rest fades out. So put the brand in the header as a menu button, mark first, and it collapses to the mark on its own:

```tsx
<SidebarHeader>
  <SidebarMenu>
    <SidebarMenuItem>
      <SidebarMenuButton size="lg" tooltip="Acme" render={<a href="/" />}>
        <AcmeLogo className="size-8" />
        <span className="truncate font-semibold">Acme</span>
      </SidebarMenuButton>
    </SidebarMenuItem>
  </SidebarMenu>
</SidebarHeader>
```

`SidebarHeader` and `SidebarFooter` are plain containers and leave anything else in them alone, since it may be something to keep on the rail. Hide other text there yourself with `group-data-[collapsible=icon]:hidden`, as in `<p className="px-2 text-ui-sm group-data-[collapsible=icon]:hidden">Free plan</p>`.

### Mobile

Below the `md` breakpoint, the sidebar becomes a sheet: a modal dialog that slides in from its edge, with a focus trap. The trigger and ⌘B open it, and Escape or a tap outside closes it. After a navigation, close it with `setOpenMobile(false)` from `useSidebar()`. The same `useIsMobile()` hook is exported from `@youj/react` for your own layouts.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### SidebarProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `true` |  |
| `open` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |

#### Sidebar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'left' \| 'right'` | `'left'` | 'left' is the inline-start edge (the right, under RTL). |
| `variant` | `'sidebar' \| 'floating' \| 'inset'` | `'sidebar'` |  |
| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | `'offcanvas'` |  |
| `surface` | `'solid' \| 'glass'` | `'solid'` | `glass` frosts the sidebar over whatever is behind it (a backdrop, an image), the phone's sheet too. |

#### SidebarMenuButton

It renders a `button`, or your element through `render`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | The current page: the sidebar's raised key sits under it. |
| `tooltip` | `ReactNode` |  | Shown beside the item while the sidebar is collapsed to icons. |
| `variant` | `'default' \| 'raised' \| 'outline'` | `'default'` |  |
| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` |  |

#### SidebarMenuSubButton

It renders an `a`, or your element through `render`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md'` | `'md'` |  |
| `isActive` | `boolean` | `false` | The current page: the sidebar's raised key sits under it. |

#### SidebarContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indicator` | `'raised' \| 'fill' \| 'mark' \| 'none'` | `'raised'` | How the current page is marked: a raised key (default), a quiet fill, an accent mark on the inline-start edge, or `none` when the rows mark it themselves. It glides from page to page. |

#### SidebarMenuBadge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'plain' \| 'pill'` | `'plain'` | `pill` sets the count on a well. |
| `tone` | `'default' \| 'danger'` | `'default'` | `danger` is the loud count: something failed or is overdue. |

#### SidebarMenuAction and SidebarMenuSkeleton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showOnHover` | `boolean` | `false` |  |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showIcon` | `boolean` | `false` |  |

The other parts add no props: `SidebarHeader`, `SidebarFooter`, `SidebarCard`, `SidebarGroup`, `SidebarGroupContent` and `SidebarSeparator` render `div`s, `SidebarMenu` and `SidebarMenuSub` render `ul`s, and their items render `li`s. `SidebarGroupLabel` and `SidebarGroupAction` take `render`. `SidebarTrigger` takes the props of [Button](https://www.youj.dev/docs/components/button).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Collapse and expand | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the width, frame by frame |
| Labels out | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | labels, badges and actions, before the width closes |
| Labels in | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | after a `fast` delay, once the width is back |
| Group labels | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | fold away as the menu below rises into their place |
| Nested lists | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | close their height |
| Off-canvas | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the panel slides out as the space closes over it |
| Current page | `spring.smooth` | 0.36s, bounce 0 | the raised key glides across groups |
| Collapsed tooltip | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the `yj-tooltip` preset, on the inline-end side |
| Mobile sheet | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the `yj-sheet` preset; it leaves on `base` |

**Reduced motion:** The sidebar collapses and expands at once, the key jumps to the current page, and tooltips and the mobile sheet appear without moving.

#### Reduced motion

Everything still works, without movement: the sidebar snaps between widths, labels appear and disappear in place, the current-page key jumps, and tooltips and the mobile sheet appear at once.

### Accessibility

- `SidebarTrigger` is a button named "Toggle sidebar", with `aria-expanded` and `aria-keyshortcuts="Meta+B Control+B"`.
- ⌘B and Ctrl+B toggle the sidebar, but never while you type in a field (it's bold there), and not on key repeat. The shortcut listens on the window but acts on one sidebar at a time: with several `SidebarProvider`s on a page, the one you last clicked or focused in (the first on the page until then).
- The rail is a pointer shortcut. It's hidden from assistive technology and out of the tab order, so the trigger is the one toggle.
- Collapsed to icons, labels stay in the document: each item keeps its accessible name, and its tooltip shows the label to sighted users on hover and focus.
- The sidebar renders plain containers. Wrap its menus in a `nav` with an `aria-label` to make your primary navigation a landmark.
- On mobile, the sheet is a modal dialog named "Sidebar". It traps focus, closes on Escape, and returns focus to the trigger.

---

# Account Menu

> Give signed-in users a menu for their account, workspaces, theme and sign-out action.

Source: https://www.youj.dev/docs/components/account-menu

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ThemeScope, presetById, type ColorMode } from '@youj/core'
import { CreditCardIcon, KeyboardIcon, SettingsIcon, UserIcon } from '@youj/icons'
import {
  AccountMenu,
  Button,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuShortcut,
} from '@youj/react'

const WORKSPACES = [
  { id: 'northwind', name: 'Northwind Labs' },
  { id: 'acme', name: 'Acme Corp' },
  { id: 'personal', name: 'Personal' },
]

export default function AccountMenuDemo() {
  const [workspace, setWorkspace] = useState('northwind')
  const [theme, setTheme] = useState('basalt')
  const [mode, setMode] = useState<ColorMode>('dark')
  const [signedOut, setSignedOut] = useState(false)

if (signedOut) {
    return (
      <Button variant="outline" onClick={() => setSignedOut(false)}>
        Sign back in
      </Button>
    )
  }

return (
    // The menu only reports the choice; here a ThemeScope applies the preset to the card, menu included.
    <ThemeScope theme={presetById(theme)}>
      <div className="flex w-[22rem] max-w-full items-center justify-between gap-4 rounded-xl border border-line bg-surface p-4 text-ui shadow-xs">
        <div className="flex min-w-0 flex-col">
          <span className="truncate font-medium text-fg">{WORKSPACES.find((w) => w.id === workspace)?.name}</span>
          <span className="text-ui-sm text-fg-muted">
            {presetById(theme).name} · {mode}
          </span>
        </div>
        <div className="flex items-center gap-2">
          <Button size="sm" variant="outline">
            Invite
          </Button>
          <AccountMenu
            user={{ name: 'Ada Lovelace', email: 'ada@northwind.dev' }}
            workspaces={WORKSPACES}
            workspace={workspace}
            onWorkspaceChange={setWorkspace}
            theme={theme}
            onThemeChange={setTheme}
            colorMode={mode}
            onColorModeChange={setMode}
            onSignOut={() => setSignedOut(true)}
          >
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <UserIcon size={16} strokeWidth={1.75} />
                Profile
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CreditCardIcon size={16} strokeWidth={1.75} />
                Billing
              </DropdownMenuItem>
              <DropdownMenuItem>
                <SettingsIcon size={16} strokeWidth={1.75} />
                Settings
                <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
              </DropdownMenuItem>
              <DropdownMenuItem>
                <KeyboardIcon size={16} strokeWidth={1.75} />
                Keyboard shortcuts
                <DropdownMenuShortcut>?</DropdownMenuShortcut>
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </AccountMenu>
        </div>
      </div>
    </ThemeScope>
  )
}
```

An avatar menu with workspaces, theme and appearance choices, and a sign-out action; choosing a theme or mode restyles the card beside it.

The Theme submenu lists every preset `@youj/core` ships (`themes`), and the current one's name sits beside the row. The menu only reports what was chosen. Apply it where your app keeps its theme, with a [Youj Provider](https://www.youj.dev/docs/theming) or, as the preview does, a `ThemeScope` around part of the page:

```tsx
import { useState } from 'react'
import { AccountMenu, type AccountMenuUser } from '@youj/react'
import { ThemeScope, presetById, type ColorMode } from '@youj/core'

export function ThemedAccount({ user }: { user: AccountMenuUser }) {
  const [theme, setTheme] = useState('basalt')
  const [mode, setMode] = useState<ColorMode>('dark')

return (
    <ThemeScope theme={presetById(theme)}>
      <AccountMenu user={user} theme={theme} onThemeChange={setTheme} colorMode={mode} onColorModeChange={setMode} />
    </ThemeScope>
  )
}
```

Pass only `colorMode` for an appearance choice without presets, or only `theme` for presets without it.

### Minimal

```tsx
'use client'

import { AccountMenu, toast } from '@youj/react'

export default function AccountMenuMinimal() {
  return (
    // Just who you are and a way out. A long name and address truncate.
    <AccountMenu
      user={{
        name: 'Maximiliana Featherstonehaugh-Worthington',
        email: 'maximiliana.featherstonehaugh@a-very-long-domain.example',
      }}
      align="center"
      onSignOut={() => toast('Signed out')}
    />
  )
}
```

A menu with only a user and a sign-out action, using a very long name and address.

With just a user and `onSignOut`, it's who you are and a way out. Long names and addresses truncate instead of widening the menu.

`align` and `side` place the menu against the avatar. It aligns to the end by default, which suits the corner of a header. Choose `side="top"` at the foot of a sidebar.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add account-menu
```

It brings `avatar`, `dropdown-menu`, `icon-log-out`, `icon-theme`, `youj-core`, `youj-labels-account-menu`, `youj-presets`, `youj-ui-core` with it.

The copy is 14 registry items, about 8,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `dropdown-menu`, `icon-check`, `icon-chevron-right`, `icon-engine`, `icon-log-out`, `icon-theme`, `presentation`, `sliding-indicator`.

Use it at the end of an [App Header](https://www.youj.dev/docs/components/app-header) or at the foot of a [Sidebar](https://www.youj.dev/docs/components/sidebar): the one place a person finds their profile, settings, theme and the way out. It's a [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) with the account parts already laid out, so build your own dropdown when the menu isn't about the signed-in user. When switching workspaces is a main job in the app, give it a [Workspace Switcher](https://www.youj.dev/docs/components/workspace-switcher) of its own.

```tsx
import {
  AccountMenu,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuShortcut,
  type AccountMenuUser,
} from '@youj/react'

export function Account({ user, onSignOut }: { user: AccountMenuUser; onSignOut: () => void }) {
  return (
    <AccountMenu user={user} onSignOut={onSignOut}>
      <DropdownMenuGroup>
        <DropdownMenuItem>Profile</DropdownMenuItem>
        <DropdownMenuItem>
          Settings
          <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuGroup>
    </AccountMenu>
  )
}
```

The trigger is the user's avatar, with their initials until the image loads (or if it fails). The menu opens with a profile header: a larger avatar, the name and the email, each truncated when it runs long. Then, in order and each behind a separator:

1. **Workspaces**, when you pass `workspaces`: a radio group of logos and names, with a check on `workspace`. `onWorkspaceChange` reports a choice.
2. **Your items**: `children`, any [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) rows and groups.
3. **Theme**, when you pass `theme` or `colorMode`: a submenu with the built-in presets, each wearing its accent, and an appearance choice of light, dark or system.
4. **Sign out**, when you pass `onSignOut`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `user` (required) | `AccountMenuUser` |  |  |
| `workspaces` | `AccountMenuWorkspace[]` |  | Workspaces to switch between, shown as a radio group. |
| `workspace` | `string` |  |  |
| `onWorkspaceChange` | `(id: string) => void` |  |  |
| `theme` | `string` |  | The active preset's id (`graphite`, `terminal`…). The Theme submenu shows when this or `colorMode` is set. |
| `onThemeChange` | `(id: string) => void` |  |  |
| `colorMode` | `'system' \| 'light' \| 'dark'` |  |  |
| `onColorModeChange` | `(mode: ColorMode) => void` |  |  |
| `onSignOut` | `() => void` |  | Adds Sign out at the end. |
| `children` | `ReactNode` |  | Your own rows, between the profile and the theme: DropdownMenuItem, DropdownMenuShortcut, groups. |
| `align` | `'end' \| 'start' \| 'center'` | `'end'` |  |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom' \| 'inline-end' \| 'inline-start'` |  |  |
| `trigger` | `ReactElement<Record<string, unknown>>` |  | Your own trigger in place of the avatar, e.g. a sidebar's account card or a status pill: an element the trigger renders as, with its content inside. It keeps the menu's accessible name unless it brings its own. |
| `className` | `string` |  | The trigger's class. |

### Motion

The motion is the [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu)'s.

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | grows out of the avatar: scale .96 → 1 and fade (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Highlight | `spring.smooth` | 0.36s, bounce 0 | one Sliding Indicator glides between rows |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws in on the chosen workspace, preset or appearance |
| Trigger ring | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | appears around the avatar while the menu is open |
| Theme and Sign out icons |  | per icon | play as their row is highlighted |

**Reduced motion:** The menu and its submenu appear at once, the highlight jumps between rows, and checks appear already drawn.

#### Reduced motion

The menu opens and closes at once, the highlight moves from row to row without gliding, and checks appear already drawn. Keyboard handling and submenus work the same.

### Accessibility

- The trigger is a button named "Account: " and the user's name. The avatars inside are decorative.
- Everything else is the Dropdown Menu's: roving focus with ↑ and ↓, typeahead, Home and End, and Escape to close and return focus to the avatar.
- The Theme row opens its submenu on → (← to come back), mirrored in right-to-left layouts. Workspaces, presets and appearance are radio groups, so the chosen one is announced as checked.
- Each preset's color dot is decorative; its name is the label.

---

# Workspace Switcher

> Find and switch between teams, organizations or projects, or create a new one.

Source: https://www.youj.dev/docs/components/workspace-switcher

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { WorkspaceSwitcher, type Workspace } from '@youj/react/workspace-switcher'

const SEED: Workspace[] = [
  { id: 'northwind', name: 'Northwind Labs', detail: 'Pro · 12 members' },
  { id: 'acme', name: 'Acme Corp', detail: 'Enterprise · 148 members' },
  { id: 'globex', name: 'Globex', detail: 'Free · 3 members' },
  { id: 'personal', name: 'Personal', detail: 'Hobby' },
]

export default function WorkspaceSwitcherDemo() {
  const [workspaces, setWorkspaces] = useState(SEED)
  const [value, setValue] = useState('northwind')

return (
    <div className="w-64 rounded-xl border border-line bg-chrome p-2 shadow-xs">
      <WorkspaceSwitcher
        workspaces={workspaces}
        value={value}
        onValueChange={setValue}
        className="w-full"
        // Type a name that isn't there, then press Enter on "Create workspace".
        onCreate={(name) => {
          const id = `ws-${workspaces.length + 1}`
          setWorkspaces((list) => [...list, { id, name: name || 'Untitled workspace', detail: 'Free · 1 member' }])
          setValue(id)
        }}
      />
      <div className="mt-2 flex flex-col gap-1 border-t border-line px-1.5 pt-3 pb-1">
        {['Projects', 'Deployments', 'Members'].map((label) => (
          <span key={label} className="h-7 rounded-md px-1.5 text-ui leading-7 text-fg-muted">
            {label}
          </span>
        ))}
      </div>
    </div>
  )
}
```

A switcher in a small sidebar card; searching for a name that doesn't exist offers to create it.

### Compact

```tsx
'use client'

import { useState } from 'react'
import { FolderIcon, HomeIcon, SettingsIcon, UsersIcon } from '@youj/icons'
import { Button } from '@youj/react'
import { WorkspaceSwitcher, type Workspace } from '@youj/react/workspace-switcher'

const WORKSPACES: Workspace[] = [
  { id: 'northwind', name: 'Northwind Labs', detail: 'Pro · 12 members' },
  { id: 'acme', name: 'Acme Corp', detail: 'Enterprise · 148 members' },
  { id: 'personal', name: 'Personal', detail: 'Hobby' },
]

export default function WorkspaceSwitcherCompact() {
  const [value, setValue] = useState('acme')

return (
    // A sidebar collapsed to icons: the switcher shrinks to its logo, and the popup opens beside the rail.
    <nav aria-label="Workspace" className="flex h-72 flex-col items-center gap-1 rounded-xl border border-line bg-chrome p-2 shadow-xs">
      <WorkspaceSwitcher compact workspaces={WORKSPACES} value={value} onValueChange={setValue} side="inline-end" />
      <span aria-hidden className="my-1 h-px w-6 bg-line" />
      {[
        { label: 'Home', icon: <HomeIcon size={18} strokeWidth={1.75} /> },
        { label: 'Projects', icon: <FolderIcon size={18} strokeWidth={1.75} /> },
        { label: 'Members', icon: <UsersIcon size={18} strokeWidth={1.75} /> },
      ].map((item) => (
        <Button key={item.label} variant="ghost" size="icon" aria-label={item.label}>
          {item.icon}
        </Button>
      ))}
      <Button variant="ghost" size="icon" aria-label="Settings" className="mt-auto">
        <SettingsIcon size={18} strokeWidth={1.75} />
      </Button>
    </nav>
  )
}
```

A logo-only switcher at the top of an icon rail, opening its list beside the rail.

`compact` shows only the logo, for a sidebar collapsed to icons. The name moves into the trigger's accessible name, and `side` opens the list beside the rail instead of below it.

## Installation & usage

```bash
pnpm add @youj/react cmdk
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add workspace-switcher
```

It brings `avatar`, `command`, `icon-chevrons-up-down`, `icon-plus`, `popover`, `youj-core`, `youj-labels-workspace-switcher`, `youj-presets`, `youj-ui-core` with it.

The copy is 28 registry items, about 10,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `button`, `checkbox`, `collapse`, `command`, `dialog`, `field`, `icon-check`, `icon-chevrons-up-down`, `icon-engine` and 9 more.

Requires `cmdk`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/workspace-switcher`.

Use it at the top of a [Sidebar](https://www.youj.dev/docs/components/sidebar), or at the start of an [App Header](https://www.youj.dev/docs/components/app-header), when people belong to several workspaces and move between them often. The trigger always says which one they're in. The list is searchable, so it holds up at 3 workspaces or 300. For a short list that sits among other account items, the `workspaces` option of the [Account Menu](https://www.youj.dev/docs/components/account-menu) is enough.

```tsx
import { WorkspaceSwitcher, type Workspace } from '@youj/react/workspace-switcher'

const workspaces: Workspace[] = [
  { id: 'northwind', name: 'Northwind Labs', detail: 'Pro · 12 members' },
  { id: 'acme', name: 'Acme Corp', detail: 'Enterprise · 148 members' },
]

export function Switcher() {
  const [workspace, setWorkspace] = useState('northwind')
  return <WorkspaceSwitcher workspaces={workspaces} value={workspace} onValueChange={setWorkspace} onCreate={createWorkspace} />
}
```

Each workspace has an `id`, a `name`, an optional `logo` (its initials show until the image loads, or if it fails) and an optional `detail` line such as the plan or member count. The trigger shows the current one, and the list marks it with a check. It's controlled with `value` and `onValueChange`, or uncontrolled with `defaultValue`.

### Creating a workspace

Pass `onCreate` and a "Create workspace" row sits under the list. It carries what was typed in the search, so someone who looks for a workspace that isn't there can press Enter to create it with that name: with no match left, the create row is the active one. `onCreate` receives the trimmed search text, which is empty when nothing was typed. Rename the row with `createLabel`. Search is plain substring matching, so a new name never fuzzily matches an existing one.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workspaces` (required) | `Workspace[]` |  |  |
| `value` | `string` |  |  |
| `defaultValue` | `string` |  |  |
| `onValueChange` | `(id: string) => void` |  |  |
| `onCreate` | `(name: string) => void` |  | Adds the "Create workspace" row. Receives what was typed in the search. |
| `createLabel` | `string` |  |  |
| `searchPlaceholder` | `string` |  |  |
| `compact` | `boolean` | `false` | Only the logo: for a sidebar collapsed to icons. |
| `align` | `'end' \| 'start' \| 'center'` | `'start'` |  |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom' \| 'inline-end' \| 'inline-start'` |  |  |
| `className` | `string` |  | The trigger's class. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, from the trigger (`yj-pop`) |
| Close | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Chevrons |  | per icon | part while the list is open (`ChevronsUpDownIcon`) |
| Highlight | `spring.smooth` | 0.36s, bounce 0 | the active row’s background glides with ↑ and ↓ |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws in on the current workspace |
| Trigger hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | background |

**Reduced motion:** The list opens and closes at once, the highlight jumps between rows, and the check appears already drawn.

#### Reduced motion

The popover appears and disappears at once, the highlight moves between rows without gliding, and the chevrons and check change without animating. Search, focus and keyboard handling work the same.

### Accessibility

- The trigger is a button named after the current workspace ("Northwind Labs, switch workspace"), which also covers the compact trigger. The logos are decorative.
- It opens with Enter, Space or ↓, and focus lands in the search field. ↑ and ↓ move the active row, Enter chooses it, and Escape closes the list and returns focus to the trigger.
- The list is the [Command](https://www.youj.dev/docs/components/command) listbox, so the active row is announced as you move, and the current workspace as selected. Each row's detail is read after its name.
- The search clears once the list has closed, so it opens fresh next time.

---

# Notification Center

> Collect notifications behind a bell, with unread counts, filters and actions.

Source: https://www.youj.dev/docs/components/notification-center

## Examples

### Demo

```tsx
'use client'

import { useRef, useState } from 'react'
import { AlertTriangleIcon, RocketIcon } from '@youj/icons'
import { Button, NotificationCenter, useNotificationToasts, type NotificationItem } from '@youj/react'

const minutes = (n: number) => new Date(Date.now() - n * 60_000)
const days = (n: number) => new Date(Date.now() - n * 86_400_000)

const INBOX: NotificationItem[] = [
  {
    id: 'n1',
    actor: { name: 'Mira Chen' },
    title: 'mentioned you in Q3 roadmap',
    body: '“@you can we get the chart kit into the dashboard before the review?”',
    time: minutes(3),
    mention: true,
    actions: [
      { label: 'Reply', onClick: () => {}, variant: 'default' },
      { label: 'Open doc', onClick: () => {} },
    ],
  },
  { id: 'n2', icon: RocketIcon, title: 'web@4f2c91a is live in production', body: 'Build 38s · 14 regions', time: minutes(18) },
  {
    id: 'n3',
    actor: { name: 'Jonas Weber' },
    title: 'invited you to youj/infra',
    time: minutes(64),
    actions: [
      { label: 'Accept', onClick: () => {}, variant: 'default' },
      { label: 'Decline', onClick: () => {} },
    ],
  },
  { id: 'n4', icon: AlertTriangleIcon, title: 'Error rate on /api/checkout recovered', time: days(1), read: true },
  { id: 'n5', actor: { name: 'Priya Natarajan' }, title: 'approved your pull request #479', time: days(2), read: true },
]

const ARRIVALS: Omit<NotificationItem, 'id' | 'time'>[] = [
  { actor: { name: 'Kenji Mori' }, title: 'assigned you KIN-231', body: 'Chart tooltips should follow keyboard focus' },
  { icon: RocketIcon, title: 'Preview ready for feat/notifications' },
  { actor: { name: 'Inès Laurent' }, title: 'mentioned you in Research notes', mention: true, body: '“@you the avatar stack tested well.”' },
]

export default function NotificationCenterDemo() {
  const [items, setItems] = useState(INBOX)
  const [open, setOpen] = useState(false)
  const sent = useRef(0)

// While the panel is closed, each arrival also shows as a toast (the app renders one <Toaster />).
  useNotificationToasts(items, { enabled: !open })

const simulate = () => {
    const next = ARRIVALS[sent.current % ARRIVALS.length]!
    sent.current++
    setItems((list) => [{ ...next, id: `live-${sent.current}`, time: new Date() }, ...list])
  }

return (
    <header className="flex w-full max-w-2xl items-center gap-3 rounded-xl border border-line bg-surface px-4 py-2.5">
      <span className="text-ui font-semibold whitespace-nowrap">youj</span>
      <span className="text-ui whitespace-nowrap text-fg-muted">/ web</span>
      <div className="ms-auto flex items-center gap-2">
        <Button variant="outline" size="sm" onClick={simulate}>
          Simulate notification
        </Button>
        <NotificationCenter
          notifications={items}
          open={open}
          onOpenChange={setOpen}
          onMarkRead={(id) => setItems((list) => list.map((item) => (item.id === id ? { ...item, read: true } : item)))}
          onMarkAllRead={() => setItems((list) => list.map((item) => ({ ...item, read: true })))}
        />
      </div>
    </header>
  )
}
```

A bell in a header with an inbox of mentions, deployments and invitations, and a button that simulates a new notification.

### Empty states

```tsx
'use client'

import { useState } from 'react'
import { NotificationCenter, type NotificationItem } from '@youj/react'

export default function NotificationCenterEmpty() {
  const [items, setItems] = useState<NotificationItem[]>([])

return (
    <div className="flex flex-col items-center gap-3 text-ui text-fg-muted">
      <span>Nothing new</span>
      <NotificationCenter
        notifications={items}
        onMarkRead={(id) => setItems((list) => list.map((item) => (item.id === id ? { ...item, read: true } : item)))}
        onMarkAllRead={() => setItems((list) => list.map((item) => ({ ...item, read: true })))}
      />
    </div>
  )
}
```

A bell with no notifications, showing the empty state.

Each tab has its own empty state: "No notifications", "You're all caught up" once everything is read, and "No mentions".

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add notification-center
```

It brings `avatar`, `button`, `counter`, `empty`, `icon-bell`, `icon-check`, `icon-engine`, `icon-inbox`, `popover`, `presence-list`, `scroll-area`, `sheet`, `tabs`, `timeline`, `toast`, `use-mobile`, `use-now`, `youj-core`, `youj-labels-notification-center`, `youj-presets`, `youj-ui-core` with it.

The copy is 52 registry items, about 12,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `avatar`, `button`, `collapse`, `collapsible`, `counter`, `dialog`, `empty`, `icon-alert-triangle`, `icon-bell` and 30 more.

Use a notification center for things that happened while someone was away and that they'll act on later: mentions, invites, deploys, alerts. Press the bell to open it, or simulate an arrival and watch the bell swing and the count roll. For a message about something that just happened in front of the person, use a [Toast](https://www.youj.dev/docs/components/toast). For a history of events on one object, use a [Timeline](https://www.youj.dev/docs/components/timeline).

```tsx
import { NotificationCenter, type NotificationItem } from '@youj/react'

export function Inbox({ items }: { items: NotificationItem[] }) {
  return (
    <NotificationCenter
      notifications={items}
      onMarkRead={(id) => markRead(id)}
      onMarkAllRead={() => markAllRead()}
    />
  )
}
```

The center reads the list you pass and never changes it: marking read calls `onMarkRead` or `onMarkAllRead`, and you pass back the updated list. Each item has an `id`, a `title` and a `time`, and optionally:

- `actor`, the person who did it (their avatar shows beside it), or an `icon` for system events.
- `body`, a second line, clamped to two lines.
- `read`. Unread items carry a dot and count towards the badge.
- `mention`, which lists the item under Mentions.
- `actions`, buttons under the item, such as Reply or Accept.
- `summary`, plain text for announcements and toasts when `title` isn't a string.

It opens in a [Popover](https://www.youj.dev/docs/components/popover) aligned to the bell's end on desktop, and in a bottom [Sheet](https://www.youj.dev/docs/components/sheet) below the `md` breakpoint.

### Arrivals and toasts

A notification whose `id` wasn't in the previous list is an arrival. If it's unread, the bell swings once and it's announced. With the panel open, it takes its slot at the top of the list and the rest glide down.

`useNotificationToasts` also shows a [Toast](https://www.youj.dev/docs/components/toast) for each arrival. Pass `enabled: !open` so arrivals toast only while the panel is closed, and render one `<Toaster />` in the app, as the Demo story does.

```tsx
import { useState } from 'react'
const [open, setOpen] = useState(false)
useNotificationToasts(items, { enabled: !open })

<NotificationCenter notifications={items} open={open} onOpenChange={setOpen} />
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `notifications` (required) | `readonly NotificationItem[]` |  |  |
| `onMarkRead` | `(id: string) => void` |  |  |
| `onMarkAllRead` | `() => void` |  |  |
| `open` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `now` | `Date \| number` |  | The moment Today and relative times count from, pinned (a demo's clock, a test). Default: the clock when the list opens. |
| `className` | `string` |  |  |

`useNotificationToasts(items, { enabled })` takes the same list, and toasts every arrival while `enabled` (default `true`).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Bell swing | `duration.deliberate` | 560ms | The Youj BellIcon swings once per arrival; a second arrival mid-swing extends it |
| Count | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the number rolls to its new value (Counter, `roll`) |
| Badge | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | pops in from scale 0 on the first unread |
| Arrival | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | rises into its slot at the top and fades in (PresenceList) |
| Removal | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades out, as when an item leaves the Unread tab |
| Reflow | `spring.smooth` | 0.36s, bounce 0 | the rest of the list glides to its new place |
| Unread dot | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | fades and shrinks to half when read |
| Tab indicator | `spring.smooth` | 0.36s, bounce 0 | glides to the chosen filter (SlidingIndicator) |

**Reduced motion:** The bell doesn't swing and the badge doesn't pop; the count and the list change in place.

#### Reduced motion

The bell stays still, the badge appears without the pop and new or removed items change the list in place. Arrivals are still announced, and toasts still show.

### Accessibility

- The bell is a button whose name carries the count: "Notifications, 3 unread".
- Arrivals are announced politely: "New notification: Mira Chen mentioned you in Q3 roadmap".
- Unread items start with "Unread:" for screen readers, so the dot isn't the only signal.
- Mark as read, Mark all as read and every action are real buttons. Mark as read shows on hover and focus, and always on touch screens.
- Today and Earlier are labeled sections with their own headings, and the filters are [Tabs](https://www.youj.dev/docs/components/tabs) with arrow-key navigation.
- Times are `<time>` elements with a machine-readable `dateTime`.

---

# Chart

> Build charts with theme colors, shared motion and a table of the underlying values.

Source: https://www.youj.dev/docs/components/chart

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from 'recharts'
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  ToggleGroup,
  ToggleGroupItem,
} from '@youj/react'
import {
  ChartContainer,
  ChartDataTable,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  useChartMotion,
  type ChartConfig,
} from '@youj/react/chart'

type Range = '6m' | '12m'

const MONTHS = [
  { month: 'Oct', revenue: 31200, expenses: 26100 },
  { month: 'Nov', revenue: 33800, expenses: 26900 },
  { month: 'Dec', revenue: 39100, expenses: 28400 },
  { month: 'Jan', revenue: 36400, expenses: 29100 },
  { month: 'Feb', revenue: 40900, expenses: 29800 },
  { month: 'Mar', revenue: 44600, expenses: 30700 },
  { month: 'Apr', revenue: 48200, expenses: 31800 },
  { month: 'May', revenue: 51900, expenses: 32600 },
  { month: 'Jun', revenue: 49400, expenses: 33900 },
  { month: 'Jul', revenue: 58700, expenses: 34800 },
  { month: 'Aug', revenue: 63100, expenses: 36200 },
  { month: 'Sep', revenue: 71800, expenses: 37100 },
]

const config = {
  revenue: { label: 'Revenue', color: 'var(--color-chart-1)' },
  expenses: { label: 'Expenses', color: 'var(--color-chart-4)' },
} satisfies ChartConfig

const usd = (value: number) => `$${value.toLocaleString('en-US')}`
const compact = (value: number) => `$${Math.round(value / 1000)}k`

export default function RevenueChart() {
  const [range, setRange] = useState<Range>('6m')
  const motion = useChartMotion()
  const data = range === '6m' ? MONTHS.slice(-6) : MONTHS
  const first = data[0]!.revenue
  const last = data[data.length - 1]!.revenue

return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle>Revenue</CardTitle>
        <CardDescription>Net revenue against operating expenses, {range === '6m' ? 'last 6 months' : 'last 12 months'}.</CardDescription>
        <CardAction>
          <ToggleGroup
            variant="segmented"
            size="sm"
            aria-label="Range"
            value={[range]}
            onValueChange={(value) => value[0] && setRange(value[0] as Range)}
          >
            <ToggleGroupItem value="6m">6M</ToggleGroupItem>
            <ToggleGroupItem value="12m">12M</ToggleGroupItem>
          </ToggleGroup>
        </CardAction>
      </CardHeader>
      <CardContent>
        <ChartContainer
          config={config}
          className="aspect-auto h-60 w-full"
          title="Revenue and expenses by month"
          summary={`Revenue grew from ${usd(first)} to ${usd(last)}; expenses rose more slowly.`}
        >
          <AreaChart data={data} margin={{ left: 4, right: 12, top: 8 }}>
            <defs>
              <linearGradient id="revenue-wash" x1="0" y1="0" x2="0" y2="1">
                <stop offset="0%" stopColor="var(--color-revenue)" stopOpacity={0.28} />
                <stop offset="100%" stopColor="var(--color-revenue)" stopOpacity={0} />
              </linearGradient>
            </defs>
            <CartesianGrid vertical={false} strokeDasharray="3 3" />
            <XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} minTickGap={16} />
            <YAxis tickLine={false} axisLine={false} tickMargin={4} width={40} tickFormatter={compact} />
            <ChartTooltip cursor content={<ChartTooltipContent indicator="line" valueFormatter={(v) => usd(Number(v))} />} />
            <Area dataKey="revenue" type="monotone" fill="url(#revenue-wash)" stroke="var(--color-revenue)" strokeWidth={2} {...motion.draw(0)} />
            <Area
              dataKey="expenses"
              type="monotone"
              fill="transparent"
              stroke="var(--color-expenses)"
              strokeWidth={1.5}
              strokeDasharray="4 4"
              {...motion.draw(1)}
            />
            <ChartLegend content={<ChartLegendContent />} />
          </AreaChart>
        </ChartContainer>
      </CardContent>
      <CardFooter className="flex-col items-stretch gap-0 py-2">
        <ChartDataTable
          mode="toggle"
          data={data}
          config={config}
          labelKey="month"
          labelHeading="Month"
          caption="Revenue and expenses by month, in USD."
          valueFormatter={usd}
        />
      </CardFooter>
    </Card>
  )
}
```

A revenue and expenses chart with a six or twelve month range.

`ChartTooltip` is Recharts' `Tooltip` with Youj timing: it glides between points instead of jumping. Give it `ChartTooltipContent`, which reads labels from the config and formats each value with `valueFormatter`. `indicator` sets the swatch (`dot`, `line` or `dashed`), and `hideLabel` drops the heading for single-series charts. `ChartLegend` lists series in the order they're drawn, not alphabetically, and `ChartLegendContent` renders them with their config labels.

```tsx
<ChartTooltip content={<ChartTooltipContent indicator="line" valueFormatter={(v) => `$${Number(v).toLocaleString()}`} />} />
<ChartLegend content={<ChartLegendContent />} />
```

### Lines

```tsx
'use client'

import { CartesianGrid, Line, LineChart, XAxis, YAxis } from 'recharts'
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@youj/react'
import {
  ChartContainer,
  ChartDataTable,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  useChartMotion,
  type ChartConfig,
} from '@youj/react/chart'

const latency = [
  { hour: '00:00', p50: 82, p95: 210, p99: 390 },
  { hour: '03:00', p50: 79, p95: 198, p99: 362 },
  { hour: '06:00', p50: 88, p95: 231, p99: 420 },
  { hour: '09:00', p50: 104, p95: 286, p99: 541 },
  { hour: '12:00', p50: 112, p95: 302, p99: 588 },
  { hour: '15:00', p50: 108, p95: 277, p99: 512 },
  { hour: '18:00', p50: 97, p95: 251, p99: 466 },
  { hour: '21:00', p50: 86, p95: 219, p99: 401 },
]

const config = {
  p50: { label: 'p50', color: 'var(--color-chart-1)' },
  p95: { label: 'p95', color: 'var(--color-chart-3)' },
  p99: { label: 'p99', color: 'var(--color-chart-4)' },
} satisfies ChartConfig

export default function LatencyChart() {
  const motion = useChartMotion()
  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle>API latency</CardTitle>
        <CardDescription>Percentiles over the last 24 hours, in ms.</CardDescription>
      </CardHeader>
      <CardContent>
        <ChartContainer
          config={config}
          className="aspect-auto h-56 w-full"
          title="API latency percentiles"
          summary="Latency peaks around midday, with p99 reaching 588 ms at 12:00."
        >
          <LineChart data={latency} margin={{ left: 4, right: 12, top: 8 }}>
            <CartesianGrid vertical={false} />
            <XAxis dataKey="hour" tickLine={false} axisLine={false} tickMargin={8} />
            <YAxis tickLine={false} axisLine={false} width={36} tickMargin={4} />
            <ChartTooltip content={<ChartTooltipContent valueFormatter={(v) => `${v} ms`} />} />
            {(['p50', 'p95', 'p99'] as const).map((key, i) => (
              <Line key={key} dataKey={key} type="monotone" stroke={`var(--color-${key})`} strokeWidth={2} dot={false} {...motion.draw(i)} />
            ))}
            <ChartLegend content={<ChartLegendContent />} />
          </LineChart>
        </ChartContainer>
        <ChartDataTable data={latency} config={config} labelKey="hour" labelHeading="Hour" caption="Latency percentiles by hour, in ms." />
      </CardContent>
    </Card>
  )
}
```

Three latency percentiles over 24 hours sharing one axis.

Several series share one axis. `motion.draw(i)` staggers each later series a step behind the one before, so the lines arrive in the order the legend reads.

The `ChartDataTable` under this chart is visually hidden: screen readers get the numbers as a real table, sighted readers get the lines. The demo shows the other mode, `mode="toggle"`, a View data button that opens the table in place.

### Series color and trend

```tsx
'use client'

import { useEffect, useMemo, useRef, useState, type RefObject } from 'react'
import { Area, CartesianGrid, ComposedChart, Line, XAxis, YAxis } from 'recharts'
import { RotateCcwIcon, SlidersIcon, TrendingUpIcon } from '@youj/icons'
import {
  Button,
  Card,
  ColorPicker,
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuTrigger,
  SegmentedControl,
  SegmentedControlItem,
  Toggle,
} from '@youj/react'
import { ChartContainer, ChartTooltip, ChartTooltipContent, useChartMotion, type ChartConfig } from '@youj/react/chart'
import { linearTrend, sumEvery } from './trend-line'

const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
const LEADS = {
  y25: [402, 435, 506, 487, 549, 529, 446, 470, 566, 612, 590, 540],
  y24: [352, 383, 404, 436, 429, 460, 392, 400, 455, 498, 470, 436],
}

type Key = keyof typeof LEADS
type Period = 'month' | 'quarter'

const SERIES: { key: Key; label: string; token: string }[] = [
  { key: 'y25', label: '2025', token: 'var(--color-chart-1)' },
  { key: 'y24', label: '2024', token: 'var(--color-fg-subtle)' },
]

const sum = (values: number[]) => values.reduce((total, v) => total + v, 0)
const whole = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 })
const signed = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1, signDisplay: 'exceptZero' })

/** What a theme token paints right now, as hex: the picker needs a color, not a `var()`. Follows a change of theme. */
function useThemeColor(token: string, scope: RefObject<HTMLElement | null>) {
  const [hex, setHex] = useState('#808080')
  useEffect(() => {
    const read = () => {
      const probe = document.createElement('span')
      probe.style.color = token
      scope.current?.append(probe)
      const painted = getComputedStyle(probe).color
      probe.remove()
      const context = document.createElement('canvas').getContext('2d', { willReadFrequently: true })
      if (!context) return
      context.fillStyle = painted
      context.fillRect(0, 0, 1, 1)
      const [r = 0, g = 0, b = 0] = context.getImageData(0, 0, 1, 1).data
      setHex('#' + [r, g, b].map((c) => c.toString(16).padStart(2, '0')).join(''))
    }
    read()
    const watch = new MutationObserver(read)
    watch.observe(document.documentElement, { attributes: true })
    return () => watch.disconnect()
  }, [token, scope])
  return hex
}

export default function SeriesColorAndTrend() {
  const motion = useChartMotion()
  const card = useRef<HTMLDivElement>(null)
  const [period, setPeriod] = useState<Period>('month')
  const [trend, setTrend] = useState(true)
  const [area, setArea] = useState(true)
  const [points, setPoints] = useState(false)
  const [compare, setCompare] = useState(true)
  const [picked, setPicked] = useState<Partial<Record<Key, string>>>({})
  const themed: Record<Key, string> = {
    y25: useThemeColor(SERIES[0]!.token, card),
    y24: useThemeColor(SERIES[1]!.token, card),
  }

const quarterly = period === 'quarter'
  const rows = useMemo(() => {
    const labels = quarterly ? ['Q1', 'Q2', 'Q3', 'Q4'] : MONTHS
    const y25 = quarterly ? sumEvery(LEADS.y25, 3) : LEADS.y25
    const y24 = quarterly ? sumEvery(LEADS.y24, 3) : LEADS.y24
    const t25 = linearTrend(y25)
    const t24 = linearTrend(y24)
    return {
      slope: { y25: t25.slope, y24: t24.slope },
      data: labels.map((label, i) => ({ label, y25: y25[i]!, y24: y24[i]!, t25: t25.fitted[i]!, t24: t24.fitted[i]! })),
    }
  }, [quarterly])

const config = Object.fromEntries(SERIES.map((s) => [s.key, { label: s.label, color: picked[s.key] ?? s.token }])) as ChartConfig
  const total = { y25: sum(LEADS.y25), y24: sum(LEADS.y24) }
  const change = ((total.y25 - total.y24) / total.y24) * 100
  const shown = SERIES.filter((s) => compare || s.key === 'y25')
  const unit = quarterly ? 'a quarter' : 'a month'

return (
    <Card ref={card} data-slot="series-trend" className="w-full max-w-3xl gap-0 overflow-hidden py-0">
      <header className="flex flex-wrap items-start justify-between gap-x-4 gap-y-3 px-5 pt-5 pb-4">
        <div>
          <h3 className="text-ui font-semibold text-fg">Inbound leads</h3>
          <p className="mt-1 flex items-center gap-1.5 text-ui-sm text-fg-muted tabular-nums">
            <TrendingUpIcon size={16} className="text-success-text" />
            <span className="font-medium text-success-text">{signed.format(change)}%</span>
            vs 2024
          </p>
        </div>
        <div className="flex flex-wrap items-center gap-2">
          <SegmentedControl variant="pill" aria-label="Period" value={period} onValueChange={(value) => setPeriod(value as Period)}>
            <SegmentedControlItem value="month">Month</SegmentedControlItem>
            <SegmentedControlItem value="quarter">Quarter</SegmentedControlItem>
          </SegmentedControl>
          <DropdownMenu>
            <DropdownMenuTrigger render={<Button variant="outline" size="sm" />}>
              <SlidersIcon />
              Display
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end" className="w-48">
              <DropdownMenuCheckboxItem checked={compare} onCheckedChange={setCompare}>
                Compare with 2024
              </DropdownMenuCheckboxItem>
              <DropdownMenuCheckboxItem checked={area} onCheckedChange={setArea}>
                Area fill
              </DropdownMenuCheckboxItem>
              <DropdownMenuCheckboxItem checked={points} onCheckedChange={setPoints}>
                Points
              </DropdownMenuCheckboxItem>
            </DropdownMenuContent>
          </DropdownMenu>
          <Toggle variant="outline" size="sm" pressed={trend} onPressedChange={setTrend}>
            Linear trend
          </Toggle>
        </div>
      </header>

<div className="px-3 pb-4">
        <ChartContainer
          config={config}
          className="aspect-auto h-64 w-full"
          title="Inbound leads, 2025 against 2024"
          summary={`${whole.format(total.y25)} leads in 2025, ${signed.format(change)}% on 2024, with a dashed linear trend line per year when it is on.`}
        >
          <ComposedChart data={rows.data} margin={{ left: 4, right: 16, top: 8 }}>
            <CartesianGrid vertical={false} />
            <XAxis dataKey="label" tickLine={false} axisLine={false} tickMargin={8} />
            <YAxis tickLine={false} axisLine={false} width={40} tickMargin={4} tickFormatter={(v: number) => whole.format(v)} />
            <ChartTooltip
              content={
                <ChartTooltipContent
                  labelFormatter={(label, payload) => {
                    const row = payload[0]?.payload as { y25: number; y24: number } | undefined
                    const delta = row ? ((row.y25 - row.y24) / row.y24) * 100 : 0
                    return (
                      <span className="flex items-baseline justify-between gap-4">
                        {label}
                        {compare && <span className="font-normal text-success-text tabular-nums">{signed.format(delta)}%</span>}
                      </span>
                    )
                  }}
                  valueFormatter={(value) => whole.format(Number(value))}
                />
              }
            />
            {shown.map((s, i) => (
              <Area
                key={s.key}
                dataKey={s.key}
                type="monotone"
                stroke={`var(--color-${s.key})`}
                strokeWidth={2}
                fill={`var(--color-${s.key})`}
                fillOpacity={area ? 0.1 : 0}
                dot={points ? { r: 3, strokeWidth: 0, fill: `var(--color-${s.key})` } : false}
                activeDot={{ r: 4 }}
                {...motion.draw(i)}
              />
            ))}
            {trend &&
              shown.map((s, i) => (
                <Line
                  key={`trend-${s.key}`}
                  dataKey={s.key === 'y25' ? 't25' : 't24'}
                  type="linear"
                  stroke={`var(--color-${s.key})`}
                  strokeWidth={1.5}
                  strokeDasharray="5 4"
                  dot={false}
                  activeDot={false}
                  legendType="none"
                  tooltipType="none"
                  {...motion.draw(i + 2)}
                />
              ))}
          </ComposedChart>
        </ChartContainer>
      </div>

<footer className="flex flex-wrap items-center gap-x-5 gap-y-2 border-t border-line px-5 py-3 text-ui-sm">
        {shown.map((s) => (
          <div key={s.key} className="flex items-center gap-1 first:-ms-1.5">
            <ColorPicker
              swatchOnly
              aria-label={`${s.label} color`}
              value={picked[s.key] ?? themed[s.key]}
              onValueChange={(value) => setPicked((current) => ({ ...current, [s.key]: value }))}
            />
            <span className="text-fg-muted">{s.label}</span>
            <span className="font-medium text-fg tabular-nums">{whole.format(total[s.key])}</span>
            <Button
              variant="ghost"
              size="icon-sm"
              aria-label={`Reset ${s.label} to the theme color`}
              disabled={picked[s.key] === undefined}
              onClick={() => setPicked(({ [s.key]: _, ...rest }) => rest)}
            >
              <RotateCcwIcon />
            </Button>
          </div>
        ))}
        <p className="ms-auto text-fg-muted tabular-nums" aria-live="polite">
          {trend ? (
            <>
              Linear trend <span className="font-medium text-fg">{signed.format(Math.round(rows.slope.y25))}</span> {unit}
            </>
          ) : (
            'Trend off'
          )}
        </p>
      </footer>
    </Card>
  )
}
```

Two years of inbound leads with a Month or Quarter view, a Display menu, a linear trend and a color for each series.

The trend is a plain Recharts `Line` over a second field in each row: a least-squares line fitted to that series, drawn dashed in its color and left out of the tooltip with `tooltipType="none"`. The fit is a small pure function, `linearTrend(values)`, in the example's source, so the line follows whichever period is on show. Each swatch in the footer is a `ColorPicker` with `swatchOnly`: the series color goes into the `ChartConfig`, so the area, the line, the trend and the tooltip all follow, and reset puts back the theme's chart color. The tooltip heading carries the change on the year before.

### Bars and live data

```tsx
'use client'

import { useState } from 'react'
import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from 'recharts'
import {
  Button,
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@youj/react'
import {
  ChartContainer,
  ChartDataTable,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  useChartMotion,
  type ChartConfig,
} from '@youj/react/chart'

const WEEKS = [
  { week: 'W32', production: 42, preview: 118, failed: 4 },
  { week: 'W33', production: 38, preview: 131, failed: 7 },
  { week: 'W34', production: 51, preview: 144, failed: 3 },
  { week: 'W35', production: 47, preview: 126, failed: 5 },
  { week: 'W36', production: 58, preview: 162, failed: 2 },
  { week: 'W37', production: 63, preview: 171, failed: 6 },
]

const config = {
  production: { label: 'Production', color: 'var(--color-chart-1)' },
  preview: { label: 'Preview', color: 'var(--color-chart-3)' },
  failed: { label: 'Failed', color: 'var(--color-chart-4)' },
} satisfies ChartConfig

const reading = (rows: typeof WEEKS) =>
  rows.map((row) => ({
    ...row,
    production: Math.round(30 + Math.random() * 40),
    preview: Math.round(90 + Math.random() * 90),
    failed: Math.round(Math.random() * 9),
  }))

export default function BuildsChart() {
  const motion = useChartMotion()
  const [data, setData] = useState(WEEKS)
  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle>Builds</CardTitle>
        <CardDescription>Per week, stacked by environment.</CardDescription>
        <CardAction>
          <Button variant="outline" size="sm" onClick={() => setData(reading)}>
            Refresh
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <ChartContainer config={config} className="aspect-auto h-56 w-full" title="Builds per week by environment">
          <BarChart data={data} margin={{ left: 4, right: 4, top: 8 }}>
            <CartesianGrid vertical={false} />
            <XAxis dataKey="week" tickLine={false} axisLine={false} tickMargin={8} />
            <YAxis tickLine={false} axisLine={false} width={32} />
            <ChartTooltip cursor={{ radius: 6 }} content={<ChartTooltipContent />} />
            <Bar dataKey="production" stackId="builds" fill="var(--color-production)" {...motion.grow()} />
            <Bar dataKey="preview" stackId="builds" fill="var(--color-preview)" {...motion.grow()} />
            <Bar dataKey="failed" stackId="builds" fill="var(--color-failed)" radius={[4, 4, 0, 0]} {...motion.grow()} />
            <ChartLegend content={<ChartLegendContent />} />
          </BarChart>
        </ChartContainer>
        <ChartDataTable data={data} config={config} labelKey="week" labelHeading="Week" caption="Builds per week by environment." />
      </CardContent>
    </Card>
  )
}
```

Weekly builds as bars, with a Refresh button that morphs the bars to new readings.

Bars grow from the baseline with `motion.grow()`. When the data changes, every mark morphs from where it stands to its new value on the same timing, and a change that lands mid-morph continues from where the bars are. Press Refresh a few times in a row.

### Donuts

```tsx
'use client'

import { Label, Pie, PieChart, Sector, type PieSectorShapeProps } from 'recharts'
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@youj/react'
import {
  ChartContainer,
  ChartDataTable,
  ChartTooltip,
  ChartTooltipContent,
  useChartMotion,
  type ChartConfig,
} from '@youj/react/chart'

const traffic = [
  { source: 'direct', visitors: 4820, fill: 'var(--color-direct)' },
  { source: 'search', visitors: 3610, fill: 'var(--color-search)' },
  { source: 'social', visitors: 1940, fill: 'var(--color-social)' },
  { source: 'referral', visitors: 1180, fill: 'var(--color-referral)' },
  { source: 'email', visitors: 640, fill: 'var(--color-email)' },
]

const config = {
  visitors: { label: 'Visitors' },
  direct: { label: 'Direct', color: 'var(--color-chart-1)' },
  search: { label: 'Search', color: 'var(--color-chart-2)' },
  social: { label: 'Social', color: 'var(--color-chart-3)' },
  referral: { label: 'Referral', color: 'var(--color-chart-4)' },
  email: { label: 'Email', color: 'var(--color-chart-5)' },
} satisfies ChartConfig

const total = traffic.reduce((sum, row) => sum + row.visitors, 0)

/** The hovered slice steps out 4px. */
function Slice(props: PieSectorShapeProps) {
  return <Sector {...props} outerRadius={(props.outerRadius ?? 0) + (props.isActive ? 4 : 0)} />
}

export default function TrafficDonut() {
  const motion = useChartMotion()
  return (
    <Card className="w-full max-w-xs">
      <CardHeader>
        <CardTitle>Traffic sources</CardTitle>
        <CardDescription>Visitors this week.</CardDescription>
      </CardHeader>
      <CardContent>
        <ChartContainer
          config={config}
          className="mx-auto aspect-square h-52"
          title="Traffic by source"
          summary={`Direct traffic leads with ${Math.round((4820 / total) * 100)}% of ${total.toLocaleString('en-US')} visitors.`}
        >
          <PieChart>
            <ChartTooltip content={<ChartTooltipContent nameKey="source" hideLabel />} />
            <Pie
              data={traffic}
              dataKey="visitors"
              nameKey="source"
              innerRadius="62%"
              outerRadius="88%"
              paddingAngle={2}
              cornerRadius={3}
              stroke="none"
              shape={Slice}
              {...motion.sweep()}
            >
              <Label
                content={({ viewBox }) =>
                  viewBox && 'cx' in viewBox ? (
                    <text x={viewBox.cx} y={viewBox.cy} textAnchor="middle" dominantBaseline="middle">
                      <tspan x={viewBox.cx} y={(viewBox.cy ?? 0) - 6} className="fill-fg text-2xl font-semibold tabular-nums">
                        {total.toLocaleString('en-US')}
                      </tspan>
                      <tspan x={viewBox.cx} y={(viewBox.cy ?? 0) + 16} className="fill-fg-muted text-ui-xs">
                        visitors
                      </tspan>
                    </text>
                  ) : null
                }
              />
            </Pie>
          </PieChart>
        </ChartContainer>
        <ChartDataTable data={traffic} config={config} keys={['visitors']} labelKey="source" labelHeading="Source" caption="Visitors by traffic source." />
      </CardContent>
    </Card>
  )
}
```

Traffic sources as a donut with the total in the middle.

Pies, donuts and radial bars sweep round with `motion.sweep()`. Put the color on each datum (`fill: 'var(--color-direct)'`) and name slices with `nameKey`. A `Label` inside the `Pie` holds the total.

## Installation & usage

```bash
pnpm add @youj/react recharts
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chart
```

It brings `button`, `collapse`, `table`, `youj-core`, `youj-labels-chart`, `youj-ui-core` with it.

Requires `recharts`, an [optional dependency](https://www.youj.dev/docs/installation#optional-dependencies). Import it from `@youj/react/chart`.

The chart parts come from Recharts itself, so import them from `recharts` in your app.

Use a chart when the shape of the numbers is the point: a trend over time, a comparison between groups, a share of a whole. It's shadcn's chart, so you still write Recharts (`AreaChart`, `Bar`, `Pie`) and the kit supplies the container, the tooltip, the legend, the theme colors and the timing. For a trend the size of a word, in a KPI or a table cell, use a [Sparkline](https://www.youj.dev/docs/components/sparkline). For one number and how it moved, use a [Stat Card](https://www.youj.dev/docs/components/stat-card). When people need to sort, filter or copy the values, give them a [data table](https://www.youj.dev/docs/blocks/tables-and-lists).

A `ChartConfig` names each series and gives it a color. `ChartContainer` exposes each one as `--color-<key>`, so the marks read `var(--color-revenue)`. Spread `useChartMotion()` onto each series for Youj timing.

```tsx
import { Area, AreaChart, XAxis } from 'recharts'
import { ChartContainer, ChartTooltip, ChartTooltipContent, useChartMotion, type ChartConfig } from '@youj/react/chart'

const config = {
  revenue: { label: 'Revenue', color: 'var(--color-chart-1)' },
} satisfies ChartConfig

export function Revenue({ data }: { data: { month: string; revenue: number }[] }) {
  const motion = useChartMotion()
  return (
    <ChartContainer config={config} className="h-56 w-full" title="Revenue by month" summary="Revenue doubled since April.">
      <AreaChart data={data}>
        <XAxis dataKey="month" tickLine={false} axisLine={false} />
        <ChartTooltip content={<ChartTooltipContent />} />
        <Area dataKey="revenue" stroke="var(--color-revenue)" fill="var(--color-revenue)" fillOpacity={0.2} {...motion.draw(0)} />
      </AreaChart>
    </ChartContainer>
  )
}
```

Point the config at the chart colors, `var(--color-chart-1)` to `var(--color-chart-5)`. They come from the theme: its own [chart palette](https://www.youj.dev/docs/theming#chart-palette), which every preset tunes (Basalt's neon series, Graphite's calm blue, rose, violet, amber and teal), else one drawn from its accent. Either way light and dark and every [theme preset](https://www.youj.dev/docs/theming) re-color the chart with no change to your code, and every series reads at 3:1 against the surface. Axes, grid lines and cursors take the ink ramp on their own.

### Size

`ChartContainer` is full width and `aspect-video` (16:9) by default, and it shrinks with its column, so a chart in a CSS grid or a flex row never pushes a phone page wider than the screen. A height class gives it a fixed height instead (`className="h-64"`), and an aspect class another shape (`aspect-square`).

### Series keys

Each config key becomes a CSS variable name. A key that isn't a CSS name, like `PM2.5` or `Net revenue`, has each character a name can't hold written as `-` (`--color-PM2-5`), and development warns once. `chartColor(key)` gives you a series' color for any key, so you never spell the variable yourself:

```tsx
import { chartColor, type ChartConfig } from '@youj/react/chart'

const config = {
  'PM2.5': { label: 'Fine particles', color: 'var(--color-chart-1)' },
} satisfies ChartConfig

<Bar dataKey="PM2.5" fill={chartColor('PM2.5')} />
```

### Donut center labels

A Recharts `Label` inside the `Pie` draws in the hole. Its `content` gets the hole's center as `viewBox`; write the total and its unit as two `tspan`s on the theme's text roles:

```tsx
<Pie data={traffic} dataKey="visitors" nameKey="source" innerRadius="62%" {...motion.sweep()}>
  <Label
    content={({ viewBox }) =>
      viewBox && 'cx' in viewBox ? (
        <text x={viewBox.cx} y={viewBox.cy} textAnchor="middle" dominantBaseline="middle">
          <tspan x={viewBox.cx} y={(viewBox.cy ?? 0) - 6} className="fill-fg text-2xl font-semibold tabular-nums">
            {total.toLocaleString()}
          </tspan>
          <tspan x={viewBox.cx} y={(viewBox.cy ?? 0) + 16} className="fill-fg-muted text-ui-xs">
            visitors
          </tspan>
        </text>
      ) : null
    }
  />
</Pie>
```

### Pie legends and tooltips

A pie's series are its rows, not its fields, so tell the legend and the tooltip which field names a slice: `nameKey`, the same one the `Pie` takes. Each slice's name is then looked up in the config for its label.

```tsx
<ChartTooltip content={<ChartTooltipContent nameKey="source" hideLabel />} />
<ChartLegend content={<ChartLegendContent nameKey="source" />} />
```

### A period filter that drives the charts

Keep the period in one piece of state: a `SegmentedControl` sets it from presets, a `DateRangePicker` sets a custom range, and every chart reads the rows inside it. A preset fills the picker; picking a range clears the preset.

```tsx
'use client'

import { useMemo, useState } from 'react'
import { SegmentedControl, SegmentedControlItem } from '@youj/react'
import { DateRangePicker, type DateRange } from '@youj/react/date'

const DAY = 86_400_000
const PRESETS = { '7d': 7, '30d': 30, '90d': 90 } as const

export function Overview({ rows, latest }: { rows: { date: Date; value: number }[]; latest: Date }) {
  const [preset, setPreset] = useState<keyof typeof PRESETS | ''>('30d')
  const [range, setRange] = useState<DateRange>({ from: new Date(latest.getTime() - 29 * DAY), to: latest })
  const shown = useMemo(() => rows.filter((r) => r.date >= range.from! && r.date <= range.to!), [rows, range])
  return (
    <>
      <div className="flex flex-wrap items-end gap-3">
        <SegmentedControl
          aria-label="Period"
          value={preset}
          onValueChange={(value) => {
            if (!(value in PRESETS)) return
            const key = value as keyof typeof PRESETS
            setPreset(key)
            setRange({ from: new Date(latest.getTime() - (PRESETS[key] - 1) * DAY), to: latest })
          }}
        >
          <SegmentedControlItem value="7d">7 days</SegmentedControlItem>
          <SegmentedControlItem value="30d">30 days</SegmentedControlItem>
          <SegmentedControlItem value="90d">90 days</SegmentedControlItem>
        </SegmentedControl>
        <DateRangePicker
          value={range}
          maxDate={latest}
          onValueChange={(next) => {
            if (!next?.from || !next.to) return
            setPreset('')
            setRange(next)
          }}
        />
      </div>
      <TrendChart rows={shown} />
      <BreakdownChart rows={shown} />
    </>
  )
}
```

Anchor the presets to the newest row (`latest`), not to the clock: the page renders the same on the server and in the browser, and a prerender never reads the time.

### Loading

While the rows load, show a `Skeleton` the chart's size in its place, so nothing moves when the chart arrives:

```tsx
import { Skeleton } from '@youj/react'

{loading ? <Skeleton className="aspect-video w-full" /> : <ChartContainer config={config}>…</ChartContainer>}
```

### Heatmaps: a value per cell

There's no general heatmap. For a value in each cell of a grid, pick the one that fits the grid:

- **A value by hour (or any column) for a few kinds:** [Density Lanes](https://www.youj.dev/docs/components/density-lanes), one lane of dots per kind, swelling where it's busy.
- **A value by day, as a streak or a habit:** [Calendar Heatmap](https://www.youj.dev/docs/components/calendar-heatmap), a day grid by week.
- **How well each row is covered by each column:** [Coverage Matrix](https://www.youj.dev/docs/components/coverage-matrix), with the gaps hatched.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### ChartContainer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `ChartConfig` |  |  |
| `children` (required) | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<AwaitedReactNode>` |  | One Recharts chart (LineChart, BarChart, PieChart…). |
| `title` | `string` |  | The figure's accessible name, e.g. "Revenue by month". |
| `summary` | `ReactNode` |  | One or two sentences on what the chart shows (the trend, the extremes), read after the name. |
| `initialDimension` | `{ width: number; height: number }` | `INITIAL_DIMENSION` | Size used before the container is measured (and on the server). |

Also takes the props of `ComponentProps<'div'>`.

#### ChartTooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  |  |
| `payload` | `readonly TooltipPayloadItem[]` |  |  |
| `label` | `ReactNode` |  |  |
| `hideLabel` | `boolean` | `false` |  |
| `hideIndicator` | `boolean` | `false` |  |
| `indicator` | `'line' \| 'dot' \| 'dashed'` | `'dot'` |  |
| `nameKey` | `string` |  | The payload field whose value names each row in the config. |
| `labelKey` | `string` |  | The payload field whose value is the heading. |
| `labelFormatter` | `(label: ReactNode, payload: readonly TooltipPayloadItem[]) => ReactNode` |  |  |
| `labelClassName` | `string` |  |  |
| `valueFormatter` | `(value: number \| string, name: string, item: TooltipPayloadItem) => ReactNode` |  | Formats each value, e.g. as currency. Default: toLocaleString. |
| `color` | `string` |  |  |

Also takes the props of `ComponentProps<'div'>`.

#### ChartLegendContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `payload` | `readonly RechartsPrimitive.LegendPayload[]` |  |  |
| `verticalAlign` | `'top' \| 'middle' \| 'bottom'` | `'bottom'` |  |
| `hideIcon` | `boolean` | `false` |  |
| `nameKey` | `string` |  |  |

Also takes the props of `ComponentProps<'div'>`.

#### ChartDataTable

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly Record<string, unknown>[]` |  |  |
| `config` (required) | `ChartConfig` |  |  |
| `labelKey` (required) | `string` |  | The field that names each row (the x axis, or the slice name). |
| `labelHeading` | `ReactNode` |  | Heading for the label column. Default: the config's label for labelKey, else the key. |
| `keys` | `string[]` |  | Columns to show, in order. Default: every config key present in the data. |
| `caption` (required) | `ReactNode` |  | Describes the table, e.g. "Revenue by month, in USD". |
| `mode` | `'hidden' \| 'toggle'` | `'hidden'` | `hidden`: a visually hidden table for assistive tech. `toggle`: a "View data" button that reveals it. |
| `valueFormatter` | `(value: number, key: string) => ReactNode` |  |  |

Also takes the props of `ComponentProps<'div'>`.

`ChartTooltip` and `ChartLegend` take Recharts' `Tooltip` and `Legend` props. `useChartMotion()` returns `draw(i)`, `grow(i)` and `sweep(i)` for series, `tooltip` for the tooltip, and `reduced`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lines and areas enter | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | `motion.draw()`: the stroke draws in and the area wipes in |
| Bars enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `motion.grow()`: from the baseline |
| Pies and radials enter | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | `motion.sweep()`: round from the start angle |
| Later series | `stagger.loose` | 72ms step | each one a stagger step behind the one before |
| Data change |  |  | every mark morphs from where it is, with its entrance timing |
| Tooltip | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | glides between points |
| View data | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the table opens with Collapse: height and opacity |

**Reduced motion:** Marks render in place, a data change jumps to the new values and the tooltip moves without gliding. The data table opens at once.

Recharts animates the marks itself. `useChartMotion()` replaces its 1.5s default ease with the token durations and curves, scaled by the Speed control, so a chart moves on the same clock as the rest of the page. The values it returns are plain numbers and strings, stable across renders, because Recharts restarts an animation whenever they change.

#### Reduced motion

Every mark is drawn in its final place, updates replace the old values at once, and the tooltip jumps to the pointer. The chart carries exactly the same information: only the transitions go.

### Accessibility

- `ChartContainer` is a figure (`role="figure"`) named by `title`. `summary` is read after the name, so say what the chart shows: the trend, the peak, the outlier.
- The plot is one Tab stop. The arrow keys walk the points and open the tooltip on each, and the ring shows on keyboard focus only.
- `ChartDataTable` gives the same numbers as a real table with a caption, column headers and row headers. Keep it hidden for screen readers, or put it behind View data, which is a disclosure button with `aria-expanded`.
- Color is never the only key: the legend and the tooltip name every series, and the table holds every value.

---

# Flow Graph

> Show the steps of a run or a pipeline as a graph that lays itself out, with each step’s state.

Source: https://www.youj.dev/docs/components/flow-graph

## Examples

### Demo

```tsx
'use client'

import { useId, useState } from 'react'
import { FlowGraph, type FlowEdge, type FlowNode } from '@youj/react'

// An image upload's processing: two cleanups, three encodes, then the CDN.
const NODES: FlowNode[] = [
  { id: 'upload', label: 'upload.receive', kind: 'input', status: 'ok', meta: '0.4 s' },
  { id: 'exif', label: 'exif.strip', kind: 'step', status: 'ok', meta: '0.1 s' },
  { id: 'resize', label: 'image.resize', kind: 'step', status: 'retried', meta: '1.8 s', attempts: 2 },
  { id: 'webp', label: 'encode.webp', kind: 'step', status: 'ok', meta: '0.9 s' },
  { id: 'avif', label: 'encode.avif', kind: 'step', status: 'running', meta: '2.1 s' },
  { id: 'thumb', label: 'thumb.make', kind: 'step', status: 'error', meta: 'timeout' },
  { id: 'cdn', label: 'cdn.publish', kind: 'output', status: 'queued' },
]
const EDGES: FlowEdge[] = [
  { from: 'upload', to: 'exif' },
  { from: 'upload', to: 'resize' },
  { from: 'exif', to: 'webp' },
  { from: 'resize', to: 'webp' },
  { from: 'resize', to: 'avif' },
  { from: 'resize', to: 'thumb' },
  { from: 'webp', to: 'cdn' },
  { from: 'avif', to: 'cdn' },
]

export default function FlowGraphDemo() {
  const [open, setOpen] = useState<string | null>('avif')
  const detailId = useId()
  const node = NODES.find((n) => n.id === open)
  return (
    <div className="flex w-full max-w-4xl flex-col gap-3">
      <FlowGraph nodes={NODES} edges={EDGES} value={open} onValueChange={setOpen} controls={detailId} label="Image processing" />
      <p id={detailId} className="min-h-5 font-mono text-ui-sm text-fg-muted">
        {node ? `${node.label} · ${node.status}${node.meta ? ` · ${node.meta}` : ''}` : 'Pick a step to open it.'}
      </p>
    </div>
  )
}
```

An image-processing pipeline from upload to CDN, with step statuses and a line of detail for the step you open.

The graph opens fitted to its canvas, but never below `fitFloor` (85%), so step names stay legible; a wider graph opens at the start of its flow and pans instead of shrinking. The canvas grows to the graph's height (`height="auto"`, from 200 to 640px), or takes a fixed `height`. Drag the canvas or use the wheel to pan, zoom with Ctrl or ⌘ and the wheel (or a pinch), the corner buttons or + and −, and press 0 to fit again. A minimap shows where you are while the graph overflows (`minimap={false}` hides it).

`orientation="auto"` (the default) lays the graph out left to right, right to left under RTL, and top to bottom when the canvas is narrower than 34rem. Pass `horizontal` or `vertical` to fix it.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add flow-graph
```

It brings `button`, `icon-maximize`, `icon-minus`, `icon-plus`, `use-controllable-state`, `youj-core`, `youj-labels-flow-graph`, `youj-presets`, `youj-ui-core` with it.

Use a flow graph when steps depend on each other and some run side by side: an agent's tool calls, a data pipeline, a build, a media job. You pass the steps and the edges between them, and it lays them out itself in layers that read in the flow direction: each step one layer past the furthest step it waits on, ordered to keep edges from crossing, and placed near the steps it joins. Steps are mono cards on a dot grid, joined port to port by curves, each showing its state: queued, running (a soft pulse, with dashes flowing along the edges into it), succeeded, failed, retried (with its attempts) or skipped (dashed, like its edges). Picking a step opens it, so the graph can drive a detail panel beside or under it. For a straight line of stages, use a [Stage Rail](https://www.youj.dev/docs/components/stage-rail).

```tsx
import { FlowGraph } from '@youj/react'

<FlowGraph
  nodes={[
    { id: 'fetch', label: 'git.log', kind: 'tool', status: 'ok', meta: '1.2 s' },
    { id: 'group', label: 'changes.group', kind: 'llm', status: 'running', meta: '4.8 s' },
    { id: 'draft', label: 'notes.draft', kind: 'llm', status: 'queued' },
  ]}
  edges={[
    { from: 'fetch', to: 'group' },
    { from: 'group', to: 'draft' },
  ]}
  value={open}
  onValueChange={setOpen}
  controls="step-detail"
/>
```

`meta` is one figure beside the kind, already formatted ("1.2 s", "404"), and it's spoken after the state. A retried step shows its `attempts`. Cards are sized to their names so nothing truncates, and the edges of a step that skips a layer are routed around the steps in between. A cycle's closing edge is left out of the layout. `layoutFlowGraph(nodes, edges, orientation)` returns the same layout for drawing your own.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` (required) | `readonly FlowNode[]` |  |  |
| `edges` (required) | `readonly FlowEdge[]` |  |  |
| `value` | `string \| null` |  | The open step's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` |  |
| `onValueChange` | `(id: string \| null) => void` |  |  |
| `controls` | `string` |  | The id of the region an open step's detail shows in, for `aria-controls`. |
| `orientation` | `FlowOrientation \| 'auto'` | `'auto'` |  |
| `minimap` | `boolean` | `true` | A small overview of the whole graph while zoomed in. |
| `label` | `string` |  | The graph's accessible name. Default: the labels' "Flow graph". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | With sound on, opening a step plays `select` and closing it `close`. |
| `height` | `number \| 'auto'` | `'auto'` | The canvas height in pixels. |
| `fitFloor` | `number` | `FIT_FLOOR` | The least the view zooms out to fit, so step names stay legible; a wider graph pans instead. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `flow-graph` (with `data-orientation`), `flow-graph-viewport` (with `data-dragging`), `flow-graph-world`, `flow-graph-edges`, `flow-graph-edge` (with `data-state` `running`, `done`, `pending`, `error` or `skipped`, and `data-active`), `flow-graph-nodes`, `flow-graph-node` (with `data-status` and `data-open`), `flow-graph-pulse`, `flow-graph-port` (with `data-side`), `flow-graph-node-status`, `flow-graph-node-name`, `flow-graph-node-kind`, `flow-graph-node-meta`, `flow-graph-node-attempts`, `flow-graph-fade`, `flow-graph-minimap`, `flow-graph-controls` and `flow-graph-zoom`. The kinds take the theme's label voice; in [Bezel](https://www.youj.dev/docs/looks) they're mono capital eyebrows and the figures are mono.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Running | `duration.deliberate` | 560ms | the step’s halo breathes and its dot throws a ring; dashes flow along the edges into it, looping until it finishes |
| Zoom and fit | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the view glides to its new scale, and can be caught mid-way by a drag or a wheel |
| Pan |  |  | the view follows the pointer and the wheel, never eased |

**Reduced motion:** Nothing breathes or flows: a running edge stays dashed in the accent, and zoom and fit land in place.

#### Reduced motion

The running step holds still and its edges stop flowing (they stay dashed in the accent), and zoom and fit land at once. Panning is unchanged, since it never animates.

### Accessibility

- The canvas is a group named by `label` (default "Flow graph"), described by a hint that explains the keys. The steps are buttons in one list and one tab stop: the running step, the open one, or the first.
- Arrow keys along the flow follow the edges to the next or previous step (the nearest one, or back the way you came), the cross arrows move within a layer, and Home and End go to the first and last step. They're mirrored under RTL and turn with the orientation.
- Each step is named by its name, state and figure ("changes.group, Running, 4.8 s") and described by what it follows and leads to ("After git.log. Then notes.draft"). An open step has `aria-expanded="true"` and `aria-controls` pointing at `controls`; Escape closes it.
- The state is always a word as well as a color and a dot shape. With sound on, opening a step plays `select` and closing it `close`.
- Its words come from the labels (`flowGraph`, `flowGraphHint`, the `flow*` states, `flowGraphNode`, `flowGraphAfter`, `flowGraphThen`, `flowGraphAttempts`, `zoomIn`, `zoomOut`, `zoomToFit`), translated by the language packs.

---

# Flow Lanes

> Show where a stream goes: one source fanning out to a lane per destination, each a stream of particles as dense as its rate.

Source: https://www.youj.dev/docs/components/flow-lanes

## Examples

### Demo

```tsx
'use client'

import { FlowLanes, type FlowLane } from '@youj/react'

/** A made-up delivery hub's parcels per minute, by route. */
const LANES: FlowLane[] = [
  { id: 'north', label: 'North loop', value: 64 },
  { id: 'harbor', label: 'Harbor run', value: 142 },
  { id: 'airport', label: 'Airport express', value: 88 },
  { id: 'hills', label: 'Hill towns', value: 31 },
]

export default function FlowLanesDemo() {
  return (
    <div className="w-full max-w-lg">
      <FlowLanes source="Hub" lanes={LANES} formatValue={(v) => `${v}/min`} label="Parcels by route" />
    </div>
  )
}
```

A made-up delivery hub's parcels per minute, by route. Each lane's particles cross at the same speed, so the busy Harbor run is a dense stream and the Hill towns a trickle; the line's weight says the same.

### Pointing

```tsx
'use client'

import { useState } from 'react'
import { Button, FlowLanes, type FlowLane } from '@youj/react'

/** A made-up balancer's requests a second, by pool. */
const POOLS: FlowLane[] = [
  { id: 'a', label: 'pool-a', value: 210, tone: 'chart-1' },
  { id: 'b', label: 'pool-b', value: 180, tone: 'chart-2' },
  { id: 'c', label: 'pool-c', value: 96, tone: 'chart-3' },
  { id: 'canary', label: 'canary', value: 12, tone: 'chart-5' },
]

export default function FlowLanesPointing() {
  const [active, setActive] = useState<string | null>('canary')
  return (
    <div className="grid w-full max-w-lg gap-4">
      <FlowLanes source="Balancer" lanes={POOLS} active={active} onActiveChange={setActive} formatValue={(v) => `${v}/s`} label="Requests by pool" />
      <div className="flex flex-wrap gap-2">
        {POOLS.map((pool) => (
          <Button
            key={pool.id}
            size="sm"
            variant={active === pool.id ? 'secondary' : 'outline'}
            aria-pressed={active === pool.id}
            onClick={() => setActive(active === pool.id ? null : pool.id)}
            className="font-mono"
          >
            {pool.label}
          </Button>
        ))}
      </div>
    </div>
  )
}
```

`active` lights one lane and quiets the rest, and `onActiveChange` reports where pointing and focus go, so a table or a set of buttons beside the chart can light a lane too.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add flow-lanes
```

It brings `use-controllable-state`, `use-resize-measure`, `youj-core`, `youj-labels-flow-lanes`, `youj-presets`, `youj-ui-core` with it.

Use flow lanes for one stream split many ways, where the split is the story: a model router's traffic by model, a load balancer's pools, a queue's consumers, an inbox's routing rules. The [Routing flow](https://www.youj.dev/docs/blocks/flows#routing-flow) card is built on it. For a run of steps with branches use a [Flow Graph](https://www.youj.dev/docs/components/flow-graph); for shares without a source, a [Share Bar](https://www.youj.dev/docs/components/share-bar).

```tsx
import { FlowLanes } from '@youj/react'

<FlowLanes
  source="Gateway"
  label="Requests by model"
  lanes={[
    { id: 'pro', label: 'Kestrel 3 Pro', value: 47, tone: 'chart-1' },
    { id: 'orrery', label: 'Orrery 2', value: 137, tone: 'chart-2' },
  ]}
  formatValue={(v) => `${Math.round(v)}/s`}
/>
```

`source` names the node the lanes leave from. Each lane's `value` is its rate in any unit: it sets how many particles ride it (a share of the whole, at least one for any flow), the weight of its line and the share spoken with it. Lanes take the chart colors in order unless they set a `tone`. `formatValue` writes a rate with its unit. The particles stop while the chart is off screen or the tab is hidden, and `paused` stops them for good. No lanes, or nothing flowing, shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source` (required) | `string` |  | The node every lane leaves from, named over it: "Gateway". |
| `lanes` (required) | `readonly FlowLane[]` |  |  |
| `active` | `string \| null` |  | The lane to light, by id (controlled); `null` for none. |
| `defaultActive` | `string \| null` | `null` | The lane lit at first (uncontrolled). |
| `onActiveChange` | `(id: string \| null) => void` |  | Called when pointing or focus moves to a lane, or off them (`null`). |
| `paused` | `boolean` | `false` | Stops the particles where they are. They also stop while the chart is off screen or the tab is hidden. |
| `formatValue` | `(value: number) => string` |  | Writes a rate with its unit: "57/s". Default: the locale's number format. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Flow lanes". |
| `config` | `Readonly<Record<string, { color?: string }>>` |  | A ChartConfig shared with your other charts: a lane whose id is a key takes its color, so one series matches across chart types. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `flow-lanes`, `flow-lanes-plot`, `flow-lanes-source`, `flow-lanes-source-node`, `flow-lanes-lane`, `flow-lanes-stream`, `flow-lanes-particles`, `flow-lanes-particle`, `flow-lanes-list`, `flow-lanes-item`, `flow-lanes-label`, `flow-lanes-value`, `flow-lanes-summary` and `flow-lanes-empty`. While a lane is lit, its lane, particles and item have `data-state="active"` and the others `data-state="inactive"`. The lane pitch is `--flow-lanes-pitch` (32px, 28px compact).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Draw | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | the lanes draw out from the source when a third of the chart scrolls into view, a lane after another |
| Stream |  | linear, looping | particles cross at one steady speed, a full width in six deliberate beats, fading in and out at the ends; they stop off screen |
| Reweight | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | a new rate thickens or thins the line and reseeds the stream |
| Pointing | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the other lanes and their streams quiet |

**Reduced motion:** Drawn in place; the particles rest on their lanes, spaced by the rate, so the density still reads.

#### Reduced motion

The lanes are drawn in place and the particles stand still on them, as many as the rate gives, so a busy lane still looks busy.

### Accessibility

- A named `group` (your `label`, or the labels' "Flow lanes") described by the source, how many lanes it feeds and their total ("Gateway to 4 lanes, 312/s in all.").
- The lanes are a list; each is read with its name, rate and share ("Orrery 2: 137/s, 44%").
- The names are one tab stop. The arrow keys, `Home` and `End` move between them, and focus lights the lane as pointing does.
- The drawing and the particles are decorative; the list says the same in words. Color is never the only cue: every lane is named.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Lollipop Chart

> Compare many items on one value scale: a dot on a stem from a baseline each, sorted into a curve, with one item picked and named.

Source: https://www.youj.dev/docs/components/lollipop-chart

## Examples

### Demo

```tsx
'use client'

import { LollipopChart, type LollipopDatum } from '@youj/react'

/** A made-up league's teams, goal difference against par. */
const TEAMS: LollipopDatum[] = [
  { id: 'harbor', label: 'Harbor FC', value: 14 },
  { id: 'mill', label: 'Mill Lane', value: -9 },
  { id: 'north', label: 'North End', value: 6 },
  { id: 'quarry', label: 'Quarry Town', value: -17 },
  { id: 'river', label: 'Riverside', value: 2 },
  { id: 'station', label: 'Station Road', value: -3 },
  { id: 'vale', label: 'Vale Rovers', value: 21 },
  { id: 'wharf', label: 'Wharf United', value: 9 },
].map((team) => ({ ...team, tone: team.value < -5 ? 'danger' : team.value < 5 ? 'warning' : 'success' }))

export default function LollipopChartDemo() {
  return (
    <div className="w-full max-w-lg">
      <LollipopChart data={TEAMS} sort="ascending" formatValue={(v) => `${v > 0 ? '+' : ''}${v}`} label="Goal difference by team" />
    </div>
  )
}
```

A made-up league's goal difference against par, sorted lowest first, each dot in its status tone. Sorted, the stems read as one curve from the worst to the best, below the baseline on one side and above it on the other.

### Picking one

```tsx
'use client'

import { useState } from 'react'
import { LollipopChart, type LollipopDatum } from '@youj/react'

/** A made-up bakery chain's shops, the share of the week's waste budget left. */
const SHOPS: LollipopDatum[] = [
  { id: 'dock', label: 'Dock Street', value: -0.42 },
  { id: 'park', label: 'Park Row', value: 0.18 },
  { id: 'mill', label: 'Mill Square', value: 0.64 },
  { id: 'bridge', label: 'Bridge End', value: -0.11 },
  { id: 'hill', label: 'Hill Road', value: 0.37 },
  { id: 'market', label: 'Market Hall', value: 0.81 },
].map((shop) => ({ ...shop, tone: shop.value < 0 ? 'danger' : shop.value < 0.25 ? 'warning' : 'success' }))

const percent = (v: number) => `${v > 0 ? '+' : ''}${Math.round(v * 100)}%`

export default function LollipopChartPicked() {
  const [picked, setPicked] = useState<string | null>('bridge')
  return (
    <div className="grid w-full max-w-lg gap-3">
      <LollipopChart
        data={SHOPS}
        sort="ascending"
        domain={[-1, 1]}
        ticks={[-1, -0.5, 0, 0.5, 1]}
        value={picked}
        onValueChange={setPicked}
        formatValue={percent}
        label="Waste budget left by shop"
      />
      <p className="text-ui-sm text-fg-muted">Picked: {SHOPS.find((shop) => shop.id === picked)?.label ?? 'none'}</p>
    </div>
  )
}
```

`value` and `onValueChange` pick one item: its column gets a band, its dot a ring, and a pill over the plot names it with its value. A fixed `domain` and `ticks` keep separate charts on the same scale.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add lollipop-chart
```

It brings `tooltip`, `use-controllable-state`, `youj-core`, `youj-labels-lollipop-chart`, `youj-presets`, `youj-ui-core` with it.

Use a lollipop chart to compare many items on one measure where the sign matters, like error budget left by SLO, score against par by team, or stock against target by shop. A table beside it can follow and lead the pick. For a few items' parts of a whole use a [Share Bar](https://www.youj.dev/docs/components/share-bar); for values over time, a [Chart](https://www.youj.dev/docs/components/chart). The [Lollipop ranking](https://www.youj.dev/docs/blocks/rankings-and-breakdowns#lollipop-ranking) card is built on it.

```tsx
import { LollipopChart } from '@youj/react'

<LollipopChart
  label="Budget left by SLO"
  data={slos.map((s) => ({ id: s.id, label: s.name, value: s.budget, tone: s.budget < 0 ? 'danger' : 'success' }))}
  sort="ascending"
  domain={[-1, 1]}
  value={picked}
  onValueChange={setPicked}
  formatValue={(v) => percent.format(v)}
/>
```

Each item is a dot at its `value` on a stem from `baseline` (0 by default), in its `tone`. `sort` orders them lowest or highest first; without it they keep the data's order. The scale runs over `domain` (by default the data's range with the baseline, rounded out to even `ticks`). `formatValue` writes values in the tooltip, the pill and the spoken text, and `formatTick` the axis. Give it a height with a class (`h-64` by default). No items shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly LollipopDatum[]` |  |  |
| `sort` | `'ascending' \| 'descending'` |  | Order the items by value, lowest first or highest first. Default: the data's order. |
| `value` | `string \| null` |  | The picked item's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` | The item picked at first (uncontrolled). |
| `onValueChange` | `(id: string \| null) => void` |  |  |
| `domain` | `readonly [number, number]` |  | The value scale. Default: the data's range with the baseline, rounded out to the ticks. |
| `baseline` | `number` | `0` | Where the stems start. |
| `ticks` | `readonly number[]` |  | Values on the axis. Default: about five even steps across the domain. |
| `formatValue` | `(value: number) => string` |  | Writes a value in the tooltip, the pill and the spoken text. Default: the locale's number format. |
| `formatTick` | `(value: number) => string` | ``formatValue`` | Writes an axis tick. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Lollipop chart". |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `lollipop-chart`, `lollipop-chart-flag-row`, `lollipop-chart-flag`, `lollipop-chart-axis`, `lollipop-chart-plot`, `lollipop-chart-grid`, `lollipop-chart-baseline`, `lollipop-chart-band`, `lollipop-chart-item`, `lollipop-chart-stem`, `lollipop-chart-dot` and `lollipop-chart-summary`. The picked item has `data-state="selected"`; an item's tone is `--lollipop-ink`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Grow | `spring.smooth` | 0.36s, bounce 0 | the stems grow from the baseline and the dots ride them out when a third of the chart scrolls into view |
| Pick | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the band and the pill glide to the picked item; its dot grows a ring |

**Reduced motion:** Drawn in place; a new pick lands at once.

#### Reduced motion

The stems and dots are drawn at their values, and the band and pill jump to a new pick.

### Accessibility

- A named `listbox` (your `label`, or the labels' "Lollipop chart") described by the count and the range ("18 points, from -82.3% to +94.1%.").
- Every item is an `option` named with its label and value, `aria-selected` when picked.
- One tab stop. The arrow keys walk the items (mirrored in RTL), `Home` and `End` go to the ends, and `Enter` or `Space` picks; focus shows the same tooltip as hovering.
- The axis, gridlines and stems are decorative. Tones never carry the meaning alone: the values are signed and spoken.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Hierarchy Chart

> Draw an org chart, a team of teams or any parent-and-children structure as a tidy tree that folds, pans and zooms.

Source: https://www.youj.dev/docs/components/hierarchy-chart

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { HierarchyChart, type HierarchyNode } from '@youj/react'

// A small company, three levels deep.
const ORG: HierarchyNode = {
  id: 'maya',
  name: 'Maya Lindqvist',
  role: 'Chief Executive Officer',
  children: [
    {
      id: 'jonas',
      name: 'Jonas Okafor',
      role: 'VP Engineering',
      badge: 'Hiring',
      children: [
        { id: 'priya', name: 'Priya Raman', role: 'Platform Lead' },
        { id: 'ken', name: 'Ken Watanabe', role: 'Product Engineering' },
        { id: 'amara', name: 'Amara Nwosu', role: 'Frontend Engineer' },
      ],
    },
    {
      id: 'elena',
      name: 'Elena Petrova',
      role: 'VP Product',
      children: [
        { id: 'noah', name: 'Noah Kim', role: 'Product Manager' },
        { id: 'hana', name: 'Hana Sato', role: 'Design Lead' },
      ],
    },
    {
      id: 'david',
      name: 'David Mensah',
      role: 'Chief Financial Officer',
      children: [{ id: 'olivia', name: 'Olivia Hart', role: 'Controller' }],
    },
  ],
}

export default function HierarchyChartDemo() {
  const [selected, setSelected] = useState<string | null>('ken')
  return (
    <div className="w-full max-w-5xl">
      <HierarchyChart nodes={ORG} label="Company org chart" selected={selected} onSelectedChange={setSelected} height={440} />
    </div>
  )
}
```

A company's org chart. Select a person to light their reporting line, and close a branch with the chip on a card's foot to fold it into a count ("+3").

The chart opens fitted to its canvas, but never below 60%, so names stay legible; a bigger chart opens on its root and pans instead. Drag anywhere to pan (a click that doesn't move still picks a node), use the wheel, or one finger across; zoom with Ctrl or ⌘ and the wheel, a pinch, the corner buttons or + and −, and press 0 to fit the whole chart.

### Team of teams

```tsx
'use client'

import { Badge, HierarchyChart, type HierarchyNode } from '@youj/react'

interface Team extends HierarchyNode {
  mission: string
  people: number
  children?: Team[]
}

// A product org as teams, read along the line, each card drawn by renderNode.
const TEAMS: Team = {
  id: 'product',
  name: 'Product',
  mission: 'Everything customers touch',
  people: 46,
  children: [
    {
      id: 'core',
      name: 'Core experience',
      mission: 'Editor, sync, offline',
      people: 15,
      children: [
        { id: 'editor', name: 'Editor', mission: 'Blocks and embeds', people: 8 },
        { id: 'sync', name: 'Sync', mission: 'Real-time and conflicts', people: 7 },
      ],
    },
    {
      id: 'growth',
      name: 'Growth',
      mission: 'Activation and billing',
      people: 13,
      children: [
        { id: 'onboarding', name: 'Onboarding', mission: 'First week to aha', people: 6 },
        { id: 'billing', name: 'Billing', mission: 'Plans and invoices', people: 7 },
      ],
    },
    {
      id: 'platform',
      name: 'Platform',
      mission: 'Infrastructure and data',
      people: 18,
      children: [
        { id: 'infra', name: 'Infrastructure', mission: 'Clusters and deploys', people: 10 },
        { id: 'data', name: 'Data', mission: 'Pipelines and warehouse', people: 8 },
      ],
    },
  ],
}

export default function HierarchyChartTeams() {
  return (
    <div className="w-full max-w-5xl">
      <HierarchyChart<Team>
        nodes={TEAMS}
        orientation="horizontal"
        label="Product teams"
        nodeSize={{ width: 220, height: 60 }}
        height={400}
        renderNode={(team, state) => (
          <span className="flex min-w-0 flex-1 items-center gap-3">
            <span className="flex min-w-0 flex-1 flex-col gap-0.5">
              <span className="truncate font-medium text-fg text-ui leading-tight">{team.name}</span>
              <span className="truncate text-fg-muted text-ui-sm leading-tight">{team.mission}</span>
            </span>
            <Badge variant={state.depth === 0 ? 'default' : 'secondary'} className="shrink-0 tabular-nums">
              {team.people}
            </Badge>
          </span>
        )}
      />
    </div>
  )
}
```

`orientation="horizontal"` grows the tree along the reading direction (right to left under RTL). `renderNode` draws each card's contents (here the team, its mission and its headcount) inside the chart's card frame, which still draws focus, selection and the path.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add hierarchy-chart
```

It brings `avatar`, `badge`, `button`, `icon-maximize`, `icon-minus`, `icon-plus`, `use-controllable-state`, `youj-core`, `youj-labels-hierarchy-chart`, `youj-presets`, `youj-ui-core` with it.

The copy is 18 registry items, about 8,500 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `badge`, `button`, `icon-engine`, `icon-loader-ring`, `icon-maximize`, `icon-minus`, `icon-plus`, `icon-x`, `spinner` and 1 more.

Use a hierarchy chart when the shape of a tree is the point: who reports to whom, which teams sit under which group, how a product breaks down. For a tree people browse and pick from (files, settings, categories), use a [Tree View](https://www.youj.dev/docs/components/tree-view); for steps that depend on each other, a [Flow Graph](https://www.youj.dev/docs/components/flow-graph).

```tsx
import { HierarchyChart } from '@youj/react'

<HierarchyChart
  nodes={{
    id: 'maya',
    name: 'Maya Lindqvist',
    role: 'CEO',
    children: [
      { id: 'jonas', name: 'Jonas Okafor', role: 'VP Engineering', badge: 'Hiring', children: [/* … */] },
      { id: 'elena', name: 'Elena Petrova', role: 'VP Product' },
    ],
  }}
  selected={selected}
  onSelectedChange={setSelected}
/>
```

`nodes` is one root or an array of them, each `{ id, name, role?, avatar?, badge?, children? }`; the default card shows the avatar (or the name's initials), the name, the role and the badge. Pass your own type that extends `HierarchyNode` and a `renderNode(node, state)` to draw the card yourself; `state` says its depth, whether it's selected, on the selected path, a branch and open, and how many nodes sit below it. Every card has one size, `nodeSize` (224 × 64 by default).

The layout is a tidy tree (Reingold–Tilford, in Walker's linear form): every parent is centered over its children, subtrees pack as close as the gaps allow without overlapping, and identical subtrees are drawn identically. It handles a few hundred nodes at once; `layoutHierarchy(nodes, options)` returns the same layout for drawing your own.

Branches are all open by default; `defaultExpanded` or `expanded` with `onExpandedChange` take the open ids. To find someone, hold a `ref`: `ref.current.focusNode(id)` opens the branches above them, focuses their card and centers it, and `ref.current.fit()` fits the chart.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` (required) | `T \| readonly T[]` |  | The tree: one root, or several side by side. Ids must be unique. |
| `renderNode` | `(node: T, state: HierarchyNodeState) => ReactNode` |  | A node's card contents, inside the chart's card frame (which draws focus, selection and the path). Default: avatar, name, role and badge. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | `vertical` (default) grows down from the root; `horizontal` grows along the reading direction. |
| `expanded` | `string[]` |  | Open branches (controlled). |
| `defaultExpanded` | `string[]` |  | Default: every branch open. |
| `onExpandedChange` | `(ids: string[]) => void` |  |  |
| `selected` | `string \| null` |  | The selected node (controlled); `null` for none. |
| `defaultSelected` | `string \| null` | `null` |  |
| `onSelectedChange` | `(id: string \| null) => void` |  |  |
| `nodeSize` | `{ width: number; height: number }` | `NODE` | Every card's size in pixels. |
| `height` | `number` | `480` | The canvas height in pixels. |
| `label` | `string` |  | The tree's accessible name. Default: the labels' "Hierarchy chart". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | With sound on, selecting plays `select`, opening a branch `open` and closing it `close`. |
| `ref` | `Ref<HierarchyChartHandle>` |  |  |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `hierarchy-chart` (with `data-orientation`), `hierarchy-chart-viewport` (with `data-dragging`), `hierarchy-chart-world`, `hierarchy-chart-edges`, `hierarchy-chart-edge` (with `data-active` on the selected path), `hierarchy-chart-nodes`, `hierarchy-chart-node` (with `data-yj-node` holding its id, `data-selected`, `data-yj-path` on the selection's ancestors, and `data-state` `open` or `closed` on a branch), `hierarchy-chart-name`, `hierarchy-chart-role`, `hierarchy-chart-toggle` (with `data-state`), `hierarchy-chart-controls` and `hierarchy-chart-zoom`. Connectors use the theme's strong line, and the accent on the selected path.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Open and close | `spring.smooth` | 0.36s, bounce 0 | the toggled node stays put while the others glide to their new places; children grow out of their parent and shrink back into it, and the connectors redraw as they move |
| Zoom, fit and focus | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the view glides to its new place and scale |
| Pan |  |  | the view follows the pointer, the wheel and the pinch, never eased |

**Reduced motion:** Nothing glides: branches open and close in place, and zoom, fit and focus land at once.

#### Reduced motion

Branches open and close in place, connectors are redrawn at once, and zoom, fit and focus jump to their view. Panning is unchanged, since it never animates.

### Accessibility

- The chart is a WAI-ARIA `tree` named by `label` (default "Hierarchy chart") and described by a hint that explains the keys. Each card is a `treeitem` with `aria-level`, `aria-setsize`, `aria-posinset`, `aria-selected` and, on a branch, `aria-expanded`. It's named by the node's `name` and described by its role, its badge and, when closed, how many it hides ("3 hidden below").
- One Tab stop. ↑ and ↓ move through the nodes in reading order, → opens a branch or steps into it, ← closes it or steps out to its parent (mirrored under RTL), Home and End go to the first and last node, and * opens every sibling branch. Enter opens or closes a branch, Space selects. +, − and 0 zoom and fit.
- Focus from the keyboard brings its node into view, and closing a branch that holds the focus hands it to the branch.
- The open/close chip is a pointer shortcut for Enter, hidden from assistive technology; selection is shown by a border and a ring as well as the path's color.
- With sound on, selecting plays `select`, opening a branch `open` and closing it `close`.
- Its words come from the labels (`hierarchyChart`, `hierarchyChartHint`, `hierarchyChartHidden`, `hierarchyChartExpand`, `hierarchyChartCollapse`, `zoomIn`, `zoomOut`, `zoomToFit`), translated by the language packs.

---

# Stat Card

> Analytics tiles: a figure, how it moved, and one picture of its data, on a card or joined in a panel.

Source: https://www.youj.dev/docs/components/stat-card

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, Stat, StatBars, StatBreakdown, StatDelta, StatGroup, StatMeter, StatNote, StatValue } from '@youj/react'

const usd = { style: 'currency', currency: 'USD', notation: 'compact', maximumFractionDigits: 1 } as const

interface Reading {
  mrr: number
  mrrChange: number
  orders: number[]
  lastWeek: number[]
  latency: number
  health: [number, number, number]
}

const FIRST: Reading = {
  mrr: 121_140,
  mrrChange: 0.064,
  orders: [182, 204, 197, 221, 236, 214, 248],
  lastWeek: [171, 188, 201, 194, 210, 205, 219],
  latency: 184,
  health: [41, 15, 8],
}

/** The next live reading: figures drift and the week gains a day. */
function next(r: Reading): Reading {
  const drift = (n: number, spread: number) => Math.max(0, Math.round(n * (1 + (Math.random() - 0.45) * spread)))
  return {
    mrr: drift(r.mrr, 0.04),
    mrrChange: Math.round((Math.random() - 0.3) * 200) / 1000,
    orders: [...r.orders.slice(1), drift(r.orders.at(-1)!, 0.2)],
    lastWeek: [...r.lastWeek.slice(1), drift(r.lastWeek.at(-1)!, 0.1)],
    latency: drift(r.latency, 0.18),
    health: [drift(r.health[0], 0.1), drift(r.health[1], 0.3), drift(r.health[2], 0.4)],
  }
}

export default function StatDesk() {
  const [r, setReading] = useState(FIRST)
  const [loading, setLoading] = useState(false)
  const orders = r.orders.reduce((a, b) => a + b, 0)
  const before = r.lastWeek.reduce((a, b) => a + b, 0)

const refetch = () => {
    setLoading(true)
    setTimeout(() => {
      setReading(next)
      setLoading(false)
    }, 1200)
  }

return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex gap-2">
        <Button variant="outline" size="sm" onClick={() => setReading(next)}>
          Next reading
        </Button>
        <Button variant="ghost" size="sm" onClick={refetch}>
          Refetch
        </Button>
      </div>
      <StatGroup aria-label="This week" className="grid-cols-1 sm:grid-cols-2">
        <Stat label="Monthly recurring revenue" loading={loading}>
          <StatValue locale="en-US" value={r.mrr} format={usd} />
          <StatDelta locale="en-US" value={r.mrrChange}>
            vs. last month
          </StatDelta>
          <StatMeter locale="en-US" value={r.mrr} max={130_000} marker={120_000}>
            of the $130K target
          </StatMeter>
        </Stat>
        <Stat label="Orders" action={<span>7 days</span>} loading={loading}>
          <StatValue locale="en-US" value={orders} />
          <StatDelta locale="en-US" value={(orders - before) / before}>
            vs. last week
          </StatDelta>
          <StatBars data={r.orders} previous={r.lastWeek} tone="accent" label="Orders by day this week, with last week's as ticks" />
        </Stat>
        <Stat label="p95 latency" loading={loading}>
          <StatValue locale="en-US" value={r.latency} format={{ style: 'unit', unit: 'millisecond', unitDisplay: 'short' }} />
          <StatDelta locale="en-US" value={(r.latency - 176) / 176} invert>
            vs. yesterday
          </StatDelta>
          <StatMeter locale="en-US" value={r.latency} max={250} tone={r.latency > 225 ? 'danger' : r.latency > 200 ? 'warning' : 'neutral'}>
            of the 250 ms budget
          </StatMeter>
        </Stat>
        <Stat label="Accounts" loading={loading}>
          <StatValue locale="en-US" value={r.health[0] + r.health[1] + r.health[2]} />
          <StatNote>by health</StatNote>
          <StatBreakdown
            locale="en-US"
            parts={[
              { label: 'Healthy', value: r.health[0], tone: 'neutral' },
              { label: 'At risk', value: r.health[1], tone: 'warning' },
              { label: 'Churning', value: r.health[2], tone: 'danger' },
            ]}
          />
        </Stat>
      </StatGroup>
    </div>
  )
}
```

A dashboard of stat tiles for revenue, orders, latency and health that take a new live reading.

Give a tile the one picture its data calls for, drawn from real values:

- **`StatBars`**: recent readings as thin bars on a baseline, the latest lit and the rest a quiet tint of its `tone`. With `previous`, last period's readings sit on each bar as ticks, so you see where this period beat it. Counts and sums read best as bars.
- **`StatMeter`**: a share of a whole, or progress to a target. The caption leads with the share; `marker` puts a notch on the track (where the pace says you should be by now), and the fill turns warning behind it and success once the target is met.
- **`StatBreakdown`**: how a total splits, one bar in parts from the inline start with a key of names and figures. A neutral part is the quiet gray, so the parts that need attention carry the color, and any part with a value keeps a sliver you can see.

For a rate or an average, a [Sparkline](https://www.youj.dev/docs/components/sparkline) reads better than bars.

### Stat cards

```tsx
'use client'

import { MoreHorizontalIcon } from '@youj/icons'
import { Button, Sparkline, StatBars, StatCard, StatMeter } from '@youj/react'

/* StatCard: one tile on its own Card, its parts as props, and one picture in
 * the `chart` slot. */
export default function StatCards() {
  return (
    <div className="grid w-full gap-3 sm:grid-cols-3">
      <StatCard
        label="Visitors"
        value={48210}
        previous={42891}
        locale="en-US"
        comparison="vs. last week"
        action={
          <Button variant="ghost" size="icon-xs" aria-label="Visitors options">
            <MoreHorizontalIcon />
          </Button>
        }
        chart={<StatBars data={[31, 33, 32, 36, 38, 37, 41, 44, 48]} tone="chart-1" label="Visitors by day, rising" />}
      />
      <StatCard
        label="Error rate"
        value={0.0021}
        previous={0.0029}
        invert
        locale="en-US"
        format={{ style: 'percent', maximumFractionDigits: 2 }}
        comparison="vs. last 30 days"
        chart={<Sparkline data={[29, 31, 27, 26, 28, 24, 25, 23, 22, 21]} color="var(--color-success)" className="h-9" />}
      />
      <StatCard
        label="Seats"
        value={42}
        unit="of 50"
        locale="en-US"
        comparison="8 left on this plan"
        chart={
          <StatMeter locale="en-US" value={42} max={50}>
            in use
          </StatMeter>
        }
      />
    </div>
  )
}
```

Three stat cards, each with its own picture in the chart slot.

`StatCard` is a tile on its own Card, with its parts as props: `value`, `format`, `delta` (or `previous`, which it works the change out from), `comparison` and one picture in `chart`. It takes the Card's props too, `spotlight` included.

```tsx
import { StatBars, StatCard } from '@youj/react'

<StatCard
  label="Visitors"
  value={48210}
  previous={42891}
  comparison="vs. last week"
  chart={<StatBars data={[31, 33, 32, 36, 38, 37, 41, 44, 48]} tone="chart-1" />}
/>
```

### Down is good

```tsx
'use client'

import { StatCard } from '@youj/react'

/* For latency, churn and cost, down is good: `invert` colors the change by
 * the news, while the arrow still follows the number. */
export default function StatCardInvert() {
  return (
    <div className="grid w-full max-w-lg gap-3 sm:grid-cols-2">
      <StatCard
        label="Churn rate"
        value={0.031}
        delta={0.14}
        invert
        locale="en-US"
        comparison="vs. last quarter"
        format={{ style: 'percent', minimumFractionDigits: 1, maximumFractionDigits: 1 }}
      />
      <StatCard
        label="Cloud spend"
        value={18420}
        previous={21300}
        invert
        locale="en-US"
        comparison="last month"
        format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}
      />
    </div>
  )
}
```

A churn rate and a cloud spend where a fall reads as good news.

For latency, churn and cost, a fall is good news. `invert` colors the change by the news (green when it fell), while the triangle still follows the number.

### Deltas

```tsx
'use client'

import { StatDelta } from '@youj/react'

export default function StatDeltas() {
  return (
    <div className="flex flex-col gap-2.5">
      <StatDelta locale="en-US" value={0.124}>
        vs. last month
      </StatDelta>
      <StatDelta locale="en-US" value={-0.031}>
        vs. last month
      </StatDelta>
      <StatDelta locale="en-US" value={-0.092} invert>
        p95 latency, vs. yesterday
      </StatDelta>
      <StatDelta locale="en-US" value={0}>
        vs. last week
      </StatDelta>
      <StatDelta locale="en-US" value={4} format={{ maximumFractionDigits: 0 }}>
        accounts since Monday
      </StatDelta>
    </div>
  )
}
```

A list of deltas, up, down, inverted, flat and as a count.

`StatDelta` works on its own too, in a table cell or beside a heading.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stat-card
```

It brings `card`, `content-swap`, `counter`, `share-bar`, `skeleton`, `youj-core`, `youj-labels-stat-card`, `youj-presets`, `youj-ui-core` with it.

The copy is 12 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `card`, `content-swap`, `counter`, `settled-entrances`, `share-bar`, `skeleton`, `spotlight`.

Use stat tiles for the handful of numbers a dashboard opens with: revenue, orders, latency, accounts. Each one is built like an instrument readout: a small label, one big figure with its unit set small and muted, how it moved (a triangle and the change in the good or bad ink, then what it's compared against), and at most one picture of its data underneath. For a trend people need to read values from, use a [Chart](https://www.youj.dev/docs/components/chart).

```tsx
import { Stat, StatBars, StatDelta, StatGroup, StatMeter, StatValue } from '@youj/react'

<StatGroup aria-label="This week" className="sm:grid-cols-2">
  <Stat label="Monthly recurring revenue">
    <StatValue value={121140} format={{ style: 'currency', currency: 'USD', notation: 'compact', maximumFractionDigits: 1 }} />
    <StatDelta value={0.064}>vs. last month</StatDelta>
    <StatMeter value={121140} max={130000} marker={120000}>of the $130K target</StatMeter>
  </Stat>
  <Stat label="Orders" action={<span>7 days</span>}>
    <StatValue value={1502} />
    <StatDelta value={0.08}>vs. last week</StatDelta>
    <StatBars data={[182, 204, 197, 221, 236, 214, 248]} previous={[171, 188, 201, 194, 210, 205, 219]} />
  </Stat>
</StatGroup>
```

- **`Stat`** is one tile: a group named by its `label`, with an `action` at the end of the label's line (a period, a live marker, a small menu) and `loading`.
- **`StatGroup`** joins tiles into one panel, split by hairlines at the theme's stroke. Any number of tiles wraps cleanly; set the columns with `grid-cols-*`.
- **`StatValue`** is the figure. `format` takes `Intl.NumberFormat` options, so currencies, percentages, compact numbers and units format in the YoujProvider's locale (en-US without one), or the `locale` you pass; `unit` adds words Intl has no unit for ("seats").
- **`StatDelta`** is the change: a fraction by default (`0.124` is 12.4%), or in the value's own terms with `format`. Its children are the comparison. **`StatNote`** is a muted line for when there's no change to show.

Press Next reading in the preview: each figure rolls to its new value, each change counts to its own, the bars morph and a triangle turns when its change does. Refetch shows `loading`: the label stays, and the figures wait behind a skeleton.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Stat

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  | What is measured: "Monthly recurring revenue". Names the tile. |
| `action` | `ReactNode` |  | At the end of the label's line: a period ("30 days"), a live marker, or a small menu button. |
| `loading` | `boolean` | `false` | The figures and picture wait behind a skeleton; the tile is busy. |
| `loadingLabel` | `string` |  | Announced while loading. Default "Loading {label}" when the label is a string. |
| `children` | `ReactNode` |  |  |

Also takes the props of `ComponentProps<'div'>`.

#### StatGroup

`StatGroup` takes [Card](https://www.youj.dev/docs/components/card)'s props. Its columns auto-fit at 11rem and up; set your own with `grid-cols-*`.

#### StatValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `from` | `number` |  | Where the first roll starts. Default 0; pass the value itself to start settled and roll only on a change. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options: currency, percent, compact notation, units. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `unit` | `ReactNode` |  | Words Intl has no unit for, set small and muted after the figure: "seats", "/mo". |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | `sm` for dense strips, `lg` for the one figure a panel leads with. |

Also takes the props of `ComponentProps<'span'>`.

#### StatDelta

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | The change: a fraction (0.124 = 12.4%) by default, or in the value's own terms with `format`. |
| `format` | `Intl.NumberFormatOptions` | `PERCENT` | Intl.NumberFormat options for the change. |
| `invert` | `boolean` | `false` | Down is good for this metric (latency, churn, cost): a fall takes the good ink. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `children` | `ReactNode` |  | What it's compared against, muted after the change: "vs. last month". |

Also takes the props of `ComponentProps<'span'>`.

#### StatBars

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly number[]` |  | The readings, oldest first: one bar each. |
| `previous` | `readonly number[]` |  | Last period's readings, aligned with `data`: a tick on each bar, so you see where it beat them. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'neutral'` | The lit bar's color; the rest are a quiet tint of it. |
| `highlight` | `number \| 'none'` |  | Which bar is lit. Default: the latest. `none` lights none. |
| `max` | `number` |  | The top of the scale. Default: the largest reading (or tick). |
| `label` | `string` |  | Accessible name, e.g. "Orders per hour today, peaking at 11 am". Without it the bars are decorative. |

Also takes the props of `ComponentProps<'div'>`.

#### StatMeter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `max` (required) | `number` |  | The whole, or the target. |
| `marker` | `number` |  | A notch on the track at this value: where the pace says you should be by now, or a limit inside a bigger whole. Behind it, the fill turns warning. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` |  | The fill. Default `accent`; `success` once the value reaches `max`. |
| `segments` | `number` |  | Draw this many cells instead of a solid bar. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `children` | `ReactNode` |  | The words after the share: "of the $150K target". |
| `detail` | `ReactNode` |  | At the end of the caption: "$42K to go". |

Also takes the props of `ComponentProps<'div'>`.

#### StatBreakdown

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parts` (required) | `StatBreakdownPart[]` |  |  |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for each part's figure in the key. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `legend` | `boolean` | `true` | The key under the bar: each part's swatch, name and figure. |

Also takes the props of `ComponentProps<'div'>`.

#### StatCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  | What is measured: "Monthly recurring revenue". |
| `value` (required) | `number` |  |  |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the value: currency, percent, compact, units. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `unit` | `ReactNode` |  | Words Intl has no unit for, small and muted after the value: "seats". |
| `previous` | `number` |  | The previous period's value. Gives the change when `delta` is not set. |
| `delta` | `number` |  | Change as a fraction (0.124 = +12.4%). Default: from `previous`. |
| `invert` | `boolean` | `false` | Down is good for this metric (latency, churn, cost): a fall is shown as good news. |
| `comparison` | `ReactNode` |  | The period compared against, after the change: "vs. last month". Without a change it's a note. |
| `action` | `ReactNode` |  | A slot beside the label: a period, a menu, a link. |
| `chart` | `ReactNode` |  | A slot under the figures: StatBars, StatMeter, StatBreakdown or a Sparkline. |
| `loading` | `boolean` | `false` |  |
| `loadingLabel` | `string` |  | Announced while loading. Default "Loading {label}" when the label is a string. |
| `spotlight` | `boolean` |  | Light the card with motion's Spotlight effect. |
| `variant` | `'default' \| 'inset' \| 'panel'` |  | `inset`: in the Bezel style, a shell carrying the head, with the rest in a well inside it at the concentric radius. Classic draws it as the default card. `panel`: in every style, a slim header strip (the title as a small label, an info tip, a menu button) over the content on a raised surface inset in the shell. |
| `lift` | `boolean` |  | Rise on hover and focus: for cards that are one big target. |
| `size` | `'default' \| 'sm'` |  |  |

`StatCard` passes the rest of its props to [Card](https://www.youj.dev/docs/components/card), at `size="sm"`.

### Right to left

Labels, figures and captions follow the page's direction; the hairlines between tiles move to the inline end, and meters and breakdowns fill from the inline start. Bars and sparklines keep time running left to right.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Value changes | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | motion’s Counter rolls each digit to the new number, a tight stagger step per place from the right |
| Change changes | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the figure counts to its new value |
| Change turns | `spring.snappy` | 0.2s, bounce 0 | the triangle turns to face the new direction |
| Bars arrive | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | each rises from the baseline in turn, left to right, when they scroll into view (a clip, so the rounded tops stay round) |
| New readings | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | bars and ticks morph from where they are |
| Meter fills | `spring.smooth` | 0.36s, bounce 0 | ShareBar’s edge travels to the share; a new value retargets from where it is |
| Breakdown opens | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the parts open from the inline start in turn; a new split glides |
| Figures arrive | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | ContentSwap: rise out of a light blur while the height follows |

**Reduced motion:** Figures, bars, meters and breakdowns are drawn at their values: nothing rolls, rises or opens.

#### Reduced motion

Values swap to the new number without rolling, the triangle shows its new direction at once, bars, meters and breakdowns are drawn at their values, and loaded figures replace the skeleton without a fade or blur.

### Accessibility

- Each tile is a group (`role="group"`) named by its label, so "Monthly recurring revenue, $121.1K, up 6.4% vs. last month" is read as one thing.
- `StatDelta` says "Up", "Down" or "No change" in words before the figure. The triangle and its color are decorative.
- The pictures are decorative by default: the figures and words beside them say the same. Give `StatBars` a `label` to make it an image with a name ("Orders by day this week, rising"). `StatBreakdown`'s key is a list of each part's name and figure.
- While `loading`, a tile sets `aria-busy`, keeps its label, and announces "Loading" and the label (or `loadingLabel`); the new figures are read when they arrive.
- An `action` needs its own name, such as `aria-label="Revenue options"`.

---

# Limit Meter

> Show a value against a limit, with the remaining amount and policy thresholds, such as spending.

Source: https://www.youj.dev/docs/components/limit-meter

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { LimitMeter, Button } from '@youj/react'

export default function LimitMeterDemo() {
  const [spent, setSpent] = useState(1240)
  const [limit, setLimit] = useState(2000)
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      <LimitMeter
        spent={spent}
        limit={limit}
        format={{ style: 'currency', currency: 'EUR' }}
        markers={[{ value: 1800, label: 'freeze', tone: 'warning' }]}
        label="Card limit"
      />
      <div className="flex flex-wrap gap-2">
        <Button size="sm" variant="outline" onClick={() => setSpent((s) => s + 180)}>
          Charge €180
        </Button>
        <Button size="sm" variant="outline" onClick={() => setLimit((l) => l + 250)}>
          Raise limit €250
        </Button>
        <Button size="sm" variant="ghost" onClick={() => (setSpent(1240), setLimit(2000))}>
          Reset
        </Button>
      </div>
    </div>
  )
}
```

A card limit of 1,240 spent against 2,000 with a freeze line at 1,800, and buttons to charge, raise the limit or reset.

- The caret under the ruler points up at the spend, with a hairline across the ruler above it. Marker names sit over the ruler, pushed apart when two are close.
- Ticks already spent are lit in `tone` (default `success`).
- The stretch still to go before a marker takes the marker's tone: the runway to it.
- Ticks past the last marker are dim.
- Spending past a marker turns those ticks to its tone, and spending past the limit turns the headline to "Over limit" with the overage in danger.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add limit-meter
```

It brings `youj-core`, `youj-labels-limit-meter`, `youj-presets`, `youj-ui-core` with it.

Use an limit meter for a budget: what is left, large, with the spent and the limit as a quiet readout under it, over a ruler from zero to the limit. An index caret under the ruler points at the spend, and named lines mark the policies that act on it, so "how far until the card freezes" reads off the ruler.

```tsx
import { LimitMeter } from '@youj/react'

<LimitMeter
  spent={1240}
  limit={2000}
  format={{ style: 'currency', currency: 'EUR' }}
  markers={[{ value: 1800, label: 'freeze', tone: 'warning' }]}
  label="Card limit"
/>
```

The ruler has 50 minor intervals with a major tick every 10 (`ticks`, `majorEvery`), and zero, the middle and the limit labeled under it. The remainder's decimals are set quieter than its whole part, whatever the locale's currency format. For a unit Intl has none for (GB, kcal), pass `formatValue` instead of `format`: a function that writes every amount and the scale.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spent` (required) | `number` |  |  |
| `limit` (required) | `number` |  |  |
| `markers` | `AllowanceMarker[]` |  | Named lines on the ruler, e.g. the amount at which a card freezes. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the amounts, e.g. `{ style: 'currency', currency: 'EUR' }`. Default: two decimals. |
| `formatValue` | `(value: number) => string` |  | Writes every amount (and the scale) with your own function, for units Intl has none for ("12.5 TB"). Replaces `format`. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `ticks` | `number` | `50` | Minor intervals on the ruler. |
| `majorEvery` | `number` | `10` | Every how many minor ticks a major one falls. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'success'` | The spent ticks' tone. |
| `label` | `string` |  | Names the meter for assistive tech. Default: the visible "Remaining". |

Also takes the props of `MeterPrimitive.Root.Props`.

### Styling

Parts: `limit-meter`, `limit-meter-header`, `limit-meter-label`, `limit-meter-remaining`, `limit-meter-fraction`, `limit-meter-summary`, `limit-meter-stat`, `limit-meter-scale`, `limit-meter-flags`, `limit-meter-flag`, `limit-meter-ruler`, `limit-meter-tick` (with `data-major` and `data-zone`: `spent`, `runway` or `idle`), `limit-meter-marker`, `limit-meter-spent` (the hairline at the spend), `limit-meter-caret` and `limit-meter-axis`. The root has `data-state` (`within` or `over`).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate` | 560ms | when it scrolls into view the spend sweeps up from zero at a constant rate: the caret rides the front and the ticks light as it passes |
| Each tick | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades to its zone’s tone |
| New spend or limit | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | sweeps on from where the caret is; markers glide to their new place |

**Reduced motion:** Drawn at its value; a new spend or limit is drawn in place.

#### Reduced motion

The ruler, the caret and the ticks are drawn at the value, with no sweep.

### Accessibility

- It's a `meter` (Base UI Meter) whose value is the spend and whose maximum is the limit. Name it with `label`; without one it's named by the visible "Remaining", which reads "Over limit" once the spend passes the limit.
- Its value text says it all: "€1,240.00 spent of €2,000.00, €760.00 left, freeze at €1,800.00". Every word comes from `labels` (`allowanceValueText`, `allowanceOverText`, `allowanceMarkerAt`, …), translated in all 14 language packs.
- The ruler is hidden from assistive tech. It runs from the inline start, so right to left in RTL.

---

# Treemap

> Compare parts of a whole as cells sized by value, with tooltips and keyboard access.

Source: https://www.youj.dev/docs/components/treemap

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, Treemap, type TreemapItem } from '@youj/react'

/** A web app's JavaScript, gzipped, by package. */
const BUNDLE: TreemapItem[] = [
  { id: 'app', name: 'app code', value: 164 },
  { id: 'react-dom', name: 'react-dom', value: 131 },
  { id: 'recharts', name: 'recharts', value: 96 },
  { id: 'prosemirror', name: 'prosemirror', value: 74 },
  { id: 'motion', name: 'motion', value: 52 },
  { id: 'date-fns', name: 'date-fns', value: 31 },
  { id: 'zod', name: 'zod', value: 18 },
  { id: 'rest', name: 'the rest', value: 12 },
]
const kb = new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilobyte' }).format

export default function TreemapDemo() {
  const [items, setItems] = useState(BUNDLE)
  // Loading the charts on demand moves 88 kB out of the first load: the map re-lays itself around the change.
  const split = items.find((item) => item.id === 'recharts')!.value < 96
  return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <Treemap items={items} highlight="recharts" formatValue={kb} label="Bundle by package" />
      <Button
        variant="outline"
        size="sm"
        className="self-start"
        onClick={() => setItems(split ? BUNDLE : items.map((item) => (item.id === 'recharts' ? { ...item, value: item.value - 88 } : item)))}
      >
        {split ? 'Bundle the charts again' : 'Load the charts on demand'}
      </Button>
    </div>
  )
}
```

A web app's bundle by package, with a button that loads the charts on demand and re-lays the map.

### Highlight and tone

```tsx
'use client'

import { Treemap } from '@youj/react'

const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }).format

export default function TreemapTones() {
  return (
    <Treemap
      className="w-full max-w-xl"
      aspect={2.6}
      label="Spend by line item"
      formatValue={usd}
      highlight="bandwidth"
      items={[
        { id: 'compute', name: 'Compute', value: 4200, tone: 'chart-1' },
        { id: 'database', name: 'Database', value: 2100, tone: 'chart-2' },
        { id: 'bandwidth', name: 'Bandwidth', value: 1500, tone: 'warning' },
        { id: 'support', name: 'Support', value: 900, tone: 'chart-3' },
        { id: 'failed', name: 'Failed jobs', value: 640, tone: 'danger' },
        { id: 'credits', name: 'Credits', value: 400, tone: 'success' },
      ]}
    />
  )
}
```

Spend by line item, with one highlighted cell and a tone on each category.

`highlight` takes one id or several: those cells are tinted and outlined in their tone, the accent unless the item sets one. An item's `tone` alone tints its cell faintly, for categories that carry a color of their own.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add treemap
```

It brings `tooltip`, `use-resize-measure`, `youj-core`, `youj-labels-treemap`, `youj-presets`, `youj-ui-core` with it.

Use a treemap when the question is "where does it all go": a bundle by package, a disk by table, spend by line item. Each part is a cell whose area is its value, laid out squarified so cells stay close to square and compare by eye, largest first from the top-start corner. For one part's share in a row, use a [Share Bar](https://www.youj.dev/docs/components/share-bar); for exact values people compare or sort, a table.

```tsx
import { Treemap } from '@youj/react'

const kb = new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilobyte' }).format

<Treemap
  label="Bundle by package"
  items={[
    { id: 'app', name: 'app code', value: 164 },
    { id: 'react-dom', name: 'react-dom', value: 131 },
    { id: 'recharts', name: 'recharts', value: 96 },
  ]}
  highlight="recharts"
  formatValue={kb}
/>
```

It's a wide strip by default (`aspect` 3.5, width to height); pass another `aspect`, or a height class, which wins. Cells show the name and value where they have room, the name alone when smaller and nothing in a sliver, and every cell keeps its tooltip with the name, the value and its share of the total. Items at zero or below are left out, and with nothing to show it says so.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly TreemapItem[]` |  |  |
| `highlight` | `string \| readonly string[]` |  | Ids of the items to highlight. |
| `formatValue` | `(value: number) => string` |  | Formats values in cells, the tooltip and the spoken text. Default: the locale's number format. |
| `label` | `string` |  | Accessible name of the map. Default: the labels' "Treemap". |
| `gap` | `number` | `4` | Space between cells, in px. |
| `aspect` | `number` |  | Width to height. Default 3.5, a wide strip; a height class wins over it. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | cells fade in largest first when a third of the map scrolls into view |
| New data | `spring.smooth` | 0.36s, bounce 0 | the map re-lays itself with a FLIP, so only transforms move; labels keep their size |
| Parts come and go | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | a part that leaves fades out where it was; a new one fades in |
| Highlight | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fill, border and text change color |

**Reduced motion:** Drawn in place; new data and highlights land at once.

#### Reduced motion

Cells are drawn in place, and new data and highlights land at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Treemap") holding a `list`, largest first. Each item is named with its value, its share and whether it's highlighted ("recharts: 96 kB, 17% of total, highlighted").
- A summary describes the group: how many parts, their total and the largest.
- One tab stop. The arrow keys move to the nearest cell in that direction as laid out, in either text direction; Home and End go to the largest and the smallest. Focus shows the tooltip, as hover does.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Unit Chart

> Show counts per bucket as stacked dots, one dot per unit, over a faint grid.

Source: https://www.youj.dev/docs/components/unit-chart

## Examples

### Demo

```tsx
'use client'

import { UnitChart } from '@youj/react'

/** Quarter-hour slots from 11:30, as "HH:MM". */
const slot = (i: number) => {
  const minutes = 11 * 60 + 30 + i * 15
  return `${String(Math.floor(minutes / 60)).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`
}

/** A bistro's expected covers per quarter hour: a lunch rush, a quiet afternoon, a longer dinner. */
const COVERS = [
  3, 6, 9, 12, 13, 11, 9, 7, 5, 3, 2, 1, 0, 0, 0, 1, 1, 2, 3, 5, 8, 11, 14, 17, 19, 18, 16, 14, 12, 10, 8, 6, 5, 4, 3, 2, 1, 1, 0, 0, 0, 1, 0, 0,
].map((value, i) => ({ label: slot(i), value }))

const covers = (value: number) => `${value} ${value === 1 ? 'cover' : 'covers'}`

export default function UnitChartDemo() {
  const total = COVERS.reduce((sum, bucket) => sum + bucket.value, 0)
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <div className="flex items-baseline justify-between gap-4">
        <div className="flex items-baseline gap-2">
          <span className="text-3xl font-medium tabular-nums">{total}</span>
          <span className="text-sm text-fg-muted">covers expected</span>
        </div>
        <span className="text-sm text-fg-muted">One dot, one cover</span>
      </div>
      <UnitChart data={COVERS} formatValue={covers} label="Covers through the day" tickEvery={8} highlight={[18, 33]} />
    </div>
  )
}
```

A bistro's expected covers per quarter hour, with the dinner service highlighted.

### Unit

```tsx
'use client'

import { UnitChart } from '@youj/react'

/** Support tickets per hour over a day. */
const TICKETS = [12, 8, 5, 4, 6, 10, 22, 48, 85, 110, 124, 118, 96, 102, 115, 108, 92, 70, 52, 40, 33, 28, 20, 15].map((value, hour) => ({
  label: `${String(hour).padStart(2, '0')}:00`,
  value,
}))

export default function UnitChartUnit() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <UnitChart data={TICKETS} unit={5} tone="chart-2" tickEvery={6} label="Support tickets by hour" formatValue={(v) => `${v} tickets`} />
      <p className="text-sm text-fg-muted">Each dot is five tickets.</p>
    </div>
  )
}
```

Support tickets per hour, where each dot counts for five tickets, in a chart tone.

`unit` sets how much one dot counts for; each column rounds to whole dots. Say what a dot is next to the chart: the reader needs it to read the count.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add unit-chart
```

It brings `tooltip`, `youj-core`, `youj-labels-unit-chart`, `youj-presets`, `youj-ui-core` with it.

Use a unit chart when the counts are small enough to see one by one and that matters: covers through a service, tickets by hour, signups by day. Each column is a bucket and each dot one unit, stacked from the baseline over a faint grid of every dot the chart could hold, so the empty room reads as part of the scale. For larger values, or a trend with tooltips on several series, use a [Chart](https://www.youj.dev/docs/components/chart); for a distribution someone filters, a [Histogram Range](https://www.youj.dev/docs/components/histogram-range).

```tsx
import { UnitChart } from '@youj/react'

<UnitChart
  label="Covers through the day"
  data={[
    { label: '11:30', value: 3 },
    { label: '11:45', value: 6 },
    { label: '12:00', value: 9 },
  ]}
  highlight={[1, 2]}
  formatValue={(v) => `${v} covers`}
/>
```

The grid is as tall as the peak with some headroom; pass `rows` to keep the scale still when the data changes. Labels sit under about six columns; `tickEvery` sets the step. `highlight` takes the first and last index of a range to keep in the tone, and the rest go quiet.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly UnitChartBucket[]` |  |  |
| `unit` | `number` | `1` | How much one dot counts for. |
| `rows` | `number` |  | The grid's height in dots. Default: the peak with some headroom; pass one to keep the scale still across data. |
| `highlight` | `readonly [number, number]` |  | The first and last index of the buckets to keep in the tone; the rest go quiet. |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The lit dots' color. |
| `formatValue` | `(value: number) => string` |  | Formats values in the tooltip and the spoken text. Default: the locale's number format. |
| `label` | `string` |  | Accessible name of the chart. Default: the labels' "Unit chart". |
| `tickEvery` | `number` |  | Label every nth column. Default: about six labels across. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `unit-chart`, `unit-chart-plot`, `unit-chart-columns`, `unit-chart-column`, `unit-chart-dots`, `unit-chart-dot`, `unit-chart-axis`, `unit-chart-tick`, `unit-chart-summary`, `unit-chart-tooltip` and `unit-chart-empty`. Each dot has `data-state` (`on` or `off`); a column inside the `highlight` range has `data-highlighted`. The root sets `--unit-chart-tone`, the lit dots' color, and `--unit-chart-off`, the empty ones'.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the dots light column by column from the start, each from the baseline up, when a third of the chart scrolls into view |
| New data | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | dots that change light or darken in the same wave |
| Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | a band washes behind the column |

**Reduced motion:** Drawn in place; new data lands at once.

#### Reduced motion

The dots are drawn in place, and new data lands at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Unit chart") holding a `list` of the columns. Each is named with its label and value, and whether it's highlighted ("19:00: 19 covers, highlighted").
- A summary describes the group: how many columns, the total and the peak.
- One tab stop. The arrow keys walk the columns in the order they're drawn, in either text direction; Home and End go to the first and last. Focus shows the tooltip, as hover does.
- The dots and the axis are decorative; everything they show is in the names.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Waffle Chart

> Show a whole as countable cells colored by part, square or hexagonal, with a legend that lights each part.

Source: https://www.youj.dev/docs/components/waffle-chart

## Examples

### Demo

```tsx
'use client'

import { WaffleChart } from '@youj/react'

/** A kitchen's food waste over a week, in kilograms, by where it came from. */
const WASTE = [
  { id: 'trim', name: 'Produce trim', value: 22 },
  { id: 'plates', name: 'Plate returns', value: 17 },
  { id: 'overprep', name: 'Overprep', value: 15 },
  { id: 'bread', name: 'Bread', value: 11 },
  { id: 'dairy', name: 'Dairy', value: 7 },
]

export default function WaffleChartDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <div className="flex items-baseline gap-2">
        <span className="text-3xl font-medium tabular-nums">72 kg</span>
        <span className="text-sm text-fg-muted">this week. Each cell is 1 kg.</span>
      </div>
      <WaffleChart items={WASTE} shape="hex" layout="cluster" columns={16} rows={10} label="Waste by source" formatValue={(v) => `${v} kg`} />
    </div>
  )
}
```

A kitchen's food waste over a week by source, as a cluster of hexagons, one per kilogram.

### Rows

```tsx
'use client'

import { WaffleChart } from '@youj/react'

/** A team's storage, in GB, by file type. */
const STORAGE = [
  { id: 'video', name: 'Video', value: 412 },
  { id: 'images', name: 'Images', value: 236 },
  { id: 'docs', name: 'Documents', value: 128 },
  { id: 'archives', name: 'Archives', value: 94 },
  { id: 'other', name: 'Other', value: 50, tone: 'neutral' as const },
]

export default function WaffleChartRows() {
  return (
    <div className="flex w-full max-w-md flex-col gap-2">
      <WaffleChart items={STORAGE} unit={10} columns={15} label="Storage by file type" formatValue={(v) => `${v} GB`} />
      <p className="text-sm text-fg-muted">Each cell is 10 GB.</p>
    </div>
  )
}
```

A team's storage by file type in square cells filled row by row, each cell ten gigabytes, with the remainder in the neutral tone.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add waffle-chart
```

It brings `youj-core`, `youj-labels-waffle-chart`, `youj-presets`, `youj-ui-core` with it.

Use a waffle chart when a whole splits into a few parts and the count matters as much as the share: waste by source, seats by plan, storage by type. Each cell is one unit, colored by its part, so shares read as areas you could count. For many parts, or parts that differ by orders of magnitude, use a [Treemap](https://www.youj.dev/docs/components/treemap); for one share in a row, a [Share Bar](https://www.youj.dev/docs/components/share-bar).

```tsx
import { WaffleChart } from '@youj/react'

<WaffleChart
  label="Waste by source"
  items={[
    { id: 'trim', name: 'Produce trim', value: 22 },
    { id: 'plates', name: 'Plate returns', value: 17 },
    { id: 'bread', name: 'Bread', value: 11 },
  ]}
  formatValue={(v) => `${v} kg`}
/>
```

`unit` sets how much one cell counts for, and each part rounds to whole cells. `layout="rows"` (the default) fills from the top-start corner row by row; `layout="cluster"` gathers the cells into a round patch at the center, each part a wedge, with empty cells around it. `shape="hex"` draws hexagons. The grid is `columns` wide (20 by default) and as tall as it needs, or `rows` tall; it grows when the cells don't fit. Parts take the chart colors in order unless they set a `tone`. Say what a cell is next to the chart.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly WaffleChartItem[]` |  |  |
| `unit` | `number` | `1` | How much one cell counts for. |
| `columns` | `number` | `20` | Cells across. |
| `rows` | `number` |  | Cells down. Default: enough to hold every filled cell, with room around a cluster. |
| `shape` | `'square' \| 'hex'` | `'square'` |  |
| `layout` | `'rows' \| 'cluster'` | `'rows'` | `rows` fills from the top-start corner, row by row; `cluster` gathers the cells at the center, each part a wedge. |
| `formatValue` | `(value: number) => string` |  | Formats values in the legend's spoken text and the summary. Default: the locale's number format. |
| `label` | `string` |  | Accessible name of the chart. Default: the labels' "Waffle chart". |
| `legend` | `boolean` | `true` | Show the legend under the cells. |
| `config` | `Readonly<Record<string, { color?: string }>>` |  | A ChartConfig shared with your other charts: an item whose id is a key takes its color, so one series matches across chart types. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `waffle-chart`, `waffle-chart-cells`, `waffle-chart-cell`, `waffle-chart-legend`, `waffle-chart-legend-item`, `waffle-chart-swatch`, `waffle-chart-legend-name`, `waffle-chart-legend-share`, `waffle-chart-summary` and `waffle-chart-empty`. Each cell has `data-state` (`on` or `off`) and, when filled, `data-tone`; a legend item has `data-tone`, and `data-active` while its part is lit. `--waffle-chart-off` on the root is the empty cells' color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the cells fill in order, along the rows or outward from the center for a cluster, when a third of the chart scrolls into view |
| New data | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | cells that change part recolor in the same order |
| Lighting a part | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the other parts fade back at once, without waiting |

**Reduced motion:** Drawn in place; new data lands at once.

#### Reduced motion

The cells are drawn in place, and new data lands at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Waffle chart"), described by a summary: how many parts, their total and the largest.
- The legend is a `list`; each part is named with its value and share ("Bread: 11 kg, 15% of total").
- The legend is one tab stop. The arrow keys walk the parts, Home and End go to the first and last, and Escape lets go. Focusing a part lights its cells, as hovering it or one of its cells does.
- The cells are decorative; everything they show is in the legend and the summary. Color is never the only cue: each part's name and share are written beside its swatch.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Radar Chart

> Compare several things on the same axes, one filled shape each, with axis tooltips, a series legend and a keyboard-readable plot.

Source: https://www.youj.dev/docs/components/radar-chart

## Examples

### Demo

```tsx
'use client'

import { RadarChart } from '@youj/react'

const AXES = [
  { id: 'reasoning', label: 'Reasoning', description: 'How well it works through problems that take several steps.' },
  { id: 'code', label: 'Code', description: 'Writing, explaining and fixing programs.' },
  { id: 'speed', label: 'Speed', description: 'How quickly the first words arrive and how fast the rest follow.' },
  { id: 'value', label: 'Value', description: 'What you get for each dollar spent.' },
  { id: 'memory', label: 'Memory', description: 'How much of a long conversation or document it keeps in view.' },
  { id: 'vision', label: 'Vision', description: 'Reading images, charts and screenshots.' },
  { id: 'tools', label: 'Tools', description: 'Calling other programs and using what comes back.' },
  { id: 'safety', label: 'Safety', description: 'Staying within its limits when pushed.' },
]

/** Three made-up assistants scored out of 100. */
const SERIES = [
  { id: 'atlas', name: 'Atlas 2', values: [88, 82, 56, 48, 90, 76, 84, 80] },
  { id: 'quill', name: 'Quill S', values: [64, 70, 92, 90, 52, 58, 66, 72] },
  { id: 'meridian', name: 'Meridian', values: [76, 58, 70, 66, 70, 88, 52, 90] },
]

export default function RadarChartDemo() {
  return (
    <div className="w-full max-w-xl">
      <RadarChart axes={AXES} series={SERIES} label="Assistants compared" />
    </div>
  )
}
```

Three made-up assistants scored on eight things. Hover or focus an axis label to see what it measures, hover or focus a point to read its value, and press a name in the legend to take its shape out of the plot.

### Scale

```tsx
'use client'

import { RadarChart } from '@youj/react'

const AXES = [
  { id: 'sleep', label: 'Sleep' },
  { id: 'focus', label: 'Focus' },
  { id: 'mood', label: 'Mood' },
  { id: 'energy', label: 'Energy' },
  { id: 'calm', label: 'Calm' },
]

/** Two check-ins on a 0 to 10 scale. */
const SERIES = [
  { id: 'mon', name: 'Monday', values: [6, 7, 5, 6, 4], tone: 'chart-5' as const },
  { id: 'fri', name: 'Friday', values: [8, 6, 9, 7, 8], tone: 'chart-4' as const },
]

export default function RadarChartScale() {
  return (
    <div className="w-full max-w-md">
      <RadarChart axes={AXES} series={SERIES} max={10} rings={5} formatValue={(v) => `${v} of 10`} label="Week check-in" />
    </div>
  )
}
```

Two weekly check-ins on a fixed 0 to 10 scale with five rings, and values written with their scale.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add radar-chart
```

It brings `tooltip`, `youj-core`, `youj-labels-radar-chart`, `youj-presets`, `youj-ui-core` with it.

Use a radar chart to compare a handful of things on the same few measures, when the overall shape matters more than any one number: models, plans, candidates, products. Keep it to three to eight axes and a few series. For one thing over time use a [Sparkline](https://www.youj.dev/docs/components/sparkline); for exact values side by side, a table; the [Compare items](https://www.youj.dev/docs/blocks/trends-and-comparisons) card pairs this chart with an overview table.

```tsx
import { RadarChart } from '@youj/react'

<RadarChart
  label="Assistants compared"
  axes={[
    { id: 'reasoning', label: 'Reasoning', description: 'How well it works through multi-step problems.' },
    { id: 'speed', label: 'Speed' },
    { id: 'safety', label: 'Safety' },
  ]}
  series={[
    { id: 'atlas', name: 'Atlas 2', values: [88, 56, 80] },
    { id: 'quill', name: 'Quill S', values: [64, 92, 72] },
  ]}
/>
```

`axes` are drawn clockwise from the top, and each series gives one value per axis in the same order. The scale runs from zero at the center to `max` at the outer ring (by default the largest value rounded up to a round number; pass one to keep the scale still as data changes), divided by `rings`. Series take the chart colors in order unless they set a `tone`. `formatValue` writes values with their unit, and `legendEnd` adds your own controls beside the legend. Fewer than three axes, or no series, shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `axes` (required) | `readonly RadarChartAxis[]` |  |  |
| `series` (required) | `readonly RadarChartSeries[]` |  |  |
| `max` | `number` |  | The value at the outer ring. Default: the largest value rounded up to a round number. |
| `rings` | `number` | `4` | How many rings divide the scale. |
| `formatValue` | `(value: number, axis: RadarChartAxis) => string` |  | Formats values for the readout, the table and the spoken points. Default: the locale's number format. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Names the chart for assistive tech. Default: the labels' "Radar chart". |
| `legend` | `boolean` | `true` | Show the legend under the plot. |
| `legendEnd` | `ReactNode` |  | Rendered in place of the legend, e.g. your own series controls. |
| `config` | `Readonly<Record<string, { color?: string }>>` |  | A ChartConfig shared with your other charts: a series whose id is a key takes its color, so one series matches across chart types. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `radar-chart`, `radar-chart-stage`, `radar-chart-plot`, `radar-chart-ring`, `radar-chart-spoke`, `radar-chart-series`, `radar-chart-points`, `radar-chart-point`, `radar-chart-axis`, `radar-chart-readout`, `radar-chart-swatch`, `radar-chart-legend`, `radar-chart-legend-item`, `radar-chart-table` and `radar-chart-empty`. A series has `data-state` (`shown` or `hidden`) and `data-tone`; the readout has `data-state` (`open` or `closed`); a legend item has `data-state` too. A series' color is `--radar-chart-tone` on its group.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | every shape opens from the center, its corners sliding out along the spokes, when a third of the chart scrolls into view |
| New values, toggling a series | `spring.smooth` | 0.36s, bounce 0 | shapes morph to their new corners; a hidden series folds to the center |
| Lighting a series, an axis or a point | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the other shapes quiet, the spoke strengthens, the readout fades in |

**Reduced motion:** Drawn in place; new values and toggles land at once.

#### Reduced motion

The shapes are drawn in place, and new values and toggled series land at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Radar chart"). Every point is an image named "series, axis: value" ("Atlas 2, Reasoning: 88"), and a visually hidden table holds every number, with the series as columns and the axes as rows.
- The plot is one tab stop. Left and Right walk the axes, Up and Down the series, Home and End go to the first and last axis, and Escape lets go. Focusing a point reads it out beside the point and lights its series, as hovering it does.
- An axis with a `description` is a focusable label: its tooltip appears on hover or focus, and the sentence is also the label's accessible description.
- The legend is a row of toggle buttons (`aria-pressed`), each reachable with Tab. Color is never the only cue: every series is named in the legend, the readout and the table.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Radial Graph

> Show what one thing reaches, in rings by how many hops away, with each node's kind, state and path from the center.

Source: https://www.youj.dev/docs/components/radial-graph

## Examples

### Demo

```tsx
'use client'

import { RadialGraph, type RadialGraphNode } from '@youj/react'

/** A made-up service account and what it can reach: the vault and a bucket were hit, three more are exposed through them. */
const NODES: RadialGraphNode[] = [
  { id: 'vault', label: 'secrets-vault', tone: 'chart-3', ring: 'solid', state: 'Hit', detail: 'Read with the leaked token' },
  { id: 'queue', label: 'jobs-queue', tone: 'chart-1' },
  { id: 'bucket', label: 'exports-bucket', tone: 'chart-5', ring: 'solid', state: 'Hit', detail: 'Listed twice in a minute' },
  { id: 'db', label: 'orders-db', tone: 'chart-1' },
  { id: 'cache', label: 'session-cache', tone: 'chart-5' },
  { id: 'api', label: 'billing-api', via: 'vault', tone: 'chart-3', ring: 'dashed', state: 'Exposed', detail: 'Its key is in the vault' },
  { id: 'ci', label: 'ci-runner', via: 'vault', tone: 'chart-1' },
  { id: 'worker', label: 'report-worker', via: 'queue', tone: 'chart-1' },
  { id: 'archive', label: 'cold-archive', via: 'bucket', tone: 'chart-5', ring: 'dashed', state: 'Exposed', detail: 'Same bucket policy' },
  { id: 'cdn', label: 'assets-cdn', via: 'bucket', tone: 'chart-5' },
  { id: 'replica', label: 'orders-replica', via: 'db', tone: 'chart-1', ring: 'dashed', state: 'Exposed', detail: 'Replicates from orders-db' },
  { id: 'warehouse', label: 'warehouse', via: 'db', tone: 'chart-1' },
]

export default function RadialGraphDemo() {
  return (
    <div className="w-full max-w-sm">
      <RadialGraph center={{ id: 'svc', label: 'svc-reports', short: 'SR' }} nodes={NODES} label="What svc-reports can reach" />
    </div>
  )
}
```

A made-up service account and what it can reach. Two things were hit (a solid ring and a solid link) and three more are exposed through them (dashed). Hover or focus a node to read it and light its path from the center.

### Hops

```tsx
'use client'

import { useState } from 'react'
import { RadialGraph, SegmentedControl, SegmentedControlItem, type RadialGraphNode } from '@youj/react'

/** A person and the teams around them, two rings deep. */
const NODES: RadialGraphNode[] = [
  { id: 'design', label: 'Design', tone: 'chart-4' },
  { id: 'research', label: 'Research', tone: 'chart-4' },
  { id: 'platform', label: 'Platform', tone: 'chart-5' },
  { id: 'brand', label: 'Brand', via: 'design', tone: 'chart-4' },
  { id: 'motion', label: 'Motion', via: 'design', tone: 'chart-4', ring: 'solid', ringTone: 'accent', state: 'New this week' },
  { id: 'insights', label: 'Insights', via: 'research', tone: 'chart-4' },
  { id: 'infra', label: 'Infra', via: 'platform', tone: 'chart-5' },
  { id: 'data', label: 'Data', via: 'platform', tone: 'chart-5' },
]

export default function RadialGraphHops() {
  const [hops, setHops] = useState('2')
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-4">
      <SegmentedControl variant="pill" aria-label="Rings" value={hops} onValueChange={setHops}>
        <SegmentedControlItem value="1">1 hop</SegmentedControlItem>
        <SegmentedControlItem value="2">2 hops</SegmentedControlItem>
      </SegmentedControl>
      <RadialGraph center={{ id: 'noor', label: 'Noor Haddad', tone: 'chart-2' }} nodes={NODES} hops={Number(hops)} label="Teams around Noor" />
    </div>
  )
}
```

`hops` shows fewer rings: the outer nodes fold into the ones they hang from, and unfold on the same spot.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add radial-graph
```

It brings `tooltip`, `youj-core`, `youj-labels-radial-graph`, `youj-presets`, `youj-ui-core` with it.

Use a radial graph when the question is "what does this one thing reach, and how directly": the blast radius of a compromised account, the services a change touches, the people around a person. Each node hangs from its `via` (or from the center), so a branch reads as a wedge, and its ring says how many hops out it is. For a run or pipeline with an order, use a [Flow Graph](https://www.youj.dev/docs/components/flow-graph); for a hierarchy you browse, a [Hierarchy Chart](https://www.youj.dev/docs/components/hierarchy-chart). The [Radial network](https://www.youj.dev/docs/blocks/networks-and-maps#radial-network) card is built on it.

```tsx
import { RadialGraph } from '@youj/react'

<RadialGraph
  label="What svc-reports can reach"
  center={{ id: 'svc', label: 'svc-reports', short: 'SR' }}
  nodes={[
    { id: 'vault', label: 'secrets-vault', tone: 'chart-3', ring: 'solid', state: 'Hit', detail: 'Read with the leaked token' },
    { id: 'queue', label: 'jobs-queue', tone: 'chart-1' },
    { id: 'api', label: 'billing-api', via: 'vault', ring: 'dashed', state: 'Exposed' },
  ]}
/>
```

A node's `tone` colors its dot (its kind); `ring` draws its state around it, `solid` or `dashed` in `ringTone` (danger by default), and the link into it takes the same line, so a path through the graph shows at a glance. `state` and `detail` are shown in its tooltip and spoken with it. The rings are spaced evenly out to the deepest node and named in a quiet gap ("1 hop", "2 hops"; `ringLabels={false}` hides them). A `via` that is unknown, or that loops, hangs the node from the center. No nodes shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `center` (required) | `RadialGraphCenter` |  | What the graph is drawn around. Its tone defaults to 'accent'. |
| `nodes` (required) | `readonly RadialGraphNode[]` |  | Everything linked to it, in any order: each hangs from its `via`, or from the center. |
| `hops` | `number` |  | How many rings to show; the nodes past it fold into the ones they hang from. Default: all. |
| `ringLabels` | `boolean` | `true` | Name each ring in a gap beside it ("1 hop"). |
| `label` | `string` |  | Accessible name of the graph. Default: the labels' "Radial graph". |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `radial-graph`, `radial-graph-stage`, `radial-graph-plot`, `radial-graph-ring`, `radial-graph-link`, `radial-graph-center`, `radial-graph-node`, `radial-graph-caption`, `radial-graph-short`, `radial-graph-nodes`, `radial-graph-target`, `radial-graph-tooltip`, `radial-graph-summary` and `radial-graph-empty`. A node, its link and the center have `data-yj-ring` (`solid` or `dashed`) when they carry a state; a node and a ring have `data-state` (`shown`, or `folded` and `hidden` past `hops`). The gap kept round each dot is `--radial-graph-gap` (the surface by default): set it to the color behind the graph.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the nodes travel out from the center ring by ring and their links fade in, when a third of the graph scrolls into view |
| Folding and unfolding | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | nodes past `hops` glide into the node they hang from and fade; they come back out the same way |
| Reading a node | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | its path from the center strengthens, the rest quiet, its dot grows a step |

**Reduced motion:** Drawn in place; folds land at once.

#### Reduced motion

The graph is drawn in place, and folding or unfolding lands at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Radial graph") described by a summary: how many nodes are linked to the center, and within how many hops.
- The nodes are a list, the center first and then each ring clockwise from the top. Each is named with its label and distance ("shared-drive, 2 hops away") and described by its `state` and `detail`. Color is never the only cue: the state is in words, and solid and dashed rings tell hit from exposed.
- One tab stop. Left and Right walk a ring (mirrored in RTL), Down follows a link outward, Up goes back toward the center, Home and End go to the center and the last node. Focus shows the node's tooltip and lights its path, as hovering does.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Density Lanes

> Show when things happen, one lane of dots per kind, swelling where it's busy, on one scale with a highlight and a marker.

Source: https://www.youj.dev/docs/components/density-lanes

## Examples

### Demo

```tsx
'use client'

import { DensityLanes, type DensityLane } from '@youj/react'

/** Half-hours of a day, "00:00" to "23:30", and a label every six hours. */
const COLUMNS = Array.from({ length: 48 }, (_, i) => `${String(Math.floor(i / 2)).padStart(2, '0')}:${i % 2 ? '30' : '00'}`)
const TICKS = [0, 12, 24, 36, 48].map((at) => ({ at, label: String(at / 2).padStart(2, '0') }))

/** A swell around `peak` (a half-hour index), over a low floor. */
const swell = (peak: number, height: number, width: number, floor = 4) =>
  COLUMNS.map((_, i) => Math.round(floor + height * Math.exp(-((i - peak) ** 2) / (2 * width * width))))

/** A made-up café's orders through a day, by channel. */
const LANES: DensityLane[] = [
  { id: 'counter', label: 'Counter', values: swell(17, 60, 5) },
  { id: 'app', label: 'App', values: swell(24, 46, 7) },
  { id: 'delivery', label: 'Delivery', values: swell(38, 52, 4) },
  { id: 'catering', label: 'Catering', values: swell(22, 24, 3, 1) },
]

export default function DensityLanesDemo() {
  return (
    <div className="w-full max-w-lg">
      <DensityLanes lanes={LANES} columns={COLUMNS} ticks={TICKS} formatValue={(v) => `${v} orders`} label="Orders through the day, by channel" />
    </div>
  )
}
```

A made-up café's orders through a day, by channel. Each lane swells where it's busy, and every lane uses the same scale, so the counter's morning rush and the evening's deliveries compare at a glance.

### Highlight and marker

```tsx
'use client'

import { useState } from 'react'
import { DensityLanes, Switch, type DensityLane } from '@youj/react'

const COLUMNS = Array.from({ length: 24 }, (_, h) => `${String(h).padStart(2, '0')}:00`)
const TICKS = [0, 6, 12, 18, 24].map((at) => ({ at, label: String(at).padStart(2, '0') }))

/** A made-up support desk's tickets by hour, by channel. */
const LANES: DensityLane[] = [
  { id: 'chat', label: 'Chat', values: [3, 2, 2, 1, 1, 2, 5, 11, 18, 22, 24, 23, 21, 22, 24, 22, 18, 13, 9, 7, 6, 5, 4, 3], tone: 'chart-1' },
  { id: 'email', label: 'Email', values: [6, 5, 4, 4, 3, 4, 6, 9, 13, 15, 14, 13, 12, 13, 14, 13, 12, 10, 9, 8, 8, 7, 7, 6], tone: 'chart-4' },
  { id: 'phone', label: 'Phone', values: [0, 0, 0, 0, 0, 0, 1, 4, 9, 12, 11, 9, 6, 9, 11, 10, 8, 4, 1, 0, 0, 0, 0, 0], tone: 'chart-5' },
]

export default function DensityLanesHighlight() {
  const [night, setNight] = useState(true)
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <label className="flex items-center gap-2 text-ui text-fg-muted">
        <Switch size="sm" checked={night} onCheckedChange={setNight} />
        Outside office hours
      </label>
      <DensityLanes
        lanes={LANES}
        columns={COLUMNS}
        ticks={TICKS}
        depth={3}
        highlight={
          night
            ? [
                [0, 7],
                [18, 23],
              ]
            : undefined
        }
        marker={{ column: 10, label: 'Busiest 10:00 · 49 tickets' }}
        formatValue={(v) => `${v} tickets`}
        label="Tickets by hour, by channel"
      />
    </div>
  )
}
```

`highlight` keeps column ranges in tone and quiets the rest (here the hours outside the office), and `marker` flags one column through every lane.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add density-lanes
```

It brings `tooltip`, `youj-core`, `youj-labels-density-lanes`, `youj-presets`, `youj-ui-core` with it.

Use density lanes for "when" across a few kinds of thing: alerts by hour per source, orders by half-hour per channel, commits by weekday per team. Each lane's shape tells when it's busy; the shares under the names tell how much of the whole it is. For one series of counts use a [Unit Chart](https://www.youj.dev/docs/components/unit-chart); for a year of days, a [Calendar Heatmap](https://www.youj.dev/docs/components/calendar-heatmap). The [Hour lanes](https://www.youj.dev/docs/blocks/trends-and-comparisons#hour-lanes) card is built on it.

```tsx
import { DensityLanes } from '@youj/react'

<DensityLanes
  label="Alerts by hour"
  columns={hours}
  lanes={[
    { id: 'identity', label: 'Identity', values: identityByHour, tone: 'chart-3' },
    { id: 'network', label: 'Network', values: networkByHour, tone: 'chart-2' },
  ]}
  highlight={[[0, 6], [19, 23]]}
  marker={{ column: 12, label: 'Peak 12:00 · 504 alerts' }}
/>
```

`columns` names each column (in its tooltip and spoken), and every lane gives one value per column. A column swells `depth` dots (4 by default) above and below the lane's spine at `max` (by default the largest value, one scale for every lane), and a column with nothing draws no dots, only the faint grid. `ticks` places labels at column edges (`at` 0 is the start of the first column), by default one at each quarter. Lanes take the chart colors in order unless they set a `tone`; `shares={false}` drops the shares under their names; `formatValue` writes values with their unit. No lanes, or nothing in them, shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lanes` (required) | `readonly DensityLane[]` |  |  |
| `columns` (required) | `readonly string[]` |  | Names each column, in its tooltip and spoken: "12:30". |
| `depth` | `number` | `4` | How many dots a column can swell above and below the spine. |
| `maxDot` | `number` | `16` | The largest a dot grows, in px from one dot to the next. Past it a wide plot stops growing taller and its columns spread apart. |
| `max` | `number` |  | The value at full swell, one scale for every lane. Default: the largest value. |
| `highlight` | `readonly (readonly [number, number])[]` |  | Column ranges, first and last index, kept in each lane's tone; the rest go quiet. |
| `marker` | `{ column: number; label: string }` |  | A dashed rule through every lane at one column, with a flag above it. |
| `ticks` | `readonly DensityLanesTick[]` |  | Labels under the plot at column edges. Default: a label at each quarter, from `columns`. |
| `shares` | `boolean` | `true` | Each lane's share of the total under its name. |
| `formatValue` | `(value: number) => string` |  | Formats values in the tooltip and the spoken text. Default: the locale's number format. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name of the chart. Default: the labels' "Density lanes". |
| `config` | `Readonly<Record<string, { color?: string }>>` |  | A ChartConfig shared with your other charts: a lane whose id is a key takes its color, so one series matches across chart types. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `density-lanes`, `density-lanes-grid`, `density-lanes-lane`, `density-lanes-label`, `density-lanes-plot`, `density-lanes-column`, `density-lanes-cells`, `density-lanes-cell`, `density-lanes-band`, `density-lanes-flag-row`, `density-lanes-flag`, `density-lanes-marker`, `density-lanes-axis`, `density-lanes-tick`, `density-lanes-tooltip`, `density-lanes-summary` and `density-lanes-empty`. A column in a highlight has `data-highlighted`. A lane's color is `--density-lanes-tone` on its plot, and an empty dot's is `--density-lanes-off`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the dots light column by column from the start when a third of the chart scrolls into view |
| Highlight | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | columns leaving or entering a highlight recolor between the tone and the quiet gray |

**Reduced motion:** Drawn in place; changes land at once.

#### Reduced motion

The dots are drawn in place, and a new highlight lands at once.

### Accessibility

- A named `grid` (your `label`, or the labels' "Density lanes") described by a summary: how many lanes, their total, and the busiest column with its value.
- A row per lane, its header the lane's name and share; every cell is named with its column and value, and says when it is in the highlight ("12:00: 504 alerts, highlighted").
- One tab stop. Left and Right walk the columns (mirrored in RTL), Up and Down the lanes, Home and End go to a lane's ends. Focus shows the cell's tooltip and marks its column through every lane, as hovering does.
- The dots, flag and axis are decorative; the cells say the same in words. Color is never the only cue: lanes are named, and a highlight is spoken.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Coverage Matrix

> Show how deep each row is covered by each column, with gaps hatched and a selectable row whose gaps turn red.

Source: https://www.youj.dev/docs/components/coverage-matrix

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CoverageMatrix, type CoverageMatrixColumn, type CoverageMatrixRow } from '@youj/react'

/** A made-up app's features against the platforms they ship on, filled by how complete each is (0–3). */
const COLUMNS: CoverageMatrixColumn[] = [
  { id: 'web', label: 'Web' },
  { id: 'ios', label: 'iOS' },
  { id: 'android', label: 'Android' },
  { id: 'desktop', label: 'Desktop' },
]
const ROWS: CoverageMatrixRow[] = [
  { id: 'sync', label: 'Offline sync', values: [3, 3, 2, 1] },
  { id: 'share', label: 'Sharing', values: [3, 2, 2, 0] },
  { id: 'search', label: 'Search', values: [3, 1, 1, 2] },
  { id: 'export', label: 'Export', values: [2, 0, 0, 3] },
  { id: 'widgets', label: 'Widgets', values: [0, 3, 2, 0] },
]

export default function CoverageMatrixDemo() {
  const [row, setRow] = useState('export')
  const picked = ROWS.find((r) => r.id === row)
  const gaps = picked ? COLUMNS.filter((_, c) => !picked.values[c]).map((col) => col.label) : []
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <CoverageMatrix
        rows={ROWS}
        columns={COLUMNS}
        max={3}
        value={row}
        onValueChange={setRow}
        formatValue={(v) => `${v} of 3`}
        noneLabel="Not started"
        label="Features by platform"
      />
      <p className="text-ui text-fg-muted">
        {gaps.length ? `${picked?.label} is missing on ${gaps.join(' and ')}.` : `${picked?.label} ships everywhere.`}
      </p>
    </div>
  )
}
```

A made-up app's features against the platforms they ship on. Each cell fills by how complete the feature is there, and a feature that hasn't started on a platform is hatched. Pick a row (click it, or Enter on one of its cells) and its gaps turn red; the line under it reacts to the pick.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add coverage-matrix
```

It brings `hatched-bar`, `tooltip`, `use-controllable-state`, `youj-core`, `youj-labels-coverage-matrix`, `youj-presets`, `youj-ui-core` with it.

Use a coverage matrix when the question is "where are the gaps": detection rules by tactic and source, features by platform, tests by module and browser, translations by page and language. A cell's fill is how deep the coverage goes, so thin spots read as well as empty ones. For who may do what, use a [Level Matrix](https://www.youj.dev/docs/components/level-matrix); for one value over a calendar, a [Calendar Heatmap](https://www.youj.dev/docs/components/calendar-heatmap). The [Coverage grid](https://www.youj.dev/docs/blocks/trends-and-comparisons#coverage-grid) card is built on it.

```tsx
import { CoverageMatrix } from '@youj/react'

<CoverageMatrix
  label="Detection coverage"
  columns={[
    { id: 'identity', label: 'Identity', tone: 'chart-3' },
    { id: 'network', label: 'Network', tone: 'chart-2' },
  ]}
  rows={[
    { id: 'access', label: 'Initial access', values: [4, 2] },
    { id: 'lateral', label: 'Lateral movement', values: [1, 0] },
  ]}
  defaultValue="lateral"
  formatValue={(n) => `${n} rules`}
  noneLabel="No rules"
/>
```

Each row gives one value per column, in the order of `columns`; 0 or `null` is no coverage and draws the hatch. A cell fills from the bottom by its value out of `max` (by default the largest value, one scale for every cell), never less than a sliver when it has any. Columns take the chart colors in order unless they set a `tone`. The selected row is `value`/`defaultValue`/`onValueChange`; in it the gaps take the danger tone, so it's the row your suggestion or action is about. `formatValue`, `noneLabel` and `depthLabel` word the cells and the key; `legend={false}` drops the key. No rows or columns shows the empty state.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `readonly CoverageMatrixRow[]` |  |  |
| `columns` (required) | `readonly CoverageMatrixColumn[]` |  |  |
| `max` | `number` |  | The value of a full cell. Default: the largest value. |
| `value` | `string \| null` |  | The selected row's id, controlled; `null` for none. |
| `defaultValue` | `string \| null` | `null` | The row selected at first. |
| `onValueChange` | `(id: string) => void` |  | Called with the row's id when a row is selected. |
| `formatValue` | `(value: number) => string` |  | Formats a covered cell's value in its tooltip and spoken name: "3 rules". Default: the locale's number format. |
| `noneLabel` | `string` |  | What a cell with nothing says, and the key's name for the hatch. Default: the labels' "None". |
| `depthLabel` | `string` |  | The key's name for a filled cell. Default: the labels' "Fill shows depth". |
| `legend` | `boolean` | `true` | The key under the grid. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name of the grid. Default: the labels' "Coverage matrix". |
| `config` | `Readonly<Record<string, { color?: string }>>` |  | A ChartConfig shared with your other charts: a column whose id is a key takes its color, so one series matches across chart types. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `coverage-matrix`, `coverage-matrix-grid`, `coverage-matrix-columns`, `coverage-matrix-row`, `coverage-matrix-label`, `coverage-matrix-cell`, `coverage-matrix-fill`, `coverage-matrix-legend`, `coverage-matrix-tooltip`, `coverage-matrix-summary` and `coverage-matrix-empty`. A row has `data-state="selected"` when it is chosen; a cell has `data-state` (`covered` or `none`). The cell size is `--coverage-matrix-cell` (32px).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the fills rise from the bottom of their cells, row after row, when a third of the grid scrolls into view |
| New values | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | a fill eases to its new depth |
| Selecting a row | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the row band and its gaps change color |

**Reduced motion:** Drawn in place; changes land at once.

#### Reduced motion

The fills are drawn in place, and new values land at once.

### Accessibility

- A named `grid` (your `label`, or the labels' "Coverage matrix") described by a summary of how many cells are covered, of how many.
- A row per row, its header the row's name, and the chosen one `aria-selected`. Every cell is named with its column and value ("Cloud: 3 rules", or `noneLabel`), so the decorative column names over the grid aren't needed to read it.
- One tab stop. The arrows move between the row names and the cells (mirrored in RTL), Home and End go to a row's name and its last cell, and Enter or Space selects the row. Focus shows the cell's tooltip, as hovering does.
- A gap is hatched and dashed as well as colored, and its value is spoken, so color is never the only cue.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Share Ring

> Show how a total divides into parts, with each amount and share beside the ring.

Source: https://www.youj.dev/docs/components/share-ring

## Examples

### Demo

```tsx
'use client'

import { ShareRing } from '@youj/react'

// A bowl's calories by where they come from: `value` sizes each part (kcal),
// `amount` is what the legend shows (grams).
const MACROS = [
  { id: 'protein', label: 'Protein', value: 152, amount: 38 },
  { id: 'carbs', label: 'Carbs', value: 256, amount: 64 },
  { id: 'fat', label: 'Fat', value: 198, amount: 22 },
]

export default function ShareRingDemo() {
  return (
    <div className="w-full max-w-xl rounded-2xl border border-line bg-surface p-6">
      <ShareRing size="lg" segments={MACROS} unit="kcal" amountFormat={{ style: 'unit', unit: 'gram', unitDisplay: 'short' }} />
    </div>
  )
}
```

A bowl's calories split into protein, carbs and fat, with the grams in the legend.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add share-ring
```

It brings `counter`, `youj-core`, `youj-labels-share-ring`, `youj-presets`, `youj-ui-core` with it.

Use a share ring when the question is what a whole is made of and the parts are few: a dish's calories by protein, carbs and fat, a month's spending by category, a day's hours by activity. The cells run clockwise from twelve o'clock, each lit in the tone of the part it falls in, so the split reads at a glance and the cells can be counted. The total sits in the bowl in big mono figures that count to each new value, with its unit under it, and the legend gives each part its amount and its share. For many parts, or parts inside parts, use a [Treemap](https://www.youj.dev/docs/components/treemap); for one quantity against a limit, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter).

```tsx
import { ShareRing } from '@youj/react'

<ShareRing
  unit="kcal"
  // `value` sizes each part; `amount` is what the legend shows for it.
  segments={[
    { id: 'protein', label: 'Protein', value: 152, amount: 38 },
    { id: 'carbs', label: 'Carbs', value: 256, amount: 64 },
    { id: 'fat', label: 'Fat', value: 198, amount: 22 },
  ]}
  amountFormat={{ style: 'unit', unit: 'gram', unitDisplay: 'short' }}
/>
```

Each part takes whole cells by the largest remainder, so the parts always fill exactly the cells they're due and the shares in the legend always add up to 100%. `value` sizes a part on the ring and `amount` is what its row shows, so a macro can take its share of the calories while the legend lists its grams. Parts take the chart colors in turn, or a `tone` of their own.

`max` sets the ring's full scale: above the total, the rest of the ring stays dark (606 kcal of a 2,000 kcal day). `value` puts a different figure in the bowl, `format` formats it, and `children` replaces the bowl altogether. Pointing at a part, on the dial or in the legend, dims the others and puts its amount and share in the bowl; `highlight` does the same from your own state.

The legend sits beside the dial when the ring has the room and under it when it hasn't (`legend="side"`, the default), always under it with `legend="below"`, or not at all with `legend={false}`, when the parts are still spoken. At `size="xs"` the ring is 28px across, with no bowl and no legend: small enough to sit in a pill, as the timers in the [Procedure](https://www.youj.dev/docs/blocks/forms-and-inputs) block do.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` (required) | `readonly ShareRingSegment[]` |  |  |
| `max` | `number` |  | The ring's full scale. Default: the segments' total, so the ring is full; above it, the rest stays dark. |
| `value` | `number` |  | The figure in the bowl. Default: the segments' total. |
| `unit` | `string` |  | A word under the figure: "kcal". |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the figure in the bowl. Default: whole numbers. |
| `amountFormat` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for each part's amount in the legend, such as `{ style: 'unit', unit: 'gram' }`. Default: whole numbers. |
| `size` | `Extract<Size, 'xs' \| 'sm' \| 'default' \| 'lg'>` | `'default'` | The ring's size: `xs`, `sm`, `default` or `lg`. |
| `cells` | `number` |  | How many cells round the dial. Default 60 (48 at `sm`, 12 at `xs`). |
| `legend` | `'side' \| 'below' \| false` | `'side'` | Where the legend sits: `side` puts it beside the dial when the ring has room and under it when not, `below` always under. |
| `highlight` | `string \| null` |  | A part to single out (controlled). Default: whichever part the pointer is on. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `children` | `ReactNode` |  | Content for the bowl instead of the figure and unit. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `share-ring` (with `data-size` and `data-legend`), `share-ring-dial`, `share-ring-rule`, `share-ring-cell` (with `data-state` and `data-segment`), `share-ring-center`, `share-ring-value`, `share-ring-focus-value`, `share-ring-unit`, `share-ring-legend`, `share-ring-item` (with `data-highlighted`), `share-ring-swatch`, `share-ring-label`, `share-ring-amount` and `share-ring-share`. In Bezel the labels and the unit are mono capital eyebrows and every figure is mono.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the cells light one after another round the dial |
| New values | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | cells recolor in place and the total counts to its new value |
| Pointing at a part | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the others dim and the bowl cross-fades to the part |

**Reduced motion:** The ring is drawn lit and the total jumps to each new value.

#### Reduced motion

The cells are drawn lit from the first frame, and the total and the bowl change in place.

### Accessibility

- The dial is an image named by its total and each part's share, in order ("606 kcal: Protein 25%, Carbs 42%, and Fat 33%"), or by the total and "No data" when every part is zero.
- The legend is a list of plain text rows, so each part's amount and share are read as they're shown.
- Its words come from the labels (`shareRingPart`, `shareRingSummary`, `noData`), translated by the language packs.
- A dial turns clockwise in every script, so the ring keeps its direction under RTL; the bowl and the legend follow the page.

---

# Activity Rings

> Show a few goals side by side as concentric rings, each filling toward its own target.

Source: https://www.youj.dev/docs/components/activity-rings

## Examples

### Demo

```tsx
'use client'

import { ArrowRightIcon, ArrowUpIcon, ZapIcon } from '@youj/icons'
import { ActivityRings, type ActivityRing } from '@youj/react'

// A day's three goals, outermost first. Each ring is its own goal: `value` of `max`.
const DAY: ActivityRing[] = [
  { label: 'Move', value: 420, max: 500, unit: 'calories', tone: 'danger', icon: <ArrowRightIcon /> },
  { label: 'Exercise', value: 26, max: 30, unit: 'minutes', tone: 'success', icon: <ZapIcon /> },
  { label: 'Stand', value: 9, max: 12, unit: 'hours', tone: 'info', icon: <ArrowUpIcon /> },
]

export default function ActivityRingsDemo() {
  return (
    <div className="w-full max-w-xl rounded-2xl border border-line bg-surface p-6">
      <ActivityRings rings={DAY} size="lg" legend="side" />
    </div>
  )
}
```

A day's move, exercise and stand goals, with each ring's glyph at its start and the legend beside.

### Team quotas

```tsx
'use client'

import { PhoneIcon, TargetIcon, UsersIcon } from '@youj/icons'
import { ActivityRings, type ActivityRing } from '@youj/react'

// Two quotas past their goal: those rings run a second lap over the first.
const QUARTER: ActivityRing[] = [
  { label: 'New revenue', value: 1_380_000, max: 1_000_000, unit: 'USD', tone: 'accent', icon: <TargetIcon /> },
  { label: 'Meetings booked', value: 162, max: 120, tone: 'chart-2', icon: <UsersIcon /> },
  { label: 'Calls', value: 1_740, max: 2_000, tone: 'chart-3', icon: <PhoneIcon /> },
]

export default function ActivityRingsQuotas() {
  return (
    <div className="w-80 rounded-2xl border border-line bg-surface p-6">
      <ActivityRings rings={QUARTER} size="xl" legend="below" format={{ notation: 'compact', maximumFractionDigits: 1 }} />
    </div>
  )
}
```

A sales team's quarter. Two quotas are past their goal, so those rings run a second lap over the first, and the head of each casts a small shadow onto the lap beneath it.

### Live update

```tsx
'use client'

import { useState } from 'react'
import { BriefcaseIcon, TimerIcon } from '@youj/icons'
import { ActivityRings, Button, type ActivityRing } from '@youj/react'

const START: ActivityRing[] = [
  { label: 'Focus', value: 70, max: 120, unit: 'minutes', tone: 'accent', icon: <TimerIcon /> },
  { label: 'Deep work', value: 1, max: 3, unit: 'blocks', tone: 'chart-2', icon: <BriefcaseIcon /> },
]

export default function ActivityRingsLive() {
  const [rings, setRings] = useState(START)
  // New values retarget from where each ring is; crossing a goal glows once.
  const log = () => setRings((rs) => rs.map((r) => ({ ...r, value: r.value >= r.max * 1.4 ? 0 : r.value + r.max / 6 })))

return (
    <div className="flex w-full max-w-md flex-col items-center gap-5 rounded-2xl border border-line bg-surface p-6">
      <ActivityRings rings={rings} legend="below" format={{ maximumFractionDigits: 0 }} />
      <Button variant="outline" size="sm" onClick={log}>
        Log progress
      </Button>
    </div>
  )
}
```

Each new value fills from where the ring already is. A ring that reaches its goal glows once.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add activity-rings
```

It brings `youj-core`, `youj-labels-activity-rings`, `youj-presets`, `youj-ui-core` with it.

Use activity rings when a few goals are tracked together and each has its own target: a day's fitness goals, a team's quotas, a quarter's key results, a learning streak. Each ring is one goal, a round-capped arc over a faint track of its color, running clockwise from twelve o'clock. Two to four rings fit. To show how one whole splits into parts, use a [Share Ring](https://www.youj.dev/docs/components/share-ring). For a single score on a scale, use a [Gauge](https://www.youj.dev/docs/components/gauge).

```tsx
import { ActivityRings, type ActivityRing } from '@youj/react'

const rings: ActivityRing[] = [
  { label: 'Move', value: 420, max: 500, unit: 'calories', tone: 'danger' },
  { label: 'Exercise', value: 26, max: 30, unit: 'minutes', tone: 'success' },
  { label: 'Stand', value: 9, max: 12, unit: 'hours', tone: 'info' },
]

<ActivityRings rings={rings} legend="side" />
```

A ring is `value` of `max`, with a `label`, an optional `unit` after its goal, a `tone` (accent, a chart color or a status; the chart colors in turn by default) and an `icon` drawn at its start. Rings are listed outermost first. Past its goal a ring keeps going for a second lap (it draws up to two), and the legend and the spoken value give the full share, such as 138%.

The bowl shows the first ring's share in big figures with its name, or the share of the ring being pointed at. Pass `children` to put your own content there, such as a streak or a total. At `size="sm"` (96px) the bowl is left empty. The other sizes are `default`, `lg` and `xl`.

`legend="side"` puts the legend beside the rings when there's room and under them when there isn't. `legend="below"` always puts it under them. Each row gives the ring's value, goal and share. Pointing at a row, or tabbing to it, singles out its ring, and pointing at a ring singles out its row. `format` formats the values (whole numbers by default, `{ notation: 'compact' }` for large figures).

The rings fill as they come into view. `inView={false}` fills them on mount, and `{ once, amount, margin }` sets what counts as in view. A ring that closes plays the success cue when the provider has sound on, and `sound={false}` turns that off.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rings` (required) | `readonly ActivityRing[]` |  | Two to four goals, outermost first. |
| `size` | `Extract<Size, 'sm' \| 'default' \| 'lg' \| 'xl'>` | `'default'` | The rings' size: `sm`, `default`, `lg` or `xl`. |
| `legend` | `'side' \| 'below' \| false` | `false` | Where the legend sits: `side` puts it beside the rings when there's room and under them when not, `below` always under. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the values. Default: whole numbers. |
| `inView` | `InView` |  | When the rings fill: `false` on mount; `true` (the default) or `{ once, amount, margin }` as they come into view. |
| `sound` | `boolean` | `true` | Play the success cue when a ring closes. |
| `label` | `string` | `"Activity rings"` | Names the rings for assistive tech. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `children` | `ReactNode` |  | Content for the bowl instead of the figure. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `activity-rings` (with `data-size` and `data-yj-legend`), `activity-rings-dial`, `activity-rings-ring` (with `data-index`, `data-tone`, `data-closed` once it reaches its goal and `data-yj-over` past it), `activity-rings-track`, `activity-rings-arc`, `activity-rings-overlap` (the second lap), `activity-rings-head`, `activity-rings-glow`, `activity-rings-icon`, `activity-rings-center`, `activity-rings-value`, `activity-rings-caption`, `activity-rings-legend`, `activity-rings-item` (with `data-highlighted` and `data-closed`), `activity-rings-swatch`, `activity-rings-label`, `activity-rings-amount` and `activity-rings-share`. In Bezel the labels are mono capital eyebrows.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `spring.smooth` | 0.36s, bounce 0 | each ring fills from zero to its value |
| New values | `spring.smooth` | 0.36s, bounce 0 | each ring retargets from where it is, keeping its speed |
| Closing a ring | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | a soft glow swells off the ring and fades, once |
| Pointing at a ring | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the other rings and rows dim |

**Reduced motion:** The rings are drawn at their values and change in place, with no glow.

#### Reduced motion

The rings are drawn at their values from the first frame, new values jump, and closing a ring doesn't glow or play a cue.

### Accessibility

- The rings are a group, named by `label` or "Activity rings", and each ring is a `meter` named by its label, with its value text spoken in full: "Move: 420 of 500 calories, 84%". Past its goal, `aria-valuenow` holds at the goal and the text gives the real value and share.
- The legend is a list. Each row takes focus, so the keyboard can single out a ring the same way the pointer does.
- Its words come from the labels (`activityRings`, `activityRingsValue`), translated by the language packs.
- A dial turns clockwise in every script, so the rings keep their direction under RTL. The bowl and the legend follow the page.

---

# Dot Map

> Show where activity happens on a world map made of dots.

Source: https://www.youj.dev/docs/components/dot-map

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { DotMap, type DotMapRegion } from '@youj/react'

const REGIONS: DotMapRegion[] = [
  { id: 'iad', name: 'iad', lon: -77.04, lat: 38.9, value: 12_400 },
  { id: 'fra', name: 'fra', lon: 8.68, lat: 50.11, value: 9_800 },
  { id: 'sfo', name: 'sfo', lon: -122.42, lat: 37.77, value: 8_900 },
  { id: 'nrt', name: 'nrt', lon: 139.69, lat: 35.68, value: 6_100 },
  { id: 'sin', name: 'sin', lon: 103.82, lat: 1.35, value: 4_300 },
  { id: 'gru', name: 'gru', lon: -46.63, lat: -23.55, value: 2_700, tone: 'warning' },
  { id: 'syd', name: 'syd', lon: 151.21, lat: -33.87, value: 1_900 },
]
const compact = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 })

export default function DotMapDemo() {
  const [active, setActive] = useState<string | null>(null)
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <DotMap regions={REGIONS} active={active} onActiveChange={setActive} label="Requests by region" formatValue={(v) => `${compact.format(v)} rps`} />
      {/* The list holds the figures; the map follows it. */}
      <ul className="grid grid-cols-2 gap-1 sm:grid-cols-4">
        {REGIONS.map((r) => (
          <li key={r.id}>
            <button
              type="button"
              onFocus={() => setActive(r.id)}
              onBlur={() => setActive(null)}
              onPointerEnter={() => setActive(r.id)}
              onPointerLeave={() => setActive(null)}
              data-on={active === r.id}
              className="flex w-full items-baseline justify-between gap-2 rounded-md px-2 py-1.5 font-mono text-ui outline-none focus-visible:ring-2 focus-visible:ring-focus data-[on=true]:bg-hover"
            >
              {r.name}
              <span className="text-fg-muted tabular-nums">{compact.format(r.value)}</span>
            </button>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

Requests by region as dots on a world map, with a region list that lights the same region.

`active` highlights one region: it brightens, the others dim, and a crosshair runs through it with its name and value on an ink tag. Hovering the map reports the nearest region through `onActiveChange`, so a list beside it can light the same row; setting `active` from the list's hover and focus moves the crosshair, which glides from one region to the next.

```tsx
import { useState } from 'react'
const [active, setActive] = useState<string | null>(null)

<DotMap regions={regions} active={active} onActiveChange={setActive} />
<RegionList regions={regions} active={active} onHover={setActive} />
```

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dot-map
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-dot-map`, `youj-presets`, `youj-ui-core` with it.

Use a dot map when the question is "where": requests by point of presence, customers by city, incidents by region. Each region lights the land dots around it like LEDs, the reach and strength growing with its share of the largest value, under a soft halo in its tone. Pair it with a list or table that holds the figures: the map shows where, the list says how much.

```tsx
import { DotMap } from '@youj/react'

<DotMap
  label="Requests by region"
  regions={[
    { id: 'iad', name: 'iad', lon: -77.04, lat: 38.9, value: 12_400 },
    { id: 'fra', name: 'fra', lon: 8.68, lat: 50.11, value: 9_800 },
    { id: 'gru', name: 'gru', lon: -46.63, lat: -23.55, value: 2_700, tone: 'warning' },
  ]}
/>
```

Regions take a longitude and latitude in degrees and a `value`; a region's `tone` colors its dots and halo (the accent by default, a status or a chart color). The land is a committed equirectangular grid of 3° cells from 78°N to 57°S, derived once from Natural Earth's public-domain land polygons, so nothing geographic loads at runtime and the map stays west to east in any text direction.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `regions` | `readonly DotMapRegion[]` | `[]` |  |
| `active` | `string \| null` |  | The highlighted region's id; `null` for none. Set it to follow a list beside the map. |
| `defaultActive` | `string \| null` | `null` |  |
| `onActiveChange` | `(id: string \| null) => void` |  | Hovering or tapping a region on the map, and leaving it. |
| `formatValue` | `(value: number) => string` |  | Formats values on the tag and in the summary. Default: the locale's compact number format. |
| `label` | `string` |  | Accessible name of the map. Default: the labels' "World map". |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | a scan sweeps the grid in from the west; each region lights as the scan reaches it, outward from its center |
| Update | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | each region whose value changed sends one ring that opens and fades, and its dots brighten or dim outward |
| Highlight | `spring.smooth` | 0.36s, bounce 0 | the crosshair and tag glide to the region |

**Reduced motion:** Drawn in place: no scan, no pulses; changes land at once.

#### Reduced motion

The map is drawn in place without the scan or pulses, and new values land at once.

### Accessibility

- The map is a labeled image (your `label`, or the labels' "World map") described by a summary: how many regions it marks and the largest. The drawing itself is hidden from assistive technology.
- It isn't keyboard-operable on purpose: the list or table beside it is the source of truth, and focusing a row there moves the map's highlight.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Lane Meter

> Compare workloads across queues or pipeline stages on a shared grid.

Source: https://www.youj.dev/docs/components/lane-meter

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, LaneMeter, type Lane, type LaneItem } from '@youj/react'

const FAILED: LaneItem[] = [
  { id: 'job-8f2a1c', label: 'job-8f2a1c', detail: 'Timeout after 30 s' },
  { id: 'job-41be07', label: 'job-41be07', detail: 'SMTP 421: try again later' },
  { id: 'job-c93d58', label: 'job-c93d58', detail: 'Timeout after 30 s' },
  { id: 'job-0a7f12', label: 'job-0a7f12', detail: 'Rate limited by provider' },
  { id: 'job-5e61b9', label: 'job-5e61b9', detail: 'Template not found' },
]

export default function LaneMeterDemo() {
  const [failed, setFailed] = useState(FAILED)
  const [queued, setQueued] = useState(214)
  const retry = (items: LaneItem[]) => {
    const ids = new Set(items.map((i) => i.id))
    setFailed((list) => list.filter((i) => !ids.has(i.id)))
    setQueued((q) => q + items.length)
  }
  const lanes: Lane[] = [
    { id: 'queued', label: 'Queued', value: queued, max: 500 },
    { id: 'running', label: 'Running', value: 24, max: 32, tone: 'accent', active: true },
    {
      id: 'failed',
      label: 'Failed',
      value: failed.length,
      tone: 'danger',
      items: failed,
      action: (
        <Button size="xs" variant="secondary" disabled={failed.length === 0} onClick={() => retry(failed)}>
          Retry all
        </Button>
      ),
    },
    { id: 'done', label: 'Done', value: 12480, max: 16000, tone: 'success' },
  ]
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <LaneMeter lanes={lanes} format={{ notation: 'compact', maximumFractionDigits: 1 }} onItemAction={(item) => retry([item])} />
      <Button
        size="sm"
        variant="outline"
        className="self-start"
        onClick={() => {
          setFailed(FAILED)
          setQueued(214)
        }}
      >
        Reset
      </Button>
    </div>
  )
}
```

Queued, running and failed job lanes, where the failed lane lists its jobs and can retry them.

A lane with `items` lights one cell per item, such as a failed job. With `onItemAction`, each item is a button with a tooltip (its `label` and `detail`), named by the action and the item ("Retry job-8f2a1c"; set the verb with `itemActionLabel`). The lane is one tab stop: arrow keys move between items, Home and End go to the first and last. When an item leaves, it shrinks out, the rest glide over, and focus moves to its neighbor.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add lane-meter
```

It brings `tooltip`, `youj-core`, `youj-labels-lane-meter`, `youj-presets`, `youj-ui-core` with it.

Use a lane meter where a workload moves through states and people compare them at a glance: queued, running, failed and done jobs; builds by stage; requests by region. Every lane has as many cells as the others, so the rows form one ruled grid. A lane with its own capacity (worker slots, a queue's size) fills against it and shows it muted beside the value ("24 / 32"); the other lanes share one scale. For one resource on its own, use a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter); for a share of a whole in a table row, use a [Share Bar](https://www.youj.dev/docs/components/share-bar).

```tsx
import { Button, LaneMeter } from '@youj/react'

<LaneMeter
  lanes={[
    { id: 'queued', label: 'Queued', value: 214, max: 500 },
    { id: 'running', label: 'Running', value: 24, max: 32, tone: 'accent', active: true },
    { id: 'failed', label: 'Failed', value: failed.length, tone: 'danger', items: failed, action: <Button size="xs" variant="secondary">Retry all</Button> },
    { id: 'done', label: 'Done', value: 12480, max: 16000, tone: 'success' },
  ]}
  format={{ notation: 'compact', maximumFractionDigits: 1 }}
  onItemAction={(item) => retry(item)}
/>
```

Each lane takes a `label`, a `value` and, optionally, its own `max`, a `tone` (a status, the accent, a chart color or `neutral`, the ink), `active` for work in progress and an `action` for its end. `segments` sets the cells per lane (default 32) and `format` takes `Intl.NumberFormat` options for the values.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lanes` (required) | `readonly Lane[]` |  |  |
| `max` | `number` |  | The scale shared by lanes without their own `max`. Default: the largest of their values. |
| `segments` | `number` | `32` | Cells per lane. |
| `onItemAction` | `(item: LaneItem, lane: Lane) => void` |  | Makes each item cell a button that calls this. |
| `itemActionLabel` | `string` |  | The items' action, spoken with each ("Retry job-8f2a"). Default: the labels' "Retry". |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the values. Default: plain counts. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | The meter's accessible name. Default: the labels' "Queue load". |
| `sound` | `boolean` | `true` | With sound on, an item action plays `tap`. `false` keeps it silent. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `lane-meter`, `lane-meter-lanes`, `lane-meter-lane`, `lane-meter-meter`, `lane-meter-label`, `lane-meter-value`, `lane-meter-max`, `lane-meter-track`, `lane-meter-cell` (with `data-state` `on` or `off`), `lane-meter-item`, `lane-meter-glint`, `lane-meter-action` and `lane-meter-tooltip`. Each lane has `data-tone` and, when active, `data-active`. The labels take the theme's label voice (mono capitals in Basalt). Under 30rem of width, each lane stacks its label and value over the cells.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fill | `duration.deliberate` | 560ms | when the meter scrolls into view, each lane lights its cells one after another at a constant rate, a stagger step after the lane above |
| New value | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | lights or darkens the cells between the edge on screen and the new one, in order |
| Active lane | `duration.deliberate` | 560ms | a soft light crosses its lit cells and rests, only while the meter is on screen |
| Item leaves | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | shrinks and fades out while the others glide to their new cells |

**Reduced motion:** Cells are lit in place, the active lane has no traveling light, and items change at once.

#### Reduced motion

Every cell is lit at once, the active lane's light is off, and items appear and leave without animation.

### Accessibility

- The meter is a `group` named by `label` (default "Queue load"). Each lane is a `meter` named by its visible label; a lane with its own `max` is spoken "24 of 32".
- Item buttons sit in a group named by their lane. The lane is one tab stop; arrow keys follow the reading direction.
- The cells are hidden from assistive tech; they fill from the inline start, so right to left in RTL.

---

# Day Ring

> Show scheduled runs on a daily dial, with overlaps and the next run highlighted, such as a job schedule.

Source: https://www.youj.dev/docs/components/day-ring

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, DayRing, findOverlaps, type ScheduleJob } from '@youj/react'

const JOBS: ScheduleJob[] = [
  { id: 'backup', name: 'backup-db', runs: [120], duration: 40, tone: 'chart-1' },
  { id: 'reindex', name: 'reindex-search', runs: [150], duration: 25, tone: 'chart-2' },
  { id: 'sync', name: 'sync-crm', runs: [15, 255, 495, 735, 975, 1215], duration: 10, tone: 'chart-3' },
  { id: 'digest', name: 'send-digest', runs: [540], duration: 5, tone: 'chart-4' },
  { id: 'billing', name: 'billing-export', runs: [1210], duration: 15, tone: 'chart-5' },
]

export default function DayRingDemo() {
  const [highlight, setHighlight] = useState<string>()
  const overlaps = findOverlaps(JOBS)
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-5">
      <DayRing jobs={JOBS} timeZone="UTC" highlight={highlight} className="w-72" />
      <div className="flex flex-wrap justify-center gap-1.5">
        {JOBS.map((job) => (
          <Button key={job.id} size="sm" variant={highlight === job.id ? 'secondary' : 'outline'} onClick={() => setHighlight((h) => (h === job.id ? undefined : job.id))}>
            {job.name}
          </Button>
        ))}
      </div>
      <p className="font-mono text-ui-sm text-fg-muted">{overlaps.length} overlaps today</p>
    </div>
  )
}
```

Five scheduled jobs on a 24-hour ring in UTC, where you can highlight one job and see how many runs overlap.

Runs collide when runs of two or more jobs share any minute; runs that only touch (one ends as the next starts) don't. A run without a duration counts as one minute, and a collision across midnight is one collision. `findOverlaps(jobs)` returns them (`start`, `end` in minutes, which passes 1440 across midnight, and the `jobs` involved), so your list can say who collides and when.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add day-ring
```

It brings `use-now`, `youj-core`, `youj-labels-day-ring`, `youj-presets`, `youj-ui-core` with it.

Use a day ring where people plan recurring work around the clock: cron jobs, backups, report exports, maintenance windows. Each job gets its own track, so a day of runs reads at a glance, and where runs of different jobs collide a warning zone brackets them and a marker points at it from outside the ruler. For a timeline of what already happened, use a [Timeline](https://www.youj.dev/docs/components/timeline); for one bounded value, a [Gauge](https://www.youj.dev/docs/components/gauge).

```tsx
import { DayRing, findOverlaps } from '@youj/react'

const jobs = [
  { id: 'backup', name: 'backup-db', runs: [120], duration: 40 },
  { id: 'reindex', name: 'reindex-search', runs: [150], duration: 25 },
  { id: 'sync', name: 'sync-crm', runs: [15, 255, 495, 735, 975, 1215], duration: 10 },
]

<DayRing jobs={jobs} timeZone="UTC" />
findOverlaps(jobs) // [{ start: 150, end: 160, jobs: ['backup', 'reindex'] }]
```

`runs` are the starts today, in minutes after midnight, in `timeZone` (default: the browser's). A job with a `duration` draws its runs as arcs as long as they take; without one, as ticks. `tone` picks the job's color (the chart colors in turn by default), and `paused` draws it dim and dashed and leaves it out of every collision. `highlight` keeps one job lit, dims the rest and counts down to its next run: point it at the row a person is hovering in your own list. `now` pins the clock (tests, screenshots); by default it's live, and on the server there's no hand or countdown until the browser has the time.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `jobs` (required) | `readonly ScheduleJob[]` |  |  |
| `now` | `Date \| number` |  | The time the hand shows. Default: the live clock. |
| `timeZone` | `string` |  | The time zone the runs are in. Default: the browser's. |
| `highlight` | `string` |  | A job id: its runs stay lit, the others dim, and the center counts down to its next run. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Daily schedule". |
| `nextLabel` | `string` |  | The center's caption over the countdown. Default: the labels' "Next run". |
| `formatTime` | `(minute: number) => string` |  | Formats a minute of the day. Default: the locale's 24-hour HH:mm. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `day-ring`, `day-ring-svg`, `day-ring-ruler`, `day-ring-elapsed`, `day-ring-hour`, `day-ring-track`, `day-ring-overlap` (with `data-jobs`), `day-ring-runs` (a job's group, with `data-job`, `data-tone`, `data-paused`, `data-highlighted` and `data-dimmed`), `day-ring-run` (with `data-minute`), `day-ring-hand`, `day-ring-center`, `day-ring-label`, `day-ring-next`, `day-ring-value` and `day-ring-description`. It fills its box's width up to 20rem; the center's type scales with it.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate` | 560ms | the runs appear as a radar pass: each fades in a step later the further round the day it sits |
| Hand | `spring.smooth` | 0.36s, bounce 0 | turns from midnight to now on the smooth spring, with the elapsed shading on the same spring; then it steps each minute |
| A run moves | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | it glides round its track to the new time |
| Highlight | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the other jobs fade down |
| Collisions | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | zones fade in and out as runs move or jobs pause |

**Reduced motion:** Drawn in place; a run that moves jumps. The countdown still ticks.

#### Reduced motion

Every run and the hand are drawn in place, with no radar pass; runs that move jump. The countdown keeps ticking: it's information, not motion.

### Accessibility

- The ring is an image (`role="img"`) named by `label` (default: the labels' "Daily schedule") and described in words: how many runs a day, how many collisions, the next run, and one sentence per collision ("backup-db and reindex-search overlap at 02:30").
- The countdown isn't live, so it doesn't talk every second; announce a start yourself if the page needs it.
- A dial turns clockwise in every script, so the ring keeps its direction under RTL; the text in the center follows the page.
- Its words come from the labels (`dayRing`, `nextRun`, `runsIn`, `scheduleRunAt`, `scheduleRuns`, `scheduleOverlaps`, `scheduleOverlapAt`), translated by the language packs.

---

# Distribution Strip

> Show a distribution as dots on a log scale, with percentile marks and a target, such as request latency.

Source: https://www.youj.dev/docs/components/distribution-strip

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { DistributionStrip, SegmentedControl, SegmentedControlItem } from '@youj/react'

/** Latencies in ms around `median`, log-normal with a slow tail, from a fixed seed so the page draws the same requests every time. */
function sampleLatencies(count: number, median: number, seed: number) {
  let t = seed
  const random = () => {
    t = (t + 0x6d2b79f5) | 0
    let r = Math.imul(t ^ (t >>> 15), 1 | t)
    r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r
    return ((r ^ (r >>> 14)) >>> 0) / 4294967296
  }
  const normal = () => Math.sqrt(-2 * Math.log(1 - random())) * Math.cos(2 * Math.PI * random())
  return Array.from({ length: count }, () => {
    const slow = random() < 0.05
    return Math.exp(Math.log(slow ? median * 4.5 : median) + normal() * (slow ? 0.55 : 0.42))
  })
}

const WINDOWS = {
  before: sampleLatencies(320, 82, 7),
  after: sampleLatencies(320, 118, 11),
}

export default function DistributionStripDemo() {
  const [window, setWindow] = useState<keyof typeof WINDOWS>('before')
  return (
    <div className="flex w-full max-w-2xl flex-col gap-5">
      <SegmentedControl aria-label="Window" value={window} onValueChange={(value) => setWindow(value as keyof typeof WINDOWS)} className="self-start">
        <SegmentedControlItem value="before">Before the deploy</SegmentedControlItem>
        <SegmentedControlItem value="after">After the deploy</SegmentedControlItem>
      </SegmentedControl>
      {/* Switching morphs the swarm: each quantile slides to where it now falls. */}
      <DistributionStrip samples={WINDOWS[window]} slo={300} label="checkout-api" />
    </div>
  )
}
```

Request latencies before and after a deploy, as a swarm of dots with percentile flags, which you can switch between.

### Percentiles and the objective

```tsx
'use client'

import { DistributionStrip } from '@youj/react'

/** Search latencies in ms: a fast body and a long tail of cold queries, from a fixed seed. */
function sampleLatencies(count: number, seed: number) {
  let t = seed
  const random = () => {
    t = (t + 0x6d2b79f5) | 0
    let r = Math.imul(t ^ (t >>> 15), 1 | t)
    r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r
    return ((r ^ (r >>> 14)) >>> 0) / 4294967296
  }
  const normal = () => Math.sqrt(-2 * Math.log(1 - random())) * Math.cos(2 * Math.PI * random())
  return Array.from({ length: count }, () => {
    const cold = random() < 0.08
    return Math.exp(Math.log(cold ? 260 : 24) + normal() * (cold ? 0.6 : 0.5))
  })
}

const SEARCH = sampleLatencies(360, 5)

export default function DistributionStripPercentiles() {
  // No objective: the dots stay in the neutral ink and the header has no share.
  return <DistributionStrip samples={SEARCH} percentiles={[75, 95, 99.9]} label="search-api · p75, p95, p99.9" className="w-full max-w-2xl" />
}
```

Search latencies with the p75, p95 and p99.9 flags and no objective.

`percentiles` takes any percentiles, 0 to 100, and draws the highest in the strongest ink (in the warning ink once it's past the objective). Flags that would collide spread apart and stay inside the strip. Without `slo` there's no hatch and no share, and the dots stay in the neutral ink.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add distribution-strip
```

It brings `counter`, `hatched-bar`, `use-resize-measure`, `youj-core`, `youj-labels-distribution-strip`, `youj-presets`, `youj-ui-core` with it.

Use a distribution strip where the question is "how slow is it, really": a service's or a route's latency, a job's run time. Every sampled request is a dot on a log-scaled strip, stacked into rows where they crowd, so the swarm is fattest where most requests land and the tail stays visible dot by dot. The percentiles (p50, p90 and p99 by default) are flagged hairlines, and the objective is a dashed line: past it the strip is hatched and its dots turn to the warning tone. For one latency against a limit, use a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter); for a trend over time, a [Chart](https://www.youj.dev/docs/components/chart).

```tsx
import { DistributionStrip } from '@youj/react'

// Latencies in milliseconds, one per sampled request.
<DistributionStrip samples={latencies} slo={300} label="checkout-api · last 24h" />
```

The axis runs over the whole decades around the samples (10 ms to 1 s for samples between 22 and 990 ms), with a tick for every step of each decade; pass `domain` for other ends. Latencies read in milliseconds, and in seconds from 1 s, in the provider's locale; pass `format` for your own. The header counts the share of samples within `slo`.

`percentileOf(samples, p)` gives the same interpolated percentile the strip flags, for a headline figure beside it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `samples` (required) | `readonly number[]` |  | Sampled request latencies, in milliseconds. |
| `slo` | `number` |  | The latency objective, in milliseconds: a dashed line, the strip past it hatched, and the share of samples within it in the header. |
| `percentiles` | `readonly number[]` | `DEFAULT_PERCENTILES` | The percentiles to mark, 0–100. |
| `domain` | `readonly [number, number]` |  | The axis's ends, in milliseconds. Default: the whole decades around the samples. |
| `rows` | `number` | `11` | How many rows the dots stack into where they crowd; an even number gets one more, so the swarm has a middle. |
| `format` | `(ms: number) => string` |  | Formats a latency for the flags, the ruler, the objective and the summary. Default: milliseconds, and seconds from 1 s, in the locale. |
| `label` | `string` |  | The visible name over the strip, which also names the figure. Default: the labels' "Latency distribution". |

Also takes the props of `ComponentProps<'figure'>`.

### Styling

Parts: `distribution-strip`, `distribution-strip-header`, `distribution-strip-label`, `distribution-strip-within`, `distribution-strip-within-label`, `distribution-strip-value`, `distribution-strip-empty`, `distribution-strip-chart`, `distribution-strip-plot`, `distribution-strip-over`, `distribution-strip-dot`, `distribution-strip-slo`, `distribution-strip-slo-flag`, `distribution-strip-marker`, `distribution-strip-line`, `distribution-strip-flag`, `distribution-strip-axis`, `distribution-strip-tick`, `distribution-strip-tick-label` and `distribution-strip-summary`. A dot past the objective has `data-over`, a marker its `data-percentile`, and a decade tick `data-major`. The labels take the theme's label voice (mono capitals in Basalt).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the dots rise from under the baseline and fade in when two fifths of the strip scroll into view |
| Wave |  | the base token, spread from start to end | each dot waits for its place along the axis, so the rise sweeps from the start |
| Markers | `spring.smooth` | 0.36s, bounce 0 | the percentile hairlines and their flags glide in from the inline start, and retarget from where they are |
| New samples | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the dots are matched by rank, so each quantile slides to where it now falls, in the same wave |
| Share within the objective | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | counts to its new value |
| Flags | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | shift apart as their lines close in |

**Reduced motion:** Drawn in place; new samples land at once.

#### Reduced motion

The dots and markers are drawn in place, and new samples land at once.

### Accessibility

- A `figure` named by its visible label (by default the labels' "Latency distribution") and described by a text summary: how many requests were sampled, each percentile's latency, and the share within the objective ("97.4% within the 300 ms SLO.").
- The dots, the ruler and the hatch are decorative (`aria-hidden`); the flags and the header are text.
- With no samples it says "No data", and there's no summary.
- The axis runs from the inline start, so right to left in RTL; the flags' figures keep their order.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# History Strip

> Show daily status as colored cells, with details on hover or focus, such as uptime.

Source: https://www.youj.dev/docs/components/history-strip

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { SegmentedControl, SegmentedControlItem, HistoryStrip, type UptimeDay } from '@youj/react'

/** Ninety days ending 28 Sep 2026: quiet, a few short blips, and one long outage `outageAgo` days back. */
function history(outageAgo: number, seed: number): UptimeDay[] {
  let s = seed
  const random = () => ((s = (s * 16807) % 2147483647) - 1) / 2147483646
  return Array.from({ length: 90 }, (_, i) => {
    const ago = 89 - i
    const date = new Date(2026, 8, 28 - ago)
    const outage = ago === outageAgo
    const minutes = outage ? 192 : ago > 0 && random() < 0.08 ? 1 + Math.floor(random() * 5) : 0
    return {
      date,
      uptime: 1 - minutes / 1440,
      downtimeMinutes: minutes,
      incidents: outage ? 1 : 0,
      ...(outage ? { note: 'Delivery queue stalled; backlog replayed' } : null),
    }
  })
}

const SERVICES = { 'api-gateway': history(23, 3), webhooks: history(41, 7), search: history(64, 11) }
type Service = keyof typeof SERVICES

export default function HistoryStripDemo() {
  const [service, setService] = useState<Service>('webhooks')
  return (
    <div className="flex w-full max-w-2xl flex-col gap-5">
      <SegmentedControl aria-label="Service" value={service} onValueChange={(next) => setService(next as Service)} className="self-start">
        {(Object.keys(SERVICES) as Service[]).map((name) => (
          <SegmentedControlItem key={name} value={name} className="font-mono">
            {name}
          </SegmentedControlItem>
        ))}
      </SegmentedControl>
      {/* A new service sweeps its colours across, oldest day to newest. */}
      <HistoryStrip days={SERVICES[service]} label={`Daily uptime, ${service}`} />
    </div>
  )
}
```

Ninety days of uptime for a service, which you pick from api-gateway, webhooks and search.

Days at or above `target` (default 99.9%) take the success tone. Below it the color slides through warning, and below `critical` (default 99%) on toward danger, so a day is as loud as it was bad. A day without data is a dim well, and a day with an incident carries a pip over its cell.

In a narrow container it keeps the latest 60 days under about 28rem and the latest 30 under 18rem, so cells never thin past legibility; the axis says how far back it goes.

### Mini strips

```tsx
'use client'

import { HistoryStrip, type UptimeDay } from '@youj/react'

/** Ninety days ending 28 Sep 2026 with a few bad days, `[days ago, minutes down]`. */
function history(bad: [number, number][]): UptimeDay[] {
  return Array.from({ length: 90 }, (_, i) => {
    const ago = 89 - i
    const minutes = bad.find(([day]) => day === ago)?.[1] ?? 0
    return { date: new Date(2026, 8, 28 - ago), uptime: 1 - minutes / 1440, downtimeMinutes: minutes }
  })
}

const SERVICES = [
  { name: 'api-gateway', days: history([[23, 9]]) },
  { name: 'webhooks', days: history([[41, 192], [40, 11]]) },
  { name: 'search', days: history([[12, 6], [11, 14], [10, 8]]) },
  { name: 'storage', days: history([[4, 26]]) },
]

const percent = new Intl.NumberFormat('en-US', { style: 'percent', minimumFractionDigits: 2, maximumFractionDigits: 2 })

export default function HistoryStripMini() {
  return (
    <ul className="flex w-full max-w-xl flex-col gap-2">
      {SERVICES.map((service) => {
        const average = service.days.reduce((sum, day) => sum + (day.uptime ?? 1), 0) / service.days.length
        return (
          // The row says the name and the figure, so its strip is decoration.
          <li key={service.name} className="grid grid-cols-[7rem_minmax(0,1fr)_4.5rem] items-center gap-4 rounded-xl bg-band px-4 py-3">
            <span className="truncate font-mono text-ui text-fg">{service.name}</span>
            <HistoryStrip days={service.days} size="sm" interactive={false} />
            <span className="text-end font-mono text-ui text-fg-muted tabular-nums">{percent.format(Math.floor(average * 10000) / 10000)}</span>
          </li>
        )
      })}
    </ul>
  )
}
```

A list of services, each with a mini strip beside its uptime figure.

`size="sm"` is the mini strip for a list row: short cells, hairline gaps and no axis. With `interactive={false}` it's decoration, hidden from assistive technology and out of the tab order, for a row that says the name and the figure itself.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add history-strip
```

It brings `tooltip`, `youj-core`, `youj-labels-history-strip`, `youj-presets`, `youj-ui-core` with it.

Use an history strip for day-by-day availability over a window: a status page, a service's health card, an SLA report. Each day is a slim cell whose color is its uptime, so the bad days stand out from the quiet ones at a glance, and hovering or focusing a day gives its date, uptime, downtime, incidents and a note. For one figure against a target, pair it with the big number it adds up to; for a value that moves within a range, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter).

```tsx
import { HistoryStrip, type UptimeDay } from '@youj/react'

// One entry per day, oldest first; the last one is today.
const days: UptimeDay[] = [
  { date: '2026-09-26', uptime: 1, incidents: 0 },
  { date: '2026-09-27', uptime: 0.8667, downtimeMinutes: 192, incidents: 1, note: 'Delivery queue stalled' },
  { date: '2026-09-28', uptime: 0.9995 },
]

<HistoryStrip days={days} label="Daily uptime, webhooks" />
```

A day's `uptime` is the share of it the service was up, from 0 to 1, or `null` when there's no data for it; `date` is a `Date` or an ISO date, read as a calendar day. `downtimeMinutes` defaults to what the uptime implies.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `days` (required) | `readonly UptimeDay[]` |  | One entry per day, oldest first; the last one is today. |
| `target` | `number` | `0.999` | Days at or above this uptime are healthy. |
| `critical` | `number` | `0.99` | Days below this mix from warning toward danger. |
| `size` | `'default' \| 'sm'` | `'default'` | `sm`: the mini strip for a list row: short cells, hairline gaps, no axis. |
| `interactive` | `boolean` | `true` | Focusable days with tooltips. `false` draws a decorative strip (hidden from assistive technology) for a row that speaks for itself. |
| `label` | `string` |  | Accessible name. Default: the labels' "Uptime". |
| `formatDate` | `(date: Date) => string` |  | Formats a day for the tooltip and the spoken text. Default: weekday, month and day in the locale. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `history-strip`, `history-strip-list`, `history-strip-cell`, `history-strip-pip-slot`, `history-strip-pip`, `history-strip-bar`, `history-strip-axis`, `history-strip-axis-start`, `history-strip-axis-rule`, `history-strip-axis-end`, `history-strip-summary`, and in the tooltip `history-strip-tooltip`, `history-strip-tooltip-date`, `history-strip-tooltip-value`, `history-strip-tooltip-incidents` and `history-strip-tooltip-note`. The root has `data-size` and, while a day is read, `data-reading`; each cell has `data-tone` (`success`, `warning`, `danger` or `none`) and, while read, `data-active`. A cell's color is the `--uptime-color` variable.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the cells rise from the baseline (`scale`, `opacity`), oldest to newest, when a third of the strip scrolls into view |
| Reveal wave |  | half the deliberate token, spread across the days | the delay from the oldest day to today |
| New data | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the colors sweep across in the same order |
| Reading a day | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the day lifts 2px and the others dim, on hover or focus |

**Reduced motion:** Drawn in place; new data and the day in reading change at once.

#### Reduced motion

The cells are drawn in place, and new data and the day in reading change at once.

### Accessibility

- A named `group` (your `label`, or the labels' "Uptime") holding a `list` of days. Each day is named with its date, uptime, downtime, incidents and note ("Sat, Sep 26: 99.37% uptime, 9 min down, 1 incident. Config push"), and a day without data says so.
- A summary describes the group: how many days, the average uptime and how many days had downtime.
- One tab stop, on today. The arrow keys step a day in the reading direction (mirrored in right-to-left text), Page Up and Page Down a week, Home and End go to the ends. Focus shows the day's tooltip, as hover does.
- With `interactive={false}` the strip is hidden from assistive technology and has no tab stops: the row around it has to speak.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it; dates, percentages and durations follow the provider's locale.

---

# Forecast Band

> Show a running total’s forecast range and when it may cross a budget.

Source: https://www.youj.dev/docs/components/forecast-band

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ForecastBand, type ForecastPoint } from '@youj/react'

/** Nineteen days of cloud spend, lighter at weekends, as a running total. */
const DAILY = [412, 468, 455, 301, 288, 476, 490, 463, 471, 318, 296, 502, 488, 479, 495, 334, 305, 512, 497]
const ACTUAL = DAILY.reduce<number[]>((sums, day) => [...sums, (sums.at(-1) ?? 0) + day], [])

/** The other 11 days of September at `pace` a day, the likely range widening with each day out. */
function project(pace: number): ForecastPoint[] {
  const last = ACTUAL.at(-1)!
  return Array.from({ length: 11 }, (_, i) => {
    const value = last + pace * (i + 1)
    const spread = 160 * Math.sqrt(i + 1) + 25 * (i + 1)
    return { value, low: value - spread * 0.8, high: value + spread }
  })
}

export default function ForecastBandDemo() {
  const [pace, setPace] = useState(460)
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      {/* max holds the scale still, so a new pace morphs the paths and glides the marker instead of rescaling. */}
      <ForecastBand
        actual={ACTUAL}
        forecast={project(pace)}
        budget={12000}
        max={15000}
        start="2026-09-01"
        format={{ style: 'currency', currency: 'USD' }}
        label="Cloud spend forecast for September"
      />
      <div className="flex gap-2">
        {[460, 520].map((p) => (
          <Button key={p} size="sm" variant={p === pace ? 'secondary' : 'outline'} onClick={() => setPace(p)}>
            ${p} a day
          </Button>
        ))}
      </div>
    </div>
  )
}
```

September cloud spend as a running total, with a forecast range that crosses the budget and a button to change the daily pace.

### Within budget

```tsx
'use client'

import { ForecastBand, type ForecastPoint } from '@youj/react'

/** Twenty-one days of ad spend at about $180 a day, as a running total. */
const ACTUAL = Array.from({ length: 21 }, (_, i) => Math.round((i + 1) * 180 + Math.sin(i * 1.7) * 60))

/** The last 9 days at a slower $150 a day; the range still reaches toward the budget. */
const FORECAST: ForecastPoint[] = Array.from({ length: 9 }, (_, i) => {
  const value = ACTUAL.at(-1)! + 150 * (i + 1)
  const spread = 90 * Math.sqrt(i + 1) + 20 * (i + 1)
  return { value, low: value - spread, high: value + spread * 1.2 }
})

export default function ForecastBandWithinBudget() {
  return (
    <div className="w-full max-w-2xl">
      {/* No crossing: no marker, and the summary says it stays within budget. */}
      <ForecastBand
        actual={ACTUAL}
        forecast={FORECAST}
        budget={6000}
        start="2026-06-01"
        format={{ style: 'currency', currency: 'EUR' }}
        tone="chart-3"
        label="Ad spend forecast for June"
      />
    </div>
  )
}
```

An ad spend forecast whose range stays under the budget line, drawn in a different tone.

When the forecast stays under the line there's no marker, and the summary says so. The range can still reach past the budget: that's the risk, drawn honestly.

### Scenario

```tsx
'use client'

import { ForecastBand, type ForecastPoint } from '@youj/react'

/** Eighteen days of a team's API spend at about $260 a day, as a running total. */
const ACTUAL = Array.from({ length: 18 }, (_, i) => Math.round((i + 1) * 260 + Math.sin(i * 1.3) * 90))

/** The rest of the month at the current pace, the range widening with each day out. */
const FORECAST: ForecastPoint[] = Array.from({ length: 12 }, (_, i) => {
  const value = ACTUAL.at(-1)! + 265 * (i + 1)
  const spread = 120 * Math.sqrt(i + 1) + 18 * (i + 1)
  return { value, low: value - spread, high: value + spread }
})

/** If the batch jobs move to the cheaper tier from tomorrow: about $190 a day. */
const CHEAPER_TIER = FORECAST.map((_, i) => ACTUAL.at(-1)! + 190 * (i + 1))

export default function ForecastBandScenario() {
  return (
    <div className="w-full max-w-2xl">
      <ForecastBand
        actual={ACTUAL}
        forecast={FORECAST}
        budget={7500}
        start="2026-11-01"
        format={{ style: 'currency', currency: 'USD' }}
        label="API spend forecast for November"
        scenario={{ label: 'Batch jobs on the cheaper tier', values: CHEAPER_TIER, tone: 'chart-1' }}
      />
    </div>
  )
}
```

An API bill on pace to cross its budget, with a second path for moving batch jobs to a cheaper tier, which lands under the line.

`scenario` draws a second running total from today as a solid line in its own tone (`chart-2` unless you pass one), ending in a dot, with its `label` in the legend. The summary adds where it ends and whether it crosses the budget. Its values cover the same remaining days as `forecast`.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add forecast-band
```

It brings `hatched-bar`, `youj-core`, `youj-labels-forecast-band`, `youj-presets`, `youj-ui-core` with it.

Use a forecast band for a total that only grows through a period (cloud spend, ad spend, API calls against a quota) when the question is where it lands and when it crosses the line. Spend so far is a solid ink line over a faint wash. From today the forecast carries on as a dashed line in its tone, inside its likely range, over a hatched projected area: solid for what's settled, hatched for what isn't, as in the [Hatched Bar](https://www.youj.dev/docs/components/hatched-bar). The budget is a dashed line. If the forecast crosses it, the stretch above the line is hatched in danger and a marker lands on the crossing day, with its flag over the plot. For a budget read as what's left, use an [Limit Meter](https://www.youj.dev/docs/components/limit-meter); for values over time with axes and tooltips, a [Chart](https://www.youj.dev/docs/components/chart).

```tsx
import { ForecastBand } from '@youj/react'

<ForecastBand
  // The running total at the end of each elapsed day; the last one is today.
  actual={[412, 880, 1335 /* … */]}
  // The forecast running total for each remaining day, with its likely range.
  forecast={[{ value: 8500, low: 8370, high: 8710 } /* … */]}
  budget={12000}
  start="2026-09-01"
  format={{ style: 'currency', currency: 'USD' }}
/>
```

The period runs from `start` for as many days as `actual` and `forecast` hold between them. Its days are named in the locale ("Sep 28"). Without `start`, the crossing is named from today ("in 9 days") and the axis numbers the days. The scale tops out at a round number above the budget and the forecast's high. Pass `max` to hold it still when the data changes, so the axis stays put while the paths morph. For a unit Intl has none for (tickets, kWh), pass `formatValue` instead of `format`: a function that writes every amount and the axis labels.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actual` (required) | `readonly number[]` |  | The running total at the end of each elapsed day, the last one being today. |
| `forecast` (required) | `readonly ForecastPoint[]` |  | The forecast running total for each remaining day of the period. |
| `budget` (required) | `number` |  |  |
| `start` | `Date \| string` |  | The period's first day, to name dates ("Sep 28"). Without it the crossing is named relative to today ("in 9 days") and days are numbered. |
| `max` | `number` |  | The top of the scale. Default: a round number above the budget and the forecast's high; pass one to keep the scale still across data. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the amounts, e.g. `{ style: 'currency', currency: 'USD' }`. |
| `formatValue` | `(value: number) => string` |  | Writes every amount (and the scale) with your own function, for units Intl has none for ("1,240 kWh"). Replaces `format`. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Names the chart for assistive tech. Default: the labels' "Spend forecast". |
| `tone` | `'accent' \| 'neutral' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'chart-5'` | The forecast's color: its line, range and hatch. |
| `legend` | `boolean` | `true` | Show the legend over the plot. |
| `scenario` | `ForecastScenario` |  | A second path from today: what the total does if something changes. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `forecast-band`, `forecast-band-legend`, `forecast-band-swatch`, `forecast-band-chart` (the image), `forecast-band-axis` (with `data-axis` `x` or `y`), `forecast-band-tick`, `forecast-band-plot`, `forecast-band-data`, `forecast-band-grid`, `forecast-band-art` (the drawing, mirrored in RTL), `forecast-band-actual`, `forecast-band-actual-area`, `forecast-band-actual-line`, `forecast-band-forecast`, `forecast-band-range`, `forecast-band-forecast-line`, `forecast-band-projection`, `forecast-band-overshoot`, `forecast-band-today`, `forecast-band-today-label`, `forecast-band-now`, `forecast-band-budget`, `forecast-band-flag` (the budget's and the crossing's), `forecast-band-flag-name`, `forecast-band-flag-value`, `forecast-band-crossing` (with `data-day`), `forecast-band-marker`, `forecast-band-pulse`, `forecast-band-leader`, `forecast-band-scenario-line`, `forecast-band-scenario-end` and `forecast-band-summary`. The root has `data-state` (`over` or `within`). `tone` sets the forecast's color, a chart color by default, as `--forecast-tone`, and the scenario's tone is `--forecast-scenario-tone`. `--forecast-band-height` sets the plot's height (13rem). The flags and the today chip take the theme's label voice.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Reveal: actual | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | when a third of the chart scrolls into view, the spend line and its wash draw in from the start to today (a clip, so nothing stretches) |
| Reveal: forecast | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the forecast, its range and the hatch wipe on from today to the period’s end, starting as the actual line lands |
| Crossing | `spring.settle` | 0.45s, bounce 0.3 | the marker arrives as the wipe reaches it, and its ring pulses once; the flag fades in over it |
| New data | `spring.smooth` | 0.36s, bounce 0 | every path morphs to the new values (keep the point counts stable), and the budget line and the marker glide; the ring pulses once more only if the crossing day moves |
| No crossing | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the marker and its flag leave |

**Reduced motion:** Drawn in place: no draw or wipe, the marker's ring static, new data landing at once.

#### Reduced motion

Everything is drawn in place. There's no draw, no wipe and no pulse, and new data lands at once.

### Accessibility

- The plot is an `img` named by `label` (by default the labels' "Spend forecast"). It's described by a text summary: what's spent of the budget, the forecast at the period's end and its likely range, and the crossing day ("Crosses budget Sep 28") or "Stays within budget".
- The legend over the plot is a list of text, so it reads as it looks. The lines, the hatch, the marker and the axes are inside the image.
- Time runs from the inline start, like the kit's other rulers, so the plot mirrors in RTL. It holds no text; the flags and axis labels stay upright and in their own order.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Calendar Heatmap

> Show a day grid by week with intensity and the current streak, such as habit completion.

Source: https://www.youj.dev/docs/components/calendar-heatmap

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { StreakCheck, CalendarHeatmap, StreakSummary, streakStats, type StreakDay } from '@youj/react'

const DAY = 86_400_000
const TODAY = '2026-09-28'
const T = Date.parse(`${TODAY}T00:00:00Z`) / DAY
const iso = (n: number) => new Date(n * DAY).toISOString().slice(0, 10)

/** Missed days: one before the current run, one either side of an older 31-day run, and a scatter further back. */
const missed = (ago: number) => {
  if (ago === 24 || ago === 40 || ago === 72) return true
  if (ago > 40 && ago < 72) return false
  return ago > 24 && (ago % 9 === 0 || ago % 13 === 5)
}

const HISTORY: StreakDay[] = []
for (let ago = 182; ago >= 1; ago--) {
  if (ago === 9) HISTORY.push({ date: iso(T - ago), frozen: true })
  else if (!missed(ago)) HISTORY.push({ date: iso(T - ago) })
}

export default function CalendarHeatmapDemo() {
  const [days, setDays] = useState(HISTORY)
  const done = streakStats(days, TODAY).today
  const setToday = (next: boolean) => setDays((list) => [...list.filter((d) => d.date !== TODAY), ...(next ? [{ date: TODAY }] : [])])

return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <div className="flex flex-col gap-6">
        <div className="flex items-start justify-between gap-4">
          <div className="flex min-w-0 flex-col gap-0.5">
            <p className="text-ui font-medium text-fg">Morning run</p>
            <p className="text-ui-sm text-fg-muted">5 km before 8:00</p>
          </div>
          <StreakCheck pressed={done} onPressedChange={setToday} />
        </div>
        <StreakSummary days={days} today={TODAY} freezes={{ left: 2, total: 3 }} />
        <CalendarHeatmap days={days} today={TODAY} onTodayChange={setToday} />
      </div>
    </div>
  )
}
```

A morning-run habit shown as a half-year grid of days, with a check for today.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add calendar-heatmap
```

It brings `button`, `counter`, `icon-check`, `icon-flame`, `icon-snowflake`, `morph-label`, `typography`, `use-announcer`, `use-now`, `youj-core`, `youj-labels-calendar-heatmap`, `youj-presets`, `youj-ui-core` with it.

The copy is 20 registry items, about 8,700 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `counter`, `icon-check`, `icon-engine`, `icon-flame`, `icon-loader-ring`, `icon-snowflake`, `morph-label`, `settled-entrances`, `spinner` and 3 more.

Use a calendar heatmap for anything done day by day, where the run matters as much as the total: a habit, a practice, a daily check-in. Each week is a column and each weekday a row, with the newest week at the inline end. A done dot is lit in the tone, stronger the more got done; a missed day is a recessed well; a day a freeze token covered is hatched and keeps the run alive; days still to come are empty rings. `StreakSummary` sits over it with the current run and how far it is to the next milestone, and `StreakCheck` is the "Mark done" button for a header or a list row. The [Streaks block](https://www.youj.dev/docs/blocks/calendars-and-schedules) puts all three together. For a count per day without a run to keep, use a [Chart](https://www.youj.dev/docs/components/chart); for one bounded value, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter).

```tsx
import { StreakCheck, CalendarHeatmap, StreakSummary, streakStats, type StreakDay } from '@youj/react'

const [days, setDays] = useState<StreakDay[]>([
  { date: '2026-09-26' },
  { date: '2026-09-27', frozen: true },
])
const setToday = (done: boolean) =>
  setDays((list) => [...list.filter((d) => d.date !== '2026-09-28'), ...(done ? [{ date: '2026-09-28' }] : [])])

<StreakCheck pressed={streakStats(days, '2026-09-28').today} onPressedChange={setToday} />
<StreakSummary days={days} today="2026-09-28" freezes={{ left: 2, total: 3 }} />
<CalendarHeatmap days={days} today="2026-09-28" onTodayChange={setToday} />
```

A day is an ISO `date`, a `value` out of the grid's `max` (1 by default, so a listed day is done), and `frozen` for a day a freeze token covered. Days not listed are missed. With `max` above 1 the dots take four levels of heat, and the legend reads from Less to More; `tone` sets their color (the accent by default). `weeks` is how many columns show (26 by default) and `weekStart` whether a week starts on Monday (`1`, the default) or Sunday (`0`).

`today` is the newest day. Leave it out and the grid reads the browser's date once the page is live, and moves on at midnight. Give `onTodayChange` and today's dot becomes a toggle, called with whether today is now done; the grid is controlled, so update `days` there. `size="sm"` draws a mini grid for a list row: dots only, not interactive, and an image named by `label` if you give one.

`StreakSummary` takes the same `days` and `today`, and shows the current run, cells toward the next of its `milestones` (7, 30, 100 and 365 days by default), the longest run, the completion rate and, with `freezes`, the tokens left. `streakStats(days, today)` returns the same figures (`current`, `longest`, `rate` and whether `today` counts yet) for your own copy. `StreakCheck` is a toggle: pass `pressed` and `onPressedChange`, and `label` and `doneLabel` to change its words.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `days` (required) | `StreakDay[]` |  |  |
| `today` | `string` |  | The newest day, as an ISO date. Default: today in the browser's time zone, once the page is live. |
| `weeks` | `number` | `26` | Weeks shown, oldest first. |
| `max` | `number` | `1` | The value that fills a dot. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | Done dots' color. |
| `size` | `'default' \| 'sm'` | `'default'` | 'sm' is a mini grid for a list row: dots only, not interactive. |
| `weekStart` | `0 \| 1` | `1` | The first day of the week: 0 Sunday, 1 Monday. |
| `onTodayChange` | `(done: boolean) => void` |  | Makes today's dot a toggle, called with whether today is now done. |
| `label` | `string` | `"Daily history"` | The grid's accessible name. |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `days` (required) | `StreakDay[]` |  |  |
| `today` | `string` |  | The newest day, as an ISO date. Default: today in the browser's time zone. |
| `freezes` | `{ left: number; total: number }` |  | Freeze tokens: how many are left, of how many the period allows. |
| `milestones` | `number[]` | `[7, 30, 100, 365]` | The runs the flame meter counts toward. |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'default'` | `'sm'` |  |
| `label` | `string` | `"Mark done"` | The label while not done. |
| `doneLabel` | `string` | `"Done"` | The label once done. |
| `sound` | `boolean` | `true` | With sound on, marking plays `toggleOn` and unmarking `toggleOff`. |

Also takes the props of `TogglePrimitive.Props`.

### Styling

Parts: `calendar-heatmap` (with `data-size`), `calendar-heatmap-body`, `calendar-heatmap-month`, `calendar-heatmap-weekday`, `calendar-heatmap-day` (with `data-state`, `data-level` and `data-today`), `calendar-heatmap-dot`, `calendar-heatmap-footer`, `calendar-heatmap-readout` and `calendar-heatmap-legend`; `streak-summary`, `streak-summary-value`, `streak-summary-flame-icon`, `streak-summary-milestone`, `streak-summary-meter`, `streak-summary-cell` (with `data-state`), `streak-summary-stats`, `streak-summary-stat` and `streak-summary-token` (with `data-state`). `StreakCheck` is a `button` part with `data-streak-check`. The dots' color is `--streak-tone`, frozen days `--streak-frozen`, the summary's flame `--streak-flame`, and a mini grid's dot `--streak-mini` (5px).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Mark today done | `spring.settle` | 0.45s, bounce 0.3 | the dot pops in with one ripple |
| Today still open | `duration.deliberate` | 560ms | the dot breathes once a beat, three times the token |
| Summary first paint | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the meter’s cells light from the tail of the run to its head |
| Run grows | `duration.slow`, `ease.exit` | 340ms; cubic-bezier(0.4, 0, 1, 1) | the new head cell flares once, and the flame grows toward the milestone |
| Mark done | `spring.snappy` | 0.2s, bounce 0 | the pill morphs to Done and the check draws in |

**Reduced motion:** Dots and cells light at once, nothing breathes or ripples, the flame holds still and the check is drawn.

#### Reduced motion

Today's dot lights without the pop or the ripple and doesn't breathe while open. The summary's cells light at once, the flame holds still, and the check in `StreakCheck` is drawn without its stroke.

### Accessibility

- The grid is a group named by `label` (default: the labels' "Daily history"); each day is a button named by its date and state ("Sat, Sep 26, Done", "Sun, Sep 27, Frozen"). Days to come are disabled; past days are `aria-disabled`.
- The days are one tab stop, starting on today. Up and down step a day, left and right a week (mirrored in RTL), Home goes to the first day and End to today.
- With `onTodayChange`, today is a toggle with `aria-pressed`, named "Today, …, Mark done" whichever state it's in. Marking it announces the new run ("Done for today. Streak: 24 days") in a polite live region.
- The readout under the grid, the legend and the summary's meter are hidden from screen readers; the summary's figures are a description list.
- `StreakCheck` is a toggle with `aria-pressed`, named "Mark done" unless you pass a name.
- Its words come from the labels (`calendarHeatmap`, `streakDay`, `streakDone`, `streakMissed`, `streakFrozen`, `streakPartial`, `streakToday`, `streakMarkDone`, `streakTodayDone`, `streakTodayUndone`, `streakCurrent`, `streakLongest`, `streakRate`, `streakFreezes`, `streakDays`, `streakFreezesLeft`, `streakMilestone`, `streakLess` and `streakMore`), translated by the language packs.

---

# Allocation Meter

> Split a fixed total across categories and move amounts between them, such as budget envelopes.

Source: https://www.youj.dev/docs/components/allocation-meter

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { AllocationMeter, type Envelope } from '@youj/react'
import { CarIcon, CoffeeIcon, GiftIcon, ShoppingCartIcon, TicketIcon } from '@youj/icons'

const ENVELOPES: Envelope[] = [
  { id: 'groceries', name: 'Groceries', icon: <ShoppingCartIcon />, budget: 520, spent: 402, rollover: 40 },
  { id: 'eating', name: 'Eating out', icon: <CoffeeIcon />, budget: 220, spent: 252 },
  { id: 'fun', name: 'Fun', icon: <TicketIcon />, budget: 160, spent: 71 },
  { id: 'transport', name: 'Transport', icon: <CarIcon />, budget: 120, spent: 103 },
  { id: 'gifts', name: 'Gifts', icon: <GiftIcon />, budget: 80, spent: 12, rollover: 30 },
]

export default function AllocationMeterDemo() {
  const [envelopes, setEnvelopes] = useState(ENVELOPES)
  // Moving money shifts budget: the source's shrinks by the amount and the target's grows by it.
  const move = (from: string, to: string, amount: number) =>
    setEnvelopes((list) => list.map((e) => (e.id === from ? { ...e, budget: e.budget - amount } : e.id === to ? { ...e, budget: e.budget + amount } : e)))

return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <AllocationMeter envelopes={envelopes} onMove={move} step={10} />
    </div>
  )
}
```

Five budget envelopes with spending and rollover, where you can move money from one to another.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add allocation-meter
```

It brings `use-announcer`, `youj-core`, `youj-labels-allocation-meter`, `youj-presets`, `youj-ui-core` with it.

Use an allocation meter for a budget split into pots that each have their own limit: groceries, eating out, transport. Each envelope is a column of cells holding what's left, draining from the top as money is spent. Money rolled over from last period sits on top, hatched, and goes first; an envelope spent past empty turns its base the danger tone and drips under it, one drop for each tenth it's over, up to three. Money moves by dragging one envelope onto another, or from the keyboard. The [Budget block](https://www.youj.dev/docs/blocks/rankings-and-breakdowns) builds a month's budget around it. For spend against one limit with policy lines, use an [Limit Meter](https://www.youj.dev/docs/components/limit-meter); for how full several resources are, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter).

```tsx
import { useState } from 'react'
import { AllocationMeter, type Envelope } from '@youj/react'

export function Budget() {
  const [envelopes, setEnvelopes] = useState<Envelope[]>([
    { id: 'groceries', name: 'Groceries', budget: 520, spent: 402, rollover: 40 },
    { id: 'eating', name: 'Eating out', budget: 220, spent: 252 },
    { id: 'fun', name: 'Fun', budget: 160, spent: 71 },
  ])
  const move = (from: string, to: string, amount: number) =>
    setEnvelopes((list) => list.map((e) => (e.id === from ? { ...e, budget: e.budget - amount } : e.id === to ? { ...e, budget: e.budget + amount } : e)))

return <AllocationMeter envelopes={envelopes} onMove={move} step={10} />
}
```

An envelope is its `name`, this period's `budget`, what's been `spent`, and any `rollover` carried in; what's left is the budget plus the rollover, less the spending. `icon` puts a glyph beside the name, and `tone` sets its color (the chart colors in turn by default). An envelope under 15% turns the warning tone, and one past empty the danger tone. Under the rack, a readout names the envelope in focus or under the pointer and what it has left, beside the rollover and overspent swatches; `legend={false}` leaves that row out.

The meter is controlled. Give `onMove` and money can move: it's called with the source's `id`, the target's `id` and the amount, and you update the budgets. Without it the meter is read-only. `step` is what one drag or one Up press carries (10 by default), and a move never takes more than the source has left. `segments` is the cells per envelope (16), and `format` the `Intl.NumberFormat` options for the amounts (whole US dollars by default).

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `envelopes` (required) | `Envelope[]` |  |  |
| `onMove` | `(from: string, to: string, amount: number) => void` |  | Money moved from one envelope to another; update the budgets. Without it nothing moves. |
| `step` | `number` | `10` | What one drop or one Up press carries. |
| `segments` | `number` | `16` | Cells per envelope. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for the amounts. Default: US dollars, whole. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` | `"Envelopes"` | The rack's accessible name. |
| `sound` | `boolean` | `true` | With sound on, a drop plays `select`. |
| `legend` | `boolean` | `true` | The row under the rack: a readout of the envelope in focus or under the pointer, and the rollover and overspent swatches. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `allocation-meter` (with `data-carrying`), `allocation-meter-envelope` (with `data-state`: `ok`, `low` or `over`, and `data-source` and `data-target` while money is in hand), `allocation-meter-value`, `allocation-meter-track`, `allocation-meter-cell` (with `data-state` and `data-rollover`), `allocation-meter-base`, `allocation-meter-spill`, `allocation-meter-label`, `allocation-meter-ghost`, `allocation-meter-carry`, `allocation-meter-packet`, and under the rack `allocation-meter-rack`, `allocation-meter-footer`, `allocation-meter-readout` and `allocation-meter-legend`. An envelope's color is `--envelope-tone`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pick up | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the cells the amount would take dim in the source, and a ghost of the cells it would add rings the target |
| Drop | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | a chip carries the amount across in a low arc |
| Relight | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | both columns relight from their old edge, one cell at a time |
| Overspend | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the drops under the base draw out one after another |

**Reduced motion:** Cells light at once, no chip travels and the drops appear in place.

#### Reduced motion

Cells light and darken at once, the chip doesn't travel on a drop, and an overspent envelope's drops appear in place.

### Accessibility

- The rack is a group named by `label` (default: the labels' "Envelopes"), and with `onMove` described by how to move money from the keyboard.
- Each envelope is a button named by what it has left, of what, and any rollover ("Groceries, $158 left of $560, $40 rolled over"), or by how far over it is ("Eating out, $32 over").
- The envelopes are one tab stop. Left and right move between them (mirrored in RTL), Home and End go to the ends. Space or Enter picks money up; then the arrows choose where it goes, Up and Down change the amount by `step`, Enter moves it and Escape cancels. Moving focus out of the rack cancels too.
- Every step is announced in a polite live region: what's picked up, where it would go, what moved and a cancel.
- Its words come from the labels (`envelopes`, `envelopeLeft`, `envelopeOver`, `envelopeOf`, `envelopeRollover`, `envelopeRolloverTag`, `envelopeOverspentTag`, `envelopeHint`, `envelopePickedUp`, `envelopeTarget`, `envelopeMoved` and `envelopeMoveCancelled`), translated by the language packs.

---

# Seat Map

> Choose seats from a venue plan, with price tiers, availability and keyboard navigation.

Source: https://www.youj.dev/docs/components/seat-map

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { SeatMap, type SeatMapRow, type SeatMapTier } from '@youj/react'

const TIERS: SeatMapTier[] = [
  { id: 'front', name: 'Front stalls', price: 68 },
  { id: 'stalls', name: 'Stalls', price: 48 },
  { id: 'rear', name: 'Rear', price: 32 },
]

const TAKEN = new Set(['A4', 'A5', 'A6', 'B6', 'B7', 'C1', 'C2', 'C9', 'D5', 'D6', 'E10', 'F3', 'F4', 'F11', 'G7', 'G8'])
const ROWS: SeatMapRow[] = 'ABCDEFG'.split('').map((letter, r) => ({
  id: letter,
  label: letter,
  seats: Array.from({ length: 12 }, (_, i) => ({
    id: `${letter}${i + 1}`,
    number: i + 1,
    tier: r < 2 ? 'front' : r < 5 ? 'stalls' : 'rear',
    unavailable: TAKEN.has(`${letter}${i + 1}`),
  })),
}))

export default function SeatMapDemo() {
  const [picked, setPicked] = useState(['D8', 'D9'])
  const money = new Intl.NumberFormat('en-GB', { style: 'currency', currency: 'EUR' })
  const total = picked.reduce((sum, id) => sum + (TIERS.find((t) => t.id === ROWS.flatMap((r) => r.seats).find((s) => s.id === id)?.tier)?.price ?? 0), 0)
  return (
    <div className="flex w-full max-w-lg flex-col gap-4 rounded-2xl border border-line bg-surface p-6">
      <SeatMap rows={ROWS} tiers={TIERS} aisles={[3, 9]} value={picked} onValueChange={setPicked} max={6} locale="en-GB" />
      <p className="flex justify-between border-t border-line pt-3 font-mono text-ui-sm text-fg-muted tabular-nums">
        <span>{picked.join(' · ') || 'No seats yet'}</span>
        <span className="text-fg">{money.format(total)}</span>
      </p>
    </div>
  )
}
```

A theater with three price tiers and two aisles, a running total, and two seats chosen to start.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add seat-map
```

It brings `icon-check`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-seat-map`, `youj-presets`, `youj-ui-core` with it.

Use a seat map when where someone sits is the choice: a concert, a cinema, a flight, a table plan. The stage sits at the top and the rows bend gently round it, split by aisles, with each row's letter at both ends. Seats take their price tier's color, taken seats are dimmed and hatched, and picked seats fill with their tier and spring in with a check. Pointing at or focusing a seat raises a chip over it with its row, number, tier and price, and the chip glides from seat to seat.

```tsx
import { SeatMap, type SeatMapRow, type SeatMapTier } from '@youj/react'

const tiers: SeatMapTier[] = [
  { id: 'front', name: 'Front stalls', price: 68 },
  { id: 'rear', name: 'Rear', price: 32 },
]
const rows: SeatMapRow[] = ['A', 'B'].map((letter) => ({
  id: letter,
  label: letter,
  seats: Array.from({ length: 10 }, (_, i) => ({ id: `${letter}${i + 1}`, number: i + 1, tier: letter === 'A' ? 'front' : 'rear' })),
}))

<SeatMap rows={rows} tiers={tiers} aisles={[5]} value={picked} onValueChange={setPicked} max={6} />
```

`rows` run from the stage back, each with its seats in order along the row; a seat names its `tier` and can be `unavailable`. `aisles` lists the seat positions after which an aisle runs. `value` and `onValueChange` hold the picked seat ids (or use `defaultValue`), and `max` caps how many can be picked. Prices format in `currency` (EUR by default) and the provider's locale. `stage` changes the stage's word, or `false` leaves the stage out, for a table plan or a classroom. The legend under the map lists the tiers with their prices.

Seats shrink with the room down to about 17px. On a narrower screen the plan scrolls sideways instead, so seats stay big enough to tap. It opens on its center, where the stage is, and its edges fade by how far there is left to scroll. Each seat's hit area fills the gaps around it, and a seat you arrow to scrolls clear of the fades.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `SeatMapRow[]` |  |  |
| `tiers` (required) | `SeatMapTier[]` |  |  |
| `aisles` | `number[]` | `[]` | Seat positions (1-based, counted along the row) after which an aisle runs. |
| `value` | `string[]` |  | The picked seats' ids. |
| `defaultValue` | `string[]` |  |  |
| `onValueChange` | `(value: string[]) => void` |  |  |
| `max` | `number` |  | How many seats can be picked. Default: no limit. |
| `currency` | `string` | `'EUR'` | ISO 4217 code for the prices. |
| `format` | `(price: number) => string` |  | Formats a tier's price. Default: `currency` in the locale, without decimals. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Seat map". |
| `stage` | `string \| false` |  | The word on the stage, or false for no stage. Default: the labels' "Stage". |
| `sound` | `boolean` | `true` | Plays toggle cues as seats are picked and let go. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `seat-map`, `seat-map-stage`, `seat-map-grid`, `seat-map-row`, `seat-map-row-label`, `seat-map-seat` (with `data-state`), `seat-map-aisle`, `seat-map-inspector` and `seat-map-legend`. The seat size is `--seat`, fitted to the width between 1.0625rem and 1.75rem.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pick | `spring.settle` | 0.45s, bounce 0.3 | the seat fills with its tier and the check springs in |
| Let go | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | the check shrinks away |
| Point or focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the chip glides to the seat |

**Reduced motion:** The check and the chip appear in place.

#### Reduced motion

A picked seat's check appears in place, and the chip moves to the next seat without gliding.

### Accessibility

- The map is a grid named by `label` (default: the labels' "Seat map") and described by how to use it; each row is a row headed by its letter.
- Each seat is a grid cell named by its row, number, price and status ("Row F, seat 12, €48, available"), with `aria-selected` when picked and `aria-disabled` when taken.
- The grid is one tab stop. Arrows move seat to seat and row to row (skipping aisles), Home and End jump to a row's ends, Ctrl+Home and Ctrl+End to the first and last seat, and Space or Enter picks or lets go.
- Picking and letting go are announced ("Row F, seat 12 added"), with the toggle cues; at the limit the pick is refused with the error cue and "You can pick up to 6 seats".
- A venue plan is a physical map, so it isn't mirrored in RTL: seat 1 stays where the venue put it, and the arrow keys keep their direction. The text around it follows the page.
- Its words come from the labels (`seatMap`, `seatMapHint`, `seatMapStage`, `seatItem`, `seatAvailable`, `seatUnavailable`, `seatSelected`, `seatRow`, `seatNumber`, `seatAdded`, `seatRemoved`, `seatLimit`), translated by the language packs.

---

# Slot Grid

> Choose a bookable time from a weekly grid that shows remaining places.

Source: https://www.youj.dev/docs/components/slot-grid

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { SlotGrid, type SlotGridSlot } from '@youj/react'

const WEEK = new Date(2026, 8, 28)
const TIMES = [7 * 60, 9 * 60, 12 * 60 + 30, 18 * 60]
// Places still free in each slot, a row per start time and a column per day; -1 isn't offered.
const LEFT = [
  [6, 0, 3, 1, 8, 5, 2],
  [2, 4, 8, 7, 1, 0, 6],
  [8, 6, 5, 8, 7, 3, 4],
  [0, 1, 2, 0, 3, 5, -1],
]

const SLOTS: SlotGridSlot[] = LEFT.flatMap((row, r) =>
  row.flatMap((left, day) => {
    if (left < 0) return []
    const start = new Date(WEEK)
    start.setDate(start.getDate() + day)
    start.setHours(Math.floor(TIMES[r]! / 60), TIMES[r]! % 60)
    return [{ id: `${r}-${day}`, start, left, capacity: 8, mine: r === 2 && day === 3 }]
  }),
)

export default function SlotGridDemo() {
  const [slot, setSlot] = useState<string | null>(null)
  return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <SlotGrid slots={SLOTS} start={WEEK} value={slot} onValueChange={setSlot} />
    </div>
  )
}
```

A week of class slots with the places left in each, one of them already yours.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add slot-grid
```

It brings `icon-check`, `sliding-indicator`, `use-controllable-state`, `use-resize-measure`, `youj-core`, `youj-labels-slot-grid`, `youj-presets`, `youj-ui-core` with it.

Use a slot grid to pick one time from a week of sessions that each have a number of places: a studio's classes, a salon's chairs, a clinic's appointments, a tour's departures. There's a column per day and a row per start time. In each cell a run of pips, one per place up to eight, is lit for the places still free, so availability reads as a pattern before you read a number. A slot with only a few places left warms to the warning tone, a full one is hatched and dark, a time the day doesn't offer is a dash, and the viewer's own booking carries a check. For a single day of free times, use a list of buttons; for picking a date, a [Calendar](https://www.youj.dev/docs/components/calendar).

```tsx
import { SlotGrid, type SlotGridSlot } from '@youj/react'

const slots: SlotGridSlot[] = [
  { id: 'mon-7', start: new Date('2026-09-28T07:00'), left: 3, capacity: 8 },
  { id: 'mon-9', start: new Date('2026-09-28T09:00'), left: 0, capacity: 8 },
  { id: 'tue-7', start: new Date('2026-09-29T07:00'), left: 8, capacity: 8, mine: true },
]

const [slot, setSlot] = useState<string | null>(null)

<SlotGrid slots={slots} start={new Date('2026-09-28')} value={slot} onValueChange={setSlot} />
```

`start` is the first day shown (by default, the day of the earliest slot) and `days` how many follow (7). The rows are every start time among the slots, or the ones you pass as `times`, in minutes after midnight, so a time one day doesn't offer shows as a dash. A slot counts as few when it has `fewAt` places left or fewer (2). Only a slot with room can be picked: `onValueChange` is called with its id and the slot, and `value` makes the pick controlled.

`layout="auto"` (the default) measures the grid's own width and shows one day at a time when it's under 36rem, whatever the viewport: a track of the week's days, each with a bar of how much of it is still free, over that day's times as full-width rows. `layout="week"` and `layout="day"` fix one or the other.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `slots` (required) | `readonly SlotGridSlot[]` |  |  |
| `start` | `Date \| number` |  | The first day shown. Default: the day of the earliest slot. |
| `days` | `number` | `7` | Days shown. |
| `times` | `readonly number[]` |  | The rows, as start times in minutes after midnight. Default: every start time among the slots. |
| `value` | `string \| null` |  | The picked slot's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` | The slot picked at first. |
| `onValueChange` | `(id: string, slot: SlotGridSlot) => void` |  |  |
| `fewAt` | `number` | `2` | A slot with this many places left or fewer counts as few. |
| `layout` | `'auto' \| 'week' \| 'day'` | `'auto'` | `week` is the grid, `day` one day under a day picker; `auto` picks by the room there is. |
| `legend` | `boolean` | `true` | Show the legend under the grid. |
| `label` | `string` |  | The grid's accessible name. Default: the labels' "Available times". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | With sound on, picking a slot plays `select`. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `slot-grid` (with `data-layout`), `slot-grid-grid`, `slot-grid-row`, `slot-grid-time`, `slot-grid-day`, `slot-grid-cell` (with `data-state`: `open`, `few`, `full`, `closed` or `mine`, and `data-picked`), `slot-grid-pips`, `slot-grid-pip` (with `data-state`), `slot-grid-value`, `slot-grid-legend`, and in the day view `slot-grid-days`, `slot-grid-day-key`, `slot-grid-date` and `slot-grid-day-indicator`. In Bezel the day names are mono capital eyebrows and the times, dates and counts are mono.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the cells come in as a wave from the first slot |
| Pick | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the cell lights as the key; a press gives a little |
| Another day | `spring.snappy` | 0.2s, bounce 0 | in the day view the new day slides in from the side it lies on; the day key glides |

**Reduced motion:** The grid is drawn in place, days swap without the slide and the key jumps.

#### Reduced motion

The cells are drawn in place, a new day replaces the last without sliding, and the day key moves without gliding.

### Accessibility

- The grid is an ARIA grid named by `label` (default: the labels' "Available times") and described by how to move through it, with the days as column headers and the times as row headers.
- Each cell is named by its day, time and state ("Monday, September 28, 07:00, 3 left"). A slot with room is selectable and says whether it's picked; a full slot, a time not offered and your own booking are disabled.
- The grid is one tab stop, starting on the picked slot or the first with room. Arrow keys move between days and times (left and right mirrored in RTL), Home and End to a row's ends, Ctrl+Home and Ctrl+End to the grid's, and Enter or Space picks. In the day view, left and right step the day.
- With sound on, picking a slot plays `select` (`sound={false}` keeps it quiet).
- Its words come from the labels (`slotGrid`, `slotGridHint`, `slotGridCell`, `slotGridLeft`, `slotGridFull`, `slotGridClosed`, `slotGridFew`, `slotGridOpen`, `slotGridMine`, `slotGridDays`, `slotGridOpenCount`), translated by the language packs.

---

# World Clock

> Compare several time zones side by side and find a time that works for everyone.

Source: https://www.youj.dev/docs/components/world-clock

## Examples

### Demo

```tsx
'use client'

import { WorldClock, type WorldClockZone } from '@youj/react'

const TEAM: WorldClockZone[] = [
  { timeZone: 'Europe/London', label: 'Ada · London' },
  { timeZone: 'America/New_York', label: 'Grace · New York' },
  { timeZone: 'Asia/Singapore', label: 'Lin · Singapore', workingHours: [8.5, 17.5] },
  { timeZone: 'America/Los_Angeles', label: 'Joan · San Francisco', workingHours: [8, 16] },
]

export default function WorldClockDemo() {
  // No value: the cursor follows the clock. Drag it, or use the arrow keys, to propose a time.
  return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <WorldClock zones={TEAM} />
    </div>
  )
}
```

A team in four cities, following the clock. Drag the cursor, or use the arrow keys, to propose a time.

Each row reads the cursor's moment in its own zone, and its strip shows the first row's day an hour per cell: working hours, the waking hours around them, and night. The ring shows the hours when everyone is working.

### Find a meeting time

```tsx
'use client'

import { useState } from 'react'
import { Button, WorldClock, type WorldClockZone } from '@youj/react'

const ZONES: WorldClockZone[] = [
  { timeZone: 'Europe/Berlin', label: 'Berlin' },
  { timeZone: 'America/New_York', label: 'New York' },
  { timeZone: 'Asia/Kolkata', label: 'Bengaluru', workingHours: [10, 18] },
]

export default function WorldClockMeeting() {
  const [value, setValue] = useState<Date | null>(new Date('2026-10-13T12:00:00Z'))
  const when = value ?? new Date()

return (
    <div className="flex w-full max-w-3xl flex-col gap-4 rounded-2xl border border-line bg-surface p-5">
      <div className="flex flex-wrap items-center justify-between gap-3">
        <div>
          <h3 className="text-ui-lg font-medium text-fg">Quarterly planning</h3>
          <p className="text-ui-sm text-fg-muted">
            {new Intl.DateTimeFormat(undefined, { weekday: 'long', hour: '2-digit', minute: '2-digit', timeZone: 'Europe/Berlin', timeZoneName: 'short' }).format(when)}
          </p>
        </div>
        <Button size="sm">Send invite</Button>
      </div>
      {/* Controlled, on half hours: the app keeps the proposed time and books it. */}
      <WorldClock zones={ZONES} value={value} onValueChange={setValue} step={30} />
    </div>
  )
}
```

A meeting being planned on half hours. The app keeps the proposed time and shows it beside the title.

`value` and `onValueChange` make the chosen moment the app's, ready to send as an invite. Now sets it back to `null`, which follows the clock.

### Compact

```tsx
'use client'

import { WorldClock, type WorldClockZone } from '@youj/react'

const OFFICES: WorldClockZone[] = [
  { timeZone: 'America/Sao_Paulo', label: 'São Paulo' },
  { timeZone: 'Europe/Stockholm', label: 'Stockholm' },
  { timeZone: 'Asia/Tokyo', label: 'Tokyo' },
]

export default function WorldClockCompact() {
  // One line per office and a slim strip, for a sidebar or a card.
  return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <WorldClock zones={OFFICES} compact hourCycle={24} />
    </div>
  )
}
```

Three offices, one line each, for a sidebar or a card.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add world-clock
```

It brings `button`, `icon-moon`, `icon-sun`, `morph-label`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-labels-world-clock`, `youj-presets`, `youj-ui-core` with it.

The copy is 17 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `icon-engine`, `icon-loader-ring`, `icon-moon`, `icon-sun`, `morph-label`, `spinner`, `use-announcer`, `use-controllable-state`, `use-now`.

Use a world clock wherever people in different places have to meet: a team page, a meeting planner, a support rota, a booking that crosses borders. Each row is a zone or a person, with its name, its offset from UTC and from the first row, the time there with a sun or a moon, and a strip of the day. For one place's day as a ring, use [Day Ring](https://www.youj.dev/docs/components/day-ring); for shifts across a week, [Time Lanes](https://www.youj.dev/docs/components/time-lanes).

```tsx
import { WorldClock, type WorldClockZone } from '@youj/react'

const zones: WorldClockZone[] = [
  { timeZone: 'Europe/London', label: 'Ada · London' },
  { timeZone: 'America/New_York', label: 'Grace · New York' },
  { timeZone: 'Asia/Singapore', label: 'Lin · Singapore', workingHours: [8.5, 17.5] },
]

const [value, setValue] = useState<Date | null>(null)

<WorldClock zones={zones} value={value} onValueChange={setValue} step={30} />
```

A zone is an IANA `timeZone`, a `label`, and its `workingHours` as local hours from 0 to 24 (`[9, 17]` by default; `[9, 17.5]` ends at 17:30, and `[22, 6]` is a night shift). The waking hours outside work run from 07:00 to 22:00, and the rest is night.

The rows share one time axis: the first zone's day, midnight to midnight. On the days its clocks change that day is 23 or 25 hours long, and every offset is read from each zone's own clock at each moment, so the gap between two zones follows their changes too. Where a zone's date turns over, a line marks it and the cell names the new day.

The cursor is the chosen moment. With no `value` it follows the clock (`now`, by default the device's, ticking every second once the page is live); drag it, click a strip, or use the keys, and it snaps to `step` minutes (15 by default). `onValueChange` gets a `Date`, or `null` when Now is pressed. Moving past either end of the day moves the axis to the next or the previous one. Times read in 12 or 24 hours by the locale, unless `hourCycle` says otherwise; `compact` keeps one line per zone and drops the legend.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `zones` (required) | `WorldClockZone[]` |  | The zones, one row each. The first is the reference: the axis is its day, and the others say how far they are from it. |
| `value` | `Date \| number \| null` |  | The chosen moment. `null` follows the clock. Controlled. |
| `defaultValue` | `Date \| number \| null` | `null` | The moment chosen at first. |
| `onValueChange` | `(value: Date \| null) => void` |  | Called with the chosen moment, or `null` when Now is pressed. |
| `now` | `Date \| number` |  | The clock. Default: the device's, ticking every second once the page is live. |
| `step` | `number` | `15` | Minutes the cursor snaps to and the arrow keys move by. |
| `hourCycle` | `12 \| 24` |  | 12- or 24-hour times. Default: the locale's. |
| `compact` | `boolean` | `false` | One line per zone and a slimmer strip, for a sidebar or a card. |
| `label` | `string` |  | The accessible name of the whole. Default: the labels' "World clock". |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `world-clock` (with `data-state`: `live` or `set`, `data-yj-compact`, and `data-yj-overlap` while the cursor is in hours everyone shares), `world-clock-header`, `world-clock-overlap-summary`, `world-clock-now`, `world-clock-scroll`, `world-clock-grid`, `world-clock-ruler`, `world-clock-zone` (with `data-state`: the period at the cursor, `work`, `evening` or `night`), `world-clock-info`, `world-clock-daylight` (with `data-state`: `day` or `night`), `world-clock-label`, `world-clock-time`, `world-clock-offset`, `world-clock-date`, `world-clock-strip`, `world-clock-hour` (with `data-state`: `work`, `evening` or `night`), `world-clock-day-line`, `world-clock-track` (with `data-dragging`), `world-clock-overlap`, `world-clock-cursor`, `world-clock-handle` (with `data-state`) and `world-clock-legend`. Working hours are the accent's subtle tint, the hours around them the band, night the well, and the shared hours a ring in success. Below 40rem (30rem compact) the rows scroll sideways.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Cursor moves | `spring.snappy` | 0.2s, bounce 0 | from a key, a click or Now, the cursor glides to its new time; while dragged it follows the pointer with no lag |
| Clock tick | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | each time ticks over letter by letter: the digits that change leave and arrive, the rest stay |

**Reduced motion:** The cursor jumps to each new time and the times change in place.

#### Reduced motion

The cursor jumps to each new time instead of gliding, and the times change in place.

### Accessibility

- The whole is a group named by `label` (default: the labels' "World clock"). Each zone is a list item that reads its name, then its time, day, offset and whether it's day or night ("05:00, Tue 13 Jan, GMT-5, Night"); the strips are hidden from screen readers.
- The cursor's handle is a slider named "Proposed time", described by how to move it, and its value reads the moment in the first zone ("Tue 13 Jan, 10:00 in London").
- Left and right move it a step (mirrored in RTL), as do up and down; Shift with an arrow, or Page Up and Page Down, an hour; Home and End go to the ends of the day. Now returns to the clock and puts focus back on the handle.
- After every change a polite live region says the moment in every zone: "10:00 in London is 05:00 in New York and 18:00 in Singapore", with "tomorrow" or "yesterday" where a zone is on another day.
- Its words come from the labels (`worldClock`, `worldClockCursor`, `worldClockHint`, `worldClockTime`, `worldClockSummary`, `worldClockOverlap`, `worldClockNoOverlap`, `worldClockWorkingHours`, `worldClockOutsideHours`, `worldClockNight`, `worldClockDaytime`, `worldClockEveryone` and `now`), translated by the language packs; dates, offsets and "tomorrow" come from Intl in the locale.

---

# Timeline

> Show an activity feed grouped by day, with space made for new events.

Source: https://www.youj.dev/docs/components/timeline

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Badge, Button, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle, Timeline, type TimelineEvent } from '@youj/react'

const minutesAgo = (n: number) => new Date(Date.now() - n * 60_000)
const daysAgo = (n: number, hour: number) => {
  const d = new Date()
  d.setDate(d.getDate() - n)
  d.setHours(hour, 12, 0, 0)
  return d
}

const ACTIVITY: TimelineEvent[] = [
  {
    id: 'e1',
    type: 'deploy',
    actor: { name: 'Mira Chen' },
    title: (
      <>
        deployed <strong>web@4f2c91a</strong> to production
      </>
    ),
    summary: 'deployed web@4f2c91a to production',
    time: minutesAgo(4),
    meta: <Badge variant="success">Ready</Badge>,
    details: (
      <pre className="overflow-x-auto rounded-md border border-line bg-band px-3 py-2 font-mono text-ui-xs leading-5 text-fg">
        {'Build 38s · 212 routes · 14 edge regions\nPromoted from preview web-git-main'}
      </pre>
    ),
  },
  {
    id: 'e2',
    type: 'alert',
    title: (
      <>
        Error rate on <code>/api/checkout</code> above 2% for 5 minutes
      </>
    ),
    summary: 'Error rate on /api/checkout above 2%',
    time: minutesAgo(26),
    meta: <Badge variant="warning">Resolved</Badge>,
  },
  {
    id: 'e3',
    type: 'comment',
    actor: { name: 'Jonas Weber' },
    title: 'commented on #482, “Can we keep the old endpoint until Friday?”',
    time: minutesAgo(58),
  },
  { id: 'e4', type: 'merge', actor: { name: 'Priya Natarajan' }, title: 'merged #479, Streaming responses for search', time: daysAgo(1, 17) },
  { id: 'e5', type: 'pull-request', actor: { name: 'Jonas Weber' }, title: 'opened #482, Deprecate v1 checkout endpoint', time: daysAgo(1, 11) },
]

const OLDER: TimelineEvent[] = [
  { id: 'o1', type: 'commit', actor: { name: 'Sam Okafor' }, title: 'pushed 7 commits to feat/billing-portal', time: daysAgo(3, 16) },
  { id: 'o2', type: 'alert', title: 'Certificate for status.acme.dev renews in 7 days', time: daysAgo(4, 8) },
]

const INCOMING: Omit<TimelineEvent, 'id' | 'time'>[] = [
  { type: 'commit', actor: { name: 'Sam Okafor' }, title: 'pushed 1 commit to main' },
  { type: 'comment', actor: { name: 'Priya Natarajan' }, title: 'commented on #482, “Friday works.”' },
  { type: 'deploy', actor: { name: 'Sam Okafor' }, title: 'deployed web@9c01aa4 to preview' },
]

export default function ActivityFeed() {
  const [events, setEvents] = useState(ACTIVITY)
  const [hasMore, setHasMore] = useState(true)
  const [count, setCount] = useState(0)

const simulate = () => {
    const next = INCOMING[count % INCOMING.length]!
    setEvents((list) => [{ ...next, id: `live-${count}`, time: new Date() }, ...list])
    setCount((c) => c + 1)
  }

return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle role="heading" aria-level={2}>
          Activity
        </CardTitle>
        <CardDescription>acme/web · all environments</CardDescription>
        <CardAction>
          <Button variant="outline" size="sm" onClick={simulate}>
            Simulate event
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <Timeline
          events={events}
          locale="en-US"
          hasMore={hasMore}
          onLoadMore={async () => {
            await new Promise((resolve) => setTimeout(resolve, 900))
            setEvents((list) => [...list, ...OLDER])
            setHasMore(false)
          }}
        />
      </CardContent>
    </Card>
  )
}
```

An activity feed with a Simulate event button and a Load more for older events.

A timeline is always **newest first**: it sorts `events` by `time`, whatever their order, and groups them under Today, Yesterday and dated headings, so the latest event is at the top and older ones load at the bottom. Add an event to the front of `events` while the feed is on screen, as Simulate event does in the demo. It fades into its slot at the top while the events below glide down to make room, and its mark plays once. `onLoadMore` with `hasMore` adds a Load more button that shows a spinner while the promise runs. Older events join the bottom the same way, and once `hasMore` is false the feed says "That's everything."

`details` adds a Details toggle under an event that opens in place, for a build log, a stack trace or the commits in a push. `meta` puts a badge or a link at the end of the event's line.

### Your own event types

```tsx
'use client'

import { CreditCardIcon, UserPlusIcon } from '@youj/icons'
import { Badge, Timeline, type TimelineEvent, type TimelineEventType } from '@youj/react'

/* Your own event types sit beside the built-in ones (commit, comment, deploy,
 * alert, merge, pull-request). Each names an icon, a tone and a spoken label. */
const TYPES: Record<string, TimelineEventType> = {
  invoice: { icon: CreditCardIcon, tone: 'success', label: 'Invoice' },
  member: { icon: UserPlusIcon, tone: 'accent', label: 'New member' },
}

const hoursAgo = (n: number) => new Date(Date.now() - n * 3_600_000)

const EVENTS: TimelineEvent[] = [
  { id: 'b1', type: 'invoice', title: 'Invoice INV-0192 paid, $1,240.00', time: hoursAgo(0.3), meta: <Badge variant="success">Paid</Badge> },
  { id: 'b2', type: 'member', actor: { name: 'Lena Fischer' }, title: 'joined the Billing team', time: hoursAgo(1.5) },
  { id: 'b3', type: 'comment', actor: { name: 'Omar Haddad' }, title: 'left a note on the Q3 renewal', time: hoursAgo(3) },
]

export default function TimelineTypes() {
  return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <Timeline events={EVENTS} types={TYPES} locale="en-US" />
    </div>
  )
}
```

Two custom event types, an invoice and a new member, beside the built-in comment.

The built-in types are `commit`, `comment`, `deploy`, `alert`, `merge` and `pull-request`. `types` adds your own, or replaces them. Each one names an icon, a tone (`neutral`, `accent`, `success`, `warning` or `danger`) and the label a screen reader hears before the title.

### Comments

```tsx
'use client'

import { useState } from 'react'
import { CircleDashedIcon } from '@youj/icons'
import { Button, Textarea, Timeline, type TimelineEvent, type TimelineEventType } from '@youj/react'

/* An issue's activity: comments beside status changes, newest first. The
 * composer sits above the feed, where a posted comment lands. */
const TYPES: Record<string, TimelineEventType> = {
  status: { icon: CircleDashedIcon, tone: 'accent', label: 'Status change' },
}

const minutesAgo = (n: number) => new Date(Date.now() - n * 60_000)

const ACTIVITY: TimelineEvent[] = [
  { id: 'c3', type: 'comment', actor: { name: 'Jonas Ortiz' }, title: 'Safari 17 still loops after the cookie fix. Repro steps in the ticket.', time: minutesAgo(12) },
  { id: 's2', type: 'status', actor: { name: 'Mira Kovac' }, title: 'moved this from To do to In progress', time: minutesAgo(48) },
  { id: 'c1', type: 'comment', actor: { name: 'Mira Kovac' }, title: 'Taking this one. I think it is the SameSite change.', time: minutesAgo(50) },
]

export default function TimelineComments() {
  const [events, setEvents] = useState(ACTIVITY)
  const [draft, setDraft] = useState('')
  const post = () => {
    const text = draft.trim()
    if (!text) return
    setEvents((list) => [{ id: `c${list.length + 1}`, type: 'comment', actor: { name: 'Sana Noor' }, title: text, time: new Date() }, ...list])
    setDraft('')
  }
  return (
    <div className="flex w-full max-w-md flex-col gap-4 rounded-xl border border-line bg-surface p-4">
      <form
        className="flex flex-col gap-2"
        onSubmit={(event) => {
          event.preventDefault()
          post()
        }}
      >
        <Textarea aria-label="Comment" placeholder="Leave a comment" value={draft} onChange={(event) => setDraft(event.target.value)} rows={2} />
        <Button type="submit" size="sm" className="self-end" disabled={!draft.trim()}>
          Comment
        </Button>
      </form>
      <Timeline events={events} types={TYPES} />
    </div>
  )
}
```

An issue's activity: comments beside status changes, with a comment box above the feed.

A comment is an event of the built-in `comment` type whose `title` is what the person wrote; the timeline puts their name and avatar before it. Since the feed is newest first, put the composer above it, not below as a chat would: a posted comment then lands right under the box, fades into its slot and is announced. Add your own types (here `status`) for the other things that happen to the record. For a thread that reads oldest first, with replies and reactions, use the [Comment thread](https://www.youj.dev/docs/blocks/activity-and-conversations) block instead.

```tsx
const post = (text: string) =>
  setEvents((list) => [{ id: crypto.randomUUID(), type: 'comment', actor: me, title: text, time: new Date() }, ...list])
```

### Empty

```tsx
'use client'

import { Timeline } from '@youj/react'

export default function TimelineEmpty() {
  return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <Timeline events={[]} />
    </div>
  )
}
```

A timeline with no events.

With no events the feed says so. Pass `empty` to say something more specific.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add timeline
```

It brings `avatar`, `button`, `collapse`, `collapsible`, `empty`, `icon-alert-triangle`, `icon-engine`, `icon-git-commit`, `icon-git-merge`, `icon-git-pull-request`, `icon-message`, `icon-rocket`, `presence-list`, `use-now`, `youj-core`, `youj-labels-timeline`, `youj-ui-core` with it.

The copy is 25 registry items, about 8,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `button`, `collapse`, `collapsible`, `empty`, `icon-alert-triangle`, `icon-chevron-down`, `icon-engine`, `icon-git-commit`, `icon-git-merge` and 8 more.

Use a timeline for what happened, in order: deploys, commits, comments and alerts on a project, or the history of an order or an account. Each event has a typed mark on a rail, who did it, when, and optional details that open in place. For a list of things people act on (read, archive, snooze), use [Notification Center](https://www.youj.dev/docs/components/notification-center). For records people sort and filter, use a [data table](https://www.youj.dev/docs/blocks/tables-and-lists).

```tsx
import { Timeline, type TimelineEvent } from '@youj/react'

const events: TimelineEvent[] = [
  { id: 'e1', type: 'deploy', actor: { name: 'Mira Chen' }, title: 'deployed web@4f2c91a to production', time: '2026-09-27T09:41:00Z' },
  { id: 'e2', type: 'comment', actor: { name: 'Jonas Weber' }, title: 'commented on #482', time: '2026-09-27T08:15:00Z' },
]

export function Activity() {
  return <Timeline events={events} />
}
```

Pass events in any order. The timeline sorts them newest first and groups them under Today, Yesterday and dated headings. Each time reads as "5 min ago" today and as a clock time on older days, and it stays true: the feed re-renders every minute. Pass `now` to pin the clock instead, so a demo or a test reads the same on any day.

Keep the actor out of `title`: the timeline shows the name, with an avatar, before it. When `title` is JSX, pass a plain-text `summary` too, for the announcement when the event arrives live.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` (required) | `readonly TimelineEvent[]` |  |  |
| `types` | `Record<string, TimelineEventType>` |  | Extra or replacement event types. |
| `onLoadMore` | `() => Promise<unknown> \| void` |  | Loads older events. Shows a Load more button while `hasMore`. |
| `hasMore` | `boolean` | `false` |  |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `empty` | `ReactNode` |  | Shown when there are no events. |
| `now` | `Date \| number` |  | The moment "Today" and relative times count from, pinned (a demo's clock, a test). Default: the clock, read every minute once the page is live. |

Also takes the props of `ComponentProps<'div'>`.

An event (`TimelineEvent`) has an `id`, a `type`, a `title`, a `time` (a `Date`, an ISO string or a timestamp), and optionally an `actor` (`name`, `avatar`), a plain-text `summary`, `details` and `meta`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Event arrives | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades down 6px into its slot at the top (PresenceList) |
| Events below | `spring.smooth` | 0.36s, bounce 0 | glide down to make room |
| Event leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Mark |  |  | an arriving event’s icon plays once; every mark plays while its row is hovered |
| Details | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height and opacity (Collapse) |

**Reduced motion:** Events appear and leave in place, details open at once and the marks stay still.

#### Reduced motion

New events take their place at once and the list below doesn't glide. Details open and close instantly, and the marks don't play. What's announced, and when, is unchanged.

### Accessibility

- Each day is a section with a heading and an ordered list of its events.
- Every event starts with its type in words, "Deploy:", before who did it and what, because the mark is decorative.
- Times are `<time>` elements with the full date and time in `datetime` and on hover.
- A live arrival is announced once in a polite live region, as "Deploy: Mira Chen deployed web@4f2c91a to production". Loaded history isn't announced as news.
- Details toggles are disclosure buttons with `aria-expanded` and `aria-controls`. Load more announces "Loading older activity" while it runs.

---

# Stage Rail

> Track a pipeline’s stages, with duration, progress and status for each.

Source: https://www.youj.dev/docs/components/stage-rail

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Button, StageRail, type Stage } from '@youj/react'

const fresh = (): Stage[] => [
  { id: 'build', name: 'Build', status: 'running', startedAt: Date.now(), estimate: 6000 },
  { id: 'test', name: 'Test', status: 'queued', estimate: 8000 },
  { id: 'deploy', name: 'Deploy', status: 'queued', estimate: 5000 },
]

export default function StageRailDemo() {
  const [stages, setStages] = useState(fresh)
  // Each stage passes when its usual time runs out, and hands over to the next.
  useEffect(() => {
    const timer = setInterval(() => {
      setStages((list) => {
        const index = list.findIndex((s) => s.status === 'running')
        const stage = list[index]
        if (!stage || Date.now() - (stage.startedAt ?? 0) < (stage.estimate ?? 0)) return list
        return list.map((s, i) =>
          i === index ? { ...s, status: 'passed', duration: Date.now() - (s.startedAt ?? 0) } : i === index + 1 ? { ...s, status: 'running', startedAt: Date.now() } : s,
        )
      })
    }, 250)
    return () => clearInterval(timer)
  }, [])
  const done = stages.every((s) => s.status === 'passed')
  return (
    <div className="flex w-full max-w-xl flex-col items-start gap-4">
      <StageRail stages={stages} />
      <Button size="sm" variant="secondary" disabled={!done} onClick={() => setStages(fresh())}>
        Run again
      </Button>
    </div>
  )
}
```

A build, test and deploy pipeline whose stages pass in turn, with a button to run it again.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stage-rail
```

It brings `sliding-indicator`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-labels-stage-rail`, `youj-presets`, `youj-ui-core` with it.

Use a stage rail for work that moves through ordered stages: build, test and deploy in CI, the steps of a migration, the phases of a rollout. Each stage is a key in a recessed track holding its name, its duration (ticking in mono while it runs), a run of cells that fill as it progresses and its state: queued, running, passed, failed or skipped. The cells of every stage share one line, so the run reads as a single bar: ink where work is done, the accent where it's under way, the danger tone where it broke, hatched where a stage was skipped. Picking a stage raises its key, so the rail can drive whatever sits below it, such as that stage's log. For steps a person works through, use a [Stepper](https://www.youj.dev/docs/components/stepper).

```tsx
import { useState } from 'react'
import { StageRail } from '@youj/react'

export function Pipeline() {
  const [stage, setStage] = useState('test')
  const testStartedAt = Date.now() - 20_000
  return (
    <StageRail
      stages={[
        { id: 'build', name: 'Build', status: 'passed', duration: 72_000 },
        { id: 'test', name: 'Test', status: 'running', startedAt: testStartedAt, estimate: 64_000 },
        { id: 'deploy', name: 'Deploy', status: 'queued' },
      ]}
      value={stage}
      onValueChange={setStage}
    />
  )
}
```

Times are in milliseconds. A running stage ticks from its `startedAt` and fills toward its `estimate` (what it usually takes), stopping short of full until it passes; pass `progress` (0–1) instead when you know it. A finished stage shows its `duration`, and a failed one fills to its `progress`, where it broke. Without `value`, the rail picks the running stage, else the first that failed, else the last to have run.

The rail is one toggle group with a stage always picked. Pass the id of the panel it drives as `controls`, and it sets `aria-controls` on every stage:

```tsx
<StageRail stages={stages} value={picked} onValueChange={setPicked} controls="stage-log" />
<div id="stage-log" role="log" aria-label={`${name} log`}>…</div>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stages` (required) | `Stage[]` |  |  |
| `value` | `string` |  | The selected stage's id (controlled). |
| `defaultValue` | `string` |  | The stage selected at first. Default: the running stage, else the first failed, else the last. |
| `onValueChange` | `(id: string) => void` |  |  |
| `segments` | `number` | `12` | Cells per stage. |
| `label` | `string` |  | Names the rail. Default: the labels' "Pipeline stages". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `controls` | `string` |  | The id of the panel the selection drives (a log), for `aria-controls`. |
| `sound` | `boolean` | `true` | With sound on, picking a stage plays `select`. |

Also takes the props of `ToggleGroupPrimitive.Props`.

### Styling

Parts: `stage-rail`, `stage-rail-stage` (with `data-status`), `stage-rail-header`, `stage-rail-dot`, `stage-rail-label`, `stage-rail-track`, `stage-rail-cell` (with `data-state` `on` or `off`), `stage-rail-footer`, `stage-rail-status`, `stage-rail-value` and `stage-rail-indicator`. Units in the duration carry `data-part="unit"`. The names take the theme's label voice; in [Bezel](https://www.youj.dev/docs/looks) the track is a recessed well, the picked stage a lit key and the figures mono.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate` | 560ms | the cells light from the start of the rail, one after another, the whole rail spanning the deliberate token |
| Stage change | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the stage’s cells take their new tone in order from its own start, so a stage that finishes washes into ink |
| Running | `duration.deliberate` | 560ms | the next cell breathes and the dot throws a ring, looping until the stage finishes |
| Pick | `spring.smooth` | 0.36s, bounce 0 | the raised key glides to the stage (SlidingIndicator) |

**Reduced motion:** Cells change in place, nothing breathes and the key jumps. Durations still tick: they're information, not motion.

#### Reduced motion

The cells change in place with no stagger, the running cell and dot hold still, and the key jumps to the picked stage.

### Accessibility

- It's a toggle group named by `label` (default "Pipeline stages"): one tab stop, arrow keys move between stages (mirrored in RTL), Home and End jump, and Enter or Space picks. The picked stage has `aria-pressed="true"`; pressing it again keeps it picked.
- Each stage is named with its state and duration: "Test, Running, 42 seconds". The cells are hidden from assistive tech.
- A stage that changes state is announced politely: "Test, Passed".
- The state is always a word as well as a color and a dot shape.

---

# Severity Timeline

> Trace an incident’s events, durations and resolution milestones.

Source: https://www.youj.dev/docs/components/severity-timeline

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, SeverityTimeline, type SeverityEvent } from '@youj/react'

const MIN = 60_000

function incident(start: number): SeverityEvent[] {
  return [
    { id: 'alert', at: start, severity: 2, title: 'Error rate above 5% on checkout-api', detail: '5xx at 7.4% over 5 min', actor: 'pagerbot', ongoing: true },
    { id: 'page', at: start + MIN, title: 'Paged the payments on-call', actor: 'pagerbot' },
    { id: 'ack', at: start + 3 * MIN, milestone: 'acknowledged', title: 'M. Oyelaran took command', actor: 'm.oyelaran' },
    { id: 'sev1', at: start + 6 * MIN, severity: 1, title: 'Card payments failing in eu-west', actor: 'pagerbot', duration: 9 * MIN },
    { id: 'rollback', at: start + 9 * MIN, severity: 3, title: 'Rolled back checkout-api to v2.14.3', actor: 'deploybot', duration: 4 * MIN },
    { id: 'mitigated', at: start + 15 * MIN, milestone: 'mitigated', title: 'Authorisations recovering', actor: 'm.oyelaran' },
  ]
}

export default function SeverityTimelineDemo() {
  const [events, setEvents] = useState(() => incident(Date.now() - 18 * MIN))
  const resolved = events.some((e) => e.milestone === 'resolved')
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <SeverityTimeline events={events} />
      <div className="flex gap-2">
        <Button
          size="sm"
          variant="secondary"
          disabled={resolved}
          onClick={() => setEvents((list) => [...list, { id: `e${list.length}`, at: Date.now(), severity: 3, title: 'Scaled payments-worker to 12 replicas', actor: 'autoscaler', duration: 2 * MIN }])}
        >
          Add an event
        </Button>
        <Button
          size="sm"
          disabled={resolved}
          onClick={() => setEvents((list) => [...list, { id: 'resolved', at: Date.now(), milestone: 'resolved', title: 'Error rate under 0.5% for 10 min', actor: 'm.oyelaran' }])}
        >
          Resolve
        </Button>
      </div>
    </div>
  )
}
```

An incident that began 18 minutes ago, with buttons to add an event or resolve it.

While no event is the `resolved` milestone (and you pass no `end`), the incident is open: the ribbon's window runs from the first event to now, growing in whole steps (5, 15, 30 minutes and up) so the scale holds still between them, and a solid edge marks now. Ongoing durations tick every second. Once an event resolves it, the window closes at that moment, ongoing bars stop there and the clock stops. Pass `now` to pin the time (for a replay or a test) and `start` when the incident began before its first event.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add severity-timeline
```

It brings `presence-list`, `use-now`, `youj-core`, `youj-labels-severity-timeline`, `youj-presets`, `youj-ui-core` with it.

Use a severity timeline for the story of one incident: the alerts that fired, the pages, the deploys and rollbacks, and the moments it was acknowledged, mitigated and resolved. Every row has its clock time and how long after the start it came, a node on a rail, a soft SEV chip and the title. Beside it runs the ribbon, a thin track spanning the whole incident on every row, with the event's own bar at its offset and length and each milestone as a dashed rule on every row, so the phases line up down the list and you can see at a glance what was still firing when someone took command. For a project's general activity feed, use a [Timeline](https://www.youj.dev/docs/components/timeline).

```tsx
import { SeverityTimeline, type SeverityEvent } from '@youj/react'

const events: SeverityEvent[] = [
  { id: 'alert', at: start, severity: 2, title: 'Error rate above 5% on checkout-api', actor: 'pagerbot', ongoing: true },
  { id: 'ack', at: start + 3 * 60_000, milestone: 'acknowledged', title: 'M. Oyelaran took command' },
  { id: 'rollback', at: start + 11 * 60_000, severity: 3, title: 'Rolled back to v2.14.3', duration: 4 * 60_000 },
  { id: 'mitigated', at: start + 16 * 60_000, milestone: 'mitigated', title: 'Authorisations recovering' },
]

<SeverityTimeline events={events} timeZone="UTC" />
```

Pass events in any order: they're shown oldest first. `at` is a time in ms. An event with `duration` draws a bar, one with `ongoing` runs to now (or to the resolution), and one with neither draws a tick. `severity` (1 is the worst) draws the SEV chip and tones the node and the bar: SEV1 in danger, SEV2 in warning, SEV3 in the accent and SEV4 neutral. An event without a severity can take a `tone` instead (a chart color for its kind, as the [Threat case](https://www.youj.dev/docs/blocks/trends-and-comparisons) card colors each step of an attack chain); without either it is neutral.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` (required) | `readonly SeverityEvent[]` |  |  |
| `start` | `number` |  | When the incident began, in ms. Default: the first event. |
| `end` | `number` |  | When it ended, in ms. Default: the resolved milestone, else it's open and runs to now. |
| `now` | `number` |  | The current time, in ms. Default: a live clock (every second while the incident is open). |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `timeZone` | `string` |  | Clock times in this zone, e.g. "UTC". Default: the browser's. |
| `label` | `string` |  | The list's accessible name. Default: the labels' "Incident timeline". |
| `formatTime` | `(ms: number) => string` |  | Formats clock times. Default: 24-hour HH:mm in the locale. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `severity-timeline`, `severity-timeline-axis`, `severity-timeline-list`, `severity-timeline-event`, `severity-timeline-time`, `severity-timeline-node`, `severity-timeline-body`, `severity-timeline-severity`, `severity-timeline-label` (a milestone's word, in the theme's label voice), `severity-timeline-title`, `severity-timeline-detail`, `severity-timeline-actor`, `severity-timeline-value` (the since-start and duration figures), `severity-timeline-ribbon`, `severity-timeline-bar`, `severity-timeline-rule`, `severity-timeline-now` and `severity-timeline-empty`. The root has `data-state` (`open` or `closed`); each event has `data-severity`, `data-milestone` and `data-ongoing`. Under 34rem of its own width (a container query) the ribbon drops under each row.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Event arrives | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | the row takes its slot and fades down while the rows below glide (PresenceList) |
| Node | `spring.snappy` | 0.2s, bounce 0 | a new event’s dot or diamond lands, with no overshoot |
| Bar | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | grows from its start edge; bars and rules move when the window re-ranges (clip-path and translate only) |
| Live end | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | an ongoing bar’s end breathes while the incident is open |

**Reduced motion:** Rows, nodes and bars appear in place, the window re-ranges at once and the live end holds still.

#### Reduced motion

Everything is drawn in place: new rows appear without a fade or a glide, bars take their length at once and the live end holds still.

### Accessibility

- It's an ordered list (`ol`) named by `label` (default "Incident timeline"), oldest first.
- Each row reads in order: its time (a `time` element), its severity spoken in full ("Severity 2", the chip's SEV2 is hidden), the title, the detail, how long it lasted ("12 minutes, Ongoing") and how long after the start it came ("6 minutes after start").
- The ribbon, the nodes and the rail are hidden from assistive tech: the text carries what they show.
- Ticking durations aren't announced. Announce new events from your app where it matters, as the incident block does.

---

# Milestone Ruler

> Put a year of milestones on a ruler of fine ticks, with today marked and a callout for the one you point at.

Source: https://www.youj.dev/docs/components/milestone-ruler

## Examples

### Demo

```tsx
'use client'

import { MilestoneRuler, type Milestone } from '@youj/react'

/** A made-up app's year: two big releases, a few features, one at risk and two a day apart. */
const MILESTONES: Milestone[] = [
  { id: 'offline', date: '2026-02-09', title: 'Offline mode', description: 'Edits sync when you reconnect' },
  { id: 'folders', date: '2026-04-01', title: 'Shared folders', description: 'Invite a team to a folder' },
  { id: 'v1-5', date: '2026-06-04', title: 'Version 1.5', description: 'New editor, faster search', major: true },
  { id: 'mobile', date: '2026-08-31', title: 'Mobile beta' },
  { id: 'api', date: '2026-09-02', title: 'Public API' },
  { id: 'sso', date: '2026-10-28', title: 'SSO and audit log', description: 'Waiting on the security review', status: 'at-risk' },
  { id: 'v2', date: '2026-11-26', title: 'Version 2', description: 'Rebuilt sync engine', major: true },
]

export default function MilestoneRulerDemo() {
  return (
    <div className="w-full max-w-md">
      <MilestoneRuler milestones={MILESTONES} today="2026-10-13" label="Milestones in 2026" />
    </div>
  )
}
```

A made-up app's 2026, seen on 13 October. Shipped milestones are solid, upcoming ones hollow and the one at risk amber; the two that land a day apart share a pin with their count. Hover anywhere along the ruler and the nearest pin answers.

### A quarter, controlled

```tsx
'use client'

import { useState } from 'react'
import { MilestoneRuler, type Milestone } from '@youj/react'

/** One quarter of a launch plan, on the success tone. */
const MILESTONES: Milestone[] = [
  { id: 'design', date: '2026-10-09', title: 'Design review', description: 'Flows signed off' },
  { id: 'build', date: '2026-11-02', title: 'Feature complete', description: 'Code freeze on main', major: true },
  { id: 'qa', date: '2026-11-20', title: 'QA sign-off' },
  { id: 'ship', date: '2026-12-08', title: 'Ship', description: 'To every workspace', major: true },
]

export default function MilestoneRulerQuarter() {
  const [picked, setPicked] = useState<string | null>('build')
  const milestone = MILESTONES.find((m) => m.id === picked)
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <MilestoneRuler
        milestones={MILESTONES}
        start="2026-10-01"
        end="2026-12-31"
        today="2026-10-20"
        tone="success"
        value={picked}
        onValueChange={setPicked}
        label="Q4 launch plan"
      />
      <p className="text-ui text-fg-muted">
        Picked: <span className="text-fg">{milestone?.title ?? 'nothing'}</span>
      </p>
    </div>
  )
}
```

`start` and `end` set any span of days (here one quarter, each month still cut in four), `tone` colors the pins, and `value` with `onValueChange` lets your app own which milestone is picked.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add milestone-ruler
```

It brings `use-controllable-state`, `use-now`, `use-resize-measure`, `youj-core`, `youj-labels-milestone-ruler`, `youj-presets`, `youj-ui-core` with it.

Use a milestone ruler for when things land across a long span: a product's year of releases, a quarter's launch plan, a grant's reporting dates. It answers "what's next, what slipped, how far along are we" at a glance and keeps one line of detail a hover away. For the order of steps in one flow use a [Stage Rail](https://www.youj.dev/docs/components/stage-rail); for events and durations within one incident, a [Severity Timeline](https://www.youj.dev/docs/components/severity-timeline). The [Roadmap timeline](https://www.youj.dev/docs/blocks/timelines-and-steps#roadmap-timeline) card is built on it.

```tsx
import { MilestoneRuler, type Milestone } from '@youj/react'

const milestones: Milestone[] = [
  { id: 'v1-5', date: '2026-06-04', title: 'Version 1.5', description: 'New editor', major: true },
  { id: 'sso', date: '2026-10-28', title: 'SSO and audit log', status: 'at-risk' },
  { id: 'v2', date: '2026-11-26', title: 'Version 2', description: 'Rebuilt sync engine', major: true },
]

<MilestoneRuler milestones={milestones} today={today} label="Roadmap 2026" />
```

A milestone's `date` is a day: a date-only string such as `"2026-11-26"` is that calendar day in every time zone, and a `Date` or a time in ms counts by its local date. Without `start` and `end` the ruler spans January 1 to December 31 of today's year. `status` is `done`, `upcoming` or `at-risk`; left out, it is done before `today` and upcoming from it on. Pass `today` from your server so the page hydrates with the same marks; without it the ruler waits for the browser's clock. `major` draws a taller pin.

Milestones closer than about ten pixels share one pin with their count, so the grouping follows the space the ruler has. A picked milestone (`value`, or the next one from today by default) keeps its callout shown; hovering or focusing another shows that one until the pointer or focus leaves. `formatDate` writes the days your way.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `milestones` (required) | `readonly Milestone[]` |  |  |
| `start` | `MilestoneDate` |  | The ruler's first day. Default: January 1 of today's year (or of the first milestone's). |
| `end` | `MilestoneDate` |  | The ruler's last day. Default: December 31 of the start's year. |
| `today` | `MilestoneDate` |  | Marked on the ruler, and splits done from upcoming. Default: the browser's clock once mounted (none on the server). |
| `value` | `string \| null` |  | The selected milestone's id, shown when nothing is hovered or focused (controlled); `null` for none. |
| `defaultValue` | `string \| null` |  | Default: the next milestone from today, else the last one. |
| `onValueChange` | `(id: string \| null) => void` |  |  |
| `tone` | `'accent' \| 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'accent'` | The pins' color. At-risk milestones take the warning tone. |
| `formatDate` | `(date: Date) => string` |  | Formats a day in the callout and the spoken names. Default: the locale's short month and day. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` |  | Accessible name. Default: the labels' "Milestones". |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `milestone-ruler`, `milestone-ruler-callout-zone`, `milestone-ruler-callout`, `milestone-ruler-caret`, `milestone-ruler-plot`, `milestone-ruler-ticks`, `milestone-ruler-tick`, `milestone-ruler-today`, `milestone-ruler-pins`, `milestone-ruler-pin`, `milestone-ruler-dot`, `milestone-ruler-count`, `milestone-ruler-axis`, `milestone-ruler-month` and `milestone-ruler-empty`. A pin has `data-status` (`done`, `upcoming` or `at-risk`), `data-yj-major`, `data-yj-shown` while its callout is up and `data-yj-count` when it holds several milestones; a tick has `data-yj-major` at a month's start. The pins' color is `--milestone-ruler-tone`, and the count's ink `--milestone-ruler-ink`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Rise | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | the pins grow up from the ruler left to right when a third of it scrolls into view |
| Callout | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the callout glides to the pin under the pointer or focus, its caret staying on the pin |
| Stretch | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the ticks within about 40px of the pointer stretch toward it, most at the pointer |

**Reduced motion:** Drawn in place: the pins stand, the callout jumps and the ticks don't stretch.

#### Reduced motion

The pins are drawn standing, the callout moves at once and the ticks keep their length.

### Accessibility

- A horizontal `listbox` (your `label`, or the labels' "Milestones") described by a summary: how many milestones, and how many are done.
- Every pin is an `option` named with its title, day and status ("SSO and audit log, Oct 28, At risk"), and described by its one-line description; a shared pin names each of its milestones. The picked one is `aria-selected`.
- One tab stop. Left and Right walk the pins (mirrored in RTL), Home and End go to the ends, and selection follows focus. A click or tap anywhere on the ruler picks the nearest pin.
- The callout, ticks, today mark and month names are decorative; the options say the same in words. Status is a word and a solid, hollow or warning-toned dot, never color alone.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Rollout Ruler

> Set a feature’s rollout stage and show when a kill switch rolls it back.

Source: https://www.youj.dev/docs/components/rollout-ruler

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, RolloutRuler } from '@youj/react'

export default function RolloutRulerDemo() {
  const [value, setValue] = useState(10)
  // What the kill switch rolled back from, so Restore can put it back.
  const [killed, setKilled] = useState<number | null>(null)
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <RolloutRuler
        label="Rolled out to"
        value={value}
        tone={killed !== null ? 'danger' : 'accent'}
        onValueChange={(next) => {
          setValue(next)
          setKilled(null)
        }}
      />
      <Button
        variant={killed !== null ? 'secondary' : 'danger'}
        className="self-start"
        disabled={killed === null && value === 0}
        onClick={() => {
          if (killed !== null) {
            setValue(killed)
            setKilled(null)
          } else {
            setKilled(value)
            setValue(0)
          }
        }}
      >
        {killed !== null ? `Restore ${killed}%` : 'Kill switch'}
      </Button>
    </div>
  )
}
```

A ruler at 10% with a kill switch that rolls it back to 0, and a button that restores it.

### Meters

```tsx
'use client'

import { RolloutRuler } from '@youj/react'

const FLAGS = [
  { key: 'checkout-v2', share: 10 },
  { key: 'semantic-search', share: 50 },
  { key: 'inbox-summaries', share: 5 },
  { key: 'edge-cache', share: 100 },
]

export default function RolloutRulerMeters() {
  return (
    <ul className="flex w-full max-w-lg flex-col gap-3">
      {FLAGS.map((flag) => (
        <li key={flag.key} className="grid grid-cols-[9rem_minmax(0,1fr)_3rem] items-center gap-4 font-mono text-ui">
          <span className="truncate">{flag.key}</span>
          <RolloutRuler readOnly size="sm" value={flag.share} label={flag.key} />
          <span className="text-end tabular-nums">{flag.share}%</span>
        </li>
      ))}
    </ul>
  )
}
```

Four flags as small read-only rulers, one per row.

`readOnly` makes it a meter with no playhead, and `size="sm"` is the bare track for a list row, one per flag.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add rollout-ruler
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-rollout-ruler`, `youj-presets`, `youj-ui-core` with it.

Use a rollout ruler to show and set how far a feature has rolled out: internal, beta, 10%, 50%, GA. The track is cut into its stages, each an equal stretch, so the early cohorts get as much room as the late ones; the axis under it says what each gate is worth. For a free percentage, use a [Slider](https://www.youj.dev/docs/components/slider).

```tsx
import { RolloutRuler } from '@youj/react'

const [share, setShare] = useState(10)

<RolloutRuler label="Rolled out to" value={share} onValueChange={setShare} />
```

`value` is the share of users, 0–100, and while it's interactive it's always a stage's value (or 0). The default stages are Internal 1%, Beta 5%, 10%, 50% and GA 100%; pass `stages` for your own, in any order:

```tsx
<RolloutRuler
  stages={[
    { value: 0.5, label: 'Canary' },
    { value: 2, label: 'Staff' },
    { value: 25, label: '25%' },
    { value: 100, label: 'All' },
  ]}
/>
```

Ticks already rolled out light in `tone` (the accent), the stretch to the next gate is a runway at a third of it, and the gate the value sits on names itself in the tone. A kill switch is a change from outside: set `value` to 0 (with `tone="danger"`) and the ruler sweeps back tick by tick.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | The share rolled out, 0–100. Interactive, it's always a stage's value (or 0). |
| `defaultValue` | `number` | `0` |  |
| `onValueChange` | `(value: number) => void` |  |  |
| `onValueCommitted` | `(value: number) => void` |  | Called once a drag or key press ends, with the final value. |
| `stages` | `readonly RolloutStage[]` |  | The gates, in any order. Default: Internal 1%, Beta 5%, 10%, 50% and GA 100%. |
| `readOnly` | `boolean` | `false` | A meter to read, without a playhead to move. |
| `disabled` | `boolean` | `false` |  |
| `size` | `'default' \| 'sm'` | `'default'` | `sm`: the bare track, no header, names or axis, for a list row. |
| `tone` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'accent'` | The lit ticks. |
| `label` | `string` |  | The visible name over the track, and its accessible name. Default: the labels' "Rollout". |
| `ticks` | `number` |  | Minor intervals per stage. Default 10, or 5 at `sm`. |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| A step you take | `spring.snappy` | 0.2s, bounce 0 | drag, a press on the ruler or a key: the playhead snaps to the gate |
| A change from outside | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1) | a kill switch or a schedule: the ticks light or go dark one after another at a constant rate, the playhead riding the front |
| Reveal | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1) | it sweeps up from zero as it scrolls into view |

**Reduced motion:** Drawn at its value; changes jump.

#### Reduced motion

The ruler is drawn at its value, and changes jump without the sweep.

### Accessibility

- Interactive, it's a slider over the stages, named by `label` (or the labels' "Rollout"). Its value is spoken with the stage's name: "Beta at 5%", "50%", "Off".
- The arrow keys and Page keys step one gate; Home and End go to off and the last stage. A press anywhere on the ruler moves to the nearest gate.
- `readOnly` and `size="sm"` are meters with the same spoken value.
- Its built-in text (the default stage names, "Off") comes from the labels, so `<YoujProvider labels>` translates it.

---

# Level Matrix

> Set a level for each row and column pair, with pending changes and bulk editing, such as access by role and resource.

Source: https://www.youj.dev/docs/components/level-matrix

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, diffPermissions, LevelMatrix, type PermissionResource, type PermissionRole, type PermissionValue } from '@youj/react'

const ROLES: PermissionRole[] = [
  { id: 'owner', name: 'Owner', detail: '1 member', locked: true },
  { id: 'editor', name: 'Editor', detail: '8 members' },
  { id: 'viewer', name: 'Viewer', detail: '23 members' },
]
const RESOURCES: PermissionResource[] = [
  { id: 'docs', name: 'Docs' },
  { id: 'billing', name: 'Billing' },
  { id: 'members', name: 'Members' },
  { id: 'api', name: 'API keys' },
]
const SAVED: PermissionValue = {
  owner: { docs: 'admin', billing: 'admin', members: 'admin', api: 'admin' },
  editor: { docs: 'write', billing: 'read', members: 'read', api: 'none' },
  viewer: { docs: 'read', billing: 'none', members: 'none', api: 'none' },
}

export default function LevelMatrixDemo() {
  const [saved, setSaved] = useState(SAVED)
  const [value, setValue] = useState(SAVED)
  const changes = diffPermissions(saved, value, ROLES, RESOURCES)
  return (
    <div className="flex w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-line bg-surface">
      <LevelMatrix label="Workspace permissions" roles={ROLES} resources={RESOURCES} value={value} baseline={saved} onValueChange={setValue} />
      <div className="flex items-center justify-between gap-3 px-5 py-3">
        <span className="font-mono text-ui-sm text-fg-muted">{changes.length ? `${changes.length} pending` : 'Up to date'}</span>
        <Button size="sm" disabled={!changes.length} onClick={() => setSaved(value)}>
          Apply
        </Button>
      </div>
    </div>
  )
}
```

Three roles across four resources, with an Apply button that counts the pending changes.

Against `baseline` (by default, the value it opened with), a changed cell keeps the level it had in view, struck through, and draws the difference in its segments: gained segments light in the success tone, lost ones stay as a hollow danger outline. `diffPermissions(baseline, value, roles, resources)` lists the changes in grid order, for a summary or a review before you save.

```tsx
const changes = diffPermissions(saved, value, roles, resources)
// [{ role, resource, from: 'read', to: 'write' }, …]
```

A row header's box selects the role's cells, a column header's box selects the resource for every role, and the corner selects everything. The bar that opens sets every selected cell to one level.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add level-matrix
```

It brings `button`, `checkbox`, `collapse`, `icon-lock`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-level-matrix`, `youj-presets`, `youj-ui-core` with it.

The copy is 19 registry items, about 8,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `checkbox`, `collapse`, `field`, `icon-engine`, `icon-loader-ring`, `icon-lock`, `label`, `separator`, `spinner` and 2 more.

Use a level matrix when access is decided per role and per resource: who can read billing, who can deploy, who can manage members. Each cell is an access level (none, read, write, admin) drawn as three segments lit to it, so a column or a row reads at a glance. For one person's settings, a list of switches reads better.

```tsx
import { LevelMatrix, type PermissionValue } from '@youj/react'

const [value, setValue] = useState<PermissionValue>(saved)

<LevelMatrix
  label="Workspace permissions"
  roles={[
    { id: 'owner', name: 'Owner', locked: true },
    { id: 'editor', name: 'Editor', detail: '8 members' },
  ]}
  resources={[
    { id: 'docs', name: 'Docs' },
    { id: 'billing', name: 'Billing' },
  ]}
  value={value}
  baseline={saved}
  onValueChange={setValue}
/>
```

A value maps a role's id to its levels by resource id; a missing cell is `none`. A `locked` role (an owner) can't change and sits out of bulk selection.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `roles` (required) | `readonly PermissionRole[]` |  |  |
| `resources` (required) | `readonly PermissionResource[]` |  |  |
| `value` | `PermissionValue` |  |  |
| `defaultValue` | `PermissionValue` | `{}` |  |
| `onValueChange` | `(value: PermissionValue) => void` |  |  |
| `baseline` | `PermissionValue` |  | The saved levels: cells that differ from it show their pending gain or loss. Default: the value it opened with. |
| `label` | `string` |  | Accessible name of the grid. Default: the labels' "Permissions". |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| A cell changes | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | its segments light or empty one after another |
| A bulk set | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the same, as a wave across the grid from the top-start corner |
| The bulk bar | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | opens and closes with the selection |

**Reduced motion:** Levels change in place.

#### Reduced motion

Levels change in place, without the segment stagger or the wave.

### Accessibility

- It's an ARIA grid, named by `label` (or the labels' "Permissions") and multiselectable, with column and row headers and a keyboard hint as its description.
- One tab stop, then the arrow keys move between cells, the header boxes included; Home and End go to a row's ends, and Ctrl+Home and Ctrl+End to the grid's. Space or Enter steps a cell up a level, and Shift steps it down.
- Every change is announced: "Editor, Billing: Write", or "6 permissions set to Read". A pending cell adds "changed from Read" to its name, selected cells are `aria-selected`, and a locked role's cells are read-only.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Progress Path

> Show progress through ordered sections of items, with mastery and section milestones, such as a course.

Source: https://www.youj.dev/docs/components/progress-path

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ProgressPath, type ProgressPathSection } from '@youj/react'

const SECTIONS: ProgressPathSection[] = [
  {
    id: 'basics',
    eyebrow: 'Section 1',
    title: 'Basics',
    lessons: [
      { id: 'greetings', title: 'Greetings', detail: '6 min', mastery: 4 },
      { id: 'numbers', title: 'Numbers', detail: '7 min', mastery: 3 },
      { id: 'family', title: 'Family', detail: '9 min', mastery: 1 },
      { id: 'basics-check', title: 'Basics checkpoint', detail: '+50 XP', milestone: true },
    ],
  },
  {
    id: 'cafe',
    eyebrow: 'Section 2',
    title: 'Café & food',
    lessons: [
      { id: 'coffee', title: 'Ordering coffee', detail: '8 min' },
      { id: 'market', title: 'At the market', detail: '10 min' },
      { id: 'cafe-check', title: 'Café checkpoint', detail: '+50 XP', milestone: true },
    ],
  },
]

const ORDER = SECTIONS.flatMap((s) => s.lessons.map((l) => l.id))

export default function ProgressPathDemo() {
  // Finish lesson moves `current` on: the next segment draws and the Start callout glides after it.
  const [at, setAt] = useState(2)
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <div className="rounded-2xl border border-line bg-surface px-6 py-2">
        <ProgressPath sections={SECTIONS} current={ORDER[at] ?? null} />
      </div>
      <div className="flex justify-end gap-2">
        <Button variant="secondary" onClick={() => setAt(2)}>
          Reset
        </Button>
        <Button onClick={() => setAt((i) => Math.min(ORDER.length, i + 1))}>Finish lesson</Button>
      </div>
    </div>
  )
}
```

Two sections of lessons with a checkpoint each, where Finish lesson moves the current lesson on.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add progress-path
```

It brings `icon-check`, `icon-crown`, `icon-lock`, `icon-star`, `icon-trophy`, `share-bar`, `use-resize-measure`, `youj-core`, `youj-labels-progress-path`, `youj-presets`, `youj-ui-core` with it.

Use a progress path for anything learned in order: a language course, an onboarding program, a training plan. Lessons are nodes on a trail that swings across the column, grouped into sections that each take a chart color and close on a trophy milestone. Each node wears a segmented ring, one segment per level of mastery. Lessons before the current one are done, the current one is an ink disc glowing in its section's color with a Start callout beside it, and the rest are locked. The trail is solid behind you and dotted ahead. For steps of a form, use a [Stepper](https://www.youj.dev/docs/components/stepper); for a pipeline's stages, a [Stage Rail](https://www.youj.dev/docs/components/stage-rail).

```tsx
import { ProgressPath, type ProgressPathSection } from '@youj/react'

const sections: ProgressPathSection[] = [
  {
    id: 'basics',
    eyebrow: 'Section 1',
    title: 'Basics',
    lessons: [
      { id: 'greetings', title: 'Greetings', detail: '6 min', mastery: 4 },
      { id: 'numbers', title: 'Numbers', detail: '7 min', mastery: 1 },
      { id: 'basics-check', title: 'Basics checkpoint', milestone: true },
    ],
  },
]

<ProgressPath sections={sections} current="numbers" onSelect={(lesson) => open(lesson.id)} />
```

`current` is the lesson up next: those before it are done and those after it locked; `null` means the course is finished. Leave it out and the first lesson not fully mastered is up next. `mastery` counts the levels a lesson has mastered, out of `levels` (4 by default), and a done lesson at full mastery wears a crown. `detail` adds a mono line beside a lesson's title, and `milestone` draws a lesson as a trophy that closes its section. Sections take the chart colors in turn, or their own `tone`.

The trail swings wider as the column grows, and lesson titles sit beside their nodes once it's at least 32rem wide; narrower, the nodes carry the path alone. `onSelect` opens a lesson that's done or current. A locked one shakes its head and plays the error cue.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sections` (required) | `ProgressPathSection[]` |  |  |
| `current` | `string \| null` |  | The lesson up next: those before it are done and those after it locked. `null` when the course is finished. Default: the first lesson not fully mastered. |
| `levels` | `number` | `4` | Levels of mastery per lesson, one ring segment each. |
| `onSelect` | `(lesson: ProgressPathLesson, section: ProgressPathSection) => void` |  | Called when a lesson that isn't locked is opened. |
| `label` | `string` |  | Accessible name. Default: the labels' "Progress path". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | Plays the success cue when the current lesson moves on. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `progress-path`, `progress-path-trail`, `progress-path-walked` (with `data-walked`), `progress-path-section`, `progress-path-head`, `progress-path-eyebrow`, `progress-path-title`, `progress-path-value`, `progress-path-node` (with `data-state` and `data-milestone`), `progress-path-glow`, `progress-path-ring`, `progress-path-level` (with `data-state`), `progress-path-disc`, `progress-path-label` (with `data-side`) and `progress-path-callout`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the walked trail draws itself, segment by segment |
| Current moves on | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the next segment draws and the Start callout glides after it |
| Current lesson | `duration.deliberate`, `ease.exit` | 560ms; cubic-bezier(0.4, 0, 1, 1) | a slow ping from its glow while the path is on screen |
| Locked lesson pressed | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the node shakes its head |

**Reduced motion:** The trail is drawn in place, the callout jumps, and there's no ping or shake.

#### Reduced motion

The trail is drawn in place, the callout jumps to the next lesson, and the current lesson glows without pinging.

### Accessibility

- The path is a group named by `label` (default: the labels' "Progress path") and described by how to move through it; each section is named by its title.
- Each lesson is a button named by its title, its place in the course, its status and its mastery ("Numbers, lesson 2 of 3, up next, mastery 1 of 4"). The current one has `aria-current="step"`, and locked ones are `aria-disabled`.
- The lessons are one tab stop, starting on the current lesson. Up and down walk the path, left and right do too (mirrored in RTL), and Home and End jump to its ends.
- A section's progress is spoken with its count ("1 of 3 lessons").
- Its words come from the labels (`progressPath`, `progressPathHint`, `lessonItem`, `milestoneItem`, `lessonDone`, `lessonCurrent`, `lessonLocked`, `lessonStart`, `sectionProgress`), translated by the language packs.

---

# Progress List

> List items with progress, speed, time remaining and controls for each, such as file transfers.

Source: https://www.youj.dev/docs/components/progress-list

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ProgressList, TransferSummary, type TransferItem } from '@youj/react'

const MB = 1_000_000

const FILES: TransferItem[] = [
  { id: 'film', name: 'launch-film-master.mov', size: 2310 * MB, transferred: 1402 * MB, rate: 18.9 * MB, status: 'active' },
  { id: 'still', name: 'hero-still-04.png', size: 14.6 * MB, transferred: 9.4 * MB, rate: 2.9 * MB, status: 'active' },
  { id: 'traces', name: 'eval-traces-0926.jsonl', size: 386 * MB, transferred: 243 * MB, status: 'failed', error: 'Connection reset at 63%' },
  { id: 'brand', name: 'brand-guidelines.key', size: 212 * MB, transferred: 81 * MB, status: 'paused' },
  { id: 'deck', name: 'q4-planning-deck.pdf', size: 38.2 * MB, transferred: 0, status: 'queued' },
  { id: 'review', name: 'q3-board-review.pdf', size: 48.2 * MB, transferred: 48.2 * MB, status: 'done' },
]

export default function ProgressListDemo() {
  const [items, setItems] = useState(FILES)

// Your uploader's state goes here; this moves the active files every half second.
  useEffect(() => {
    const id = setInterval(
      () =>
        setItems((list) =>
          list.map((f) => {
            if (f.status !== 'active') return f
            const transferred = Math.min(f.size, f.transferred + (f.rate ?? 4 * MB) / 2)
            return transferred >= f.size ? { ...f, transferred, rate: undefined, status: 'done' } : { ...f, transferred }
          }),
        ),
      500,
    )
    return () => clearInterval(id)
  }, [])

const set = (id: string, change: Partial<TransferItem>) => setItems((list) => list.map((f) => (f.id === id ? { ...f, ...change } : f)))

return (
    <div className="flex w-full max-w-xl flex-col gap-6 rounded-2xl border border-line bg-surface p-5">
      <TransferSummary items={items} />
      <ProgressList
        items={items}
        max={4}
        onPause={(id) => set(id, { status: 'paused', rate: undefined })}
        onResume={(id) => set(id, { status: 'active', rate: 6 * MB })}
        onRetry={(id) => set(id, { status: 'active', rate: 8 * MB, error: undefined })}
        onCancel={(id) => setItems((list) => list.filter((f) => f.id !== id))}
      />
    </div>
  )
}
```

Six files, one in each state, with a summary above them and pause, resume, retry and cancel handlers.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add progress-list
```

It brings `button`, `collapse`, `icon-alert-triangle`, `icon-check`, `icon-file`, `icon-file-code`, `icon-file-image`, `icon-file-text`, `icon-play`, `icon-rotate-ccw`, `icon-x`, `presence-list`, `segmented-meter`, `typography`, `use-announcer`, `youj-core`, `youj-labels-progress-list`, `youj-presets`, `youj-ui-core` with it.

The copy is 27 registry items, about 8,400 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `button`, `collapse`, `icon-alert-triangle`, `icon-check`, `icon-engine`, `icon-file`, `icon-file-code`, `icon-file-image`, `icon-file-text`, `icon-loader-ring` and 9 more.

Use a progress list wherever files move and people wait on them: uploads, downloads, syncs, exports. Each file is a row with a run of cells that lights as its bytes arrive, what has moved of its size, and while it moves, its rate and the time left. A finished row settles into a compact done row with a drawn check and sinks to the foot, so the list keeps what still needs attention at the top. For one bounded value use a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter); for a queue's load across lanes, a [Lane Meter](https://www.youj.dev/docs/components/lane-meter).

```tsx
import { ProgressList, TransferSummary, type TransferItem } from '@youj/react'

const files: TransferItem[] = [
  { id: 'film', name: 'launch-film-master.mov', size: 2_310_000_000, transferred: 1_402_000_000, rate: 18_900_000, status: 'active' },
  { id: 'traces', name: 'eval-traces.jsonl', size: 386_000_000, transferred: 243_000_000, status: 'failed', error: 'Connection reset at 63%' },
]

<TransferSummary items={files} onPauseAll={pauseAll} onResumeAll={resumeAll} onCancelAll={cancelAll} />
<ProgressList items={files} max={6} onPause={pause} onResume={resume} onCancel={cancel} onRetry={retry} />
```

An item is a file's `name`, its `size` and the bytes `transferred` so far, a `status` (`queued`, `active`, `paused`, `done` or `failed`), the `rate` in bytes a second while it's active, and an `error` for a failed one. The list is controlled: it draws what you pass and calls `onPause`, `onResume`, `onCancel` and `onRetry` with the row's `id`. Leave a callback out and its button goes with it; with none, the list is read-only.

Rows sort themselves: failed first, then moving and paused, then queued, and the done ones last. Past `max` rows (6 by default, `0` for all) the rest fold under "Show N more", which says what they hold. Sizes and rates pick the largest unit under a thousand (`48.2 MB`, `18.9 MB/s`), and bytes moved read in their size's unit, so an empty file says "0 MB of 940 MB".

`TransferSummary` is the header: the bytes moved of the whole, an overall [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter) named by how many files are done, the combined rate and the time left. Give it `onPauseAll`, `onResumeAll` and `onCancelAll` for the all-row actions.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `TransferItem[]` |  |  |
| `max` | `number` | `6` | Rows shown before the rest fold under "Show N more". |
| `segments` | `number` | `32` | Cells per row. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `label` | `string` | `"Transfers"` | The list's accessible name. |
| `format` | `TransferFormat` |  | Writes sizes and rates in your unit. Default: decimal bytes in the locale. |
| `onPause` | `(id: string) => void` |  |  |
| `onResume` | `(id: string) => void` |  |  |
| `onCancel` | `(id: string) => void` |  | Without it a row has no cancel button. |
| `onRetry` | `(id: string) => void` |  | Without it a failed row has no Retry. |

Also takes the props of `ComponentProps<'div'>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `TransferItem[]` |  |  |
| `segments` | `number` | `48` | Cells in the overall meter. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `format` | `TransferFormat` |  | Writes sizes and rates in your unit. Default: decimal bytes in the locale. |
| `onPauseAll` | `() => void` |  | With these, the summary carries Pause all / Resume all and Cancel all. |
| `onResumeAll` | `() => void` |  |  |
| `onCancelAll` | `() => void` |  |  |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `progress-list`, `progress-list-item` (with `data-status`), `progress-list-row`, `progress-list-icon`, `progress-list-body`, `progress-list-name`, `progress-list-value`, `progress-list-progress`, `progress-list-track`, `progress-list-cell` (with `data-state`), `progress-list-meta`, `progress-list-status`, `progress-list-error`, `progress-list-actions`, `progress-list-action` and `progress-list-more`; and `transfer-summary`, `transfer-summary-figure`, `transfer-summary-actions`, `transfer-summary-meter` and `transfer-summary-stat`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Bytes arrive | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | cells light one at a time; the next cell to fill breathes while the file moves |
| Done | `spring.snappy` | 0.2s, bounce 0 | the row lets go of its well and its cells fold away; the file glyph turns into a drawn check and the row glides to the foot |
| Reorder, add, remove | `spring.smooth` | 0.36s, bounce 0 | rows glide to their new places and fade in or out through PresenceList |

**Reduced motion:** Cells light at once, rows fold and move in place, the check is drawn and nothing breathes.

#### Reduced motion

Cells are lit at once, finished rows fold and move in place, the check is drawn without its stroke, and the next cell doesn't breathe.

### Accessibility

- Each unfinished row is a `progressbar` named by its file, with the percentage and state as `aria-valuetext` ("50%, 48 MB of 120 MB", "38%, Paused", or the error).
- Every button is named for its file: "Pause launch-film-master.mov", "Retry eval-traces.jsonl".
- A file that finishes or fails is announced once, in a polite live region.
- When a row's buttons leave from under focus (canceled, or finished), focus moves to the row now in its place, so it's never dropped on the page.
- "Show N more" is a button with `aria-expanded`.
- Its words come from the labels (`transfers`, `transferPause`, `transferResume`, `transferCancel`, `transferProgress`, `transferLeft`, `transferFiles`, …), translated by the language packs.

---

# Time Lanes

> Show shifts or runs in lanes across a week or a day, with overrides, proposals, handoffs and now, such as an on-call rota.

Source: https://www.youj.dev/docs/components/time-lanes

## Examples

### Demo

```tsx
'use client'

import { TimeLanes, type RotaLane, type RotaShift } from '@youj/react'

const HOUR = 3_600_000
const WEEK = new Date(2026, 8, 28).getTime()
const at = (day: number, hour: number) => WEEK + (day * 24 + hour) * HOUR

const PEOPLE: RotaLane[] = [
  { id: 'mara', name: 'Mara Quinn', detail: 'Platform' },
  { id: 'theo', name: 'Theo Park', detail: 'Platform' },
  { id: 'iris', name: 'Iris Okafor', detail: 'Data infra' },
  { id: 'jonas', name: 'Jonas Weber', detail: 'Platform' },
]

const SHIFTS: RotaShift[] = [
  { id: 's0', lane: 'jonas', start: at(-1, 9), end: at(0, 9) },
  { id: 's1', lane: 'mara', start: at(0, 9), end: at(1, 9) },
  { id: 's2', lane: 'theo', start: at(1, 9), end: at(2, 9) },
  { id: 's3', lane: 'iris', start: at(2, 9), end: at(3, 9) },
  { id: 's4', lane: 'jonas', start: at(3, 9), end: at(4, 9) },
  { id: 's5', lane: 'mara', start: at(4, 9), end: at(7, 9) },
  { id: 'o1', lane: 'theo', start: at(3, 12), end: at(3, 18), override: true, note: 'Covering Jonas' },
  { id: 'o2', lane: 'iris', start: at(5, 10), end: at(5, 16), override: true },
]

export default function TimeLanesDemo() {
  // `now` pins the line for the demo; leave it out and the line follows the clock.
  return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <TimeLanes lanes={PEOPLE} shifts={SHIFTS} start={WEEK} now={at(2, 14.5)} />
    </div>
  )
}
```

A week of on-call shifts for four people, with two overrides and the time line pinned mid-week.

### Day view

```tsx
'use client'

import { TimeLanes, type RotaLane, type RotaShift } from '@youj/react'

const DAY = new Date(2026, 9, 5, 8).getTime()
const at = (h: number, m = 0) => DAY + ((h - 8) * 60 + m) * 60_000

const DRIVERS: RotaLane[] = [
  { id: 'mq', name: 'Mara Quinn', detail: 'Load 4821' },
  { id: 'tp', name: 'Theo Park', detail: 'Load 4910' },
  { id: 'io', name: 'Iris Okafor', detail: 'Available' },
]

const RUNS: RotaShift[] = [
  { id: 'r1', lane: 'mq', start: at(8), end: at(9, 40), label: '4790', tone: 'neutral' },
  { id: 'r2', lane: 'mq', start: at(10), end: at(14, 50), label: '4821' },
  { id: 'r2x', lane: 'mq', start: at(14, 50), end: at(15, 37), label: '+47m', tone: 'danger', override: true, note: 'Running late on Ridge road' },
  { id: 'r3', lane: 'tp', start: at(8), end: at(10, 20), label: '4874', tone: 'neutral' },
  { id: 'r4', lane: 'tp', start: at(10, 50), end: at(13, 20), label: '4910', tone: 'danger', note: 'Dock conflict at 13:30' },
  { id: 'p1', lane: 'tp', start: at(13, 50), end: at(16), label: 'Reassign', proposed: true },
  { id: 'r5', lane: 'io', start: at(8), end: at(9, 50), label: '4863', tone: 'neutral' },
  { id: 'p2', lane: 'io', start: at(10, 30), end: at(13), label: '4935', proposed: true, note: '4.2 mi from the yard' },
  { id: 'p3', lane: 'io', start: at(13, 50), end: at(16), label: '4910', proposed: true },
]

export default function TimeLanesDay() {
  return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <TimeLanes lanes={DRIVERS} shifts={RUNS} start={DAY} hours={9} now={at(11, 58)} label="Driver timeline" />
    </div>
  )
}
```

One day of driver runs, with a late run, a dock conflict and proposed reassignments.

`hours` shows a day instead of a week: the axis counts hours from `start` (every hour or two), and the now line runs across every lane at the time. A shift's `label` replaces its start time on the bar (a load, a job) and is read first; its `tone` overrides its lane's, so a late run can wear `danger`. A `proposed` shift is a suggestion not yet accepted: a dashed outline in the accent, never on call, with no handoff, and its detail says Proposed.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add time-lanes
```

It brings `badge`, `popover`, `use-now`, `youj-core`, `youj-labels-time-lanes`, `youj-presets`, `youj-ui-core` with it.

The copy is 11 registry items, about 7,900 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `badge`, `icon-engine`, `icon-x`, `popover`, `presentation`, `use-now`.

Use time lanes for any rotation where the question is who holds it when: on-call pagers, support shifts, a release captain. There's a lane per person or team, each shift a bar from its start to its end, an override hatched over the lane of whoever covers, a dashed baton where one lane hands off to another, and now as a line in the accent. For events that already happened, use a [Timeline](https://www.youj.dev/docs/components/timeline); for jobs that run on a daily clock, a [Day Ring](https://www.youj.dev/docs/components/day-ring).

```tsx
import { TimeLanes, type RotaLane, type RotaShift } from '@youj/react'

const lanes: RotaLane[] = [
  { id: 'mara', name: 'Mara Quinn', detail: 'Platform' },
  { id: 'theo', name: 'Theo Park', detail: 'Platform' },
]
const shifts: RotaShift[] = [
  { id: 'a', lane: 'mara', start: new Date('2026-09-28T09:00'), end: new Date('2026-09-29T09:00') },
  { id: 'b', lane: 'theo', start: new Date('2026-09-29T09:00'), end: new Date('2026-09-30T09:00') },
  { id: 'c', lane: 'theo', start: new Date('2026-09-28T13:00'), end: new Date('2026-09-28T17:00'), override: true, note: 'Covering Mara' },
]

<TimeLanes lanes={lanes} shifts={shifts} start={new Date('2026-09-28T00:00')} />
```

`start` is the first moment shown (usually a Monday at midnight) and `days` how many follow (7 by default). A shift sits in its `lane` from `start` to `end`; `override` draws it hatched above the lane, and `note` adds a line to its detail. Lanes take the chart colors in turn, or their own `tone`. Where one lane's shift ends as another lane's begins, a dashed baton joins them, with a diamond on the day axis.

`now` places the line: by default it follows the clock, read every 30 seconds once the page is live (on the server there's no line until the browser has the time); pass a time to pin it, or `null` to hide it. Shifts that ended fade and the one on call now is lit. `renderDetail` adds your own actions to a shift's detail: Swap, Page, a link to the schedule.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lanes` (required) | `RotaLane[]` |  |  |
| `shifts` (required) | `RotaShift[]` |  |  |
| `start` (required) | `Date \| number` |  | The first moment shown: usually a Monday at midnight. |
| `days` | `number` | `7` | Days shown. |
| `hours` | `number` |  | Hours shown instead of days, for a day view ("08:00 to 17:00" is 9): the axis counts hours. |
| `now` | `Date \| number \| null` |  | Where the now line sits. Default: the clock, read every 30 s once the page is live. |
| `label` | `string` | `"On-call rota"` | The rota's accessible name. |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `renderDetail` | `(shift: RotaShift, lane: RotaLane) => ReactNode` |  | Extra content at the foot of a shift's detail: actions, links. |

Also takes the props of `ComponentProps<'div'>`.

#### Shifts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `lane` (required) | `string` |  | The lane it sits in. |
| `start` (required) | `Date \| number` |  |  |
| `end` (required) | `Date \| number` |  |  |
| `override` | `boolean` |  | Covering someone else's shift: drawn hatched. |
| `note` | `string` |  | A line for the detail: "Covering Ada's dentist visit". |
| `proposed` | `boolean` |  | Suggested, not yet accepted: drawn as a dashed outline in the accent (or its `tone`), never on call. |
| `label` | `string` |  | Text on the bar in place of its start time: a job or load ("48291"). Read before the lane's name. |
| `tone` | `'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5' \| 'accent' \| 'danger' \| 'neutral'` |  | The bar's own color, over its lane's: `danger` for a late run. |

### Styling

Parts: `time-lanes`, `time-lanes-heads`, `time-lanes-head`, `time-lanes-avatar`, `time-lanes-body`, `time-lanes-axis`, `time-lanes-day` (with `data-today`), `time-lanes-hour`, `time-lanes-handoff`, `time-lanes-grid`, `time-lanes-baton`, `time-lanes-lane`, `time-lanes-shift` (with `data-state`, `data-override` and `data-proposed`), `time-lanes-label`, `time-lanes-detail`, `time-lanes-when` and `time-lanes-now`. A lane is `--rota-lane` tall (2.75rem).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Clock tick | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the now line glides to its new place |
| Detail | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the shift’s popover opens from the bar |

**Reduced motion:** The line jumps; the popover appears in place.

#### Reduced motion

The now line jumps to each new time, and the detail opens in place.

### Accessibility

- The rota is a group named by `label` (default: the labels' "On-call rota") and described by how to move through it; each lane is a group named by its person or team.
- Each shift is a button named by its label, who, from and until when, whether it's an override and whether it's proposed ("4935, Iris Okafor, Mon 10:30 to Mon 13:00, Proposed").
- The shifts are one tab stop, starting on the shift on call now. Left and right move along a lane (mirrored in RTL), up and down to the nearest shift in the next lane, Home and End to a lane's ends, and Enter or Space opens the detail.
- The detail says when, for how long, whether it's an override, who takes over, and whether the shift is on call now, upcoming or ended.
- Its words come from the labels (`rota`, `rotaShift`, `rotaHint`, `rotaHandoff`, `rotaOverride`, `rotaOnCall`, `rotaUpcoming`, `rotaEnded`, `proposed`), translated by the language packs.

---

# Route Map

> Draw a route on a tile-free map, with delayed stretches, a proposed reroute and cards anchored to stops.

Source: https://www.youj.dev/docs/components/route-map

## Examples

### Demo

```tsx
'use client'

import { CheckIcon, TruckIcon } from '@youj/icons'
import { Button, RouteMap, type RouteMapRoute, type RouteMapStop } from '@youj/react'

const STOPS: RouteMapStop[] = [
  { id: 'depot', name: 'Harbor depot', kind: 'origin', x: 12, y: 72, detail: 'Departed 09:14' },
  { id: 'yard', name: 'North yard', x: 29, y: 55, detail: 'Passed 10:41' },
  {
    id: 'truck',
    name: 'Load 4821',
    kind: 'current',
    x: 43,
    y: 45,
    detail: '47 min late',
    icon: <TruckIcon size={14} />,
    cardSide: 'top',
    card: (
      <div className="flex flex-col gap-0.5">
        <span className="font-mono text-ui-xs text-fg-muted">LOAD 4821</span>
        <span className="font-medium text-fg">Slowed on Ridge road</span>
        <span className="font-mono text-ui-xs text-danger-text tabular-nums">+47 min · speed −24%</span>
      </div>
    ),
  },
  { id: 'ridge', name: 'Ridge junction', x: 64, y: 29, detail: 'ETA 13:05' },
  { id: 'summit', name: 'Summit DC', kind: 'destination', x: 86, y: 18, detail: 'ETA 15:49' },
]

const ROUTES: RouteMapRoute[] = [
  { id: 'driven', status: 'done', path: ['depot', [20, 65], 'yard', [36, 49], 'truck'] },
  { id: 'late', status: 'delayed', path: ['truck', [53, 36], 'ridge'] },
  { id: 'ahead', status: 'on-time', path: ['ridge', [76, 23], 'summit'] },
  { id: 'reroute', status: 'proposed', label: 'Proposed via river road', path: ['truck', [52, 55], [66, 57], [78, 42], [84, 28], 'summit'] },
]

export default function RouteMapDemo() {
  return (
    <div className="w-full max-w-3xl">
      <RouteMap stops={STOPS} routes={ROUTES}>
        {/* Your own overlay: the reroute to approve, beside the legend. */}
        <div className="absolute end-3 bottom-3 z-20 hidden w-56 flex-col gap-2 rounded-xl border border-line bg-overlay p-3 shadow-md sm:flex">
          <span className="font-mono text-ui-xs text-accent-text">REROUTE · LOAD 4821</span>
          <div className="flex items-baseline justify-between rounded-lg bg-band px-2.5 py-1.5">
            <span className="text-ui-sm text-fg-muted">Ridge road</span>
            <span className="font-mono text-ui text-danger-text tabular-nums">15:49</span>
          </div>
          <div className="flex items-baseline justify-between rounded-lg bg-accent-subtle px-2.5 py-1.5">
            <span className="text-ui-sm text-fg">River road</span>
            <span className="font-mono text-ui text-accent-text tabular-nums">15:18</span>
          </div>
          <Button size="sm">
            <CheckIcon size={14} />
            Approve reroute
          </Button>
        </div>
      </RouteMap>
    </div>
  )
}
```

A truck's route from the depot to the distribution center, with a delayed leg, a proposed reroute and your own overlay.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add route-map
```

It brings `use-controllable-state`, `youj-core`, `youj-labels-route-map`, `youj-presets`, `youj-ui-core` with it.

Use a route map where the question is where a load, a courier or a crew is on its way, which stretch is late and what the alternative would be. There are no tiles: land, water, parks and roads are abstract shapes in the theme's tones, so the routes are the loudest thing on it and nothing loads from a map provider. For a world view of where traffic comes from, use a [Dot Map](https://www.youj.dev/docs/components/dot-map); for the same stops as a line of steps, a [Stepper](https://www.youj.dev/docs/components/stepper) with a detour.

```tsx
import { RouteMap, type RouteMapRoute, type RouteMapStop } from '@youj/react'

const stops: RouteMapStop[] = [
  { id: 'depot', name: 'Harbor depot', kind: 'origin', x: 12, y: 72, detail: 'Departed 09:14' },
  { id: 'truck', name: 'Load 4821', kind: 'current', x: 43, y: 45, card: <p>+47 min</p> },
  { id: 'summit', name: 'Summit DC', kind: 'destination', x: 86, y: 18, detail: 'ETA 15:49' },
]
const routes: RouteMapRoute[] = [
  { id: 'driven', status: 'done', path: ['depot', [24, 60], 'truck'] },
  { id: 'ahead', status: 'delayed', path: ['truck', 'summit'] },
  { id: 'reroute', status: 'proposed', label: 'Proposed via river road', path: ['truck', [66, 57], 'summit'] },
]

<RouteMap stops={stops} routes={routes} />
```

Stops sit at `x` and `y`, from 0 to 100 across and down the map. Their `kind` picks the marker: `origin`, `stop`, `destination`, or `current` for where the vehicle is now (it pulses). Any stop takes your own `icon`: the current one wears it on the accent, the others on an ink disc, as a fleet map's other trucks do. A route's `path` lists what it passes through: stop ids, and `[x, y]` waypoints to bend it along the roads; the line is smoothed through them. Its `status` is `done` (driven, quiet), `on-time` (ink), `delayed` (the danger tone) or `proposed` (a dotted line in the accent), and its `label` names it in the legend.

A stop's `card` is anchored beside its marker and always shown: an ETA, a warning, a reroute to approve. It sits toward the middle of the map unless `cardSide` says `left`, `right`, `top` or `bottom`. Anything else you lay over the map (a summary card, zoom controls) goes in `children`. `terrain` swaps the built-in coast for your own shapes, as path data in a 100 × 100 box; `ratio` sets the map's width over its height (16 / 10).

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stops` (required) | `RouteMapStop[]` |  |  |
| `routes` (required) | `RouteMapRoute[]` |  |  |
| `terrain` | `RouteMapTerrain` | `DEFAULT_TERRAIN` | The land under the routes. |
| `value` | `string \| null` |  | The picked stop's id (controlled); `null` for none. |
| `defaultValue` | `string \| null` | `null` | The stop picked at first. |
| `onValueChange` | `(id: string \| null) => void` |  |  |
| `legend` | `boolean` | `true` | Shows the legend of route states. |
| `ratio` | `number` | `16 / 10` | The map's width over its height. |
| `label` | `string` |  | The map's accessible name. Default: the labels' "Route map". |
| `children` | `ReactNode` |  | Your own overlays on the map: controls, a summary card. |

Also takes the props of `ComponentProps<'div'>`.

#### Stops

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `name` (required) | `string` |  | "Harbor depot". |
| `x` (required) | `number` |  | Across the map, 0–100 from its left edge. |
| `y` (required) | `number` |  | Down the map, 0–100 from its top. |
| `kind` | `'origin' \| 'stop' \| 'destination' \| 'current'` | ``stop`` | Its marker. |
| `detail` | `string` |  | A line said with its name and shown on hover: "Departed 09:14", "ETA 15:49". |
| `icon` | `ReactNode` |  | Your own marker face: a truck, a courier. The current position wears it on the accent; any other stop on an ink disc, in place of its dot. |
| `card` | `ReactNode` |  | A card anchored beside the marker, always shown. |
| `cardSide` | `'left' \| 'right' \| 'top' \| 'bottom'` |  | Which side of the marker the card sits on. Default: left or right, toward the middle of the map. |

#### Routes

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `path` (required) | `(string \| RouteMapPoint)[]` |  | What it passes through, in order: stop ids, and waypoints as [x, y] (0–100) to bend it along the roads. |
| `status` | `'done' \| 'on-time' \| 'delayed' \| 'proposed'` | ``on-time`` |  |
| `label` | `string` |  | Its name in the legend and the text alternative: "AI proposed via ring road". Default: its state's word. |

### Styling

Parts: `route-map`, `route-map-land`, `route-map-terrain`, `route-map-routes`, `route-map-route` (with `data-status`), `route-map-stop` (with `data-kind`), `route-map-marker`, `route-map-tag`, `route-map-card` (with `data-side`) and `route-map-legend`. Lines keep their width at any size; the map never mirrors in RTL, since geography doesn't.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Land | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | fades in as the map scrolls into view |
| Routes | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | each draws along its length: driven, then on time, delayed and proposed, one state after another |
| Markers | `spring.snappy` | 0.2s, bounce 0 | land as their first line starts; the destination settles |
| Cards | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | rise in after their marker |
| Current position | `duration.deliberate`, `ease.exit` | 560ms; cubic-bezier(0.4, 0, 1, 1) | a ring opens and fades, only while the map is on screen |

**Reduced motion:** Everything is drawn in place, and the current position doesn't pulse.

#### Reduced motion

Routes, markers and cards are drawn in place and the current position holds still. The states read the same: color, dots and the legend carry them.

### Accessibility

- The map is a group named by `label` (default: the labels' "Route map").
- Markers are buttons in stop order, named by place, kind and detail ("Summit DC, Destination, ETA 15:49"); pressing one picks it (`aria-pressed`), and hover or focus shows its name.
- The routes and stops are written out for screen readers: every stop with its kind and detail, every route with its state and the stops it runs through ("Proposed via river road: Load 4821 → Summit DC").
- Cards are ordinary content, read where they sit after their marker. The land, lines and legend are decorative.
- Its words come from the labels (`routeMap`, `routeOrigin`, `routeStop`, `routeDestination`, `routeCurrent`, `routeDone`, `routeOnTime`, `routeDelayed`, `proposed`), translated by the language packs.

---

# Proposal Card

> Weigh a proposed change against the current plan, then approve or dismiss it: a reroute, a reassignment, a new slot.

Source: https://www.youj.dev/docs/components/proposal-card

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { CheckIcon, LockIcon, SparklesIcon } from '@youj/icons'
import { Button, ProposalCard, type ProposalStatus } from '@youj/react'

export default function ProposalCardDemo() {
  const [status, setStatus] = useState<ProposalStatus>('pending')
  return (
    <ProposalCard
      headingLevel={2}
      className="w-full max-w-sm"
      source={
        <>
          <SparklesIcon size={12} /> Route agent · 92% confidence
        </>
      }
      title="Reroute load 4821 via Ridge Rd"
      description="Congestion on Harbor Fwy has cut speed by 24%. The delivery window stays intact."
      options={[
        { id: 'current', label: 'Harbor Fwy · current', value: '15:49', detail: '+47 min', tone: 'danger' },
        { id: 'proposed', label: 'Ridge Rd · proposed', value: '15:18', detail: '−31 min', proposed: true },
      ]}
      facts={[
        { label: 'Time saved', value: '31 min', tone: 'success' },
        { label: 'Extra distance', value: '+4.2 mi' },
        { label: 'Window', value: 'Kept', tone: 'success' },
      ]}
      note={
        <span className="inline-flex items-center gap-1.5">
          <LockIcon size={12} /> Route changes need a dispatcher’s approval.
        </span>
      }
      status={status}
      resolution={
        <span className="flex items-center justify-between gap-2">
          {status === 'approved' ? 'Approved · driver notified' : 'Dismissed · keeping Harbor Fwy'}
          <Button size="sm" variant="ghost" onClick={() => setStatus('pending')}>
            Undo
          </Button>
        </span>
      }
      actions={
        <>
          <Button size="sm" onClick={() => setStatus('approved')}>
            <CheckIcon size={14} /> Approve reroute
          </Button>
          <Button size="sm" variant="ghost" onClick={() => setStatus('dismissed')}>
            Dismiss
          </Button>
        </>
      }
    />
  )
}
```

A route agent proposes a reroute; approving or dismissing resolves the card, and Undo brings it back.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add proposal-card
```

It brings `collapse`, `youj-core`, `youj-labels-proposal-card`, `youj-presets`, `youj-ui-core` with it.

Use a proposal card where someone, often an agent, suggests a change and a person decides: a reroute that saves half an hour, a load moved to another driver, a meeting moved to a free slot. It says where the proposal came from, what it is, then weighs the options side by side, the proposed one drawn as a dashed accent outline like a proposed route on a [Route Map](https://www.youj.dev/docs/components/route-map) or a proposed run on [Time Lanes](https://www.youj.dev/docs/components/time-lanes). Its impact reads as figures, and your buttons decide it.

```tsx
import { Button, ProposalCard } from '@youj/react'

const [status, setStatus] = useState<'pending' | 'approved' | 'dismissed'>('pending')

<ProposalCard
  source="Route agent · 92% confidence"
  title="Reroute load 4821 via Ridge Rd"
  options={[
    { id: 'current', label: 'Harbor Fwy · current', value: '15:49', detail: '+47 min', tone: 'danger' },
    { id: 'proposed', label: 'Ridge Rd · proposed', value: '15:18', detail: '−31 min', proposed: true },
  ]}
  facts={[{ label: 'Time saved', value: '31 min', tone: 'success' }]}
  status={status}
  resolution="Approved · driver notified"
  actions={<Button size="sm" onClick={() => setStatus('approved')}>Approve reroute</Button>}
/>
```

`options` are the plans side by side, usually the current one and the proposal (`proposed: true`). Each has a `label`, a `value` in mono (an ETA, a price) and a `detail` for how it moves against plan, inked by its `tone`. `facts` are the impact as a row of figures. `note` is a line over the actions: why it needs a person. You own `status`: `pending` shows `actions`; `approved` makes the proposal solid, steps the other options back and folds the actions away for your `resolution`; `dismissed` fades the proposal and keeps the plan.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source` | `ReactNode` |  | Where it came from, as an eyebrow: an agent's name, a confidence, an age. |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `options` | `ProposalOption[]` |  | The options side by side: usually the current plan, then the proposal. |
| `facts` | `ProposalFact[]` |  | The impact as figures: time saved, extra distance, the window kept. |
| `note` | `ReactNode` |  | A line over the actions: why it needs a person ("Route changes need approval"). |
| `actions` | `ReactNode` |  | Your buttons while it's pending. |
| `status` | `'pending' \| 'approved' \| 'dismissed'` | `'pending'` |  |
| `resolution` | `ReactNode` |  | What shows once it's decided, in place of the actions: "Approved by you · 11:58". |
| `headingLevel` | `2 \| 3 \| 4` | `3` | The title's heading level. |

Also takes the props of `ComponentProps<'article'>`.

#### Options

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `label` (required) | `ReactNode` |  | "Harbor Fwy · current". |
| `value` | `ReactNode` |  | The figure the options are weighed by: "15:49", "$1,842". |
| `detail` | `ReactNode` |  | How it moves against plan: "+47 min". |
| `tone` | `'neutral' \| 'success' \| 'warning' \| 'danger' \| 'accent'` |  | The figure's and detail's ink. Default neutral; a proposed option defaults to accent. |
| `proposed` | `boolean` |  | The option being proposed: a dashed accent outline until it's approved. |

### Styling

Parts: `proposal-card` (with `data-status`). Each option row carries `data-proposed` and, once stepped back, `data-muted`. The card takes the theme's radius, border and card surface; pass `className` to place it, for example over a map.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Decided | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | option rows change their outline, tint and opacity |
| Actions out, resolution in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the two trade places through Collapse; a reversal continues from the current height |

**Reduced motion:** Rows change tone in place, and the actions and resolution swap at once.

#### Reduced motion

Every change lands in place. The status still reads from the outline, the struck-through figure and the resolution text.

### Accessibility

- The card is an `article` named by its title; `headingLevel` sets the title's level (3 by default).
- The proposed option says so to screen readers ("Ridge Rd · proposed, Proposed"), from the labels' `proposed`, translated by the language packs.
- Facts are a description list: each figure is read with its label.
- The resolution sits in a polite status region, so approving or dismissing is announced.

---

# Whiteboard

> Sketch, write sticky notes, connect shapes, embed your own components, pin comments and see who else is on the board, then export the scene.

Source: https://www.youj.dev/docs/components/whiteboard

## Examples

### Flow sketch

```tsx
'use client'

import { Sparkline, StatCard, Whiteboard, type WhiteboardScene } from '@youj/react'

const FLOW: WhiteboardScene = {
  shapes: [
    { id: 'signup', type: 'sticky', color: 'blue', width: 'medium', x: 40, y: 72, w: 168, h: 96, text: 'Sign up\nEmail or Google' },
    { id: 'verify', type: 'sticky', color: 'accent', width: 'medium', x: 304, y: 72, w: 168, h: 96, text: 'Verify email\nLink valid 24h' },
    { id: 'workspace', type: 'sticky', color: 'green', width: 'medium', x: 568, y: 72, w: 168, h: 96, text: 'Create workspace\nName, invite team' },
    { id: 'expired', type: 'sticky', color: 'red', width: 'medium', x: 304, y: 264, w: 168, h: 80, text: 'Link expired\nResend and retry' },
    { id: 'c1', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'signup' }, to: { shape: 'verify' }, route: 'elbow' },
    { id: 'c2', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'verify' }, to: { shape: 'workspace' }, route: 'elbow', label: 'clicked' },
    { id: 'c3', type: 'connector', color: 'red', width: 'thin', from: { shape: 'verify' }, to: { shape: 'expired' }, route: 'elbow', label: 'after 24h' },
    { id: 'c4', type: 'connector', color: 'red', width: 'thin', from: { shape: 'expired' }, to: { shape: 'signup' }, route: 'elbow' },
    { id: 'activation', type: 'embed', x: 568, y: 232, w: 240, h: 172, title: 'Activation, last 30 days' },
    { id: 'note', type: 'text', color: 'amber', width: 'thin', x: 40, y: 380, text: 'Skip verify for SSO?' },
    {
      id: 'circle',
      type: 'pen',
      color: 'amber',
      width: 'medium',
      points: Array.from({ length: 34 }, (_, i) => {
        const a = (i / 30) * Math.PI * 2 - 0.6
        return [123 + Math.cos(a) * (102 + i * 0.6), 392 + Math.sin(a) * (26 + i * 0.2), 0.45 + 0.3 * Math.sin(i / 4)] as [number, number, number]
      }),
    },
  ],
  pins: [{ id: 'p1', shape: 'verify', x: 160, y: 4, author: 'Mara Lind', text: 'Could the link last 48 hours? Most retries come the next morning.' }],
}

const RATE = [52, 55, 54, 58, 57, 61, 60, 63, 62, 64]

export default function WhiteboardDemo() {
  return (
    <Whiteboard
      defaultValue={FLOW}
      height={480}
      className="max-w-4xl"
      embeds={{
        activation: (
          <StatCard
            label="Activated"
            value={0.64}
            format={{ style: 'percent' }}
            delta={0.04}
            comparison="vs last month"
            chart={<Sparkline data={RATE} className="h-8" />}
          />
        ),
      }}
    />
  )
}
```

An onboarding flow as sticky notes joined by connectors, a live stat card embedded beside them, a circled question and a comment pinned to a step.

Pick Select (V) to click a shape, Shift-click to add one, or drag on empty board for a marquee. Drag the selection to move it: it snaps to the edges and centers of the shapes around it and to the spacing between them, with guides and gap sizes showing why (hold Alt to move freely). Corner handles resize. Double-click a text, a note or a connector to edit its words. With two or more shapes selected, Arrange lines them up or spreads them evenly.

### Embeds

```tsx
'use client'

import { Badge, Sparkline, StatCard, Whiteboard, type WhiteboardScene } from '@youj/react'

const SCENE: WhiteboardScene = {
  shapes: [
    { id: 'signups', type: 'embed', x: 0, y: 0, w: 240, h: 176, title: 'Sign-ups, this week' },
    { id: 'release', type: 'embed', x: 320, y: 0, w: 240, h: 112, title: 'Release' },
    { id: 'why', type: 'sticky', color: 'amber', width: 'medium', x: 320, y: 152, w: 240, h: 72, text: 'Spike lines up with the pricing page launch' },
    { id: 'k1', type: 'connector', color: 'amber', width: 'thin', from: { shape: 'why' }, to: { shape: 'signups' }, route: 'elbow' },
  ],
}

export default function WhiteboardEmbeds() {
  return (
    <Whiteboard
      defaultValue={SCENE}
      height={400}
      tools={['select', 'hand', 'sticky', 'connector', 'comment']}
      className="max-w-3xl"
      embeds={{
        signups: (
          <StatCard
            label="Sign-ups"
            value={1284}
            delta={0.18}
            comparison="vs last week"
            chart={<Sparkline data={[120, 132, 128, 141, 150, 238, 275]} className="h-8" />}
          />
        ),
        release: (
          <div className="flex h-full flex-col justify-center gap-2 rounded-xl bg-surface px-4 shadow-xs">
            <div className="flex items-center gap-2">
              <span className="font-medium text-ui">v2.4 pricing</span>
              <Badge variant="success">Live</Badge>
            </div>
            <span className="text-fg-muted text-ui-sm">Shipped Tuesday, 09:40</span>
          </div>
        ),
      }}
    />
  )
}
```

Kit components placed on the board: a stat card and a release card, with a note connected to the card it explains.

An `embed` shape is a frame for any React node: `embeds` maps its id to what it holds (or is a function of the shape). The frame moves and resizes like any shape, from its title; what's inside keeps its own pointer and keyboard, and stays mounted while it's offscreen so it keeps its state. Connectors attach to embeds as they do to shapes.

### Connectors

```tsx
'use client'

import { Whiteboard, type WhiteboardScene } from '@youj/react'

const SCENE: WhiteboardScene = {
  shapes: [
    { id: 'api', type: 'rectangle', color: 'ink', width: 'medium', x: 0, y: 40, w: 140, h: 64 },
    { id: 'api-t', type: 'text', color: 'ink', width: 'thin', x: 50, y: 62, text: 'API' },
    { id: 'queue', type: 'ellipse', color: 'blue', width: 'medium', x: 240, y: 32, w: 160, h: 80 },
    { id: 'queue-t', type: 'text', color: 'blue', width: 'thin', x: 296, y: 62, text: 'Queue' },
    { id: 'worker', type: 'sticky', color: 'green', width: 'medium', x: 500, y: 0, w: 160, h: 64, text: 'Worker A' },
    { id: 'worker-b', type: 'sticky', color: 'green', width: 'medium', x: 500, y: 112, w: 160, h: 64, text: 'Worker B' },
    { id: 'dlq', type: 'sticky', color: 'red', width: 'medium', x: 240, y: 200, w: 160, h: 64, text: 'Dead letters' },
    { id: 'k1', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'api' }, to: { shape: 'queue' }, label: 'enqueue' },
    { id: 'k2', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'queue' }, to: { shape: 'worker' }, route: 'elbow' },
    { id: 'k3', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'queue' }, to: { shape: 'worker-b' }, route: 'elbow' },
    { id: 'k4', type: 'connector', color: 'red', width: 'thin', from: { shape: 'worker-b' }, to: { shape: 'dlq' }, route: 'elbow', label: 'after 5 tries' },
  ],
}

export default function WhiteboardConnectors() {
  return <Whiteboard defaultValue={SCENE} defaultTool="connector" height={400} className="max-w-3xl" />
}
```

A queue's design, opening on the Connector tool (X): drag from one shape to another.

A connector stores the shapes it joins, not where they are, so it re-routes whenever either end moves. `straight` runs from edge to edge, `elbow` leaves the side that faces the other shape and turns at right angles. Double-click it (or press Enter on it) to write a label. A connector dropped on empty board ends at that point. Deleting a shape deletes its connectors in the same undo step.

### Comments

```tsx
'use client'

import type { ReactNode } from 'react'
import { Avatar, AvatarFallback, Whiteboard, type WhiteboardPin, type WhiteboardScene } from '@youj/react'

const THREADS: Record<string, { who: string; text: string }[]> = {
  p1: [
    { who: 'Mara Lind', text: 'Can the hero say what it does in five words?' },
    { who: 'Theo Park', text: 'Trying “Your team’s plans, in one place”.' },
  ],
  p2: [{ who: 'Ana Ruiz', text: 'Pricing link goes to the old page.' }],
}

const SCENE: WhiteboardScene = {
  shapes: [
    { id: 'hero', type: 'rectangle', color: 'ink', width: 'medium', x: 0, y: 0, w: 520, h: 140 },
    { id: 'hero-t', type: 'text', color: 'ink', width: 'bold', x: 32, y: 40, text: 'Plan together' },
    { id: 'nav', type: 'sticky', color: 'blue', width: 'medium', x: 0, y: 180, w: 240, h: 72, text: 'Nav: Product, Pricing, Docs' },
    { id: 'cta', type: 'sticky', color: 'accent', width: 'medium', x: 280, y: 180, w: 240, h: 72, text: 'Start free trial' },
  ],
  pins: [
    { id: 'p1', shape: 'hero', x: 300, y: 28, author: 'Mara Lind' },
    { id: 'p2', shape: 'nav', x: 210, y: 10, author: 'Ana Ruiz', resolved: true },
  ],
}

function Thread({ pin, actions }: { pin: WhiteboardPin; actions: ReactNode }) {
  const replies = THREADS[pin.id] ?? []
  return (
    <div className="flex flex-col">
      <div className="flex items-center gap-1 py-1.5 ps-3 pe-1.5">
        <span className="flex-1 font-medium text-ui-sm">
          {replies.length} {replies.length === 1 ? 'reply' : 'replies'}
        </span>
        {actions}
      </div>
      <ol className="flex flex-col gap-3 px-3 pb-3">
        {replies.map((c) => (
          <li key={c.text} className="flex gap-2.5">
            <Avatar size="sm">
              <AvatarFallback>{c.who.slice(0, 1)}</AvatarFallback>
            </Avatar>
            <div className="flex min-w-0 flex-col">
              <span className="font-medium text-ui-sm">{c.who}</span>
              <span className="text-fg-muted text-ui-sm">{c.text}</span>
            </div>
          </li>
        ))}
      </ol>
    </div>
  )
}

export default function WhiteboardComments() {
  return (
    <Whiteboard
      defaultValue={SCENE}
      defaultTool="comment"
      height={380}
      className="max-w-3xl"
      pinContent={(pin, actions) => <Thread pin={pin} actions={actions} />}
    />
  )
}
```

A landing page review with a thread on the hero and a resolved one on the nav, opening on the Comment tool (C).

Click to drop a pin: on a shape it attaches there and moves with it. A pin opens `pinContent(pin, actions)`, your own thread, in a popover; `actions` are the pin's Resolve and Delete, to put in your thread's header so the popover has one header (CommentThread takes them as `actions`). Without `pinContent` it holds the pin's name, those actions and a plain note that writes `pin.text`. Pins keep their size at any zoom. The [Collaborative canvas](https://www.youj.dev/docs/blocks/specialized#collaborative-canvas) screen puts a full CommentThread in them.

### Presence

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Whiteboard, type WhiteboardCursor, type WhiteboardScene } from '@youj/react'

const SCENE: WhiteboardScene = {
  shapes: [
    { id: 'a', type: 'sticky', color: 'amber', width: 'medium', x: 0, y: 0, w: 180, h: 80, text: 'Research' },
    { id: 'b', type: 'sticky', color: 'blue', width: 'medium', x: 240, y: 0, w: 180, h: 80, text: 'Design' },
    { id: 'c', type: 'sticky', color: 'green', width: 'medium', x: 480, y: 0, w: 180, h: 80, text: 'Build' },
    { id: 'k1', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'a' }, to: { shape: 'b' } },
    { id: 'k2', type: 'connector', color: 'ink', width: 'thin', from: { shape: 'b' }, to: { shape: 'c' } },
  ],
}

/** Two people moving around the board: in an app these come from your realtime layer. */
function useDemoCursors() {
  const [t, setT] = useState(0)
  useEffect(() => {
    const id = setInterval(() => setT(performance.now() / 700), 60)
    return () => clearInterval(id)
  }, [])
  const cursors: WhiteboardCursor[] = [
    { id: 'ana', name: 'Ana', x: 90 + Math.cos(t / 2) * 120, y: 130 + Math.sin(t / 3) * 30 },
    { id: 'theo', name: 'Theo', x: 520 + Math.sin(t / 2.5) * 80, y: -40 + Math.cos(t / 2) * 20, message: t % 8 < 4 ? 'Moving Build here?' : undefined },
  ]
  return cursors
}

export default function WhiteboardPresence() {
  const cursors = useDemoCursors()
  const [mine, setMine] = useState<{ x: number; y: number } | null>(null)
  return (
    <div className="flex w-full max-w-3xl flex-col gap-2">
      <Whiteboard defaultValue={SCENE} defaultTool="select" height={340} cursors={cursors} onCursorMove={setMine} />
      <span className="font-mono text-fg-muted text-ui-xs">{mine ? `You: ${Math.round(mine.x)}, ${Math.round(mine.y)}` : 'Move over the board'}</span>
    </div>
  )
}
```

Two people on the board, with a chat bubble, and your own position reported as you move.

`cursors` takes everyone else's pointers in board coordinates (the same as the shapes'), so they stay on the spot they point at as you pan and zoom; [Live Cursors](https://www.youj.dev/docs/components/live-cursors) draws them, with names, colors from the chart palette, chat bubbles and join and leave announcements. `onCursorMove` reports yours in the same coordinates, throttled, and `null` when the pointer leaves: send it to the others.

### Large board

```tsx
'use client'

import { Whiteboard, type WhiteboardColor, type WhiteboardScene } from '@youj/react'

const COLORS: WhiteboardColor[] = ['amber', 'blue', 'green', 'accent', 'red']
const TOPICS = ['Onboarding', 'Billing', 'Search', 'Mobile', 'Reports', 'Teams', 'Exports', 'Alerts']

/** A retro wall: 8 columns of 20 notes, a header box over each and connectors between the headers, 200 shapes in all. */
function wall(): WhiteboardScene {
  const shapes: WhiteboardScene['shapes'] = []
  TOPICS.forEach((topic, col) => {
    const x = col * 240
    shapes.push({ id: `h${col}`, type: 'rectangle', color: 'ink', width: 'medium', x, y: 0, w: 200, h: 56 })
    shapes.push({ id: `t${col}`, type: 'text', color: 'ink', width: 'medium', x: x + 20, y: 14, text: topic })
    for (let row = 0; row < 22; row++) {
      shapes.push({
        id: `n${col}-${row}`,
        type: 'sticky',
        color: COLORS[(col + row) % COLORS.length]!,
        width: 'medium',
        x,
        y: 96 + row * 104,
        w: 200,
        h: 88,
        text: `${topic} idea ${row + 1}`,
      })
    }
    if (col) shapes.push({ id: `k${col}`, type: 'connector', color: 'ink', width: 'thin', from: { shape: `h${col - 1}` }, to: { shape: `h${col}` } })
  })
  return { shapes: shapes.slice(0, 200) }
}

const WALL = wall()

export default function WhiteboardLargeBoard() {
  return <Whiteboard defaultValue={WALL} defaultMinimap height={440} className="max-w-3xl" />
}
```

A retro wall of 200 shapes with the minimap on.

Wheel or two fingers pan, ⌘/Ctrl + wheel or a pinch zooms at the pointer, Space-drag or the Hand tool (H) pans. The zoom menu fits the board (⇧1) or the selection (⇧2), goes back to 100% and turns on the minimap (M) and Snap to grid. Only the shapes near the view are drawn, and moving the view moves two layers rather than every shape, so panning stays smooth at a few hundred shapes.

### Empty board

```tsx
'use client'

import { useRef, useState } from 'react'
import { Button, Whiteboard, type WhiteboardHandle, type WhiteboardScene } from '@youj/react'

export default function WhiteboardEmpty() {
  const board = useRef<WhiteboardHandle>(null)
  const [scene, setScene] = useState<WhiteboardScene>({ shapes: [] })
  const [out, setOut] = useState('')

const png = async () => {
    const blob = await board.current?.toPNG()
    if (blob) setOut(`${blob.size} bytes of PNG`)
  }

return (
    <div className="flex w-full max-w-3xl flex-col gap-3">
      <Whiteboard ref={board} value={scene} onValueChange={setScene} height={360} />
      <div className="flex items-center gap-2">
        <Button variant="outline" size="sm" disabled={!scene.shapes.length} onClick={() => setOut(`${board.current?.toSVG().length ?? 0} bytes of SVG`)}>
          Export SVG
        </Button>
        <Button variant="outline" size="sm" disabled={!scene.shapes.length} onClick={png}>
          Export PNG
        </Button>
        <span className="ms-1 truncate font-mono text-ui-xs text-fg-muted">{out || `${scene.shapes.length} shapes in the scene`}</span>
      </div>
    </div>
  )
}
```

A controlled board that starts empty, with SVG and PNG export.

The scene is plain JSON, `{ shapes, pins }`, so it saves and loads as it is. `onValueChange` fires once a stroke, drag or edit ends, not on every pointer move. The ref's `toSVG()` returns a standalone SVG cropped to the shapes in the theme's colors of the moment, and `toPNG()` the same picture as an image; embeds can't travel in a file, so they export as titled placeholders.

### Read only

```tsx
'use client'

import { Whiteboard, type WhiteboardScene } from '@youj/react'

const REVIEW: WhiteboardScene = {
  shapes: [
    { id: 'api', type: 'rectangle', color: 'ink', width: 'medium', x: 40, y: 40, w: 140, h: 64 },
    { id: 'api-t', type: 'text', color: 'ink', width: 'medium', x: 82, y: 60, text: 'API' },
    { id: 'queue', type: 'rectangle', color: 'ink', width: 'medium', x: 260, y: 40, w: 140, h: 64 },
    { id: 'queue-t', type: 'text', color: 'ink', width: 'medium', x: 290, y: 60, text: 'Queue' },
    { id: 'a1', type: 'arrow', color: 'ink', width: 'medium', x1: 190, y1: 72, x2: 250, y2: 72 },
    { id: 'note', type: 'text', color: 'amber', width: 'thin', x: 240, y: 130, text: 'Retries back off here' },
    { id: 'a2', type: 'arrow', color: 'amber', width: 'thin', x1: 320, y1: 125, x2: 330, y2: 110 },
  ],
}

export default function WhiteboardReadOnly() {
  return <Whiteboard value={REVIEW} readOnly height={280} label="Queue design" className="max-w-3xl" />
}
```

A design shared for review: the scene with pan and zoom, and no tools.

`readOnly` drops the toolbar, the handles and undo; dragging the board pans it. Shapes still take focus and are read out by name, and pins open read-only.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add whiteboard
```

It brings `button`, `dropdown-menu`, `icon-align-center-horizontal`, `icon-align-center-vertical`, `icon-align-end-horizontal`, `icon-align-end-vertical`, `icon-align-start-horizontal`, `icon-align-start-vertical`, `icon-arrow-up-right`, `icon-check`, `icon-circle`, `icon-columns`, `icon-hand`, `icon-keyboard`, `icon-layout-grid`, `icon-map`, `icon-message`, `icon-minus`, `icon-mouse-pointer`, `icon-pencil`, `icon-plus`, `icon-redo`, `icon-rows`, `icon-spline`, `icon-square`, `icon-sticky-note`, `icon-trash`, `icon-type`, `icon-undo`, `kbd`, `live-cursors`, `popover`, `textarea`, `toggle-group`, `toolbar`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-resize-measure`, `use-stroke`, `youj-core`, `youj-labels-whiteboard`, `youj-presets`, `youj-ui-core` with it.

The copy is 61 registry items, about 14,600 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `avatar`, `button`, `collapse`, `dropdown-menu`, `field`, `icon-align-center-horizontal`, `icon-align-center-vertical`, `icon-align-end-horizontal`, `icon-align-end-vertical`, `icon-align-start-horizontal` and 43 more.

Use a Whiteboard for diagrams and planning inside a product: a flow in a ticket, a retro, a review with comments, a canvas of live metrics. For laid-out graphs that come from data, a [Flow Graph](https://www.youj.dev/docs/components/flow-graph) fits better.

```tsx
import { useState } from 'react'
import { Whiteboard, type WhiteboardScene } from '@youj/react'

export function Board({ chart }: { chart: React.ReactNode }) {
  const [scene, setScene] = useState<WhiteboardScene>({ shapes: [] })
  return <Whiteboard value={scene} onValueChange={setScene} embeds={{ revenue: chart }} height={520} />
}
```

A shape is `{ id, type, color, width, … }`: `pen` keeps its `points` (`[x, y, pressure]`), `line` and `arrow` their ends, `rectangle` and `ellipse` a box, `text` a position and its `text`, `sticky` a box (its height the least it takes; it grows to fit) and its `text`, `connector` its `from` and `to` (`{ shape }` or `{ x, y }`), `route` and `label`, and `embed` a box and a `title`. `color` names a theme role (`ink`, `accent`, `red`, `amber`, `green`, `blue`), so the board follows light, dark and every preset; a note's paper is its role's soft fill. A pin is `{ id, x, y, shape?, resolved?, author?, text? }`. Scenes saved before notes, connectors, embeds and pins load as they are.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `WhiteboardScene` |  |  |
| `defaultValue` | `WhiteboardScene` | `EMPTY_SCENE` |  |
| `onValueChange` | `(scene: WhiteboardScene) => void` |  |  |
| `defaultTool` | `'select' \| 'hand' \| 'pen' \| 'line' \| 'arrow' \| 'rectangle' \| 'ellipse' \| 'text' \| 'sticky' \| 'connector' \| 'comment'` |  | The tool the board opens with. Default `pen`, or `select` when it opens with shapes. |
| `tools` | `readonly WhiteboardTool[]` | `ALL_TOOLS` | The tools the toolbar offers, in its order. |
| `readOnly` | `boolean` | `false` | Shows the scene with the view controls only. |
| `height` | `number` | `480` | The board's height in pixels. |
| `label` | `string` |  | The board's accessible name. Default: the labels' "Whiteboard". |
| `embeds` | `Record<string, ReactNode> \| ((embed: WhiteboardEmbed) => ReactNode)` |  | What each `embed` shape holds, by its id: a node, or a function of the shape. |
| `pinContent` | `(pin: WhiteboardPin, actions: ReactNode) => ReactNode` |  | What a comment pin opens: your thread (CommentThread, say). It gets the pin's Resolve and Delete buttons as `actions`, to place in its own header (CommentThread's `actions`), so the popover has one header. Default: the pin's name, its actions and a note field that writes `pin.text`. |
| `cursors` | `readonly WhiteboardCursor[]` |  | Other people's pointers, in board coordinates. |
| `onCursorMove` | `(point: { x: number; y: number } \| null) => void` |  | Your pointer in board coordinates as it moves (throttled, about twenty times a second), and `null` when it leaves: send it to the others. |
| `defaultMinimap` | `boolean` | `false` | Show the minimap at first. |
| `defaultSnapToGrid` | `boolean` | `false` | Snap moves and new shapes to the grid at first. |
| `ref` | `Ref<WhiteboardHandle>` |  | `toSVG`, `toPNG`, `zoomToFit` and `zoomToSelection`. |

Also takes the props of `ComponentProps<'div'>`.

#### Handle

| Method | Does |
|---|---|
| `toSVG()` | The scene as a standalone SVG, cropped to the shapes, in the theme's colors; embeds as titled placeholders |
| `toPNG({ scale })` | The same picture as a PNG `Blob`, `scale` times its size (default 2), on the board's surface color |
| `zoomToFit()` | Scales and centers the view on the whole scene |
| `zoomToSelection()` | Scales and centers the view on the selection |

#### Keyboard shortcuts

| Keys | Does |
|---|---|
| V, H, P, L, A, R, O, T, S, X, C | Select, Hand, Pen, Line, Arrow, Rectangle, Ellipse, Text, Sticky note, Connector, Comment |
| ⌘Z / Ctrl+Z, ⇧⌘Z / Ctrl+Y | Undo, redo |
| Delete or Backspace | Delete the selection (and its connectors) |
| ⌘A / Ctrl+A | Select every shape |
| Arrow keys | Nudge the selection (Shift: ten times as far); on the board, pan |
| ⌥ / Alt + A, H, D, W, V, S | Align left, center, right, top, middle, bottom |
| ⌥⇧ / Alt+Shift + H, V | Distribute horizontally, vertically |
| Space + drag | Pan |
| + − 0 | Zoom in, zoom out, back to 100% |
| ⇧1, ⇧2 | Fit the board, zoom to the selection |
| M | Show or hide the minimap |
| ? | List these shortcuts |
| Enter (on the board) | Place the tool's shape in the middle of the view; with Connector, join the two selected shapes; with Comment, pin the selected shape |
| Enter (on a shape) | Edit a text, a note or a connector's label |

#### Data attributes

The root carries `data-yj-tool` (the active tool) and `data-readonly`; each shape `data-yj-shape` (its type) and `data-selected` when selected; a pin `data-yj-resolved` once resolved.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drawing and dragging |  |  | follow the pointer sample by sample, never eased |
| Wheel, pinch and the zoom buttons |  |  | move the view at once |
| Fit and zoom to selection |  |  | ease the view there on the base token |
| Remote cursors |  |  | Live Cursors’ spring, between sparse updates |

**Reduced motion:** Fitting the view jumps; remote cursors jump to each update.

#### Reduced motion

The board reads and works the same; nothing eases.

### Accessibility

- The toolbar and the zoom bar are each one tab stop with arrow-key roving; each tool is a toggle named by its label, with its key in `aria-keyshortcuts` and in its tooltip.
- The board is a named group described by how many shapes it holds and how to work it from the keyboard. Its shapes are a multi-select listbox and one tab stop: Tab walks them (bringing an offscreen one into view) and leaves the board after the last. Each is named for what it is: "Sticky note: Ship it", "Connector: Sign up to Verify email", "Embed: Revenue".
- A focused shape is selected; the arrow keys nudge it, Delete removes it, Enter edits its words and Escape lets go. Align and distribute have keys, so nothing needs a pointer; with a drawing tool, Enter on the board places that shape.
- An embed's content is a region named by its title, outside the list of shapes, so its own controls keep their roles.
- Pins are a named group of buttons ("Comment 2 by Ana Ruiz, Resolved"); each opens its thread in a popover that takes focus and returns it.
- Additions, deletions and selection changes are announced in a polite live region; Live Cursors announces who joins and leaves.

---

# Live Cursors

> Show who is on a shared surface and where they point: cursors, names, chat bubbles and selections, fed by your own realtime channel.

Source: https://www.youj.dev/docs/components/live-cursors

## Examples

### Demo

```tsx
'use client'

import { useRef, useState } from 'react'
import { LiveCursors, type LiveCursorPosition, type LiveCursorUser, PresenceAvatars, useLiveCursorsInput } from '@youj/react'
import { useWalkers, type Walker } from './simulate'

const TEAM: Walker[] = [
  { id: 'mira', name: 'Mira Chen', status: 'editing', cx: 0.26, cy: 0.45, rx: 0.1, ry: 0.2, pace: 4, phase: 0, selection: [{ x: 0.06, y: 0.12, width: 0.36, height: 0.76 }] },
  { id: 'jonas', name: 'Jonas Weber', status: 'editing', cx: 0.66, cy: 0.32, rx: 0.14, ry: 0.08, pace: 5, phase: 0.2 },
  { id: 'tomas', name: 'Tomás Ruiz', status: 'viewing', cx: 0.7, cy: 0.68, rx: 0.12, ry: 0.12, pace: 2.5, phase: 0.7, lines: ['Love this header', 'Can we try 24px?'] },
]

export default function LiveCursorsDemo() {
  // Simulated people; in an app, `users` comes from your realtime channel.
  const others = useWalkers(TEAM)
  const surface = useRef<HTMLDivElement>(null)
  // Your own pointer, as you'd send it; here it comes straight back as a cursor of its own.
  const [you, setYou] = useState<LiveCursorPosition | null>(null)
  useLiveCursorsInput(surface, setYou)
  const users: LiveCursorUser[] = you ? [...others, { id: 'you', name: 'You', color: 'var(--color-accent)', ...you }] : others

return (
    <div className="flex w-full max-w-3xl flex-col overflow-hidden rounded-2xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-3 border-b border-line px-4 py-2.5">
        <span className="text-ui font-semibold text-fg">Checkout redesign</span>
        <PresenceAvatars users={others} size="sm" />
      </div>
      <LiveCursors ref={surface} users={users} className="h-80 bg-canvas [background-image:radial-gradient(var(--color-line)_1px,transparent_1px)] [background-size:16px_16px]">
        <div className="absolute top-[12%] left-[6%] flex h-[76%] w-[36%] flex-col gap-2 rounded-xl border border-line bg-surface p-3">
          <div className="h-3 w-1/2 rounded-full bg-band" />
          <div className="h-20 rounded-lg bg-accent-subtle" />
          <div className="h-3 w-3/4 rounded-full bg-band" />
          <div className="mt-auto h-8 rounded-lg bg-accent" />
        </div>
        <div className="absolute top-[52%] left-[52%] h-[34%] w-[30%] rotate-1 rounded-md bg-warning-subtle p-3 text-ui-sm text-warning-text">Ship the new totals row?</div>
      </LiveCursors>
    </div>
  )
}
```

Three simulated people in a design file: two editing, one typing a comment. Move your pointer over the canvas: it goes out through `useLiveCursorsInput` and comes straight back as the "You" cursor.

Updates arrive a few times a second, as they would over a socket, and each cursor springs between them.

### Follow a user

```tsx
'use client'

import { useState } from 'react'
import { LiveCursors, PresenceAvatars, ScrollArea } from '@youj/react'
import { useWalkers, type Walker } from './simulate'

const PEOPLE: Walker[] = [
  { id: 'ada', name: 'Ada', status: 'editing', cx: 0.5, cy: 0.5, rx: 0.42, ry: 0.4, pace: 2, phase: 0 },
  { id: 'lin', name: 'Lin', status: 'viewing', cx: 0.2, cy: 0.2, rx: 0.1, ry: 0.1, pace: 3, phase: 0.2 },
]

export default function LiveCursorsFollow() {
  const users = useWalkers(PEOPLE)
  const [following, setFollowing] = useState<string | null>(null)
  const name = users.find((user) => user.id === following)?.name

return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <span className="text-ui-sm text-fg-muted">{name ? `Following ${name}` : 'Press an avatar to follow'}</span>
        <PresenceAvatars users={users} following={following} onFollowingChange={setFollowing} />
      </div>
      <div className="rounded-2xl border border-line bg-canvas p-1.5">
        <ScrollArea orientation="both" className="h-72">
        <LiveCursors users={users} following={following} className="h-[1200px] w-[1800px] [background-image:radial-gradient(var(--color-line)_1px,transparent_1px)] [background-size:16px_16px]" />
      </ScrollArea>
      </div>
    </div>
  )
}
```

A board larger than its view. Press Ada's avatar to follow her: her cursor is scrolled into view as she moves. Press it again to stop.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add live-cursors
```

It brings `avatar`, `tooltip`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-labels-live-cursors`, `youj-presets`, `youj-ui-core` with it.

Use live cursors on anything several people work on at once: a design canvas, a whiteboard, a shared document, a dashboard being reviewed together. Youj has no transport of its own: you send the local pointer over whatever you already use (WebSockets, WebRTC, Liveblocks, Supabase Realtime, a CRDT's awareness) and pass everyone else back in.

```tsx
import { LiveCursors, PresenceAvatars, useLiveCursorsInput, type LiveCursorUser } from '@youj/react'

const surface = useRef<HTMLDivElement>(null)
const [others, setOthers] = useState<LiveCursorUser[]>([])
const [following, setFollowing] = useState<string | null>(null)

// Send your pointer: { x, y } in fractions of the surface, or null when it leaves.
useLiveCursorsInput(surface, (position) => channel.send({ id: me.id, name: me.name, ...position }))
// Receive everyone else's into `others` (leave yourself out).
useEffect(() => channel.onPresence(setOthers), [])

<PresenceAvatars users={others} following={following} onFollowingChange={setFollowing} />
<LiveCursors ref={surface} users={others} following={following}>
  <Canvas />
</LiveCursors>
```

`LiveCursors` wraps the surface (it renders a `relative` box around its children) and draws a cursor for each person in `users` with an `x` and `y`. Positions are fractions of the surface, 0 to 1 from the top left, so a person on a wide screen and one on a phone point at the same spot. Leave `x` and `y` out while someone's pointer is elsewhere and their cursor goes; remove them from `users` when they leave.

Each person has a `color`, by default one of the theme's five chart colors picked from their `id`, so every screen gives them the same one. Five colors mean two people can share one; pass `color` (a slot your server hands out, say) where they must differ. The name tag's text turns black or white for contrast. A `message` shows as a chat bubble under the name, and `selection` draws their selected areas as tinted rectangles.

Updates can be sparse: each cursor springs to its newest position, all of them on one animation loop that stops when they rest or the surface scrolls out of view. A cursor that hasn't moved for `idleAfter` milliseconds (10 seconds by default; `0` keeps them) fades out until it moves or speaks again.

`useLiveCursorsInput(ref, onMove, { throttle })` reports the pointer at most every `throttle` milliseconds (50 by default), always ending on the last move, and `null` when it leaves the surface.

`PresenceAvatars` shows who is here, with each person's color as a ring and their `status` ("Viewing" or "Editing") in a tooltip. Give it `following` and `onFollowingChange` and each avatar becomes a button that follows that person: pass the same `following` to `LiveCursors`, which scrolls their cursor into view as they move. Without them, the avatars only show who's here. Past `max` (5) the rest are counted.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### LiveCursors

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `users` (required) | `readonly LiveCursorUser[]` |  | Everyone else on the surface. Leave the local person out. |
| `following` | `string \| null` |  | The id of a person to follow: their cursor is scrolled into view as it moves. Pair it with PresenceAvatars' `following`. |
| `idleAfter` | `number` | `DEFAULT_IDLE` | Milliseconds without a move (or a new message) before a cursor fades out. `0` keeps every cursor. |
| `announce` | `boolean` | `true` | Announce joins and leaves in a polite live region. |
| `locale` | `string` |  | Formats the announced lists of names. Default: the YoujProvider locale. |

Also takes the props of `ComponentProps<'div'>`.

#### PresenceAvatars

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `users` (required) | `readonly LiveCursorUser[]` |  | Everyone here, in the order to show them. |
| `max` | `number` | `5` | Avatars shown before "+N". |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` |  |
| `following` | `string \| null` |  | The id of the person being followed, or `null`. Controlled. |
| `defaultFollowing` | `string \| null` | `null` | The person followed at first. |
| `onFollowingChange` | `(id: string \| null) => void` |  | Called with an id when an avatar is pressed, and `null` when it's pressed again. Leave it out, and `following` too, for avatars that only show who's here. |
| `label` | `string` |  | The group's name. Default: the labels' "People here". |

Also takes the props of `ComponentProps<'div'>`.

#### LiveCursorUser

| Field | Type | |
| --- | --- | --- |
| `id` | `string` | Stable across updates: it keys the cursor and picks the color. |
| `name` | `string` | The name tag. |
| `x`, `y` | `number` | Where their pointer is, as fractions of the surface. Leave both out while it's elsewhere. |
| `color` | `string` | Any CSS color. Default: a chart color chosen by `id`. |
| `message` | `string` | A chat bubble under the name. |
| `selection` | `LiveCursorRect[]` | Selected areas, `{ x, y, width, height }` in fractions. |
| `status` | `'viewing' \| 'editing'` | Shown in PresenceAvatars' tooltip. |
| `src` | `string` | An avatar image. |

### Styling

Parts: `live-cursors` (with `data-yj-following` while a placed person is followed), `live-cursors-overlay`, `live-cursor` (with `data-yj-idle` once faded and `data-yj-following`), `live-cursor-name`, `live-cursor-message`, `live-cursor-selection`, `live-cursors-follow-anchor`, `presence-avatars`, `presence-avatar` (with `data-status`: `viewing` or `editing`, and `aria-pressed` while followed) and `presence-avatars-more`. Each cursor, selection and avatar sets `--ui--live-cursor` to the person's color. The overlay is left to right whatever the page's direction: a position is the same spot on every screen.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Cursor moves | `spring.snappy` | 0.2s, bounce 0 | each cursor springs to its newest position, all on one animation loop that stops when they rest or the surface is off screen |
| Someone arrives or leaves | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the cursor scales up from its tip, or shrinks away |
| Chat bubble | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | pops in under the name and out when the message clears |
| Idle | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | a cursor that stops moving fades out after idleAfter |

**Reduced motion:** Cursors jump to each update, and appear, go idle and leave at once.

#### Reduced motion

Each cursor jumps to its newest position; cursors, bubbles and selections appear and go without fades or scaling, and following scrolls without smoothing.

### Accessibility

- The cursors, bubbles and selections are decorative and hidden from screen readers; the surface's own content stays as it is.
- A polite live region announces who joined and who left ("Joan and Kenji joined. Grace left"), not who was already there. Turn it off with `announce={false}` where the app announces presence itself.
- PresenceAvatars is a group named "People here" (or `label`). With following, each avatar is a toggle button named "Follow Ada", pressed while followed, and starting to follow is announced ("Following Ada"); without it, each is an image named with the person and their status ("Ada, Editing").
- Its words come from the labels (`liveCursorsJoined`, `liveCursorsLeft`, `liveCursorsPeople`, `liveCursorsViewing`, `liveCursorsEditing`, `liveCursorsFollow`, `liveCursorsFollowing` and `liveCursorsMore`), translated by the language packs; lists of names are formatted by Intl in the locale.

---

# Segmented Ring

> Show a sequence of segments as arcs with the current one in the center, such as the intervals of a workout.

Source: https://www.youj.dev/docs/components/segmented-ring

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Button, SegmentedRing, type SegmentedRingInterval } from '@youj/react'

const INTERVALS: SegmentedRingInterval[] = [
  { kind: 'warmup', duration: 30, label: 'Mobility' },
  ...['Jump squats', 'Burpees', 'Mountain climbers', 'Push-ups'].flatMap((label, i, all): SegmentedRingInterval[] => [
    { kind: 'work', duration: 20, label },
    ...(i < all.length - 1 ? [{ kind: 'rest', duration: 10 } as SegmentedRingInterval] : []),
  ]),
  { kind: 'cooldown', duration: 30, label: 'Stretch' },
]
const TOTAL = INTERVALS.reduce((sum, i) => sum + i.duration, 0)
const STARTS = INTERVALS.reduce<number[]>((acc, i) => [...acc, (acc.at(-1) ?? 0) + i.duration], [])

export default function SegmentedRingDemo() {
  // The ring keeps no clock of its own: run one, and pause or skip it by changing `elapsed`.
  const [elapsed, setElapsed] = useState(42)
  const [running, setRunning] = useState(false)
  useEffect(() => {
    if (!running) return
    const id = setInterval(() => setElapsed((t) => Math.min(TOTAL, t + 0.1)), 100)
    return () => clearInterval(id)
  }, [running])
  // The workout's over: the clock stops, and Restart is the one thing left to do.
  const done = elapsed >= TOTAL
  useEffect(() => {
    if (done) setRunning(false)
  }, [done])

return (
    <div className="flex w-full max-w-xs flex-col items-center gap-5">
      <SegmentedRing intervals={INTERVALS} elapsed={elapsed} />
      <div className="flex gap-2">
        <Button variant="secondary" disabled={done} onClick={() => setElapsed((t) => STARTS.find((s) => s > t) ?? TOTAL)}>
          Skip
        </Button>
        <Button onClick={() => (done ? (setElapsed(0), setRunning(true)) : setRunning((r) => !r))}>{running ? 'Pause' : done ? 'Restart' : 'Start'}</Button>
      </div>
    </div>
  )
}
```

A workout of a warm-up, four rounds of work and rest, and a cool-down, with a clock you start, pause or skip.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add segmented-ring
```

It brings `icon-check`, `use-announcer`, `youj-core`, `youj-labels-segmented-ring`, `youj-presets`, `youj-ui-core` with it.

Use an segmented ring for anything that runs in timed intervals: HIIT and Tabata, a pomodoro day, a breathing exercise. Each interval is an arc as long as it lasts, round the ring clockwise from the top inside a ruler of ten-second ticks. Work and rest take their own chart colors, and warm-up and cool-down share a third: intervals behind you are lit, the one running fills with a bright head at its edge, and the ones ahead wait in a dim wash of their color, so the shape of the whole session reads at a glance. The center holds the round in big mono, the phase and the time left in it. For a day of scheduled jobs, use a [Day Ring](https://www.youj.dev/docs/components/day-ring).

```tsx
import { SegmentedRing, type SegmentedRingInterval } from '@youj/react'

const intervals: SegmentedRingInterval[] = [
  { kind: 'warmup', duration: 60 },
  { kind: 'work', duration: 40, label: 'Kettlebell swings' },
  { kind: 'rest', duration: 20 },
  { kind: 'work', duration: 40, label: 'Goblet squats' },
]

<SegmentedRing intervals={intervals} elapsed={seconds} />
```

The ring keeps no clock of its own: `elapsed` is the seconds since the session started, so run your own timer and pause, skip or rewind it by changing `elapsed`. `duration` is in seconds, `kind` picks the phase and its color (or give an interval its own `tone`), and `label` names what's done in it, spoken as the interval starts. The round counts work intervals: a warm-up leads into round 1, and a rest belongs to the round before it.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intervals` (required) | `SegmentedRingInterval[]` |  |  |
| `elapsed` (required) | `number` |  | Seconds since the session started. |
| `label` | `string` |  | Accessible name. Default: the labels' "Interval timer". |
| `locale` | `string` |  | Default: the YoujProvider locale. |
| `sound` | `boolean` | `true` | Plays the notify cue as an interval starts, a tick in its last three seconds and success at the end. |

Also takes the props of `ComponentProps<'div'>`.

### Styling

Parts: `segmented-ring` (with `data-phase`), `segmented-ring-svg`, `segmented-ring-ruler`, `segmented-ring-segment` (with `data-kind` and `data-state`), `segmented-ring-progress`, `segmented-ring-head`, `segmented-ring-center`, `segmented-ring-label`, `segmented-ring-value`, `segmented-ring-phase` and `segmented-ring-summary`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Clock | `duration.instant`, `ease.standard` | 80ms; cubic-bezier(0.2, 0, 0, 1) | the running arc and its head follow `elapsed` directly |
| New round | `spring.snappy` | 0.2s, bounce 0 | the round number rolls up to the next |

**Reduced motion:** The round changes in place; the ring follows the clock either way.

#### Reduced motion

The round number changes in place. The ring still follows the clock, since that's information, not decoration.

### Accessibility

- The ring is a group named by `label` (default: the labels' "Interval timer"), with a summary of the round, the phase and the time left ("Round 3 of 8. Work, 0:24 left").
- As an interval starts, a polite live region announces its phase, its length and what follows ("Rest, 0:20. Next: Goblet squats."), and the end is announced too.
- Sound: the notify cue plays as each interval starts, a tick in each of its last three seconds, and success at the end, behind `sound` (on by default). A rewind stays quiet.
- Its words come from the labels (`intervalTimer`, `intervalWork`, `intervalRest`, `intervalWarmup`, `intervalCooldown`, `intervalRound`, `intervalRoundOf`, `intervalLeft`, `intervalStarted`, `intervalFinished`, `intervalNext`), translated by the language packs.
- A dial turns clockwise in every script, so the ring keeps its direction under RTL; the center's text follows the page.

---

# Refill Meter

> Show capacity that drains with use and refills over time, such as a rate limit’s token bucket.

Source: https://www.youj.dev/docs/components/refill-meter

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { RefillMeter, Button } from '@youj/react'

const CAPACITY = 60
const REFILL = 10

export default function RefillMeterDemo() {
  // What the gateway last reported: the tokens left and when it measured them.
  const [bucket, setBucket] = useState<{ value: number; at?: number }>({ value: 44 })

const send = (requests: number) => {
    const now = Date.now()
    // The bucket refilled since the last report; the requests spend from there.
    const level = Math.min(CAPACITY, bucket.value + (bucket.at ? ((now - bucket.at) / 1000) * REFILL : 0))
    setBucket({ value: Math.max(0, level - requests), at: now })
  }

return (
    <div className="flex w-full max-w-lg flex-col gap-5">
      <RefillMeter label="checkout-svc" value={bucket.value} updatedAt={bucket.at} capacity={CAPACITY} refillRate={REFILL} burst={20} />
      <div className="flex gap-2">
        <Button variant="secondary" size="sm" onClick={() => send(10)}>
          Send 10 requests
        </Button>
        <Button variant="secondary" size="sm" onClick={() => send(40)}>
          Send a burst of 40
        </Button>
      </div>
    </div>
  )
}
```

A gateway's bucket of 60 tokens refilling 10 a second, with buttons that spend 10 requests or a burst of 40.

### Burst and empty

```tsx
'use client'

import { RefillMeter } from '@youj/react'

export default function RefillMeterBurst() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-8">
      {/* Under the burst marker: a batch of 25 would be partly refused, so the cells turn amber. */}
      <RefillMeter label="batch-sync" value={14} capacity={40} refillRate={5} burst={25} />
      {/* Empty with no refill: every request is refused until the window resets. */}
      <RefillMeter label="POST /v1/embeddings" value={0} capacity={20} />
    </div>
  )
}
```

Two buckets: one under its burst marker, and one empty with no refill.

`burst` puts a marker in the bucket: the burst allowance, the most a client may send at once. While the level is under it, a full burst would be partly refused, so the lit cells turn to the warning tone and the value is spoken with "under the burst of 20". An empty bucket tints its track danger; with no refill it reads "Empty".

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add refill-meter
```

It brings `youj-core`, `youj-labels-refill-meter`, `youj-presets`, `youj-ui-core` with it.

Use a refill meter where a client, a key or an endpoint spends from a token bucket: how much it can still send right now, and how fast that room comes back. Each cell is a token (or a share of a large bucket), lit while it's in the bucket. Requests drain cells from the edge; between the updates you give it, the bucket refills on its own at `refillRate`, and the edge cell charges from its foot as the next token accrues. For a quota that only resets with the period, use an [Limit Meter](https://www.youj.dev/docs/components/limit-meter); for usage of a resource, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter).

```tsx
import { RefillMeter } from '@youj/react'

// What the gateway reported: 38 tokens left at `measuredAt`, refilling 10 a second.
<RefillMeter value={38} updatedAt={measuredAt} capacity={60} refillRate={10} burst={20} />
```

Give it what you measured: `value` tokens at `updatedAt` (a `Date.now()` time; by default, when `value` last changed). It counts the refill from there, so there's no need to poll to keep it moving, and a new measurement simply resets the count. The refill stops at `capacity`, while the meter is off screen and in a hidden tab, and catches up when it's back.

It draws a cell a token up to 60 cells; a larger bucket shares its capacity across 60 (set `segments` for another count), and the charging cell fills by its share.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | Tokens in the bucket when it was measured (at `updatedAt`). |
| `capacity` (required) | `number` |  | The bucket's size: the most tokens it holds, so the largest burst it lets through at once. |
| `refillRate` | `number` | `0` | Tokens earned back each second. |
| `updatedAt` | `number` |  | When `value` was measured, as a `Date.now()` time, so the refill counts from then. Default: when `value` last changed. |
| `burst` | `number` |  | A marker at this many tokens: the burst a client should keep room for. Under it the lit cells turn to the warning tone. |
| `segments` | `number` |  | How many cells. Default: one per token, up to 60. |
| `label` | `ReactNode` |  | The visible name on the start side. Default: the labels' "Tokens". |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `MeterPrimitive.Root.Props`.

### Styling

Parts: `refill-meter`, `refill-meter-header`, `refill-meter-label`, `refill-meter-value`, `refill-meter-capacity`, `refill-meter-gauge`, `refill-meter-flags`, `refill-meter-burst-flag`, `refill-meter-track`, `refill-meter-cell`, `refill-meter-fill`, `refill-meter-burst`, `refill-meter-reserve`, `refill-meter-footer`, `refill-meter-refill`, `refill-meter-eta` and `refill-meter-term` (the words in the footer). The root has `data-state` (`ok`, `low` or `empty`) and `data-full`; each cell has `data-state` (`on`, `charging` or `off`). The labels take the theme's label voice, and mono capitals in Bezel.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Refill |  | the refill rate | the edge cell fills from its foot as the next token accrues, then locks in; the clock follows the time scale and stops while full, off screen or hidden |
| Spend | `duration.deliberate` | 560ms | the cells drain from the edge inward at a constant rate, the whole row spanning the deliberate token, each falling to its foot |
| Each cell | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | falls or rises, and takes its tone |
| New value mid-drain | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | carries on from the edge on screen, so a burst of updates never jumps |

**Reduced motion:** The bucket still refills (it's data), a whole token at a time, with no charging cell and no drain: cells change in place.

#### Reduced motion

The level still refills, a whole token at a time; there's no charging cell and no drain, and cells change in place.

### Accessibility

- It's a `meter` (Base UI Meter) named by its visible `label` (by default the labels' "Tokens").
- Its value is spoken as "42 of 60 tokens, refilling 10 a second", with "under the burst of 20" while under the marker and "Empty" when there's nothing left. It updates a whole token at a time, never every frame.
- The cells, the marker and the charging fill are hidden from assistive tech. The bucket fills from the inline start, so right to left in RTL; its figures keep their order.
- Its built-in text comes from the labels, so `<YoujProvider labels>` translates it.

---

# Day Rail

> Show typed segments and time-zone changes on a daily timeline, such as a trip’s flights and stays.

Source: https://www.youj.dev/docs/components/day-rail

## Examples

### Demo

```tsx
'use client'

import { ItineraryDay, DayRail, type ItineraryLeg, type ItineraryStay, type ItineraryStop } from '@youj/react'

/** A time as it reads on the clocks at a place `offset` minutes from UTC. */
const local = (month: number, day: number, hh: number, mm: number, offset: number) => Date.UTC(2026, month - 1, day, hh, mm) - offset * 60_000
const LIS = 60
const CET = 120

const STOPS: ItineraryStop[] = [
  { id: 'lis', code: 'LIS', name: 'Lisbon', utcOffset: LIS },
  { id: 'bcn', code: 'BCN', name: 'Barcelona', utcOffset: CET },
  { id: 'fco', code: 'FCO', name: 'Rome', utcOffset: CET },
]

const LEGS: ItineraryLeg[] = [
  { id: 'out', from: 'lis', to: 'bcn', depart: local(9, 30, 9, 40, LIS), arrive: local(9, 30, 12, 55, CET), code: 'TP 1036' },
  { id: 'hop', from: 'bcn', to: 'fco', depart: local(10, 3, 14, 20, CET), arrive: local(10, 3, 16, 10, CET), code: 'VY 6104' },
  { id: 'home', from: 'fco', to: 'lis', depart: local(10, 5, 16, 20, CET), arrive: local(10, 5, 18, 25, LIS), code: 'TP 839' },
]

const STAYS: ItineraryStay[] = [
  { id: 'bonay', at: 'bcn', start: local(9, 30, 15, 0, CET), end: local(10, 3, 11, 0, CET), name: 'Casa Bonay' },
  { id: 'vilon', at: 'fco', start: local(10, 3, 17, 0, CET), end: local(10, 5, 11, 0, CET), name: 'Hotel Vilòn' },
]

const PLANS = [
  'Fly to Barcelona at 09:40, then check in at Casa Bonay.',
  'Sagrada Família at 10:30, tapas at El Xampanyet at 20:30.',
  'Montjuïc cable car at 12:00. The afternoon is free.',
  'Check out by 11:00, fly to Rome at 14:20.',
  'Vatican Museums, early entry at 08:00.',
  'Check out by 11:00, fly home at 16:20.',
]

export default function DayRailDemo() {
  // `now` pins the line mid-flight to Rome; leave it out and the line follows the clock.
  return (
    <div className="w-full max-w-3xl rounded-2xl border border-line bg-surface p-5">
      <DayRail stops={STOPS} legs={LEGS} stays={STAYS} start={local(9, 30, 0, 0, LIS)} days={6} now={local(10, 3, 15, 10, CET)}>
        {PLANS.map((plan, d) => (
          <ItineraryDay key={d} value={d}>
            <p className="text-ui-sm text-fg-muted">{plan}</p>
          </ItineraryDay>
        ))}
      </DayRail>
    </div>
  )
}
```

A six-day trip through Lisbon, Barcelona and Rome with its flights, stays and a plan for each day, pinned mid-flight to Rome.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add day-rail
```

It brings `icon-plane`, `use-now`, `youj-core`, `youj-labels-day-rail`, `youj-presets`, `youj-ui-core` with it.

Use an day rail for a trip, or anything that moves between places over a few days: a tour, a site visit, a move. Each day is a column and a tab. Flights arc over the rail from departure to arrival with their code at the top, and a change of clocks is marked beside the landing (+1 h). Stays sit under the rail as spans from check-in to check-out, in their stop's color, with their nights. Past legs are solid and quiet, the ones ahead dashed, and during a flight the plane rides its arc. Pick a day and its `ItineraryDay` panel shows under the rail. The [Trip block](https://www.youj.dev/docs/blocks/calendars-and-schedules#itinerary) lists each day's bookings there. For shifts across a week, use [Time Lanes](https://www.youj.dev/docs/components/time-lanes); for events that already happened, a [Timeline](https://www.youj.dev/docs/components/timeline).

```tsx
import { ItineraryDay, DayRail, type ItineraryLeg, type ItineraryStay, type ItineraryStop } from '@youj/react'

const stops: ItineraryStop[] = [
  { id: 'lis', code: 'LIS', name: 'Lisbon', utcOffset: 60 },
  { id: 'bcn', code: 'BCN', name: 'Barcelona', utcOffset: 120 },
]
const legs: ItineraryLeg[] = [
  { id: 'out', from: 'lis', to: 'bcn', depart: new Date('2026-09-30T08:40Z'), arrive: new Date('2026-09-30T10:55Z'), code: 'TP 1036' },
  { id: 'back', from: 'bcn', to: 'lis', depart: new Date('2026-10-03T12:20Z'), arrive: new Date('2026-10-03T14:35Z'), code: 'TP 1039' },
]
const stays: ItineraryStay[] = [
  { id: 'bonay', at: 'bcn', start: new Date('2026-09-30T13:00Z'), end: new Date('2026-10-03T09:00Z'), name: 'Casa Bonay' },
]

<DayRail stops={stops} legs={legs} stays={stays} start={new Date('2026-09-29T23:00Z')} days={4}>
  <ItineraryDay value={0}>Fly to Barcelona at 09:40.</ItineraryDay>
  <ItineraryDay value={1}>Sagrada Família at 10:30.</ItineraryDay>
</DayRail>
```

A stop is a place with a `code` for the rail, a `name` for the words, and its `utcOffset` in minutes, which sets how its times read and marks the change of clocks on landing. A leg flies `from` one stop `to` another between `depart` and `arrive`, with an optional flight `code`. A stay sits `at` a stop from `start` to `end`, and takes its stop's `tone` (the chart colors in turn by default). A flight is hours on a rail of days, so its arc is drawn at least a twelfth of the rail wide around its middle; the exact times are in the words.

`start` is the first moment shown, the first day's midnight at the first stop, and `days` how many follow (7 by default). `now` places the line: by default it follows the clock, read every 30 seconds once the page is live; pass a time to pin it, or `null` to hide it. The day shown starts on today while the trip is under way and on the first day otherwise; set it with `defaultValue`, or control it with `value` and `onValueChange`. Each `ItineraryDay` takes the `value` of its day, from 0.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stops` (required) | `ItineraryStop[]` |  |  |
| `legs` (required) | `ItineraryLeg[]` |  |  |
| `stays` | `ItineraryStay[]` | `[]` |  |
| `start` (required) | `Date \| number` |  | The first moment shown: the first day's midnight, at the first stop. |
| `days` | `number` | `7` | Days shown. |
| `now` | `Date \| number \| null` |  | Where the now line sits. Default: the clock, read every 30 s once the page is live. `null` hides it. |
| `value` | `number` |  | The day shown, from 0. Controlled. |
| `defaultValue` | `number` |  | The day shown first. Default: today, if the trip is under way, else the first day. |
| `onValueChange` | `(day: number) => void` |  |  |
| `label` | `string` | `"Itinerary"` | The rail's accessible name. |
| `locale` | `string` |  | Default: the YoujProvider locale. |

Also takes the props of `TabsPrimitive.Root.Props`.

Takes the props of `TabsPrimitive.Panel.Props`.

### Styling

Parts: `day-rail`, `day-rail-scroll`, `day-rail-days`, `day-rail-day` (with `data-today`), `day-rail-label`, `day-rail-value`, `day-rail-track`, `day-rail-sky`, `day-rail-arc` (with `data-state`: `past`, `flying` or `upcoming`), `day-rail-code`, `day-rail-plane`, `day-rail-line`, `day-rail-node`, `day-rail-stop`, `day-rail-shift`, `day-rail-stays`, `day-rail-stay`, `day-rail-now`, `day-rail-summary` and `day-rail-panel`. A stay's color is `--stay-tone`. Below 34rem the rail scrolls sideways.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| First view | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | flown and flying arcs draw in along their length, one after another; the arcs ahead fade in |
| Clock tick | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the now line and the plane on its arc glide to their new places |
| Day picked | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the day’s underline grows from its center |

**Reduced motion:** The arcs are drawn, and the plane and the now line jump to each new time.

#### Reduced motion

The arcs are drawn from the start, and the now line and the plane jump to each new time instead of gliding.

### Accessibility

- The days are a tab list named by `label` (default: the labels' "Itinerary"); each day is a tab named by its number and date ("Day 4, Sat, Oct 3"), and its `ItineraryDay` is the tab panel.
- Left and right move between days (mirrored in RTL), Home and End go to the first and last.
- The drawing is hidden from screen readers. In its place a list gives every leg with its code, from where to where, its local times and any change of clocks ("VY 6104, Barcelona to Rome, Sat, Oct 3, 14:20 to Sat, Oct 3, 16:10"), and every stay with its stop and its nights.
- Its words come from the labels (`itinerary`, `itineraryDay`, `itineraryLeg`, `itineraryTimeShift`, `itineraryNights`, `itineraryNow` and `itineraryInTransit`), translated by the language packs.

---

# Chat

> Build AI chat interfaces with components that handle streaming answers.

Source: https://www.youj.dev/docs/components/chat

## Examples

### Demo

```tsx
'use client'

import { useCallback, useEffect, useRef, useState } from 'react'
import {
  ChatMessage,
  ChatMessageList,
  ChatReasoning,
  ChatToolCall,
  ChatTypingIndicator,
  PromptInput,
  createTextStream,
  type ChatFeedback,
  type ChatTextStream,
  type ChatToolStatus,
  type PromptStatus,
} from '@youj/react'

interface Message {
  id: string
  role: 'user' | 'assistant'
  content?: string | ChatTextStream
  streaming?: boolean
  thinking?: boolean
  stopped?: boolean
  feedback?: ChatFeedback
  reasoning?: { content: ChatTextStream; streaming: boolean; duration?: number }
  tool?: { status: ChatToolStatus; result?: unknown; duration?: number }
}

const HISTORY: Message[] = [
  { id: 'h1', role: 'user', content: 'Our checkout got slower after Tuesday. Where should I look first?' },
  {
    id: 'h2',
    role: 'assistant',
    feedback: 'up',
    content:
      'Start with what changed on Tuesday. The second deployment moved `checkout` to the edge runtime, and p95 rose in **fra1** only, from 97 ms to 164 ms. Rolling back to `dpl_7c1e0b2` is safe.',
  },
]

const QUESTION = 'How do I ship orion to production with a safe rollback?'

const REASONING =
  'They want a production deploy with a way back. Check the latest deployments for orion first, so the steps match its real state, then list the checks, the command and where rollbacks live.'

const ANSWER = `Here's the path for **orion**, with a rollback ready at every step.

1. Run the checks: \`pnpm verify\`
2. Open a preview and review it with the team
3. Merge to \`main\`, which builds production

\`\`\`ts
const release = await deploy({ project: 'orion', target: 'production' })
\`\`\`

| Region | Cold start | p95 |
| :----- | ---------: | --: |
| iad1 | 112 ms | 84 ms |
| fra1 | 131 ms | 97 ms |

> Every deployment keeps its build, so promoting the previous one takes seconds.`

/** "Deploying to iad1" → ["Depl", "oyin", "g", " to", " iad1"]: a model's tokens, roughly. */
const tokenize = (text: string) => text.match(/\s*\S{1,4}|\s+/g) ?? []

export default function ChatDemo() {
  const [messages, setMessages] = useState<Message[]>(HISTORY)
  const [status, setStatus] = useState<PromptStatus>('idle')
  // Each reply runs under a generation number: stopping or unmounting bumps it, and the reply notices.
  const generation = useRef(0)
  const timers = useRef(new Set<ReturnType<typeof setTimeout>>())
  const replying = useRef<string | null>(null)

const patch = (id: string, next: Partial<Message>) => setMessages((list) => list.map((m) => (m.id === id ? { ...m, ...next } : m)))

const cancel = useCallback(() => {
    generation.current++
    for (const timer of timers.current) clearTimeout(timer)
    timers.current.clear()
  }, [])

// biome-ignore lint/correctness/useExhaustiveDependencies: deps are chosen by hand
  const reply = useCallback(
    async (id: string) => {
      const mine = ++generation.current
      const alive = () => generation.current === mine
      const sleep = (ms: number) =>
        new Promise<boolean>((resolve) => {
          const timer = setTimeout(() => {
            timers.current.delete(timer)
            resolve(alive())
          }, ms)
          timers.current.add(timer)
        })
      const type = async (stream: ChatTextStream, text: string) => {
        for (const token of tokenize(text)) {
          if (!(await sleep(22))) return false
          stream.append(token)
        }
        return true
      }

replying.current = id
      setStatus('submitted')
      if (!(await sleep(700))) return

const reasoning = createTextStream()
      setStatus('streaming')
      patch(id, { thinking: false, reasoning: { content: reasoning, streaming: true } })
      if (!(await type(reasoning, REASONING))) return
      patch(id, { reasoning: { content: reasoning, streaming: false, duration: 3 }, tool: { status: 'running' } })

if (!(await sleep(900))) return
      patch(id, { tool: { status: 'success', duration: 840, result: { latest: 'dpl_9f3a2c1', state: 'ready', regions: ['iad1', 'fra1'] } } })

const answer = createTextStream()
      patch(id, { content: answer })
      if (!(await type(answer, ANSWER))) return
      patch(id, { streaming: false })
      replying.current = null
      setStatus('idle')
    },
    [],
  )

const ask = (text: string, fresh = false) => {
    const n = Date.now()
    const question: Message = { id: `q${n}`, role: 'user', content: text }
    const answer: Message = { id: `a${n}`, role: 'assistant', streaming: true, thinking: true }
    setMessages((list) => [...(fresh ? HISTORY : list), question, answer])
    void reply(answer.id)
  }

// The preview opens mid-conversation: the question goes out on mount.
  // biome-ignore lint/correctness/useExhaustiveDependencies: deps are chosen by hand
  useEffect(() => {
    ask(QUESTION, true)
    return cancel
  }, [])

const stop = () => {
    cancel()
    const id = replying.current
    if (id) {
      setMessages((list) =>
        list.map((m) =>
          m.id === id
            ? { ...m, streaming: false, thinking: false, stopped: true, reasoning: m.reasoning && { ...m.reasoning, streaming: false } }
            : m,
        ),
      )
    }
    replying.current = null
    setStatus('idle')
  }

return (
    <div className="flex h-[600px] w-full flex-col bg-canvas">
      <ChatMessageList>
        {messages.map((m) => (
          <ChatMessage
            key={m.id}
            role={m.role}
            name={m.role === 'assistant' ? 'Youj' : 'Ada Lovelace'}
            content={m.content}
            streaming={m.streaming}
            incomplete={m.stopped}
            feedback={m.role === 'assistant' ? (m.feedback ?? null) : undefined}
            onFeedbackChange={m.role === 'assistant' ? (feedback) => patch(m.id, { feedback }) : undefined}
          >
            {m.thinking && <ChatTypingIndicator />}
            {m.reasoning && <ChatReasoning content={m.reasoning.content} streaming={m.reasoning.streaming} duration={m.reasoning.duration} />}
            {m.tool && (
              <ChatToolCall
                name="get_deployments"
                args={{ project: 'orion', limit: 3 }}
                status={m.tool.status}
                result={m.tool.result}
                duration={m.tool.duration}
              />
            )}
          </ChatMessage>
        ))}
      </ChatMessageList>
      <div className="mx-auto w-full max-w-3xl px-4 pb-4">
        <PromptInput status={status} onStop={stop} onSubmit={({ text }) => ask(text)} />
      </div>
    </div>
  )
}
```

A full conversation: a short history, a streamed answer with reasoning and a tool call, and a composer.

In the preview, a question goes out on load. The answer thinks out loud, calls a tool, then streams markdown with code and a table while the list follows it. Scroll up mid-answer to take over, or press stop.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

It brings `async-feedback`, `avatar`, `badge`, `button`, `card`, `code-block`, `collapse`, `collapsible`, `empty`, `field`, `hover-card`, `icon-alert-triangle`, `icon-arrow-down`, `icon-arrow-up`, `icon-check`, `icon-clock`, `icon-copy`, `icon-eye`, `icon-eye-off`, `icon-file-text`, `icon-hourglass`, `icon-lightbulb`, `icon-loader-dots`, `icon-octagon-alert`, `icon-paperclip`, `icon-pencil`, `icon-refresh`, `icon-shield-alert`, `icon-shield-check`, `icon-sparkles`, `icon-swap`, `icon-terminal`, `icon-thumbs-up`, `icon-x`, `input`, `input-group`, `kbd`, `morph-label`, `presence-list`, `reveal`, `scroll-area`, `spinner`, `stagger`, `text-split`, `textarea`, `toggle`, `tooltip`, `use-announcer`, `use-now`, `youj-core`, `youj-labels-chat-citation`, `youj-labels-chat-copy-button`, `youj-labels-chat-markdown`, `youj-labels-chat-message`, `youj-labels-chat-message-list`, `youj-labels-chat-prompt-input`, `youj-labels-chat-suggestions`, `youj-labels-chat-thinking`, `youj-labels-chat-tool-approval`, `youj-labels-chat-tool-call`, `youj-presets`, `youj-ui-core` with it.

The copy is 75 registry items, about 17,200 lines in all, 5,256 of them the shared `youj-core`. Beyond the shared ones it brings `async-feedback`, `avatar`, `badge`, `button`, `card`, `code-block`, `collapse`, `collapsible`, `empty`, `field` and 47 more.

The whole kit is one registry item and one import. It's built on Youj's own [Scroll Area](https://www.youj.dev/docs/components/scroll-area), [Button](https://www.youj.dev/docs/components/button), [Input Group](https://www.youj.dev/docs/components/input-group), [Hover Card](https://www.youj.dev/docs/components/hover-card) and [Collapsible](https://www.youj.dev/docs/components/collapsible), and on motion's [Presence List](https://www.youj.dev/docs/motion/presence-list), [Collapse](https://www.youj.dev/docs/motion/collapse), [Morph Label](https://www.youj.dev/docs/motion/morph-label) and [Stagger](https://www.youj.dev/docs/motion/stagger).

The chat kit is the set of parts an assistant is made of: a conversation that stays with a streaming answer, messages with actions, streamed markdown, a composer, thinking and reasoning, tool calls, citations, suggestions and a first-run greeting. It doesn't talk to a model. You bring the stream from any SDK and hand it to the parts, and they handle the hard details: following the answer without fighting the reader, announcing a reply once instead of token by token, and keeping a model's output from ever becoming markup.

A screen is a `ChatMessageList` of keyed `ChatMessage`s over a `PromptInput`. Whatever the assistant does before its text (thinking, reasoning, tool calls) goes inside its message as children.

```tsx
import { ChatMessage, ChatMessageList, ChatToolCall, PromptInput } from '@youj/react'

export function Assistant({ messages, status, send, stop }: AssistantProps) {
  return (
    <div className="flex h-dvh flex-col">
      <ChatMessageList>
        {messages.map((m) => (
          <ChatMessage key={m.id} role={m.role} content={m.text} streaming={m.streaming}>
            {m.tools.map((t) => (
              <ChatToolCall key={t.id} name={t.name} args={t.args} status={t.status} result={t.result} />
            ))}
          </ChatMessage>
        ))}
      </ChatMessageList>
      <PromptInput status={status} onStop={stop} onSubmit={({ text }) => send(text)} />
    </div>
  )
}
```

`content` takes a string, or a `ChatTextSource`: any object with `getSnapshot()` and `subscribe()`. Pass a string and every token re-renders the message. Pass a source and a token re-renders only the text that reads it, not the message, its siblings or the list. `createTextStream()` is the smallest source you can write to.

```tsx
import { createTextStream } from '@youj/react'

const stream = createTextStream()
for await (const token of reply) stream.append(token)
```

Keep one stream per reply, created when the reply starts, and set `streaming` to `false` when it ends. That's when the list announces the whole answer.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

- [Message List](https://www.youj.dev/docs/components/chat/message-list): The scrolling conversation: follows a streaming answer, lets go when you scroll, groups by author.

- [Message](https://www.youj.dev/docs/components/chat/message): One message: an answer, a bubble or a notice, with copy, regenerate, rating and edit.

- [Markdown](https://www.youj.dev/docs/components/chat/markdown): Streamed markdown that's safe by construction, with code, tables and a caret.

- [Prompt Input](https://www.youj.dev/docs/components/chat/prompt-input): The composer: a growing field, attachments, a toolbar, and send that morphs into stop.

- [Thinking](https://www.youj.dev/docs/components/chat/thinking): A typing indicator, and reasoning that folds away when it's done.

- [Tool Call](https://www.youj.dev/docs/components/chat/tool-call): A tool the assistant called: its arguments, its status and what came back.

- [Tool Approval](https://www.youj.dev/docs/components/chat/tool-approval): An agent asks before a risky action: the arguments, the risk, and Allow once, Always allow or Deny.

- [Citation](https://www.youj.dev/docs/components/chat/citation): Numbered sources in the text, previewed on hover, and a row of chips under the answer.

- [Suggestions](https://www.youj.dev/docs/components/chat/suggestions): A few good prompts, as chips or cards, arriving in sequence.

- [Chat Empty State](https://www.youj.dev/docs/components/chat/empty-state): A new conversation: a greeting and ways in.

### Reduced motion

The list jumps instead of gliding, messages appear in place, and streamed text arrives in whole sentences instead of word by word. Loops (the shimmer, the dots, the caret's blink) hold still, and every fold and morph is instant.

### Accessibility

- The conversation is a `log` that stays silent while an answer streams. The list speaks for it: "Youj is responding…" once, the whole answer when it's complete, and failures assertively.
- Every message is an `article` named by its author and time, so screen reader users can move between messages by landmark or heading.
- Actions on a message sit in one toolbar: a single tab stop, with arrow keys inside it.
- Enter sends and Shift+Enter breaks the line, and neither cuts an IME composition short.

---

# Chat Message List

> Follow streaming answers while letting people scroll back through the conversation.

Source: https://www.youj.dev/docs/components/chat/message-list

## Examples

### Demo

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { Button, ChatMessage, ChatMessageList, createTextStream, type ChatTextStream } from '@youj/react'

interface Message {
  id: string
  role: 'user' | 'assistant'
  content: string | ChatTextStream
  streaming?: boolean
}

const HISTORY: Message[] = [
  { id: 'm1', role: 'user', content: 'Which regions is orion deployed to?' },
  { id: 'm2', role: 'assistant', content: 'Two: **iad1** (Washington, D.C.) and **fra1** (Frankfurt). Both serve production traffic.' },
  { id: 'm3', role: 'user', content: 'What would adding hnd1 cost?' },
  { id: 'm4', role: 'assistant', content: 'About **$44 per 10M requests**, a little more than iad1. Cold starts there average 148 ms.' },
]

const ANSWER = `Here's a rollout plan for **hnd1**, one step at a time.

1. Add the region to \`youj.json\` and open a preview.
2. Send 5% of Asia-Pacific traffic to it for a day.
3. Compare p95 with iad1. If it's within 20 ms, raise it to 50%.
4. Watch errors for an hour, then take the rest.

Each step keeps the previous deployment ready, so a rollback is one promote away. Scroll up while this streams: the list lets go, and **Jump to latest** brings you back.

- Latency budget: p95 under 120 ms
- Error budget: under 0.1% for an hour
- Cost check: under $50 per 10M requests

When all three hold, hnd1 is ready for the whole region.`

const tokenize = (text: string) => text.match(/\s*\S{1,4}|\s+/g) ?? []

export default function MessageListDemo() {
  const [messages, setMessages] = useState(HISTORY)
  const [busy, setBusy] = useState(false)
  const timer = useRef<ReturnType<typeof setInterval>>(undefined)
  useEffect(() => () => clearInterval(timer.current), [])

const ask = () => {
    const n = messages.length
    const stream = createTextStream()
    const id = `a${n}`
    setBusy(true)
    setMessages((list) => [...list, { id: `q${n}`, role: 'user', content: 'Plan the hnd1 rollout.' }, { id, role: 'assistant', content: stream, streaming: true }])
    const tokens = tokenize(ANSWER)
    let i = 0
    timer.current = setInterval(() => {
      stream.append(tokens[i++]!)
      if (i < tokens.length) return
      clearInterval(timer.current)
      setMessages((list) => list.map((m) => (m.id === id ? { ...m, streaming: false } : m)))
      setBusy(false)
    }, 45)
  }

return (
    <div className="flex h-[440px] w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-line bg-canvas">
      <ChatMessageList contentClassName="px-5">
        {messages.map((m) => (
          <ChatMessage key={m.id} role={m.role} name={m.role === 'assistant' ? 'Youj' : 'Ada Lovelace'} content={m.content} streaming={m.streaming} />
        ))}
      </ChatMessageList>
      <div className="flex items-center justify-end gap-2 border-t border-line px-3 py-2">
        <Button size="sm" onClick={ask} disabled={busy} focusableWhenDisabled>
          Ask for a rollout plan
        </Button>
      </div>
    </div>
  )
}
```

A short history and a button that asks for a rollout plan, which streams while the list follows it.

While an answer streams, the list sticks to the bottom: as content grows, the view glides after it on a spring that keeps its velocity as each line lands, and a resize (the composer growing, a window) keeps the bottom in place. Scroll up by wheel, touch, keys or the scrollbar and it lets go at once. Scroll back to the bottom and it holds again. Sending a message brings you back down.

Scrolled up, **Jump to latest** rises in above the composer, with a dot when something new arrived below. It glides you down and hands focus to the conversation, so a keyboard user isn't dropped when the button goes. Try it in the preview: ask for the plan, then scroll up while it streams.

Only the reader lets go of the bottom. A scroll they didn't make, such as the browser clamping as content shrinks or a font swapping in, doesn't unstick it.

### Grouping

```tsx
'use client'

import { ChatMessage, ChatMessageList, ChatTypingIndicator } from '@youj/react'

const at = (minutes: number) => new Date(Date.UTC(2026, 0, 15, 9, minutes))

export default function MessageListGrouping() {
  return (
    <div className="flex h-[420px] w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-line bg-canvas">
      <ChatMessageList contentClassName="px-5">
        <ChatMessage key="s" role="system" content="Youj Pro · this chat can read your deployments" timestamp={at(0)} />
        {/* Three in a row from you: one header, bubbles that tuck their corners in. */}
        <ChatMessage key="u1" role="user" name="Ada Lovelace" content="The fra1 deploy failed again." timestamp={at(2)} />
        <ChatMessage key="u2" role="user" name="Ada Lovelace" content="Same error as yesterday." timestamp={at(2)} />
        <ChatMessage key="u3" role="user" name="Ada Lovelace" content="Can you check the build log?" timestamp={at(2)} />
        <ChatMessage
          key="a1"
          role="assistant"
          name="Youj"
          timestamp={at(3)}
          content="It's the same failure: `sharp` can't find its binary for **linux-arm64**. The build image changed on Monday."
        />
        <ChatMessage key="a2" role="assistant" name="Youj" timestamp={at(3)} content="Pinning the image to `node-22-x64` fixes it. Want me to open a pull request?" />
        {/* Anything else can sit in the flow too, keyed like a message. */}
        <ChatTypingIndicator key="typing" variant="dots" />
      </ChatMessageList>
    </div>
  )
}
```

A system notice, three messages in a row from you and two replies, with a typing indicator at the end.

Consecutive messages from one author form a group: only the first shows its avatar and header, the rest sit closer, and user bubbles tuck their corners in where they meet. The list decides from each message's author (`role` and `name`), and anything else in the flow, like a typing indicator or suggestions, sits between messages as a keyed child.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use it for the scrolling part of any chat or assistant screen, with [Chat Messages](https://www.youj.dev/docs/components/chat/message) inside it. It owns the scroll behavior people notice when it's wrong: staying with an answer as it grows, stopping when they scroll up to read, and getting them back down. For a feed of events that doesn't stream, use a [Timeline](https://www.youj.dev/docs/components/timeline) or a list with [Presence List](https://www.youj.dev/docs/motion/presence-list).

```tsx
import { ChatMessage, ChatMessageList } from '@youj/react'

export function Conversation({ messages }: { messages: Message[] }) {
  return (
    <ChatMessageList aria-label="Conversation with Youj">
      {messages.map((m) => (
        <ChatMessage key={m.id} role={m.role} content={m.stream ?? m.text} streaming={m.streaming} />
      ))}
    </ChatMessageList>
  )
}
```

Give every child a stable `key`. The list fills its parent (`flex-1`, `min-h-0`), so put it in a flex column with a height, above the composer. `contentClassName` sets the width and padding of the column the messages sit in, which is centered at `max-w-3xl` by default.

`useChatMessageList()` returns the surrounding list's `scrollToBottom(behavior)` and its scroll `viewport`, for a custom jump control or a virtualizer. With a virtualizer, pass `animate={false}` so messages render as they are and the virtualizer positions the rows itself.

```tsx
import { useChatMessageList } from '@youj/react'

function BackToLatest() {
  const { scrollToBottom } = useChatMessageList()
  return <Button onClick={() => scrollToBottom('smooth')}>Back to latest</Button>
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | ChatMessages (keyed), and anything else in the flow: a typing indicator, suggestions. |
| `aria-label` | `string` | `"Conversation"` | Names the conversation for assistive tech. |
| `animate` | `boolean` | `true` | Animate messages in and out. Turn it off for a virtualizer. |
| `contentClassName` | `string` |  | Classes for the column the messages sit in (width, padding). |
| `jumpLabel` | `string` | `"Jump to latest"` | The jump button's label. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Follow | `spring.smooth` | 0.36s, bounce 0 | the scroll glides after new content, retargeting with its velocity |
| Message enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades and drops 6px into its slot (Presence List) |
| Others make room | `spring.smooth` | 0.36s, bounce 0 |  |
| Message leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades in place |
| Jump in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | rises 8px and scales from .96 as it fades in |
| Jump out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | drops 6px and fades |

**Reduced motion:** Following and jumping are instant, messages appear and disappear in place, and the jump button shows and hides at once.

A token that arrives as new text re-renders only its own message's slot, never the list, so the enter and make-room motion runs only when messages come, go or move.

#### Reduced motion

The view jumps to new content instead of gliding, and Jump to latest takes you down at once. New messages appear in place, and the button shows and hides without a rise. Sticking, letting go and the announcements are unchanged.

### Accessibility

- The column is a `log` with `aria-live="off"`, inside a scroll area named by `aria-label` (default "Conversation"). A streaming answer is never read token by token.
- The list announces for its messages through its own live regions: "Youj is responding…" once when a reply starts, the whole answer as plain text when it's complete, and failures assertively. Messages already there when the list mounts are history and aren't announced.
- The scroll viewport is focusable, so arrow keys, Page Up and Home scroll it, and scrolling up by key lets go of the bottom like a wheel does.
- **Jump to latest** is a real button. Pressing it moves focus to the conversation before the button leaves.

---

# Chat Message

> Display a conversation turn with actions such as copy, regenerate, rate and edit.

Source: https://www.youj.dev/docs/components/chat/message

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { ChatMessage, type ChatFeedback } from '@youj/react'

const QUESTION = 'Why did checkout get slower after Tuesday?'

const ANSWER = `The second deployment on Tuesday moved \`checkout\` to the edge runtime, and p95 rose in **fra1** only:

- before: **97 ms**
- after: **164 ms**

The edge build pulls a larger crypto polyfill. Rolling back to \`dpl_7c1e0b2\` is safe.`

export default function MessageDemo() {
  const [question, setQuestion] = useState(QUESTION)
  const [feedback, setFeedback] = useState<ChatFeedback>(null)
  const [version, setVersion] = useState(1)

return (
    <div className="flex w-full max-w-2xl flex-col gap-6">
      <ChatMessage role="user" name="Ada Lovelace" timestamp={Date.UTC(2026, 0, 15, 9, 12)} content={question} onEdit={setQuestion} />
      <ChatMessage
        role="assistant"
        name="Youj"
        timestamp={Date.UTC(2026, 0, 15, 9, 12)}
        content={version === 1 ? ANSWER : `${ANSWER}\n\n_Regenerated ${version - 1}×._`}
        feedback={feedback}
        onFeedbackChange={setFeedback}
        onRegenerate={() => setVersion((v) => v + 1)}
      />
    </div>
  )
}
```

An editable question and an assistant answer you can rate and regenerate.

### Actions

```tsx
'use client'

import { useState } from 'react'
import { Avatar, AvatarFallback, ChatMessage, ChatMessageAction, toast } from '@youj/react'
import { BookmarkIcon, ShareIcon } from '@youj/icons'

export default function MessageActions() {
  const [saved, setSaved] = useState(false)

return (
    <div className="flex w-full max-w-2xl flex-col gap-6">
      <ChatMessage role="system" content="Ada shared this chat with the Platform team" />
      <ChatMessage
        role="assistant"
        name="Release bot"
        avatar={
          <Avatar className="size-7">
            <AvatarFallback className="bg-accent text-on-accent">RB</AvatarFallback>
          </Avatar>
        }
        content="**v2.4.0** is live in all regions. 214 checks passed and the build took 38s."
        actions={
          <>
            <ChatMessageAction label={saved ? 'Saved' : 'Save'} pressed={saved} onPressedChange={setSaved}>
              <BookmarkIcon size={16} strokeWidth={1.75} active={saved} />
            </ChatMessageAction>
            <ChatMessageAction label="Share" onClick={() => toast('Link copied')}>
              <ShareIcon size={16} strokeWidth={1.75} />
            </ChatMessageAction>
          </>
        }
      />
    </div>
  )
}
```

A system notice and an assistant message with two actions of its own, Save and Share.

Copy is on by default (`copyable={false}` removes it). Regenerate shows on assistant messages when `onRegenerate` is set, the good and bad pair when `feedback` or `onFeedbackChange` is, and Edit on user messages when `onEdit` is. Editing swaps the bubble for a field: Enter saves, Escape cancels, and focus returns to Edit.

Actions sit in one toolbar that stays quiet until wanted: it shows on hover and focus, always on touch screens and on the latest message, and never while the message streams. Add your own after the built-in ones with `actions` and `ChatMessageAction`, which is an icon button with a tooltip, or a toggle when you pass `pressed`. A custom `avatar` replaces the default one.

### Errors and stopping

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { ChatMessage, createTextStream } from '@youj/react'

const ANSWER = `**fra1** has the fastest cold starts in Europe, at 131 ms. **hnd1** is slower (148 ms) but serves Asia-Pacific. For a mixed audience, run both and let routing pick the nearest.`

const tokenize = (text: string) => text.match(/\s*\S{1,4}|\s+/g) ?? []

export default function MessageError() {
  const [stream] = useState(() => createTextStream())
  const [streaming, setStreaming] = useState(true)
  const [error, setError] = useState<string>()
  const [attempt, setAttempt] = useState(0)
  const timer = useRef<ReturnType<typeof setInterval>>(undefined)

// The first try drops part-way; Retry streams the whole answer.
  useEffect(() => {
    const tokens = tokenize(ANSWER)
    const failAt = attempt === 0 ? 14 : tokens.length
    let i = 0
    stream.set('')
    setStreaming(true)
    setError(undefined)
    timer.current = setInterval(() => {
      if (i === failAt && i < tokens.length) {
        clearInterval(timer.current)
        setStreaming(false)
        setError('The connection dropped before the answer finished.')
        return
      }
      stream.append(tokens[i++]!)
      if (i < tokens.length) return
      clearInterval(timer.current)
      setStreaming(false)
    }, 50)
    return () => clearInterval(timer.current)
  }, [attempt, stream])

return (
    <div className="w-full max-w-2xl">
      <ChatMessage
        role="assistant"
        name="Youj"
        content={stream}
        streaming={streaming}
        error={error}
        onRetry={() => setAttempt((n) => n + 1)}
      />
    </div>
  )
}
```

An answer that drops part-way through, with the error and a retry that streams it whole.

`error` shows under whatever arrived, with Retry when `onRetry` is set, and is announced assertively. The partial answer stays, and its unfinished end renders as it did while streaming. For an answer the reader stopped, set `incomplete` instead. The preview drops its first try part-way. Retry streams it again.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use one for every turn in a conversation, inside a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list), which groups consecutive messages and announces them. An assistant message renders its `content` as streamed [markdown](https://www.youj.dev/docs/components/chat/markdown) across the column. A user message is a bubble on the inline-end side, and a system message is a centered notice between hairlines. Hover the answer in the preview to see its actions, or edit the question.

```tsx
import { ChatMessage } from '@youj/react'

<ChatMessage role="user" name="Ada Lovelace" content="Why did checkout get slower?" onEdit={resend} />
<ChatMessage
  role="assistant"
  name="Youj"
  content={reply.stream}
  streaming={reply.streaming}
  feedback={reply.feedback}
  onFeedbackChange={rate}
  onRegenerate={regenerate}
/>
```

Names default to "Assistant", "You" and "System". `timestamp` takes a `Date`, a string or a number, and shows the time with the full date in its title. Messages are memoised, so pass stable callbacks and a message re-renders only when its own props change.

`children` render before the text, for what the assistant did first: a [typing indicator or reasoning](https://www.youj.dev/docs/components/chat/thinking), [tool calls](https://www.youj.dev/docs/components/chat/tool-call), attachments. `footer` renders after it, for follow-ups. `sources` turns `[1]` in the text into a [citation](https://www.youj.dev/docs/components/chat/citation) and adds a row of sources under the answer once it's done.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `role` (required) | `'user' \| 'assistant' \| 'system'` |  |  |
| `name` | `string` |  | The author, shown and announced. Defaults: "Assistant", "You", "System". |
| `avatar` | `ReactNode` |  | A custom avatar, e.g. `<Avatar><AvatarImage src={…} /><AvatarFallback>AL</AvatarFallback></Avatar>`. |
| `timestamp` | `Date \| string \| number` |  |  |
| `content` | `ChatText` |  | The text. Markdown for assistant messages, plain text otherwise. A ChatTextSource streams it. |
| `streaming` | `boolean` |  | The assistant is still writing it: the text streams in, and actions wait until it's done. |
| `children` | `ReactNode` |  | Blocks before the text: reasoning, tool calls, attachments. |
| `footer` | `ReactNode` |  | Blocks after the text: follow-ups, anything else. |
| `sources` | `ChatSource[]` |  | Where the answer came from: `[1]` in the text links to sources[0], and a row of chips follows the answer. |
| `headingLevel` | `number` |  | The outline level for the answer's top heading. Default 2 (see ChatMarkdown). |
| `error` | `string` |  | Why the message failed. Shown under whatever arrived, with Retry when `onRetry` is set. |
| `incomplete` | `boolean` |  | The answer was cut off (stopped): its unfinished end renders as it did while streaming. Implied by `error`. |
| `onRetry` | `() => void` |  |  |
| `onRegenerate` | `() => void` |  | Shows Regenerate on assistant messages. |
| `feedback` | `'up' \| 'down'` |  | Good / bad response, controlled. Shows the pair when set or when `onFeedbackChange` is. |
| `onFeedbackChange` | `(feedback: ChatFeedback) => void` |  |  |
| `onEdit` | `(text: string) => void` |  | Shows Edit on user messages and receives the new text. |
| `actions` | `ReactNode` |  | More actions after the built-in ones: ChatMessageAction elements. |
| `copyable` | `boolean` | `true` | Offer Copy. |
| `ref` | `Ref<HTMLElement>` |  | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |

Also takes the props of `ComponentProps<'article'>`.

#### ChatMessageAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | The action's name and tooltip. |
| `children` (required) | `ReactNode` |  |  |
| `onClick` | `() => void` |  |  |
| `pressed` | `boolean` |  | Makes it a toggle (aria-pressed), e.g. good response. |
| `onPressedChange` | `(pressed: boolean) => void` |  |  |
| `disabled` | `boolean` |  |  |
| `ref` | `Ref<HTMLButtonElement>` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Actions show and hide | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the toolbar fades on hover and focus |
| Writing |  | loop | the assistant avatar’s sparkles twinkle while it streams |
| Copied | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | the back sheet tucks in behind the front one |
| Copied check | `duration.slow` | 340ms | written on the page, after a `base` delay |
| Copied hold | `duration.deliberate` | 560ms; × 3 | before the icon and the tooltip return to rest |
| Good or bad response | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | the thumb rocks −16°, 5°, 0° as it turns on |
| Error mark | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | the warning rocks once as it mounts |

**Reduced motion:** The toolbar shows and hides at once, the avatar holds still, and the icons change without playing.

The text's own motion (words fading in, the caret) belongs to [Chat Markdown](https://www.youj.dev/docs/components/chat/markdown).

#### Reduced motion

The toolbar appears without fading, the assistant's avatar stops twinkling, and the copy, rating and warning icons change state without animating. Streamed text arrives in whole sentences (see [Chat Markdown](https://www.youj.dev/docs/components/chat/markdown)).

### Accessibility

- Each message is an `article` named by its header, the author and the time, even when grouping hides the header visually.
- While streaming it sets `aria-busy`. Inside a list, a finished assistant answer is announced once, whole, and a failure assertively.
- The actions are one toolbar named "Message actions": a single tab stop, with arrow keys moving inside it. Every action has a name and a tooltip, and the rating buttons are toggles with `aria-pressed`.
- The edit field is named "Edit message" and takes focus with the caret at the end. Escape cancels and returns focus to Edit.

---

# Chat Markdown

> Render streaming Markdown with highlighted code, tables and a writing caret.

Source: https://www.youj.dev/docs/components/chat/markdown

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Button, ChatMarkdown, createTextStream } from '@youj/react'
import { RefreshIcon } from '@youj/icons'

const SOURCE = `## Shipping orion

Run the checks, open a preview, then merge to \`main\`. **Production builds from there**, and _every_ deployment keeps its build.

\`\`\`ts
import { deploy } from '@acme/cli'

const release = await deploy({ project: 'orion', target: 'production' })
console.log(release.url)
\`\`\`

| Region | Cold start | p95 |
| :----- | ---------: | --: |
| iad1 | 112 ms | 84 ms |
| fra1 | 131 ms | 97 ms |

> Rollbacks are instant: promote the previous deployment.

Read more in [the deployment guide](https://youj.io/docs/deployments).`

const tokenize = (text: string) => text.match(/\s*\S{1,4}|\s+/g) ?? []

export default function MarkdownDemo() {
  const [stream] = useState(() => createTextStream())
  const [streaming, setStreaming] = useState(true)
  const [run, setRun] = useState(0)

useEffect(() => {
    const tokens = tokenize(SOURCE)
    let i = 0
    stream.set('')
    setStreaming(true)
    const timer = setInterval(() => {
      stream.append(tokens[i++]!)
      if (i < tokens.length) return
      clearInterval(timer)
      setStreaming(false)
    }, 30)
    return () => clearInterval(timer)
  }, [run, stream])

return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <ChatMarkdown content={stream} streaming={streaming} headingLevel={3} className="text-ui-lg leading-6" />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setRun((n) => n + 1)} disabled={streaming} focusableWhenDisabled>
        <RefreshIcon size={14} strokeWidth={1.75} />
        Stream again
      </Button>
    </div>
  )
}
```

Markdown streaming in token by token: a heading, code, a table, a quote and a link.

Paragraphs, headings, nested lists (ordered or not), fenced code, blockquotes, GFM tables and rules; inline code, strong, emphasis, strikethrough, links, autolinks and numbered citations (`[1]`, when `sources` is set). Code blocks are highlighted, labeled with their language and have a copy button, and wide code and tables scroll sideways inside their own box.

`headingLevel` places the answer in the page's outline. Models often start at `##`, so the answer's top heading becomes `headingLevel` (default 2) whatever level the model used, and deeper ones follow.

With `streaming`, each word fades up as it arrives, and a caret marks where writing happens. The caret holds solid while tokens flow, and blinks only when the stream pauses. Unfinished syntax renders optimistically: `**bol` is already bold and an unclosed fence is already code, while a last line that can't be read yet (a lone `-`, `#` or `|`) waits a few characters. Nothing flickers from raw asterisks into formatting.

When a stream is cut off, by a stop or an error, set `incomplete`: the unfinished end keeps rendering as it did while streaming, without the caret.

### Safe by construction

```tsx
'use client'

import { ChatMarkdown } from '@youj/react'

// What a model (or a prompt injection) might send. None of it becomes markup.
const SOURCE = `Here's the report you asked for. <img src=x onerror="alert(1)">

- A safe link: [status page](https://status.youj.io)
- An unsafe one stays text: [click me](javascript:alert(1))
- An image becomes a link: ![chart](https://youj.io/chart.png)

export default function MarkdownSafety() {
  return (
    <div className="w-full max-w-2xl rounded-xl border border-line bg-canvas p-5">
      <ChatMarkdown content={SOURCE} className="text-ui-lg leading-6" />
    </div>
  )
}
```

A model's HTML, a javascript: link, an image and a script tag, none of which becomes markup.

The source is parsed into data and rendered as React elements, never as HTML, so an answer can't inject markup. Raw HTML stays text, images become links, and a link is only a link when its URL is `http(s)` or `mailto`. `safeHref` and `markdownToPlainText` are exported for the same rules elsewhere.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Chat Markdown renders a model's answer while it's still arriving. Every assistant [Chat Message](https://www.youj.dev/docs/components/chat/message) uses it for its `content`, and [reasoning](https://www.youj.dev/docs/components/chat/thinking) uses it too. Use it on its own for any other place a model writes: a summary panel, an inline explanation, a generated description.

```tsx
import { ChatMarkdown } from '@youj/react'

<ChatMarkdown content={answer.stream} streaming={answer.streaming} />
```

`content` is a string or a `ChatTextSource`. With a source, a token re-renders only this component, and inside it only the block the token lands in: blocks are memoised by their source text.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ChatText` |  | Markdown source: a string, or a ChatTextSource that streams it. |
| `streaming` | `boolean` | `false` | Still being written: words fade in, a caret marks the end, unfinished syntax renders optimistically. |
| `incomplete` | `boolean` | `false` | Cut off (stopped, or failed part-way): the unfinished end still renders as it did while streaming, without the caret. |
| `sources` | `ChatSource[]` |  | Numbered citations: `[1]` in the text becomes a chip for `sources[0]`, previewed on hover. |
| `headingLevel` | `number` | `2` | The outline level of the message's top heading, whatever markdown level the model used for it (models often start at `##`); deeper ones follow. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Word arrives | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | fades up once as it mounts (`@starting-style`), and costs nothing after |
| Caret blink | `duration.deliberate`, `ease.linear` | 560ms; cubic-bezier(0, 0, 1, 1) | only after the stream pauses; one on-off cycle per 2 × deliberate |
| Link hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the underline takes the accent |

**Reduced motion:** No fades and no blink. The text is revealed in whole sentences and lines rather than word by word.

#### Reduced motion

Words don't fade and the caret doesn't blink. A streaming answer is shown up to its last finished sentence or line, so it arrives in calm chunks instead of a constant trickle. `revealedUnderReducedMotion(text)` is that rule, exported.

### Accessibility

- Output is real structure: headings at the level you choose, lists, tables with header cells, and code in `<pre><code>`.
- Code blocks and wide tables scroll inside a named scroll area ("TypeScript code", "Table"), which is a tab stop once it overflows.
- The caret and the fades are decoration. Inside a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list), the finished answer is announced once as plain text, never token by token.

---

# Prompt Input

> Compose a message with attachments and a send button that becomes a stop control.

Source: https://www.youj.dev/docs/components/chat/prompt-input

## Examples

### Demo

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import {
  PromptInput,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  Toggle,
  type PromptStatus,
} from '@youj/react'
import { GlobeIcon } from '@youj/icons'

const MODELS = [
  { value: 'pro', label: 'Youj Pro' },
  { value: 'fast', label: 'Youj Fast' },
]

export default function PromptInputDemo() {
  const [model, setModel] = useState('pro')
  const [search, setSearch] = useState(true)
  const [status, setStatus] = useState<PromptStatus>('idle')
  const [sent, setSent] = useState<string>()
  const timers = useRef<ReturnType<typeof setTimeout>[]>([])
  useEffect(() => () => timers.current.forEach(clearTimeout), [])

// A pretend reply: submitted, then streaming, then done. Send turns into stop meanwhile.
  const send = (text: string) => {
    setSent(text)
    setStatus('submitted')
    timers.current = [setTimeout(() => setStatus('streaming'), 600), setTimeout(() => setStatus('idle'), 3200)]
  }
  const stop = () => {
    timers.current.forEach(clearTimeout)
    setStatus('idle')
  }

return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <PromptInput
        status={status}
        onStop={stop}
        onSubmit={({ text }) => send(text)}
        toolbar={
          <>
            <Select items={MODELS} value={model} onValueChange={(value) => value && setModel(value)}>
              <SelectTrigger size="sm" variant="ghost" aria-label="Model" className="shadow-none">
                <SelectValue />
              </SelectTrigger>
              <SelectContent alignItemWithTrigger={false} side="top">
                {MODELS.map((m) => (
                  <SelectItem key={m.value} value={m.value}>
                    {m.label}
                  </SelectItem>
                ))}
              </SelectContent>
            </Select>
            <Toggle size="sm" pressed={search} onPressedChange={setSearch} aria-label="Search the web">
              <GlobeIcon size={16} strokeWidth={1.75} />
              Search
            </Toggle>
          </>
        }
      />
      <p className="min-h-5 text-center text-ui-sm text-fg-muted" aria-live="polite">
        {status === 'idle' ? (sent ? `Sent “${sent}”` : 'Enter sends, Shift+Enter adds a line.') : 'Replying… press Escape or the stop button.'}
      </p>
    </div>
  )
}
```

A composer with a model select and a Search toggle, where send turns into stop while a pretend reply streams.

`status` is `idle`, `submitted` or `streaming`. Anything but `idle` turns send into stop, a real path morph from the arrow to a square, and Escape in the field stops too. Send stays focusable while it can't act, so keyboard focus is never dropped mid-reply.

`toolbar` puts your controls at the start of the bottom bar: a model select, tool toggles, dictation. The demo has a model [Select](https://www.youj.dev/docs/components/select) and a [Toggle](https://www.youj.dev/docs/components/toggle). Size them `sm` to sit on the bar.

### Attachments

```tsx
'use client'

import { useState } from 'react'
import { PromptInput, usePromptAttachments } from '@youj/react'

export default function PromptInputAttachments() {
  const files = usePromptAttachments()
  const [last, setLast] = useState<string>()

return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <PromptInput
        placeholder="Attach a screenshot or a log, then ask…"
        attachments={files.attachments}
        onAttach={files.add}
        onRemoveAttachment={files.remove}
        accept="image/*,.pdf,.txt,.log,.csv"
        onSubmit={({ text, attachments }) => {
          setLast(`${text || 'No text'} · ${attachments.length} ${attachments.length === 1 ? 'file' : 'files'}`)
          files.clear()
        }}
      />
      <p className="min-h-5 text-center text-ui-sm text-fg-muted" aria-live="polite">
        {last ? `Sent: ${last}` : 'Use the paperclip, paste an image or drop files on the field.'}
      </p>
    </div>
  )
}
```

A composer that attaches files by paperclip, paste or drop, shown as chips above the text.

Pass `onAttach` and a paperclip appears, and pasting or dropping files attaches them too. `accept` filters all three, as in `<input accept>`. Attachments sit above the text as chips, a thumbnail for images and name and size for files, each with its own remove button. `usePromptAttachments()` manages picked files for you: `add`, `remove` and `clear`, with object-URL previews revoked when they're removed or the component unmounts.

An attachment with `status: 'uploading'` blocks sending until it's ready, and one with `status: 'error'` says so.

### Limits

```tsx
'use client'

import { PromptInput } from '@youj/react'

const DRAFT =
  'Summarize the incident for the status page: checkout p95 in fra1 rose from 97 ms to 164 ms after Tuesday’s edge migration, and a rollback to dpl_7c1e0b2 restored it within a minute. Keep it calm and short.'

export default function PromptInputLimit() {
  return (
    <div className="w-full max-w-2xl">
      {/* The counter appears from 80% of the limit, warns at 95% and blocks sending past it. */}
      <PromptInput defaultValue={DRAFT} maxLength={220} label="Status update" placeholder="Write the update…" onSubmit={() => {}} />
    </div>
  )
}
```

A 220-character limit with a long draft in the field, so the counter shows.

`maxLength` shows a counter near the limit and blocks sending past it. The counter appears from 80% of the limit, turns to a warning at 95% and to danger past it. Replace it with `counter`, for example `<PromptInputCounter value={tokens} max={8000} unit="tokens" />` to count tokens instead.

### Side panel

```tsx
'use client'

import { useRef, useState } from 'react'
import { Button, ChatSuggestions, PromptInput, Toggle, usePromptAttachments, type ChatSuggestion } from '@youj/react'
import { ImageIcon, MicIcon, SparklesIcon } from '@youj/icons'

const PROMPTS: ChatSuggestion[] = [
  { label: 'Summarize this week', icon: <SparklesIcon size={14} strokeWidth={1.75} /> },
  { label: 'Explain the build spike', icon: <SparklesIcon size={14} strokeWidth={1.75} /> },
  { label: 'Draft a status update', icon: <SparklesIcon size={14} strokeWidth={1.75} /> },
]

export default function PromptInputSidePanel() {
  const [value, setValue] = useState('')
  const [dictating, setDictating] = useState(false)
  const files = usePromptAttachments()
  const field = useRef<HTMLTextAreaElement>(null)
  return (
    <div className="flex w-full max-w-sm flex-col gap-3 rounded-2xl border border-line bg-surface p-3">
      <ChatSuggestions
        suggestions={PROMPTS}
        onSelect={(prompt) => {
          setValue(prompt)
          field.current?.focus()
        }}
      />
      <PromptInput
        value={value}
        onValueChange={setValue}
        textareaRef={field}
        placeholder="Ask about this workspace…"
        maxLength={300}
        attachments={files.attachments}
        onAttach={files.add}
        onRemoveAttachment={files.remove}
        onSubmit={() => {
          setValue('')
          files.clear()
        }}
        toolbar={
          <>
            <Button variant="ghost" size="sm">
              <ImageIcon size={14} strokeWidth={1.75} />
              Create
            </Button>
            <Toggle size="sm" pressed={dictating} onPressedChange={setDictating} aria-label="Dictate">
              <MicIcon size={14} strokeWidth={1.75} />
            </Toggle>
          </>
        }
      />
    </div>
  )
}
```

An assistant composer in a narrow side panel, with suggestion chips above it.

[Chat Suggestions](https://www.youj.dev/docs/components/chat/suggestions) above the field fill it on a click and move focus there. `onAttach` brings the built-in paperclip; `toolbar` takes your own tools beside it, here a Create button and a dictation [Toggle](https://www.youj.dev/docs/components/toggle). `maxLength` blocks sending past 300 characters and shows the count near the limit.

### Session details

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import {
  PromptInput,
  PropertyList,
  PropertyListItem,
  PropertyStatus,
  PropertyText,
  SegmentedMeter,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
  Spinner,
  type PromptStatus,
} from '@youj/react'
import { ActivityIcon, GaugeIcon, LightbulbIcon, PlugIcon, WrenchIcon } from '@youj/icons'

const LIMIT = 200_000
const SPACES = [
  { value: 'playground', label: 'Playground' },
  { value: 'staging', label: 'Staging' },
]
const MODES = [
  { value: 'ask', label: 'Ask first' },
  { value: 'auto', label: 'Auto-run' },
]
const tokens = (n: number) => `${(n / 1000).toFixed(1)}K`

export default function PromptInputSession() {
  const [status, setStatus] = useState<PromptStatus>('idle')
  const [used, setUsed] = useState(18_200)
  const [space, setSpace] = useState('playground')
  const [mode, setMode] = useState('ask')
  const timers = useRef<ReturnType<typeof setTimeout>[]>([])
  useEffect(() => () => timers.current.forEach(clearTimeout), [])
  const running = status !== 'idle'

// A pretend turn: the reply streams for a few seconds and the context fills a little.
  const send = () => {
    setStatus('submitted')
    timers.current = [
      setTimeout(() => setStatus('streaming'), 600),
      setTimeout(() => {
        setStatus('idle')
        setUsed((n) => n + 2_400)
      }, 3_400),
    ]
  }
  const stop = () => {
    timers.current.forEach(clearTimeout)
    setStatus('idle')
  }

return (
    <div className="flex w-full max-w-2xl flex-col gap-3">
      <PromptInput
        status={status}
        onStop={stop}
        onSubmit={send}
        placeholder="Ask about this session…"
        className="[&_[data-slot=input-group]]:shadow-none"
      />
      <section aria-label="Session details" className="flex flex-col rounded-xl bg-well">
        <PropertyList className="px-3.5 py-1.5">
          <PropertyListItem icon={<GaugeIcon size={16} />} label="Context">
            <span className="flex w-full min-w-0 items-center gap-3">
              <span className="shrink-0 tabular-nums">
                {tokens(used)} <span className="text-fg-muted">/ {tokens(LIMIT).replace('.0', '')} tokens</span>
              </span>
              <SegmentedMeter
                aria-label="Context used"
                value={used}
                max={LIMIT}
                segments={20}
                showValue={false}
                thresholds={[{ value: LIMIT * 0.8, tone: 'warning' }]}
                className="min-w-16 flex-1 [&_[data-slot=segmented-meter-track]]:h-2"
              />
            </span>
          </PropertyListItem>
          <PropertyListItem icon={<LightbulbIcon size={16} />} label="Reasoning">
            <PropertyText>Medium</PropertyText>
          </PropertyListItem>
          <PropertyListItem icon={<WrenchIcon size={16} />} label="Tools">
            <PropertyText>Read, Edit, Bash +3</PropertyText>
          </PropertyListItem>
          <PropertyListItem icon={<PlugIcon size={16} />} label="MCP & Skills">
            <PropertyText>2 servers, 4 skills</PropertyText>
          </PropertyListItem>
          <PropertyListItem icon={<ActivityIcon size={16} />} label="Status">
            <PropertyStatus tone={running ? 'success' : 'neutral'}>{running ? 'Running' : 'Idle'}</PropertyStatus>
          </PropertyListItem>
        </PropertyList>
        <div className="flex items-center gap-1 border-t border-line px-2 py-1.5">
          <Pick label="Workspace" items={SPACES} value={space} onChange={setSpace} />
          <Pick label="Permissions" items={MODES} value={mode} onChange={setMode} />
          <span className="ms-auto flex h-control-sm items-center px-2">{running ? <Spinner label="Working" size={16} /> : null}</span>
        </div>
      </section>
    </div>
  )
}
```

A composer with a session panel under it: context used, reasoning, tools, MCP and skills, and a status dot, over a footer with workspace and permission selects and a spinner.

It is a composition, not a part: a [Property List](https://www.youj.dev/docs/components/property-list) for the rows, a [Segmented Meter](https://www.youj.dev/docs/components/segmented-meter) for the context window (amber from 80%), [Selects](https://www.youj.dev/docs/components/select) and a [Spinner](https://www.youj.dev/docs/components/spinner) in the footer. Send a message: Status turns to Running with the spinner on, and the context grows by a turn when the reply ends.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use it below a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list) for anything someone writes to an assistant. It handles the keyboard rules people expect from a chat composer, attachments by picker, paste and drop, and the switch from send to stop while a reply runs. For a plain multi-line field in a form, use a [Textarea](https://www.youj.dev/docs/components/textarea).

```tsx
import { PromptInput } from '@youj/react'

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

`onSubmit` gets the trimmed text and the attachments. Uncontrolled, the field clears itself after sending. Control it with `value` and `onValueChange` to fill it from elsewhere, like a [suggestion](https://www.youj.dev/docs/components/chat/suggestions), and `textareaRef` to focus it.

Enter sends and Shift+Enter breaks the line, and neither cuts an IME composition short. On touch keyboards Enter is a line break and the button sends. The field grows with the message up to 40% of the viewport, then scrolls.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  |  |
| `defaultValue` | `string` | `''` |  |
| `onValueChange` | `(value: string) => void` |  |  |
| `onSubmit` (required) | `(message: PromptSubmission) => void` |  | Called with the trimmed text and the attachments. Uncontrolled, the text then clears itself. |
| `status` | `'idle' \| 'submitted' \| 'streaming'` | `'idle'` | 'submitted' and 'streaming' turn send into stop. |
| `onStop` | `() => void` |  |  |
| `placeholder` | `string` | `"Ask anything…"` |  |
| `label` | `string` | `"Message"` | The text field's name for assistive tech. |
| `disabled` | `boolean` | `false` |  |
| `attachments` | `PromptAttachment[]` | `[]` |  |
| `onAttach` | `(files: File[]) => void` |  | Enables attaching: the paperclip, paste and drop. Receives the files. |
| `onRemoveAttachment` | `(id: string) => void` |  |  |
| `accept` | `string` |  | Which files the picker offers and paste or drop accept, as in <input accept>. |
| `toolbar` | `ReactNode` |  | Controls at the start of the bottom bar: a model select, tool toggles. |
| `counter` | `ReactNode` |  | Replaces the built-in character counter, e.g. `<PromptInputCounter value={tokens} max={8000} unit="tokens" />`. |
| `maxLength` | `number` |  | A character limit: shows a counter near it and blocks sending past it. |
| `autoFocus` | `boolean` |  |  |
| `textareaRef` | `Ref<HTMLTextAreaElement>` |  | The textarea, e.g. to focus it after picking a suggestion. |

Also takes the props of `ComponentProps<'form'>`.

#### PromptInputCounter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `max` (required) | `number` |  |  |
| `unit` | `string` | `"characters"` | What's counted, for the announcement. |
| `from` | `number` | `0.8` | Show from this share of `max`. |
| `id` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Send to stop | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1); deliberate + fast: 700ms | IconSwap `morph`: the arrow’s strokes bend into the square, and back |
| Reversal |  | length × distance left | stopping mid-morph turns back from where it is |
| Attachment enters | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fades and drops 6px (Presence List) |
| Attachment leaves | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fades in place, then the rest close the gap |
| Chips make room | `spring.smooth` | 0.36s, bounce 0 |  |
| Counter | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades in near the limit |

**Reduced motion:** Send and stop swap instantly, and chips appear and disappear in place.

#### Reduced motion

The arrow swaps to the square without morphing, and attachment chips appear and leave at once. Everything else, the keyboard rules and the counter, is unchanged.

### Accessibility

- The field is named by `label` (default "Message"). With `maxLength`, it's described by the counter and set `aria-invalid` past the limit.
- The counter is announced only in the last stretch (under 10% left) and when over, not on every keystroke.
- Send is named "Send message", and "Stop generating" while busy, with a tooltip. It stays focusable while it can't act.
- The paperclip is named "Attach files". Attachments are a list named "Attachments", and each remove button is named after its file. Removing one moves focus to its neighbor, never to the page.
- `disabled` grays the whole frame and blocks typing, attaching and sending.

---

# Thinking

> Show when an assistant is working, with a typing indicator and collapsible reasoning.

Source: https://www.youj.dev/docs/components/chat/thinking

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Button, ChatReasoning, createTextStream } from '@youj/react'
import { RefreshIcon } from '@youj/icons'

const REASONING = `Comparing three regions on cold start, p95 and cost. The metrics tool has the last 7 days per region, and cost at 10M requests follows from the pricing table.

Most traffic comes from Europe, so **fra1** should win on both latency and cost. Check hnd1 anyway: Asia-Pacific is growing.`

const tokenize = (text: string) => text.match(/\s*\S{1,4}|\s+/g) ?? []

export default function ThinkingDemo() {
  const [stream] = useState(() => createTextStream())
  const [streaming, setStreaming] = useState(true)
  const [seconds, setSeconds] = useState<number>()
  const [run, setRun] = useState(0)

// Streams open, then folds away to "Thought for Ns", N the time it really took (about 3s here). Open it again to read it.
  useEffect(() => {
    const tokens = tokenize(REASONING)
    const started = Date.now()
    let i = 0
    stream.set('')
    setStreaming(true)
    const timer = setInterval(() => {
      stream.append(tokens[i++]!)
      if (i < tokens.length) return
      clearInterval(timer)
      setSeconds((Date.now() - started) / 1000)
      setStreaming(false)
    }, 45)
    return () => clearInterval(timer)
  }, [run, stream])

return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <ChatReasoning content={stream} streaming={streaming} duration={seconds} />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setRun((n) => n + 1)} disabled={streaming} focusableWhenDisabled>
        <RefreshIcon size={14} strokeWidth={1.75} />
        Think again
      </Button>
    </div>
  )
}
```

Reasoning that streams open, folds to “Thought for” its duration, and can be run again.

`ChatReasoning` streams its `content` as muted [markdown](https://www.youj.dev/docs/components/chat/markdown) under a rule. Uncontrolled, it's open while `streaming` and folds away when the thinking is done, until the reader toggles it: then their choice sticks. The label reads "Thinking…" with a sweep of light while it streams, then "Thought for" and `duration` (in seconds), or "Reasoning" without one. Control it with `open` and `onOpenChange`.

### Typing indicator

```tsx
'use client'

import { ChatTypingIndicator } from '@youj/react'

export default function ThinkingIndicators() {
  return (
    <div className="grid w-full max-w-md grid-cols-2 gap-3">
      <div className="flex flex-col gap-2 rounded-xl border border-line bg-canvas p-4">
        <span className="text-ui-xs font-medium tracking-wide text-fg-muted uppercase">Shimmer</span>
        <ChatTypingIndicator />
      </div>
      <div className="flex flex-col gap-2 rounded-xl border border-line bg-canvas p-4">
        <span className="text-ui-xs font-medium tracking-wide text-fg-muted uppercase">Dots</span>
        <ChatTypingIndicator variant="dots" label="Searching the docs…" />
      </div>
    </div>
  )
}
```

The two typing indicators, shimmer and dots.

The default `shimmer` sweeps a band of light across its label. `dots` is three dots in a traveling wave, for tighter spaces, with the label read to screen readers only. `label` defaults to "Thinking…". The sweep pauses while it's offscreen or the tab is hidden.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Two parts cover the wait. `ChatTypingIndicator` says the assistant is working when nothing has arrived yet. `ChatReasoning` shows a model's reasoning as it streams, then folds it under "Thought for 4s" so the answer takes the space. Put either inside the assistant's [Chat Message](https://www.youj.dev/docs/components/chat/message), before its content. For work with a name and a result, like a search or an API call, use a [Tool Call](https://www.youj.dev/docs/components/chat/tool-call) instead.

```tsx
import { ChatMessage, ChatReasoning, ChatTypingIndicator } from '@youj/react'

<ChatMessage role="assistant" content={reply.stream} streaming={reply.streaming}>
  {reply.waiting && <ChatTypingIndicator />}
  {reply.reasoning && (
    <ChatReasoning content={reply.reasoning.stream} streaming={reply.reasoning.streaming} duration={reply.reasoning.seconds} />
  )}
</ChatMessage>
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ChatText` |  | The reasoning, as markdown: a string, or a ChatTextSource streaming it. |
| `streaming` | `boolean` | `false` | Still thinking: the label sweeps and the text streams in. |
| `duration` | `number` |  | How long the thinking took, in seconds: the folded label says so. |
| `open` | `boolean` |  | Controlled. Uncontrolled, it is open while streaming and folds away when done, until the reader toggles it. |
| `onOpenChange` | `(open: boolean) => void` |  |  |

Also takes the props of `ComponentProps<'div'>`.

#### ChatTypingIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'shimmer' \| 'dots'` | `'shimmer'` | 'shimmer' sweeps light across the label; 'dots' is three dots in a wave. |
| `label` | `string` | `"Thinking…"` | Shown and announced. |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Shimmer sweep | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1); × 3 per sweep | a masked copy of the label rides a band across it; transform only |
| Dots |  | loop | three dots in a traveling wave |
| Reasoning folds | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height to and from `auto`, the text fading with it (Collapse) |
| Fold fade out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | faster than the fold, so text never looks squashed |
| Label swap | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | "Thinking…" crossfades to "Thought for 4s" (Morph Label) |
| Label width | `spring.snappy` | 0.2s, bounce 0 |  |

**Reduced motion:** The label holds still (no sweep, no wave), and the reasoning opens and closes instantly.

#### Reduced motion

The shimmer and the dots hold still, the label swaps without crossfading, and the reasoning opens and folds at once. The reasoning text arrives in whole sentences, as all streamed markdown does.

### Accessibility

- The reasoning's toggle is a button with `aria-expanded` and `aria-controls`, named by its label.
- Inside a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list), a typing indicator is announced once through the list, unless it sits in a message, which already said it's responding. On its own it's a `status` region.
- The shimmer's moving copy is `aria-hidden`, so the label is read once.

---

# Tool Call

> Show an assistant’s tool call, its arguments, status and result.

Source: https://www.youj.dev/docs/components/chat/tool-call

## Examples

### Demo

```tsx
'use client'

import { useEffect, useState } from 'react'
import { Button, ChatToolCall, type ChatToolStatus } from '@youj/react'
import { RefreshIcon } from '@youj/icons'

const RESULT = [
  { id: 'dpl_9f3a2c1', state: 'ready', region: 'iad1', builtIn: '38s' },
  { id: 'dpl_7c1e0b2', state: 'ready', region: 'fra1', builtIn: '41s' },
]

export default function ToolCallDemo() {
  const [status, setStatus] = useState<ChatToolStatus>('pending')
  const [run, setRun] = useState(0)

// Queued, running, then done: the badge morphs, the check draws, and a preview of the result unfolds.
  useEffect(() => {
    setStatus('pending')
    const timers = [setTimeout(() => setStatus('running'), 700), setTimeout(() => setStatus('success'), 2200)]
    return () => timers.forEach(clearTimeout)
  }, [run])

return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <ChatToolCall
        name="get_deployments"
        args={{ project: 'orion', target: 'production', limit: 2 }}
        status={status}
        result={status === 'success' ? RESULT : undefined}
        duration={1480}
      />
      <Button variant="outline" size="sm" className="self-start" onClick={() => setRun((n) => n + 1)}>
        <RefreshIcon size={14} strokeWidth={1.75} />
        Call again
      </Button>
    </div>
  )
}
```

A tool call that moves from queued to running to done, with its result unfolding at the end.

### States

```tsx
'use client'

import { ChatToolCall } from '@youj/react'

export default function ToolCallStates() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <ChatToolCall name="search_docs" args={{ query: 'rollback' }} status="pending" />
      <ChatToolCall name="get_metrics" args={{ region: 'fra1', window: '7d' }} status="running" />
      <ChatToolCall
        name="get_metrics"
        args={{ region: 'iad1', window: '7d' }}
        status="success"
        duration={620}
        result="p50 41 ms · p95 84 ms · cold start 112 ms · 0.02% errors"
      />
      <ChatToolCall
        name="promote_deployment"
        args={{ id: 'dpl_7c1e0b2' }}
        status="error"
        error="403: this token can't promote to production. Ask an owner for the deploy scope."
      />
    </div>
  )
}
```

A tool call in each state: pending, running, success and error.

`status` is `pending`, `running`, `success` or `error`. The mark is a spinner while it's queued or running, then a check that draws itself in, or a warning that rocks once. The badge reads Queued, Running, Done or Failed, and an error shows `error` in the preview.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use one for each function, search or API call an assistant makes, inside its [Chat Message](https://www.youj.dev/docs/components/chat/message) before the answer. People see that the answer rests on real data, and can open the call to check exactly what went in and came out. For the model thinking without a tool, use [Thinking](https://www.youj.dev/docs/components/chat/thinking).

```tsx
import { ChatToolCall } from '@youj/react'

<ChatToolCall
  name="get_deployments"
  args={{ project: 'orion', limit: 3 }}
  status={call.status}
  result={call.result}
  error={call.error}
  duration={call.ms}
/>
```

At rest it's one line: a status mark, the tool's name, a short read of its arguments and a badge. When the result arrives, a two-line preview unfolds under it. Opening the card shows the arguments and the full result, with JSON highlighted. `result` takes text or anything JSON can show, and `duration` (in ms) joins the badge once it's done. `open`, `defaultOpen` and `onOpenChange` control the card.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | The tool's name, e.g. "get_deployments". |
| `args` | `Record<string, unknown>` |  | Arguments, shown as JSON when opened and summarized in the header. |
| `status` (required) | `'pending' \| 'running' \| 'success' \| 'error'` |  |  |
| `result` | `unknown` |  | What it returned: text, or anything JSON can show. |
| `error` | `string` |  | Why it failed. |
| `duration` | `number` |  | How long it ran, in ms. |
| `defaultOpen` | `boolean` |  |  |
| `open` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Badge label | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | crossfades between states (Morph Label) |
| Badge width | `spring.snappy` | 0.2s, bounce 0 | the box morphs to the new label |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws itself in on success |
| Warning | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | rocks once on error |
| Preview unfolds | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height and fade, when the result arrives (Collapse) |
| Open and close | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the full exchange (`yj-collapse`) |

**Reduced motion:** Every swap and fold is instant, and the marks appear already drawn.

#### Reduced motion

The badge changes without crossfading, the check and the warning appear without playing, and the preview and the card open and close at once.

### Accessibility

- The header is the card's disclosure button, named by the tool and its status ("get_deployments: Done · 1.5s").
- Each status change is announced once: through the conversation's live regions inside a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list), or its own status region on its own. Errors are assertive. A call that mounts already settled, as history, isn't announced.
- Long arguments and results scroll inside a named region, which becomes a tab stop once it overflows.

---

# Tool Approval

> Ask before an AI agent runs a risky tool: the arguments, the risk, and Allow once, Always allow or Deny.

Source: https://www.youj.dev/docs/components/chat/tool-approval

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { Button, ChatToolApproval, type ToolApprovalDecision } from '@youj/react'
import { RefreshIcon, TrashIcon } from '@youj/icons'

export default function ToolApprovalDemo() {
  const [run, setRun] = useState(0)
  const [last, setLast] = useState<ToolApprovalDecision>()

// High risk: focus starts on the summary, Enter never approves, and Edit lets you narrow the delete first.
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <ChatToolApproval
        key={run}
        name="delete_rows"
        icon={<TrashIcon size={14} strokeWidth={1.75} />}
        summary="Delete 1,204 rows from the orders table"
        reason="They are test orders older than 90 days, and the cleanup job asked for a hard delete."
        risk="high"
        args={{ table: 'orders', where: "env = 'test' AND created_at < now() - interval '90 days'", limit: 5000 }}
        validate={(key, value) => (key === 'limit' && (value as number) > 10000 ? 'Deleting more than 10,000 rows needs a ticket.' : undefined)}
        approver="Maya Chen"
        onDecision={setLast}
      />
      <div className="flex items-center justify-between gap-3">
        <p className="min-w-0 truncate font-mono text-ui-sm text-fg-muted">
          {last ? `onDecision → ${last.decision}, ${last.scope}, limit ${String(last.args.limit)}` : 'onDecision hasn’t fired'}
        </p>
        <Button
          variant="outline"
          size="sm"
          onClick={() => {
            setLast(undefined)
            setRun((n) => n + 1)
          }}
        >
          <RefreshIcon size={14} strokeWidth={1.75} />
          Ask again
        </Button>
      </div>
    </div>
  )
}
```

A high-risk delete. Focus starts on the summary, not on Allow, and Enter does nothing here. Edit opens the arguments as fields (try `limit` above 10,000 or a word instead of a number), then Allow once runs with what you changed.

### Always allow

```tsx
'use client'

import { useState } from 'react'
import { Button, ChatToolApproval, type ToolApprovalDecision } from '@youj/react'
import { MailIcon, RefreshIcon } from '@youj/icons'

const BODY =
  'Hi team,\n\nInvoice 4821 (USD 18,400) was due on 30 September and is still open. Could you confirm a payment date by Friday? I attached the PDF and the purchase order so you have everything in one place.\n\nThanks,\nMaya'

export default function ToolApprovalScope() {
  const [run, setRun] = useState(0)
  const [trusted, setTrusted] = useState(false)

// After "Always allow", the app remembers the scope and would skip the card next time.
  const remember = (d: ToolApprovalDecision) => setTrusted(d.decision === 'allow' && d.scope === 'always')

return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <ChatToolApproval
        key={run}
        name="send_email"
        icon={<MailIcon size={14} strokeWidth={1.75} />}
        summary="Email finance about the overdue invoice"
        reason="You asked me to chase invoice 4821."
        args={{ to: 'finance@acme.test', subject: 'Invoice 4821 is overdue', body: BODY, api_key: 'yk_demo_example_key_0000' }}
        scope="messages to finance@acme.test"
        approver="Maya Chen"
        onDecision={remember}
      />
      <div className="flex items-center justify-between gap-3">
        <p className="text-ui-sm text-fg-muted">{trusted ? 'Remembered: later emails to finance@acme.test skip this card.' : 'Nothing remembered yet.'}</p>
        <Button
          variant="outline"
          size="sm"
          onClick={() => {
            setTrusted(false)
            setRun((n) => n + 1)
          }}
        >
          <RefreshIcon size={14} strokeWidth={1.75} />
          Ask again
        </Button>
      </div>
    </div>
  )
}
```

`scope` adds **Always allow for messages to finance@acme.test**. `onDecision` reports `scope: 'always'`, and your app remembers it and skips the card next time. The long body folds behind Show more, and `api_key` is masked until you reveal it.

### In an agent trace

```tsx
'use client'

import { ChatToolApproval, ChatToolCall } from '@youj/react'

// Resolved requests sit in the trace as one quiet line each, with who decided and when.
export default function ToolApprovalTrace() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <p className="text-ui-xs font-medium tracking-wide text-fg-muted uppercase">Agent trace</p>
      <ChatToolCall name="get_invoice" args={{ id: 4821 }} status="success" duration={420} result={{ id: 4821, amount: 18400, status: 'overdue' }} />
      <ChatToolApproval
        name="send_email"
        summary="Email finance about invoice 4821"
        risk="medium"
        args={{ to: 'finance@acme.test', subject: 'Invoice 4821 is overdue' }}
        status="done"
        duration={880}
        resolution={{ by: 'Maya Chen', at: new Date(2026, 9, 12, 16, 20) }}
      />
      <ChatToolApproval
        name="refund_payment"
        summary="Refund USD 18,400 to Acme"
        risk="high"
        args={{ payment: 'pay_91ac', amount: 18400, currency: 'USD', token: 'tok_live_77' }}
        status="denied"
        resolution={{ by: 'Maya Chen', at: new Date(2026, 9, 12, 16, 22), reason: 'Finance confirmed the payment is on its way.' }}
      />
      <ChatToolApproval name="deploy" summary="Promote orion to production" risk="high" args={{ project: 'orion', target: 'production' }} status="expired" />
      <ChatToolApproval
        name="delete_rows"
        summary="Delete 1,204 test orders"
        risk="high"
        args={{ table: 'orders', limit: 5000 }}
        status="failed"
        error="Permission denied: the role can't delete from orders."
        resolution={{ by: 'Maya Chen', at: new Date(2026, 9, 12, 16, 31) }}
      />
    </div>
  )
}
```

Resolved requests as history: approved and done, denied with a reason, expired, and failed after approval. Each is one line with who decided and when; open Arguments to see what was asked.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use one before an agent runs anything people would want to check first: sending an email, deleting rows, deploying, spending money. It sits in the conversation like a [Tool Call](https://www.youj.dev/docs/components/chat/tool-call), and once answered it becomes that call's quiet record.

```tsx
import { ChatToolApproval } from '@youj/react'

<ChatToolApproval
  name="delete_rows"
  summary="Delete 1,204 rows from the orders table"
  reason="They are test orders older than 90 days."
  risk="high"
  args={{ table: 'orders', limit: 5000 }}
  scope="this project"
  onDecision={({ decision, scope, args }) => answer(call.id, decision, scope, args)}
/>
```

It is **uncontrolled** by default: it starts pending, and a decision resolves it to approved or denied (with `approver` and the time on the resolved line). To drive it yourself, pass `status` (`pending`, `approved`, `denied`, `expired`, `running`, `done` or `failed`) and `resolution` (`{ by, at, reason }`); it then stays as it is until you change it. `error` and `duration` fill in the failed and done states. An `expired` request is a state you set, since only your app knows when its time ran out.

`risk` is `low`, `medium` (the default) or `high`, shown as an icon and a word, and a pending high-risk card also draws its border in danger. `scope` adds **Always allow for ‹scope›**; without it there is no such button. `onDecision` receives `{ decision: 'allow' | 'deny', scope: 'once' | 'always', args }`, where `args` are the arguments to run with: the originals, or the person's edits.

**Arguments** show as readable key/value rows. Values over about 140 characters, or with line breaks, fold behind Show more. Keys named like `password`, `token`, `secret` or `api_key`, and any key in `sensitive`, are masked until revealed and can't be edited.

**Edit** turns the editable arguments into fields. Each is parsed back to the type it had (a number must be a number, an object valid JSON), and `validate(key, value, args)` can refuse a value with a message. Errors appear under the field, and focus jumps to the first one. Escape cancels and returns focus to Edit. Pass `editable={false}` to hide it.

Pass `autoFocus` to move focus to the summary when a request appears. The summary is deliberately not a button: Enter on it allows once for low and medium risk, and is never bound on high risk, so a stray keypress can't approve a dangerous action.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | The tool's name, e.g. "send_email". |
| `icon` | `ReactNode` |  | The tool's icon; a terminal by default. |
| `summary` (required) | `ReactNode` |  | What the agent wants to do, in plain words. |
| `args` (required) | `Record<string, unknown>` |  | The arguments it would run with. |
| `reason` | `string` |  | The agent's reason for asking. |
| `risk` | `'low' \| 'medium' \| 'high'` | `'medium'` |  |
| `scope` | `string` |  | What "Always allow" covers, e.g. "this project". Without it there is no such button. |
| `sensitive` | `string[]` |  | Argument keys to mask until revealed (names like password, token and api_key are always masked). |
| `editable` | `boolean` | `true` | Offer Edit (default true). |
| `validate` | `(key: string, value: unknown, args: Record<string, unknown>) => string \| undefined` |  | Refuse an edited value: return a message. Types are checked first. |
| `status` | `'pending' \| 'approved' \| 'denied' \| 'expired' \| 'running' \| 'done' \| 'failed'` |  | Controlled. Without it, the card starts pending and a decision resolves it. |
| `defaultStatus` | `'pending' \| 'approved' \| 'denied' \| 'expired' \| 'running' \| 'done' \| 'failed'` | `'pending'` |  |
| `resolution` | `ToolApprovalResolution` |  | Who decided and when, for the resolved line. Uncontrolled, the card fills it in from `approver`. |
| `approver` | `string` |  | The person answering, shown on the resolved line of an uncontrolled card. |
| `onDecision` | `(decision: ToolApprovalDecision) => void` |  |  |
| `error` | `string` |  | Why it failed. |
| `duration` | `number` |  | How long it ran, in ms. |
| `autoFocus` | `boolean` |  | Move focus to the summary when it mounts pending. |

Also takes the props of `ComponentProps<'div'>`.

### Data attributes

On the root (`data-slot="chat-tool-approval"`):

- `data-status` is the current status: `pending`, `approved`, `denied`, `expired`, `running`, `done` or `failed`.
- `data-yj-risk` is `low`, `medium` or `high`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Status label | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | crossfades between states (Morph Label) |
| Status badge width | `spring.snappy` | 0.2s, bounce 0 | the box morphs to the new label |
| Check | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | draws itself in on approved and done |
| Warning | `duration.deliberate`, `ease.standard` | 560ms; cubic-bezier(0.2, 0, 0, 1) | rocks once on failed |
| Note and error | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | height and fade under the resolved line (Collapse) |
| Arguments open and close | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | on a resolved request (`yj-collapse`) |

**Reduced motion:** Every swap and fold is instant, and the marks appear already drawn.

#### Reduced motion

The status badge changes without crossfading, the marks appear without playing, and the arguments open and close at once.

### Accessibility

- The card is a group named by the tool. The risk is an icon and a word ("High risk"), never colour alone, and so is the status.
- Focus lands on the summary, not on Allow, when `autoFocus` is set. Tab then reaches Edit, Deny, Always allow and Allow once in that order, with Allow last.
- Enter on the focused summary allows once for low and medium risk. On high risk Enter is never bound to approve.
- In Edit, focus moves to the first field, Enter saves, Escape cancels and returns focus to Edit, and an invalid field is `aria-invalid` with its message linked and focus on the first one.
- A masked value is read as "Hidden"; its reveal button is named by the key ("Show password") and is a toggle. Show more and Show less set `aria-expanded`.
- A new request and each status change are announced once: through the conversation's live regions inside a [Chat Message List](https://www.youj.dev/docs/components/chat/message-list), or its own status region on its own. A high-risk request and a failure are assertive. A request that mounts already resolved, as history, isn't announced.
- All text comes from the `chatToolApprovalLabels`, so it follows the provider's locale and reads right to left in Arabic and Hebrew.

---

# Citation

> Link an answer to its sources with numbered markers and source previews.

Source: https://www.youj.dev/docs/components/chat/citation

## Examples

### Demo

```tsx
'use client'

import { ChatMessage, type ChatSource } from '@youj/react'

const SOURCES: ChatSource[] = [
  {
    title: 'Regions and pricing',
    url: 'https://youj.io/docs/regions',
    snippet: 'Per-region pricing for functions: requests, duration and bandwidth, updated monthly.',
  },
  {
    title: 'Measuring cold starts',
    url: 'https://youj.io/blog/cold-starts',
    snippet: 'How we measure cold starts: 1 GB functions, 15 minutes idle, p50 and p95 over 7 days.',
  },
]

export default function CitationDemo() {
  return (
    <div className="w-full max-w-2xl">
      {/* `[1]` in the text becomes a chip for sources[0]; the row of sources follows the answer. */}
      <ChatMessage
        role="assistant"
        name="Youj"
        sources={SOURCES}
        content="**iad1** has the fastest cold starts, and **fra1** is the cheapest at 10M requests a month [1]. Cold starts are measured on a 1 GB function after 15 minutes idle [2]."
      />
    </div>
  )
}
```

An assistant answer whose [1] and [2] become citation chips, with its sources listed underneath.

### On their own

```tsx
'use client'

import { ChatCitation, ChatSources, type ChatSource } from '@youj/react'

const SOURCES: ChatSource[] = [
  { title: 'Youj 2.0 is here', url: 'https://youj.io/blog/2-0', snippet: 'Streaming markdown, a chat kit for assistants, and five theme presets.' },
  { title: 'Upgrading to 2.0', url: 'https://youj.io/docs/upgrade', snippet: 'Bump the package, run the codemod, review the three renamed props it marks.' },
  { title: 'Internal runbook', url: 'file:///runbooks/upgrade.md' },
]

export default function CitationStandalone() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-4 rounded-xl border border-line bg-canvas p-5">
      <p className="text-ui-lg leading-6 text-fg">
        Upgrading is a one-line change for most apps
        <ChatCitation index={2} source={SOURCES[1]!} />, and the release adds a chat kit
        <ChatCitation index={1} source={SOURCES[0]!} />. The runbook covers the rest
        <ChatCitation index={3} source={SOURCES[2]!} />.
      </p>
      {/* A source that isn't http(s) is shown, but not linked. */}
      <ChatSources sources={SOURCES} label="Read more" />
    </div>
  )
}
```

Citations in plain text with a row of sources below; a source that isn't http(s) is shown but not linked.

`ChatCitation` and `ChatSources` also work outside a message, anywhere text rests on sources. `ChatSources` takes a `label` (default "Sources"). A source whose URL isn't `http(s)` or `mailto:` is shown, but not linked and not previewed.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use citations whenever an answer draws on documents, search results or a knowledge base, so people can check a claim without leaving the conversation. Most of the time you don't render them yourself: pass `sources` to a [Chat Message](https://www.youj.dev/docs/components/chat/message) and `[1]` in the text becomes `ChatCitation` for `sources[0]`, with `ChatSources` under the finished answer. Hover or focus a number in the preview to see its source.

```tsx
import { ChatMessage, type ChatSource } from '@youj/react'

const sources: ChatSource[] = [
  { title: 'Regions and pricing', url: 'https://youj.io/docs/regions', snippet: 'Per-region pricing for functions…' },
]

<ChatMessage role="assistant" content="fra1 is the cheapest at 10M requests a month [1]." sources={sources} />
```

A `ChatSource` has a `title` and a `url`, with an optional `snippet` for the preview and an `icon` (a favicon, say) to replace the domain's monogram. [Chat Markdown](https://www.youj.dev/docs/components/chat/markdown) takes the same `sources` prop.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` (required) | `number` |  | The number in the text, 1-based. |
| `source` (required) | `ChatSource` |  |  |
| `defaultOpen` | `boolean` |  | Open the preview from the start (a story, a tour). |

#### ChatSources

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sources` (required) | `ChatSource[]` |  |  |
| `label` | `string` | `"Sources"` |  |

Also takes the props of `ComponentProps<'div'>`.

#### ChatSource

Each entry in `sources`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` |  | Names the source in the preview, the chip and the marker's label. |
| `url` (required) | `string` |  | Opens in a new tab. Its domain shows in the preview and the monogram. |
| `snippet` | `string` |  | A line or two from the source, for the preview. |
| `icon` | `ReactNode` |  | Replaces the domain's monogram, e.g. a favicon. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Preview opens | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | scale .96 → 1 and fade, out of the chip (`yj-pop`) |
| Preview closes | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Open and close delays |  | 500ms, 250ms | hover intent, not motion; it stays while the pointer travels onto it |
| Chip hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | background and text take the accent |

**Reduced motion:** The preview appears and disappears at once.

#### Reduced motion

The preview opens and closes without scaling or fading. The hover delays are unchanged, since they're about intent, not motion.

### Accessibility

- Each marker is a link that opens its source in a new tab, named by its number and the source's title ("1, Regions and pricing"). The preview is a sighted convenience: the link carries everything.
- `ChatSources` is a list named by its `label`. A chip that already shows its title isn't named twice.
- Keyboard focus opens the preview like hover does, and Escape closes it.

---

# Suggestions

> Offer starting prompts and follow-up questions as chips or cards.

Source: https://www.youj.dev/docs/components/chat/suggestions

## Examples

### Demo

```tsx
'use client'

import { useRef, useState } from 'react'
import { ChatSuggestions, PromptInput } from '@youj/react'

const FOLLOW_UPS = [
  { label: 'Show the diff' },
  { label: 'Is a rollback safe?', prompt: 'Is rolling back to dpl_7c1e0b2 safe?' },
  { label: 'Compare regions' },
  { label: 'Draft a status update' },
]

export default function SuggestionsDemo() {
  const [draft, setDraft] = useState('')
  const field = useRef<HTMLTextAreaElement>(null)

return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      {/* Picking one fills the composer and focuses it, ready to edit or send. */}
      <ChatSuggestions
        suggestions={FOLLOW_UPS}
        onSelect={(prompt) => {
          setDraft(prompt)
          field.current?.focus()
        }}
      />
      <PromptInput value={draft} onValueChange={setDraft} textareaRef={field} onSubmit={() => setDraft('')} />
    </div>
  )
}
```

Four follow-up chips, where picking one fills the composer and focuses it.

### Cards

```tsx
'use client'

import { useState } from 'react'
import { ChatSuggestions } from '@youj/react'
import { BarChartIcon, BugIcon, GitBranchIcon, RocketIcon } from '@youj/icons'

const ICON = { size: 16, strokeWidth: 1.75 } as const

const STARTERS = [
  { label: 'Ship to production', description: 'Checks, command and a rollback path', icon: <RocketIcon {...ICON} /> },
  { label: 'Compare regions', description: 'Cold starts, p95 and cost per region', icon: <BarChartIcon {...ICON} /> },
  { label: 'Debug a slow page', description: 'Find what changed and where it hurts', icon: <BugIcon {...ICON} /> },
  { label: 'Search the docs', description: 'What changed in 2.0, with citations', icon: <GitBranchIcon {...ICON} /> },
]

export default function SuggestionsCards() {
  const [picked, setPicked] = useState<string>()
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <ChatSuggestions layout="cards" label="Ways to start" suggestions={STARTERS} onSelect={setPicked} />
      <p className="min-h-5 text-center text-ui-sm text-fg-muted" aria-live="polite">
        {picked ? `Picked “${picked}”` : 'Each card is a button.'}
      </p>
    </div>
  )
}
```

Four starter prompts as cards, each with an icon and a description.

`layout="cards"` sets them in a two-column grid, with an `icon` and a line of `description` under each label. Chips wrap in a centered row and show only the label and icon.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Use suggestions for ways into a new conversation, or follow-ups under an answer. Picking one hands its prompt to `onSelect`, typically to fill the [Prompt Input](https://www.youj.dev/docs/components/chat/prompt-input) and focus it, so people can edit it before sending. For a whole first-run screen with a greeting, use the [Chat Empty State](https://www.youj.dev/docs/components/chat/empty-state), which includes them.

```tsx
import { ChatSuggestions } from '@youj/react'

<ChatSuggestions
  suggestions={[{ label: 'Show the diff' }, { label: 'Is a rollback safe?', prompt: 'Is rolling back to dpl_7c1e0b2 safe?' }]}
  onSelect={(prompt) => {
    setDraft(prompt)
    composer.current?.focus()
  }}
/>
```

Each suggestion has a `label`, and a `prompt` when what goes in the composer should differ from what the chip says. `delay` waits that many stagger steps before the first one arrives, to follow something else in.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `suggestions` (required) | `ChatSuggestion[]` |  |  |
| `onSelect` (required) | `(prompt: string, suggestion: ChatSuggestion) => void` |  |  |
| `layout` | `'chips' \| 'cards'` | `'chips'` | 'chips' wrap in a row; 'cards' form a two-column grid with descriptions. |
| `label` | `string` | `"Suggested prompts"` | Names the group. |
| `delay` | `number` | `0` | Wait this many stagger steps before the first one arrives. |

Also takes the props of `ComponentProps<'div'>`.

#### ChatSuggestion

Each entry in `suggestions`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | What the chip says. |
| `prompt` | `string` |  | What it puts in the composer. Default: the label. |
| `description` | `string` |  | A second line, shown in the cards layout. |
| `icon` | `ReactNode` |  | Sits before the label. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Each suggestion | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | rises a few px and fades in (Stagger `rise`) |
| Step | `stagger.base` | 40ms step | between one suggestion and the next |

**Reduced motion:** All of them appear at once, in place.

They arrive once, when they mount, and then hold still.

#### Reduced motion

Every suggestion is in place from the first frame, with no rise or fade.

### Accessibility

- The suggestions are a `group` named by `label` (default "Suggested prompts"), and each one is a real button.
- Picking one doesn't send it. Move focus to the composer in `onSelect`, as the examples do, so the next keystroke edits the prompt.

---

# Chat Empty State

> Welcome people to a new conversation with context and suggested prompts.

Source: https://www.youj.dev/docs/components/chat/empty-state

## Examples

### Demo

```tsx
'use client'

import { useRef, useState } from 'react'
import { ChatEmptyState, PromptInput } from '@youj/react'
import { BarChartIcon, BugIcon, GitBranchIcon, RocketIcon } from '@youj/icons'

const ICON = { size: 16, strokeWidth: 1.75 } as const

const STARTERS = [
  { label: 'Ship to production', description: 'Checks, command and a rollback path', prompt: 'How do I ship orion to production with a safe rollback?', icon: <RocketIcon {...ICON} /> },
  { label: 'Compare regions', description: 'Cold starts, p95 and cost per region', prompt: 'Compare cold starts and cost across our regions', icon: <BarChartIcon {...ICON} /> },
  { label: 'Debug a slow page', description: 'Find what changed and where it hurts', prompt: 'Why did checkout get slower after Tuesday?', icon: <BugIcon {...ICON} /> },
  { label: 'Search the docs', description: 'What changed in 2.0, with citations', prompt: 'Search the docs: what changed in 2.0?', icon: <GitBranchIcon {...ICON} /> },
]

export default function ChatEmptyStateDemo() {
  const [draft, setDraft] = useState('')
  const field = useRef<HTMLTextAreaElement>(null)

return (
    <div className="flex w-full max-w-2xl flex-col gap-8 py-4">
      <ChatEmptyState
        greeting="Good morning, Ada"
        description="Ask about your deployments, logs and metrics."
        suggestions={STARTERS}
        onSelect={(prompt) => {
          setDraft(prompt)
          field.current?.focus()
        }}
      />
      <PromptInput value={draft} onValueChange={setDraft} textareaRef={field} onSubmit={() => setDraft('')} />
    </div>
  )
}
```

A greeting and four starter prompts above a composer, where picking one fills the composer.

It's one arrival, in order, then stillness. The icon tile's plates fan out, the greeting rises word by word from behind its line, the description fades in once the greeting has landed, and the suggestions stagger in two steps after that. The greeting's word count sets the timing, so a longer greeting pushes the rest back.

## Installation & usage

```bash
pnpm add @youj/react
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add chat
```

Show it in place of the [message list](https://www.youj.dev/docs/components/chat/message-list) until the first message is sent. It sets expectations (what this assistant can see and do) and offers [suggestions](https://www.youj.dev/docs/components/chat/suggestions) so nobody faces a blank field. For empty views elsewhere in an app, use [Empty State](https://www.youj.dev/docs/components/empty-state), the primitive this is built on.

```tsx
import { ChatEmptyState, ChatMessageList } from '@youj/react'

{messages.length === 0 ? (
  <ChatEmptyState
    greeting="Good morning, Ada"
    description="Ask about your deployments, logs and metrics."
    suggestions={starters}
    onSelect={(prompt) => {
      setDraft(prompt)
      composer.current?.focus()
    }}
  />
) : (
  <ChatMessageList>{/* … */}</ChatMessageList>
)}
```

Suggestions show when both `suggestions` and `onSelect` are set, as cards by default (`suggestionsLayout="chips"` for a row). `icon` replaces the tile's sparkles, and `children` render below everything else.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `greeting` (required) | `string` |  | Revealed word by word, read whole. |
| `description` | `ReactNode` |  |  |
| `icon` | `ReactNode` |  | The tile's icon. Default: youj's SparklesIcon. |
| `suggestions` | `ChatSuggestion[]` |  |  |
| `onSelect` | `(prompt: string, suggestion: ChatSuggestion) => void` |  |  |
| `suggestionsLayout` | `'chips' \| 'cards'` | `'cards'` |  |

Also takes the props of `ComponentProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Greeting | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | each word rises from behind a mask (TextSplit) |
| Greeting step | `stagger.base` | 40ms step | between words |
| Description | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | fades in after one step per word |
| Suggestions | `stagger.base` | 40ms step | rise in sequence, from two steps after the description |

**Reduced motion:** The greeting, description and suggestions are all in place at once.

#### Reduced motion

Everything is in place from the first frame: no plates fanning out, no rising words, no stagger.

### Accessibility

- Screen readers get the greeting whole, not word by word.
- The suggestions are a group of real buttons (see [Suggestions](https://www.youj.dev/docs/components/chat/suggestions)). Pick one and move focus to the composer, as the example does.

---

# Spotlight

> Add a light that follows the pointer across a surface and stays visible on keyboard focus.

Source: https://www.youj.dev/docs/components/spotlight

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { cn } from '@youj/core'
import { SpotlightGroup, SpotlightSurface } from '@youj/motion'
import { CheckIcon } from '@youj/icons'

const PLANS = [
  { id: 'hobby', name: 'Hobby', price: '$0', note: 'For side projects', features: ['1 project', 'Preview deploys', 'Community support'] },
  { id: 'pro', name: 'Pro', price: '$24', note: 'Per seat, per month', features: ['Unlimited projects', 'Password protection', 'Priority builds'] },
  { id: 'team', name: 'Team', price: '$64', note: 'Per seat, per month', features: ['SSO and audit log', 'Role-based access', '99.99% uptime SLA'] },
]

export default function SpotlightDemo() {
  const [plan, setPlan] = useState('pro')

return (
    <fieldset className="@container w-full max-w-2xl">
      <legend className="mb-3 text-sm font-medium text-fg">Choose a plan</legend>
      {/* One light for all three surfaces: near a card's edge, its neighbor lights up too. */}
      <SpotlightGroup radius={220} className="grid gap-3 @xl:grid-cols-3">
        {PLANS.map((p) => {
          const selected = plan === p.id
          return (
            <SpotlightSurface
              key={p.id}
              className={cn(
                'rounded-2xl border bg-surface transition-colors duration-(--yj-duration-fast) ease-standard has-focus-visible:ring-2 has-focus-visible:ring-accent',
                selected ? 'border-accent' : 'border-line',
              )}
            >
              <label className="flex h-full cursor-pointer flex-col p-5">
                <input type="radio" name="plan" value={p.id} checked={selected} onChange={() => setPlan(p.id)} className="sr-only" />
                <span className="flex items-center justify-between">
                  <span className="text-sm font-medium text-fg">{p.name}</span>
                  <span
                    aria-hidden
                    className={cn(
                      'grid size-4 place-items-center rounded-full border',
                      selected ? 'border-accent bg-accent text-on-accent' : 'border-line-strong',
                    )}
                  >
                    {selected && <CheckIcon size={11} strokeWidth={3} trigger="mount" />}
                  </span>
                </span>
                <span className="mt-4 text-2xl font-semibold tracking-tight text-fg">{p.price}</span>
                <span className="text-xs text-fg-muted">{p.note}</span>
                <span className="mt-4 flex flex-col gap-1.5 text-[13px] text-fg-muted">
                  {p.features.map((f) => (
                    <span key={f} className="flex items-center gap-2">
                      <CheckIcon size={13} trigger="none" className="text-accent" />
                      {f}
                    </span>
                  ))}
                </span>
              </label>
            </SpotlightSurface>
          )
        })}
      </SpotlightGroup>
    </fieldset>
  )
}
```

Three plans in one group: the light follows the pointer and spills onto the neighboring cards.

When a control inside a surface receives keyboard focus, the light parks at the center of that surface. Moving focus to the next surface glides the light across instead of jumping it. Tab into the plans in the demo, or use the arrow keys between them.

The light follows a mouse or a pen. Touch doesn't move it, because on a touchscreen there's no pointer to follow between taps.

### One surface

```tsx
'use client'

import { SpotlightSurface } from '@youj/motion'
import { ArrowRightIcon, ShieldCheckIcon } from '@youj/icons'

export default function SpotlightStandalone() {
  return (
    <div className="@container w-full max-w-xl">
      {/* Outside a group, a surface tracks the pointer itself. */}
      <SpotlightSurface radius={300} className="rounded-2xl border border-line bg-surface">
        <div className="flex flex-col gap-4 p-5 @md:flex-row @md:items-center">
          <span className="grid size-10 shrink-0 place-items-center rounded-xl border border-line bg-raised text-fg">
            <ShieldCheckIcon size={18} />
          </span>
          <div className="min-w-0 flex-1">
            <p className="text-sm font-medium text-fg">Enterprise</p>
            <p className="mt-0.5 text-sm text-fg-muted">SAML SSO, audit logs and a 99.99% SLA, on your own contract.</p>
          </div>
          <a
            href="#contact-sales"
            className="inline-flex h-9 shrink-0 items-center gap-1.5 self-start rounded-lg bg-fg px-3.5 text-sm font-medium text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface @md:self-center"
          >
            Talk to sales
            <ArrowRightIcon size={14} />
          </a>
        </div>
      </SpotlightSurface>
    </div>
  )
}
```

An Enterprise surface that tracks the pointer on its own.

Outside a group, a surface tracks the pointer itself. The light fades in over the surface under the pointer and glows along its border where it passes.

### Your own light

```tsx
'use client'

import { useRef } from 'react'
import { useSpotlight } from '@youj/motion'

const STATS = [
  { label: 'Regions', value: '18' },
  { label: 'Median latency', value: '42 ms' },
  { label: 'Cache hit rate', value: '96.4%' },
]

export default function SpotlightCustom() {
  const ref = useRef<HTMLDivElement>(null)
  // Only the tracker: it writes --yj-spot-x and --yj-spot-y onto this element for the CSS below.
  useSpotlight(ref)

return (
    <div ref={ref} data-yj-spot-card="" className="relative w-full max-w-xl overflow-hidden rounded-2xl border border-line bg-surface">
      {/* The resting dot grid, in the line color. */}
      <div
        aria-hidden
        className="absolute inset-0 [background-image:radial-gradient(var(--color-line-strong)_1px,transparent_1px)] [background-size:14px_14px]"
      />
      {/* The same grid in the accent, masked to a circle around the pointer. */}
      <div
        aria-hidden
        className="absolute inset-0 [background-image:radial-gradient(var(--color-accent)_1.5px,transparent_1.5px)] [background-size:14px_14px] [mask-image:radial-gradient(150px_circle_at_var(--yj-spot-x,-999px)_var(--yj-spot-y,-999px),black,transparent)]"
      />
      <div className="relative flex h-56 flex-col justify-between p-5">
        <div>
          <p className="text-sm font-medium text-fg">Edge network</p>
          <p className="mt-0.5 text-sm text-fg-muted">Every request is served from the region nearest the visitor.</p>
        </div>
        <dl className="flex flex-wrap gap-x-8 gap-y-3">
          {STATS.map((s) => (
            <div key={s.label}>
              <dt className="text-xs text-fg-muted">{s.label}</dt>
              <dd className="font-mono text-lg font-medium text-fg">{s.value}</dd>
            </div>
          ))}
        </dl>
      </div>
    </div>
  )
}
```

A dot grid that lights in the accent around the pointer, driven by useSpotlight.

`useSpotlight(ref)` is the tracker without the look. It writes the light's position as `--yj-spot-x` and `--yj-spot-y`, in pixels from the top-left corner, onto the element in `ref` when it carries `data-yj-spot-card`, or else onto every `[data-yj-spot-card]` inside it. Use the variables in your own CSS. Here they move a mask that shows an accent copy of a dot grid.

```tsx
import { useRef } from 'react'
import { useSpotlight } from '@youj/motion'

function EdgeNetwork() {
  const ref = useRef<HTMLDivElement>(null)
  useSpotlight(ref)
  return (
    <div ref={ref} data-yj-spot-card="" className="relative overflow-hidden rounded-2xl border border-line">
      <div
        aria-hidden
        className="absolute inset-0 [mask-image:radial-gradient(150px_circle_at_var(--yj-spot-x,-999px)_var(--yj-spot-y,-999px),black,transparent)] …"
      />
      …
    </div>
  )
}
```

Give the variables a far-off fallback, as above, so nothing is lit before the pointer arrives. The hook also sets `data-yj-spot-active` on the root while the light is on, and `data-yj-spot-mode` to `pointer` or `focus`. Pass `false` as its second argument to switch it off.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add spotlight
```

It brings `youj-core` with it.

Use it on surfaces people choose between: plans, integrations, templates. The light shows which one the pointer is on, and a group shows how close the neighbors are. Don't light surfaces that are read rather than chosen, like body text or tables, and don't light every card on a page. For the ready-made card look, use [Spotlight Card](https://www.youj.dev/docs/components/spotlight-card).

`SpotlightSurface` is a surface with the lit layers and no look of its own. Give it a radius, a border and a background.

```tsx
import { SpotlightSurface } from '@youj/motion'

export function Announcement() {
  return (
    <SpotlightSurface className="rounded-2xl border border-line bg-surface p-5">
      <p>Enterprise: SAML SSO, audit logs and a 99.99% SLA.</p>
    </SpotlightSurface>
  )
}
```

Wrap several surfaces in a `SpotlightGroup` to share one light between them. The group tracks the pointer once and gives every surface the position in its own coordinates, so a card lights along the edge nearest the cursor even while the cursor is over its neighbor.

```tsx
import { SpotlightGroup, SpotlightSurface } from '@youj/motion'

<SpotlightGroup className="grid grid-cols-3 gap-3">
  {plans.map((plan) => (
    <SpotlightSurface key={plan.id} className="rounded-2xl border border-line bg-surface">
      <PlanOption plan={plan} />
    </SpotlightSurface>
  ))}
</SpotlightGroup>
```

The group adds no layout, so bring your own grid or flex classes. `radius` sets the size of the light in pixels, 260 by default, on the group for every surface or on a single surface.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### SpotlightSurface

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `radius` | `number` | `260` | Radius of the light in px when used outside a SpotlightGroup. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### SpotlightGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `radius` | `number` | `260` | Radius of the light in px. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### useSpotlight

```ts
function useSpotlight(root: RefObject<HTMLElement | null>, enabled?: boolean): void
```

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `RefObject<HTMLElement \| null>` |  | The element to track over. Surfaces are `root` itself when it has `data-yj-spot-card`, otherwise every `[data-yj-spot-card]` inside it. |
| `enabled` | `boolean` | `true` | Turns tracking off. It's also off under reduced motion. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pointer |  | one write per animation frame | the light follows the pointer |
| Keyboard glide | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the light moves to the focused surface |
| Glow in and out | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | surface glow and border glow, `opacity` |

**Reduced motion:** No tracking and no glow. The hovered or focused surface shows a static accent border instead.

The light is a radial gradient moved with `transform`, and the border glow is the same gradient masked down to a 1px ring. Pointer moves are batched to one style write per frame, and nothing triggers layout.

#### Reduced motion

Nothing tracks the pointer. The hovered or focused surface shows a static accent border, so a reader still sees which surface they're on, and the light never moves. `useSpotlight` doesn't write its variables at all, so design your own CSS to stand on its own unlit, as the dot grid in the custom-light preview does.

### Accessibility

- The lit layers are `aria-hidden` and ignore the pointer. The effect adds no roles and no tab stops, so a surface reads exactly like its content.
- Keyboard users get the same light as pointer users: focus parks it on the focused surface. Keep a visible focus ring on the control itself too, as the plans in the demo do with `has-focus-visible:ring-2`, because a glow alone isn't a focus indicator.
- The light is decoration. Selection, state and meaning belong in the content, like the check on the chosen plan.

---

# Spotlight Card

> Light cards under the pointer, with a shared glow across neighboring cards.

Source: https://www.youj.dev/docs/components/spotlight-card

## Examples

### Demo

```tsx
'use client'

import { ArrowUpRightIcon, DatabaseIcon, GitBranchIcon, LineChartIcon, MessagesIcon, ShieldCheckIcon, WebhookIcon } from '@youj/icons'
import { SpotlightCard, SpotlightGrid } from '@youj/motion/interactions'

const INTEGRATIONS = [
  { slug: 'git', Icon: GitBranchIcon, name: 'Git provider', body: 'Preview every branch. Checks land on the pull request.', installed: true },
  { slug: 'chat', Icon: MessagesIcon, name: 'Chat alerts', body: 'Send deploy and incident alerts to the channel that owns them.', installed: true },
  { slug: 'postgres', Icon: DatabaseIcon, name: 'Postgres', body: 'Branch the database with every preview, seeded and isolated.' },
  { slug: 'analytics', Icon: LineChartIcon, name: 'Analytics', body: 'Core Web Vitals per route and per deploy.' },
  { slug: 'sso', Icon: ShieldCheckIcon, name: 'SSO', body: 'SAML and SCIM, with roles mapped from your identity provider.' },
  { slug: 'webhooks', Icon: WebhookIcon, name: 'Webhooks', body: 'Signed events for deploys and domains, retried for 24 hours.' },
]

export default function SpotlightCardDemo() {
  return (
    <div className="@container w-full max-w-2xl">
      <p className="text-sm font-medium text-fg">Integrations</p>
      <p className="mt-0.5 mb-4 text-sm text-fg-muted">Connect the tools your team already uses.</p>
      {/* The grid tracks the pointer once and lights every card in its own coordinates. */}
      <SpotlightGrid className="grid-cols-1 gap-3 @md:grid-cols-2 @xl:grid-cols-3">
        {INTEGRATIONS.map(({ slug, Icon, name, body, installed }) => (
          <SpotlightCard key={slug}>
            <a
              href={`#integration-${slug}`}
              className="block h-full rounded-xl p-4 outline-none focus-visible:ring-2 focus-visible:ring-accent"
            >
              <span className="flex items-start justify-between">
                <span className="grid size-9 place-items-center rounded-lg border border-line bg-raised text-fg">
                  <Icon size={16} />
                </span>
                {installed ? (
                  <span className="rounded-full border border-line px-2 py-0.5 text-[11px] text-fg-muted">Installed</span>
                ) : (
                  <ArrowUpRightIcon size={15} className="text-fg-muted" />
                )}
              </span>
              <span className="mt-4 block text-sm font-medium text-fg">{name}</span>
              <span className="mt-1 block text-[13px] leading-5 text-fg-muted">{body}</span>
            </a>
          </SpotlightCard>
        ))}
      </SpotlightGrid>
    </div>
  )
}
```

An integrations grid where one pointer lights every card, and neighboring edges share the glow.

### Standalone cards

```tsx
'use client'

import { SpotlightCard } from '@youj/motion/interactions'

const METRICS = [
  { label: 'p95 latency', value: '82', unit: 'ms', change: '−14% since last deploy', good: true },
  { label: 'Error rate', value: '0.08', unit: '%', change: '−0.02 pts this week', good: true },
  { label: 'Cold starts', value: '312', unit: '/ day', change: '+9% this week', good: false },
]

export default function SpotlightCardStandalone() {
  return (
    // A plain grid, not a SpotlightGrid: each card tracks the pointer on its own, so neighbors stay dark.
    <div className="@container w-full max-w-2xl">
      <div className="grid gap-3 @lg:grid-cols-3">
        {METRICS.map((m) => (
          <SpotlightCard key={m.label} radius={180} className="p-5">
            <p className="text-xs text-fg-muted">{m.label}</p>
            <p className="mt-2 text-3xl font-semibold tracking-tight text-fg">
              {m.value}
              <span className="ms-1 text-sm font-normal text-fg-muted">{m.unit}</span>
            </p>
            <p className={m.good ? 'mt-1 text-xs text-success' : 'mt-1 text-xs text-warning'}>{m.change}</p>
          </SpotlightCard>
        ))}
      </div>
    </div>
  )
}
```

Three metric cards that each track the pointer on their own.

A `SpotlightCard` outside a grid tracks the pointer by itself. Its light stays inside it, and its neighbors stay dark. Use standalone cards when they sit apart, like metrics in a row, and a grid when they read as one set.

`radius` sets the size of the light in pixels, 260 by default. Use a smaller light on smaller cards, as the metric cards in the preview do with 180, so the glow stays a highlight rather than a wash.

### Selectable cards

```tsx
'use client'

import { useId, useState } from 'react'
import { CheckCircleIcon } from '@youj/icons'
import { SpotlightCard, SpotlightGrid } from '@youj/motion/interactions'

const REGIONS = [
  { code: 'iad1', city: 'Washington, D.C.', latency: 4 },
  { code: 'sfo1', city: 'San Francisco', latency: 62 },
  { code: 'fra1', city: 'Frankfurt', latency: 88 },
]

export default function SpotlightCardSelectable() {
  const name = useId()
  const [region, setRegion] = useState('iad1')

return (
    <div className="@container w-full max-w-2xl">
      <fieldset className="min-w-0">
        <legend className="text-sm font-medium text-fg">Function region</legend>
        <p className="mt-0.5 mb-4 text-sm text-fg-muted">Your database is in iad1. Run your functions close to it.</p>
        {/* A radio fills each card, so the arrow keys move the selection and the light glides along with focus. */}
        <SpotlightGrid radius={160} className="grid-cols-1 gap-3 @md:grid-cols-3">
          {REGIONS.map((r) => (
            <SpotlightCard key={r.code} className="has-checked:border-accent">
              <label className="block h-full cursor-pointer rounded-xl p-4 has-focus-visible:ring-2 has-focus-visible:ring-accent">
                <input
                  type="radio"
                  name={name}
                  value={r.code}
                  checked={region === r.code}
                  onChange={() => setRegion(r.code)}
                  className="sr-only"
                />
                <span className="flex h-4 items-center justify-between">
                  <span className="font-mono text-xs text-fg-muted">{r.code}</span>
                  {region === r.code && <CheckCircleIcon size={16} trigger="mount" className="text-accent" />}
                </span>
                <span className="mt-5 block text-sm font-medium text-fg">{r.city}</span>
                <span className="mt-0.5 block text-xs text-fg-muted">{r.latency} ms to your database</span>
              </label>
            </SpotlightCard>
          ))}
        </SpotlightGrid>
      </fieldset>
    </div>
  )
}
```

A function-region picker with a radio in each card and the light following the selection.

For a choice, put a radio in each card and let its label fill the card: the arrow keys move the selection, and the light glides with it.

Mark the selected card in its content, here with an accent border and a check, not with the glow. `radius` on the grid sets the size of the light for every card in it.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add spotlight-card
```

It brings `youj-core`, `spotlight` with it.

Use it for a grid of choices people scan with the pointer: integrations, templates, plans. The light tells them where they are, and the shared glow along neighboring edges makes the grid feel like one surface. Keep it off dense dashboards, where every card is read rather than chosen. `SpotlightCard` is the [Spotlight](https://www.youj.dev/docs/components/spotlight) effect with a card look, so reach for the effect when you need your own look.

`SpotlightGrid` lays out its cards and shares one light across them. It's a CSS grid, so add your own columns and gaps.

```tsx
import { SpotlightCard, SpotlightGrid } from '@youj/motion/interactions'

export function Integrations({ items }: { items: Integration[] }) {
  return (
    <SpotlightGrid className="grid-cols-3 gap-3">
      {items.map((item) => (
        <SpotlightCard key={item.slug}>
          <a href={`/integrations/${item.slug}`} className="block h-full rounded-xl p-4">
            {item.name}
          </a>
        </SpotlightCard>
      ))}
    </SpotlightGrid>
  )
}
```

A card brings the look: a 12px radius, a hairline border and the surface color. Pass `className` to change any of it. When the whole card is one link or button, put the control inside the card and let it fill the card, as the demo does, so the card and its target are the same size.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### SpotlightCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `radius` | `number` | `260` | Radius of the light in px when used outside a SpotlightGroup. |
| `children` | `ReactNode` |  |  |

Other props pass through to the card's `div`.

#### SpotlightGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `radius` | `number` | `260` | Radius of the light in px. |
| `children` | `ReactNode` |  |  |

Other props pass through to the grid's `div`.

### Keyboard

Tab through the grid in the demo. Keyboard focus parks the light at the center of the focused card, and moving focus to the next card glides it across. Touch doesn't move the light.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pointer |  | one write per animation frame | the light follows the pointer |
| Keyboard glide | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the light moves to the focused card |
| Glow in and out | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | surface glow and border glow, `opacity` |

**Reduced motion:** No tracking and no glow. The hovered or focused card shows a static accent border instead.

#### Reduced motion

The light doesn't follow the pointer. The card under the pointer, or the one holding keyboard focus, shows a static accent border, so the grid still marks where the reader is, without movement.

### Accessibility

- The light's layers are `aria-hidden`, and the cards add no roles or tab stops. Put the link or button inside the card, and give it a visible focus ring.
- Keyboard focus lights the focused card just as the pointer does, so the effect is never pointer-only.
- The glow is decoration. Say what the card is, and whether it's installed or selected, in its content.

---

# Shimmer

> Draw attention to an element with accent light that travels along its border.

Source: https://www.youj.dev/docs/components/shimmer

## Examples

### Demo

```tsx
'use client'

import { Shimmer } from '@youj/motion'
import { SearchIcon } from '@youj/icons'
import { Kbd, KbdGroup } from '@youj/react'

export default function ShimmerDemo() {
  return (
    <div className="w-full max-w-md">
      {/* Hover or focus the field: the light lengthens and a bloom lifts along the edge. */}
      <Shimmer className="rounded-xl bg-surface">
        <label className="relative z-2 flex h-12 cursor-text items-center gap-3 px-4">
          <SearchIcon size={16} className="shrink-0 text-fg-muted" />
          <span className="sr-only">Search the docs or ask a question</span>
          <input
            placeholder="Search the docs or ask a question…"
            className="h-full min-w-0 flex-1 bg-transparent text-sm text-fg outline-none placeholder:text-fg-muted"
          />
          <KbdGroup className="max-sm:hidden">
            <Kbd>⌘</Kbd>
            <Kbd>K</Kbd>
          </KbdGroup>
        </label>
      </Shimmer>
      <p className="mt-3 text-center text-xs text-fg-muted">Answers cite the page they come from.</p>
    </div>
  )
}
```

A docs search field wrapped in Shimmer; hover or focus it to lengthen the light.

### On your own element

```tsx
'use client'

import { cn } from '@youj/core'
import { useShimmer } from '@youj/motion'
import { ArrowRightIcon, SparklesIcon } from '@youj/icons'

function UpgradeLink() {
  // The effect on an element you already have: spread rootProps, render layers first.
  const { rootProps, layers } = useShimmer<HTMLAnchorElement>({ idle: 'visible', speed: 'slow' })
  return (
    <a
      href="#pricing"
      {...rootProps}
      className={cn(
        rootProps.className,
        'inline-flex h-7 items-center rounded-full bg-surface px-3 text-xs font-medium text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas',
      )}
    >
      {layers}
      {/* Content sits above the light's layers. */}
      <span className="relative z-2 inline-flex items-center gap-1.5">
        <SparklesIcon size={14} className="text-accent" />
        Try Pro free
        <ArrowRightIcon size={12} />
      </span>
    </a>
  )
}

export default function ShimmerUseShimmer() {
  return (
    <nav aria-label="Workspace" className="flex w-full max-w-xl items-center gap-4 rounded-xl border border-line bg-canvas px-3 py-2">
      <span className="flex items-center gap-2 text-sm font-medium text-fg">
        <span aria-hidden className="size-5 rounded-md bg-fg" />
        northwind
      </span>
      {['Projects', 'Usage'].map((item) => (
        <a
          key={item}
          href={`#${item.toLowerCase()}`}
          className="rounded-sm text-sm text-fg-muted outline-none hover:text-fg focus-visible:ring-2 focus-visible:ring-accent max-sm:hidden"
        >
          {item}
        </a>
      ))}
      <span className="ms-auto">
        <UpgradeLink />
      </span>
    </nav>
  )
}
```

A workspace nav whose Upgrade link takes the effect through useShimmer.

`useShimmer()` puts the effect on an element you already render, like a link or a button. Spread `rootProps` on it, merging `className` and `style` with your own, and render `layers` as its first children.

```tsx
import { cn } from '@youj/core'
import { useShimmer } from '@youj/motion'

function UpgradeLink() {
  const { rootProps, layers } = useShimmer<HTMLAnchorElement>({ idle: 'visible', speed: 'slow' })
  return (
    <a href="/pricing" {...rootProps} className={cn(rootProps.className, 'rounded-full px-3')}>
      {layers}
      <span className="relative z-2">Try Pro free</span>
    </a>
  )
}
```

### Options

```tsx
'use client'

import type { ReactNode } from 'react'
import { Shimmer, type ShimmerOptions } from '@youj/motion'

const IDLE: NonNullable<ShimmerOptions['idle']>[] = ['subtle', 'visible', 'hidden']
const SPEED: NonNullable<ShimmerOptions['speed']>[] = ['slow', 'base', 'fast']

function Row({ label, children }: { label: string; children: ReactNode }) {
  return (
    <div>
      <p className="mb-2 font-mono text-xs text-fg-muted">{label}</p>
      <div className="grid grid-cols-3 gap-3">{children}</div>
    </div>
  )
}

function Tile({ children, ...options }: ShimmerOptions & { children: string }) {
  return (
    <Shimmer {...options} className="grid h-16 place-items-center rounded-xl bg-surface">
      <code className="relative z-2 font-mono text-xs text-fg">{children}</code>
    </Shimmer>
  )
}

export default function ShimmerOptionsDemo() {
  // Hover a tile to intensify it. `hidden` only shows the light on hover and focus.
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <Row label="idle">
        {IDLE.map((idle) => (
          <Tile key={idle} idle={idle}>
            {idle}
          </Tile>
        ))}
      </Row>
      <Row label="speed">
        {SPEED.map((speed) => (
          <Tile key={speed} speed={speed} idle="visible">
            {speed}
          </Tile>
        ))}
      </Row>
    </div>
  )
}
```

Tiles for each idle setting and for different speeds.

`idle` sets how visible the light is at rest: `subtle`, the default, `visible`, or `hidden`, which only shows it on hover and focus. `speed` sets how long one lap takes. `intensify`, on by default, lengthens the light and lifts a soft bloom along the edge while the element is hovered or holds keyboard focus. Hover the tiles.

`borderWidth` thickens the border that carries the light, in pixels. Past 2px it starts to read as an outline rather than a glint.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add shimmer
```

It brings `youj-core` with it.

Use it for a single invitation: an AI prompt, a search field, an upgrade link. It keeps moving, so it pulls the eye, which is the point and also the cost. Use one per screen, and not on anything the reader has to concentrate on nearby, like a form or a long text. For the ready-made composer and button looks, use [Shimmer Border](https://www.youj.dev/docs/components/shimmer-border).

`Shimmer` wraps anything in the effect and brings no look of its own. Give it a radius and a background.

```tsx
import { Shimmer } from '@youj/motion'

export function AskField() {
  return (
    <Shimmer className="rounded-xl bg-surface">
      <label className="relative z-2 flex h-12 items-center gap-3 px-4">
        <span className="sr-only">Search the docs or ask a question</span>
        <input placeholder="Search the docs or ask a question…" />
      </label>
    </Shimmer>
  )
}
```

The element gets a 1px border in `--color-line`, and the light travels along it. Keep your content above the light's layers with `relative z-2`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### Shimmer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `idle` | `'subtle' \| 'visible' \| 'hidden'` | `'subtle'` | How visible the light is at rest. 'hidden' only shows it on hover / focus. |
| `intensify` | `boolean` | `true` | Lengthen the comet and add a bloom on hover and keyboard focus. |
| `speed` | `'slow' \| 'base' \| 'fast'` | `'base'` | One lap of the border. |
| `borderWidth` | `number` | `1` | Border width in px. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### useShimmer

```ts
function useShimmer<T extends HTMLElement>(options?: ShimmerOptions): {
  rootProps: { ref; className; style; 'data-intensify'; 'data-reduced' }
  layers: ReactNode
}
```

`ShimmerOptions` are the same four options as the component's props:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `idle` | `'subtle' \| 'visible' \| 'hidden'` | `'subtle'` | How visible the light is at rest. `hidden` shows it only on hover and focus. |
| `intensify` | `boolean` | `true` | Lengthen the light and add a bloom on hover and keyboard focus. |
| `speed` | `'slow' \| 'base' \| 'fast'` | `'base'` | How long one lap of the border takes. |
| `borderWidth` | `number` | `1` | Border width in pixels. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lap | `ease.linear` | cubic-bezier(0, 0, 1, 1); deliberate × 10, × 6, × 3.5 | `speed`: `slow`, `base`, `fast` |
| Intensify | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | longer light, bloom, full strength |

**Reduced motion:** The light is parked at a fixed point on the border and doesn't travel. Hover and focus still intensify it, instantly.

At normal speed a lap takes 5.6 s (`slow`), 3.36 s (`base`) or 1.96 s (`fast`). The loop runs entirely in CSS: the light is a conic gradient whose start angle is a registered `@property`, so the browser animates it with no JavaScript per frame. The length of the light is a registered property too, so leaving mid-way through intensifying reverses from where it is. The loop pauses while the element is offscreen or the tab is hidden.

#### Reduced motion

The light stops traveling and stays parked at a fixed point on the border, so the element keeps its accent glint without movement. Hover and focus still lengthen it, instantly, with no transition.

### Accessibility

- The light's layers are `aria-hidden` and ignore the pointer. The effect adds no roles and no tab stops.
- Keyboard focus intensifies the light exactly like hover, so keyboard users see the same emphasis. It isn't a focus ring, though: keep the control's own focus indicator.
- A constantly moving element is a distraction for some readers. Keep it to one per screen, and prefer `idle="hidden"` where the emphasis only matters on interaction.

---

# Shimmer Border

> Highlight a container or button with light that travels along its border.

Source: https://www.youj.dev/docs/components/shimmer-border

## Examples

### Demo

```tsx
'use client'

import { useId } from 'react'
import { ArrowUpIcon, AtSignIcon, PaperclipIcon, SparklesIcon } from '@youj/icons'
import { ShimmerBorder } from '@youj/motion/interactions'

const ICON_BUTTON =
  'grid size-8 place-items-center rounded-lg text-fg-muted outline-none hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent'

export default function ShimmerBorderDemo() {
  const id = useId()
  return (
    <div className="w-full max-w-lg">
      <p className="mb-3 text-center text-sm text-fg-muted">Good afternoon, Ada. What should we ship today?</p>
      {/* Focus the prompt, or hover it: the light lengthens and blooms. */}
      <ShimmerBorder className="rounded-2xl">
        <div className="relative z-2">
          <label htmlFor={id} className="sr-only">
            Ask the assistant
          </label>
          <textarea
            id={id}
            rows={3}
            placeholder="Ask anything about your workspace…"
            className="block w-full resize-none bg-transparent px-4 pt-4 text-[15px] leading-6 text-fg outline-none placeholder:text-fg-muted"
          />
          <div className="flex items-center gap-1 px-2 pb-2">
            <button type="button" aria-label="Attach a file" className={ICON_BUTTON}>
              <PaperclipIcon size={16} />
            </button>
            <button type="button" aria-label="Mention a teammate" className={ICON_BUTTON}>
              <AtSignIcon size={16} />
            </button>
            <span className="ms-1 inline-flex items-center gap-1.5 rounded-md border border-line px-2 py-1 font-mono text-[11px] text-fg-muted max-sm:hidden">
              <SparklesIcon size={12} className="text-accent" />
              reasoning · high
            </span>
            <button
              type="button"
              aria-label="Send"
              className="ms-auto grid size-8 place-items-center rounded-lg bg-fg text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
            >
              <ArrowUpIcon size={16} />
            </button>
          </div>
        </div>
      </ShimmerBorder>
    </div>
  )
}
```

An AI prompt box whose border carries the light; focus or hover it to lengthen the light.

### Button

```tsx
'use client'

import { CheckIcon, SparklesIcon } from '@youj/icons'
import { ShimmerButton } from '@youj/motion/interactions'

const FEATURES = ['Unlimited projects and previews', 'SAML SSO and audit log', 'Priority build queue']

export default function ShimmerBorderButton() {
  return (
    <div className="w-full max-w-xs rounded-2xl border border-line bg-surface p-6">
      <div className="flex items-center justify-between">
        <span className="text-sm font-medium text-fg">Pro trial</span>
        <span className="rounded-full bg-raised px-2 py-0.5 font-mono text-[11px] text-fg-muted">14 days left</span>
      </div>
      <p className="mt-4 text-3xl font-semibold tracking-tight text-fg">
        $24<span className="text-base font-normal text-fg-muted"> / seat / mo</span>
      </p>
      <ul className="mt-4 space-y-2 text-sm text-fg-muted">
        {FEATURES.map((f) => (
          <li key={f} className="flex items-center gap-2">
            <CheckIcon size={14} trigger="none" className="text-accent" />
            {f}
          </li>
        ))}
      </ul>
      {/* Tab to it: keyboard focus intensifies the light exactly like hover. */}
      <ShimmerButton className="mt-6 w-full">
        <SparklesIcon size={16} className="text-accent" />
        Upgrade to Pro
      </ShimmerButton>
    </div>
  )
}
```

A trial card with a ShimmerButton as its call to action.

`ShimmerButton` is a button with the same light. It's 36px tall, with an icon gap built in, and it presses down slightly when clicked. Keyboard focus counts as hover, so Tab to it to see the light lengthen.

```tsx
import { ShimmerButton } from '@youj/motion/interactions'
import { SparklesIcon } from '@youj/icons'

<ShimmerButton onClick={openCheckout}>
  <SparklesIcon size={16} className="text-accent" />
  Upgrade to Pro
</ShimmerButton>
```

Both take the effect's options: `idle` (`subtle`, `visible` or `hidden`), `speed` (`slow`, `base` or `fast`), `intensify` and `borderWidth`. See [Shimmer](https://www.youj.dev/docs/components/shimmer#options) for what each one does.

### Featured plan

```tsx
'use client'

import type { ReactNode } from 'react'
import { CheckIcon } from '@youj/icons'
import { ShimmerBorder } from '@youj/motion/interactions'

export default function ShimmerBorderFeatured() {
  return (
    <div className="@container w-full max-w-xl">
      <div className="grid gap-3 @md:grid-cols-2">
        <div className="rounded-xl border border-line bg-surface">
          <Plan name="Hobby" price="$0" unit="/ month" features={['3 projects', 'Preview deployments', 'Community support']}>
            <p className="grid h-9 place-items-center rounded-lg border border-line text-sm text-fg-muted">Current plan</p>
          </Plan>
        </div>
        {/* The radius and surface of its neighbor, so the light is the only difference. It's the one light on
            the screen, so the button inside stays plain. */}
        <ShimmerBorder idle="visible">
          <Plan name="Pro" price="$24" unit="/ seat / mo" features={['Unlimited projects', 'SAML SSO and audit log', 'Priority build queue']}>
            <button
              type="button"
              className="h-9 w-full rounded-lg bg-accent text-sm font-medium text-on-accent outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
            >
              Upgrade to Pro
            </button>
          </Plan>
        </ShimmerBorder>
      </div>
    </div>
  )
}
```

A pair of plans where the Pro plan's border carries the light at rest.

For a featured card, give `ShimmerBorder` the radius and surface of the cards beside it, so the light is the only difference.

`idle="visible"` runs the light at full strength at rest, so the plan stands out before anyone hovers it. The button inside stays plain, since a second light would compete with the first.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add shimmer-border
```

It brings `youj-core`, `youj-presets`, `shimmer` with it.

Use it for the one place a screen invites input or an upgrade: an AI composer, a featured plan, a trial call to action. One shimmer draws the eye, and two compete, so use one per screen. `ShimmerBorder` and `ShimmerButton` are the [Shimmer](https://www.youj.dev/docs/components/shimmer) effect with a surface and a button look. Reach for the effect when the element already has its own look.

`ShimmerBorder` is a container with a 12px radius, the surface color and the traveling light on its border. Keep its content above the light with `relative z-2`.

```tsx
import { ShimmerBorder } from '@youj/motion/interactions'

export function Composer() {
  return (
    <ShimmerBorder className="rounded-2xl">
      <div className="relative z-2">
        <label htmlFor="prompt" className="sr-only">Ask the assistant</label>
        <textarea id="prompt" rows={3} placeholder="Ask anything about your workspace…" />
        <ComposerToolbar />
      </div>
    </ShimmerBorder>
  )
}
```

Focus the prompt in the preview: focus inside the container intensifies the light exactly like hover does.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

#### ShimmerBorder

Other props pass through to the container's `div`.

#### ShimmerButton

Also takes the props of `ButtonHTMLAttributes<HTMLButtonElement>`.

### Motion

**Reduced motion:** The light is parked at a fixed point on the border and doesn't travel. Hover and focus still intensify it, instantly.

The loop is pure CSS on a registered `@property` angle, so it costs no JavaScript per frame, and it pauses while the element is offscreen or the tab is hidden.

#### Reduced motion

The light stops at a fixed point on the border, so the container keeps its accent glint without movement, and hover or focus still brightens it instantly.

### Accessibility

- `ShimmerButton` is a native `button`, `type="button"` unless you pass another type, with a visible focus ring.
- The light's layers are `aria-hidden`. In `ShimmerBorder`, label the controls inside it as you would anywhere else, like the visually hidden label on the prompt in the demo.
- Keyboard focus intensifies the light like hover, so the emphasis never depends on a pointer.

---

# Tilt

> Tilt a surface toward the pointer, with optional glare, then return it to flat.

Source: https://www.youj.dev/docs/components/tilt

## Examples

### Demo

```tsx
'use client'

import { Tilt } from '@youj/motion'

export default function TiltDemo() {
  return (
    // Rounded corners go on Tilt itself, so the glare clips to them.
    <Tilt glare scale={1.02} className="w-full max-w-sm rounded-2xl">
      <div className="relative flex aspect-[1.75] flex-col justify-between overflow-hidden rounded-[inherit] border border-line bg-surface p-5 shadow-lg">
        <div
          aria-hidden
          className="absolute inset-0 bg-[radial-gradient(110%_90%_at_100%_0%,color-mix(in_oklch,var(--color-accent)_30%,transparent),transparent_62%)]"
        />
        <svg aria-hidden viewBox="0 0 200 200" className="absolute -right-20 -bottom-28 size-72 text-fg opacity-[0.07]">
          {Array.from({ length: 9 }, (_, i) => (
            <circle key={i} cx="100" cy="100" r={12 + i * 11} fill="none" stroke="currentColor" />
          ))}
        </svg>
        <div className="relative flex items-start justify-between">
          <p className="text-sm font-semibold tracking-tight text-fg">youj ship</p>
          <p className="font-mono text-xs text-fg-muted">Oct 14 · Online</p>
        </div>
        <div className="relative">
          <p className="text-xl font-semibold tracking-tight text-fg">Priya Raman</p>
          <p className="text-sm text-fg-muted">Staff engineer, Northwind</p>
        </div>
        <div className="relative flex items-end justify-between border-t border-dashed border-line-strong pt-3 font-mono text-xs">
          <span className="text-fg-muted">Ticket</span>
          <span className="tracking-[0.2em] text-fg">#0142</span>
        </div>
      </div>
    </Tilt>
  )
}
```

A ticket-style event card that tilts toward the pointer, with glare and a slight scale.

### Options

```tsx
'use client'

import { Tilt } from '@youj/motion'

const TEMPLATES = [
  { name: 'Commerce starter', meta: 'Next.js · Stripe', max: 4, glare: false, scale: 1, spot: '20% 30%' },
  { name: 'Docs starter', meta: 'MDX · Search', max: 10, glare: true, scale: 1.03, spot: '75% 25%' },
]

export default function TiltOptions() {
  return (
    <div className="flex flex-wrap justify-center gap-8">
      {TEMPLATES.map(({ name, meta, max, glare, scale, spot }) => (
        <figure key={name} className="flex flex-col items-center gap-4">
          <Tilt max={max} glare={glare} scale={scale} className="rounded-xl">
            <div className="w-56 overflow-hidden rounded-[inherit] border border-line bg-surface">
              <div
                aria-hidden
                className="h-32 bg-raised"
                style={{ backgroundImage: `radial-gradient(80% 90% at ${spot}, color-mix(in oklch, var(--color-accent) 38%, transparent), transparent 70%)` }}
              />
              <div className="p-3.5">
                <p className="text-sm font-medium text-fg">{name}</p>
                <p className="text-xs text-fg-muted">{meta}</p>
              </div>
            </div>
          </Tilt>
          <figcaption className="font-mono text-xs text-fg-muted">
            max {max}
            {glare ? ` · glare · scale ${scale}` : ''}
          </figcaption>
        </figure>
      ))}
    </div>
  )
}
```

Templates with different rotation, glare and scale settings.

`max` is the rotation, in degrees, at the edges: the pointer's position across the surface maps linearly from `-max` to `max` on both axes. `perspective` is the CSS perspective distance, where lower is more dramatic. `scale` grows the surface while it's hovered, and `glare` adds a soft highlight that follows the pointer.

The glare is a pre-drawn gradient, twice the surface's size, that translates under a soft-light blend. It never repaints, so it stays on the compositor. Its color follows the theme.

### Depth

```tsx
'use client'

import { Tilt } from '@youj/motion'
import { RocketIcon } from '@youj/icons'

export default function TiltDepth() {
  return (
    <Tilt max={12} className="w-full max-w-xs rounded-2xl">
      {/* Tilt's inner layer preserves 3D. Keep preserving it on the way down, with no overflow clipping,
          and children can sit in front of the surface with translateZ. */}
      <div className="relative rounded-[inherit] border border-line bg-surface p-6 transform-3d">
        <div className="grid size-11 translate-z-12 place-items-center rounded-xl bg-accent text-on-accent shadow-lg">
          <RocketIcon size={20} />
        </div>
        <p className="mt-5 translate-z-6 text-lg font-semibold tracking-tight text-fg">Production is live</p>
        <p className="mt-1 translate-z-3 text-sm text-fg-muted">youj-web deployed to 18 regions in 42 seconds.</p>
      </div>
    </Tilt>
  )
}
```

A card whose icon and text sit at different depths in front of the surface.

Tilt's inner layer preserves 3D. Keep `transform-style: preserve-3d` on the way down, and avoid `overflow: hidden` in between, which flattens it. Then children can sit in front of the surface with `translate-z-*`, and they shift against it as it turns.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add tilt
```

It brings `youj-core` with it.

Use it on one showcase surface that invites a closer look: a ticket, a pricing card, a product shot. Keep it off grids of everyday cards, text-heavy panels, where tilted type is harder to read, and anything people click with precision. For a lighter touch on many cards, use a [Spotlight](https://www.youj.dev/docs/components/spotlight).

Wrap the surface, and put the rounded corners on Tilt itself. Its inner layer inherits them, so the glare clips to the same shape.

```tsx
import { Tilt } from '@youj/motion'

export function Ticket() {
  return (
    <Tilt glare scale={1.02} className="rounded-2xl">
      <div className="rounded-[inherit] border bg-surface p-5">…</div>
    </Tilt>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `8` | Maximum rotation in degrees at the edges. |
| `perspective` | `number` | `900` | CSS perspective distance in px. |
| `glare` | `boolean` | `false` | A soft highlight that tracks the pointer. |
| `scale` | `number` | `1` | Scale while hovered. |
| `spring` | `'snappy' \| 'smooth' \| 'settle'` | `'smooth'` |  |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Tilt | `spring.smooth` | 0.36s, bounce 0 | `rotateX` and `rotateY`, up to `max` degrees at the edges |
| Hover scale and glare | `spring.smooth` | 0.36s, bounce 0 | grow and fade in together |
| Return | `spring.smooth` | 0.36s, bounce 0 | springs flat when the pointer leaves |

**Reduced motion:** Flat and still: no rotation, no scale and no glare.

`spring` swaps the default for another spring token. Every value is a transform or an opacity, so a tilt never triggers layout or paint.

#### Reduced motion

The surface stays flat and still. There's no rotation, no hover scale and no glare, and the content reads exactly as it does at rest.

### Accessibility

- Tilt adds no roles and no focus stop. The content inside keeps its semantics, and interactive children keep their focus rings.
- It responds to a mouse only. Touch and pen input scroll and tap as usual, and keyboard focus doesn't tilt the surface.
- The glare layer is `aria-hidden` and ignores the pointer.
- Keep `max` small on anything with text. Past about 10 degrees, type foreshortens enough to slow reading.

---

# Magnetic

> Pull an element toward a nearby pointer and return it when the pointer leaves.

Source: https://www.youj.dev/docs/components/magnetic

## Examples

### Demo

```tsx
'use client'

import { Magnetic, MagneticInner } from '@youj/motion'
import { ArrowRightIcon } from '@youj/icons'
import { Button } from '@youj/react'

export default function MagneticDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col items-center text-center">
      <p className="text-2xl font-semibold tracking-tight text-balance text-fg">Ship your first preview in minutes.</p>
      <p className="mt-2 text-sm text-fg-muted">Connect a repository, and every push gets its own URL.</p>
      <div className="mt-8 flex flex-wrap items-center justify-center gap-8">
        {/* The shell follows the pointer; the label inside lags half as far, for depth. */}
        <Magnetic strength={0.22} radius={40}>
          <Button size="lg" className="px-5">
            <MagneticInner className="inline-flex items-center gap-2">
              Start deploying
              <ArrowRightIcon size={16} />
            </MagneticInner>
          </Button>
        </Magnetic>
        {/* The secondary action pulls less, so the primary one stays the stronger invitation. */}
        <Magnetic strength={0.12} radius={40}>
          <Button size="lg" variant="outline" className="px-5">
            <MagneticInner>Talk to sales</MagneticInner>
          </Button>
        </Magnetic>
      </div>
    </div>
  )
}
```

A hero with a primary and a secondary call to action that pull toward the pointer, the label inside lagging behind.

### Strength and radius

```tsx
'use client'

import { Magnetic, MagneticInner } from '@youj/motion'
import { PlusIcon } from '@youj/icons'

const RADIUS = 40
const STRENGTHS = [0.2, 0.35, 0.5]

export default function MagneticStrength() {
  return (
    <div className="flex flex-wrap justify-center gap-x-10 gap-y-8">
      {STRENGTHS.map((strength) => (
        <figure key={strength} className="flex flex-col items-center gap-5">
          <div className="relative flex" style={{ margin: RADIUS }}>
            {/* The dashed outline is where the pull begins: `radius` px beyond the element's box. */}
            <span
              aria-hidden
              className="pointer-events-none absolute border border-dashed border-line-strong"
              style={{ inset: -RADIUS, borderRadius: RADIUS }}
            />
            <Magnetic strength={strength} radius={RADIUS}>
              <button
                type="button"
                aria-label="New project"
                className="grid size-12 place-items-center rounded-full bg-accent text-on-accent focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
              >
                <MagneticInner>
                  <PlusIcon size={20} strokeWidth={2} />
                </MagneticInner>
              </button>
            </Magnetic>
          </div>
          <figcaption className="font-mono text-xs text-fg-muted">strength {strength}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

Buttons at different strengths, each inside a dashed outline that shows where the pull begins.

The pull starts `radius` pixels outside the element's box and grows linearly to full strength at the box's edge, so there's no jump when the pointer crosses into range. `strength` is the fraction of the pointer's offset from the center that the element follows: at 0.35, a pointer 20px right of center moves the element 7px. Keep it between about 0.15 and 0.5.

The dashed outlines show each zone. It's measured from the element's rectangle, so a round button still has a rounded-square zone.

### Depth

```tsx
'use client'

import type { ReactNode } from 'react'
import { Magnetic, MagneticInner } from '@youj/motion'
import { SendIcon } from '@youj/icons'

const shell =
  'inline-flex h-11 items-center gap-2 rounded-full border border-line-strong bg-surface px-5 text-sm font-medium text-fg shadow-sm focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none'

function Specimen({ caption, children }: { caption: string; children: ReactNode }) {
  return (
    <figure className="flex flex-col items-center gap-4">
      <Magnetic strength={0.35} radius={56}>
        <button type="button" className={shell}>
          {children}
        </button>
      </Magnetic>
      <figcaption className="font-mono text-xs text-fg-muted">{caption}</figcaption>
    </figure>
  )
}

export default function MagneticDepth() {
  const label = (
    <>
      <SendIcon size={16} />
      Send invite
    </>
  )
  return (
    <div className="flex flex-wrap justify-center gap-x-10 gap-y-8">
      <Specimen caption="no inner">{label}</Specimen>
      <Specimen caption="ratio 0.5">
        <MagneticInner className="inline-flex items-center gap-2">{label}</MagneticInner>
      </Specimen>
      <Specimen caption="ratio 0.2">
        {/* The lower the ratio, the further the button slides beneath its label. */}
        <MagneticInner ratio={0.2} className="inline-flex items-center gap-2">
          {label}
        </MagneticInner>
      </Specimen>
    </div>
  )
}
```

The same button with no inner layer and with MagneticInner at different ratios.

`MagneticInner` goes inside the control, around its label or icon, and travels `ratio` as far as the shell. The default, 0.5, lets the label lag behind the button, which reads as depth. At 0 the label holds still while the button slides beneath it, and above 1 it runs ahead.

`MagneticInner` reads the nearest Magnetic around it. Outside one it renders a plain `inline-block` span.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add magnetic
```

It brings `youj-core` with it.

Use it on one or two calls to action that should feel alive: a hero's primary button, a floating action. It rewards the pointer on its way to the target. Keep it out of dense interfaces like toolbars, forms, menus and tables, where targets must stay exactly where they are, and don't put it on text.

Wrap the control. Magnetic is an `inline-block` wrapper that moves by transform, so the control keeps its layout, its semantics and its focus ring.

```tsx
import { Magnetic, MagneticInner } from '@youj/motion'
import { Button } from '@youj/react'

export function Cta() {
  return (
    <Magnetic strength={0.3} radius={48}>
      <Button size="lg">
        <MagneticInner>Start deploying</MagneticInner>
      </Button>
    </Magnetic>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strength` | `number` | `0.35` | Fraction of the pointer offset the element follows. |
| `radius` | `number` | `80` | Pull starts this many px outside the element's box and grows toward it. |
| `spring` | `'snappy' \| 'smooth' \| 'settle'` | `'smooth'` |  |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLMotionProps<'div'>`.

#### MagneticInner

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `number` | `0.5` | How far the inner content travels relative to the shell. 0.5 = half as far. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLMotionProps<'span'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pull | `spring.smooth` | 0.36s, bounce 0 | `strength` × the pointer offset, fading to zero at `radius` |
| Return | `spring.smooth` | 0.36s, bounce 0 | the pointer leaves the zone or the page, or the window loses focus |
| MagneticInner | `spring.smooth` | 0.36s, bounce 0 | rides the same spring at `ratio` of the travel |

**Reduced motion:** No pull. The element stays in place and works as usual.

`spring` swaps the default for another spring token. `snappy` tracks the pointer more tightly, and `settle` adds a small overshoot on the way home. Only `transform` moves, so the pull never triggers layout.

#### Reduced motion

Magnetic doesn't listen to the pointer at all, and the control sits exactly where the layout put it. Nothing else changes: the button is fully usable, and `MagneticInner` renders its content in place.

### Accessibility

- Magnetic adds no roles and doesn't take focus. The control inside keeps its own name, keyboard behavior and focus ring.
- The pull moves the element toward the pointer, so the target gets closer, never harder to hit.
- It's off when the primary pointer is coarse, as on phones and tablets. Keyboard focus never pulls, so for keyboard users the control stays put.
- Keep the pull small. A button that travels far from its label, or away from the pointer, feels unstable, and moving targets are hard to use for people with motor impairments.

---

# Cursor Follower

> Add a cursor effect that follows the pointer and changes shape over controls, text and media.

Source: https://www.youj.dev/docs/components/cursor-follower

## Examples

### Demo

```tsx
'use client'

import { useRef } from 'react'
import { ArrowRightIcon } from '@youj/icons'
import { CursorFollower } from '@youj/motion/interactions'

const NAV = ['Work', 'Process', 'Journal']
const WORK = [
  { slug: 'northwind', title: 'Northwind', kind: 'Brand system', tone: 'bg-[radial-gradient(120%_90%_at_20%_10%,color-mix(in_oklch,var(--color-accent)_45%,transparent),transparent_65%)]' },
  { slug: 'halcyon', title: 'Halcyon', kind: 'Product site', tone: 'bg-[radial-gradient(120%_90%_at_80%_90%,color-mix(in_oklch,var(--color-accent)_40%,transparent),transparent_60%)]' },
  { slug: 'parallel', title: 'Parallel', kind: 'iOS app', tone: 'bg-[linear-gradient(135deg,var(--color-raised)_30%,color-mix(in_oklch,var(--color-accent)_35%,var(--color-raised)))]' },
]

export default function CursorFollowerDemo() {
  const scope = useRef<HTMLDivElement>(null)

return (
    // The follower only draws while the pointer is inside `scope`. Targets opt in with data-cursor.
    <div ref={scope} className="@container w-full max-w-2xl">
      <CursorFollower scope={scope} />
      <div className="flex items-center justify-between">
        <span className="font-mono text-sm font-medium text-fg">field/studio</span>
        <nav aria-label="Studio" className="flex items-center gap-5 text-sm text-fg-muted">
          {NAV.map((item) => (
            <a
              key={item}
              href={`#${item.toLowerCase()}`}
              data-cursor="link"
              data-cursor-label={`See ${item.toLowerCase()}`}
              className="rounded-sm outline-none hover:text-fg focus-visible:ring-2 focus-visible:ring-accent"
            >
              {item}
            </a>
          ))}
        </nav>
      </div>
      <p data-cursor="text" className="mt-8 max-w-[18ch] text-3xl leading-tight font-semibold tracking-tight text-fg">
        We design software that feels inevitable.
      </p>
      <p data-cursor="text" className="mt-3 max-w-[48ch] text-sm leading-6 text-fg-muted">
        An independent studio for interface, motion and brand, from the first sketch to the last easing curve.
      </p>
      <button
        type="button"
        data-cursor="button"
        className="mt-5 inline-flex h-9 items-center gap-2 rounded-full bg-fg px-4 text-sm font-medium text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas"
      >
        Start a project
        <ArrowRightIcon size={15} />
      </button>
      <div className="mt-8 grid grid-cols-3 gap-3">
        {WORK.map((w) => (
          <a key={w.slug} href={`#${w.slug}`} data-cursor="media" className="block rounded-xl outline-none focus-visible:ring-2 focus-visible:ring-accent">
            <span className={`block aspect-[4/3] rounded-xl border border-line bg-raised ${w.tone}`} />
            <span className="mt-2 flex items-baseline justify-between gap-2 text-sm">
              <span className="font-medium text-fg">{w.title}</span>
              <span className="truncate text-xs text-fg-muted max-sm:hidden">{w.kind}</span>
            </span>
          </a>
        ))}
      </div>
    </div>
  )
}
```

A studio page where the follower reshapes over its links and other targets.

### Targets

```tsx
'use client'

import { useId, useRef, useState } from 'react'
import { CursorFollower } from '@youj/motion/interactions'
import { Label, Switch } from '@youj/react'

export default function CursorFollowerKinds() {
  const id = useId()
  const scope = useRef<HTMLDivElement>(null)
  const [hide, setHide] = useState(false)

return (
    <div ref={scope} className="w-full max-w-xl">
      <CursorFollower scope={scope} hideNativeCursor={hide} />
      <div className="grid grid-cols-2 gap-3">
        <figure className="flex h-28 flex-col items-center justify-center gap-3 rounded-xl border border-line bg-surface">
          <button
            type="button"
            data-cursor="button"
            className="h-8 rounded-lg border border-line bg-canvas px-3 text-sm font-medium text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
          >
            Invite
          </button>
          <figcaption className="font-mono text-xs text-fg-muted">button</figcaption>
        </figure>
        <figure className="flex h-28 flex-col items-center justify-center gap-3 rounded-xl border border-line bg-surface px-4">
          <p data-cursor="text" className="text-center text-sm text-fg">
            Text becomes an I-beam.
          </p>
          <figcaption className="font-mono text-xs text-fg-muted">text</figcaption>
        </figure>
        <figure className="flex h-28 flex-col items-center justify-center gap-3 rounded-xl border border-line bg-surface">
          <a
            href="#changelog"
            data-cursor="link"
            data-cursor-label="Read it"
            className="rounded-sm text-sm text-fg underline decoration-line-strong underline-offset-4 outline-none focus-visible:ring-2 focus-visible:ring-accent"
          >
            Changelog
          </a>
          <figcaption className="font-mono text-xs text-fg-muted">link</figcaption>
        </figure>
        <figure className="flex h-28 flex-col items-center justify-center gap-3 rounded-xl border border-line bg-surface">
          <a
            href="#case-study"
            data-cursor="media"
            aria-label="Northwind case study"
            className="block h-12 w-20 rounded-lg border border-line bg-[radial-gradient(120%_90%_at_20%_10%,color-mix(in_oklch,var(--color-accent)_45%,transparent),transparent_65%)] outline-none focus-visible:ring-2 focus-visible:ring-accent"
          />
          <figcaption className="font-mono text-xs text-fg-muted">media</figcaption>
        </figure>
      </div>
      <div className="mt-4 flex items-center justify-center gap-2">
        <Switch id={id} size="sm" checked={hide} onCheckedChange={setHide} />
        <Label htmlFor={id} className="text-xs font-normal text-fg-muted">
          Hide the native cursor
        </Label>
      </div>
    </div>
  )
}
```

One tile per kind of target, with a control for hiding the native cursor.

Each kind of target gets its own shape. Everything else gets a small, faint halo.

| `data-cursor` | Shape |
| --- | --- |
| `button` | Grows to wrap the target with 6px to spare, matching its corner radius, and leans 10% toward the pointer. |
| `text` | Collapses to an I-beam as tall as the line. |
| `link` | A small pill label beside the pointer. Its text is `data-cursor-label`, or "Open". |
| `media` | A round badge centered on the pointer. Its text is `data-cursor-label`, or "View". |

The native cursor stays visible by default, and the follower moves with it. With `hideNativeCursor`, the follower becomes the cursor: the native one is hidden while the follower is drawing, and a small dot marks the exact pointer position everywhere except over `text` and `media` targets, whose I-beam and badge already mark it. It comes back as soon as the pointer leaves the scope, or when the follower is disabled or unmounted. Try the switch in the preview.

Set `disabled` to turn the follower off, for example while a dialog is open.

### Scope

```tsx
'use client'

import { useId, useRef } from 'react'
import { ArrowRightIcon } from '@youj/icons'
import { CursorFollower } from '@youj/motion/interactions'

const WORK = [
  { slug: 'northwind', title: 'Northwind', kind: 'Brand system', tone: 'bg-[radial-gradient(120%_90%_at_20%_10%,color-mix(in_oklch,var(--color-accent)_45%,transparent),transparent_65%)]' },
  { slug: 'halcyon', title: 'Halcyon', kind: 'Product site', tone: 'bg-[radial-gradient(120%_90%_at_80%_90%,color-mix(in_oklch,var(--color-accent)_40%,transparent),transparent_60%)]' },
  { slug: 'parallel', title: 'Parallel', kind: 'iOS app', tone: 'bg-[linear-gradient(135deg,var(--color-raised)_30%,color-mix(in_oklch,var(--color-accent)_35%,var(--color-raised)))]' },
]

export default function CursorFollowerScope() {
  const id = useId()
  const gallery = useRef<HTMLDivElement>(null)

return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      {/* The follower owns the gallery and hides the native cursor there. The form below is outside its scope. */}
      <div ref={gallery} className="rounded-2xl border border-line bg-surface p-4">
        <CursorFollower scope={gallery} hideNativeCursor />
        <p className="text-sm font-medium text-fg">Selected work</p>
        <div className="mt-3 grid grid-cols-3 gap-3">
          {WORK.map((w) => (
            <a key={w.slug} href={`#${w.slug}`} data-cursor="media" className="block rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-accent">
              <span className={`block aspect-[4/3] rounded-lg border border-line bg-raised ${w.tone}`} />
              <span className="mt-2 block truncate text-xs font-medium text-fg">{w.title}</span>
              <span className="block truncate text-xs text-fg-muted">{w.kind}</span>
            </a>
          ))}
        </div>
      </div>
      <form onSubmit={(e) => e.preventDefault()} className="rounded-2xl border border-line bg-surface p-4">
        <p className="text-sm font-medium text-fg">Start a project</p>
        <p className="mt-0.5 text-xs text-fg-muted">Leave your email and we’ll write back within two days.</p>
        <div className="mt-3 flex gap-2">
          <label htmlFor={id} className="sr-only">
            Email
          </label>
          <input
            id={id}
            type="email"
            placeholder="you@company.com"
            className="h-9 min-w-0 flex-1 rounded-lg border border-line bg-canvas px-3 text-sm text-fg outline-none placeholder:text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
          />
          <button
            type="submit"
            className="inline-flex h-9 shrink-0 items-center gap-2 rounded-lg bg-fg px-4 text-sm font-medium text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
          >
            Send
            <ArrowRightIcon size={15} />
          </button>
        </div>
      </form>
    </div>
  )
}
```

A gallery owned by the follower above a form that keeps the native cursor.

`scope` keeps the follower to one part of the page, so leave forms out of it: over a field, people need the native text cursor to place the caret.

Here the follower owns the gallery and hides the native cursor there. Move down to the form, and the follower fades out as the native cursor comes back.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add cursor-follower
```

It brings `youj-core` with it.

Use it on expressive pages, like a portfolio, a launch or a studio site, where the pointer itself is part of the design. It tells the reader what a target is before they click: a button, some text, a link to read or a project to open. Don't use it in apps and tools. People work there with the cursor they know, and a second one adds latency to every glance. Move the pointer over the preview: it needs a mouse or a trackpad.

Render one follower, scoped to the part of the page it serves, and mark its targets with `data-cursor`.

```tsx
import { useRef } from 'react'
import { CursorFollower } from '@youj/motion/interactions'

export function Studio() {
  const scope = useRef<HTMLDivElement>(null)
  return (
    <div ref={scope}>
      <CursorFollower scope={scope} />
      <h1 data-cursor="text">We design software that feels inevitable.</h1>
      <button data-cursor="button">Start a project</button>
      <a href="/work/northwind" data-cursor="media">…</a>
    </div>
  )
}
```

Without `scope`, it follows the pointer across the whole document. It draws in a fixed layer on top of the page, portaled to `body`, and never takes pointer events, so everything under it stays clickable.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `RefObject<HTMLElement \| null>` |  | Only react inside this element. Default: the whole document. |
| `hideNativeCursor` | `boolean` | `false` | Hide the native cursor while the follower is drawing. Off by default. The native cursor is only hidden once the follower is active and visible, and comes back whenever the follower is disabled or the pointer leaves. |
| `disabled` | `boolean` | `false` | Turn the follower off. It is also off for touch / coarse pointers, reduced motion and the low motion-budget tier. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Position | `spring.snappy` | 0.2s, bounce 0 | follows the pointer |
| Shape | `spring.smooth` | 0.36s, bounce 0 | width, height and corner radius |
| Fill and label | `spring.snappy` | 0.2s, bounce 0 | crossfades between kinds |

**Reduced motion:** Renders nothing. The native cursor does all the work.

Position and shape run on separate springs, so moving feels immediate while a change of shape feels deliberate. The shape is one box scaled on each axis, with its corners counter-scaled so they stay round mid-morph, and the label sits outside the scaled box so its text never stretches. Every update happens in the pointer handler, with no React render per move. The follower appears where the pointer first enters, instead of flying in from a corner, and when the page scrolls it re-reads what's under the pointer.

#### Reduced motion

The follower renders nothing at all, as it also does on the low motion-budget tier: a cursor that trails the pointer is motion for its own sake, and there's no static version that says anything the native cursor doesn't. If `hideNativeCursor` is set, the native cursor stays visible.

### Accessibility

- The layer is `aria-hidden`, ignores the pointer and never takes focus. Keyboard users never see it, and every target keeps its own focus ring.
- Labels like "View" and "See work" are visual only. Give every link and button a name of its own in its content or with `aria-label`.
- It renders nothing for touch and other coarse pointers, or on the low [motion budget](https://www.youj.dev/docs/motion/in-your-components#the-motion-budget) tier, and keeps the native cursor unless you ask otherwise with `hideNativeCursor`.

---

# Liquid Glass

> Put a pane of liquid glass behind a button, pill or toolbar that leans toward the pointer and squishes when pressed.

Source: https://www.youj.dev/docs/components/liquid-glass

## Examples

### Demo

```tsx
'use client'

import { LiquidGlass } from '@youj/motion/interactions'
import { Aurora } from '@youj/motion/backgrounds'

const button =
  'inline-flex h-11 items-center rounded-full px-5 text-sm font-medium text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent'

export default function LiquidGlassDemo() {
  return (
    <div className="relative grid min-h-[420px] w-full place-items-center overflow-hidden rounded-xl bg-canvas">
      <Aurora className="absolute inset-0" />
      <div className="relative flex flex-col items-center gap-7 px-6 text-center">
        <p className="max-w-sm text-2xl font-semibold tracking-tight text-balance text-fg">Your work, in one calm place</p>
        <div className="flex flex-wrap justify-center gap-3">
          {/* The radius goes on LiquidGlass, so the glass takes it. */}
          <LiquidGlass className="rounded-full">
            <button type="button" className={button}>
              Start free
            </button>
          </LiquidGlass>
          <LiquidGlass className="rounded-full">
            <button type="button" className={button}>
              Watch the tour
            </button>
          </LiquidGlass>
        </div>
      </div>
    </div>
  )
}
```

Two glass buttons over a live aurora. Each leans toward the pointer, its highlight follows, and a press squishes it.

### Floating toolbar

```tsx
'use client'

import { useState } from 'react'
import { LiquidGlass } from '@youj/motion/interactions'
import { BoldIcon, ItalicIcon, LinkIcon, ListIcon, UnderlineIcon } from '@youj/icons'

const TOOLS = [
  { id: 'bold', label: 'Bold', Icon: BoldIcon },
  { id: 'italic', label: 'Italic', Icon: ItalicIcon },
  { id: 'underline', label: 'Underline', Icon: UnderlineIcon },
  { id: 'link', label: 'Link', Icon: LinkIcon },
  { id: 'list', label: 'List', Icon: ListIcon },
]

export default function LiquidGlassToolbar() {
  const [on, setOn] = useState<Set<string>>(() => new Set(['bold']))
  const toggle = (id: string) =>
    setOn((s) => {
      const next = new Set(s)
      if (!next.delete(id)) next.add(id)
      return next
    })

return (
    <div className="relative w-full max-w-lg overflow-hidden rounded-xl border border-line bg-surface p-6">
      {/* The bar floats over the text, so the glass has something to blur. */}
      <p className="text-lg font-semibold tracking-tight text-fg">Release notes</p>
      <p className="mt-2 text-sm leading-relaxed text-fg-muted">
        Search now matches comments and attachments. Saved views sync across devices, and the inbox groups related updates so a busy thread reads as
        one item. Exports keep your column order.
      </p>
      <p className="mt-3 text-sm leading-relaxed text-fg-muted">
        Charts gain a compare mode: pick two ranges and the second draws as a dashed line over the first. Shared links open on the same range and
        filters you were looking at, and embeds follow the viewer's theme.
      </p>
      <div className="absolute inset-x-0 bottom-5 flex justify-center">
        <LiquidGlass className="rounded-full">
          <div role="toolbar" aria-label="Formatting" className="flex items-center gap-1 p-1.5">
            {TOOLS.map(({ id, label, Icon }) => (
              <button
                key={id}
                type="button"
                aria-label={label}
                aria-pressed={on.has(id)}
                onClick={() => toggle(id)}
                className="grid size-9 place-items-center rounded-full text-fg-muted outline-none hover:text-fg focus-visible:ring-2 focus-visible:ring-accent aria-pressed:bg-selected aria-pressed:text-fg"
              >
                <Icon size={16} aria-hidden />
              </button>
            ))}
          </div>
        </LiquidGlass>
      </div>
    </div>
  )
}
```

A formatting toolbar floating over the text it edits.

The glass blurs and saturates what's behind it, so the bar stays readable over text, images or a gradient without hiding them. The whole bar leans and squishes as one pane, so wrap the bar, not each button.

`bulge` sets how far the pane leans toward the pointer, 4px by default; 0 keeps it still while the highlight still follows. `blur` sets the backdrop blur, 12px by default. `squish={false}` turns off the press.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add liquid-glass
```

It brings `youj-core` with it.

Use it for a few floating controls over rich content: a hero's buttons over a background, a toolbar over a canvas, a player's controls over video. Keep it off dense forms and lists, where a pane of glass behind every control is noise, and off plain flat surfaces, where there's nothing for the glass to bend.

Wrap the control and put the radius on LiquidGlass itself, so the glass takes the same shape.

```tsx
import { LiquidGlass } from '@youj/motion/interactions'

export function GlassButton() {
  return (
    <LiquidGlass className="rounded-full">
      <button type="button" className="h-11 rounded-full px-5 text-sm font-medium">
        Start free
      </button>
    </LiquidGlass>
  )
}
```

The glass is a layer behind the content, so the content keeps its own size, padding and focus ring. Other props pass through to the wrapper's `div`.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bulge` | `number` | `4` | How far the glass leans toward the pointer, in px. 0 keeps it still (the highlight still follows). |
| `blur` | `number` | `12` | Blur of what's behind the glass, in px. |
| `squish` | `boolean` | `true` | Squish on press. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLMotionProps<'div'>`.

| Data attribute | Values |
| --- | --- |
| `data-slot` | `liquid-glass` |
| `data-yj-reduced` | present under reduced motion |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Lean | `spring.settle` | 0.45s, bounce 0.3 | the pane moves up to `bulge` px toward the pointer and swells along that direction |
| Highlight | `spring.settle` | 0.45s, bounce 0.3 | the specular and the brightest stretch of rim slide to the pointer, and back to the top left on leave |
| Press | `spring.settle` | 0.45s, bounce 0.3 | the whole glass, content included, widens 4% and flattens 8%, then springs back |

**Reduced motion:** Static glass: the blur, rim and highlight stay, and nothing leans, follows or squishes.

The glass springs on `settle`, the kit's one spring that overshoots, so it lags the pointer a little and wobbles into place like something with mass. The pointer is read once per move, and everything else is a transform or a custom property on two layers, so it never triggers layout. There's no WebGL and no SVG filter: the refraction is drawn with `backdrop-filter`, gradients and inset shadows.

#### Reduced motion

The glass is still: the highlight rests at the top left, and the pane doesn't lean or squish. The blur, rim and drop shadow stay, so the control looks the same at rest.

### Accessibility

- The glass layers are `aria-hidden`, and the wrapper adds no role and no tab stop. The button or link inside carries the name, the role and the focus ring.
- It follows a mouse or pen only. Touch taps and scrolls as usual.
- Text on glass sits on whatever is behind it. Check the contrast over the busiest part of your background, and darken or lighten the backdrop if it drops below 4.5:1.

---

# Mesh Gradient

> Add a slowly shifting, theme-aware gradient behind a hero section.

Source: https://www.youj.dev/docs/components/mesh-gradient

## Examples

### Demo

```tsx
'use client'

import { MeshGradient } from '@youj/motion/backgrounds'

export default function MeshGradientDemo() {
  return (
    <section className="relative isolate flex min-h-[380px] w-full flex-col items-center justify-center overflow-hidden px-6 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <MeshGradient />
      <p className="relative mb-4 rounded-full border border-line bg-surface/60 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        Realtime sync, now in every plan
      </p>
      <h2 className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        The workspace that moves as fast as you think
      </h2>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Move the pointer over it: the field leans toward you.
      </p>
    </section>
  )
}
```

A hero section over the gradient field, which leans toward the pointer.

### Color

```tsx
'use client'

import { MeshGradient } from '@youj/motion/backgrounds'

// Any CSS colors work; tokens keep the field in step with the theme.
const COLORS = ['var(--color-success)', 'var(--color-accent)', 'var(--color-warning)', 'var(--color-success)']

export default function MeshGradientColors() {
  return (
    <div className="relative isolate min-h-[320px] w-full overflow-hidden rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <MeshGradient colors={COLORS} intensity={0.8} grain={0.35} />
    </div>
  )
}
```

A field in success, accent and warning colors with a lower intensity and some grain.

By default the colors come from your tokens: a family of the accent's neighbors (a violet, a cool cyan and a deep rose, each quieter than the accent) over `--color-canvas`. Switch between light and dark and the field reads them again. Pass up to four CSS colors to set your own. Token references keep them mode-aware.

### Tuning

```tsx
'use client'

import { useState } from 'react'
import { MeshGradient } from '@youj/motion/backgrounds'

const INTENSITY = [0.4, 0.8, 1.2]
const GRAIN = [0, 0.5, 1]

export default function MeshGradientTuning() {
  const [intensity, setIntensity] = useState(0.8)
  const [grain, setGrain] = useState(0.5)

return (
    <div className="relative isolate flex min-h-[340px] w-full flex-col items-center justify-end gap-3 overflow-hidden p-5 rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <MeshGradient intensity={intensity} grain={grain} />
      {/* Content sits above the field: positioned, like the hero's headline. */}
      <p className="relative max-w-sm text-center text-sm text-fg">
        Below 1, the field leaves room for copy. Above it, the color is the point.
      </p>
      <div className="relative flex flex-wrap justify-center gap-2">
        <Choice label="intensity" values={INTENSITY} value={intensity} onChange={setIntensity} />
        <Choice label="grain" values={GRAIN} value={grain} onChange={setGrain} />
      </div>
    </div>
  )
}
```

Buttons for the intensity and grain of the field.

- `intensity`, from 0 to 1.5, sets how much of the field is color and how much is canvas. Keep it below 1 behind long copy.
- `speed` multiplies the drift. It stacks with the time scale, which slows everything together.
- `grain` adds film grain. Dithering against 8-bit banding is always on.
- `interactive` leans the field toward the pointer.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add mesh-gradient
```

It brings `youj-core`, `youj-gl` with it.

Use it for a hero, a launch page or a sign-up screen that should feel warm and premium without saying anything specific. It's color without line work, so it sits behind a headline more calmly than any other background. Don't use it behind long text or tables, and give it one section per page: a second gradient dilutes the first.

The gradient fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { MeshGradient } from '@youj/motion/backgrounds'

export function Hero() {
  return (
    <section className="relative isolate min-h-[640px]">
      <MeshGradient />
      <h1 className="relative">The workspace that moves as fast as you think</h1>
    </section>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `string[]` |  | Up to four CSS colors for the color masses. Default: an analogous family derived from the accent token. |
| `intensity` | `number` | `1` | How much of the field is colored vs. canvas. 0–1.5, default 1. |
| `speed` | `number` | `1` | Drift speed multiplier. |
| `grain` | `number` | `0.5` | Film grain amount, 0–1. Dithering against banding is always on. |
| `interactive` | `boolean` | `true` | The field leans toward the pointer. |
| `className` | `string` |  |  |

### Performance

It's one WebGL2 fragment shader on a single full-screen triangle, rendered at a device-pixel ratio capped at 2. The loop pauses offscreen and in hidden tabs, survives a lost GL context, and releases the context on unmount. Without WebGL2 it falls back to a static CSS gradient in the same colors.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drift |  | speed ÷ time scale | continuous shader clock |
| Pointer lean |  | smoothed per frame | eases in and out with the pointer |

**Reduced motion:** Draws one composed still frame and stops. There's no drift and no pointer response, and the frame redraws only when the size, the props or the theme change.

#### Reduced motion

The gradient draws one composed frame and holds it, with the film grain halved for the still image. The colors and the composition stay the same, so the section looks as designed, only still. It redraws when the size, the props or the theme change. Switch on Reduced motion in any preview above to compare.

### Accessibility

It's decorative, so it's `aria-hidden` and ignores pointer events. Check your text's contrast over the brightest part of the field. A lower `intensity` keeps it calm behind copy.

---

# Noise Field

> Add a topographic background with contour lines and accent-tinted peaks.

Source: https://www.youj.dev/docs/components/noise-field

## Examples

### Demo

```tsx
'use client'

import { ArrowRightIcon, GlobeIcon } from '@youj/icons'
import { NoiseField } from '@youj/motion/backgrounds'

export default function NoiseFieldDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col justify-center overflow-hidden px-8 py-12 sm:px-12 rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <NoiseField />
      {/* A quiet zone behind the copy: the survey fades out where the text sits. */}
      <div aria-hidden className="absolute inset-0 bg-linear-to-r from-canvas from-20% via-canvas/60 to-transparent to-80%" />
      <p className="relative mb-5 inline-flex w-fit items-center gap-1.5 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        <GlobeIcon size={14} />
        16 new edge regions
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        Route every request along the shortest path
      </p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Latency, load and failures, read like terrain and rebalanced before anyone notices.
      </p>
      <div className="relative mt-7 flex flex-wrap gap-2">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-lg bg-fg px-3.5 py-2 text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
        >
          Deploy now
          <ArrowRightIcon size={15} />
        </button>
        <button
          type="button"
          className="rounded-lg border border-line bg-surface/70 youj-allow-glass px-3.5 py-2 text-sm font-medium text-fg backdrop-blur-md focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          See the network
        </button>
      </div>
    </section>
  )
}
```

A hero section over the contour map, which fades out behind the copy.

With `interactive` on (the default), the pointer raises a smooth mound in the terrain, and the contours bunch up around it. The mound follows the pointer on a short smoothing curve and fades in and out as the pointer enters and leaves. The pointer is tracked on the window, so the field responds under content that takes the events. Touch doesn't raise a mound, because it produces no hover.

Set `interactive={false}` for fields behind panels and forms, where a moving surface under the cursor would distract.

### Color

```tsx
'use client'

import { NoiseField } from '@youj/motion/backgrounds'

const REGIONS = [
  { name: 'Frankfurt', latency: '18 ms' },
  { name: 'Virginia', latency: '24 ms' },
  { name: 'Singapore', latency: '31 ms' },
]

// Summits in the success color, lines in a muted ink: a calm map for a calm status.
const COLORS: [string, string] = ['var(--color-fg-muted)', 'var(--color-success)']

export default function NoiseFieldStatus() {
  return (
    <div className="w-full max-w-md overflow-hidden rounded-2xl border border-line bg-surface shadow-sm">
      <div className="relative isolate h-36 overflow-hidden border-b border-line">
        <NoiseField colors={COLORS} density={10} interactive={false} />
        <span className="absolute start-4 top-4 inline-flex items-center gap-2 rounded-full border border-line bg-surface/80 youj-allow-glass px-2.5 py-1 text-xs font-medium text-fg backdrop-blur-md">
          <span className="size-1.5 rounded-full bg-success" />
          Live
        </span>
      </div>
      <div className="p-5">
        <p className="text-sm font-medium text-fg">All systems operational</p>
        <p className="mt-0.5 text-xs text-fg-muted">99.99% uptime over the last 90 days</p>
        <ul className="mt-4 divide-y divide-line rounded-xl border border-line">
          {REGIONS.map((region) => (
            <li key={region.name} className="flex items-center justify-between px-3.5 py-2.5 text-sm">
              <span className="flex items-center gap-2 text-fg">
                <span className="size-1.5 rounded-full bg-success" />
                {region.name}
              </span>
              <span className="font-mono text-xs text-fg-muted">{region.latency}</span>
            </li>
          ))}
        </ul>
      </div>
    </div>
  )
}
```

A status panel whose map has green summits, a lower density and no pointer response.

`colors` takes two CSS colors: the contour lines, then the summits. The defaults are `--color-fg` lines with `--color-accent` summits. Token references keep the map in step with the theme, and it rereads them when the theme changes.

Here the summits take the success color, and a lower `intensity` and `density` keep the map calm behind a status panel. The field works inside any positioned box, not only full-bleed sections.

### Tuning

```tsx
'use client'

import { useState } from 'react'
import { NoiseField } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

const DENSITIES = ['8', '14', '24']
const INTENSITIES = ['0.6', '1', '1.4']

export default function NoiseFieldTuning() {
  const [density, setDensity] = useState('14')
  const [intensity, setIntensity] = useState('1')

Controls for the density and intensity of the contour lines.

- `density` is the number of contour intervals across the height range. It defaults to 14. Lower values draw a few broad landforms, and higher values draw a dense survey.
- `intensity`, from 0 to 1.5, sets the strength of the lines and the summit tint. Keep it at 1 or below behind copy.
- `speed` multiplies the flow. It stacks with the time scale, which slows everything together.

Changes apply on the next frame, without restarting the loop or recompiling the shader.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add noise-field
```

It brings `youj-core`, `youj-gl` with it.

Use it behind technical products: networks, infrastructure, maps and data. The precise hairlines there read as measurement, not decoration. It suits heroes and section backdrops with short copy. Don't put it behind long text or dense UI, because the lines compete with small type. Reach for [Mesh Gradient](https://www.youj.dev/docs/components/mesh-gradient) when you want color without line work.

The field fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { NoiseField } from '@youj/motion/backgrounds'

export function NetworkHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <NoiseField />
      <p className="relative text-5xl font-semibold">Route every request along the shortest path</p>
    </section>
  )
}
```

Terrain drifts slowly through a domain-warped noise, so ridges flow into new shapes instead of sliding across the screen. Every fifth contour is an index line, drawn heavier. The summits pick up the accent, and a vignette keeps the edges quiet so the field frames the content instead of competing with it.

Keep a quiet zone behind the copy. In the preview, a gradient from `canvas` to transparent sits between the field and the text.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[lines: string, summit: string]` |  | [lines, summit] CSS colors. Default: `--color-fg` lines, `--color-accent` summits. |
| `intensity` | `number` | `1` | Line and tint strength, 0–1.5. |
| `speed` | `number` | `1` | Flow speed multiplier. |
| `density` | `number` | `14` | Number of contour intervals across the height range. |
| `interactive` | `boolean` | `true` | The pointer raises a mound that bunches the contours around it. |
| `className` | `string` |  |  |

### Performance

It's one WebGL2 fragment shader on a single full-screen triangle, rendered at a device-pixel ratio capped at 2. Contour lines are anti-aliased from screen-space derivatives, so they stay one device pixel wide at any size. The loop pauses when the field is offscreen or the tab is hidden, recovers from a lost GL context, and releases the context on unmount. Without WebGL2, it falls back to a static CSS wash of the summit color over the canvas.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Flow |  | speed ÷ time scale | continuous shader clock |
| Pointer mound |  | smoothed per frame | follows the pointer, fades in and out |

**Reduced motion:** Draws one still map and stops. There's no flow and no pointer mound, and the map redraws only when the size, the props or the theme change.

#### Reduced motion

The field draws one composed map and holds it. Nothing flows and the pointer raises no mound, but the survey, its colors and its framing stay the same, so the page looks as intended without motion. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events, so it never takes focus or clicks from the content above it.
- Check your text's contrast over the densest part of the survey. A quiet zone behind the copy, or a lower `intensity`, keeps small type readable.
- The flow is slow, and it stops when the field is offscreen. Under reduced motion the field doesn't move at all.

---

# Aurora

> Add curtains of light behind a hero, with space below for your copy.

Source: https://www.youj.dev/docs/components/aurora

## Examples

### Demo

```tsx
'use client'

import { SparklesIcon } from '@youj/icons'
import { Aurora } from '@youj/motion/backgrounds'

export default function AuroraDemo() {
  return (
    // The curtains hang above the horizon, so the copy sits in the quiet lower part of the frame.
    <section className="relative isolate flex min-h-[420px] w-full flex-col items-center justify-end overflow-hidden px-6 pt-40 pb-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <Aurora />
      <p className="relative mb-4 inline-flex items-center gap-1.5 rounded-full border border-line bg-surface/60 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        <SparklesIcon size={14} />
        Youj Intelligence, in beta
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        Answers that arrive before the question
      </p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        An assistant that reads your whole workspace and surfaces what matters, at the moment you need it.
      </p>
      <button
        type="button"
        className="relative mt-7 rounded-full bg-fg px-4 py-2 text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
      >
        Join the beta
      </button>
    </section>
  )
}
```

A hero section with the aurora curtains behind its headline, the copy in the quiet lower part of the frame.

With `interactive` on (the default), the ribbons lean gently toward the pointer's horizontal position. The lean eases in when the pointer enters the frame and out when it leaves. The pointer is tracked on the window, so the aurora responds under the content above it. Touch doesn't lean the ribbons, because it produces no hover.

### Horizon and color

```tsx
'use client'

import { useState } from 'react'
import { Aurora } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

const HORIZONS: Record<string, number> = { Low: 0.35, Default: 0.58, High: 0.8 }

// Back layer to front. Token references follow the theme.
const PALETTES: Record<string, [string, string, string] | undefined> = {
  'Accent family': undefined,
  Status: ['var(--color-success)', 'var(--color-accent)', 'var(--color-warning)'],
}

export default function AuroraTuning() {
  const [horizon, setHorizon] = useState('Default')
  const [palette, setPalette] = useState('Accent family')

return (
    <div className="mx-auto flex w-full max-w-[calc(100%-2rem)] flex-col overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <div className="relative isolate h-[260px] overflow-hidden">
        <Aurora horizon={HORIZONS[horizon]} colors={PALETTES[palette]} />
      </div>
      <div className="flex flex-wrap items-center justify-center gap-x-4 gap-y-2 border-t border-line bg-canvas px-4 py-3">
        <Setting label="Horizon" options={Object.keys(HORIZONS)} value={horizon} onChange={setHorizon} />
        <Setting label="Colors" options={Object.keys(PALETTES)} value={palette} onChange={setPalette} />
      </div>
    </div>
  )
}
```

Controls for the horizon height and the color family, so you can see both change in place.

`horizon` sets the height of the lowest curtain edge, from `0` (the bottom of the frame) to `1` (the top). The default, `0.58`, leaves the lower part of the frame for content. Lower it for a taller glow behind short copy. Raise it to keep the curtains above a form or a card.

`colors` takes three CSS colors, from the back layer to the front. By default they're a family around `--color-accent`: a cooler teal-leaning layer at the back, the accent in the middle and a violet at the front. Token references stay in step with the theme.

`intensity`, from 0 to 1.5, sets the brightness of the ribbons, and `speed` multiplies the drift. The speed stacks with the time scale, which slows everything together.

### Behind a form

```tsx
'use client'

import { useId } from 'react'
import { Aurora } from '@youj/motion/backgrounds'

export default function AuroraSignIn() {
  const email = useId()
  return (
    <div className="relative isolate flex min-h-[440px] w-full items-center justify-center overflow-hidden px-6 py-10 rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      {/* Behind a form, a calmer field that doesn't follow the pointer. */}
      <Aurora intensity={0.8} horizon={0.72} interactive={false} />
      <form
        onSubmit={(event) => event.preventDefault()}
        className="relative w-full max-w-xs rounded-2xl border border-line bg-surface/85 youj-allow-glass p-6 shadow-lg backdrop-blur-xl"
      >
        <p className="text-base font-semibold tracking-tight text-fg">Sign in to Youj</p>
        <p className="mt-1 text-sm text-fg-muted">Use the email you work with.</p>
        <label htmlFor={email} className="mt-5 block text-xs font-medium text-fg">
          Email
        </label>
        <input
          id={email}
          type="email"
          autoComplete="email"
          placeholder="ana@studio.dev"
          className="mt-1.5 h-9 w-full rounded-lg border border-line bg-canvas px-3 text-sm text-fg placeholder:text-fg-muted focus-visible:border-accent focus-visible:ring-2 focus-visible:ring-accent-line focus-visible:outline-none"
        />
        <button
          type="submit"
          className="mt-3 h-9 w-full rounded-lg bg-fg text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none"
        >
          Continue with email
        </button>
        <p className="mt-4 text-center text-xs text-fg-muted">We’ll send you a magic link.</p>
      </form>
    </div>
  )
}
```

A sign-in card over a calmer aurora with a raised horizon, lower intensity and no pointer response.

For sign-in and onboarding screens, raise the horizon so the curtains hang behind the top of the card, lower the intensity, and turn off `interactive`. A surface that moves with the pointer is a distraction while someone types.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add aurora
```

It brings `youj-core`, `youj-gl` with it.

Use it for a launch or a hero that should feel atmospheric: a new product, a beta, a sign-in screen. The curtains hang in the upper part of the frame and fade out below the horizon, so the lower part stays calm for a headline and a call to action. Don't use it behind dense content or in more than one section per page. Its glow is a statement, and two of them compete.

The aurora fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`. Place the copy below the horizon.

```tsx
import { Aurora } from '@youj/motion/backgrounds'

export function LaunchHero() {
  return (
    <section className="relative isolate flex min-h-[640px] flex-col justify-end pb-24">
      <Aurora />
      <p className="relative text-5xl font-semibold">Answers that arrive before the question</p>
    </section>
  )
}
```

Three layers drift at different depths. Each has a bright lower edge that swells and folds, rays that hang upward and fade over the curtain's height, and pulses of brightness that travel along it. On a dark canvas the layers add light. On a light canvas they tint it, so the same component works in both modes.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[string, string, string]` |  | Three CSS colors, back layer to front. Default: an analogous family around the accent token. |
| `intensity` | `number` | `1` | Brightness of the ribbons, 0–1.5. |
| `speed` | `number` | `1` | Drift speed multiplier. |
| `horizon` | `number` | `0.58` | Height of the lowest curtain edge, 0 (bottom) to 1 (top). |
| `interactive` | `boolean` | `true` | Ribbons lean gently with the pointer. |
| `className` | `string` |  |  |

### Performance

It's one WebGL2 fragment shader on a single full-screen triangle, rendered at a device-pixel ratio capped at 2, with dithering against 8-bit banding in the soft gradients. The loop pauses when the aurora is offscreen or the tab is hidden, recovers from a lost GL context, and releases the context on unmount. Without WebGL2, it falls back to a static CSS wash of the same colors.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drift |  | speed ÷ time scale | layers, folds and pulses, on one shader clock |
| Pointer lean |  | smoothed per frame | eases in and out with the pointer |

**Reduced motion:** Draws one still frame of the curtains and stops. There's no drift and no lean, and the frame redraws only when the size, the props or the theme change.

#### Reduced motion

The aurora draws one composed frame and holds it. The curtains, their colors and the quiet space for your copy stay the same, so the hero looks as designed, only still. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Keep text below the horizon, where the frame is quiet, and check its contrast there. On a light canvas the curtains tint, so muted text over the brightest band can drop below 4.5:1.
- The drift is slow, and it stops offscreen. Under reduced motion the aurora doesn't move at all.

---

# Particle Constellation

> Show drifting, connected particles that gather around the pointer.

Source: https://www.youj.dev/docs/components/particle-constellation

## Examples

### Demo

```tsx
'use client'

import { GitBranchIcon } from '@youj/icons'
import { ParticleConstellation } from '@youj/motion/backgrounds'

export default function ParticleConstellationDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <ParticleConstellation density={1.8} />
      {/* A soft pool of canvas under the copy, so the links never cross the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-25% via-canvas/70 via-45% to-transparent to-75%" />
      <p className="relative mb-4 inline-flex items-center gap-1.5 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        <GitBranchIcon size={14} />
        Service graph, now live
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        See every dependency before it breaks
      </p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Move the pointer across the field: nearby links light up and the nodes gather around it.
      </p>
    </section>
  )
}
```

A hero section over the particle graph; move the pointer across it and nearby links light up.

`colors` takes three CSS colors: the particles, the links, then the highlight for links and particles near the pointer. The defaults are `--color-fg-muted`, `--color-fg-subtle` and `--color-accent`. Token references follow the theme, and the constellation rereads them when the theme changes.

### Pointer

```tsx
'use client'

import { useState } from 'react'
import { ParticleConstellation } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

type Mode = 'attract' | 'repel'

export default function ParticleConstellationPointer() {
  const [mode, setMode] = useState<Mode>('attract')

A switch between particles that gather around the pointer and particles that part around it.

The pointer is a node of its own. It links to every particle in reach and lights the links around it in the highlight color. With `pointer="attract"` (the default), particles gather into a loose ring around it instead of collapsing onto the cursor. With `"repel"`, they part around it. When the pointer leaves, the particles ease back to their own drift.

The pointer is tracked on the window, so the field responds under the content above it. Touch doesn't gather particles, because it produces no hover. Set `interactive={false}` where the field sits behind something people work in.

### Signals

```tsx
'use client'

import { ParticleConstellation } from '@youj/motion/backgrounds'

export default function ParticleConstellationSignals() {
  return (
    <div className="relative isolate mx-auto h-[280px] w-full max-w-[calc(100%-2rem)] overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <ParticleConstellation signals density={1.6} linkDistance={110} interactive={false} />
    </div>
  )
}
```

Pulses of light firing along the links, like neurons.

Set `signals` and a node fires: a small bright pulse with a short tail runs down a link to the next node, which brightens and sometimes fires on, so the signal cascades. Each chain takes one color of a soft rainbow (mint, sky, violet and orange), brighter on a dark canvas. Pass `{ colors, rate }` to choose the CSS colors and how many chains start per second. The number of pulses in flight is capped, lower on the low motion tier, and none run under reduced motion.

### Quiet use

```tsx
'use client'

import { PlusIcon, ServerIcon } from '@youj/icons'
import { ParticleConstellation } from '@youj/motion/backgrounds'

export default function ParticleConstellationEmptyState() {
  return (
    <div className="relative isolate w-full max-w-lg overflow-hidden rounded-2xl border border-dashed border-line-strong bg-canvas">
      {/* Sparse and still under the pointer: a hint of the graph to come, not a show. */}
      <ParticleConstellation density={0.45} intensity={0.7} linkDistance={150} interactive={false} />
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-30% to-transparent to-75%" />
      <div className="relative flex flex-col items-center px-6 py-14 text-center">
        <span className="grid size-10 place-items-center rounded-xl border border-line bg-surface text-fg shadow-sm">
          <ServerIcon size={18} />
        </span>
        <p className="mt-4 text-sm font-medium text-fg">No services connected yet</p>
        <p className="mt-1 max-w-xs text-sm text-fg-muted">Connect a repository and Youj maps how your services talk to each other.</p>
        <button
          type="button"
          className="mt-5 inline-flex items-center gap-1.5 rounded-lg bg-fg px-3.5 py-2 text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
        >
          <PlusIcon size={15} />
          Connect a service
        </button>
      </div>
    </div>
  )
}
```

A sparse, still constellation behind an empty state, with no pointer response.

At a low `density` and `intensity`, and without pointer response, the constellation becomes a hint of structure behind an empty state: the graph to come, not a show.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add particle-constellation
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is connection: service graphs, networks, integrations, collaboration. It reads as a living diagram, and it's the one background that answers the pointer directly. Don't use it behind reading-length text, since the hairlines cross everything, and keep it to one per page.

The constellation fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { ParticleConstellation } from '@youj/motion/backgrounds'

export function GraphHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <ParticleConstellation />
      <p className="relative text-5xl font-semibold">See every dependency before it breaks</p>
    </section>
  )
}
```

Each particle drifts at its own slow velocity and wraps around the edges. Two particles closer than `linkDistance` are joined by a hairline that fades with distance. The number of particles follows the area: at `density={1}`, one particle per 9,000 square pixels, capped at 900. A phone and a wide display look equally full.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[particles: string, links: string, highlight: string]` |  | [particles, links, highlight] CSS colors. Default: `--color-fg-muted`, `--color-fg-subtle`, `--color-accent`. |
| `intensity` | `number` | `1` | Opacity of particles and links, 0–1.5. |
| `speed` | `number` | `1` | Drift speed multiplier. |
| `density` | `number` | `1` | Particles per area, relative. 1 ≈ one particle per 9 000 CSS px². |
| `linkDistance` | `number` | `130` | Max link length in CSS px. |
| `pointer` | `'attract' \| 'repel'` | `'attract'` | How particles respond to the pointer. |
| `interactive` | `boolean` | `true` | Pointer reactivity. |
| `signals` | `boolean \| SignalOptions` | `false` | Pulses of light that travel along the links from particle to particle, sometimes triggering the next one, like neurons firing. `true` uses the default rainbow (mint, sky, violet, orange; brighter on a dark canvas). Off by default; none under reduced motion. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. A spatial grid sized to the link distance means each particle only checks its neighboring cells, and links are batched into a handful of strokes per frame by opacity. The canvas renders at a device-pixel ratio capped at 2. The loop pauses when the constellation is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the highlight color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drift |  | speed ÷ time scale | per-particle velocity, wrapping at the edges |
| Pointer pull |  | per-frame physics | attract or repel within reach, then relax |
| Pointer strength |  | smoothed per frame | eases in and out with the pointer |

**Reduced motion:** Draws one fixed, seeded constellation: the same composition every time. There's no drift and no pointer response, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The constellation shows a fixed composition from a seeded layout, so it's the same on every visit and in every screenshot. The particles and links keep their colors and density. Only the drift and the pointer response are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Hairlines cross whatever sits above them. Keep a quiet pool of canvas behind the copy, as the hero preview does, or lower `intensity`, and check your text's contrast there.
- The drift is slow and stops offscreen. Under reduced motion the field doesn't move at all.

---

# Flow Field

> Add streaks drifting on a smooth current that the pointer stirs into a vortex.

Source: https://www.youj.dev/docs/components/flow-field

## Examples

### Demo

```tsx
'use client'

import { RouteIcon } from '@youj/icons'
import { FlowField } from '@youj/motion/backgrounds'

export default function FlowFieldDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <FlowField density={1.2} />
      {/* A soft pool of canvas under the copy, so the streaks never cross the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-25% via-canvas/70 via-45% to-transparent to-75%" />
      <p className="relative mb-4 inline-flex items-center gap-1.5 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        <RouteIcon size={14} />
        Live traffic
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        Watch requests find their way
      </p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Move the pointer across the field: the current swirls around it and the streaks it catches light up.
      </p>
    </section>
  )
}
```

A hero section over the current; move the pointer across it and the streaks swirl around it and light up.

`colors` takes two CSS colors: the streaks, then the highlight for streaks the pointer has caught. The defaults are `--color-fg-muted` and `--color-accent`. Token references follow the theme, and the field rereads them when the theme changes.

### Tuning

```tsx
'use client'

import { useState } from 'react'
import { FlowField } from '@youj/motion/backgrounds'
import { Label, Switch, ToggleGroup, ToggleGroupItem } from '@youj/react'

const SCALES = [
  { value: '0.6', label: 'Busy' },
  { value: '1', label: 'Default' },
  { value: '1.8', label: 'Broad' },
]
const TRAILS = [
  { value: '0.5', label: 'Short' },
  { value: '1', label: 'Default' },
  { value: '1.5', label: 'Long' },
]

export default function FlowFieldTuning() {
  const [scale, setScale] = useState('1')
  const [trail, setTrail] = useState('1')
  const [interactive, setInteractive] = useState(true)

return (
    <div className="mx-auto flex w-full max-w-[calc(100%-2rem)] flex-col overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <div className="relative isolate h-[260px] overflow-hidden">
        <FlowField scale={Number(scale)} trail={Number(trail)} interactive={interactive} />
      </div>
      <div className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 border-t border-line bg-canvas px-4 py-3">
        <div className="flex items-center gap-2">
          <span className="text-xs text-fg-muted">Swirls</span>
          <ToggleGroup variant="segmented" size="sm" aria-label="Swirl size" value={[scale]} onValueChange={(next) => next[0] && setScale(next[0])}>
            {SCALES.map((option) => (
              <ToggleGroupItem key={option.value} value={option.value} className="px-2.5 text-xs">
                {option.label}
              </ToggleGroupItem>
            ))}
          </ToggleGroup>
        </div>
        <div className="flex items-center gap-2">
          <span className="text-xs text-fg-muted">Trails</span>
          <ToggleGroup variant="segmented" size="sm" aria-label="Trail length" value={[trail]} onValueChange={(next) => next[0] && setTrail(next[0])}>
            {TRAILS.map((option) => (
              <ToggleGroupItem key={option.value} value={option.value} className="px-2.5 text-xs">
                {option.label}
              </ToggleGroupItem>
            ))}
          </ToggleGroup>
        </div>
        <Label className="text-xs font-normal text-fg-muted">
          <Switch size="sm" checked={interactive} onCheckedChange={setInteractive} />
          Pointer
        </Label>
      </div>
    </div>
  )
}
```

Controls for the size of the swirls, the length of the trails and the pointer.

- `scale` sets the size of the swirls in the current. Above 1 the streaks run in broad, calm sweeps; below 1 the current is busier. It defaults to 1.
- `trail`, from 0.3 to 1.5, multiplies the trail length. It defaults to 1.
- `density` sets how many streaks there are per area, `intensity` (0 to 1.5) how strongly they show, and `speed` how fast the current runs.

The pointer is a vortex: the current curls around it and the streaks it catches turn to the highlight. The pointer is tracked on the window, so the field responds under the content above it. Set `interactive={false}` where the field sits behind something people work in.

### Quiet use

```tsx
'use client'

import { ActivityIcon } from '@youj/icons'
import { FlowField } from '@youj/motion/backgrounds'

export default function FlowFieldQuiet() {
  return (
    <div className="relative isolate w-full max-w-lg overflow-hidden rounded-2xl border border-line bg-canvas">
      {/* Sparse, slow and deaf to the pointer: a sense of flow behind a status card, nothing more. */}
      <FlowField density={0.5} intensity={0.6} speed={0.6} scale={1.6} interactive={false} />
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-30% to-transparent to-75%" />
      <div className="relative flex flex-col items-center px-6 py-14 text-center">
        <span className="grid size-10 place-items-center rounded-xl border border-line bg-surface text-fg shadow-sm">
          <ActivityIcon size={18} />
        </span>
        <p className="mt-4 text-sm font-medium text-fg">All regions are flowing</p>
        <p className="mt-1 max-w-xs text-sm text-fg-muted">Requests are being served from the nearest edge, with no failures in the last hour.</p>
      </div>
    </div>
  )
}
```

A sparse, slow current behind a status card, with no pointer response.

At a low `density`, `intensity` and `speed`, and a broad `scale`, the current reads as flow rather than as an effect, a quiet signal that things are moving.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add flow-field
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is movement: traffic, data in flight, networks, anything that should feel alive and directed. It reads as weather over the page, and it answers the pointer without asking anything of it. Don't use it behind reading-length text, since the streaks cross everything, and keep it to one animated background per page.

The field fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { FlowField } from '@youj/motion/backgrounds'

export function CurrentHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <FlowField />
      <p className="relative text-5xl font-semibold">Watch requests find their way</p>
    </section>
  )
}
```

Each streak rides a smooth noise current, so neighbors flow the same way and the direction changes slowly across the canvas and over time. A streak lives for a few seconds: it fades in, drifts, fades out and starts again somewhere else. The number of streaks follows the area: at `density={1}`, one per 3,200 square pixels, capped at 800. A phone and a wide display look equally full.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[streaks: string, highlight: string]` |  | [streaks, highlight] CSS colors. Default: `--color-fg-muted`, `--color-accent`. |
| `intensity` | `number` | `1` | Opacity of the streaks, 0–1.5. |
| `speed` | `number` | `1` | Current speed multiplier. |
| `density` | `number` | `1` | Streaks per area, relative. 1 ≈ one streak per 3 200 CSS px². |
| `trail` | `number` | `1` | Trail length multiplier, 0.3–1.5. |
| `scale` | `number` | `1` | Size of the swirls in the current: above 1 is broader and calmer, below 1 is busier. |
| `interactive` | `boolean` | `true` | Pointer reactivity: the pointer stirs a vortex in the current. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. Each frame redraws every trail from a short history, in a handful of strokes batched by opacity, so nothing is left behind on the canvas and a resize or a theme change is exact. The canvas renders at a device-pixel ratio capped at 2, and the low motion budget keeps 60% of the streaks. The loop pauses when the field is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the highlight color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Current |  | speed ÷ time scale | a smooth noise field that shifts slowly over time |
| Vortex |  | per-frame physics | the current curls around the pointer within reach |
| Pointer strength |  | smoothed per frame | eases in and out with the pointer |
| Streak life |  | 4 to 10 seconds | fades in, drifts, fades out and respawns |

**Reduced motion:** Draws one fixed, seeded field with its trails laid down: the same composition every time. There's no drift and no pointer response, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The field shows a fixed composition from a seeded layout, so it's the same on every visit and in every screenshot. The streaks and trails keep their colors and density. Only the drift and the pointer response are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Streaks cross whatever sits above them. Keep a quiet pool of canvas behind the copy, as the hero preview does, or lower `intensity`, and check your text's contrast there.
- The drift is slow and stops offscreen. Under reduced motion the field doesn't move at all.

---

# Swarm

> Add a flock that roams the page, then gathers and circles the pointer.

Source: https://www.youj.dev/docs/components/swarm

## Examples

### Demo

```tsx
'use client'

import { UsersIcon } from '@youj/icons'
import { Swarm } from '@youj/motion/backgrounds'

export default function SwarmDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <Swarm density={1.3} />
      {/* A soft pool of canvas under the copy, so the flock never crosses the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-25% via-canvas/70 via-45% to-transparent to-75%" />
      <p className="relative mb-4 inline-flex items-center gap-1.5 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        <UsersIcon size={14} />
        Teams, in sync
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">
        Everyone moving the same way
      </p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Move the pointer across the field: the flock gathers around it and circles until you move on.
      </p>
    </section>
  )
}
```

A hero section over the flock; move the pointer across it and the boids gather around it and circle.

`colors` takes two CSS colors: the boids, then the highlight for the ones circling the pointer. The defaults are `--color-fg-muted` and `--color-accent`. Token references follow the theme, and the flock rereads them when the theme changes.

### Tuning

```tsx
'use client'

import { useState } from 'react'
import { Swarm } from '@youj/motion/backgrounds'
import { Label, Switch, ToggleGroup, ToggleGroupItem } from '@youj/react'

const DENSITIES = [
  { value: '0.5', label: 'Few' },
  { value: '1', label: 'Default' },
  { value: '2', label: 'Many' },
]
const SIZES = [
  { value: '0.7', label: 'Small' },
  { value: '1', label: 'Default' },
  { value: '1.6', label: 'Large' },
]

export default function SwarmTuning() {
  const [density, setDensity] = useState('1')
  const [size, setSize] = useState('1')
  const [interactive, setInteractive] = useState(true)

return (
    <div className="mx-auto flex w-full max-w-[calc(100%-2rem)] flex-col overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <div className="relative isolate h-[260px] overflow-hidden">
        <Swarm density={Number(density)} size={Number(size)} interactive={interactive} />
      </div>
      <div className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2 border-t border-line bg-canvas px-4 py-3">
        <div className="flex items-center gap-2">
          <span className="text-xs text-fg-muted">Flock</span>
          <ToggleGroup
            variant="segmented"
            size="sm"
            aria-label="Flock size"
            value={[density]}
            onValueChange={(next) => next[0] && setDensity(next[0])}
          >
            {DENSITIES.map((option) => (
              <ToggleGroupItem key={option.value} value={option.value} className="px-2.5 text-xs">
                {option.label}
              </ToggleGroupItem>
            ))}
          </ToggleGroup>
        </div>
        <div className="flex items-center gap-2">
          <span className="text-xs text-fg-muted">Boids</span>
          <ToggleGroup variant="segmented" size="sm" aria-label="Boid size" value={[size]} onValueChange={(next) => next[0] && setSize(next[0])}>
            {SIZES.map((option) => (
              <ToggleGroupItem key={option.value} value={option.value} className="px-2.5 text-xs">
                {option.label}
              </ToggleGroupItem>
            ))}
          </ToggleGroup>
        </div>
        <Label className="text-xs font-normal text-fg-muted">
          <Switch size="sm" checked={interactive} onCheckedChange={setInteractive} />
          Pointer
        </Label>
      </div>
    </div>
  )
}
```

Controls for the size of the flock, the size of each boid and the pointer.

- `density` sets how many boids there are per area. It defaults to 1, which is one per 3,800 square pixels, capped at 480.
- `size`, from 0.5 to 2.5, scales each boid. It defaults to 1.
- `intensity` (0 to 1.5) sets how strongly the flock shows, and `speed` how fast it flies.

The pointer calls the flock. Boids within reach turn toward it, settle on a circle around it and keep turning, and the ones in the circle take the highlight color. When the pointer leaves, the flock goes back to roaming. Set `interactive={false}` where the flock sits behind something people work in.

### Quiet use

```tsx
'use client'

import { UsersIcon } from '@youj/icons'
import { Swarm } from '@youj/motion/backgrounds'

export default function SwarmQuiet() {
  return (
    <div className="relative isolate w-full max-w-lg overflow-hidden rounded-2xl border border-dashed border-line-strong bg-canvas">
      {/* A small, slow flock that ignores the pointer: company for an empty room. */}
      <Swarm density={0.5} intensity={0.7} speed={0.7} interactive={false} />
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-30% to-transparent to-75%" />
      <div className="relative flex flex-col items-center px-6 py-14 text-center">
        <span className="grid size-10 place-items-center rounded-xl border border-line bg-surface text-fg shadow-sm">
          <UsersIcon size={18} />
        </span>
        <p className="mt-4 text-sm font-medium text-fg">No one else is here yet</p>
        <p className="mt-1 max-w-xs text-sm text-fg-muted">Invite your team and they will show up here as they join.</p>
      </div>
    </div>
  )
}
```

A small, slow flock behind an empty state, with no pointer response.

At a low `density`, `intensity` and `speed`, and without pointer response, the flock is company for an empty room rather than a show.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add swarm
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is a group moving as one: teams, communities, collaboration, anything with many small parts and one direction. It's playful without being busy, and the pointer gives it a hook that people reach for. Don't use it behind reading-length text, and keep it to one animated background per page.

The flock fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { Swarm } from '@youj/motion/backgrounds'

export function TeamHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <Swarm />
      <p className="relative text-5xl font-semibold">Everyone moving the same way</p>
    </section>
  )
}
```

Each boid steers by three rules: back away from a neighbor that is too close, match the heading of the neighbors in sight, and drift toward their center. A slow personal wander keeps the flock roaming instead of settling, and the edges turn boids back before they leave. The number of boids follows the area, so a phone and a wide display look equally full.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[boids: string, highlight: string]` |  | [boids, highlight] CSS colors. Default: `--color-fg-muted`, `--color-accent`. |
| `intensity` | `number` | `1` | Opacity of the flock, 0–1.5. |
| `speed` | `number` | `1` | Flight speed multiplier. |
| `density` | `number` | `1` | Boids per area, relative. 1 ≈ one boid per 3 800 CSS px². |
| `size` | `number` | `1` | Size of each boid, 0.5–2.5. |
| `interactive` | `boolean` | `true` | Pointer reactivity: the flock gathers and circles the pointer. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. Boids only look at their neighbors, which come from a spatial grid sized to their sight, so the cost grows with the size of the flock and not with its square. The boids are darts batched into a few fills by opacity. The canvas renders at a device-pixel ratio capped at 2, and the low motion budget keeps 60% of the flock. The loop pauses when the flock is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the highlight color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Flocking |  | speed ÷ time scale | separation, alignment and cohesion with neighbors in sight |
| Wander |  | per-boid phase | a slow sideways drift that is different for every boid |
| Pointer orbit |  | per-frame physics | boids in reach turn toward the pointer and circle it |
| Pointer strength |  | smoothed per frame | eases in and out with the pointer |

**Reduced motion:** Draws one fixed, seeded flock: the same composition every time. There's no flight and no pointer response, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The flock shows a fixed composition from a seeded layout that has already settled into streams, so it's the same on every visit and in every screenshot. Only the flight and the pointer response are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Boids pass over whatever sits above them. Keep a quiet pool of canvas behind the copy, as the hero preview does, or lower `intensity`, and check your text's contrast there.
- The flight is slow and stops offscreen. Under reduced motion the flock doesn't move at all.

---

# Dot Matrix Wave

> Add a dot-grid background that ripples on hover and click.

Source: https://www.youj.dev/docs/components/dot-matrix-wave

## Examples

### Demo

```tsx
'use client'

import { DotMatrixWave } from '@youj/motion/backgrounds'

export default function DotMatrixWaveDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <DotMatrixWave />
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-20% via-canvas/60 via-40% to-transparent to-70%" />
      <p className="relative mb-4 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        Youj 2.0 is here
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">Built to the last pixel</p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        An interface toolkit for teams who notice the details. Click anywhere in the field to send a ripple.
      </p>
    </section>
  )
}
```

A hero section over the dot matrix, which swells in the background; click anywhere in the field to send a ripple.

When nobody is interacting, the matrix sends a gentle pulse from a point in the middle of the field every few seconds of its clock. The points follow a fixed sequence, not a random one. Turn the pulses off with `ambient={false}` when the page already has something moving.

### Pointer and clicks

```tsx
'use client'

import { useState } from 'react'
import { SendIcon, WebhookIcon } from '@youj/icons'
import { DotMatrixWave } from '@youj/motion/backgrounds'

export default function DotMatrixWaveListening() {
  const [sent, setSent] = useState(0)

return (
    <div className="relative isolate w-full max-w-lg overflow-hidden rounded-2xl border border-line bg-canvas">
      {/* Ambient pulses say "listening". A press anywhere in the field, the button included, sends a ring from that point. */}
      <DotMatrixWave spacing={18} />
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-20% to-transparent to-65%" />
      <div className="relative flex flex-col items-center px-6 py-14 text-center">
        <span className="grid size-10 place-items-center rounded-xl border border-line bg-surface text-fg shadow-sm">
          <WebhookIcon size={18} />
        </span>
        <p className="mt-4 text-sm font-medium text-fg">Listening for events</p>
        <p className="mt-1 max-w-xs text-sm text-fg-muted">
          Point your provider at <span className="font-mono text-xs text-fg">hooks.youj.io/7f3a</span>, or send a test event.
        </p>
        <button
          type="button"
          onClick={() => setSent((n) => n + 1)}
          className="mt-5 inline-flex items-center gap-1.5 rounded-lg bg-fg px-3.5 py-2 text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
        >
          <SendIcon size={15} />
          Send test event
        </button>
        <p role="status" className="mt-3 h-4 text-xs text-fg-muted">
          {sent > 0 && `${sent} test ${sent === 1 ? 'event' : 'events'} sent`}
        </p>
      </div>
    </div>
  )
}
```

An empty state for a webhook endpoint, where the matrix reacts to the pointer and to the Send test event button.

With `interactive` on (the default), the dots under the pointer rise into a tight lens, and moving the pointer leaves a wake of soft rings, one for every 120 pixels traveled. A press anywhere in the field sends a strong ring from that point, including a press on a button that sits above the matrix.

Here the matrix is an empty state for a webhook endpoint. The ambient pulses say it's listening, and pressing **Send test event** sends a ring out from the button. The pointer is tracked on the window, so the matrix responds under the content above it.

### Tuning

```tsx
'use client'

import { useState } from 'react'
import { DotMatrixWave } from '@youj/motion/backgrounds'
import { Label, Switch, ToggleGroup, ToggleGroupItem } from '@youj/react'

const SPACINGS = ['14', '22', '32']

export default function DotMatrixWaveTuning() {
  const [spacing, setSpacing] = useState('22')
  const [ambient, setAmbient] = useState(true)

Controls for the dot spacing and for the ambient pulses.

- `spacing` is the grid pitch in CSS pixels. It defaults to 22. Smaller values read as a fine texture, and larger values as a bold graphic.
- `intensity`, from 0 to 1.5, sets the dots' contrast against the canvas.
- `speed` multiplies the clock that drives the swell and the rings' travel. It stacks with the time scale.

`colors` takes two CSS colors: the dots at rest, then the excited color they heat toward. The defaults are `--color-fg` and `--color-accent`. Token references follow the theme.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add dot-matrix-wave
```

It brings `youj-core`, `youj-gl` with it.

Use it for products that sell precision: design tools, developer platforms, anything about pixels and grids. It's also a good "listening" state, because its idle pulses read as something waiting for input. Don't use it behind long text or dense UI, and don't pair it with another animated background on the same page.

The matrix fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { DotMatrixWave } from '@youj/motion/backgrounds'

export function PrecisionHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <DotMatrixWave />
      <p className="relative text-5xl font-semibold">Built to the last pixel</p>
    </section>
  )
}
```

Every dot is a single anti-aliased disc on a grid snapped to device pixels, evaluated at its center, so the lattice stays crisp at any pixel ratio. Untouched, the matrix breathes with a slow, low swell. Dots grow and brighten toward the excited color as a wave passes through them.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[dots: string, excited: string]` |  | [dots, excited] CSS colors. Default: `--color-fg` dots that heat to `--color-accent`. |
| `intensity` | `number` | `1` | Dot contrast, 0–1.5. |
| `speed` | `number` | `1` | Clock multiplier for the idle swell and ripple travel. |
| `spacing` | `number` | `22` | Grid pitch in CSS px. |
| `interactive` | `boolean` | `true` | Pointer raises a lens of dots and leaves a wake; clicks send a ripple. |
| `ambient` | `boolean` | `true` | A pulse every few seconds while nobody is interacting, each from the next point of a fixed, evenly spread sequence across the middle of the field. |
| `className` | `string` |  |  |

### Performance

It's one WebGL2 fragment shader on a single full-screen triangle, rendered at a device-pixel ratio capped at 2. It tracks at most eight rings at a time, and the oldest gives way to a new one. The loop pauses when the matrix is offscreen or the tab is hidden, recovers from a lost GL context, and releases the context on unmount. Without WebGL2, it falls back to a static CSS dot pattern at the same spacing.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Swell |  | speed ÷ time scale | idle breathing of the whole lattice |
| Rings |  | 380 px per clock second | clicks, the pointer wake and ambient pulses |
| Pointer lens |  | smoothed per frame | follows the pointer, fades in and out |

**Reduced motion:** Draws one still frame with a single ring frozen mid-flight, so the matrix still reads as something that responds. There's no lens, no wake and no ambient pulse.

Ring travel is measured in the matrix's own clock, so it slows with the Speed control like everything else.

#### Reduced motion

The matrix holds one composed frame, with a single ring frozen in the middle of the field. There's no swell, no lens and no pulse, but the lattice and its colors stay the same, and the frozen ring still hints at what the matrix does. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events, so presses pass through to the content above it.
- A ring is visual feedback only. If a press does something, like sending a test event, confirm it in text as well. The Pointer and clicks story does this with a status message.
- Keep a quiet pool of canvas behind the copy, and check your text's contrast over the brightest rings.

---

# Magnetic Field

> Show a dot grid that bends away from the pointer and springs back.

Source: https://www.youj.dev/docs/components/magnetic-field

## Examples

### Demo

```tsx
'use client'

import { MagneticField } from '@youj/motion/backgrounds'

export default function MagneticFieldDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <MagneticField />
      {/* A soft pool of canvas under the copy, so the field never crosses the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-20% via-canvas/60 via-40% to-transparent to-70%" />
      <p className="relative mb-4 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        Live, all the time
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">Every signal, held in place</p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        The field makes room for whatever you point at, then settles back. Press anywhere to shove it.
      </p>
    </section>
  )
}
```

A hero section over the dot grid; move the pointer across it and the dots make room, then settle back.

`colors` takes two CSS colors: the dots at rest, then the color they take as they are pushed. The defaults are `--color-fg-subtle` and `--color-accent`. Token references follow the theme, and the field rereads them when the theme changes.

### Pointer

```tsx
'use client'

import { useState } from 'react'
import { MagneticField } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

type Mode = 'repel' | 'attract'

export default function MagneticFieldPointer() {
  const [value, setValue] = useState<Mode>('repel')

return (
    <div className="mx-auto flex w-full max-w-[calc(100%-2rem)] flex-col overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <div className="relative isolate h-[280px] overflow-hidden">
        <MagneticField pointer={value} radius={110} />
      </div>
      <div className="flex items-center justify-center gap-2 border-t border-line bg-canvas px-4 py-3">
        <span className="text-xs text-fg-muted">Pointer</span>
        <ToggleGroup
          variant="segmented"
          size="sm"
          aria-label="Pointer response"
          value={[value]}
          onValueChange={(next) => next[0] && setValue(next[0] as Mode)}
        >
          <ToggleGroupItem value="repel" className="px-2.5 text-xs">
            Repel
          </ToggleGroupItem>
          <ToggleGroupItem value="attract" className="px-2.5 text-xs">
            Attract
          </ToggleGroupItem>
        </ToggleGroup>
      </div>
    </div>
  )
}
```

A switch between dots that bend away from the pointer and dots that lean toward it.

Each dot follows a target on a damped spring. The target moves it along the line from the pointer, by an amount that falls off smoothly toward the edge of `radius`, so the field flows around the cursor instead of snapping. When the pointer leaves, the springs carry every dot home with one small wobble. With `pointer="attract"` the dots lean in and can never cross the pointer.

A press shoves the dots near it, and they rebound. The pointer is tracked on the window, so the field responds under the content above it. Set `interactive={false}` where the field sits behind something people work in.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add magnetic-field
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is a live surface that reacts to you: a product hero, a dashboard landing, a 404. It is the most tactile of the grid backgrounds, so keep it to one per page, and keep it quiet behind reading-length text.

The field fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { MagneticField } from '@youj/motion/backgrounds'

export function LiveHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <MagneticField />
      <p className="relative text-5xl font-semibold">Every signal, held in place</p>
    </section>
  )
}
```

`spacing` is the grid pitch in CSS pixels. A finer pitch looks denser and costs more dots: at the default 18px a 1440 x 900 screen draws about 4,000. Dots resting in place are one color; pushed dots take the second color, brighter and a little larger the further they are displaced.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[dots: string, bent: string]` |  | [dots, bent] CSS colors. Default: `--color-fg-subtle` dots that take `--color-accent` as they are pushed. |
| `intensity` | `number` | `1` | Dot opacity, 0–1.5. |
| `speed` | `number` | `1` | Spring speed multiplier. |
| `spacing` | `number` | `18` | Grid pitch in CSS px. |
| `radius` | `number` | `130` | Reach of the pointer in CSS px. |
| `pointer` | `'repel' \| 'attract'` | `'repel'` | Whether the dots bend away from the pointer or toward it. |
| `interactive` | `boolean` | `true` | Pointer reactivity; a press shoves the dots near it. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. Every dot is steered by a spring each frame, which is a few multiplications per dot, and the dots are batched into six paths by how far they are displaced, so a frame is six fills. The canvas renders at a device-pixel ratio capped at 2. On the low motion-budget tier the pitch widens by 30%, which keeps about 60% of the dots, and the loop runs at 30 fps. The loop pauses when the field is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the accent color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Bend |  | damped spring, speed ÷ time scale | each dot springs toward a target pushed away from the pointer |
| Press |  | impulse, then spring | an outward shove near the press point |
| Pointer strength |  | smoothed per frame | eases in and out with the pointer |

**Reduced motion:** Draws one still grid, bent around a fixed point: the same composition every time. There's no spring and no pointer response, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The grid is bent around one fixed point, so it's the same on every visit and in every screenshot, and it still shows what the field does. Only the spring and the pointer response are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Dots are small and low in contrast by default, but they cross whatever sits above them. Keep a quiet pool of canvas behind the copy, as the hero preview does, or lower `intensity`, and check your text's contrast there.
- Nothing moves until the pointer does, and the field stops offscreen. Under reduced motion it doesn't move at all.

---

# Ripple Pond

> Show a calm dot lattice where moving and clicking drop ripples that spread and fade.

Source: https://www.youj.dev/docs/components/ripple-pond

## Examples

### Demo

```tsx
'use client'

import { RipplePond } from '@youj/motion/backgrounds'

export default function RipplePondDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <RipplePond />
      {/* A soft pool of canvas under the copy, so the field never crosses the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-20% via-canvas/60 via-40% to-transparent to-70%" />
      <p className="relative mb-4 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        Calm by default
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">Every action leaves a ripple</p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Move across the field to leave a wake; click to drop a stone. Left alone, it lets a drop fall now and then.
      </p>
    </section>
  )
}
```

A hero section over the pond; move the pointer across it to leave a wake, or click to drop a stone.

`colors` takes two CSS colors: the dots at rest, then the color they take on a crest. The defaults are `--color-fg-subtle` and `--color-accent`. Token references follow the theme, and the pond rereads them when the theme changes.

### Spacing

```tsx
'use client'

import { useState } from 'react'
import { RipplePond } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

type Pitch = '12' | '16' | '24'

export default function RipplePondSpacing() {
  const [value, setValue] = useState<Pitch>('16')

return (
    <div className="mx-auto flex w-full max-w-[calc(100%-2rem)] flex-col overflow-hidden rounded-2xl border border-line bg-canvas sm:max-w-[calc(100%-4rem)]">
      <div className="relative isolate h-[280px] overflow-hidden">
        <RipplePond spacing={Number(value)} />
      </div>
      <div className="flex items-center justify-center gap-2 border-t border-line bg-canvas px-4 py-3">
        <span className="text-xs text-fg-muted">Spacing</span>
        <ToggleGroup
          variant="segmented"
          size="sm"
          aria-label="Spacing"
          value={[value]}
          onValueChange={(next) => next[0] && setValue(next[0] as Pitch)}
        >
          <ToggleGroupItem value="12" className="px-2.5 text-xs">
            12px
          </ToggleGroupItem>
          <ToggleGroupItem value="16" className="px-2.5 text-xs">
            16px
          </ToggleGroupItem>
          <ToggleGroupItem value="24" className="px-2.5 text-xs">
            24px
          </ToggleGroupItem>
        </ToggleGroup>
      </div>
    </div>
  )
}
```

A switch between three lattice pitches.

`spacing` is the distance between dots in CSS pixels. A finer pitch resolves the ring and its trailing wavelets more clearly and draws more dots; a wide one reads as a loose, graphic texture. The ripples keep their size and speed in pixels, so only the sampling changes.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add ripple-pond
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is calm with a response: a sign-in page, a settings landing, a quiet empty state. It does nothing loud on its own, so it suits pages that should feel still until someone touches them. Keep it to one per page.

The pond fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { RipplePond } from '@youj/motion/backgrounds'

export function CalmHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <RipplePond />
      <p className="relative text-5xl font-semibold">Every action leaves a ripple</p>
    </section>
  )
}
```

Moving the pointer drops a soft ripple every 110 pixels of travel. A press or a tap drops a strong one right where it lands, which is what makes the pond work on touch screens. Each ring travels outward as a wave packet with wavelets trailing it, and fades over about three seconds. With `ambient` on (the default), an idle pond lets a drop fall every few seconds, each from the next point of a fixed spread across the field. Turn it off where the pond sits behind something people work in.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[dots: string, wave: string]` |  | [dots, wave] CSS colors. Default: `--color-fg-subtle` dots that take `--color-accent` on a crest. |
| `intensity` | `number` | `1` | Dot opacity and wave height, 0–1.5. |
| `speed` | `number` | `1` | Clock multiplier for how fast the rings travel and fade. |
| `spacing` | `number` | `16` | Lattice pitch in CSS px. |
| `ambient` | `boolean` | `true` | A drop every few seconds while nobody is interacting. |
| `interactive` | `boolean` | `true` | Moving the pointer drops soft ripples; a press drops a strong one. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. Each ripple only visits the dots near its ring, so the cost follows the number of live ripples (at most 28) and not the size of the lattice, and the dots are batched into nine paths by wave height. The canvas renders at a device-pixel ratio capped at 2. On the low motion-budget tier the pitch widens by 30%, which keeps about 60% of the dots, and the loop runs at 30 fps. The loop pauses when the pond is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the accent color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Ring |  | speed ÷ time scale | a wave packet with trailing wavelets, losing height as it spreads |
| Wake |  | distance-based | a soft ripple every 110px the pointer travels |
| Press |  | on press | a strong ripple where it lands |
| Ambient drop |  | clock-based | one every few seconds while nobody is interacting |

**Reduced motion:** Draws one still pond with two rings caught mid-spread: the same composition every time. Nothing moves and nothing responds, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The pond shows two rings frozen mid-spread, so it's the same on every visit and in every screenshot, and it still shows what a ripple looks like. Only the travel, the wake and the ambient drops are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- The lattice is faint at rest, and crests brighten it, so check your text's contrast where a ripple can pass behind it, or lower `intensity`.
- With `ambient` on, a drop falls every few seconds. Turn it off where even that is too much. Under reduced motion nothing moves at all.

---

# Warp Grid

> Show a line grid that sags toward the pointer like mass bending space.

Source: https://www.youj.dev/docs/components/warp-grid

## Examples

### Demo

```tsx
'use client'

import { WarpGrid } from '@youj/motion/backgrounds'

export default function WarpGridDemo() {
  return (
    <section className="relative isolate flex min-h-[400px] w-full flex-col items-center justify-center overflow-hidden px-6 py-12 text-center rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <WarpGrid />
      {/* A soft pool of canvas under the copy, so the field never crosses the text. */}
      <div aria-hidden className="absolute inset-0 bg-radial from-canvas from-15% via-canvas/50 via-35% to-transparent to-65%" />
      <p className="relative mb-4 rounded-full border border-line bg-surface/70 youj-allow-glass px-3 py-1 text-xs font-medium text-fg-muted backdrop-blur-md">
        Built to carry weight
      </p>
      <p className="relative max-w-md text-3xl font-semibold tracking-tight text-balance text-fg sm:text-4xl">Space bends around what matters</p>
      <p className="relative mt-3 max-w-sm text-sm text-pretty text-fg-muted">
        Point at anything and the whole grid leans in. Let go and it settles back to the middle and breathes.
      </p>
    </section>
  )
}
```

A hero section over the grid; move the pointer across it and the whole grid leans toward it. Leave, and the well eases back to the middle.

`colors` takes two CSS colors: the grid lines, then the color the lines take close to the well. The defaults are `--color-fg-subtle` and `--color-accent`. Token references follow the theme, and the grid rereads them when the theme changes.

### Depth

```tsx
'use client'

import { useState } from 'react'
import { WarpGrid } from '@youj/motion/backgrounds'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

type Depth = '0.6' | '1' | '1.8'

export default function WarpGridDepth() {
  const [value, setValue] = useState<Depth>('1')

A switch between a shallow, a default and a deep well.

`depth` scales how far points slide toward the well, and `radius` how far out the pull reaches. Points move with an inverse-square falloff, so lines bunch and curve close to the well and stay where they are far away: the edges of the field never move. A deep well pinches the lines almost together at the center.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add warp-grid
```

It brings `youj-core`, `youj-gl` with it.

Use it where the idea is weight, gravity or structure: infrastructure, finance, anything that should feel like a surface under load. It is the one grid that never goes fully still, because with nobody there the well rests in the middle and breathes slowly. Keep it to one per page.

The grid fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { WarpGrid } from '@youj/motion/backgrounds'

export function WeightedHero() {
  return (
    <section className="relative isolate min-h-[560px]">
      <WarpGrid />
      <p className="relative text-5xl font-semibold">Space bends around what matters</p>
    </section>
  )
}
```

The well follows the pointer with the same smoothing as the other backgrounds. When the pointer leaves, it glides back to the middle of the field and shallows to 40% of its depth. A press deepens it for a moment, which is what makes it respond on touch screens.

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `[lines: string, well: string]` |  | [lines, well] CSS colors. Default: `--color-fg-subtle` lines that take `--color-accent` near the well. |
| `intensity` | `number` | `1` | Line opacity, 0–1.5. |
| `speed` | `number` | `1` | Clock multiplier for the idle breathing and the pulse a press leaves. |
| `spacing` | `number` | `26` | Grid pitch in CSS px. |
| `depth` | `number` | `1` | How far the well pulls the grid, 0–2. |
| `radius` | `number` | `240` | Reach of the well in CSS px. |
| `interactive` | `boolean` | `true` | Pointer reactivity; a press deepens the well for a moment. |
| `className` | `string` |  |  |

### Performance

It's drawn with Canvas 2D, not WebGL. Every line is sampled every 8 pixels and each sample is one inverse-square evaluation, so the whole grid is the base path plus five alpha-bucketed paths for the lit segments. The canvas renders at a device-pixel ratio capped at 2. On the low motion-budget tier the lines are sampled 60% more coarsely and the loop runs at 30 fps. The loop pauses when the grid is offscreen or the tab is hidden, and it stops and cleans up on unmount. If the browser can't create a 2D context, it falls back to a static CSS wash of the accent color.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Well position |  | smoothed per frame | blends from the middle to the pointer by pointer strength |
| Idle breathing |  | speed ÷ time scale | the well deepens and eases about 6% while nobody is there |
| Press pulse |  | about 0.3 s half-life | the well deepens by half, then decays |

**Reduced motion:** Draws one still grid sagging toward the middle: the same composition every time. There's no breathing and no pointer response, and it redraws only when the size, the props or the theme change.

#### Reduced motion

The grid sags toward the middle at its resting depth, so it's the same on every visit and in every screenshot. The lines and the lit accent keep their colors. Only the breathing and the pointer response are gone. Switch on Reduced motion in any preview above to compare.

### Accessibility

- It's decorative: the element is `aria-hidden` and ignores pointer events.
- Lines cross whatever sits above them. Keep a quiet pool of canvas behind the copy, as the hero preview does, or lower `intensity`, and check your text's contrast there.
- The idle breathing is slow and stops offscreen. Under reduced motion the grid doesn't move at all.

---

# Atmosphere

> Float a card on a painted, grainy ground: a meadow, dunes, a copper glow or a dusk, each with a preset to match.

Source: https://www.youj.dev/docs/components/atmosphere

## Examples

### Demo

```tsx
'use client'

import { useState } from 'react'
import { cinnabar, meadow, sandstone, ThemeScope, umber } from '@youj/core'
import { Atmosphere, type AtmosphereScene } from '@youj/motion/backgrounds'
import { SegmentedControl, SegmentedControlItem, StatBreakdown, StatCard } from '@youj/react'

// Each scene with the preset of its name: the card's colors come from the same Wada combination as the ground.
const PRESETS = { meadow, sandstone, cinnabar, umber }

const SOURCES = [
  { label: 'Direct', value: 7012 },
  { label: 'Search', value: 4969 },
  { label: 'Referral', value: 3129 },
  { label: 'Social', value: 2025 },
  { label: 'Email', value: 1271 },
]

export default function AtmosphereDemo() {
  const [scene, setScene] = useState<AtmosphereScene>('meadow')
  return (
    <ThemeScope theme={PRESETS[scene]}>
      <section className="relative isolate grid min-h-[440px] w-full place-items-center gap-5 overflow-hidden px-6 py-10 rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
        <Atmosphere scene={scene} />
        <StatCard
          className="w-full max-w-sm shadow-xl"
          label="Visitors by source"
          value={18406}
          delta={0.124}
          comparison="vs. last week"
          chart={<StatBreakdown parts={SOURCES} />}
        />
        <SegmentedControl aria-label="Scene" value={scene} onValueChange={(value) => setScene(value as AtmosphereScene)} className="shadow-lg">
          {Object.keys(PRESETS).map((id) => (
            <SegmentedControlItem key={id} value={id} className="capitalize">
              {id}
            </SegmentedControlItem>
          ))}
        </SegmentedControl>
      </section>
    </ThemeScope>
  )
}
```

A card on each scene in turn, wearing the preset of the scene's name.

Every scene is drawn in its own palette for light and dark, and each palette comes from a combination in Sanzo Wada's *A Dictionary of Color Combinations*. The preset of the same name (`meadow`, `sandstone`, `cinnabar`, `umber` from `@youj/core`) takes its accent, neutrals and chart colors from that same combination, so the card and its ground read as one scheme. The middle of each composition is its quietest part, where the card sits. See all six, with the two photographs the docs use, on [Backdrops](https://www.youj.dev/docs/backdrops).

### Scenes

```tsx
'use client'

import { cinnabar, meadow, sandstone, ThemeScope, umber } from '@youj/core'
import { Atmosphere } from '@youj/motion/backgrounds'

const SCENES = [
  { scene: 'meadow', theme: meadow, line: 'A meadow under sky, panned so it streaks' },
  { scene: 'sandstone', theme: sandstone, line: 'Broad dunes lit from the top left, in suede' },
  { scene: 'cinnabar', theme: cinnabar, line: 'A dark ground glowing into English red' },
  { scene: 'umber', theme: umber, line: 'A dusk from a pale sky down to umber' },
] as const

export default function AtmosphereScenes() {
  return (
    <div className="grid w-full gap-2 sm:grid-cols-2">
      {SCENES.map(({ scene, theme, line }) => (
        <ThemeScope key={scene} theme={theme}>
          <figure className="relative isolate m-0 grid aspect-[16/10] place-items-center overflow-hidden rounded-lg">
            <Atmosphere scene={scene} />
            <figcaption className="max-w-[80%] rounded-lg border border-line bg-surface px-3.5 py-2.5 text-fg shadow-lg">
              <p className="text-ui-sm font-medium capitalize">{scene}</p>
              <p className="text-ui-xs text-fg-muted">{line}</p>
            </figcaption>
          </figure>
        </ThemeScope>
      ))}
    </div>
  )
}
```

The four scenes:

- `meadow`: a meadow under sky, panned so the grass streaks. At night it's the blue hour.
- `sandstone`: broad dunes lit from the top left, with a fine suede grain lit by the same light. At night the sand sits under a navy sky, with a sienna rim on the crests.
- `cinnabar`: near-black glowing into English red, crossed by soft shadow bands, under heavy grain. By day it's ivory warming to the red.
- `umber`: a dusk going down from a pale sky to umber, with a coarse stipple. At night it's a slate sky over a brass horizon.

### Colors

```tsx
'use client'

import { Atmosphere } from '@youj/motion/backgrounds'

// Five colors in the scene's own order (sandstone: light, mid, shadow, deep, rim). Tokens keep them in your theme.
const COLORS = ['var(--color-surface)', 'var(--color-chart-4)', 'var(--color-accent)', 'var(--color-chart-2)', 'var(--color-canvas)']

export default function AtmosphereColors() {
  return (
    <div className="relative isolate min-h-[320px] w-full overflow-hidden rounded-2xl border border-line bg-canvas mx-auto max-w-[calc(100%-2rem)] sm:max-w-[calc(100%-4rem)]">
      <Atmosphere scene="sandstone" colors={COLORS} />
    </div>
  )
}
```

The sandstone scene in your theme's colors.

Pass five CSS colors to `colors`, in the scene's own order, and they replace its palette in both modes. Tokens keep them in step with your theme. The orders are:

- `meadow`: sky, haze, grass, deep, glint.
- `sandstone`: light, mid, shadow, deep, rim.
- `cinnabar`: base, low, mid, glow, band.
- `umber`: sky, glow, middle, low, deepest.

## Installation & usage

```bash
pnpm add @youj/motion
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add atmosphere
```

It brings `youj-core`, `youj-gl` with it.

Use it for a launch page, a sign-up or a product shot: anywhere one card should be the hero on a ground with some weather to it. Give it the preset of the same name, and keep one per page.

It fills its nearest positioned ancestor and paints behind your content, so make the container `relative` and `isolate`.

```tsx
import { meadow, YoujProvider } from '@youj/core'
import { Atmosphere } from '@youj/motion/backgrounds'

export function Launch() {
  return (
    <YoujProvider theme={meadow}>
      <section className="relative isolate grid min-h-dvh place-items-center p-6">
        <Atmosphere scene="meadow" />
        <YourCard />
      </section>
    </YoujProvider>
  )
}
```

## Description

Each example's description is under Examples.

## Code

Each example's code is under Examples.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scene` | `'meadow' \| 'sandstone' \| 'cinnabar' \| 'umber'` | `'meadow'` | The ground: `meadow` (a panned meadow under sky), `sandstone` (lit dunes with a suede grain), `cinnabar` (a dark ground glowing into English red) or `umber` (a grainy dusk). Each pairs with the theme preset of its name. |
| `colors` | `readonly string[]` |  | Five CSS colors in the scene's own order (meadow: sky, haze, grass, deep, glint; sandstone: light, mid, shadow, deep, rim; cinnabar: base, low, mid, glow, band; umber: sky, glow, middle, low, deepest), in place of its palette for both modes. Tokens follow the mode. |
| `speed` | `number` | `1` | Drift speed multiplier. |
| `grain` | `number` |  | Film grain, 0–1. Default: the scene's own (stronger on cinnabar, finer on sandstone, which has its own suede). |
| `className` | `string` |  |  |

### Performance

Each scene is one WebGL2 fragment shader on a single full-screen triangle, at a device-pixel ratio capped at 1.5 (1 on a low-power device). It draws at most 24 frames a second, since its drift is slow, and pauses off screen and in a hidden tab. It survives a lost GL context and releases the context on unmount. Without WebGL2 it's a still CSS gradient in the same palette, with grain, chosen for the page's light or dark.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Drift |  | speed ÷ time scale | the meadow slides along its streaks, the dunes and bands shift, the dusk glow wanders |
| Grain |  | at most 24 frames a second | a fresh pattern each frame, like film |

**Reduced motion:** Draws one composed still frame with the grain halved, and stops. It redraws only when the size, the props or the theme change.

#### Reduced motion

Each scene draws one composed frame and holds it, with the grain halved and still. The composition and the palette stay the same, so the page looks as designed, only still. Switch on Reduced motion in any preview above to compare.

### Accessibility

It's decorative, so it's `aria-hidden` and ignores pointer events. Keep text on a card, not on the scene: the grounds vary in lightness across the frame, and only the card's surface is held to your theme's contrast.

---

# Activity & conversations

> What people said and did: threads, doc comments, feeds, inboxes, versions, chat, calls and feedback.

Source: https://www.youj.dev/docs/blocks/activity-and-conversations

## Blocks

### Comment thread

The discussion on a record: threads of a comment and its replies on a rail, written in markdown-lite with @mentions that autocomplete at the caret, emoji reactions that pop, edit in place, delete with a confirmation, and resolve, which folds a thread to one line. A comment shows the moment it's sent and settles when `onPost` resolves; one that fails stays with Retry and Discard. In the demo, Mara starts typing a few seconds in, then replies.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add activity-comment-thread
```

It brings `alert-dialog`, `avatar`, `avatar-stack`, `badge`, `button`, `card`, `collapse`, `counter`, `dropdown-menu`, `empty`, `icon-at-sign`, `icon-bell`, `icon-bell-off`, `icon-bold`, `icon-check`, `icon-chevron-down`, `icon-circle-alert`, `icon-code`, `icon-engine`, `icon-italic`, `icon-link`, `icon-loader-dots`, `icon-message`, `icon-more-horizontal`, `icon-pencil`, `icon-reply`, `icon-smile-plus`, `icon-trash`, `input-group`, `kbd`, `popover`, `presence-list`, `skeleton`, `toggle`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-now`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { CommentThread, type CommentThreadProps } from '@/blocks/activity/comment-thread'

export function CommentThreadView({ threads, people, user, typing }: Pick<CommentThreadProps, 'threads' | 'people' | 'user' | 'typing'>) {
  return (
    <CommentThread
      threads={threads}
      people={people}
      user={user}
      typing={typing}
      copy={{ title: 'Discussion' }}
      onSubscribedChange={(subscribed) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onPost={async (draft) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (640px at 100% scale). |
| `classNames` | `{ card?: string }` |  | Classes for its parts: `card` holds the block's size (852px tall at 100%; the threads scroll inside it, so replies, reactions, someone typing and a longer draft never resize it). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's heading level. Default 1, or 2 when `embedded`. |
| `locale` | `string` |  | Formats its times. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `copy` | `Partial<CommentThreadCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `subject` | `string` |  | What the discussion is about, under the title: "Q4 launch plan". |
| `threads` | `CommentThreadItem[]` |  | The threads, oldest first. Default: a launch plan's discussion, with a reply arriving while it's open (a demo, marked). |
| `people` | `CommentThreadPerson[]` | `demo` | Who can be |
| `user` | `CommentThreadPerson` | `the demo's Jordan` | The signed-in person: new comments are theirs, and they can edit and delete their own. |
| `typing` | `CommentThreadPerson[]` | `[]` | People typing right now, from your realtime layer. |
| `reactions` | `string[]` | `👍 👎 😄 🎉 😕 ❤️ 🚀 👀` | The emoji a comment can get. |
| `subscribed` | `boolean` |  | Whether the signed-in person gets notified, when your app owns it; pair with `onSubscribedChange`. |
| `defaultSubscribed` | `boolean` | `true` | Subscribed at first, when the block owns it. |
| `onSubscribedChange` | `(subscribed: boolean) => void` |  |  |
| `now` | `Date \| number` |  | The time the first render shows, which the server and the browser agree on; it ticks on once mounted. Default: the demo's, or the browser's clock with your `threads`. |
| `loading` | `boolean` | `false` | Shows the threads' shapes while they load. |
| `error` | `ReactNode` |  | Why the threads didn't load; shows with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no threads. Default: a quiet "No comments yet". |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the block runs on its demo threads. |
| `onPost` | `(draft: CommentThreadDraft) => Promise<Partial<CommentThreadComment> \| void> \| Partial<CommentThreadComment> \| void` |  | A new comment (`threadId` null) or a reply. Resolve with the saved comment (its `id`, `createdAt`) to replace the one shown. |
| `onEdit` | `(commentId: string, body: string) => Promise<unknown> \| unknown` |  |  |
| `onDelete` | `(commentId: string) => Promise<unknown> \| unknown` |  |  |
| `onReact` | `(commentId: string, emoji: string, reacted: boolean) => Promise<unknown> \| unknown` |  |  |
| `onResolve` | `(threadId: string, resolved: boolean) => Promise<unknown> \| unknown` |  |  |
| `onCopyLink` | `(commentId: string) => void` |  | A comment's Copy link. Default: this page's address with the comment's anchor. |
| `actions` | `ReactNode` |  | More controls at the end of the header, after Subscribe: the host's own actions on the discussion (Resolve, Delete). |

**Strings:** `copy` takes `title`, `demoData`, `count`, `participants`, `subscribe`, `subscribed`, `subscribeHint`, `justNow`, `edited`, `editedAt`, `sending`, `sendFailed`, `retry`, `discard`, `failed`, `deleted`, `newLabel`, `newPlaceholder`, `replyLabel`, `replyPlaceholder`, `editLabel`, `send`, `sendReply`, `save`, `cancel`, `composerHint`, `composerHintOther`, `formatting`, `bold`, `italic`, `code`, `mention`, `mentionList`, `mentionResults`, `actions`, `react`, `reply`, `more`, `edit`, `copyLink`, `delete`, `resolve`, `reopen`, `deleteTitle`, `deleteDescription`, `deleteConfirm`, `resolvedBy`, `showThread`, `hideThread`, `moreReplies`, `replies`, `emojiNames`, `reactions`, `you`, `others`, `reactedWith`, `reactionLabel`, `typing`, `emptyTitle`, `emptyDescription`, `loading`, `errorTitle`, `announceSent`, `announceReply`, `announceComment`, `announceDeleted`, `announceEdited`, `announceResolved`, `announceReopened`, `announceLinkCopied`, `locale`.

### Doc comments

A document with comments pinned to its words, the way Google Docs does it: highlights in the text and a rail of threads beside them, each level with its words, the one you open set right against them and the rest pushed clear. Select a few words and press Comment to start a thread on them. Below 48rem of its own width, the rail becomes a list under the document.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add activity-doc-comments
```

It brings `activity-comment-thread`, `alert-dialog`, `avatar-stack`, `badge`, `button`, `card`, `empty`, `icon-check-circle`, `icon-circle-alert`, `icon-message-plus`, `skeleton`, `toggle`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DocComments, type DocCommentsProps } from '@/blocks/activity/doc-comments'

export function DocCommentsView({ doc, threads, people, user }: Pick<DocCommentsProps, 'doc' | 'threads' | 'people' | 'user'>) {
  return (
    <DocComments
      doc={doc}
      threads={threads}
      people={people}
      user={user}
      copy={{ comments: 'Comments' }}
      onActiveThreadChange={(threadId) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onPost={(draft) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (960px at 100% scale). |
| `classNames` | `{ card?: string }` |  | Classes for its parts: `card` holds the block's size (568px tall at 100%; the document and its comments scroll inside it, so opening, replying and showing resolved threads never resize it). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's heading level; the document's headings sit one under it. Default 1, or 2 when `embedded`. |
| `locale` | `string` |  |  |
| `copy` | `Partial<DocCommentsCopy>` |  |  |
| `doc` | `DocCommentsDoc` | `a pricing launch brief` | The document: its title and its blocks of text. |
| `threads` | `DocCommentsThread[]` |  | The threads, each pinned to a run of a block's text. Default: the brief's discussion (a demo, marked). |
| `people` | `CommentThreadPerson[]` | `demo` | Who can be |
| `user` | `CommentThreadPerson` | `the demo's Jordan` | The signed-in person. |
| `viewers` | `DocCommentsViewer[]` |  | Who has the document open, from your realtime layer. Default: three of the demo's team, with the demo. |
| `reactions` | `string[]` | `demo` |  |
| `activeThread` | `string \| null` |  | The thread that's open, when your app owns it (a deep link); pair with `onActiveThreadChange`. |
| `defaultActiveThread` | `string \| null` | `null` |  |
| `onActiveThreadChange` | `(threadId: string \| null) => void` |  |  |
| `defaultShowResolved` | `boolean` | `false` | Whether resolved threads show in the text and the rail at first. |
| `now` | `Date \| number` |  |  |
| `loading` | `boolean` | `false` |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `demoMarker` | `boolean` | `true` |  |
| `onPost` | `(draft: DocCommentsDraft) => ReturnType<NonNullable<DiscussionHandlers['onPost']>>` |  | A reply, or a new thread with its `anchor`. Resolve with the saved comment to replace the one shown. |
| `onEdit` | `(commentId: string, body: string) => Promise<unknown> \| unknown` |  |  |
| `onDelete` | `(commentId: string) => Promise<unknown> \| unknown` |  |  |
| `onReact` | `(commentId: string, emoji: string, reacted: boolean) => Promise<unknown> \| unknown` |  |  |
| `onResolve` | `(threadId: string, resolved: boolean) => Promise<unknown> \| unknown` |  |  |
| `onCopyLink` | `(commentId: string) => void` |  |  |

**Strings:** `copy` takes `comments`, `counts`, `showResolved`, `viewers`, `addComment`, `commentOn`, `commentsFrom`, `docHint`, `docHintOther`, `newThreadPlaceholder`, `emptyTitle`, `emptyDescription`, `loading`, `errorTitle`, `retry`, `title`, `demoData`, `count`, `participants`, `subscribe`, `subscribed`, `subscribeHint`, `justNow`, `edited`, `editedAt`, `sending`, `sendFailed`, `discard`, `failed`, `deleted`, `newLabel`, `newPlaceholder`, `replyLabel`, `replyPlaceholder`, `editLabel`, `send`, `sendReply`, `save`, `cancel`, `composerHint`, `composerHintOther`, `formatting`, `bold`, `italic`, `code`, `mention`, `mentionList`, `mentionResults`, `actions`, `react`, `reply`, `more`, `edit`, `copyLink`, `delete`, `resolve`, `reopen`, `deleteTitle`, `deleteDescription`, `deleteConfirm`, `resolvedBy`, `showThread`, `hideThread`, `moreReplies`, `replies`, `emojiNames`, `reactions`, `you`, `others`, `reactedWith`, `reactionLabel`, `typing`, `announceSent`, `announceReply`, `announceComment`, `announceDeleted`, `announceEdited`, `announceResolved`, `announceReopened`, `announceLinkCopied`, `locale`.

### Activity feed

A project's activity by day: one sentence a row, with what it carried under it (a comment's words, a change as from → to, labels, a deploy's outcome, the commits). Repeats fold together, filters pick a kind and people, and new events arrive live, waiting behind an "N new" pill while you're reading so nothing moves under your eyes.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add activity-feed
```

It brings `avatar`, `badge`, `button`, `card`, `collapse`, `dropdown-menu`, `empty`, `icon-activity`, `icon-arrow-right`, `icon-arrow-up`, `icon-circle-alert`, `icon-circle-dot`, `icon-engine`, `icon-file-plus`, `icon-git-commit`, `icon-git-merge`, `icon-message`, `icon-rocket`, `icon-signal`, `icon-star`, `icon-tag`, `icon-user-plus`, `icon-users`, `presence-list`, `segmented-control`, `skeleton`, `use-controllable-state`, `use-now`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ActivityFeed, type ActivityFeedProps } from '@/blocks/activity/feed'

export function ActivityFeedView({ events, types, filters }: Pick<ActivityFeedProps, 'events' | 'types' | 'filters'>) {
  return (
    <ActivityFeed
      events={events}
      types={types}
      filters={filters}
      copy={{ title: 'Activity' }}
      linkComponent={Link}
      onFilterChange={(filter) => {
        // your code
      }}
      onLoadMore={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (640px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  |  |
| `locale` | `string` |  |  |
| `copy` | `Partial<ActivityFeedCopy>` |  |  |
| `events` | `ActivityFeedEvent[]` |  | The events, any order. Default: a product team's week, with new events arriving (a demo, marked). |
| `types` | `Record<string, ActivityFeedType>` |  | Your own types, or changes to the built-in ones (comment, status, priority, assign, label, commit, merge, deploy, create, star). |
| `filters` | `ActivityFeedFilter[]` |  | The filters over the feed. Default: All, Comments, Changes, Code. |
| `filter` | `string` |  | The filter on, when your app owns it; pair with `onFilterChange`. |
| `defaultFilter` | `string` | `'all'` |  |
| `onFilterChange` | `(filter: string) => void` |  |  |
| `hasMore` | `boolean` |  | Whether there's older activity to load. |
| `onLoadMore` | `() => Promise<ActivityFeedEvent[] \| void> \| ActivityFeedEvent[] \| void` |  | Loads the next page of older events: return them (they're appended), or pass them back in `events`. |
| `live` | `boolean` |  | Shows the Live mark. Default: true while the demo runs. |
| `now` | `Date \| number` |  |  |
| `loading` | `boolean` | `false` |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no events at all. |
| `demoMarker` | `boolean` | `true` |  |
| `linkComponent` | `ElementType` | `'a'` | Renders the targets' links: your router's Link. |
| `classNames` | `{ list?: string }` |  | Classes for its parts: `list` is the region the rows scroll in (its height, 576px at 100%, holds the card's size as filters, arrivals and older pages change what's in it). |

**Strings:** `copy` takes `title`, `demoData`, `live`, `filters`, `all`, `comments`, `changes`, `code`, `people`, `everyone`, `peopleCount`, `clearPeople`, `today`, `yesterday`, `justNow`, `others`, `showItems`, `hideItems`, `newItems`, `showNew`, `announceNew`, `loadMore`, `loadingMore`, `end`, `emptyTitle`, `emptyDescription`, `noMatchesTitle`, `noMatchesDescription`, `clearFilters`, `loading`, `errorTitle`, `retry`, `failed`, `types`, `locale`.

### Inbox

The notifications triage panel, for a popover or a side panel. One row per thread with its latest words; approve, decline or reply in place; snooze to later today, tomorrow or next week; mark done with Undo. A thread with news is unread again. Every move is a key.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add activity-inbox
```

It brings `activity-comment-thread`, `async-button`, `avatar`, `badge`, `button`, `card`, `dropdown-menu`, `empty`, `icon-alarm-clock`, `icon-at-sign`, `icon-bell`, `icon-check`, `icon-check-check`, `icon-circle-alert`, `icon-engine`, `icon-git-pull-request`, `icon-key`, `icon-mail`, `icon-mail-open`, `icon-message`, `icon-reply`, `icon-rocket`, `icon-user-plus`, `illustrations`, `kbd`, `presence-list`, `skeleton`, `tabs`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ActivityInbox, type ActivityInboxProps } from '@/blocks/activity/inbox'

export function ActivityInboxView({ notifications, kinds, people, user }: Pick<ActivityInboxProps, 'notifications' | 'kinds' | 'people' | 'user'>) {
  return (
    <ActivityInbox
      notifications={notifications}
      kinds={kinds}
      people={people}
      user={user}
      copy={{ title: 'Inbox' }}
      linkComponent={Link}
      onTabChange={(tab) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onOpen={(notification) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (448px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  |  |
| `locale` | `string` |  |  |
| `copy` | `Partial<ActivityInboxCopy>` |  |  |
| `notifications` | `ActivityInboxNotification[]` |  | The notifications, any order. Default: a workspace's, with news arriving (a demo, marked). |
| `kinds` | `Record<string, ActivityInboxKind>` |  | Your own kinds (icon and tone), or changes to the built-in ones: reply, mention, assign, review, access, deploy. |
| `people` | `CommentThreadPerson[]` | `demo` | Who can be |
| `user` | `ActivityInboxPerson` | `demo` | The signed-in person: their |
| `tab` | `'inbox' \| 'mentions' \| 'snoozed'` |  | The tab on show, when your app owns it; pair with `onTabChange`. |
| `defaultTab` | `'inbox' \| 'mentions' \| 'snoozed'` | `'inbox'` |  |
| `onTabChange` | `(tab: Tab) => void` |  |  |
| `now` | `Date \| number` |  |  |
| `loading` | `boolean` | `false` |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `demoMarker` | `boolean` | `true` |  |
| `illustration` | `IllustrationSlot` |  | The picture when the inbox is empty: a scene by id, your own node, or `null`. Default: the success scene. |
| `linkComponent` | `ElementType` | `'a'` | Renders the subjects' links: your router's Link. |
| `onOpen` | `(notification: ActivityInboxNotification) => void` |  | Opening a notification (Enter, or a press on the row); it's marked read too. |
| `onMarkRead` | `(id: string, read: boolean) => Promise<unknown> \| unknown` |  |  |
| `onMarkAllRead` | `() => Promise<unknown> \| unknown` |  |  |
| `onDone` | `(id: string, done: boolean) => Promise<unknown> \| unknown` |  |  |
| `onSnooze` | `(id: string, until: Date \| null) => Promise<unknown> \| unknown` |  |  |
| `onAction` | `(id: string, actionId: string) => Promise<unknown> \| unknown` |  |  |
| `onReply` | `(id: string, body: string, mentions: string[]) => Promise<unknown> \| unknown` |  |  |
| `classNames` | `{ list?: string }` |  | Classes for its parts: `list` is the region under the header, the tabs and the notifications that scroll under them (its height, 520px at 100%, holds the card's size as tabs switch and rows come and go). |

**Strings:** `copy` takes `title`, `demoData`, `tabs`, `inbox`, `mentions`, `snoozed`, `unread`, `markAllRead`, `markRead`, `markUnread`, `unreadPrefix`, `done`, `snooze`, `unsnooze`, `laterToday`, `tomorrow`, `nextWeek`, `until`, `others`, `fresh`, `reply`, `replyPlaceholder`, `replyIn`, `replied`, `undo`, `doneUndo`, `snoozedUndo`, `keys`, `hintMove`, `hintDone`, `hintSnooze`, `hintReply`, `hintRead`, `emptyTitle`, `emptyDescription`, `noMentionsTitle`, `noMentionsDescription`, `noSnoozedTitle`, `noSnoozedDescription`, `loading`, `errorTitle`, `announceArrived`, `announceDone`, `announceSnoozed`, `announceRead`, `announceUnread`, `announceAllRead`, `announceReplied`, `count`, `participants`, `subscribe`, `subscribed`, `subscribeHint`, `justNow`, `edited`, `editedAt`, `sending`, `sendFailed`, `retry`, `discard`, `failed`, `deleted`, `newLabel`, `newPlaceholder`, `replyLabel`, `editLabel`, `send`, `sendReply`, `save`, `cancel`, `composerHint`, `composerHintOther`, `formatting`, `bold`, `italic`, `code`, `mention`, `mentionList`, `mentionResults`, `actions`, `react`, `more`, `edit`, `copyLink`, `delete`, `resolve`, `reopen`, `deleteTitle`, `deleteDescription`, `deleteConfirm`, `resolvedBy`, `showThread`, `hideThread`, `moreReplies`, `replies`, `emojiNames`, `reactions`, `you`, `reactedWith`, `reactionLabel`, `typing`, `announceSent`, `announceReply`, `announceComment`, `announceDeleted`, `announceEdited`, `announceResolved`, `announceReopened`, `announceLinkCopied`, `locale`.

### Version history

A document's versions by day beside the document as it was, with what changed marked word by word and changed properties as before → after. Compare with the version before, the current one or a named one, step through the changes, name a version, or restore one: the restore lands on top as a new version, so nothing is lost.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add activity-version-history
```

It brings `alert-dialog`, `avatar`, `badge`, `button`, `card`, `empty`, `icon-arrow-right`, `icon-chevron-down`, `icon-chevron-up`, `icon-circle-alert`, `icon-history`, `icon-pencil`, `icon-rotate-ccw`, `input`, `label`, `select`, `skeleton`, `switch`, `tooltip`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { VersionHistory, type VersionHistoryProps } from '@/blocks/activity/version-history'

export function VersionHistoryView({ versions, user }: Pick<VersionHistoryProps, 'versions' | 'user'>) {
  return (
    <VersionHistory
      versions={versions}
      user={user}
      copy={{ title: 'Version history' }}
      onVersionChange={(versionId) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onRestore={async (versionId) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (960px at 100% scale). |
| `classNames` | `{ card?: string }` |  | Classes for its parts: `card` holds the block's size (560px tall at 100%; the version and the list scroll inside it, so picking a version or filtering the list never resizes it). |
| `headingLevel` | `1 \| 2 \| 3` |  |  |
| `locale` | `string` |  |  |
| `copy` | `Partial<VersionHistoryCopy>` |  |  |
| `versions` | `VersionHistoryVersion[]` |  | The versions, newest first. Default: a pricing page's copy over two days (a demo, marked). |
| `user` | `VersionHistoryPerson` | `the demo's Jordan` | Who restores and names versions here. |
| `version` | `string` |  | The version on show, when your app owns it; pair with `onVersionChange`. |
| `defaultVersion` | `string` |  | The version on show at first. Default: the newest. |
| `onVersionChange` | `(versionId: string) => void` |  |  |
| `defaultNamedOnly` | `boolean` | `false` | Only named versions in the list at first. |
| `now` | `Date \| number` |  |  |
| `loading` | `boolean` | `false` |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `demoMarker` | `boolean` | `true` |  |
| `onRestore` | `(versionId: string) => Promise<Partial<VersionHistoryVersion> \| void> \| Partial<VersionHistoryVersion> \| void` |  | Restores a version. Resolve with the new version's fields (its `id`) to keep the one shown. |
| `onRename` | `(versionId: string, name: string) => Promise<unknown> \| unknown` |  | Names a version; an empty name removes it. |

**Strings:** `copy` takes `title`, `demoData`, `versions`, `namedOnly`, `current`, `autosave`, `restoredFrom`, `today`, `yesterday`, `counts`, `countsLabel`, `compareTo`, `previous`, `currentShort`, `showChanges`, `changes`, `changeOf`, `noChanges`, `previousChange`, `nextChange`, `added`, `removed`, `properties`, `empty`, `restore`, `restoring`, `restoreTitle`, `restoreDescription`, `restoreConfirm`, `cancel`, `rename`, `renamePlaceholder`, `save`, `announceRestored`, `announceRenamed`, `failed`, `loading`, `emptyTitle`, `emptyDescription`, `errorTitle`, `retry`, `locale`.

### Support chat

A support widget: a launcher with an unread count opens a panel with your team, recent conversations and a help search. Conversations start with an assistant that streams replies, takes attachments and hands off to a person.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-support-chat
```

It brings `avatar`, `avatar-stack`, `badge`, `button`, `chat`, `collapse`, `field`, `icon-arrow-left`, `icon-bot`, `icon-check-circle`, `icon-chevron-down`, `icon-chevron-right`, `icon-file-text`, `icon-loader-ring`, `icon-message-dots`, `icon-moon`, `icon-search`, `icon-send`, `icon-swap`, `icon-x`, `input`, `input-group`, `morph-label`, `popover`, `presence-list`, `rating`, `reveal`, `scroll-area`, `sheet`, `stagger`, `textarea`, `use-announcer`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { SupportChat, type SupportChatProps } from '@/blocks/app/support-chat'

export function SupportChatView({ user, team, threads, articles }: Pick<SupportChatProps, 'user' | 'team' | 'threads' | 'articles'>) {
  return (
    <SupportChat
      user={user}
      team={team}
      threads={threads}
      articles={articles}
      copy={{ helpPrompt: 'how can we help?' }}
      linkComponent={Link}
      onOpenChange={(open) => {
        // your code
      }}
      onSend={() => {
        // your code
      }}
      onLeaveEmail={async (email, threadId) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `false` | Just the widget, over the host's own page: no stand-in Tern page behind it. |
| `children` | `ReactNode` |  | Standalone: your page behind the widget. Default: Tern's data sources demo. |
| `defaultOpen` | `boolean` | `false` | Starts with the panel open, when uncontrolled. |
| `open` | `boolean` |  | Whether the panel is open, to control it. Pair with `onOpenChange`. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the launcher, Escape or the close button opens or closes the panel. |
| `defaultView` | `'home' \| 'new' \| (string & {})` | `'home'` | Where the panel starts: home, a new conversation (`'new'`), or a past one by id (`c-2231` with Mira, `c-2107` closed). |
| `online` | `boolean` | `true` | The team is online: handoffs reach a person. Offline, the assistant takes an email. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tern` | The product, named in the header, the assistant's name and the teaser. |
| `user` | `SupportUser` | `Sam Okafor` | The person chatting: greeted by `first`, initials on their messages. |
| `team` | `SupportAgent[]` | `Mira, Jonas, Aiko` | The people on the desk, faces on home; a handoff brings in the first unless the reply names one. |
| `threads` | `SupportThread[]` | `the demo's two` | Past conversations, newest first, listed on home with their unread counts. |
| `articles` | `SupportArticle[]` | `Tern's seven` | Help articles the search looks through; the first four show as popular. |
| `getArticleHref` | `(article: SupportArticle) => string` | `tern.io/help/<id>` | Where an article opens. |
| `linkComponent` | `ElementType` | `'a'` | The element for article links, e.g. Next.js `Link`. |
| `onSend` | `SupportSendHandler` |  | Delivers a message to your desk; resolve with the reply to play (or nothing), reject to show the error in the thread. Default: a scripted desk. |
| `onLeaveEmail` | `(email: string, threadId: string) => Promise<unknown> \| unknown` |  | Sends the email left while the team is away; a rejection shows its message under the field. |
| `onRate` | `(rating: { threadId: string; score: number; note: string }) => void` |  | A closed conversation was rated, with the optional note. |
| `onFeedback` | `(messageId: string, feedback: ChatFeedback) => void` |  | An answer from the assistant was rated helpful or not. |
| `copy` | `Partial<SupportChatCopy>` |  | Any of the widget's strings, to rewrite or translate; the ones naming the product take `brand.name`. |
| `locale` | `string` |  | Formats numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `widgetLabel`, `homeTitle`, `hello`, `helpPrompt`, `botName`, `greeting`, `openers`, `offlineReply`, `replyTime`, `backAt`, `handoffGreeting`, `handoffSuggestions`, `openChat`, `closeChat`, `close`, `dismiss`, `teaserFrom`, `messageTeam`, `supportTeam`, `teamHere`, `teamAway`, `continueConversation`, `sendMessage`, `leaveMessage`, `recent`, `yourConversation`, `justNow`, `you`, `unreadCount`, `findAnswer`, `searchHelp`, `searchPlaceholder`, `articlesFound`, `popular`, `popularArticles`, `results`, `minutesRead`, `noArticles`, `askTeam`, `backHome`, `conversation`, `quickReplies`, `finding`, `withAgent`, `support`, `closed`, `away`, `botStatus`, `joined`, `closedBy`, `replyTo`, `messageLabel`, `placeholder`, `typing`, `attachments`, `emailTitle`, `email`, `emailPlaceholder`, `notifyMe`, `emailHint`, `emailInvalid`, `emailMissing`, `allSet`, `willReply`, `rated`, `rateAsk`, `verdicts`, `tapStar`, `note`, `sendFeedback`, `thanks`, `newConversation`, `sendFailed`, `locale`.

### Voice call

A call with a voice agent: its name and what it is doing, the call clock, a [Voice Orb](https://www.youj.dev/docs/components/voice-orb), the caption line, and the controls a call needs. Mute grays the orb and stops it hearing, the speaker volume sits beside a meter of the voice, and End call leaves the call ended with how long it lasted and Call again. Its stories show the call muted and ended.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-voice-call
```

It brings `badge`, `button`, `card`, `icon-mic`, `icon-phone`, `icon-phone-off`, `icon-volume`, `segmented-meter`, `slider`, `toggle`, `tooltip`, `use-controllable-state`, `use-visible`, `voice-orb`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { VoiceCall, type VoiceCallProps } from '@/blocks/app/voice-call'

export function VoiceCallView({ agent, agentState, bands, script }: Pick<VoiceCallProps, 'agent' | 'agentState' | 'bands' | 'script'>) {
  return (
    <VoiceCall
      agent={agent}
      agentState={agentState}
      bands={bands}
      script={script}
      copy={{ idle: 'Connected' }}
      onMutedChange={(muted) => {
        // your code
      }}
      onVolumeChange={(volume) => {
        // your code
      }}
      onHangUp={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `idle`, `listening`, `thinking`, `speaking`, `muted`, `ended`, `callTime`, `lasted`, `mute`, `unmute`, `hangUp`, `ending`, `callAgain`, `calling`, `volume`, `volumeValue`, `outputLevel`, `captions`, `demoData`.

### Feedback

An in-product NPS survey: a card that slides into the corner without taking focus, with a 0 to 10 scale, a follow-up question that changes with the score and Not now or dismiss with Undo. A floating Feedback widget is also in the block.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-feedback
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `collapse`, `field`, `file-upload`, `icon-bug`, `icon-check`, `icon-heart`, `icon-lightbulb`, `icon-message-sparkle`, `icon-paperclip`, `icon-party-popper`, `icon-pencil`, `icon-sparkles`, `icon-user-plus`, `icon-x`, `kbd`, `popover`, `radio-group`, `reveal`, `segmented-control`, `sliding-indicator`, `text-split`, `textarea`, `toast`, `toggle-group`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Feedback } from '@/blocks/app/feedback'

export function FeedbackView() {
  return (
    <Feedback
      copy={{ embeddedTitle: 'Feedback' }}
      onAnswer={async (answer) => {
        // await your API here; the block shows progress until it settles
      }}
      onSend={async (feedback) => {
        // await your API here; the block shows progress until it settles
      }}
      onInvite={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `false` | A view inside another app (a settings page): a `section` named by an `h2` with the survey and the form side by side as inline cards, and no page height, width or padding, so the host lays it out. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | Embedded: the section title's level; the cards' titles sit one below it. |
| `variant` | `'survey' \| 'widget'` | `'survey'` | Standalone: the floating NPS survey or the Feedback widget. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tern` | The product the survey and form ask about, named in their copy (and the demo page's logo). |
| `onAnswer` | `(answer: NpsAnswer) => Promise<unknown> \| unknown` | `a simulated request` | Sends a survey answer; a rejection shows "Couldn’t send" and keeps the answer. |
| `onSend` | `(feedback: FeedbackEntry) => Promise<unknown> \| unknown` | `a simulated request` | Sends a feedback message; resolve with a string to show it as the reference, reject to show its message. |
| `onInvite` | `() => void` |  | The promoter's "Invite a teammate" button. Default: a toast saying an invite link was copied. |
| `onSurveyClose` | `(how: 'dismiss' \| 'snooze' \| 'done') => void` |  | The floating survey closed: dismissed (×), snoozed ("Not now") or done after the thanks. |
| `copy` | `Partial<FeedbackCopy>` |  | Any of the block's strings, to rewrite or translate; the ones naming the product take `brand.name`. |
| `children` | `ReactNode` |  | Standalone: your page, behind the floating survey or widget. Default: Tern's roadmap demo. |
| `defaultScore` | `number` |  | Start the survey with this score chosen. |
| `delay` | `number` | `900` | Standalone survey: milliseconds before it slides in. |

**Strings:** `copy` takes `embeddedTitle`, `embeddedDescription`, `surveyLabel`, `inlineTitle`, `inlineDescription`, `askStatus`, `sentStatus`, `dismissSurvey`, `question`, `scaleHint`, `scaleLow`, `scaleHigh`, `followUp`, `addMore`, `optional`, `notNow`, `send`, `sending`, `sent`, `sendFailed`, `youSaid`, `invite`, `inviteCopied`, `inviteCopiedDescription`, `changeAnswer`, `done`, `dismissed`, `dismissedDescription`, `snoozed`, `undo`, `widgetButton`, `formTitle`, `formDescription`, `widgetDescription`, `kinds`, `kindLabel`, `tooShort`, `attach`, `attached`, `dropScreenshot`, `browse`, `failedTitle`, `failedBody`, `context`, `sentWith`, `sendingFeedback`, `tryAgain`, `sentTitle`, `reference`, `sendAnother`, `close`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Keyboard

| Where | Keys | What they do |
| --- | --- | --- |
| Any composer | ⌘/Ctrl + Enter | Send |
| | Esc | Cancel an edit or a reply |
| | ↑ in an empty composer | Edit your last comment |
| | ⌘/Ctrl + B, I, E | Bold, italic, code |
| | @ | Mention someone: ↑ ↓ to choose, Enter or Tab to insert, Esc to close |
| Doc comments | ⌘⌥M / Ctrl+Alt+M | Comment on the selected words |
| | Alt + ↑ / ↓ | Previous or next thread |
| | Enter on a highlight | Open its thread and go to it |
| Activity feed | PageUp / PageDown | Previous or next row |
| | Ctrl + Home / End | Leave the feed before its start or after its end |
| Version history | ↑ ↓, Home, End in the list | Pick a version |
| | Alt + ↑ / ↓ | Previous or next change |
| Inbox | ↑ ↓ or J K, Home, End | Move between notifications |
| | Enter | Open (and mark read) |
| | E, S, R, U | Done, snooze, reply, read or unread |

### Accessibility

Comments are `article`s named by their author and described by their time, in lists. The composer is a labelled textarea whose shortcuts are its description; the mention list is a `listbox` the field drives with `aria-activedescendant`, so focus never leaves the text, and the number of matches is announced. Reactions are toggle buttons (`aria-pressed`) named with the emoji's name, the count and who reacted. Sent, edited, deleted and resolved comments, new replies and failures are announced; failures use `role="alert"`.

In Doc comments each highlight is a button in the text, named by its words and described by its comments, one tab stop per thread; the rail is a list in document order, each thread a group named by its quote.

The activity feed is a WAI-ARIA `feed` of `article`s with `aria-posinset` and `aria-setsize` (−1 while older events can load), busy while they load, under a heading per day. Arrivals are announced once, whether they come in at once or wait behind the pill.

The inbox's rows are one tab stop between them (the current row's tools join it), named by their sentence with "Unread" first when they are; its keys are listed in each tool's `aria-keyshortcuts`.

The version list is a `listbox` with groups per day; changes are real `ins` and `del` elements that say "Added" and "Removed" to a screen reader, each a stop for Previous and Next change.

The support chat is an `aside` named for the product. On desktop the panel is a popover, on phones a full-screen sheet; Escape closes it and focus returns to the launcher. A polite `role="status"` line reports the header's status.

The voice call's orb is an image named by the agent and its state, and state changes are announced politely; the clock is a `role="timer"`, Mute is a toggle with `aria-pressed`, the volume is a labeled slider and the voice level a meter, End call and Call again are named buttons, and the caption line is a polite live region. Muting grays the orb and empties the meter while the agent listens.

The survey card is a labelled `region` that does not steal focus when it appears, and focus returns to the page when it leaves. The 0 to 10 scale is one radio group: each score is named by its number, the arrow keys move through it. The feedback widget's type is a labelled segmented control, the message sends with Cmd or Ctrl and Enter.

Under reduced motion new rows and comments appear in place, threads fold instantly, reactions don't pop and the rail's cards jump to their places.

Under reduced motion cards appear in place and replies arrive whole.

---

# Calendars & schedules

> Time as a grid or a dial: month agendas, rotas, day and week schedules, heatmaps and bookings.

Source: https://www.youj.dev/docs/blocks/calendars-and-schedules

## Blocks

### Month agenda

What comes round each month, on the kit's Calendar: each day a tile with the marks of what falls on it and a dot for the cycle (solid monthly, a ring yearly), today lit and the days outside the month hatched. Hover or arrow onto a day for its events, pick one and + adds one on it; the head counts what is active and new, and the foot sums what is due in the month shown (or counts the events when none has an amount). Every name and mark in the demo is made up; pass a `logo` for yours. The demo is a household's subscriptions; stories show birthdays, a building's maintenance plan and medication refills.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-month-agenda
```

It brings `alert`, `button`, `calendar`, `card`, `hatched-bar`, `icon-chevron-left`, `icon-chevron-right`, `icon-plus`, `skeleton`, `tooltip`, `typography`, `use-controllable-state`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MonthAgenda, type MonthAgendaProps } from '@/blocks/app/month-agenda'

export function MonthAgendaView({ events }: Pick<MonthAgendaProps, 'events'>) {
  return (
    <MonthAgenda
      events={events}
      copy={{ title: 'Subscriptions' }}
      onRetry={() => {
        // your code
      }}
      onMonthChange={(month) => {
        // your code
      }}
      onValueChange={(day) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `add`, `adding`, `added`, `today`, `previous`, `next`, `monthly`, `yearly`, `count`, `newCount`, `perMonth`, `perYear`, `onDay`, `onDayEvent`, `upcoming`, `monthTotal`, `monthCount`, `loadingLabel`, `retry`, `none`, `failed`.

### Shift rota

Who is on shift now, with the shift's time left counting down and who is next, plus Swap and a contact button (Page, Call, Message). Under it, the week in lanes per person with handoffs, overrides and a line for now.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-shift-rota
```

It brings `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `hatched-bar`, `icon-arrow-right`, `icon-more-horizontal`, `icon-phone-call`, `icon-repeat`, `share-bar`, `time-lanes`, `typography`, `use-announcer`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ShiftRota, type ShiftRotaProps } from '@/blocks/app/shift-rota'

export function ShiftRotaView({ people, shifts }: Pick<ShiftRotaProps, 'people' | 'shifts'>) {
  return (
    <ShiftRota
      people={people}
      shifts={shifts}
      copy={{ title: 'On call' }}
      onContact={async (person) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `current`, `onDuty`, `override`, `timeLeft`, `ends`, `next`, `contact`, `contacting`, `contacted`, `swap`, `swapWith`, `swapped`, `covering`, `rota`, `legendNow`, `legendHandoff`, `legendOverride`, `status`, `schedule`, `locale`.

### Day schedule

A day of scheduled events on a 24 hour ring with a hand at now, next to the day's figures: jobs, doses or sailings. Each entry lists its cron expression in words with a pause switch; Stagger overlaps moves colliding entries 15 minutes apart.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-day-schedule
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `day-ring`, `dropdown-menu`, `empty`, `icon-more-horizontal`, `skeleton`, `switch`, `typography`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DaySchedule, type DayScheduleProps } from '@/blocks/app/day-schedule'

export function DayScheduleView({ jobs }: Pick<DayScheduleProps, 'jobs'>) {
  return (
    <DaySchedule
      jobs={jobs}
      copy={{ title: 'Schedules' }}
      onStagger={async (moves) => {
        // await your API here; the block shows progress until it settles
      }}
      onCreate={() => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `exportCrontab`, `pauseAll`, `resumeAll`, `ring`, `today`, `runsToday`, `overlaps`, `next`, `nextRun`, `paused`, `jobs`, `noRuns`, `everyMinutes`, `everyHours`, `hourlyAt`, `dailyAt`, `weekdaysAt`, `atTimes`, `custom`, `overlapsWith`, `enabled`, `synced`, `syncedNow`, `stagger`, `staggering`, `staggered`, `newSchedule`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Week blocks

A week of logged time as columns, one per day: each entry a rounded block in the color of its kind, placed by its start and end on a quiet track with a hairline at each labelled hour. Today is marked, and while the clock is inside the hours a line crosses today's column with its time in the gutter. The week's total leads, large, with a legend that gives the totals per kind. Point at a block, or focus the plot and use the arrow keys, to read it as "Tue 09:30–12:15 · Billable · 2h 45m".

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-week-blocks
```

It brings `card`, `empty`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { WeekBlocks, type WeekBlocksProps } from '@/blocks/app/week-blocks'

export function WeekBlocksView({ entries, kinds, hours }: Pick<WeekBlocksProps, 'entries' | 'kinds' | 'hours'>) {
  return (
    <WeekBlocks
      entries={entries}
      kinds={kinds}
      hours={hours}
      copy={{ title: 'Time this week' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `chart`, `total`, `reading`, `empty`, `summary`, `locale`.

### Week dial

The same week as a clock: a ring per weekday, Monday outermost, with an arc for each entry round a dial that runs clockwise from nine o'clock to six. A hand crosses the rings at the current time, labelled beyond the outer one, and the middle gives the headline kind's total. Both cards read the same `entries` and `kinds`, and the arrow keys step through the entries in the order of the week.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-week-dial
```

It brings `card`, `empty`, `use-now`, `use-resize-measure`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { WeekDial, type WeekDialProps } from '@/blocks/app/week-dial'

export function WeekDialView({ entries, kinds, hours }: Pick<WeekDialProps, 'entries' | 'kinds' | 'hours'>) {
  return (
    <WeekDial
      entries={entries}
      kinds={kinds}
      hours={hours}
      copy={{ title: 'Hours by weekday' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `chart`, `total`, `reading`, `now`, `empty`, `summary`, `locale`.

### Activity heatmap

When it happens: a year of days, weeks across and weekdays down, under the year in four figures. Each step holds a quarter of the active days, so one record day doesn't pale the rest, and pressing a step in the legend lights only its days. Hours shows the same year by hour of the week. Point at a day, or move through the grid with the arrow keys, and one tip glides to it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-activity-heatmap
```

It brings `alert`, `button`, `card`, `empty`, `segmented-control`, `skeleton`, `stat-card`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ActivityHeatmap, type ActivityHeatmapProps } from '@/blocks/app/activity-heatmap'

export function ActivityHeatmapView({ days, hours, steps, tone }: Pick<ActivityHeatmapProps, 'days' | 'hours' | 'steps' | 'tone'>) {
  return (
    <ActivityHeatmap
      days={days}
      hours={hours}
      steps={steps}
      tone={tone}
      copy={{ title: 'Order activity' }}
      onViewChange={(view) => {
        // your code
      }}
      onDaySelect={(day) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<ActivityHeatmapCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats every figure and date (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `days` | `Day[]` |  | What happened each day; a day left out had none. Default: the demo shop's orders. |
| `hours` | `number[][]` |  | Each hour of the week's average per day, Sunday first and midnight first (7 rows of 24): turns on the Hours view. Default: the demo's with the demo's days; none with yours. |
| `today` | `string` |  | The last day shown, as an ISO date. Default: the demo's (10 October 2026), else the latest of `days`. |
| `weeks` | `number` | `53` | How many weeks the grid shows, today's last. |
| `weekStart` | `number` |  | The weekday each column starts on, 0 (Sunday) to 6. Default: the locale's (Monday where the browser can't tell). |
| `format` | `Intl.NumberFormatOptions` | `whole numbers` | Intl.NumberFormat options for every value. |
| `goal` | `number` |  | A day at or over it keeps the streak going. Default: the demo's 25 a day; with your days, any activity. |
| `steps` | `number[]` |  | Where steps two to four start. Default: the quartiles of the active days. |
| `tone` | `'chart-1' \| 'chart-2' \| 'chart-3' \| 'chart-4' \| 'chart-5'` | `'chart-1'` | The chart colour of the steps. |
| `view` | `'days' \| 'hours'` |  | The view shown, controlled: pair it with `onViewChange`. Default: uncontrolled. |
| `defaultView` | `'days' \| 'hours'` | `'days'` | The view shown first, uncontrolled. |
| `onViewChange` | `(view: ActivityHeatmapView) => void` |  | Called with the view picked. |
| `onDaySelect` | `(day: ActivityHeatmapDay) => void` |  | A day is pressed, or picked with Enter. Default: days aren't pickable. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures and the grid while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the grid when the data fails to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message when there's no activity. Default: `copy.empty` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `description`, `view`, `views`, `total`, `activeDays`, `average`, `weekday`, `busiestDay`, `busiestHour`, `streak`, `days`, `best`, `grid`, `count`, `soFar`, `cell`, `legend`, `less`, `more`, `none`, `step`, `range`, `atLeast`, `showing`, `showingAll`, `scale`, `summary`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Terrain calendar

Months of days as an isometric landscape where each day's column is its measure. Switch the measure or the category, then point at a day for its entries, your usual day and its share of the week. The demo is a triathlete's training; stories show a store's sales by department and a weather network's rain by station.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-terrain-calendar
```

It brings `alert`, `button`, `card`, `empty`, `kbd`, `segmented-control`, `skeleton`, `stat-card`, `tooltip`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { TerrainCalendar, type TerrainCalendarProps } from '@/blocks/app/terrain-calendar'

export function TerrainCalendarView({ days, metrics, categories, details }: Pick<TerrainCalendarProps, 'days' | 'metrics' | 'categories' | 'details'>) {
  return (
    <TerrainCalendar
      days={days}
      metrics={metrics}
      categories={categories}
      details={details}
      copy={{ title: 'Training' }}
      onSelect={(day) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `locale`, `title`, `subtitle`, `metricLabel`, `categoryLabel`, `all`, `week`, `vsLastWeek`, `weekly`, `streak`, `span`, `peak`, `terrain`, `range`, `rest`, `noCategory`, `vsUsual`, `entries`, `entryCount`, `rowLabel`, `weekShare`, `grid`, `day`, `legend`, `selected`, `hints`, `hintsLabel`, `showing`, `cell`, `synced`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`.

### Slot booking

A timetable booked the calm way: a month calendar beside the day's slots with places left in words. Narrow to one service, pick a slot to review it, then Book and see the confirmation. A grid variant shows the week. Classes, clinic appointments and tutoring lessons read the same way: your services, hosts, prices and pass are props.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-slot-booking
```

It brings `alert`, `async-button`, `avatar`, `badge`, `button`, `calendar`, `card`, `empty`, `icon-calendar-plus`, `icon-check`, `icon-check-circle`, `icon-chevron-left`, `icon-chevron-right`, `icon-more-horizontal`, `segmented-control`, `segmented-meter`, `skeleton`, `slot-grid`, `stagger`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SlotBooking, type SlotBookingProps } from '@/blocks/app/slot-booking'

export function SlotBookingView({ services, schedule, slots }: Pick<SlotBookingProps, 'services' | 'schedule' | 'slots'>) {
  return (
    <SlotBooking
      services={services}
      schedule={schedule}
      slots={slots}
      copy={{ title: 'Book a class' }}
      onBook={async (slot, service) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `currency`, `title`, `subtitle`, `more`, `service`, `previousWeek`, `nextWeek`, `week`, `grid`, `confirm`, `with`, `duration`, `price`, `places`, `placesLeft`, `minutes`, `pass`, `passLeft`, `change`, `book`, `booking`, `booked`, `bookedTitle`, `bookedNote`, `bookedAnnounce`, `addToCalendar`, `bookAnother`, `email`, `pickPrompt`, `status`, `allServices`, `day`, `slotsOn`, `slotCount`, `placesOpen`, `fewLeft`, `full`, `yours`, `closed`, `noneOfService`, `nextOne`, `openDays`, `yourDays`, `review`, `host`, `when`, `bookedLine`, `topUp`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Itinerary

A trip the way a travel app keeps it: the next leg as a boarding pass with a countdown to departure, then arrival, and the booking reference to copy. Below it the days, each with the place it's spent in, and the picked day's plans in time order with where you sleep that night and every confirmation code to copy. City breaks, conference weeks and film shoots read the same way: the kinds of booking, their icons and their statuses are props.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-itinerary
```

It brings `alert`, `badge`, `button`, `card`, `empty`, `icon-building`, `icon-check`, `icon-coffee`, `icon-copy`, `icon-home`, `icon-more-horizontal`, `icon-plane`, `icon-plus`, `icon-share`, `icon-swap`, `icon-ticket`, `skeleton`, `tabs`, `typography`, `use-announcer`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Itinerary, type ItineraryProps } from '@/blocks/app/itinerary'

export function ItineraryView({ stops, legs, stays, bookings }: Pick<ItineraryProps, 'stops' | 'legs' | 'stays' | 'bookings'>) {
  return (
    <Itinerary
      stops={stops}
      legs={legs}
      stays={stays}
      bookings={bookings}
      copy={{ title: 'Barcelona & Rome' }}
      onDayChange={(day) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `next`, `underway`, `departsIn`, `arrivesIn`, `finished`, `legCode`, `legPlace`, `legReference`, `route`, `days`, `today`, `plans`, `travelTo`, `tonight`, `nothing`, `copyCode`, `copied`, `share`, `addPlan`, `footer`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Month agenda is the kit's Calendar grid: the arrow keys walk the days, Page Up and Page Down the months, and a day with events is named with its date and them ("Bills Tessel, $54.99 Monthly"), which its tooltip shows on hover and keyboard focus. The month name is a polite live region, the cycle is a solid dot or a ring as well as a word, and the arrows and + are named buttons.

Shift rota groups the current shift under a label, the countdown is `role="timer"`, and the time lanes are one tab stop where the arrow keys walk the shifts and Enter opens one, with a hidden hint.

Day schedule draws a ring that is an image with a text description, and each entry's pause switch is named for it. Its heading level follows whether it is embedded.

The week's time blocks and its clock are each one tab stop, a group named for the chart and described by a sentence on the week's total. The arrow keys step through the entries in the order of the week (Right and Down on, Left and Up back), Home and End jump to the first and last, and Escape lets go. The entry is read out by a polite live region as its day, times, kind and length, and every entry is also listed as text for screen readers. The now line and hand are decorative; the time is text beside them.

Each chart has a name and a one-sentence summary, and the metric chart's numbers are also in a real table behind View data. Wherever you can scrub a chart (the KPI tiles and the metric chart), it is a slider: Left and Right step a bucket, Home and End jump to either end, Escape lets go, and each position is read out as a sentence with the date, the figures and the change. The tile and chart headers update with it.

The activity heatmap is a grid with one tab stop. The arrow keys move a day or a week, Home and End move along a weekday, Page Up and Page Down jump four weeks, and Ctrl+Home and Ctrl+End go to the first and last day. Every day is named with its date and value, and the grid is described by a sentence on the total, the busiest day and the busiest weekday. The legend's steps are toggle buttons named with their range, and picking one says how many days it holds.

Terrain calendar draws on a `canvas` that is `aria-hidden`. Its days are exposed as an ARIA grid for the keyboard and screen readers (arrow keys move between days), the measure and category switches are labelled, the entries table has a hidden caption, and view changes are announced.

Slot booking lists each day's slots in a labelled list; every slot is a button. The service filter, the pass and the confirmation are labelled, and the grid variant adds previous and next week buttons. The review pane is a labelled region.

In Itinerary the boarding pass is a labelled group whose route line is named (Barcelona to Rome) and whose countdown is a timer with live announcements off. The days are tabs (arrow keys, Home and End), each named with its date, Today and its city or Travel to …; each day's plans are an ordered list under a heading, statuses are written out, and the copy buttons name the code they copy and announce it. The stories show other worlds, with their own names and words.

Under reduced motion rows, panes and the plane on the pass are drawn in place.

---

# Flows

> Where things go: splits, routes, loops and switchovers, with what moves along each path.

Source: https://www.youj.dev/docs/blocks/flows

## Blocks

### Flow

Where things go, as a sankey. Each path is a ribbon of its own in its source's colour all the way to the end, so a source can be followed past the first step. Point at a step to light every path through it, press it to keep them lit, or point at a ribbon to follow one path. A new range morphs the flow, and View data swaps in the table.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-flow
```

It brings `alert`, `button`, `card`, `empty`, `segmented-control`, `skeleton`, `table`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Flow, type FlowProps } from '@/blocks/app/flow'

export function FlowView({ stages, nodes, paths, ranges }: Pick<FlowProps, 'stages' | 'nodes' | 'paths' | 'ranges'>) {
  return (
    <Flow
      stages={stages}
      nodes={nodes}
      paths={paths}
      ranges={ranges}
      copy={{ title: 'Trial flow' }}
      onRangeChange={(range) => {
        // your code
      }}
      onSelectedChange={(id) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<FlowCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats every figure (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `stages` | `string[]` |  | The stages' names, first to last. Default: the demo's Source, Plan and Outcome. |
| `nodes` | `Node[]` |  | The nodes, each in its stage, in the order they stack. Default: the demo's sources, plans and outcomes. |
| `paths` | `Path[]` |  | The routes through the stages and how many took each. Default: the demo's trials for the range shown. |
| `format` | `Intl.NumberFormatOptions` | `whole numbers` | Intl.NumberFormat options for every figure. |
| `ranges` | `Range[]` |  | The ranges the switch offers, each `{ id, label, name? }`; fewer than two hides it. Default: 7, 30 and 90 days with the demo's paths, none with yours. |
| `range` | `string` |  | The id of the range shown, controlled: pair it with `onRangeChange`. Default: uncontrolled. |
| `defaultRange` | `string` |  | The id of the range shown first, uncontrolled. Default: the first of your `ranges`, else `30d`. |
| `onRangeChange` | `(range: string) => void` |  | Called with the id of the range picked; answer with its `paths`. |
| `selected` | `string \| null` |  | The node kept lit, controlled (`null` for none): pair it with `onSelectedChange`. Default: uncontrolled. |
| `defaultSelected` | `string \| null` | `null` | The node kept lit first, uncontrolled. |
| `onSelectedChange` | `(id: string \| null) => void` |  | Called with the node pressed, or `null` when it's let go. |
| `loading` | `boolean` | `false` | A skeleton in place of the chart while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the chart when the data fails to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message when nothing has flowed. Default: `copy.empty` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `description`, `range`, `count`, `chart`, `nodes`, `node`, `onward`, `from`, `part`, `path`, `arrow`, `summary`, `viewData`, `hideData`, `table`, `columnFrom`, `columnTo`, `columnValue`, `columnShare`, `announcement`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Routing flow

How a stream is routed across the places it can go, and what that costs; the default is a team's LLM traffic, and card payments or a water network read the same way. The blended cost leads, with how far a draft moves it from the live policy and the throughput, slow time and failure rate it blends to. Your own strategies (Cost, Balanced and Quality in the demo) reshape the split: the source fans out to each route as a stream as dense as its share. Below, the routes with share, typical / slow time, cost and failures, each lighting its lane, and the fallback rule as a sentence; Deploy policy makes the draft the next live version. It has loading, error and empty states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-routing-flow
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `empty`, `flow-lanes`, `segmented-control`, `select`, `share-bar`, `skeleton`, `stat-card`, `switch`, `table`, `typography`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RoutingFlow, type RoutingFlowProps } from '@/blocks/app/routing-flow'

export function RoutingFlowView({ routes, strategies, shares, formats }: Pick<RoutingFlowProps, 'routes' | 'strategies' | 'shares' | 'formats'>) {
  return (
    <RoutingFlow
      routes={routes}
      strategies={strategies}
      shares={shares}
      formats={formats}
      copy={{ title: 'Model router' }}
      onRetry={() => {
        // your code
      }}
      onStrategyChange={(strategy) => {
        // your code
      }}
      onDeploy={async (policy) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (576px at 100% scale). |
| `copy` | `Partial<RoutingFlowCopy>` |  | Any of the card's strings, to rewrite or translate; `currency` prices the routes. |
| `locale` | `string` |  | Formats costs, rates and shares (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `routes` | `RoutingFlowRoute[]` | `demo` | The routes the flow can be sent to. |
| `strategies` | `RoutingFlowStrategy[]` | `Cost, Balanced, Quality` | The ways to weigh a choice, in the switch's order. |
| `shares` | `RoutingFlowShares` | `demo` | Each strategy's split of the flow: strategy id, then route id. |
| `throughput` | `number` | `demo` | Units a second through the source, split by the shares. |
| `formats` | `RoutingFlowFormats` |  | How the figures are written; each replaces its default whole. Default: the demo's currency, seconds and percents. |
| `failWarnAt` | `number` | `0.01` | The failure rate (0–1) from which a route's rate turns warning-colored. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures, the flow and the table while your data loads. |
| `error` | `string` |  | Shown in place of the flow when it fails to load, with Retry when `onRetry` is set; the headline shows a dash. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there are no routes. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `policy` | `RoutingFlowPolicy` | `demo` | The live policy: its version, strategy and fallback. The card's draft starts from it. |
| `strategy` | `string` |  | The draft's strategy, when your app owns it; pair with `onStrategyChange`. |
| `defaultStrategy` | `string` |  | The draft's strategy at first, when the card owns it. Default: the live policy's. |
| `onStrategyChange` | `(strategy: string) => void` |  | Called when the strategy switch moves. |
| `onDeploy` | `(policy: RoutingFlowPolicy) => Promise<unknown> \| unknown` |  | Deploys the draft; the card awaits it, then shows it live as the next version. |

**Strings:** `copy` takes `title`, `pool`, `live`, `draft`, `blended`, `sameAsLive`, `changed`, `perMillion`, `vsLive`, `facts`, `strategy`, `source`, `flow`, `rate`, `routes`, `route`, `share`, `time`, `cost`, `failures`, `timeUnit`, `fallback`, `fallbackIf`, `fallbackThen`, `fallbackFrom`, `fallbackTo`, `policy`, `unsaved`, `revert`, `deploy`, `deploying`, `deployed`, `failed`, `announceStrategy`, `announceDeployed`, `currency`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Queue flow

Work moving through steps, live: arrivals, triage and teams with items riding the routes between them, shown as a support desk, an emergency room and a parcel sorter. Pick a lens (volume, wait time, rejects), add people to a team over target or clear the rejects.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-queue-flow
```

It brings `async-button`, `badge`, `button`, `card`, `icon-ban`, `icon-bot`, `icon-code`, `icon-credit-card`, `icon-mail`, `icon-messages`, `icon-phone`, `icon-play`, `icon-route`, `segmented-control`, `sparkline`, `stat-card`, `typography`, `use-announcer`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { QueueFlow, type QueueFlowProps } from '@/blocks/app/queue-flow'

export function QueueFlowView({ lenses, nodes, routes, desk }: Pick<QueueFlowProps, 'lenses' | 'nodes' | 'routes' | 'desk'>) {
  return (
    <QueueFlow
      lenses={lenses}
      nodes={nodes}
      routes={routes}
      desk={desk}
      copy={{ title: 'Support desk' }}
      onStaff={async (node, agents) => {
        // await your API here; the block shows progress until it settles
      }}
      onPurge={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `live`, `demoData`, `paused`, `pause`, `resume`, `overview`, `volume`, `reply`, `waiting`, `sink`, `perHour`, `ofTarget`, `deepest`, `noneWaiting`, `rejectedShare`, `lens`, `layers`, `kinds`, `graph`, `health`, `table`, `from`, `to`, `rate`, `in`, `new`, `routed`, `solved`, `waitingLabel`, `staffLabel`, `held`, `rejected`, `reads`, `writes`, `nothing`, `staff`, `staffing`, `staffed`, `purge`, `purging`, `purged`, `open`, `overTarget`, `backOnTarget`, `deskPaused`, `deskResumed`, `updated`, `legend`, `history`, `locale`.

### Loop route

A vehicle's loop as a route map (the demo: a plant's milk run, with a school bus and a campus shuttle in the stories): stops done, the next one ringed, the rest hollow, and the vehicle where it is now, with the loop count and what is on board in the middle. Below it the stops still to come with what each gets and its arrival time, then Skip stop and Rush delivery. `format.time` reads the times, and loading, error and empty states take the map's place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-loop-route
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `empty`, `skeleton`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { LoopRoute, type LoopRouteProps } from '@/blocks/app/loop-route'

export function LoopRouteView({ stops }: Pick<LoopRouteProps, 'stops'>) {
  return (
    <LoopRoute
      stops={stops}
      copy={{ title: 'Milk run' }}
      onSkip={(stop) => {
        // your code
      }}
      onRush={async (stop) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `minutes`, `subtitle`, `vehicle`, `onRoute`, `rushing`, `mapLabel`, `loop`, `onBoard`, `nextTag`, `upNext`, `cargo`, `eta`, `rush`, `state`, `skipped`, `skip`, `skipping`, `rushDelivery`, `rushingNow`, `rushed`, `announceSkipped`, `announceRushed`, `none`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Switchover

A primary source handing over to its backup, told live. Simulate an outage and watch the primary fail its checks, the load move onto the backup and then Switch back; every step lands on a timeline. The demo is a home riding through a power cut; stories show a database failing over and a branch office's fiber falling back to a cellular link.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-switchover
```

It brings `async-button`, `badge`, `button`, `card`, `counter`, `dropdown-menu`, `icon-more-horizontal`, `iso-scene`, `iso-shapes`, `share-bar`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Switchover, type SwitchoverProps } from '@/blocks/app/switchover'

export function SwitchoverView({ primary, backup }: Pick<SwitchoverProps, 'primary' | 'backup'>) {
  return (
    <Switchover
      primary={primary}
      backup={backup}
      copy={{ title: 'Backup power' }}
      onSimulate={() => {
        // your code
      }}
      onSwitchBack={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `site`, `more`, `openSettings`, `status`, `rig`, `split`, `loadSplit`, `signal`, `signalValue`, `reserve`, `primary`, `backup`, `health`, `unit`, `ofLoad`, `carries`, `checks`, `checksLabel`, `failedOf`, `passing`, `timeline`, `stages`, `empty`, `events`, `started`, `rule`, `simulate`, `switchBack`, `switchingBack`, `switchedBack`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The flow's ribbons are decorative. Its steps are buttons on one tab stop: Up and Down move along a stage, Left and Right go to the nearest step of the next or last stage, and each is named with its figure, its share and where its people went next (or, at the end, where they came from). Enter pins a step and Escape lets it go. A new range is announced with its total, and View data shows every step to step as a table.

Routing flow names its strategy switch (a segmented control whose segments are pressed buttons) and announces the new blended cost in a polite live region. The flow is a named group described by its source and total, with each route in a list read with its rate and share; the drawing is decorative. The routes are a table with a header per column, and the fallback rule is a labelled switch and two named selects that turn off with it. The head's badge and the foot's caption say in words whether the policy is live or a draft, and a failed deploy says why in its button.

Queue flow lays steps out as a labelled group of buttons with `aria-pressed`, spoken with their name, kind, health and figure; the arrow keys move along the flow. The lens switch is labelled, the overview is a labelled stat group, and a hidden table lists every figure.

Loop route draws the map as an image whose text gives how many stops are done and how many bins are on board, and the list under it names each stop's state in words (the ring and the filled dots only echo it). Skip stop and Rush delivery announce their result, and the vehicle's ring holds still under reduced motion.

Switchover announces each step as it is logged. The four stages are an ordered list with `aria-current="step"` on the current one, the timeline is a labelled group, each source's carried power is a labelled group and its checks are an image with a spoken label. The simulation holds while it is off screen or the tab is hidden.

Under reduced motion pulses and pings stop and everything else changes in place.

---

# Forms & inputs

> Asking and setting: forms, filters, permission matrices, steppers, allocations, seat maps, controls, procedures and preferences.

Source: https://www.youj.dev/docs/blocks/forms-and-inputs

## Blocks

### Settings

A settings section built from your groups of fields. A changed field gets a mark in the margin and its own Reset, and the card's footer turns into a save bar with the number of changes. The bar sticks to the bottom of the window while the card's end is out of view. ⌘S saves and Discard offers Undo. Closing the tab asks first, and a link elsewhere in the app waits until the changes are saved or discarded.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add forms-settings
```

It brings `button`, `combobox`, `field`, `form`, `icon-alert-triangle`, `icon-check`, `icon-undo`, `input-group`, `kbd`, `radio-group`, `segmented-control`, `select`, `spinner`, `switch`, `tag-input`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SettingsForm, type SettingsFormProps } from '@/blocks/forms/settings'

export function SettingsFormView({ groups, value }: Pick<SettingsFormProps, 'groups' | 'value'>) {
  return (
    <SettingsForm
      groups={groups}
      value={value}
      copy={{ title: 'General' }}
      onValueChange={(values) => {
        // your code
      }}
      onSave={async (values, changed) => {
        // await your API here; the block shows progress until it settles
      }}
      onDirtyChange={(dirty) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2` instead of the page's `h1` (its groups an `h3`), and no page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `copy` | `Partial<SettingsFormCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Picks the plural of its counts (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `groups` | `SettingsGroup[]` | `a workspace's name, defaults and security` | The settings, in groups. |
| `value` | `SettingsValues` |  | The saved settings, controlled: pair it with `onValueChange`. A new value updates every field you haven't changed. |
| `defaultValue` | `SettingsValues` | `the demo workspace's` | The saved settings to start from, when the block owns them. |
| `onValueChange` | `(values: SettingsValues) => void` |  | Called with the settings once a save goes through. |
| `onSave` | `(values: SettingsValues, changed: string[]) => Promise<unknown> \| unknown` |  | Saves the settings (all of them, and the names of those that changed). Reject with `{ fields: { name: message } }` to put messages under fields, or with an Error to say why in the bar. Default: a short demo wait. |
| `onDirtyChange` | `(dirty: boolean) => void` |  | Called when unsaved changes appear or go, to guard your router's own navigation. |
| `guard` | `boolean` | `true` | Ask before the tab closes and hold links elsewhere in the app while changes are unsaved. |

**Strings:** `copy` takes `title`, `description`, `footer`, `saved`, `changes`, `discard`, `save`, `saving`, `savedLabel`, `saveFailed`, `invalid`, `discarded`, `undo`, `leave`, `saveAndLeave`, `discardAndLeave`, `failed`, `reset`, `resetLabel`, `empty`, `on`, `off`, `required`, `tooLong`, `left`, `checking`, `available`, `search`.

### Multi-step form

A multi-step application whose steps follow the answers: a limited company goes on to its register details and the people who control it, a sole trader to their own details. Continue lists any problems at the top of the step, each linking to its field. Saving the draft keeps the answers to finish later, and Check your answers comes before the send.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add forms-multi-step
```

It brings `alert`, `async-button`, `button`, `checkbox`, `collapse`, `field`, `file-upload`, `form`, `icon-check`, `icon-plus`, `icon-trash`, `input`, `input-group`, `presence-list`, `radio-group`, `select`, `wizard`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { MultiStepForm, type MultiStepFormProps } from '@/blocks/forms/multi-step'

export function MultiStepFormView({ types, countries, industries, roles }: Pick<MultiStepFormProps, 'types' | 'countries' | 'industries' | 'roles'>) {
  return (
    <MultiStepForm
      types={types}
      countries={countries}
      industries={industries}
      roles={roles}
      copy={{ title: 'Open a business account' }}
      onValueChange={(values) => {
        // your code
      }}
      onSaveDraft={async (values, step) => {
        // await your API here; the block shows progress until it settles
      }}
      onUpload={async (file, context) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2` instead of the page's `h1` (each step an `h3`), and no page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (672px at 100% scale). |
| `copy` | `Partial<MultiStepFormCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Writes the draft's saved time in this locale (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `types` | `ApplicationOption[]` | `sole trader, limited company, partnership, non-profit` | The kinds of business, each with its path. |
| `countries` | `ApplicationOption[]` | `five in Europe` | The countries a business can be registered in. |
| `industries` | `ApplicationOption[]` | `six broad industries` | What a business can do. |
| `roles` | `ApplicationOption[]` | `director, owner, both` | The roles a person in control can have. |
| `maxPeople` | `number` | `4` | The most people in control. |
| `minAge` | `number` | `18` | The youngest age that may apply, checked against the date of birth. |
| `value` | `Partial<ApplicationValues>` |  | The answers, controlled: pair it with `onValueChange`. |
| `defaultValue` | `Partial<ApplicationValues>` |  | The answers to start from (a saved draft): it opens on the first step that still needs something. Default: none. |
| `onValueChange` | `(values: ApplicationValues) => void` |  | Called with the answers as they change. |
| `onSaveDraft` | `(values: ApplicationValues, step: ApplicationStepId) => Promise<unknown> \| unknown` |  | Saves the answers to finish later. Default: a short demo wait. |
| `onUpload` | `(file: File, context: UploadContext) => Promise<unknown>` |  | Uploads one document, reporting progress. Default: a demo upload. |
| `onSubmit` | `(application: ApplicationSubmission) => Promise<string \| void> \| string \| void` |  | Sends the application; resolve with its reference to show it. Reject to keep everything and say why. Default: a short demo wait. |
| `now` | `Date` |  | Today, for the date of birth and the year founded. Default: the moment the block mounts. |

**Strings:** `copy` takes `title`, `description`, `steps`, `descriptions`, `type`, `name`, `nameHint`, `country`, `industry`, `choose`, `registration`, `registrationHint`, `founded`, `website`, `websitePlaceholder`, `optional`, `person`, `personName`, `role`, `share`, `addPerson`, `removePerson`, `shares`, `yourName`, `birth`, `birthHint`, `day`, `month`, `year`, `document`, `documentTitle`, `declaration`, `change`, `changeLabel`, `none`, `problemTitle`, `next`, `back`, `submit`, `submitted`, `saveDraft`, `savedAt`, `failedTitle`, `failedDescription`, `doneTitle`, `reference`, `nextTitle`, `nextSteps`, `typeMissing`, `nameMissing`, `industryMissing`, `registrationMissing`, `registrationInvalid`, `foundedInvalid`, `websiteInvalid`, `personNameMissing`, `roleMissing`, `shareMissing`, `sharesOver`, `yourNameMissing`, `birthMissing`, `birthInvalid`, `birthFuture`, `birthAge`, `documentsMissing`, `documentsUploading`, `declarationMissing`, `locale`.

### Payment details

Card fields that recognize the brand and format the number to match, then move focus on as each field is complete. The billing address follows the country's order and terms, with a lookup on its first line. A business purchase adds the tax number, checked in that country's format. In production, your payment provider's element takes the card fields' place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add forms-payment
```

It brings `alert`, `badge`, `checkbox`, `collapse`, `combobox`, `field`, `form`, `icon-credit-card`, `icon-lock`, `icon-map-pin`, `input-group`, `morph-label`, `select`, `spinner`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { PaymentForm, type PaymentFormProps } from '@/blocks/forms/payment'

export function PaymentFormView({ countries, brands, now }: Pick<PaymentFormProps, 'countries' | 'brands' | 'now'>) {
  return (
    <PaymentForm
      countries={countries}
      brands={brands}
      now={now}
      copy={{ title: 'Payment details' }}
      onAddressChange={(address) => {
        // your code
      }}
      onSearchAddress={async (query, country) => {
        // await your API here; the block shows progress until it settles
      }}
      onSubmit={async (details) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `card`, `cardNumber`, `cardNumberPlaceholder`, `brandLabel`, `expiry`, `expiryPlaceholder`, `cvc`, `cvcHint`, `cardName`, `numberIncomplete`, `numberInvalid`, `brandRefused`, `expiryIncomplete`, `expiryMonth`, `expiryPast`, `expiryFar`, `cvcIncomplete`, `nameMissing`, `billing`, `country`, `searchCountry`, `suggestions`, `addressLine1`, `addressLine2`, `addressNoun`, `addressPlaceholder`, `optional`, `missing`, `choose`, `invalid`, `regionPlaceholder`, `business`, `businessHint`, `company`, `companyMissing`, `dueToday`, `pay`, `save`, `paying`, `paid`, `saved`, `failed`, `invalidForm`, `failedTitle`, `failedDescription`, `secure`, `locale`.

### Support request

A support request where the topic decides the fields: a bug asks where it happened and how bad it is, and billing asks for the invoice. Help articles appear under the subject as it's typed, and screenshots upload with progress. The footer says when to expect a reply, based on the team's real hours and shown in the requester's own time.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add forms-support
```

It brings `alert`, `button`, `checkbox`, `collapse`, `field`, `file-upload`, `form`, `icon-book-open`, `icon-bug`, `icon-check`, `icon-external-link`, `icon-key`, `icon-lightbulb`, `icon-message`, `icon-receipt`, `input`, `presence-list`, `radio-group`, `segmented-control`, `select`, `textarea`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { SupportRequest, type SupportRequestProps } from '@/blocks/forms/support'

export function SupportRequestView({ topics, hours, now, diagnostics }: Pick<SupportRequestProps, 'topics' | 'hours' | 'now' | 'diagnostics'>) {
  return (
    <SupportRequest
      topics={topics}
      hours={hours}
      now={now}
      diagnostics={diagnostics}
      copy={{ title: 'Contact support' }}
      linkComponent={Link}
      onTopicChange={(topic) => {
        // your code
      }}
      onSearchArticles={async (query, topic) => {
        // await your API here; the block shows progress until it settles
      }}
      onUpload={async (file, context) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `topic`, `email`, `emailPlaceholder`, `topicMissing`, `emailMissing`, `emailInvalid`, `subject`, `subjectMissing`, `articles`, `newTab`, `message`, `messagePlaceholder`, `messageMissing`, `attachments`, `attachmentsTitle`, `uploading`, `diagnostics`, `diagnosticsHint`, `optional`, `choose`, `required`, `online`, `away`, `dayAt`, `send`, `sending`, `sent`, `failed`, `invalid`, `failedTitle`, `failedDescription`, `doneTitle`, `doneDescription`, `another`, `requests`, `locale`.

### Chip filters

A search written first and refined after (orders, job listings or a catalog): filters as a query of chips you can type or edit, a histogram cut by a range, and groups as a checklist. The result count rolls to each change.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-chip-filters
```

It brings `async-button`, `button`, `card`, `checkbox`, `counter`, `dropdown-menu`, `field`, `filter-chips`, `histogram-range`, `icon-copy`, `icon-more-horizontal`, `icon-rotate-ccw`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ChipFilters, type ChipFiltersProps } from '@/blocks/app/chip-filters'

export function ChipFiltersView({ fields, options }: Pick<ChipFiltersProps, 'fields' | 'options'>) {
  return (
    <ChipFilters
      fields={fields}
      options={options}
      copy={{ title: 'Orders' }}
      onValueChange={(value) => {
        // your code
      }}
      onSaveView={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the panel in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside your page: an `h2`, at its natural width, with no page around it. `false` draws its own page around it (a centered canvas and the page's `h1`). |
| `fill` | `boolean` | `false` | Take the width the page gives it, not its natural width. |
| `copy` | `Partial<ChipFiltersCopy>` |  | Any of the panel's strings, to rewrite or translate. |
| `fields` | `ChipFiltersFields` | `basket value and order state` | The two fields: the range the histogram spreads records along, and the checklist; each names its filter in the query. |
| `options` | `ChipFiltersOption[]` | `a quarter of demo orders by fulfillment state` | The groups the records fall into, each with its counts per bin of the range. |
| `defaultValue` | `ChipFiltersValue` | `25 to 180, paid and shipped` | The filters it opens with. |
| `onValueChange` | `(value: ChipFiltersValue) => void` |  |  |
| `onSaveView` | `(value: ChipFiltersValue) => unknown` | `demo` | "Save search". Reject with an Error to show it failed. |
| `format` | `(value: number) => string` |  | Formats the range's amounts on the axis and the thumbs. Default: whole units of `copy.currency` in the locale. |
| `locale` | `string` |  | Formats counts and amounts. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `currency`, `title`, `scope`, `more`, `copyQuery`, `copied`, `search`, `ofTotal`, `matchedAnnouncement`, `rangeLabel`, `choiceLabel`, `allOptions`, `countColumn`, `selectedOf`, `reset`, `saveView`, `saving`, `saved`, `invalidToken`, `invalidRange`, `unknownOption`, `unknownField`, `locale`.

### Permission matrix

Who can do what in a workspace, a school or a clinic, read one role at a time: pick a role, then choose for each area whether it has no access, can view, can edit or has full access. Switch to the grid to see every role at once. Changes wait until you review them and save.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-permission-matrix
```

It brings `async-button`, `badge`, `button`, `card`, `dialog`, `dropdown-menu`, `icon-arrow-right`, `icon-credit-card`, `icon-folder`, `icon-history`, `icon-key`, `icon-lock`, `icon-more-horizontal`, `icon-rocket`, `icon-users`, `level-matrix`, `segmented-control`, `select`, `tabs`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { PermissionMatrix, type PermissionMatrixProps } from '@/blocks/app/permission-matrix'

export function PermissionMatrixView({ roles, resources, view, saved }: Pick<PermissionMatrixProps, 'roles' | 'resources' | 'view' | 'saved'>) {
  return (
    <PermissionMatrix
      roles={roles}
      resources={resources}
      view={view}
      saved={saved}
      copy={{ title: 'Permissions' }}
      onViewChange={(view) => {
        // your code
      }}
      onApply={async (value) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `scope`, `roles`, `more`, `exportCsv`, `copyJson`, `access`, `levels`, `shape`, `view`, `views`, `abilities`, `abilityHints`, `roleList`, `areaAccess`, `was`, `locked`, `grid`, `pending`, `upToDate`, `added`, `removed`, `review`, `reviewTitle`, `reviewDescription`, `change`, `discard`, `apply`, `applying`, `applied`, `locale`.

### Setup stepper

Setting something up in three steps (an AI assistant, a store or a course): a free-text step, a settings step (a name, a choice, a slider and pills you switch on) and who gets access. The TOML config it will save rebuilds beside the form, marking lines that differ from where it started.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-setup-stepper
```

It brings `async-button`, `button`, `card`, `empty`, `field`, `gradient-slider`, `icon-arrow-right`, `icon-check-circle`, `input`, `radio-group`, `reveal`, `select`, `textarea`, `toggle`, `wizard`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SetupStepper, type SetupStepperProps } from '@/blocks/app/setup-stepper'

export function SetupStepperView({ initial, choices, options, audiences }: Pick<SetupStepperProps, 'initial' | 'choices' | 'options' | 'audiences'>) {
  return (
    <SetupStepper
      initial={initial}
      choices={choices}
      options={options}
      audiences={audiences}
      copy={{ brand: 'Lumen' }}
      onCreate={async (config) => {
        // await your API here; the block shows progress until it settles
      }}
      onOpen={(config) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (1152px at 100% scale). |
| `copy` | `Partial<SetupStepperCopy>` |  | Any of the flow's strings, to rewrite or translate. |
| `initial` | `SetupStepperConfig` | `the template, a release-notes writer` | Where the form starts, and what the config's `~` marks are measured against. |
| `choices` | `SetupStepperChoice[]` | `three models` | What the select offers, in order. |
| `options` | `SetupStepperOption[]` | `five tools` | The pills you switch on. |
| `scale` | `SetupStepperScale \| null` | `creativity from 0 to 1.5` | The slider's range and zones; `null` leaves it out. |
| `audiences` | `SetupStepperAudience[]` | `only me, my team, everyone` | The radios of the last step. |
| `step` | `number` | `1` | The step it opens on, from 0. |
| `onCreate` | `(config: SetupStepperConfig) => Promise<unknown> \| unknown` |  | Creates it from the config; resolve when it exists. Reject to stay on the last step. |
| `onOpen` | `(config: SetupStepperConfig) => void` |  | "Start a conversation" on the done state. |
| `locale` | `string` |  | Formats its numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `brand`, `title`, `subtitle`, `stepDetails`, `stepDetailsDescription`, `stepSettings`, `stepSettingsDescription`, `stepAccess`, `stepAccessDescription`, `description`, `descriptionRequired`, `name`, `namePlaceholder`, `nameHint`, `nameRequired`, `choice`, `measure`, `scale`, `options`, `optionsCount`, `audience`, `back`, `next`, `create`, `created`, `preview`, `previewFile`, `previewSections`, `previewKeys`, `changed`, `copy`, `copied`, `doneTitle`, `doneDescription`, `open`, `locale`.

### Split allocation

One amount split across categories, evenly or by hand: a bar that shows what is allocated and what is still open, rows whose amount and percent stay in step, and a status that says what is left before the split can be saved. The demo is a purchase; stories show roommates sharing the rent and a festival's volunteer hours across stations.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-split-allocation
```

It brings `async-button`, `button`, `card`, `hatched-bar`, `icon-plus`, `icon-x`, `segmented-control`, `select`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SplitAllocation, type SplitAllocationProps } from '@/blocks/app/split-allocation'

export function SplitAllocationView({ total, categories }: Pick<SplitAllocationProps, 'total' | 'categories'>) {
  return (
    <SplitAllocation
      total={total}
      categories={categories}
      copy={{ title: 'Split transaction' }}
      onModeChange={(mode) => {
        // your code
      }}
      onLinesChange={(lines) => {
        // your code
      }}
      onSave={async (lines) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `mode`, `equal`, `custom`, `allocation`, `category`, `amount`, `percent`, `amountOf`, `percentOf`, `categoryOf`, `add`, `remove`, `complete`, `left`, `over`, `cancel`, `save`, `saving`, `saved`, `locale`.

### Slot sorter

A setup step that sorts items into slots (an inbox, expenses or support tickets): a step count and a picture, today’s split as one bar with each slot’s count (an off slot is hatched), and the latest items with how sure the sorting is. Drag an item onto another slot to correct it, or use its slot menu or the number keys, and the counts and bar follow.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-slot-sorter
```

It brings `async-button`, `avatar`, `button`, `card`, `dropdown-menu`, `hatched-bar`, `icon-chevron-down`, `icon-inbox`, `icon-zap`, `illustrations`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SlotSorter, type SlotSorterProps } from '@/blocks/app/slot-sorter'

export function SlotSorterView({ slots, items, value }: Pick<SlotSorterProps, 'slots' | 'items' | 'value'>) {
  return (
    <SlotSorter
      slots={slots}
      items={items}
      value={value}
      copy={{ title: 'Split inbox' }}
      onValueChange={(value) => {
        // your code
      }}
      onMove={(item, slot) => {
        // your code
      }}
      onBack={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `step`, `heading`, `splitLabel`, `total`, `splitAria`, `slotOff`, `sortingLive`, `correctHint`, `confidence`, `moveTo`, `row`, `dragInstructions`, `moved`, `throughput`, `back`, `turnOn`, `turningOn`, `turnedOn`.

### Seat plan

Seat picking on a plan: a seat map with tiers beside a live selection of seats, fees and total. A hold counts down and the seats go back on sale when it runs out. Concerts, flights and classrooms read the same way: tiers can carry a price or none, and the fee, the hold and the limit are props.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-seat-plan
```

It brings `alert`, `async-button`, `button`, `card`, `empty`, `icon-more-horizontal`, `icon-x`, `presence-list`, `seat-map`, `share-bar`, `skeleton`, `typography`, `use-announcer`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SeatPlan, type SeatPlanProps } from '@/blocks/app/seat-plan'

export function SeatPlanView({ rows, tiers, aisles }: Pick<SeatPlanProps, 'rows' | 'tiers' | 'aisles'>) {
  return (
    <SeatPlan
      rows={rows}
      tiers={tiers}
      aisles={aisles}
      copy={{ title: 'Nightjar' }}
      onConfirm={async (seats) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `currency`, `title`, `subtitle`, `more`, `map`, `footnote`, `selection`, `count`, `pickPrompt`, `remove`, `seat`, `subtotal`, `fees`, `total`, `held`, `holdHint`, `expired`, `holdAgain`, `confirm`, `clear`, `cleared`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Device controls

A set of rooms at a glance: a tile per room with temperature, humidity and a light switch, and a thermostat dial for the room you pick with Heat, Cool, Auto and Off modes and the day's schedule, in °C or °F. The demo is a home; stories show an office floor of meeting rooms and a greenhouse in °F.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-device-controls
```

It brings `alert`, `badge`, `button`, `card`, `dial`, `empty`, `icon-droplet`, `icon-flame`, `icon-lightbulb`, `icon-more-horizontal`, `icon-snowflake`, `segmented-control`, `segmented-meter`, `skeleton`, `switch`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DeviceControls, type DeviceControlsProps } from '@/blocks/app/device-controls'

export function DeviceControlsView({ rooms, unit, range, schedule }: Pick<DeviceControlsProps, 'rooms' | 'unit' | 'range' | 'schedule'>) {
  return (
    <DeviceControls
      rooms={rooms}
      unit={unit}
      range={range}
      schedule={schedule}
      copy={{ title: 'Home' }}
      onChange={(rooms) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `locale`, `title`, `subtitle`, `more`, `litCount`, `thermostat`, `mode`, `modes`, `captions`, `target`, `heating`, `cooling`, `holding`, `idle`, `schedule`, `now`, `hold`, `held`, `resume`, `rooms`, `temperature`, `humidity`, `lights`, `lightsIn`, `lamps`, `showRoom`, `allOff`, `energy`, `energyValue`, `loadingLabel`, `emptyTitle`, `emptyDescription`, `retry`.

### Procedure

A procedure with a share ring of what a yield amounts to, a yield stepper that rescales every quantity, a checklist of inputs, numbered steps with countdown timers, and an action that adds what is not ticked to a list. The demo is a recipe; stories show a lab protocol scaled by sample count and a cocktail batched by the drink in US ounces.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-procedure
```

It brings `alert`, `async-button`, `button`, `card`, `checkbox`, `counter`, `empty`, `icon-bookmark`, `icon-list-checks`, `icon-play`, `icon-rotate-ccw`, `number-input`, `segmented-control`, `share-ring`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Procedure, type ProcedureProps } from '@/blocks/app/procedure'

export function ProcedureView({ inputs, units, steps, facts }: Pick<ProcedureProps, 'inputs' | 'units' | 'steps' | 'facts'>) {
  return (
    <Procedure
      inputs={inputs}
      units={units}
      steps={steps}
      facts={facts}
      copy={{ title: 'Miso salmon bowl' }}
      onAddToList={async (items) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `save`, `unsave`, `facts`, `factsUnit`, `perUnit`, `whole`, `showing`, `yield`, `prep`, `cook`, `level`, `prepTime`, `cookTime`, `levelValue`, `minutes`, `inputs`, `gathered`, `steps`, `step`, `startTimer`, `pauseTimer`, `resetTimer`, `timerDone`, `done`, `status`, `totalPerUnit`, `totalWhole`, `addToList`, `adding`, `added`, `addedAnnounce`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Sound settings

Sound preferences: whether the app makes sounds, how loud, which pack and which events. Nothing plays on its own; Play on a row and the sound check are the only ways to hear anything.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-sound-settings
```

It brings `alert`, `button`, `card`, `field`, `icon-audio-lines`, `icon-bell`, `icon-check-circle`, `icon-circle-alert`, `icon-mouse-pointer`, `icon-refresh`, `icon-toggle`, `icon-volume`, `radio-group`, `slider`, `switch`, `use-controllable-state`, `waveform-scrubber`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SoundSettings, type SoundSettingsProps } from '@/blocks/app/sound-settings'

export function SoundSettingsView({ value }: Pick<SoundSettingsProps, 'value'>) {
  return (
    <SoundSettings
      value={value}
      copy={{ title: 'Sound' }}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `SoundSettingsValue` |  | The settings (controlled). Keep them, and pass them to your YoujProvider. |
| `defaultValue` | `SoundSettingsValue` | `on, Glass, half volume, every event` | The settings it opens with (uncontrolled). |
| `onValueChange` | `(value: SoundSettingsValue) => void` |  |  |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another settings page: a `section` named by an `h2`, without the page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (672px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` | `1, or 2 when embedded` | The page title's level; the cards' titles sit one below it. |
| `copy` | `Partial<SoundSettingsCopy>` |  | Any of the page's strings, to rewrite or translate. |

**Strings:** `copy` takes `title`, `description`, `reset`, `interfaceSounds`, `offDescription`, `onDescription`, `volume`, `volumeValue`, `keepReduced`, `keepReducedDetail`, `quietTitle`, `quietBody`, `packTitle`, `packDescription`, `eventsTitle`, `eventsDescription`, `soundCheck`, `play`, `playEvent`, `silent`, `packs`, `events`.

### Effects inspector

A design tool's effects panel with the layer it styles beside it: a drop or inner shadow, a stroke, a fill and a layer blur (uniform or progressive), each a collapsible panel with a checkbox, an eye and a trash. A button and the CSS it comes to change as you edit. Drag a field's handle to scrub it, with Shift for ×10 and Alt for ×0.1, or type and use the arrow keys.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-effects-inspector
```

It brings `button`, `card`, `color-opacity-field`, `dropdown-menu`, `icon-grip`, `icon-plus`, `icon-ruler`, `icon-sun`, `inspector-panel`, `scrub-number-field`, `segmented-control`, `select`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { EffectsInspector, type EffectsInspectorProps } from '@/blocks/app/effects-inspector'

export function EffectsInspectorView({ value }: Pick<EffectsInspectorProps, 'value'>) {
  return (
    <EffectsInspector
      value={value}
      copy={{ title: 'Effects' }}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `EffectsValue` |  | The effects (controlled). |
| `defaultValue` | `EffectsValue` | `a drop shadow, an inside stroke and a blue fill, with the blur off` | The effects it opens with (uncontrolled). |
| `onValueChange` | `(value: EffectsValue) => void` |  |  |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another page: a `section` named by an `h2`, without the page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (896px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` | `1, or 2 when embedded` | The title's level. |
| `copy` | `Partial<EffectsInspectorCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `title`, `description`, `add`, `noneToAdd`, `preview`, `button`, `css`, `noStyles`, `shadow`, `shadowTypes`, `stroke`, `fill`, `blur`, `position`, `x`, `y`, `shadowBlur`, `spread`, `color`, `strokePosition`, `strokePositions`, `weight`, `blurType`, `blurTypes`, `amount`, `range`, `start`, `end`.

### Cookie consent

A cookie banner that asks once. Accept all and Reject all save and the card sinks away, leaving a small button to reopen it; Customize opens a dialog with a switch per category and a table of its cookies.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cookie-consent
```

It brings `async-button`, `badge`, `button`, `collapse`, `dialog`, `field`, `icon-cookie`, `icon-shield-check`, `switch`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CookieConsent, type CookieConsentProps } from '@/blocks/marketing/cookie-consent'

export function CookieConsentView({ categories }: Pick<CookieConsentProps, 'categories'>) {
  return (
    <CookieConsent
      categories={categories}
      copy={{ title: 'A few cookies, if that’s all right' }}
      linkComponent={Link}
      onValueChange={(choices) => {
        // your code
      }}
      onSave={async (choices) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the consent card, corner button and dialog. Default: none, so they inherit the app's (YoujProvider or a ThemeScope around it). |
| `defaultOpen` | `'banner' \| 'preferences'` | `'banner'` | What shows first while no choice is made: the card, or the preferences dialog. |
| `categories` | `CookieConsentCategory[]` | `the demo's necessary, analytics, marketing and preferences` | The cookie categories, in order. |
| `value` | `CookieConsentChoices \| null` |  | The saved choice, to control it; `null` while the visitor hasn't chosen. |
| `defaultValue` | `CookieConsentChoices \| null` | `null` | The choice already made (e.g. read from a cookie), when uncontrolled. |
| `onValueChange` | `(choices: CookieConsentChoices) => void` |  | Called once a choice is saved. |
| `onSave` | `(choices: CookieConsentChoices) => Promise<unknown> \| unknown` |  | Stores the choice; resolve when saved, reject to keep the card and show the error's message. Default: a short demo wait. |
| `policyHref` | `string` | `'#policy'` | Where the cookie policy link goes. |
| `children` | `ReactNode` |  | The page under the consent, rendered as is beside it (outside its theme). Default: a quiet demo bakery page. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | The card's heading level. |
| `copy` | `Partial<CookieConsentCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `linkComponent` | `LinkComponent` | `'a'` | Renders the policy link, e.g. Next.js `Link`. |

**Strings:** `copy` takes `title`, `description`, `policyLink`, `policySuffix`, `customize`, `rejectAll`, `acceptAll`, `allowAll`, `saveChoices`, `saved`, `preferences`, `dialogDescription`, `alwaysOn`, `toggleCookies`, `cookieColumn`, `purposeColumn`, `expiresColumn`, `footnote`, `announceNone`, `announceAll`, `announceSaved`, `saveFailed`.

### Cart drawer

The cart as a floating panel from the inline end, as tall as its lines: a photo, quantity stepper and remove per line, the road to free shipping in the header, and shipping, subtotal and checkout in the footer. An empty cart offers a way back to the shop. Use it as your cart panel.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-cart-drawer
```

It brings `async-button`, `badge`, `button`, `commerce-product-card`, `counter`, `empty`, `icon-arrow-right`, `icon-shopping-bag`, `icon-truck`, `number-input`, `presence-list`, `progress`, `sheet`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CartDrawer, type CartDrawerProps } from '@/blocks/commerce/cart-drawer'

export function CartDrawerView({ lines }: Pick<CartDrawerProps, 'lines'>) {
  return (
    <CartDrawer
      lines={lines}
      copy={{ title: 'Your cart' }}
      linkComponent={Link}
      onLinesChange={(lines) => {
        // your code
      }}
      onQuantityChange={(line, quantity) => {
        // your code
      }}
      onRemove={(line) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `CartLine[]` |  | The cart, controlled: pair it with `onLinesChange`. |
| `defaultLines` | `CartLine[]` | `the demo's three lines` | The cart when the drawer owns it. |
| `onLinesChange` | `(lines: CartLine[]) => void` |  | Hears the whole cart after every quantity change or removal. |
| `onQuantityChange` | `(line: CartLine, quantity: number) => void` |  | Hears a line's new quantity. |
| `onRemove` | `(line: CartLine) => void` |  | Hears a line being removed. |
| `open` | `boolean` |  | Whether the drawer is open, controlled: pair it with `onOpenChange`. |
| `defaultOpen` | `boolean` | `false` | Whether it starts open when the drawer owns it. |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `onCheckout` | `(lines: CartLine[]) => Promise<unknown>` | `a short demo wait` | Resolve once checkout is ready to take over; reject to shake the button. |
| `currency` | `string` | `'USD'` | An ISO 4217 code. |
| `locale` | `string` | `'en-US'` | A BCP 47 locale for every amount. |
| `freeShippingAt` | `number \| null` | `150` | The subtotal that ships free, in `currency`; `null` hides the bar. |
| `maxQuantity` | `number` | `10` | The most of one line a shopper can take. |
| `shopHref` | `string` | `'#shop'` | Where "Continue shopping" goes from an empty cart. |
| `linkComponent` | `ElementType` | `'a'` | Renders the "Continue shopping" link, e.g. Next.js `Link`. |
| `copy` | `Partial<CartDrawerCopy>` |  | Any of the drawer's strings, to rewrite or translate. |
| `empty` | `ReactNode` |  | Replaces the empty cart's message. |
| `className` | `string` |  | Classes for the drawer's panel. |
| `data-yj-density` | `'compact' \| 'roomy'` |  | The layout density (ui.css) of the trigger and the drawer. Default: the page's (YoujProvider's or ThemeScope's `density`). |

**Strings:** `copy` takes `trigger`, `title`, `count`, `nothingYet`, `awayBefore`, `awayAfter`, `freeShipping`, `list`, `quantity`, `remove`, `removeLabel`, `emptyTitle`, `emptyDescription`, `continueShopping`, `subtotal`, `shipping`, `shippingFree`, `shippingLater`, `taxesNote`, `checkout`, `checkoutPending`, `checkoutSuccess`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every control sits in the kit's Field with its label, description and error, so it's named and described without extra wiring, and `aria-invalid` marks a field with a problem. Errors appear under their fields as soon as a field is left, and they're read out. Saving, sending or continuing checks every field and moves focus to the first problem. The application also gathers a step's problems in a summary at the top, which takes focus and links to each field.

The settings save bar announces the number of changes. Each Reset says what it restores, and focus goes back to the control afterwards. ⌘S and Ctrl+S save, and when a link is held, the reason is read out and focus moves to Save. The payment address lookup follows the WAI-ARIA combobox pattern: arrow keys move through the matches while focus stays in the field, and the number of matches is read out. The support request's help articles open in a new tab and say so.

Chip filters has a labelled search field, the result count is spoken once it settles, and the checklist is a labelled group with a tri-state box and a hidden summary of the range. Editing chips and moving controls stay in sync both ways.

Permission matrix lists its roles as tabs (the arrow keys move between them) and names each level picker for its area and role ("Secrets access for Engineer"); a role's tab says how many unsaved changes it holds, and the footer's count is a polite live region. The grid view is a keyboard matrix: the arrow keys move between cells, Space steps a level, and a bar for bulk changes appears for the selected rows and columns. Review opens a dialog with the diff. The owner role is locked. The stories show other worlds, with their own names and words.

Setup stepper is a Wizard with a Stepper. The config preview is a labelled region, and the option pills are a labelled group of toggles with `aria-pressed`.

Split allocation names each row's category, amount and percent; the allocation bar is decorative, and the status line (a live region) says in words how much is allocated, left or over, and is the reason Save is unavailable. The split can be typed, added to and removed from entirely by keyboard.

Slot sorter is a `section` named by its title. Every item has a slot button that names the item, its detail, the slot and how sure the sorting is, opens a menu of the slots and takes the number keys 1 to 4, so dragging is never the only way; a correction is announced with the new counts, the bar and its legend are one labelled image with the counts in text, and the picture is decorative. A slot that is off is dimmed in the menu and takes no item.

Seat plan is one ARIA grid with one tab stop: arrow keys move between seats and rows, Home and End jump to a row's ends, Ctrl+Home and Ctrl+End to the first and last seat, and Space or Enter picks or releases. Each seat is named with row, number, price and availability. The selection's remove buttons are named per seat, and the hold is `role="timer"` with live announcements off.

In Device controls each room tile is a button with `aria-pressed` and a name, and its lights are a switch labelled for the room. The thermostat is a Dial with a label and a hidden description; drag the knob or use the arrow keys. The mode switch is a labelled segmented control and the schedule marks the current slot with `aria-current="time"`.

Procedure's share ring is an image whose label sums up the total and each part. The switch between one yield and all of it is a labelled segmented control, steps carry a hidden step number, and each timer is a toggle button with `aria-pressed` and a label that says whether it starts, pauses or resets and for how long. Save is a pressed toggle.

Sound settings has a labelled master switch and volume slider, and a Play button named for each event. With sounds off the pack, volume and rows go inert. Under reduced motion the page says why sounds are quiet, and previews are silent without a provider.

Effects inspector is a stack of panels, each a named section with an enable checkbox, an eye that says Hide or Show, and Remove. Every field is keyboard operable: the number fields are spinbuttons (arrow keys, with Shift and Alt for the pace, PageUp and PageDown, Home and End), the hex fields commit on Enter, and the shadow's kind and the blur's type are a menu and a segmented control. The preview is described as an image, and the CSS beside it is plain text. Under reduced motion the panels fold at once.

Cookie consent opens its preferences in a dialog that traps focus and closes with Escape. Each category is a switch, Necessary stays on, each cookie table has a visually hidden header row, and saving is announced in a status region.

The cart is a Sheet, so it traps focus and closes with Escape. Its trigger is named with the item count, and each line has a remove button and a quantity field named for its product, in a labelled list.

Under reduced motion, steps swap in place, the save bar appears without rising or shaking, and fields appear and disappear instantly. Colors and messages still show every state.

Under reduced motion pulses and pings stop and everything else changes in place.

Under reduced motion numbers and the ring are drawn in place; the timers still count.

Under reduced motion rows, rings and steps change in place, the chosen plan is simply built and the bar jumps to its new split.

---

# Media

> Files, pictures and sound: uploads, libraries, editors, players, arrangers and product pictures.

Source: https://www.youj.dev/docs/blocks/media

## Blocks

### Drop zone

A drop zone that takes files every way people have them. It wakes as soon as files are dragged anywhere over the page, says how many are coming and whether they're accepted, and turns to danger when none would be; a drop that misses it never opens the file in the tab. Folders drop or pick whole, read in batches with their paths kept and system files left out, and ⌘V pastes a screenshot under the moment's name. Every refusal has its own reason: the type, the size, the count, the total, a duplicate, an image's dimensions or your own check. Files show a real thumbnail drawn small, a video's frame and running time, then upload three at a time with progress and Retry.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add media-dropzone
```

It brings `alert`, `button`, `collapse`, `icon-check`, `icon-file`, `icon-file-archive`, `icon-file-audio`, `icon-file-image`, `icon-file-text`, `icon-file-video`, `icon-folder-open`, `icon-play`, `icon-refresh`, `icon-x`, `presence-list`, `progress`, `spinner`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MediaDropzone } from '@/blocks/media/dropzone'

export function MediaDropzoneView() {
  return (
    <MediaDropzone
      copy={{ title: 'Upload files' }}
      onFilesChange={(files) => {
        // your code
      }}
      onUpload={async (file, context) => {
        // await your API here; the block shows progress until it settles
      }}
      onRemove={async (file) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2`, and no page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (672px at 100% scale). |
| `copy` | `Partial<MediaDropzoneCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Writes sizes and running times in this locale (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `defaultFiles` | `MediaDropzoneFile[]` | `four demo files part-way through` | The files it starts with, usually the ones already stored (`status: 'done'`). |
| `onFilesChange` | `(files: MediaDropzoneFile[]) => void` |  | Every change to the list: added, uploading, uploaded (with what `onUpload` resolved), failed, removed. |
| `accept` | `string` | `'image/jpeg,image/png,image/webp,video/mp4,video/quicktime,application/pdf'` | The types it takes, as an input's `accept`: extensions (`.pdf`), MIME types (`image/png`) or families (`image/*`). |
| `maxSize` | `number` | `50 MB` | The largest file, in bytes. |
| `minSize` | `number` | `1` | The smallest file, in bytes. |
| `maxFiles` | `number` | `20` | How many files it holds. |
| `maxTotalSize` | `number` | `200 MB` | All the files together, in bytes. |
| `minDimensions` | `{ width: number; height: number }` |  | An image's smallest size in pixels: `{ width: 1200, height: 1200 }` for product photos. Default: any. |
| `validate` | `(file: File) => string \| null \| undefined \| Promise<string \| null \| undefined>` |  | Your own rule: return a reason to refuse the file, or nothing to take it. May be async (a name check on your server). |
| `folders` | `boolean` | `true` | Take whole folders, dropped or picked. |
| `paste` | `boolean` | `true` | Take files pasted into the block, or onto the page while nothing else has focus. |
| `disabled` | `boolean` | `false` |  |
| `onUpload` | `(file: File, context: MediaDropzoneUploadContext) => Promise<unknown> \| unknown` |  | Uploads one file: report progress (0–100) and resolve when it's stored, with anything you'll want back (a URL, a key); reject to show why. Default: a simulated upload. |
| `onRemove` | `(file: MediaDropzoneFile) => Promise<unknown> \| unknown` |  | Removes a stored file (from your storage). Awaited, the row dimmed meanwhile; reject to keep it and say why. Without it, removing only takes it off the list. |
| `onReject` | `(rejections: MediaDropzoneRejection[]) => void` |  | The files the rules turned away, each with its reason. |
| `footer` | `ReactNode` |  | Under the list, beside the totals: a Continue button, a note. |
| `classNames` | `{ list?: string }` |  | Classes for its parts: `list` is the region the files scroll in (its height, 256px at 100%, holds the card's size). |

**Strings:** `copy` takes `title`, `description`, `drop`, `browse`, `pasteHint`, `dropReady`, `dropCount`, `dropSome`, `dropNone`, `onlyTypes`, `dropRelease`, `reading`, `full`, `fullHint`, `chooseFolder`, `types`, `typeGroup`, `atLeast`, `eachUpTo`, `inAll`, `refusedTitle`, `refusedMore`, `dismiss`, `skipped`, `notAccepted`, `tooLarge`, `empty`, `duplicate`, `tooMany`, `overBudget`, `tooSmall`, `unreadable`, `pastedName`, `files`, `noFiles`, `checking`, `queued`, `uploaded`, `failed`, `uploadFailed`, `removing`, `removeFailed`, `retry`, `remove`, `cancel`, `uploading`, `dimensions`, `summary`, `ofBudget`, `budget`, `added`, `refused`, `uploadedOne`, `failedOne`, `removed`, `locale`.

### Upload tray

Uploads that keep going while people keep working. Wrap a page in it and files dropped anywhere upload under a veil that names where they go; any button inside sends files with `useUploadTray().add`. A few move at once, each pauses and resumes from the bytes already stored (your `onUpload` gets the offset and an AbortSignal, as tus and S3 multipart need), and a failure retries itself with a countdown. Going offline holds everything and says so, and coming back resumes it. The header sums it up with a smoothed speed and an honest time left, folds to a hairline of progress, and asks before closing on unfinished uploads.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add media-upload-tray
```

It brings `alert-dialog`, `badge`, `button`, `collapse`, `icon-alert-triangle`, `icon-check`, `icon-chevron-down`, `icon-cloud-upload`, `icon-file`, `icon-file-archive`, `icon-file-audio`, `icon-file-image`, `icon-file-text`, `icon-file-video`, `icon-play`, `icon-refresh`, `icon-wifi-off`, `icon-x`, `presence-list`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { UploadTray, type UploadTrayProps } from '@/blocks/media/upload-tray'

export function UploadTrayView({ retryDelays }: Pick<UploadTrayProps, 'retryDelays'>) {
  return (
    <UploadTray
      retryDelays={retryDelays}
      copy={{ region: 'Uploads' }}
      onItemsChange={(items) => {
        // your code
      }}
      onExpandedChange={(expanded) => {
        // your code
      }}
      onUpload={async (file, context) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block (and the page in it) in this theme. Default: the theme around it. |
| `copy` | `Partial<UploadTrayCopy>` |  | Any of the block's strings, to rewrite or translate; `destination` names where files go. |
| `locale` | `string` |  | Writes sizes, speeds and times in this locale (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `children` | `ReactNode` |  | The page under the tray. Files dropped anywhere on it upload, and anything inside can add files with `useUploadTray()`. |
| `defaultItems` | `UploadTrayItem[]` |  | The queue it starts with. Items with a `file` upload; items without one are simulated. Default: six demo files mid-flight. |
| `onItemsChange` | `(items: UploadTrayItem[]) => void` |  | Every change to the queue: added, moving, paused, done (with what `onUpload` resolved), failed, removed. |
| `concurrency` | `number` | `3` | How many files move at once. |
| `retryDelays` | `number[]` | `2, 5 and 10 seconds` | The waits before each automatic retry of a failed upload, in milliseconds; as many retries as waits, `[]` for none. |
| `dropOnPage` | `boolean` | `true` | Files dropped anywhere on the page upload. |
| `expanded` | `boolean` |  | Whether the list is open (controlled): pair it with `onExpandedChange`. |
| `defaultExpanded` | `boolean` | `true` | Whether the list starts open, when the block owns it. |
| `onExpandedChange` | `(expanded: boolean) => void` |  |  |
| `onUpload` | `(file: File, context: UploadTrayContext) => Promise<unknown> \| unknown` |  | Uploads one file: resume from `offset`, report the bytes stored through `onProgress`, stop on `signal`, and resolve with anything you'll want back (a URL, a key); reject to retry or fail with your message. Default: a simulated upload. |
| `onComplete` | `(items: UploadTrayItem[]) => void` |  | When the queue comes to rest, with every item as it ended. |
| `demoMarker` | `boolean` | `true` | The dashed Demo data badge in the tray's header while it shows the demo's files. |
| `classNames` | `{ tray?: string; list?: string }` |  | Classes for its parts: `tray` is the floating panel (its place and width), `list` the region the queue scrolls in (its height, 320px at 100%, holds the tray's size). |

**Strings:** `copy` takes `region`, `destination`, `uploading`, `paused`, `offline`, `complete`, `someFailed`, `rate`, `timeLeft`, `fewSeconds`, `calculating`, `doneIn`, `offlineHint`, `pauseAll`, `resumeAll`, `close`, `offlineBanner`, `of`, `queued`, `uploadedRow`, `pausedRow`, `waitingRow`, `retryingIn`, `failed`, `uploadFailed`, `connectionReset`, `pause`, `resume`, `cancel`, `retry`, `open`, `remove`, `progressText`, `settled`, `clearDone`, `confirmTitle`, `confirmBody`, `keep`, `confirmCancel`, `dropTitle`, `dropTo`, `dropCount`, `demoData`, `started`, `uploadedOne`, `failedOne`, `allDone`, `wentOffline`, `backOnline`, `locale`.

### Image editor

An image field that shows exactly how the picture will look everywhere it appears. The photo moves under a fixed frame: drag it, pinch or scroll to zoom about the pointer, turn it a quarter, straighten it by the degree or flip it, and at any angle it still covers the frame. The focal point marks what matters, and the previews beside it are the real framing at each size the image is shown, cropped around the focal point as far as the edges allow. Save draws the result on a canvas and hands over the file with its region in the source's pixels and the focal point, ready for an image CDN. It also comes as a 3:1 cover and a round avatar.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add media-image-editor
```

It brings `async-button`, `button`, `field`, `icon-flip-horizontal`, `icon-flip-vertical`, `icon-image-plus`, `icon-rotate-ccw`, `icon-rotate-cw`, `icon-zoom-in`, `icon-zoom-out`, `segmented-control`, `slider`, `spinner`, `textarea`, `tooltip`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ImageEditor, type ImageEditorProps } from '@/blocks/media/image-editor'

export function ImageEditorView({ aspects, previews }: Pick<ImageEditorProps, 'aspects' | 'previews'>) {
  return (
    <ImageEditor
      aspects={aspects}
      previews={previews}
      copy={{ title: 'Edit image' }}
      onEditChange={(edit) => {
        // your code
      }}
      onSave={async (result) => {
        // await your API here; the block shows progress until it settles
      }}
      onRemove={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `avatarTitle`, `avatarDescription`, `coverTitle`, `coverDescription`, `replace`, `remove`, `stage`, `stageRole`, `stageKeys`, `hint`, `focal`, `focalKeys`, `focalAt`, `crop`, `straighten`, `degrees`, `zoom`, `zoomIn`, `zoomOut`, `rotateLeft`, `rotateRight`, `flipHorizontal`, `flipVertical`, `reset`, `previews`, `alt`, `altHint`, `altCount`, `output`, `save`, `saving`, `saved`, `saveFailed`, `emptyTitle`, `emptyHint`, `emptyRules`, `minRule`, `loading`, `broken`, `chooseAnother`, `notAnImage`, `tooLarge`, `tooSmall`, `turned`, `flipped`, `removed`, `locale`.

### Media library

A media picker that's as quick from the keyboard as with a mouse. Search names and descriptions, narrow by type, open a folder, switch between grid and list. Picking keeps its order, the first being the cover, and stops at a maximum with a word on why. Arrows move through the grid in two dimensions, Shift picks a run and ⌘A picks everything shown. Enter opens a lightbox that grows from its tile and picks from there. Drop files on the grid to upload into the open folder; they fill as they go and are picked as they land.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add media-library
```

It brings `alert`, `async-button`, `breadcrumb`, `button`, `collapse`, `dialog`, `empty`, `icon-check`, `icon-chevron-left`, `icon-chevron-right`, `icon-folder`, `icon-image`, `icon-layout-grid`, `icon-layout-list`, `icon-maximize`, `icon-play`, `icon-search`, `icon-search-x`, `icon-upload`, `icon-x`, `input-group`, `presence-list`, `segmented-control`, `select`, `skeleton`, `toggle-group`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MediaLibrary, type MediaLibraryProps } from '@/blocks/media/library'

export function MediaLibraryView({ assets, folders, selection }: Pick<MediaLibraryProps, 'assets' | 'folders' | 'selection'>) {
  return (
    <MediaLibrary
      assets={assets}
      folders={folders}
      selection={selection}
      copy={{ title: 'Choose media' }}
      onSelectionChange={(ids) => {
        // your code
      }}
      onViewChange={(view) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `upload`, `search`, `searchLabel`, `filter`, `filters`, `sort`, `sorts`, `view`, `grid`, `list`, `root`, `folders`, `inFolder`, `media`, `dimensions`, `open`, `selectedAs`, `uploading`, `selected`, `clear`, `cancel`, `insert`, `inserting`, `inserted`, `insertFailed`, `full`, `previous`, `next`, `position`, `select`, `deselect`, `type`, `dimensionsLabel`, `length`, `size`, `added`, `folder`, `alt`, `noAlt`, `noPreview`, `kinds`, `emptyTitle`, `emptyBody`, `noResults`, `noResultsBody`, `clearSearch`, `loading`, `errorTitle`, `retry`, `dropHere`, `uploadFailed`, `results`, `selectedOne`, `deselectedOne`, `cleared`, `uploadedOne`, `failedOne`, `locale`.

### Attachments

A reply box that takes files while you write: attach, paste a screenshot or drop files, and each uploads at once with a ring as it goes. Arrange them by dragging, with a caret showing where one lands, or with Alt or Option and the arrows. Send waits for uploads still running and says how many it's waiting for, then sends the text and the files in their order; a failed upload stops it with focus on the file, which retries on a press.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add media-attachments
```

It brings `async-button`, `button`, `dialog`, `icon-alert-triangle`, `icon-external-link`, `icon-file`, `icon-file-archive`, `icon-file-audio`, `icon-file-text`, `icon-file-video`, `icon-paperclip`, `icon-refresh`, `icon-x`, `input-group`, `kbd`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { AttachmentComposer } from '@/blocks/media/attachments'

export function AttachmentComposerView() {
  return (
    <AttachmentComposer
      copy={{ title: 'Reply to Priya Raman' }}
      onValueChange={(text) => {
        // your code
      }}
      onAttachmentsChange={(files) => {
        // your code
      }}
      onUpload={async (file, context) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `message`, `placeholder`, `attach`, `attachments`, `dropHere`, `noFiles`, `uploading`, `failed`, `uploadFailed`, `remove`, `retry`, `retryShort`, `keys`, `count`, `send`, `sending`, `sent`, `sendFailed`, `waiting`, `blocked`, `shortcut`, `notAccepted`, `tooLarge`, `tooMany`, `pastedName`, `open`, `close`, `attached`, `removed`, `moved`, `uploadedOne`, `failedOne`, `sentMessage`, `locale`.

### Track arranger

A project in tracks: a song idea, a podcast edit or a video timeline. Drag clips to move or trim them with snapping, solo or mute each track, and open the selected clip in an inspector with its start, end and gain. Play runs the clock and playhead.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-track-arranger
```

It brings `alert`, `async-button`, `button`, `card`, `dropdown-menu`, `empty`, `field`, `icon-more-horizontal`, `icon-play`, `icon-ruler`, `icon-skip-back`, `number-input`, `skeleton`, `slider`, `toggle`, `track-timeline`, `typography`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { TrackArranger, type TrackArrangerProps } from '@/blocks/app/track-arranger'

export function TrackArrangerView({ project, tracks, clips }: Pick<TrackArrangerProps, 'project' | 'tracks' | 'clips'>) {
  return (
    <TrackArranger
      project={project}
      tracks={tracks}
      clips={clips}
      copy={{ more: 'More options' }}
      onExport={async (clips, tracks) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `subtitle`, `more`, `duplicate`, `rename`, `timeline`, `play`, `pause`, `rewind`, `snap`, `inspector`, `none`, `onTrack`, `start`, `end`, `gain`, `length`, `seconds`, `decibels`, `saved`, `export`, `exporting`, `exported`, `announceExported`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Product

An editorial storefront card where the photo is the card: a 4:5 studio shot with the name, price, category and rating under it. Hover or focus turns the product to its other side (or eases the shot closer), the swatches preview and pick a colorway with its own photo, and quick add goes straight to the cart or opens sizes first. Use it for a shop grid; pass your own photos per product or per colorway.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-product-card
```

It brings `async-button`, `badge`, `button`, `commerce-product-render`, `icon-shopping-cart`, `icon-star`, `icon-x`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ProductCard, type ProductCardProps } from '@/blocks/commerce/product-card'

export function ProductCardView({ product }: Pick<ProductCardProps, 'product'>) {
  return (
    <ProductCard
      product={product}
      copy={{ color: 'Color' }}
      linkComponent={Link}
      onAdd={async (product, choice) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `product` | `Product` | `the first photographed product` | The product: name, price, colors, sizes, and its photos (`image`, `angle`). |
| `onAdd` | `(product: Product, choice: { color: string; size?: string }) => Promise<unknown>` | `a short wait` | Resolve once the product is in the cart; reject to shake the button. |
| `copy` | `Partial<ProductCardCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `currency` | `string` |  | An ISO 4217 code. Default: the format around it, else 'USD'. |
| `locale` | `string` |  | A BCP 47 locale for prices and counts. Default: the format around it, else the app's locale (YoujProvider), else en-US. |
| `linkComponent` | `ElementType` | `'a'` | Renders the product link, e.g. Next.js `Link`. |
| `actions` | `ReactNode` |  | Controls over the photo's top-end corner (a save heart, a quick view), above the product link; they can reveal themselves with the card's `group-hover/product` and `group-focus-within/product`. |

**Strings:** `copy` takes `color`, `was`, `now`, `pickSize`, `closeSizes`, `sizesFor`, `soldOut`, `addSize`, `chooseSize`, `sizeLabel`, `addToCart`, `quickAdd`, `adding`, `added`, `addedSize`, `addError`, `rated`, `from`, `off`.

### Exploded view

A spec card built around an exploded drawing of one device. Switch between assembled and exploded, and point at a spec figure to light the part it describes. The drawing is a fixed five-layer illustration; the part names and the spec sheet are your data. Use it for hardware product pages.

**Partly demo.** `copy`, `parts`, `specs` and `onOrder` are props; the five-layer drawing itself is fixed.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-exploded-view
```

It brings `async-button`, `button`, `card`, `grid-backdrops`, `icon-file-text`, `icon-more-horizontal`, `iso-scene`, `iso-shapes`, `iso-stack`, `segmented-control`, `typography`, `use-announcer`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ExplodedView, type ExplodedViewProps } from '@/blocks/app/exploded-view'

export function ExplodedViewView({ parts, specs, focusPart }: Pick<ExplodedViewProps, 'parts' | 'specs' | 'focusPart'>) {
  return (
    <ExplodedView
      parts={parts}
      specs={specs}
      focusPart={focusPart}
      copy={{ title: 'Relay R4' }}
      onOrder={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `status`, `more`, `drawing`, `view`, `assembled`, `exploded`, `showing`, `headline`, `body`, `specs`, `lights`, `statusLine`, `datasheet`, `order`, `ordering`, `ordered`, `orderedAnnounce`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Connecting your storage

Nothing here touches the network. Every upload goes through an `onUpload` you wire to your own storage, and without one a simulated upload stands in (it warns once in development). Each block awaits it, shows its progress, stops it through the `AbortSignal` when a file is removed or paused, and keeps whatever it resolves with (a URL, a key) on the file.

The drop zone, the media library and the attachments report progress in percent. With a presigned URL (S3, R2, Vercel Blob), an `XMLHttpRequest` reports it as the bytes go:

```tsx
async function onUpload(file: File, { signal, onProgress }: { signal: AbortSignal; onProgress: (percent: number) => void }) {
  const { url, key } = await fetch('/api/uploads', { method: 'POST', body: JSON.stringify({ name: file.name, type: file.type }) }).then((r) => r.json())
  await new Promise<void>((resolve, reject) => {
    const xhr = new XMLHttpRequest()
    xhr.upload.onprogress = (event) => onProgress((event.loaded / event.total) * 100)
    xhr.onload = () => (xhr.status < 300 ? resolve() : reject(new Error(`Upload failed (${xhr.status})`)))
    xhr.onerror = () => reject(new Error('The connection dropped.'))
    xhr.onabort = () => reject(new Error('Canceled'))
    signal.addEventListener('abort', () => xhr.abort())
    xhr.open('PUT', url)
    xhr.send(file)
  })
  return { key }
}
```

The upload tray reports bytes and passes the `offset` already stored, so a resumable protocol carries on from there after a pause or a lost connection: tus picks it up from its upload URL, S3 multipart from its last part. An uploader that can't resume starts over and reports from 0, and the tray follows. Rejecting retries after each of `retryDelays`, then shows your message with Retry.

### Accessibility

Every drop target is also a button, or sits beside one, so nothing needs a mouse: the drop zone is the picker's button and describes its rules, the image editor's empty stage is a button, and the library and the composer have Upload and Attach. Pasting works wherever focus is in the block. Refusals are listed with one reason per file, tied to the zone or the field with `aria-describedby`; outcomes (added, uploaded, failed, all done, removed, moved) are announced politely through one live region per block, and failures assertively. Progress isn't read out percent by percent: each file is a named progress bar with its bytes and time left as its value text.

The upload tray's header is a disclosure button whose name is its summary; each row's ring is its Pause, Resume or Retry, named for the file, and closing mid-upload is an alert dialog. The image editor's stage is a labelled group that describes its keys (arrows move, + and − zoom, [ and ] straighten, R turns, H and V flip, 0 resets); the focal point is a control of its own whose position is read out, and the sliders speak in degrees and percent. The media library is one multi-select listbox with a single tab stop: arrows move in two dimensions, Space picks, Shift picks a run, ⌘A or Ctrl+A picks all and Escape clears, and each option's name includes its place in the selection. Its lightbox is a dialog that steps with the arrow keys and hands focus back to the file's tile. The composer's attachments are buttons named with their size and state; Alt or Option with an arrow moves one and says where it went, Delete removes it and focus moves on, and ⌘↵ or Ctrl+↵ sends.

The Chapter player's waveform is a slider underneath: the arrow keys step, Page Up and Page Down step ten times as far, and the chapter title is announced politely as it changes. The play button is named and carries `aria-pressed`, the skip buttons say how far they jump, the speed fader is labelled, the clip toggle is pressed while a clip is open, and the chapter now playing is marked `aria-current`.

Both players are simulated by a clock; wire them to real audio and keep these labels. Under reduced motion the wave is drawn in place and level strips jump to each reading.

In Track arranger every clip is a tab stop: the arrow keys move it, Shift moves it ten times as far, and its trim edges are sliders. Play and rewind are named, and the clock is `role="timer"` with live announcements off. The gain fader is labelled.

The product card is an `article` named by its product name (an `h2`), and its photos are decorative (`alt=""`); a studio shot becomes an image only when you pass `label`, and its fallback keeps that name if the photo fails. The colorway swatches are a radio group: each is named by its color, and the arrow keys pick one. Quick add is a button named for the product, and a product with sizes opens a labelled group over the photo Escape closes it and focus returns. A struck-through price is read as was and now.

The device spec card keeps its drawing `aria-hidden`; the Assembled / Exploded switch and the spec figures are labelled groups, and focusing a figure lights its part the same way hovering does.

Under reduced motion the turn, the push-in, the photo fades and crossfades, the sheet and every cart change happen at once.

Under reduced motion the zone and tray change in place, rows and chips appear and leave at once, progress jumps, the editor's changes land without gliding or springing back, and the lightbox opens without growing. Colors and messages still show every state.

---

# Meters & limits

> How much is used and how much is left: limits, allowances, dials, capacity, stock, envelopes, streaks and goals.

Source: https://www.youj.dev/docs/blocks/meters-and-limits

## Blocks

### Limit meters

How much of an allowance is used, live: pick what is limited (your own kinds, such as API keys and endpoints, phone lines or library cards) and watch its bucket drain as it is spent and refill at the limit's pace. Send a burst to see it refuse, or raise the limit.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-limit-meters
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `empty`, `icon-more-horizontal`, `refill-meter`, `select`, `skeleton`, `sparkline`, `typography`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { LimitMeters, type LimitMetersProps } from '@/blocks/app/limit-meters'

export function LimitMetersView({ limiters, kinds }: Pick<LimitMetersProps, 'limiters' | 'kinds'>) {
  return (
    <LimitMeters
      limiters={limiters}
      kinds={kinds}
      copy={{ title: 'Rate limits' }}
      onRaiseLimit={async (limiter) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `scope`, `more`, `viewLogs`, `copyId`, `refill`, `limiter`, `throughput`, `perMinute`, `status`, `tokens`, `throttledCode`, `throttledWindow`, `throttledChart`, `limit`, `capacity`, `accepted`, `perMinuteUnit`, `tokensUnit`, `policy`, `sendBurst`, `raise`, `raising`, `raised`, `refilled`, `demoData`, `loading`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Limit tracker

What has been used of a limit, on a ruler from zero, with a rule's line and the pace beside it, a tile per category and the rules as switches. Change the limit or ask for more. The demo is a team card; stories show a yearly time-off allowance and a cloud storage plan.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-limit-tracker
```

It brings `alert`, `async-button`, `button`, `card`, `dropdown-menu`, `empty`, `icon-chevron-down`, `icon-more-horizontal`, `limit-meter`, `skeleton`, `switch`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { LimitTracker, type LimitTrackerProps } from '@/blocks/app/limit-tracker'

export function LimitTrackerView({ entries, rules, limits }: Pick<LimitTrackerProps, 'entries' | 'rules' | 'limits'>) {
  return (
    <LimitTracker
      entries={entries}
      rules={rules}
      limits={limits}
      copy={{ title: 'Team card' }}
      onRetry={() => {
        // your code
      }}
      onRequestIncrease={async (limit) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2` instead of the page's `h1` (its sections an `h3` instead of an `h2`), and no page around it. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (576px at 100% scale). |
| `copy` | `Partial<LimitTrackerCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `entries` | `LimitTrackerEntry[]` | `four demo categories` | What has been used so far, by category. |
| `limit` | `number` | `2,000` | The limit for the period. |
| `rules` | `LimitTrackerRule[]` | `a card's freeze, receipts and approver rules` | The rules at the foot, as switches; one with a `line` draws it on the ruler. |
| `limits` | `number[]` | `1,500 to 5,000` | The limits the menu offers, with the current one. |
| `increase` | `number` | `250` | What a request adds to the limit. |
| `count` | `number` | `23` | How many entries there have been, for the pace list. |
| `elapsed` | `number` | `19 (days)` | How much of the period has gone, in the unit the average is read in. |
| `format` | `(value: number) => string` |  | Writes every amount; the ruler, tiles, rules and menu all use it. Default: `copy.currency` in the locale's number format. |
| `loading` | `boolean` | `false` | Skeletons in place of the ruler, the tiles and the rules while your data loads. |
| `error` | `string` |  | Shown in place of the ruler when it fails to load, with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there are no entries. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `onRequestIncrease` | `(limit: number) => Promise<unknown> \| unknown` |  | Requests a higher limit (the current one plus `increase`); the ruler rescales once it resolves. Default: a short demo wait. |

**Strings:** `copy` takes `currency`, `title`, `aside`, `subtitle`, `more`, `viewHistory`, `viewDetails`, `meter`, `runway`, `untilLine`, `untilLimit`, `countLabel`, `perUnit`, `categories`, `rules`, `change`, `limitLabel`, `increase`, `requesting`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Health dial

One thing's health across its parts: a zoned gauge beside its signals and a row per part with two figures and a state. A part whose state offers the action (a lagging region) can be shifted off; the footer adds capacity. The windows, signals, states and every word are yours: a service and its regions, a patient and their monitors, a wind farm and its turbines.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-health-dial
```

It brings `alert`, `async-button`, `badge`, `button`, `empty`, `gauge`, `icon-x`, `segmented-control`, `segmented-meter`, `skeleton`, `typography`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { HealthDial, type HealthDialProps } from '@/blocks/app/health-dial'

export function HealthDialView({ ranges, snapshots, statuses }: Pick<HealthDialProps, 'ranges' | 'snapshots' | 'statuses'>) {
  return (
    <HealthDial
      ranges={ranges}
      snapshots={snapshots}
      statuses={statuses}
      copy={{ title: 'Service health' }}
      onRangeChange={(range) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onRebalance={async (part) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A panel inside another page: an `h2` instead of the page's `h1` (its sections an `h3` instead of an `h2`), and no page around it. |
| `fill` | `boolean` | `false` | Take the width the page gives it (a grid cell), not its natural width. |
| `copy` | `Partial<HealthDialCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `ranges` | `HealthDialRange[]` | `15 minutes, 6 hours, 3 days` | The windows to read over, in the control's order. |
| `snapshots` | `Record<string, HealthDialSnapshot>` | `demo data` | A snapshot per window, keyed by the range's id. |
| `statuses` | `HealthDialStatus[]` | `nominal, lagging (offers the action, then isolated) and isolated` | The states a part can be in. |
| `defaultRange` | `string` |  | The window shown first, uncontrolled (a range id). Default `6h`, else the first. |
| `range` | `string` |  | The window shown, controlled: pair it with `onRangeChange`. Default: uncontrolled. |
| `onRangeChange` | `(range: string) => void` |  | Called with the window picked. Default: none. |
| `subject` | `string` |  | The subject's name, set in mono under the title. Default: `copy.subject` ("payments-api"). |
| `format` | `{ measures?: [(value: number) => string, (value: number) => string]; }` |  | Writes the two figures beside each part, whole (`format.measures`, [first, second]). Default: the first compact with `copy.firstMeasure`, the second in milliseconds with `copy.secondMeasure`. |
| `loading` | `boolean` | `false` | Skeletons in place of the signals and the parts while your data loads. |
| `error` | `string` |  | Shown in place of the signals and the parts when they fail to load, with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when the window has no snapshot. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `onRebalance` | `(part: HealthDialPart) => Promise<unknown> \| unknown` |  | Moves a part off the load of its status's `action`; resolve when done, reject to show the button's error. Default: a short demo wait. |
| `onAddCapacity` | `(capacity: number) => Promise<unknown> \| unknown` |  | Adds capacity, with the count it will reach; resolve when done, reject to show the button's error. Default: a short demo wait. |
| `locale` | `string` |  | Formats every number. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level; the parts heading is one below. Default: 1, or 2 when `embedded`. |
| `className` | `string` |  | Classes for the root element (the card when embedded, else the page), merged with its own. Default: none. |
| `capacity` | `number` | `9` | How much capacity it runs (the footer's count). |
| `checkedAgo` | `number` | `4` | Seconds since the last check, when the block mounts. |
| `onClose` | `() => void` |  | Called by the close button. Without it the button isn't shown. |

**Strings:** `copy` takes `title`, `subject`, `close`, `range`, `index`, `nominal`, `strained`, `critical`, `signals`, `parts`, `firstMeasure`, `secondMeasure`, `checked`, `failed`, `justNow`, `rebalance`, `rebalanceFrom`, `rebalancing`, `capacity`, `capacityValue`, `addCapacity`, `adding`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Tiered capacity

How full each region is, tier by tier, as a block of isometric columns, each filling its dashed case. Pick a region for its tiers and when it fills, and Add capacity provisions a step more. Storage by default; warehouse floors and parking levels are in the stories, and the tiers and the unit are yours.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-tiered-capacity
```

It brings `alert`, `async-button`, `button`, `card`, `empty`, `grid-backdrops`, `icon-more-horizontal`, `iso-scene`, `iso-shapes`, `segmented-control`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { TieredCapacity, type TieredCapacityProps } from '@/blocks/app/tiered-capacity'

export function TieredCapacityView({ regions, tiers }: Pick<TieredCapacityProps, 'regions' | 'tiers'>) {
  return (
    <TieredCapacity
      regions={regions}
      tiers={tiers}
      copy={{ title: 'Capacity' }}
      onRetry={() => {
        // your code
      }}
      onAddCapacity={async (region, amount) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `nearLimit`, `overLimit`, `allClear`, `used`, `ofProvisioned`, `table`, `region`, `regions`, `regionButton`, `provisioned`, `legend`, `percentUsed`, `fullIn`, `full`, `over`, `steady`, `updated`, `rebalance`, `addCapacity`, `adding`, `addStep`, `added`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Bin rack

A rack of bins as an isometric drawing (the demo: a line-side flow rack, with a pharmacy shelf and a vending machine in the stories): each bin a cell holding a block as tall as its stock, in its part's color, with low bins in the warning color and empty ones as dashed outlines. Point at a bin for a tag with how many are left and when it runs out, and flip the auto-call switch to have a low bin call the refill. `format` reads the counts and times, and loading, error and empty states take the drawing's place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-bin-rack
```

It brings `alert`, `badge`, `button`, `card`, `empty`, `iso-scene`, `iso-shapes`, `skeleton`, `switch`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { BinRack, type BinRackProps } from '@/blocks/app/bin-rack'

export function BinRackView({ parts, bins }: Pick<BinRackProps, 'parts' | 'bins'>) {
  return (
    <BinRack
      parts={parts}
      bins={bins}
      copy={{ title: 'Line-side stock' }}
      onAutoCallChange={(on) => {
        // your code
      }}
      onBinSelect={(bin) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `rack`, `lowBadge`, `allStocked`, `toRefill`, `minutes`, `nextRefill`, `drawingLabel`, `binList`, `bin`, `state`, `tag`, `emptyIn`, `isEmpty`, `keyLow`, `keyEmpty`, `autoCall`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `autoCallHint`.

### Envelopes

A budget as envelopes: safe to spend today in large mono, then a rack of cells per envelope that drain as the budget is spent. Drag between envelopes, or log the next entry. The demo is a household's month; stories show a team's sprint in hours and a cloud account's credits per project.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-envelopes
```

It brings `alert`, `allocation-meter`, `async-button`, `badge`, `button`, `card`, `counter`, `empty`, `icon-car`, `icon-coffee`, `icon-gift`, `icon-more-horizontal`, `icon-plus`, `icon-shopping-cart`, `icon-ticket`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { Envelopes, type EnvelopesProps } from '@/blocks/app/envelopes'

export function EnvelopesView({ envelopes, entries }: Pick<EnvelopesProps, 'envelopes' | 'entries'>) {
  return (
    <Envelopes
      envelopes={envelopes}
      entries={entries}
      copy={{ title: 'Budget' }}
      onAdd={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `safe`, `safeHint`, `onTrack`, `tight`, `left`, `spent`, `spentOf`, `envelopes`, `dragHint`, `recent`, `today`, `yesterday`, `payday`, `cover`, `covered`, `add`, `adding`, `added`, `loadingLabel`, `emptyTitle`, `emptyDescription`, `retry`, `locale`.

### Streaks

A run of days on anything, as an instrument: the picked item's streak as a flame meter, 26 weeks of heat dots where today's dot is the toggle, and a daily list with a Mark done pill. A freeze can save a run broken yesterday. The demo is four daily habits; stories show a support team's response target and a student's study days.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-streaks
```

It brings `alert`, `async-button`, `badge`, `button`, `calendar-heatmap`, `card`, `empty`, `icon-book-open`, `icon-chevron-down`, `icon-droplet`, `icon-leaf`, `icon-more-horizontal`, `icon-plus`, `icon-snowflake`, `icon-sunrise`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Streaks, type StreaksProps } from '@/blocks/app/streaks'

export function StreaksView({ items }: Pick<StreaksProps, 'items'>) {
  return (
    <Streaks
      items={items}
      copy={{ title: 'Habits' }}
      onFreeze={async (item) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `list`, `history`, `onTrack`, `atRisk`, `doneToday`, `rescue`, `useFreeze`, `freezing`, `frozen`, `noFreezes`, `today`, `streak`, `held`, `noStreak`, `showAll`, `showFewer`, `markDone`, `show`, `resets`, `newItem`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Goals

The period's targets, each with its progress, a notch for where an even pace would be by today and a status from the recent rate. The picked goal is drawn as a burn-up: the total so far, the even pace, and a forecast inside its likely range, with the day it reaches the target.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-goals
```

It brings `alert`, `badge`, `button`, `card`, `chart`, `empty`, `skeleton`, `sliding-indicator`, `stat-card`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Goals, type GoalsProps } from '@/blocks/app/goals'

export function GoalsView({ goals }: Pick<GoalsProps, 'goals'>) {
  return (
    <Goals
      goals={goals}
      copy={{ title: 'Second-half goals' }}
      onGoalChange={(id) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `goals`, `of`, `status`, `lands`, `projected`, `neededPerWeek`, `soFarPerWeek`, `daysLeft`, `crosses`, `misses`, `reached`, `actual`, `pace`, `forecast`, `target`, `goal`, `chart`, `summary`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Limit meters has a labelled picker, and the bucket is a meter named by its label.

Health dial labels its window control and the signals section, and each row's action button names its part ("Shift traffic from us-east-2"). Loading is announced, and an error says why with a Retry button. The stories show other worlds, with their own names and words.

Tiered capacity draws its columns as a picture (`aria-hidden`); the region picker is a labelled segmented control with spoken buttons, the legend is a list, and a hidden table holds every figure.

Bin rack draws the rack as a decorative image and lists every bin as a button with its state and when it runs out (for example "Caps C-12, 6 left, low, empty in ~14 min"); focusing a bin tags it on the drawing. Low and empty are named in words as well as colored and dashed, and the auto-call switch is labelled. The stories show other worlds, with their own names and words.

Envelopes are a labelled group; each envelope is named with what is left (or by how much it is over). Money moves by drag or by keyboard: Space picks an envelope up, the arrow keys choose the target and the amount, Enter moves it and Escape cancels, with a hidden hint describing the keys.
The Pace budget treemap has one tab stop, with the arrow keys and Home and End moving between cells. The plan is a list of switches, each beside the step it applies.

In Streaks each item in the list is a button with `aria-pressed` and a name, and the Mark done control is a labelled toggle for today. The list has its own label.

Under reduced motion values change in place.

---

# Networks & maps

> What connects to what and where: rings out from one thing, hubs and lanes, a globe of arcs and a map of regions.

Source: https://www.youj.dev/docs/blocks/networks-and-maps

## Blocks

### Radial network

What a compromised account reaches, as a radial graph: the account in the middle, what it touches one hop out and what those lead to on the next ring, each dot in its kind's color. Compromised things wear a solid ring and at-risk ones a dashed ring, with the link into them drawn the same way, so the attacker's path reads at a glance. Pick 1 or 2 hops in the header; the foot counts what is compromised, at risk and reached.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-radial-network
```

It brings `alert`, `button`, `card`, `empty`, `radial-graph`, `segmented-control`, `skeleton`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RadialNetwork, type RadialNetworkProps } from '@/blocks/app/radial-network'

export function RadialNetworkView({ center, nodes, kinds, states }: Pick<RadialNetworkProps, 'center' | 'nodes' | 'kinds' | 'states'>) {
  return (
    <RadialNetwork
      center={center}
      nodes={nodes}
      kinds={kinds}
      states={states}
      copy={{ title: 'Blast radius' }}
      onRetry={() => {
        // your code
      }}
      onHopsChange={(hops) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `hopsLabel`, `hops`, `graphLabel`, `statesLabel`, `kindsLabel`, `total`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`.

### Hub map

A network of hubs on a world map: volume handled, the share on target and hubs healthy, with lanes drawn as arcs. Pick a hub for its figures and top lanes, then act on it. A parcel carrier by default, with airline routes and a data center mesh in the stories; the statuses, metrics, thresholds and formats are yours.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-hub-map
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `dropdown-menu`, `empty`, `icon-arrow-down-left`, `icon-arrow-up-right`, `icon-more-horizontal`, `icon-play`, `segmented-control`, `share-bar`, `skeleton`, `sparkline`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { HubMap, type HubMapProps } from '@/blocks/app/hub-map'

export function HubMapView({ hubs, lanes, history, statuses }: Pick<HubMapProps, 'hubs' | 'lanes' | 'history' | 'statuses'>) {
  return (
    <HubMap
      hubs={hubs}
      lanes={lanes}
      history={history}
      statuses={statuses}
      copy={{ title: 'Hub network' }}
      onRetry={() => {
        // your code
      }}
      onAction={async (hub, active) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (1024px at 100% scale). |
| `copy` | `Partial<HubMapCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `hubs` | `HubMapHub[]` |  | The hubs, with their figures and status now; re-render with fresh ones to keep it live. Default: nine demo hubs whose figures drift. |
| `lanes` | `HubMapLane[]` |  | The lanes between hubs, one entry per direction that carries volume. Default: nine demo lanes. |
| `history` | `Record<string, number[]>` |  | The last hour's volume per hub id, oldest first, for the panel's sparkline. Default: the demo's, or the volumes you pass as they change. |
| `statuses` | `HubMapStatus[]` | `on schedule, delayed, halted` | The states a hub can be in, with their colors. |
| `metrics` | `HubMapMetric[]` | `volume and delays` | What the halos can show, in the toggle's order. |
| `thresholds` | `Partial<HubMapThresholds>` |  | Where readings turn to the warning ink (`health` below, `backlog` and `load` above). Default: 90% on target, 1,000 held up, 85% of capacity. |
| `format` | `Intl.NumberFormatOptions` | `compact notation` | Writes volumes and backlogs (`Intl.NumberFormat` options). |
| `durationFormat` | `Intl.NumberFormatOptions` | `hours, narrow` | Writes a duration (`Intl.NumberFormat` options). |
| `loading` | `boolean` | `false` | Skeletons in place of the map and the panel while your data loads. |
| `error` | `string` |  | Shown in place of the map when it fails to load, with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there are no hubs. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `defaultHub` | `string` |  | The hub picked first, by id. Default: the first one that isn't healthy, else the busiest. |
| `defaultMetric` | `string` |  | The id of the metric the halos show first. Default: the first. |
| `live` | `boolean` | `true` | Let the parcels run and, on the demo hubs, the figures drift every few seconds (yours never drift). |
| `onAction` | `(hub: HubMapHub, active: boolean) => Promise<unknown> \| unknown` |  | Acts on a hub (the demo's divert to its peers; `active` true) or undoes it; resolve when it's done. Default: a short demo wait. |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the map runs on its demo hubs (no `hubs` or `lanes` passed). |
| `locale` | `string` |  | Formats its numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `title`, `subtitle`, `more`, `exportCsv`, `openRunbook`, `live`, `demoData`, `throughput`, `unit`, `health`, `healthy`, `healthyCount`, `inTransit`, `metric`, `map`, `hubs`, `acted`, `hubLabel`, `volume`, `backlog`, `load`, `lastHour`, `lanes`, `outbound`, `inbound`, `duration`, `legend`, `arcs`, `action`, `actionPending`, `resume`, `resumePending`, `actionNote`, `resumeNote`, `manifests`, `updated`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Arc globe

What comes in from around the world, live: a dot globe turns while each event is thrown across it as an arc to the place that serves it. Regions and places are toggles that bring a part of the globe forward; period and site re-cut every figure. Site visitors by default; card payments and flights are in the stories, and the regions, periods, sites, figures and words are all yours.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-arc-globe
```

It brings `alert`, `badge`, `button`, `card`, `counter`, `empty`, `icon-arrow-right`, `icon-play`, `segmented-control`, `select`, `share-bar`, `skeleton`, `stat-card`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ArcGlobe, type ArcGlobeProps } from '@/blocks/app/arc-globe'

export function ArcGlobeView({ places, regions, sites, periods }: Pick<ArcGlobeProps, 'places' | 'regions' | 'sites' | 'periods'>) {
  return (
    <ArcGlobe
      places={places}
      regions={regions}
      sites={sites}
      periods={periods}
      copy={{ title: 'Global traffic' }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `live`, `paused`, `demoData`, `pause`, `resume`, `period`, `scope`, `now`, `vsHourAgo`, `primary`, `secondary`, `rate`, `vsPrevious`, `regions`, `topPlaces`, `share`, `globe`, `hint`, `latest`, `waiting`, `via`, `units`, `table`, `place`, `change`, `announcePeriod`, `announceScope`, `announcePlace`, `announceRegion`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `announceLive`, `locale`.

### Region map

Where activity comes from: the total rate, a dot map with each region lit by its share, and a table of regions with share, rate and a reading that flags the ones in trouble. API traffic by default, with ride requests and store sales in the stories; the ranges, formats, threshold and the action are yours.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-region-map
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `dot-map`, `dropdown-menu`, `empty`, `icon-more-horizontal`, `icon-play`, `segmented-control`, `share-bar`, `skeleton`, `table`, `typography`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { RegionMap, type RegionMapProps } from '@/blocks/app/region-map'

export function RegionMapView({ snapshots, ranges }: Pick<RegionMapProps, 'snapshots' | 'ranges'>) {
  return (
    <RegionMap
      snapshots={snapshots}
      ranges={ranges}
      copy={{ title: 'Traffic' }}
      onRetry={() => {
        // your code
      }}
      onAction={async (flagged) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (736px at 100% scale). |
| `copy` | `Partial<RegionMapCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `snapshots` | `Record<string, RegionMapRegion[]>` |  | A snapshot of the regions per range id, now; re-render with fresh ones to keep it live. Default: ten demo points of presence whose rates drift. |
| `ranges` | `RegionMapRange[]` | `5 minutes, 1 hour, 24 hours` | The spans of time to choose between, in the toggle's order. |
| `format` | `Intl.NumberFormatOptions` | `compact notation` | Writes the rates (`Intl.NumberFormat` options). |
| `readingFormat` | `Intl.NumberFormatOptions` | `milliseconds` | Writes the readings (`Intl.NumberFormat` options). |
| `threshold` | `number` | `180` | A region is flagged past this reading. |
| `loading` | `boolean` | `false` | Skeletons in place of the map and the table while your data loads. |
| `error` | `string` |  | Shown in place of the map and the table when they fail to load, with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there are no regions. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `defaultRange` | `string` |  | The range shown first, by id. Default: the first. |
| `defaultRegion` | `string` |  | A region pinned from the start, by id: lit on the map with its row marked, as if clicked. For a link from elsewhere (the region an incident hits). Default: none. |
| `live` | `boolean` | `true` | Let the demo rates drift every few seconds (yours never drift). |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the card runs on its demo regions (no `snapshots` passed). |
| `onAction` | `(flagged: RegionMapRegion[]) => Promise<unknown> \| unknown` |  | Acts on the flagged regions (the demo's reroute); resolve when it's done. Default: a short demo wait. |

**Strings:** `copy` takes `title`, `scope`, `more`, `exportCsv`, `openLogs`, `range`, `measure`, `unit`, `change`, `live`, `demoData`, `reading`, `failures`, `regionsLabel`, `regionCount`, `map`, `mapLabel`, `mapHint`, `region`, `share`, `valueHead`, `readingHead`, `flagged`, `showOnMap`, `footer`, `action`, `actionPending`, `actionDone`, `logs`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Radial network picks its hops with one named choice and draws the graph as a named group described by how many things are reached within the hops shown. Every node is in a list, named with its distance ("invoice-exports, 2 hops away") and described by its state and note; the graph is one tab stop, the arrow keys walk the rings and follow links, and focus shows the same tooltip hovering does. States are words and solid or dashed rings, never color alone, and the foot's counts are a description list.

On the hubs map the drawing is `aria-hidden` and the hubs are a labelled radio group: each hub is named with its figures, and the arrow keys walk west to east. Each lane in the panel has a spoken label with its direction, volume and travel time.

The arc globe is an image with a text summary, drawn on a canvas that is `aria-hidden`; its figures are also in a visually hidden table and the lists beside it. Regions and places are `aria-pressed` toggles, places are named with their share, and the period and site controls and the Live toggle are labelled. The feed of latest visits has a heading.

The region map makes the table the source of truth for the dot map: the map is an image with a summary, rows are named, and each region's Show on map button has `aria-pressed`. The range control and Live toggle are labelled.

Under reduced motion the globe is a single still frame and values change in place.

---

# Onboarding & states

> Getting started and the in-between pages: checklists, setup choices, first sources, empty and illustrated states.

Source: https://www.youj.dev/docs/blocks/onboarding-and-states

## Blocks

### Checklist

A getting-started checklist that floats at the bottom of an app: a progress ring, one open step at a time with its action, and finished steps gliding down to Done. It minimizes to a pill that keeps the count.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-checklist
```

It brings `async-button`, `button`, `collapse`, `counter`, `icon-check`, `icon-chevron-down`, `icon-git-branch`, `icon-globe`, `icon-minimize`, `icon-party-popper`, `icon-rocket`, `icon-user-plus`, `icon-wand`, `icon-x`, `presence-list`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Checklist, type ChecklistProps } from '@/blocks/app/checklist'

export function ChecklistView({ completed, steps }: Pick<ChecklistProps, 'completed' | 'steps'>) {
  return (
    <Checklist
      completed={completed}
      steps={steps}
      copy={{ region: 'Getting started' }}
      onCompletedChange={(ids) => {
        // your code
      }}
      onMinimizedChange={(minimized) => {
        // your code
      }}
      onComplete={async (step) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultCompleted` | `string[]` |  | Ids of the steps done when the card opens, uncontrolled. Default: the first step. |
| `completed` | `string[]` |  | Ids of the done steps, controlled. Pair it with `onCompletedChange`. |
| `onCompletedChange` | `(ids: string[]) => void` |  | Called with the done ids after a step completes. |
| `defaultMinimized` | `boolean` | `false` | Starts folded into the pill, uncontrolled. |
| `minimized` | `boolean` |  | Folded into the pill, controlled. Pair it with `onMinimizedChange`. |
| `onMinimizedChange` | `(minimized: boolean) => void` |  | Called when the card folds or unfolds. |
| `embedded` | `boolean` |  | Inside a host app: no faux app, page landmark or h1; the card sits where the host lays it out. Default true; `false` draws its own page around it (a centered canvas and an `h1`). |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (672px at 100% scale). |
| `product` | `string` | `"Fern"` | The product its copy names. Prefer `brand`. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The product the copy names. Default: Fern. |
| `steps` | `ChecklistStep[]` |  | The steps, in order. Default: the demo's five, from workspace to domain. |
| `onComplete` | `(step: ChecklistStep) => Promise<unknown> \| unknown` |  | Does a step's work when its action is pressed; resolve to mark it done, throw to show why it failed. Default: a short demo wait. |
| `onDismiss` | `() => void` |  | Called when the finished checklist is dismissed. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | The card title's level. |
| `locale` | `string` |  | Formats the percentage. Default: the provider's locale. |
| `copy` | `Partial<ChecklistCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `classNames` | `{ list?: string }` |  | Classes for its parts: `list` is the region the steps scroll in (its height, 306px at 100%, holds the card's size as steps open, close and finish). |
| `theme` | `ThemeInput` |  |  |

**Strings:** `copy` takes `region`, `title`, `stepsDone`, `minimize`, `pill`, `pillCount`, `openPill`, `done`, `doneSr`, `working`, `failed`, `allSet`, `allSetBody`, `dismiss`, `show`, `announceStep`, `announceAll`, `page`.

### Setup picker

A setup step where each choice shows what it builds: three deployment shapes as cards with a small isometric plan that builds when chosen. A sentence says what the choice means, and Continue saves it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-setup-picker
```

It brings `async-button`, `button`, `card`, `field`, `iso-scene`, `iso-shapes`, `radio-group`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SetupPicker } from '@/blocks/app/setup-picker'

export function SetupPickerView() {
  return (
    <SetupPicker
      copy={{ title: 'New database' }}
      onContinue={async (shape) => {
        // await your API here; the block shows progress until it settles
      }}
      onBack={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `step`, `question`, `lead`, `legend`, `options`, `back`, `next`, `saving`, `saved`, `chosen`.

### Connect sources

A setup step for plugging your sources in. An isometric power strip shows each connected source as a plug in its color, the one still backfilling hovering over its socket, and empty sockets for the rest. Each tile shows a source's day as a small histogram with events a day, how far a backfill has come, or the coverage it would add and a Connect button; the foot sums the coverage on a segmented meter beside Skip for now and Continue.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-connect-sources
```

It brings `badge`, `button`, `card`, `icon-plus`, `iso-scene`, `iso-shapes`, `share-bar`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ConnectSources, type ConnectSourcesProps } from '@/blocks/app/connect-sources'

export function ConnectSourcesView({ sources }: Pick<ConnectSourcesProps, 'sources'>) {
  return (
    <ConnectSources
      sources={sources}
      copy={{ title: 'Data sources' }}
      onConnect={async (source) => {
        // await your API here; the block shows progress until it settles
      }}
      onSkip={() => {
        // your code
      }}
      onContinue={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `connectedCount`, `sourcesLabel`, `connected`, `perDay`, `backfilling`, `adds`, `connect`, `connecting`, `announceConnected`, `failed`, `coverage`, `skip`, `continue`.

### First data source

The first source for an empty library, drawn as a floor plan; a data warehouse by default. Choice cards (database, event stream, files here; a photo library or a CRM with your own `sources`) reshape what is waiting to land, and the primary action connects the chosen source.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-first-source
```

It brings `async-button`, `button`, `card`, `field`, `grid-backdrops`, `icon-activity`, `icon-book-open`, `icon-database`, `icon-folder-input`, `illustrations`, `iso-scene`, `iso-shapes`, `radio-group`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { FirstSource, type FirstSourceProps } from '@/blocks/app/first-source'

export function FirstSourceView({ sources }: Pick<FirstSourceProps, 'sources'>) {
  return (
    <FirstSource
      sources={sources}
      copy={{ title: 'Warehouse' }}
      onConnect={async (source) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (736px at 100% scale). |
| `copy` | `Partial<FirstSourceCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `sources` | `FirstSourceOption[]` | `database, event stream and files` | The ways in, as choice cards (two to four): each has its label, formats, primary action and the shape that waits to land. |
| `defaultSource` | `string` |  | The source chosen when the card opens, by id. Default: the first. |
| `onConnect` | `(source: FirstSourceOption) => Promise<unknown> \| unknown` |  | Starts connecting the chosen source; resolve when it's set up. Default: a short demo wait. |
| `illustration` | `IllustrationSlot` |  | The picture over the choices: a scene from the illustrations by id, or your own node. Default: the warehouse floor, with the chosen source waiting to land. |

**Strings:** `copy` takes `title`, `scope`, `status`, `heading`, `body`, `sourceLabel`, `tier`, `guide`, `connecting`, `connected`.

### Gallery

Four empty states in one card: no projects yet, no results, no access and offline. Each says what is missing, why, and the one thing to do next, with an isometric scene that assembles as it scrolls into view.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-empty-states
```

It brings `async-button`, `button`, `card`, `empty`, `icon-folder`, `icon-git-branch`, `icon-lock`, `icon-plus`, `icon-search`, `icon-wifi`, `illustrations`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { EmptyStates } from '@/blocks/app/empty-states'

export function EmptyStatesView() {
  return (
    <EmptyStates
      copy={{ galleryTitle: 'Empty states' }}
      linkComponent={Link}
      onCreate={() => {
        // your code
      }}
      onImport={() => {
        // your code
      }}
      onClear={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The gallery title's level. |
| `illustration` | `IllustrationSlot` |  | The picture over the state: a scene by id, your own node, or `null` for the icon. Default: a scene that fits the state. |
| `copy` | `Partial<EmptyStatesCopy>` |  | Any of the states' strings, to rewrite or translate. |
| `onCreate` | `() => void` |  | "New project". |
| `onImport` | `() => void` |  | "Import from Git". |
| `query` | `string` | `'billing webhook'` | What was searched for. |
| `onClear` | `() => void` |  | "Clear filters". |
| `onRequest` | `() => unknown` |  | Asks for access; resolve when the request is sent. Default: a short demo wait. |
| `switchHref` | `string` | `'#switch'` | Where "switch workspace" goes. |
| `linkComponent` | `ElementType` | `'a'` | The element for the switch link, e.g. Next.js `Link`; it gets `href`. |
| `onRetry` | `() => unknown` |  | Tries to reconnect; the button fails while the browser is still offline. Default: a short demo wait. |

**Strings:** `copy` takes `galleryTitle`, `galleryDescription`, `projectsTitle`, `projectsDescription`, `newProject`, `importProject`, `resultsTitle`, `resultsDescription`, `clearFilters`, `accessTitle`, `accessDescription`, `switchWorkspace`, `accessAfter`, `requestAccess`, `requesting`, `requested`, `requestFailed`, `offlineTitle`, `offlineDescription`, `retry`, `reconnecting`, `reconnected`, `stillOffline`, `online`, `waiting`.

### Illustrated

A full page for the moments between real pages: welcome, empty workspace, 404, maintenance, payment done and offline. One composition keeps them looking like a family; the story shows the welcome state.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add content-illustrated-states
```

It brings `async-button`, `button`, `grid-backdrops`, `icon-arrow-right`, `icon-check`, `icon-circle-dashed`, `icon-external-link`, `icon-home`, `icon-loader-ring`, `icon-mail`, `icon-plus`, `icon-receipt`, `icon-refresh`, `icon-search`, `icon-upload`, `icon-wifi`, `icon-wifi-off`, `illustrations`, `progress`, `reveal`, `stagger`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { IllustratedState, type IllustratedStateProps } from '@/blocks/content/illustrated-states'

export function IllustratedStateView({ state }: Pick<IllustratedStateProps, 'state'>) {
  return (
    <IllustratedState
      state={state}
      onPrimary={() => {
        // your code
      }}
      onSecondary={() => {
        // your code
      }}
      onTemplate={(name) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `'welcome' \| 'empty' \| 'not-found' \| 'maintenance' \| 'success' \| 'offline'` | `'welcome'` | Which page. |
| `illustration` | `IllustrationSlot` |  | The picture: a scene from the illustrations by id, your own node, or `null` for none. Default: a scene that fits the state. |
| `copy` | `Partial<StateCopy>` |  | Any of the state's strings, to rewrite or translate. |
| `onPrimary` | `() => unknown` |  | The main action. Offline runs it as Try again: resolve when connected, reject when not. Default: offline checks the browser; the rest do nothing. |
| `onSecondary` | `() => void` |  |  |
| `onTemplate` | `(name: string) => void` |  | Empty workspace: a template was picked. |
| `path` | `string` |  | 404: the address that missed. Default: a sample path. |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | Inside another app: a `section` named by an `h2`, without the page height around it. |

**Strings:** `copy` takes `eyebrow`, `title`, `body`, `primary`, `secondary`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The checklist is a `section` labelled by its title and each change is announced. Its title heading follows `headingLevel`.

Setup picker uses a radio group, so the arrow keys move between the cards and the choice is announced. The isometric plans are decorative.

Connect sources keeps its drawing decorative (hidden from assistive tech) and says everything in the tiles: a named list where each tile has its source's name, its state in words ("Connected", a backfill percentage, or the coverage it adds) and a Connect button named for the source. The histograms are decorative too; the line under each says the number. The coverage meter is a `meter` named Coverage, and connecting announces the result in a polite live region.

Every state has a plain title and sentence, and the illustrated pages are a `section` or `main` named by their heading. The isometric scenes are pictures: they are `aria-hidden`, and the words beside them carry the meaning.

In the gallery the offline state follows the browser's online state and announces changes in a `role="status"` paragraph. In the first data source block the three choices are a labelled radio group, so the arrow keys move between them and the chosen one is announced; the primary action's label follows the choice.

Under reduced motion the scenes appear finished and still, nothing bobs or drops, and the choice reshapes in place.

Under reduced motion rows, rings and steps change in place, the chosen plan is simply built and the bar jumps to its new split.

---

# Rankings & breakdowns

> How a total splits and what ranks first: rings and bars, waterfalls, cause rings, budgets, forecasts and plan against actual.

Source: https://www.youj.dev/docs/blocks/rankings-and-breakdowns

## Blocks

### Breakdown

How a total splits, as a ring beside a ranked bar list, with the long tail folded into Other. Press a part to zoom the ring into it and see its own parts. The breadcrumb, or Escape, takes you back up, and a reversal partway through runs smoothly back.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-breakdown
```

It brings `alert`, `button`, `card`, `empty`, `icon-chevron-right`, `skeleton`, `stat-card`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Breakdown, type BreakdownProps } from '@/blocks/app/breakdown'

export function BreakdownView({ items, path }: Pick<BreakdownProps, 'items' | 'path'>) {
  return (
    <Breakdown
      items={items}
      path={path}
      copy={{ title: 'Revenue by region' }}
      onPathChange={(path) => {
        // your code
      }}
      onItemSelect={(item, path) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `all`, `other`, `total`, `list`, `path`, `item`, `drill`, `share`, `up`, `down`, `versus`, `opened`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Share gauge

Where a total went, as a half-donut over a ranked list with the tail folded into Other. Point at a segment or a row, or arrow through the list, and both light up with a tag over the segment. Switch the period and the segments move to their new places while the total counts.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-share-gauge
```

It brings `alert`, `button`, `card`, `counter`, `empty`, `icon-bot`, `icon-cloud`, `icon-cpu`, `icon-database`, `icon-globe`, `icon-hard-drive`, `icon-key`, `icon-mail`, `icon-message`, `icon-network`, `icon-shield`, `icon-terminal`, `icon-zap`, `segmented-control`, `skeleton`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ShareGauge, type ShareGaugeProps } from '@/blocks/app/share-gauge'

export function ShareGaugeView({ periods }: Pick<ShareGaugeProps, 'periods'>) {
  return (
    <ShareGauge
      periods={periods}
      copy={{ title: 'Spend by service' }}
      onPeriodChange={(id) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `other`, `otherDetail`, `periodLabel`, `listLabel`, `summary`, `part`, `empty`, `emptyDescription`, `loading`, `retry`, `currency`, `locale`.

### Loss waterfall

A start amount worn down to a result, as an isometric waterfall: the start as the first, tall bar, each loss hanging from where the last one left the level, and what is left standing as the green bar at the end. The biggest loss is called out in your unit, a legend picks another, and a row below says where to look into the one you picked. Shown with a machine's day; stories also use take-home pay and a signup funnel.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-loss-waterfall
```

It brings `badge`, `card`, `counter`, `icon-chevron-right`, `iso-scene`, `iso-shapes`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { LossWaterfall, type LossWaterfallProps } from '@/blocks/app/loss-waterfall'

export function LossWaterfallView({ losses }: Pick<LossWaterfallProps, 'losses'>) {
  return (
    <LossWaterfall
      losses={losses}
      copy={{ title: 'Efficiency' }}
      onLossChange={(loss) => {
        // your code
      }}
      onDrill={(loss) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `metric`, `change`, `drawingLabel`, `loss`, `callout`, `legendLabel`.

### Cause rings

Why something was lost, as a total and its change, then a two-ring donut. The inner ring is the causes; the outer ring splits each cause into where its share came from (lines, plans, channels), the three largest hatched with lines, dots and crosses so it reads without color and in print. The legend lists each cause's figure, and a pill says how few causes make up most of the total. Shown with a plant's line stops; stories also use churn reasons and ticket reasons.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-cause-rings
```

It brings `alert`, `button`, `card`, `empty`, `icon-sparkle`, `skeleton`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { CauseRings, type CauseRingsProps } from '@/blocks/app/cause-rings'

export function CauseRingsView({ causes }: Pick<CauseRingsProps, 'causes'>) {
  return (
    <CauseRings
      causes={causes}
      copy={{ title: 'Why lines stop' }}
      onRetry={() => {
        // your code
      }}
      onActiveChange={(id) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `total`, `change`, `versus`, `chartLabel`, `share`, `legendLabel`, `legendHint`, `contributors`, `patternTop`, `patternSecond`, `patternThird`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `insight`.

### Pace budget

A period's budget read map first: a treemap of where it went, what is used and left, and the day it runs out at this pace. A plan of switches outlines the categories it trims. The demo is a household's month; stories show a marketing budget and a week of calories.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-pace-budget
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `dropdown-menu`, `empty`, `field`, `icon-more-horizontal`, `presence-list`, `share-bar`, `skeleton`, `switch`, `treemap`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { PaceBudget, type PaceBudgetProps } from '@/blocks/app/pace-budget'

export function PaceBudgetView({ categories, steps, period }: Pick<PaceBudgetProps, 'categories' | 'steps' | 'period'>) {
  return (
    <PaceBudget
      categories={categories}
      steps={steps}
      period={period}
      copy={{ title: 'Spending' }}
      onRetry={() => {
        // your code
      }}
      onApply={async (steps) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `currency`, `title`, `subtitle`, `more`, `exportCsv`, `editBudget`, `meter`, `meterValue`, `mapLabel`, `used`, `left`, `runsOut`, `lasts`, `pace`, `plan`, `noneSelected`, `nothingLeft`, `apply`, `applying`, `applied`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Month forecast

A month's running total read as where it will land: the projection against the budget, its likely range and the day it crosses, and the parts it is made of. Switch between your own scenarios, adjust the budget or set an alert. The demo is a cloud bill; stories show a home's electricity and a support team's tickets, in your own format.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-month-forecast
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `dropdown-menu`, `empty`, `forecast-band`, `hatched-bar`, `icon-chevron-down`, `icon-more-horizontal`, `segmented-control`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MonthForecast, type MonthForecastProps } from '@/blocks/app/month-forecast'

export function MonthForecastView({ actual, scenarios, forecasts, series }: Pick<MonthForecastProps, 'actual' | 'scenarios' | 'forecasts' | 'series'>) {
  return (
    <MonthForecast
      actual={actual}
      scenarios={scenarios}
      forecasts={forecasts}
      series={series}
      copy={{ title: 'Cloud spend' }}
      onRetry={() => {
        // your code
      }}
      onSetAlert={async (budget) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (704px at 100% scale). |
| `copy` | `Partial<MonthForecastCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `actual` | `readonly number[]` | `demo` | The running total at the end of each elapsed day, the last being today. |
| `scenarios` | `readonly MonthForecastScenario[]` | `current pace and a savings plan` | The ways the rest of the period could go, switched between at the top. |
| `forecasts` | `Record<string, readonly ForecastPoint[]>` | `demo` | The rest of the period per scenario id, as ForecastBand takes it. |
| `series` | `readonly MonthForecastSeries[]` | `demo` | The parts the total is made of, drawn as bars. |
| `start` | `string` | `1 September 2026` | The period's first day. |
| `budget` | `number` | `12,000` | The budget it opens with. |
| `budgets` | `readonly number[]` | `11,000 to 14,000` | The budgets the menu offers, with the current one. |
| `max` | `number` | `15,000` | The chart's top, held across scenarios and budgets so the axis stays still. |
| `defaultScenario` | `string` |  | The id of the scenario it opens with. Default: the first. |
| `format` | `(value: number) => string` |  | Writes every amount; with it the headline is text rather than a rolling Counter. Default: US dollars in the locale's number format. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures, chart and bars while your data loads. |
| `error` | `string` |  | Shown in place of the chart when it fails to load, with Retry when `onRetry` is set; the figures show a dash. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there is no data. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `onSetAlert` | `(budget: number) => Promise<unknown> \| unknown` |  | Sets an alert at the budget; resolve when it's saved. Default: a short demo wait. |
| `locale` | `string` |  | Formats every amount (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `currency`, `title`, `subtitle`, `more`, `exportCsv`, `viewDetails`, `scenario`, `projected`, `over`, `under`, `likely`, `spent`, `budget`, `burn`, `daysLeft`, `chart`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `breakdown`, `spentKey`, `projectedKey`, `seriesRow`, `updated`, `adjust`, `budgetMenu`, `setAlert`, `settingAlert`, `alertSet`, `announce`, `locale`.

### Portfolio

A value, how it moved and what it is made of. Switch the period and the chart morphs while the change counts to its new figure; hover the chart, or arrow along it, to read the value on a date. The demo is an investment portfolio; stories show revenue by product line and spend by campaign.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-portfolio
```

It brings `alert`, `button`, `card`, `counter`, `empty`, `icon-banknote`, `icon-building`, `icon-chart-area`, `icon-info`, `icon-landmark`, `icon-pie-chart`, `segmented-control`, `skeleton`, `tooltip`, `use-controllable-state`, `youj-core`, `youj-labels-portfolio`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Portfolio, type PortfolioProps } from '@/blocks/app/portfolio'

export function PortfolioView({ periods, series, holdings }: Pick<PortfolioProps, 'periods' | 'series' | 'holdings'>) {
  return (
    <Portfolio
      periods={periods}
      series={series}
      holdings={holdings}
      copy={{ title: 'Portfolio' }}
      onPeriodChange={(period) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `valueLabel`, `valueInfo`, `investments`, `holdings`, `loadingLabel`, `emptyTitle`, `emptyDescription`, `retry`, `locale`.

### Plan vs actual

What each row of a set adds up to this year, against its plan; the default is a team's agent spend, and department budgets or a harvest by field read the same way. A row of month cells per big one and one for the rest, on one scale: settled months solid and forecast ones hatched, in the warning ink when the year runs past its plan (the dashed tick) and the success ink when under. Below them, the year by quarter against the plan. Beside them, the total to date against the plan to date, the projected year, a few facts and the biggest movers with why; the foot carries the insight with Set budget and the next step. Your own formats write the figures in any unit. It has loading, error and empty states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-plan-vs-actual
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `cell-bar`, `empty`, `hatched-bar`, `icon-bell`, `icon-bot`, `icon-clock`, `icon-gauge`, `icon-trending-down`, `icon-trending-up`, `icon-wallet`, `skeleton`, `stat-card`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { PlanVsActual, type PlanVsActualProps } from '@/blocks/app/plan-vs-actual'

export function PlanVsActualView({ rows, facts, formats }: Pick<PlanVsActualProps, 'rows' | 'facts' | 'formats'>) {
  return (
    <PlanVsActual
      rows={rows}
      facts={facts}
      formats={formats}
      copy={{ title: 'Agent spend' }}
      onSetPlan={() => {
        // your code
      }}
      onAction={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `overPlan`, `underPlan`, `monthly`, `actual`, `projected`, `rows`, `others`, `spendOf`, `scale`, `byQuarter`, `quarter`, `quarters`, `plan`, `spentYtd`, `againstPlan`, `projectedYear`, `rowsOver`, `rowsOverValue`, `movers`, `insight`, `setPlan`, `action`, `acting`, `acted`, `failed`, `currency`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Estimate builder

What anything priced by the amount will cost; the default is usage pricing for a log platform, and a catering quote or a move reads the same way. The estimate leads, for one period or twelve with the discount on the longer segment, and its all-in price per unit of the first line. A bar and its key split it by line; pointing at a key row, a line or a ruler lights its part. Below, a preset switch (Hobby, Startup, Scale in the demo) and a ruler of ticks per line in its color, each with its cost and unit price. The picker in the head scales every price, and Save estimate sends the usage, region, billing and totals. It has loading, error and empty states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-estimate-builder
```

It brings `alert`, `async-button`, `breakdown-list`, `button`, `card`, `empty`, `segmented-control`, `select`, `share-bar`, `skeleton`, `slider`, `stat-card`, `typography`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { EstimateBuilder, type EstimateBuilderProps } from '@/blocks/app/estimate-builder'

export function EstimateBuilderView({ lines, presets, regions, usage }: Pick<EstimateBuilderProps, 'lines' | 'presets' | 'regions' | 'usage'>) {
  return (
    <EstimateBuilder
      lines={lines}
      presets={presets}
      regions={regions}
      usage={usage}
      copy={{ title: 'Cost estimate' }}
      onUsageChange={(usage) => {
        // your code
      }}
      onRegionChange={(region) => {
        // your code
      }}
      onBillingChange={(billing) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (512px at 100% scale). |
| `copy` | `Partial<EstimateBuilderCopy>` |  | Any of the card's strings, to rewrite or translate; `currency` prices the lines. |
| `locale` | `string` |  | Formats amounts and prices (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `lines` | `EstimateBuilderLine[]` | `demo` | The lines of the bill, each with its ruler and price. |
| `presets` | `EstimateBuilderPreset[]` | `demo` | The usage presets on the switch; the second is where the card starts. |
| `regions` | `EstimateBuilderRegion[]` | `demo` | The regions in the head's picker; each scales every price. |
| `usage` | `EstimateBuilderUsage` |  | The usage per line, when your app owns it; pair with `onUsageChange`. |
| `defaultUsage` | `EstimateBuilderUsage` |  | The usage at first. Default: the second preset's (the first's when there is one). |
| `onUsageChange` | `(usage: EstimateBuilderUsage) => void` |  |  |
| `defaultRegion` | `string` |  | The region at first, by id. Default: the first. |
| `onRegionChange` | `(region: string) => void` |  |  |
| `defaultBilling` | `'monthly' \| 'annual'` | `'monthly'` | Monthly or annual at first. |
| `onBillingChange` | `(billing: EstimateBuilderBilling) => void` |  |  |
| `annualDiscount` | `number` | `0.15` | The annual discount, 0–1. |
| `showBilling` | `boolean` | `true` | Show the switch between one period and twelve. |
| `onSave` | `(estimate: EstimateBuilderValue) => Promise<unknown> \| unknown` |  | Saves the estimate; the card awaits it. |
| `formats` | `EstimateBuilderFormats` |  | How the amounts are written; each replaces its default whole. Default: `copy.currency`, whole units for amounts and two decimals for unit prices. |
| `loading` | `boolean` | `false` | Skeletons in place of the estimate and the usage lines while your data loads. |
| `error` | `string` |  | Shown over the card's body when it fails to load, with Retry when `onRetry` is set. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `empty` | `ReactNode` |  | Replaces the message when there are no lines. Default: `copy.emptyTitle` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `region`, `estimated`, `billing`, `monthly`, `annual`, `discount`, `perMonth`, `perYear`, `allIn`, `breakdown`, `usage`, `presets`, `preset`, `custom`, `unitPrice`, `caption`, `reset`, `save`, `saving`, `saved`, `failed`, `announce`, `currency`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Lollipop ranking

Where every item of a set stands against a line; the default is a company's error budgets, and school attendance or supplier ratings read the same way. The items as a table with their owner, 90 days of trend in the status ink, the signed value, when it crosses the line and the alert, filtered by status tabs that count each one, a group and a search. Beside it, the index: every item as a dot on a stem from zero, from the lowest to the highest. Picking a row picks its dot and the other way round, and the panel names it with its target, period and owner. Your own statuses set the bands, their words and colors. It has loading, error and empty states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-lollipop-ranking
```

It brings `alert`, `avatar`, `badge`, `button`, `card`, `empty`, `icon-arrow-down`, `icon-arrow-up`, `icon-bell`, `icon-database`, `icon-layers`, `icon-search`, `icon-server`, `icon-shield`, `input-group`, `lollipop-chart`, `select`, `skeleton`, `sparkline`, `table`, `tabs`, `tooltip`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { LollipopRanking, type LollipopRankingProps } from '@/blocks/app/lollipop-ranking'

export function LollipopRankingView({ items, statuses, domain }: Pick<LollipopRankingProps, 'items' | 'statuses' | 'domain'>) {
  return (
    <LollipopRanking
      items={items}
      statuses={statuses}
      domain={domain}
      copy={{ title: 'Reliability index' }}
      onValueChange={(id) => {
        // your code
      }}
      onOpen={async (id) => {
        // await your API here; the block shows progress until it settles
      }}
      onCreate={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `summary`, `raised`, `filters`, `all`, `search`, `searchPlaceholder`, `group`, `allGroups`, `items`, `item`, `owner`, `trend`, `value`, `eta`, `alert`, `pastZero`, `steady`, `alerts`, `period`, `meta`, `trendOf`, `index`, `indexLabel`, `picked`, `noMatch`, `noMatchHint`, `showing`, `updated`, `open`, `create`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Loss waterfall draws the isometric bars as an image whose text gives the start, every loss with its figure and the result left. The legend repeats every loss as a button (`aria-pressed`) that moves the callout, and the drill-in row is a button named by its title.

Cause rings draws the donut as an image whose text lists every cause with its figure and share, and the legend repeats it as buttons (`aria-pressed`) that light a cause and list where its share came from. Patterns and a hairline edge carry the meaning, never color alone.

The forecast chart is an image with a text alternative and a summary, the scenario switch is labelled, and each series row has a hidden sentence of spent against projected. Limit tracker's rules are switches.

Plan vs actual lists its rows in order of size; each bar is a named group described by its total, the projected part and the plan, and its months are a list one tab stop deep, each read with its amount and whether it is projected. Over and under plan are said in the head's badge and with signed amounts, not by color alone, and the facts are a description list.

Estimate builder names its billing switch, region picker and preset switch. The bar is a `meter` whose value text names every line with its share, and the key repeats them as a list that is one tab stop walked with the arrow keys. Each line is a `slider` named by the line and spoken in its unit ("60 GB / day"); the ruler's ticks are decorative. A new preset or billing period announces the new total in a polite live region.

Lollipop ranking filters with status tabs (each counting its items), a labelled search and a group select. The table is named, its value column has `aria-sort` and sorts from its header button, and each item's name is a button pressed while it is picked; owners are spoken by name, and each trend is an image named for its item. The index is a listbox, one tab stop walked with the arrows, its options named with the item and its value and `aria-selected` when picked; the picked item's line above it is a polite live region. Statuses are signed amounts and words as well as inks.

Each card is a `section` named by its title. Under reduced motion the figures, bars, the fan and its particles are drawn in place.

---

# Status & health

> Is everything all right: status over 90 days, queues, tile boards and a score with what is open.

Source: https://www.youj.dev/docs/blocks/status-and-health

## Blocks

### Status

A platform's services over 90 days inside your app: the SLA as a large figure and a strip with a cell per day colored by uptime. Press a service to put its history on the strip.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `dropdown-menu`, `empty`, `history-strip`, `icon-more-horizontal`, `segmented-meter`, `skeleton`, `typography`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { StatusCard, type StatusCardProps } from '@/blocks/app/status'

export function StatusCardView({ services, statuses }: Pick<StatusCardProps, 'services' | 'statuses'>) {
  return (
    <StatusCard
      services={services}
      statuses={statuses}
      copy={{ title: 'Status' }}
      onValueChange={(id) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onSubscribe={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (640px at 100% scale). |
| `copy` | `Partial<StatusCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's heading level. Default 1, or 2 when `embedded`. |
| `locale` | `string` |  | Formats percentages and "days ago". Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `services` | `StatusService[]` |  | Each service with a day per entry, oldest first, the last today. Default: six demo services. |
| `today` | `Date \| string` |  | The day the services' last entry is, as a Date or "YYYY-MM-DD"; "days ago" counts from it, and the demo fleet ends on it. Default: the last day in `services` (the demo's Sep 28, 2026). |
| `statuses` | `StatusLevel[]` | `operational, degraded, outage` | The statuses a service can be in, best first: a day at or above the target is the first, one above the critical line the second, anything below the last. A service's own `status` (an id) overrides that. |
| `critical` | `number` | `0.99` | The uptime below which a day is an outage, 0–1, always under `target`. |
| `format` | `{ uptime?: (share: number) => string }` |  | Formats the uptime shares (0–1) in the figure, the target, the legend and the rows. Default: percentages in the locale. |
| `target` | `number` | `0.999` | The SLA a day must meet, 0–1. |
| `value` | `string \| null` |  | The id of the service on the day strip, or null for all of them; pair with `onValueChange`. |
| `defaultValue` | `string \| null` | `null` | The service on the day strip at first. |
| `onValueChange` | `(id: string \| null) => void` |  | Called with the service id pressed, or null when it's pressed again. |
| `loading` | `boolean` | `false` | Shows skeletons in place of the figures, strip and services. |
| `error` | `ReactNode \| Error` |  | Shown in place of the figures when loading failed; an Error shows its message. |
| `onRetry` | `() => void` |  | Offers a retry beside `error`. |
| `empty` | `ReactNode` | ``copy.empty`` | Replaces the empty state shown when there are no services. |
| `onSubscribe` | `() => Promise<unknown> \| unknown` |  | Subscribes to updates; resolve when done, reject with an Error to show its message. Default: a short demo wait that warns once in development. |
| `onCopyLink` | `() => void` |  | The menu's Copy status link. Default: nothing. |
| `onExport` | `() => void` |  | The menu's Export CSV. Default: nothing. |
| `onHistory` | `() => void` |  | The Incident history button. Default: nothing. |

**Strings:** `copy` takes `title`, `subtitle`, `more`, `copyLink`, `exportCsv`, `uptime`, `target`, `operational`, `partial`, `budget`, `daily`, `allServices`, `stripLabel`, `showAll`, `noData`, `services`, `servicesSummary`, `lastIncident`, `ongoing`, `history`, `subscribe`, `subscribing`, `subscribed`, `failed`, `empty`, `emptyDescription`, `retry`, `locale`.

### Queue monitor

A queue as an instrument: pick a queue, read its throughput and waits, and see backlog and busy workers as lanes of cells. Background jobs, kitchen stations and printers fit. Retry a failed item on its own, pause the queue or add a worker.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-queue-monitor
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `empty`, `icon-more-horizontal`, `lane-meter`, `segmented-control`, `skeleton`, `sparkline`, `typography`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { QueueMonitor, type QueueMonitorProps } from '@/blocks/app/queue-monitor'

export function QueueMonitorView({ queues }: Pick<QueueMonitorProps, 'queues'>) {
  return (
    <QueueMonitor
      queues={queues}
      copy={{ title: 'Job queue' }}
      onRetryFailed={(items, queue) => {
        // your code
      }}
      onScale={async (queue, workers) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `queue`, `live`, `paused`, `demoData`, `throughput`, `perMinute`, `change`, `trend`, `last30`, `now`, `p95Wait`, `oldest`, `slots`, `load`, `queued`, `running`, `failed`, `done`, `retry`, `retryAll`, `retrying`, `retryingAll`, `updated`, `justNow`, `pause`, `resume`, `pauseQueue`, `resumeQueue`, `drain`, `drained`, `scale`, `scaling`, `scaled`, `scaledTo`, `loadingLabel`, `emptyTitle`, `emptyDescription`, `locale`.

### Tile board

A grid of things as tiles, each in one of your statuses, with the one status the board handles marked `alert`. Select a tile and the panel shows what is being done: for an alert tile a timer, the reason as one choice, who is on the way and in how many minutes, and a ring counting down to the escalation, with Escalate now and Resolve below. Shown with a plant's assembly line; stories also use checkout lanes and hospital beds.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-tile-board
```

It brings `async-button`, `avatar`, `badge`, `button`, `card`, `segmented-control`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { TileBoard, type TileBoardProps } from '@/blocks/app/tile-board'

export function TileBoardView({ tiles, statuses, reasons }: Pick<TileBoardProps, 'tiles' | 'statuses' | 'reasons'>) {
  return (
    <TileBoard
      tiles={tiles}
      statuses={statuses}
      reasons={reasons}
      copy={{ title: 'Station board' }}
      onReasonChange={(tile, reasonId) => {
        // your code
      }}
      onEscalate={(tile) => {
        // your code
      }}
      onResolve={async (tile) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `demoData`, `allClear`, `alertCount`, `gridLabel`, `cycle`, `alertTitle`, `statusTitle`, `nothing`, `timerLabel`, `reasonLabel`, `eta`, `etaLabel`, `escalatesIn`, `paged`, `escalate`, `escalating`, `escalated`, `resolve`, `resolving`, `resolved`, `announceResolved`, `announceEscalated`, `announceReason`.

### Score overview

Where anything audited stands, in one card; the default is a company's security posture, and a food safety inspection or an accessibility audit reads the same way. A ring of ticks lit up to the score with its letter grade, the score out of 100 with how it moved and a sparkline of the month, then open findings (and how many are of the worst severity), resolved, assets watched and the median time to fix. Tabs show the open findings by severity over 30 days as a stacked chart, the findings worst first, and the assets they sit on, all in one height. Your own severities set the levels, their words and colors. Scan now sweeps the ring and counts the assets in the foot; Export report sits beside it. It has loading and error states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-score-overview
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `chart`, `empty`, `icon-download`, `icon-refresh`, `icon-shield-check`, `score-ring`, `skeleton`, `sparkline`, `stat-card`, `tabs`, `typography`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ScoreOverview, type ScoreOverviewProps } from '@/blocks/app/score-overview'

export function ScoreOverviewView({ scoreHistory, grades, severities, stats }: Pick<ScoreOverviewProps, 'scoreHistory' | 'grades' | 'severities' | 'stats'>) {
  return (
    <ScoreOverview
      scoreHistory={scoreHistory}
      grades={grades}
      severities={severities}
      stats={stats}
      copy={{ title: 'Security overview' }}
      onTabChange={(tab) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onScan={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (448px at 100% scale). |
| `copy` | `Partial<ScoreOverviewCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats the figures, days and ages (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `score` | `number` | `77` | The security score. |
| `maxScore` | `number` | `100` | What the score is out of. |
| `scoreChange` | `number` | `13` | How the score moved over the period. |
| `scoreHistory` | `readonly number[]` | `demo` | The score over the period, a reading a day, oldest first: a sparkline beside it. |
| `grades` | `readonly ScoreGrade[]` | `F, D, C, B (from 75) and A (from 90)` | Bands of the score, each with its letter and tone. |
| `severities` | `ScoreOverviewSeverity[]` | `Critical, High, Medium, Low` | The levels a finding can have, worst first: each with its label, short chip word and color. |
| `stats` | `ScoreOverviewStats` | `demo` | The four figures under the score. |
| `trend` | `ScoreOverviewTrendPoint[]` |  | Open findings by severity, a point a day, oldest first. |
| `findings` | `ScoreOverviewFinding[]` |  | The open findings. |
| `assets` | `ScoreOverviewAsset[]` | `demo` | The assets with open findings. |
| `now` | `Date \| string \| number` |  | The time the ages are counted from, which the server and the browser agree on. Default: the demo's time with the demo data; with your own, the browser's clock once mounted. |
| `lastScanAt` | `Date \| string \| number` |  | When the last scan finished. |
| `scanning` | `boolean` |  | A scan your app is running, when it owns the scan. |
| `scanned` | `number` |  | Assets scanned so far in the running scan. |
| `tab` | `'trend' \| 'findings' \| 'assets'` |  | The tab shown, when your app owns it. |
| `defaultTab` | `'trend' \| 'findings' \| 'assets'` | `'trend'` | The tab shown at first. |
| `onTabChange` | `(tab: ScoreOverviewTab) => void` |  |  |
| `loading` | `boolean` | `false` | Skeletons in place of the score, the figures and the panels while your data loads. |
| `error` | `string` |  | Shown over the panels when they fail to load, with Retry when `onRetry` is set; the figures show a dash. |
| `onRetry` | `() => void` |  | Retries after an `error`. |
| `onScan` | `() => Promise<unknown> \| unknown` |  | Runs a scan; the card awaits it. |
| `onOpenFinding` | `(finding: ScoreOverviewFinding) => void` |  | Opens a finding from the list. |
| `onExport` | `() => Promise<unknown> \| unknown` |  | Exports the report; the card awaits it. |

**Strings:** `copy` takes `title`, `subtitle`, `scan`, `scanning`, `scanned`, `score`, `outOf`, `versus`, `open`, `urgentCount`, `resolved`, `inPeriod`, `assets`, `newAssets`, `fixTime`, `median`, `tabs`, `trend`, `findings`, `assetsTab`, `chartTitle`, `chartSummary`, `openFinding`, `assetFindings`, `noFindings`, `noFindingsHint`, `noAssets`, `noTrend`, `noTrendHint`, `scanningCaption`, `scanningAll`, `lastScan`, `export`, `exporting`, `exported`, `failed`, `announceScanned`, `loadingLabel`, `retry`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Status gives each service button a spoken label of its name, state and uptime, with `aria-pressed` for the one you picked and a labelled remove control on the filter badge. Errors use `role="alert"`.

The queue picker in Queue monitor is a labelled segmented control. The status line does not announce each tick.

Tile board makes every tile a button (`aria-pressed`) whose name includes its status in words; the colored bar only echoes it. The alert timer is a `role="timer"` that is not announced every second, the reason is one named choice, and Escalate now and Resolve announce their result in a polite live region. Timers stop in a hidden tab.

Score overview puts the score on a `meter` named Security score whose value text is the score and its grade ("77 of 100, grade B"), and each figure is a group named by its label. The tabs are a named tab list; the chart is a named figure with a summary of how the open findings moved, its plot one tab stop whose arrow keys walk the days and open the tooltip. Every finding is a button named with its severity, title, asset and how long it has been open, and every asset says its counts by severity in words. A scan is announced when it finishes, and the foot's progress is a polite live region. The stories show other worlds, with their own names and words.

Under reduced motion figures, bars, rings and rows are drawn in place instead of animating, and nothing loops.

---

# Tables & lists

> Records to scan and act on: grids, tables, logs, grouped and bulk tables, spreadsheets and lists.

Source: https://www.youj.dev/docs/blocks/tables-and-lists

## Blocks

### Data grid

The records engine: a rich cell for every kind of value (an identity with its logo, a status, tags, a meter, a trend line, money, relative dates, people, a switch, a copyable id), row actions where the pointer is, grouping with totals, detail panels, saved views as tabs and cards on a narrow screen. Describe each column by its kind and the grid draws it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-data-grid
```

It brings `avatar`, `badge`, `button`, `checkbox`, `collapse`, `command`, `content-swap`, `data-table`, `dropdown-menu`, `icon-archive`, `icon-arrow-down`, `icon-arrow-up`, `icon-arrow-up-right`, `icon-check`, `icon-check-circle`, `icon-chevron-left`, `icon-chevron-right`, `icon-circle-alert`, `icon-columns`, `icon-copy`, `icon-external-link`, `icon-filter`, `icon-inbox`, `icon-layers`, `icon-link`, `icon-minus`, `icon-more-horizontal`, `icon-rotate-ccw`, `icon-rotate-cw`, `icon-search`, `icon-search-x`, `icon-sort`, `icon-trending-down`, `icon-trending-up`, `icon-x`, `input-group`, `kbd`, `pagination`, `popover`, `presence-list`, `segmented-control`, `skeleton`, `sliding-indicator`, `sortable-list`, `switch`, `tabs`, `tooltip`, `use-announcer`, `use-now`, `youj-core`, `youj-labels`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DataGrid, type DataGridProps } from '@/blocks/tables/data-grid'

export function DataGridView({ rowActions, density }: Pick<DataGridProps, 'rowActions' | 'density'>) {
  return (
    <DataGrid
      rowActions={rowActions}
      density={density}
      onSortingChange={() => {
        // your code
      }}
      onColumnFiltersChange={() => {
        // your code
      }}
      onGlobalFilterChange={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `ReadonlyArray<TData>` |  | The records, one per row. Default: 18 projects, with the demo's columns. |
| `columns` | `ReadonlyArray<DataGridColumnDef<TData>>` |  | The columns, from `createDataGridColumns` (this block's `data-grid/columns`). Default: the projects' Project, Status, Lead, Progress, Velocity, Budget, Target and Tags. |
| `getRowId` | `(row: TData, index: number) => string` |  | Stable row identity: selection, expansion and row motion key on it. Default: its `id` field. |
| `getRowLabel` | `(row: TData) => string` |  | Names a row for its checkbox, its menus and announcements. Default: its first column's value. |
| `title` | `ReactNode` |  | The heading over the grid. Without one the grid stands alone, named by `label`. Default: "Projects" with the demo's rows. |
| `description` | `ReactNode` |  | A line under the title. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when `embedded`. |
| `label` | `string` |  | The grid's accessible name, when it has no `title`. |
| `aria-labelledby` | `string` |  | Identifies the element (or elements) that labels the current element. |
| `initialState` | `Partial<DataGridState>` |  | Starting state for every slice you don't control. |
| `state` | `Partial<DataGridState>` |  | Controlled slices. Pair each with its change callback. |
| `onSortingChange` | `Change<SortingState>` |  |  |
| `onColumnFiltersChange` | `Change<ColumnFiltersState>` |  |  |
| `onGlobalFilterChange` | `Change<string>` |  |  |
| `onRowSelectionChange` | `Change<RowSelectionState>` |  |  |
| `onColumnVisibilityChange` | `Change<ColumnVisibilityState>` |  |  |
| `onColumnOrderChange` | `Change<ColumnOrderState>` |  |  |
| `onColumnSizingChange` | `Change<ColumnSizingState>` |  |  |
| `onGroupingChange` | `Change<string \| null>` |  |  |
| `onExpandedChange` | `Change<Record<string, boolean>>` |  |  |
| `onPageIndexChange` | `Change<number>` |  |  |
| `selectable` | `boolean \| ((row: TData) => boolean)` |  | A checkbox on every row, or a function deciding per row. |
| `bulkActions` | `(selection: DataGridSelection<TData>) => ReactNode` |  | The selection bar's actions. |
| `rowActions` | `(row: TData) => DataGridRowAction<TData>[]` |  | Each row's actions: `inline` ones show as icon buttons on hover, and all are in its "…" menu. |
| `onRowOpen` | `(row: TData) => void` |  | Enter on a row (or a click on its name) opens it. |
| `onRowClick` | `(row: TData) => void` |  | A click on a row (or card), anywhere but its own controls (checkbox, actions, links, detail panel) and not while text is selected. Keyboard opens go through `onRowOpen`. |
| `renderDetail` | `(row: TData) => ReactNode` |  | A detail panel under a row, opened from its chevron (or Enter, when rows don't open). |
| `activeRowId` | `string \| null` |  | The row open elsewhere (in a side panel or a drawer): it keeps the selection's tint and bar, and `aria-current`. Default: none. |
| `density` | `'compact' \| 'comfortable' \| 'spacious'` |  |  |
| `defaultDensity` | `'compact' \| 'comfortable' \| 'spacious'` |  | Default: `compact` inside a compact layout density (YoujProvider's `density`), else `comfortable`. |
| `onDensityChange` | `Change<DataGridDensity>` |  |  |
| `striped` | `boolean` |  | Alternate rows take a faint tint, instead of hairlines alone. |
| `enableMultiSort` | `boolean` | `true` | Shift+click on a header adds it to the sort. |
| `enableColumnResizing` | `boolean` | `true` | Drag a header's edge to resize its column. |
| `pinFirstColumn` | `boolean` | `true` | Pins the first column (the identity) while the grid scrolls sideways. |
| `search` | `boolean \| { placeholder?: string; shortcut?: string \| false }` | `true` | A search over every visible column. |
| `filters` | `boolean` | `true` | The Filter menu, for columns that filter (status, tags, people…). |
| `grouping` | `boolean` | `true` | The Group menu, for columns that group. |
| `columnsMenu` | `boolean` | `true` | The Columns menu: show, hide and reorder. |
| `densitySwitch` | `boolean` | `true` | The density switch. |
| `views` | `ReadonlyArray<DataGridView>` |  | Saved views, as tabs over the toolbar. |
| `activeView` | `string` |  |  |
| `defaultActiveView` | `string` |  |  |
| `onActiveViewChange` | `Change<string>` |  |  |
| `pageSize` | `number \| false` | `25` | Rows per page, or false for every row. Grouped rows aren't paged: groups fold instead. |
| `virtualize` | `boolean` | `false` | Renders only the rows in view, for thousands of rows. Needs a `height`. Paging is off. |
| `height` | `number \| string` |  | The scroll area's height: the header sticks and virtualized rows scroll inside it. |
| `maxHeight` | `number \| string` |  |  |
| `onEndReached` | `() => void` |  | Called when a virtualized grid scrolls to its end: load the next rows. |
| `loadingMore` | `boolean` |  | Rows are on their way (with `onEndReached`): skeleton rows follow the last. |
| `loading` | `boolean` | `false` | No rows yet: skeleton rows that resolve into the data. With rows: a progress line, and nothing moves. |
| `skeletonRows` | `number` |  |  |
| `error` | `ReactNode` |  | Replaces the rows with an error panel. A string is its message. |
| `onRetry` | `() => void` |  |  |
| `empty` | `DataGridEmpty` |  | The empty state: its title, description, an illustration or icon, and an action. |
| `layout` | `'auto' \| 'table' \| 'cards'` |  | `auto` lays rows out as cards when the grid is narrower than `cardsBelow`. Default auto. |
| `cardsBelow` | `number` | `640` | The width (px) under which `auto` shows cards. |
| `toolbar` | `ReactNode` |  | The start of the toolbar: a scope switch, a count. |
| `actions` | `ReactNode` |  | The end of the toolbar: "New customer". |
| `now` | `number \| Date` |  | The moment relative dates count from. Default: the browser's clock, each minute. |
| `theme` | `ThemeInput` |  | Wraps the grid in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another page: the grid alone, at its natural width (72rem at 100% scale) unless `fill`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width. |
| `copy` | `Partial<DataGridCopy>` |  | Any of the grid's strings, to rewrite or translate. `noun` names the rows ("customers"). A locale pack on YoujProvider translates the rest. |
| `locale` | `string` |  | Formats its numbers and dates (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `search`, `justNow`, `actions`, `clearFilters`, `views`, `copied`, `copyFailed`, `searchPlaceholder`, `selectRow`, `selected`, `columns`, `noItems`, `tryAgain`, `sortBy`, `clearSelection`, `clearSearch`, `clearAll`, `activeFilters`, `removeFilter`, `row`, `itemCount`, `loadFailed`, `pagination`, `noMatches`, `emptyHint`, `escKey`, `trendUp`, `trendDown`, `trendFlat`, `rowNumber`, `toggleColumns`, `resetColumns`, `sortAscending`, `sortDescending`, `rowActions`, `rowDensity`, `compactRows`, `comfortableRows`, `filterBy`, `filterNoOptions`, `clearFilter`, `previousPage`, `nextPage`, `rangeOf`, `pageOf`, `selectionActions`, `selectAllCount`, `selectAllRows`, `selectAllOnPage`, `sortedBy`, `sortedColumn`, `sortCleared`, `selectionCleared`, `selectedRows`, `matchCount`, `totalCount`, `cellOf`, `gridHintArrows`, `gridHintSelect`, `gridHintSort`, `noMatchesHint`, `spaciousRows`, `groupBy`, `noGrouping`, `groupedBy`, `groupingCleared`, `showDetails`, `hideDetails`, `copyValue`, `addFilter`, `booleanYes`, `booleanNo`, `valueOfMax`, `gridHintOpen`, `groupTotal`, `noun`.

### Data table

The engine the others are built on. Give it your columns and rows and it handles the rest: sorting that glides rows into place, a filter for each column you declare (values with counts, ranges, dates) shown as chips, search, saved views, header menus to sort, pin, move and hide, resizing, density, CSV export, row selection with an action bar, inline editing that saves optimistically and rolls back, server mode and virtualization for thousands of rows. Arrow keys move between cells, as in a spreadsheet.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-data-table
```

It brings `badge`, `button`, `checkbox`, `content-swap`, `data-table`, `icon-check-circle`, `icon-circle-alert`, `icon-circle-dashed`, `icon-circle-x`, `icon-copy`, `icon-download`, `icon-external-link`, `icon-inbox`, `icon-loader-ring`, `icon-rotate-ccw`, `icon-rotate-cw`, `icon-search-x`, `icon-trash`, `presence-list`, `skeleton`, `use-announcer`, `youj-core`, `youj-labels`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DataTable, type DataTableProps } from '@/blocks/tables/data-table'

export function DataTableView({ initialState, pageSizeOptions, density }: Pick<DataTableProps, 'initialState' | 'pageSizeOptions' | 'density'>) {
  return (
    <DataTable
      initialState={initialState}
      pageSizeOptions={pageSizeOptions}
      density={density}
      onSortingChange={() => {
        // your code
      }}
      onPaginationChange={() => {
        // your code
      }}
      onRowSelectionChange={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `ReadonlyArray<TData>` |  | The records, one per row. Default: 48 deployments, with the demo's columns. |
| `columns` | `ReadonlyArray<DataTableColumnDef<TData>>` |  | The columns, from `createDataTableColumnHelper` (`@youj/react/data-table`). Default: the deployments' Commit, Status, Environment, Duration and Created. |
| `getRowId` | `(row: TData, index: number) => string` |  | Stable row identity. Strongly recommended: selection, editing and row animation key on it. |
| `getRowLabel` | `(row: TData) => string` |  | Names a row for its checkbox and for announcements: "ORD-1042". Default: its first column's value. |
| `title` | `ReactNode` |  | The heading over the table. Without one the table stands alone, named by `label`. Default: "Deployments" with the demo's rows. |
| `description` | `ReactNode` |  | A line under the title. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when `embedded`. |
| `actions` | `ReactNode` |  | Buttons at the end of the title row: "New deployment". |
| `label` | `string` |  | The grid's accessible name, when it has no `title`. |
| `aria-labelledby` | `string` |  | Identifies the element (or elements) that labels the current element. |
| `initialState` | `DataTableInitialState` |  | Starting state for every uncontrolled slice. |
| `state` | `Partial<DataTableState>` |  | Controlled slices. Pair each with its change callback. |
| `onSortingChange` | `Change<SortingState>` |  |  |
| `onPaginationChange` | `Change<PaginationState>` |  |  |
| `onRowSelectionChange` | `Change<RowSelectionState>` |  |  |
| `onColumnFiltersChange` | `Change<ColumnFiltersState>` |  |  |
| `onGlobalFilterChange` | `Change<string>` |  |  |
| `onColumnSizingChange` | `Change<ColumnSizingState>` |  |  |
| `onColumnPinningChange` | `Change<ColumnPinningState>` |  |  |
| `onColumnVisibilityChange` | `Change<ColumnVisibilityState>` |  |  |
| `onColumnOrderChange` | `Change<ColumnOrderState>` |  |  |
| `manual` | `boolean` |  | Server mode: sorting, filtering and pagination happen outside. Pass one page of `rows` and the `rowCount`. |
| `rowCount` | `number` |  | Rows behind the current page, in server mode. |
| `enableRowSelection` | `boolean \| ((row: TData) => boolean)` |  | Adds a checkbox column. A function decides per row. |
| `enableSorting` | `boolean` |  |  |
| `enableMultiSort` | `boolean` | `true` | Shift+click (Shift+Enter) adds a column to the sort. |
| `enableColumnResizing` | `boolean` |  |  |
| `paginated` | `boolean` |  | Client-side pages. Default true (off when virtualized). |
| `pageSizeOptions` | `readonly number[]` |  |  |
| `virtualize` | `boolean` | `false` | Renders only the rows in view, for thousands of rows. Needs a `height`. |
| `height` | `number \| string` |  | The scroll area's height. Sticky headers and virtualization scroll inside it. |
| `maxHeight` | `number \| string` |  |  |
| `density` | `'compact' \| 'standard' \| 'comfortable'` |  |  |
| `defaultDensity` | `'compact' \| 'standard' \| 'comfortable'` |  | Default: `compact` inside a compact layout density (YoujProvider's `density`), else `standard`. |
| `onDensityChange` | `Change<DataTableDensity>` |  |  |
| `showDensityToggle` | `boolean` | `true` | The density switch in the toolbar. |
| `exportable` | `boolean \| { filename?: string }` |  | An Export button in the toolbar (all rows in view order) and in the selection bar. |
| `loading` | `boolean` | `false` | Loading with no rows shows skeleton rows that resolve into the data; with rows, they stay (surfaces a step darker, text at full contrast) under a progress line. |
| `skeletonRows` | `number` |  |  |
| `error` | `ReactNode` |  | Replaces the rows with an error panel. A string is its message. |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no rows. |
| `search` | `boolean \| { placeholder?: string; debounce?: number; shortcut?: string \| false }` |  | A search field above the grid, filtering every column as you type. |
| `showFilters` | `boolean` | `true` | A filter key for every column with `meta.filter`, and chips for the ones set. |
| `showColumnsMenu` | `boolean` | `true` | The Columns menu: show, hide and reset columns. |
| `headerMenus` | `boolean` | `true` | A menu on every header (sort, pin, move, hide): its chevron, a right-click, or Alt+↓ on the header. |
| `views` | `ReadonlyArray<DataTableView>` |  | Saved views: named filters, sort, columns and density. Enables the view switcher. |
| `onViewsChange` | `(views: DataTableView[]) => void` |  | Called with the new list whenever a view is saved, updated or deleted. Persist it. |
| `activeViewId` | `string \| null` |  |  |
| `defaultActiveViewId` | `string \| null` |  |  |
| `onActiveViewChange` | `Change<string \| null>` |  |  |
| `onActiveCellChange` | `(cell: DataTableActiveCell \| null) => void` |  | The cell the keyboard is on moved (arrows, a click, focus coming back); `null` on a header. A formula bar, a status line. |
| `onCellEdit` | `(edit: DataTableCellEdit<TData>) => void \| Promise<unknown>` |  | Commits an inline edit. Return a promise to show saving; a rejection rolls the cell back. |
| `bulkActions` | `(selection: DataTableSelection<TData>) => ReactNode` |  | Actions for the current selection, rendered in the selection bar. |
| `toolbar` | `ReactNode \| ((table: DataTableInstance<TData>) => ReactNode)` |  | Content at the start of the toolbar: a title, filters, a search. |
| `theme` | `ThemeInput` |  | Wraps the table in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another page: the table alone, at its natural width (72rem at 100% scale) unless `fill`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width. |
| `copy` | `Partial<DataTableCopy>` |  | Any of the table's strings, to rewrite or translate. `noun` names the rows ("orders"). A locale pack on YoujProvider translates the rest. |
| `locale` | `string` |  | Formats its counts (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `search`, `clearFilters`, `saved`, `saving`, `selectRow`, `noItems`, `tryAgain`, `columnWidth`, `export`, `row`, `loadFailed`, `noMatches`, `emptyHint`, `loadingNamed`, `rowNumber`, `quoted`, `filterFrom`, `filterUntil`, `pageOf`, `selectAllRows`, `selectAllOnPage`, `sortedBy`, `sortedColumn`, `sortCleared`, `selectionCleared`, `selectedRows`, `matchCount`, `totalCount`, `cellOf`, `cellSaved`, `cellSaveFailed`, `gridHintArrows`, `gridHintSelect`, `gridHintEdit`, `gridHintSort`, `gridHintResize`, `gridHintMenu`, `noMatchesHint`, `noun`.

### Records table

People you work through, shown as a sales pipeline: each record's organization, stage, amount, owner, tags and last touch, in views you define (everyone, yours, hot leads, customers). Move a record to another stage from its own row, open it for its details, or select a few to email, assign, tag, export or delete them. The stories also show job candidates and patient follow-ups.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-records
```

It brings `alert`, `async-button`, `badge`, `button`, `dropdown-menu`, `icon-building`, `icon-calendar`, `icon-chevron-down`, `icon-download`, `icon-mail`, `icon-map-pin`, `icon-pencil`, `icon-phone`, `icon-plus`, `icon-tag`, `icon-trash`, `icon-upload`, `icon-user`, `icon-user-plus`, `icon-users`, `tables-data-grid`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { RecordsTable, type RecordsTableProps } from '@/blocks/tables/records'

export function RecordsTableView({ records, stages, owners, tags }: Pick<RecordsTableProps, 'records' | 'stages' | 'owners' | 'tags'>) {
  return (
    <RecordsTable
      records={records}
      stages={stages}
      owners={owners}
      tags={tags}
      copy={{ title: 'Contacts' }}
      onViewChange={(view) => {
        // your code
      }}
      onStageChange={async (record, stage) => {
        // await your API here; the block shows progress until it settles
      }}
      onRecordOpen={(record) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `records` | `RecordsTableRecord[]` |  | The people, one row each. A new array replaces the rows. Default: 36 demo records. |
| `stages` | `RecordsTableStage[]` | `Lead, Contacted, Qualified, Customer, Churned` | The funnel's stages, in order: the Stage menu, its filter and its sort. |
| `owners` | `RecordsTableOwner[]` | `four demo teammates` | The teammates who own records: the Owner column and Assign. |
| `tags` | `Record<string, { label: string; tone?: DataGridOptionTone }>` | `Hot, Champion, Decision maker, On trial, Met at event` | The tags a record can carry, by key. |
| `activities` | `RecordsTableActivityKind[]` | `email, call, meeting, note` | The kinds of last touch, with the icon beside the date. |
| `views` | `RecordsTableView[]` | `all, mine, hot leads, customers` | The tabs, each the records that match what it names. |
| `scoreLowIsBetter` | `boolean` | `false` | Reads the score as a risk: a low one is the good one. |
| `me` | `string` | `the first owner` | The signed-in teammate's id: the `owner: 'me'` view. |
| `view` | `string` |  | The open view's id (controlled). |
| `defaultView` | `string` | `'all'` | The view open at first. |
| `onViewChange` | `(view: string) => void` |  |  |
| `currency` | `string` | `'USD'` | The currency of open deals. |
| `now` | `number \| Date` | `the demo's fixed moment, so server and browser agree` | The moment relative dates count from. |
| `onStageChange` | `(record: RecordsTableRecord, stage: string) => Promise<unknown> \| unknown` |  | A record's stage changed in its cell. It shows at once; a rejection puts the old stage back and shows its message. Default: a demo save. |
| `onRecordOpen` | `(record: RecordsTableRecord) => void` |  | Enter on a row, or a click on its name. Default: its detail panel opens. |
| `onEmail` | `(record: RecordsTableRecord) => Promise<unknown> \| unknown` |  | Email, from a row or its panel. Default: a demo wait. |
| `onAssign` | `(records: RecordsTableRecord[], owner: string) => Promise<unknown> \| unknown` |  | Assign, from a row or the selection. Default: assigned here only. |
| `onTag` | `(records: RecordsTableRecord[], tag: string) => Promise<unknown> \| unknown` |  | Tag, from the selection. Default: tagged here only. |
| `onExport` | `Many` |  | Export the selection. Default: a demo wait. |
| `onDelete` | `Many` |  | Delete: the rows leave at once and come back if it rejects. Default: deleted here only. |
| `onCreate` | `() => Promise<unknown> \| unknown` |  | The header's Add record. Default: a demo wait. |
| `onImport` | `() => Promise<unknown> \| unknown` |  | The header's Import. Default: a demo wait. |
| `actions` | `ReactNode` |  | Header buttons in place of Import and Add record. |
| `loading` | `boolean` |  |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no records. Default: the table's empty state from `copy.empty…`, with Import. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when embedded. |
| `theme` | `ThemeInput` |  | Wraps the table in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another page: the card alone, a `section` named by its title. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at 72rem. |
| `copy` | `Partial<RecordsTableCopy>` |  | Any of the table's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats its counts, money and dates (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `title`, `description`, `noun`, `search`, `add`, `import`, `columns`, `changeStage`, `stageChanged`, `stageFailed`, `actions`, `bulk`, `deleted`, `people`, `failed`, `dismiss`, `detail`, `emptyTitle`, `emptyDescription`, `demoData`.

### Bulk actions table

Rows worked in bulk, shown as a store's orders. Select some and the selection bar becomes a command bar: the actions you define (here fulfill, print labels, mark as paid, refund after a confirmation that names the count, archive or export), each with its own key and all of them in a menu you can search. The statuses, channels and actions are your data. Every action shows at once and goes back, with the reason, if your app refuses it. The stories also show expense reports and library holds.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-bulk-actions
```

It brings `alert`, `async-button`, `avatar`, `badge`, `button`, `command`, `data-table`, `icon-archive`, `icon-arrow-up-right`, `icon-check-circle`, `icon-circle-alert`, `icon-circle-dashed`, `icon-circle-x`, `icon-clock`, `icon-command`, `icon-download`, `icon-globe`, `icon-plus`, `icon-printer`, `icon-rotate-ccw`, `icon-smartphone`, `icon-store`, `icon-truck`, `kbd`, `popover`, `tables-data-table`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { BulkActionsTable, type BulkActionsTableProps } from '@/blocks/tables/bulk-actions'

export function BulkActionsTableView({ rows, statuses, stages, channels }: Pick<BulkActionsTableProps, 'rows' | 'statuses' | 'stages' | 'channels'>) {
  return (
    <BulkActionsTable
      rows={rows}
      statuses={statuses}
      stages={stages}
      channels={channels}
      copy={{ title: 'Orders' }}
      onAction={async (id, rows) => {
        // await your API here; the block shows progress until it settles
      }}
      onFulfill={() => {
        // your code
      }}
      onPrint={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `BulkActionsTableRow[]` |  | The rows, one each. A new array replaces the rows. Default: 64 demo orders. |
| `currency` | `string` | `'USD'` | The currency amounts are in. |
| `statuses` | `BulkActionsTableStatus[]` | `paid, pending, refunded, failed` | The first status column's values, in the filter's order. |
| `stages` | `BulkActionsTableStatus[]` | `unfulfilled, partial, fulfilled, returned` | The second status column's values. |
| `channels` | `BulkActionsTableChannel[]` | `online store, iOS app, Android app, in store` | Where rows came from. |
| `actions` | `BulkActionsTableAction[]` | `fulfill, print labels, mark as paid, refund, archive, export` | What the selection can do, with its keys. |
| `onAction` | `(id: string, rows: BulkActionsTableRow[]) => Promise<unknown> \| unknown` |  | Runs any action that has no `on…` of its own, with the selected rows. Default: a demo wait. |
| `onFulfill` | `Many` |  | The `fulfill` action. Default: fulfilled here only. |
| `onPrint` | `Many` |  | Print shipping labels for the selection. Default: a demo wait. |
| `onMarkPaid` | `Many` |  | Mark the selection as paid. Default: marked here only. |
| `onRefund` | `Many` |  | Refund the selection, after its confirmation. Default: refunded here only. |
| `onArchive` | `Many` |  | Archive the selection: the rows leave at once and come back if it rejects. Default: archived here only. |
| `onExport` | `Many` |  | Export the selection. Default: a CSV of the selected rows, downloaded. |
| `onRowOpen` | `(row: BulkActionsTableRow) => void` |  | A row's reference, or Open in its menu. Default: none. |
| `onCreate` | `() => Promise<unknown> \| unknown` |  | The header's create button. Default: a demo wait. |
| `header` | `ReactNode` |  | Header buttons in place of the create button. |
| `loading` | `boolean` |  |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no rows. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when embedded. |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another page: the card alone, a `section` named by its title. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at 72rem. |
| `copy` | `Partial<BulkActionsTableCopy>` |  | Any of the table's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats dates, counts and money (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `title`, `description`, `noun`, `search`, `create`, `columns`, `open`, `more`, `commandPlaceholder`, `commandEmpty`, `shortcutsHint`, `countOf`, `actionDone`, `failed`, `dismiss`, `emptyTitle`, `emptyHint`.

### Spreadsheet table

Rows that work like a spreadsheet, shown as a stock sheet. Edit any cell in place, and read the active cell's address and contents in the name box and formula bar (Value shows its formula). Paste a block of cells from Excel or Google Sheets and it lands from the active cell on, each value checked against its column. ⌘Z and ⇧⌘Z undo and redo, a paste as one step, and the totals row stays in view as you scroll.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-spreadsheet
```

It brings `alert`, `button`, `data-table`, `icon-function`, `icon-redo`, `icon-undo`, `input-group`, `tables-data-table`, `tooltip`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SpreadsheetTable, type SpreadsheetTableProps } from '@/blocks/tables/spreadsheet'

export function SpreadsheetTableView({ rows, categories }: Pick<SpreadsheetTableProps, 'rows' | 'categories'>) {
  return (
    <SpreadsheetTable
      rows={rows}
      categories={categories}
      copy={{ title: 'Inventory' }}
      onEdit={async (edits) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `SpreadsheetTableRow[]` |  | The rows, one each. A new array replaces the rows (undo keeps working for the rows still there). Default: 32 lines of outdoor gear. |
| `categories` | `readonly string[]` | `Apparel, Footwear, Camp, Climb, Accessories` | What Category can be. |
| `currency` | `string` | `'USD'` | The currency costs are in. |
| `onEdit` | `(edits: SpreadsheetTableEdit[]) => Promise<unknown> \| unknown` |  | Saves changed cells, an edit, a paste, an undo or a redo at a time. A rejection puts them back. Default: kept here only. |
| `actions` | `ReactNode` |  | Header buttons beside Undo and Redo. |
| `loading` | `boolean` |  |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no rows. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when embedded. |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another page: the card alone, a `section` named by its title. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at 72rem. |
| `copy` | `Partial<SpreadsheetTableCopy>` |  | Any of the sheet's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats and reads numbers and money (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `title`, `description`, `noun`, `columns`, `formulaBar`, `nameBox`, `formulaLabel`, `formulaPlaceholder`, `low`, `total`, `lowCount`, `undo`, `redo`, `undid`, `redid`, `changed`, `cells`, `pasted`, `skipped`, `copied`, `wholeNumber`, `amount`, `required`, `unknownCategory`, `failed`, `dismiss`, `emptyTitle`, `emptyHint`.

### Grouped table

Planned against spent as a tree, shown as a budget. Lines gather the ways you define (the demo: by team inside their department, by category or by owner), and every group sums its plan, its spend, how far over or under it runs and how much it has used, down to a grand total. Open a group and its lines slide in under it; sort a money column and every level sorts inside itself.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-grouped
```

It brings `button`, `icon-arrow-down`, `icon-arrow-up`, `icon-chevron-right`, `icon-chevrons-up-down`, `icon-list-collapse`, `presence-list`, `progress`, `segmented-control`, `skeleton`, `tooltip`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { GroupedTable, type GroupedTableProps } from '@/blocks/tables/grouped'

export function GroupedTableView({ lines, groupings }: Pick<GroupedTableProps, 'lines' | 'groupings'>) {
  return (
    <GroupedTable
      lines={lines}
      groupings={groupings}
      copy={{ title: 'Operating budget' }}
      onGroupByChange={(groupBy) => {
        // your code
      }}
      onLineOpen={(line) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `GroupedTableLine[]` |  | The lines, planned and spent each. Default: a software company's quarter, 28 lines in four departments. |
| `groupings` | `GroupedTableGrouping[]` | `team (department then team), category, owner, none` | The ways to gather the lines, each a choice in the header. |
| `groupBy` | `string` |  | The grouping's id (controlled). Pair with `onGroupByChange`. |
| `defaultGroupBy` | `string` |  | The grouping's id at first. Default: the first of `groupings`. |
| `onGroupByChange` | `(groupBy: string) => void` |  |  |
| `currency` | `string` | `'USD'` | The currency the money is in. |
| `format` | `(value: number) => string` |  | Formats the amounts, the totals and the variance's size (hours, points…). Default: the money in `currency`. |
| `onLineOpen` | `(line: GroupedTableLine) => void` |  | A line's row clicked, or Enter on it: open its detail. Default: none. |
| `actions` | `ReactNode` |  | Header buttons beside the grouping. |
| `loading` | `boolean` |  |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no lines. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when embedded. |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another page: the card alone, a `section` named by its title. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at 72rem. |
| `copy` | `Partial<GroupedTableCopy>` |  | Any of the table's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats money and counts (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `title`, `period`, `description`, `columns`, `groupBy`, `expandAll`, `collapseAll`, `lines`, `total`, `over`, `under`, `sortBy`, `expanded`, `collapsed`, `treeHint`, `retry`, `emptyTitle`, `emptyHint`.

### Logs

A live event stream, virtualized for thousands of rows. Read from the top and it follows new events as they glow in; scroll down or pause and it holds still, counting what's waiting in a pill that takes you back up. Arrow through the events and the inspector beside them shows each one in full: request, duration and its payload as JSON to copy.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add tables-logs
```

It brings `badge`, `button`, `code-block`, `data-table`, `icon-arrow-up`, `icon-braces`, `icon-circle-pause`, `icon-play`, `icon-x`, `tables-data-table`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { LogsTable, type LogsTableProps } from '@/blocks/tables/logs'

export function LogsTableView({ events }: Pick<LogsTableProps, 'events'>) {
  return (
    <LogsTable
      events={events}
      copy={{ title: 'Logs' }}
      onPausedChange={(paused) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `LogsTableEvent[]` |  | The events, oldest first; append to stream. A new array updates the table (held while someone reads further down). Default: a simulated stream. |
| `paused` | `boolean` |  | Holds the view still, counting what arrives. Pair with `onPausedChange`. |
| `defaultPaused` | `boolean` | `false` |  |
| `onPausedChange` | `(paused: boolean) => void` |  |  |
| `actions` | `ReactNode` |  | Header buttons after Live. |
| `loading` | `boolean` |  |  |
| `error` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Shown when there are no events. |
| `demoMarker` | `boolean` | `true` | The dashed `Demo data` badge shown while the stream is simulated. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | The title's level when embedded. |
| `theme` | `ThemeInput` |  |  |
| `embedded` | `boolean` | `true` | Inside another page: the card alone, a `section` named by its title. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at 72rem. |
| `copy` | `Partial<LogsTableCopy>` |  | Any of the stream's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats times and counts (BCP 47). Default: the app's locale (YoujProvider). |

**Strings:** `copy` takes `title`, `description`, `noun`, `search`, `columns`, `levels`, `live`, `paused`, `pauseStream`, `resumeStream`, `newEvents`, `showNew`, `waitingAbove`, `inspector`, `inspectHint`, `closeInspector`, `request`, `duration`, `payload`, `copyJson`, `ms`, `demoData`, `emptyTitle`, `emptyHint`.

### Audit log

See who did what with a searchable, sortable audit log; a row opens the event in a sheet. How events end and their kinds are your data (the stories show a workspace, a clinic's records access and a shared drive). Embedded, it sits as a section inside a settings page.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-audit-log
```

It brings `avatar`, `badge`, `button`, `code-block`, `data-table`, `empty`, `icon-arrow-right`, `icon-key`, `icon-shield-check`, `icon-sparkle`, `reveal`, `sheet`, `tables-data-table`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { AuditLog, type AuditLogProps } from '@/blocks/app/audit-log'

export function AuditLogView({ events, actors, results, categories }: Pick<AuditLogProps, 'events' | 'actors' | 'results' | 'categories'>) {
  return (
    <AuditLog
      events={events}
      actors={actors}
      results={results}
      categories={categories}
      copy={{ title: 'Audit log' }}
      onRetry={() => {
        // your code
      }}
      onOpen={(event) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Default: the host's theme. |
| `embedded` | `boolean` | `false` | A view inside another app (a settings page): a `section` named by an `h2` instead of the page's `main` and `h1`, and no page height, width or padding, so the host lays it out. |
| `events` | `AuditEvent[]` | `sample events` | The events, newest first or not: the table sorts by time. |
| `actors` | `Record<string, AuditActor>` | `the demo's people, API key and system` | Who can appear as an event's `actor`, by id. |
| `results` | `AuditResult[]` | `success, denied, failed` | How events end, with their badge tone and whether the summary counts them as flagged. |
| `categories` | `AuditCategory[]` | `members, security, billing, projects, sign-in` | The kinds of event, a choice in the Type filter. |
| `copy` | `Partial<AuditLogCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the English demo copy. |
| `loading` | `boolean` | `false` | Shows skeleton rows while the events load. |
| `empty` | `ReactNode` |  | Replaces the empty state shown when there are no events. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `error` | `ReactNode` |  | Replaces the rows with an error panel; a string is its message. Default: none. |
| `onRetry` | `() => void` |  | Adds a Retry button to the error panel. Default: none. |
| `onOpen` | `(event: AuditEvent) => void` |  | Called when an event's details open, with the event. Default: none. |
| `locale` | `string` |  | Formats the events' times (always in UTC). Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` |  | The page heading's level. Default: 1, or 2 when `embedded`. |
| `className` | `string` |  | Classes for the page's root element, merged with its own. Default: none. |

**Strings:** `copy` takes `title`, `summary`, `retention`, `tableLabel`, `noun`, `searchPlaceholder`, `exportFilename`, `emptyTitle`, `emptyDescription`, `timeZone`, `time`, `date`, `actor`, `event`, `type`, `result`, `location`, `action`, `target`, `client`, `changes`, `changedTo`, `raw`, `copyRaw`, `close`.

### Cause log

Recent events with a duration as a table to filter by cause and sort, with a last-24-hours strip per source: a mark for every entry in its cause's color and a line at now. Tick entries and Assign cause files them all under one cause. Shown with a plant's downtime; stories also use support escalations and clinic delays. `format` sets how durations read and `longAfter` where an entry counts as long.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-cause-log
```

It brings `alert`, `button`, `card`, `checkbox`, `dropdown-menu`, `empty`, `select`, `skeleton`, `table`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { CauseLog, type CauseLogProps } from '@/blocks/app/cause-log'

export function CauseLogView({ entries, causes }: Pick<CauseLogProps, 'entries' | 'causes'>) {
  return (
    <CauseLog
      entries={entries}
      causes={causes}
      copy={{ title: 'Downtime log' }}
      onRetry={() => {
        // your code
      }}
      onAssign={(entryIds, causeId) => {
        // your code
      }}
      onSortChange={(sort) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `window`, `filterLabel`, `allReasons`, `sortLabel`, `sortNewest`, `sortLongest`, `tableLabel`, `selectAll`, `selectRow`, `started`, `reason`, `durationHead`, `duration`, `empty`, `lastDay`, `now`, `timelineLabel`, `selected`, `assign`, `assigned`, `loadingLabel`, `retry`.

### Preview list

Things with a picture, listed with search, sort and a create button above: a picture of each, its name and status, where to find it, who made it and when, and its latest activity, with Details as the one primary button and Visit, Activity and Settings as icon buttons with tooltips. The statuses and the pictures it draws are your data; the stories show workspace projects, real estate listings and a course catalog.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-preview-list
```

It brings `avatar`, `button`, `card`, `empty`, `icon-arrow-up-right`, `icon-folder`, `icon-git-branch`, `icon-globe`, `icon-plus`, `icon-rocket`, `icon-search`, `icon-settings`, `input-group`, `select`, `skeleton`, `tooltip`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { PreviewList, type PreviewListProps } from '@/blocks/app/preview-list'

export function PreviewListView({ items, statuses, looks }: Pick<PreviewListProps, 'items' | 'statuses' | 'looks'>) {
  return (
    <PreviewList
      items={items}
      statuses={statuses}
      looks={looks}
      copy={{ title: 'Projects' }}
      onSortChange={(sort) => {
        // your code
      }}
      onCreate={() => {
        // your code
      }}
      onOpen={(project, view) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `count`, `searchLabel`, `searchPlaceholder`, `sortLabel`, `sortActivity`, `sortName`, `sortCreated`, `create`, `details`, `visit`, `activity`, `settings`, `more`, `createdBy`, `emptyTitle`, `emptyDescription`, `noMatchTitle`, `noMatchDescription`, `loading`, `error`, `retry`.

### Transfer list

A panel for transfers in flight: overall progress, rate and time left, then a row per item with pause, resume and cancel. Failed items say why and offer Retry, and finished ones sink to the foot. `format` writes sizes and rates in your own unit, so it counts rows for a table migration or frames for video exports as well as bytes for a file sync, and loading, error and empty take the rows' place at the card's size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-transfer-list
```

It brings `alert`, `button`, `card`, `empty`, `icon-cloud-upload`, `icon-more-horizontal`, `progress-list`, `skeleton`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { TransferList, type TransferListProps } from '@/blocks/app/transfer-list'

export function TransferListView({ items, format }: Pick<TransferListProps, 'items' | 'format'>) {
  return (
    <TransferList
      items={items}
      format={format}
      copy={{ title: 'Transfers' }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `overall`, `items`, `status`, `settled`, `pauseAll`, `resumeAll`, `cancelAll`, `connectionReset`, `emptyTitle`, `emptyBody`, `loadingLabel`, `retry`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Building your own

Contacts, Orders and Inventory are the Data table with columns, copy and a header of their own, and Logs is the Data table virtualized beside an inspector: read them to see how a domain table is put together. For a table of your own, start from the Data table and pass `rows` and `columns` (made with `createDataTableColumnHelper` from `@youj/react/data-table`). For data that lives on a server, pass `manual` with one page of `rows` and the `rowCount`, and own the sorting, filters and pages through `state` and their `on…Change` callbacks.

The parts these tables are made of are components: the [Table](https://www.youj.dev/docs/components/table) primitives and the [Data table kit](https://www.youj.dev/docs/components/data-table) (column header, toolbar, search, filters and chips, view options, pagination, selection column and bar, saved views, the cell editor, the keyboard grid and CSV export), from `@youj/react/data-table`. Use them when a table needs a layout the engines don't have.

### Accessibility

The Data table and the tables built on it are a native `<table role="grid">` named by their title, and a single Tab stop: the arrow keys move between cells, Home and End to a row's ends, Ctrl+Home and Ctrl+End to the corners, Page Up and Page Down a screen at a time. Space selects a row (Shift+Space a range), Ctrl+A or ⌘A every row and Escape clears the selection; Enter, F2 or typing edits a cell, Alt+↓ opens a header's menu and Shift+←/→ resizes a column. The keys are listed in the grid's description. `aria-rowcount` and `aria-rowindex` keep every row's place when the table is paged or virtualized, headers carry `aria-sort`, and selection uses `aria-multiselectable` and `aria-selected`. Saves, rollbacks, sorting and selection are announced in a live region.

In Orders the command bar is a group named "Selection actions"; each action's key is in its `aria-keyshortcuts`, and a refund asks first in an alert dialog that names the count. In Inventory the name box is an output named "Cell", the formula bar is named for the cell it edits ("Contents of E7"), a value that doesn't fit is described on the field with `aria-invalid`, and undo, redo, copy and paste are announced. Low stock is said in words, not only in amber. The stories show other worlds, with their own names and words.

Budget is a `treegrid`: every row carries `aria-level`, `aria-posinset` and `aria-setsize`, groups `aria-expanded`. Up and Down move between rows, Right opens a group (or moves into it), Left closes it (or moves to its parent), mirrored in right-to-left text, and Enter opens a line. Variance is read as over or under budget, and opening or closing a group is announced. The stories show other worlds, with their own names and words.

Logs keeps the inspector in a complementary region named "Event". The pill for waiting events is a button, and a polite status says once that events are waiting rather than counting each one. Levels are written out, so color is never the only signal.

Cause log lists the entries in a real table with a tick per row and one for all; every tick is named for its source and the time. Each source's strip is an image whose text gives its entries and total in the last 24 hours, and Assign cause is a menu that stays disabled until a stop is ticked and announces the result.

Preview list is a labelled list of projects; each row names its status in words (the dot only echoes it), its picture is decorative, and the icon buttons carry the project's name in their labels and tooltips. Search and sort are named controls, and the list scrolls inside the card so a search never resizes it.

Transfer list groups the overall meter under a label, and every row is a named progress bar with pause, resume, cancel and retry buttons named for the item. While it loads the skeletons are one named status.

Under reduced motion rows change in place instead of gliding, the waiting-events pill appears without moving, the live dot stops pulsing and groups open at once.

---

# Timelines & steps

> Things that move through stages: event timelines, trackers, pipelines, traces, rollouts, gates, paths and roadmaps.

Source: https://www.youj.dev/docs/blocks/timelines-and-steps

## Blocks

### Event timeline

Something in progress as one card: a status pill, a level of urgency and a ticking open time, the time each phase took to reach, what it touches with a rate each, and a timeline of entries. Step it through your own phases (Acknowledge, Mitigate, Resolve; or Triage, Treat, Discharge), or raise its level.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-event-timeline
```

It brings `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `icon-more-horizontal`, `severity-timeline`, `share-bar`, `typography`, `use-announcer`, `use-controllable-state`, `use-now`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { EventTimeline, type EventTimelineProps } from '@/blocks/app/event-timeline'

export function EventTimelineView({ event, phases, severities, statuses }: Pick<EventTimelineProps, 'event' | 'phases' | 'severities' | 'statuses'>) {
  return (
    <EventTimeline
      event={event}
      phases={phases}
      severities={severities}
      statuses={statuses}
      copy={{ more: 'More actions' }}
      onPhaseChange={(phase) => {
        // your code
      }}
      onSeverityChange={(severity) => {
        // your code
      }}
      onAdvance={async (phase) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (736px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's heading level; the block's own sections sit one under it. Default 1, or 2 when `embedded`. |
| `locale` | `string` |  | Formats durations and clock times. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `copy` | `Partial<EventTimelineCopy>` |  | Any of the block's UI strings, to rewrite or translate. The event's own words are in `event`. |
| `event` | `EventTimelineEvent` | `the demo's INC-2817 on checkout-api` | The event: its id, title, subject, lead and start. |
| `phases` | `EventTimelinePhase[]` | `triggered, acknowledged, mitigated, resolved` | The stages it passes through, in order: the first is where it starts, the last closes it. |
| `severities` | `EventTimelineSeverity[]` | `SEV1 to SEV4` | Levels of urgency, most urgent first (level 1), at most four. |
| `statuses` | `EventTimelineStatus[]` | `down, degraded, operational` | How an item reads from its rate, worst first. |
| `scale` | `number` | `0.4` | The rate (0–1) at which an item's bar is full. |
| `format` | `{ rate?: (rate: number) => string }` |  | Writes an item's rate (0–1). Default: a percentage with one decimal in the locale. |
| `phase` | `string` |  | The id of the phase it is in, when your app owns it; pair with `onPhaseChange`. The block adds milestone entries only when its own action moves it. |
| `defaultPhase` | `string` |  | The id of the phase it starts in, when the block owns it. Default: the first phase. |
| `onPhaseChange` | `(phase: string) => void` |  | Called with the new phase's id after the action that moves it has run. |
| `severity` | `1 \| 2 \| 3 \| 4` |  | Its severity, 1–4, when your app owns it; pair with `onSeverityChange`. |
| `defaultSeverity` | `1 \| 2 \| 3 \| 4` | `2` | Its severity at first, 1–4. |
| `onSeverityChange` | `(severity: SeverityLevel) => void` |  | Called with the new severity after Escalate, or when a phase eases it. |
| `entries` | `SeverityEvent[]` |  | What has happened so far, read when the block mounts (give it a new `key` to replace them). Default: the demo's four, opened 12 minutes before `now`. |
| `items` | `EventTimelineItem[]` | `the demo's three` | What it touches, each with its rate per phase. |
| `now` | `Date \| number` |  | The time the block first renders at, in ms, which the server and the browser agree on; the clock ticks on from it once mounted. Default: the demo's fixed time with the demo events; with your own `entries`, the browser's clock once mounted. |
| `timeZone` | `string` |  | Clock times on the timeline in this zone, e.g. "UTC"; set it when you render on the server. Default: the browser's. |
| `live` | `boolean` | `true` | Keep the demo alive: new demo alerts arrive until someone acknowledges (never with your own `entries`). |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the block runs on the demo's entries (no `entries` passed). |
| `onAdvance` | `(phase: EventTimelinePhase) => Promise<unknown> \| unknown` |  | Moves it into the next phase, which it receives; resolve when done, reject to show the message. Default: a short demo wait. |
| `onEscalate` | `(severity: SeverityLevel) => Promise<unknown> \| unknown` |  |  |
| `onCopyLink` | `() => void` |  | The menu's Copy link. Default: nothing. |
| `onOpenRunbook` | `() => void` |  | The menu's Open runbook. Default: nothing. |
| `onPostmortem` | `() => void` |  | Start postmortem, once resolved. Default: nothing. |
| `classNames` | `{ card?: string }` |  | Classes for its parts: `card` holds the block's size (717px tall at 100%; the timeline scrolls inside it, so alerts, escalations and milestones never resize it). |

**Strings:** `copy` takes `subtitle`, `more`, `copyLink`, `demoData`, `runbook`, `open`, `closedAfter`, `notYet`, `affected`, `noItems`, `rate`, `timeline`, `entries`, `lead`, `escalate`, `escalating`, `escalated`, `escalatedDetail`, `postmortem`, `failed`, `announceEvent`, `locale`.

### Step tracker

Anything on a road of stages, replayed scan by scan on one rail: a parcel from ordered to delivered by default, a loan or a visa with your own stages. Retried stops, refusals and skipped stages are drawn too. Pick a stage for its details or another item from the tabs.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-step-tracker
```

It brings `alert`, `async-button`, `button`, `card`, `empty`, `icon-rotate-ccw`, `morph-label`, `skeleton`, `tabs`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { StepTracker, type StepTrackerProps } from '@/blocks/app/step-tracker'

export function StepTrackerView({ stages, items }: Pick<StepTrackerProps, 'stages' | 'items'>) {
  return (
    <StepTracker
      stages={stages}
      items={items}
      copy={{ title: 'Shipments' }}
      onNotify={async (item) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `items`, `replay`, `replayLabel`, `states`, `outcome`, `attemptMissed`, `lastScan`, `journey`, `summary`, `total`, `doorToDoor`, `stoppedAfter`, `attempts`, `missed`, `neverOut`, `attempt`, `tries`, `notReached`, `working`, `retrying`, `missedNote`, `skippedBecause`, `notify`, `notifying`, `handlerSite`, `attemptFailed`, `completedOnRetry`, `stopped`, `completed`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Stage pipeline

A run through ordered stages on one rail, with the selected stage's log tailing beneath it: a deploy from build to release, a bakery batch from mix to ship, an article from draft to publish. When every stage passes, Promote puts the result out; Roll back returns to what came before. The stages, the lines each prints and every word are yours.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-stage-pipeline
```

It brings `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `icon-arrow-down`, `icon-copy`, `icon-more-horizontal`, `icon-play`, `icon-rotate-ccw`, `stage-rail`, `use-announcer`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { StagePipeline, type StagePipelineProps } from '@/blocks/app/stage-pipeline'

export function StagePipelineView({ run, stages, progress }: Pick<StagePipelineProps, 'run' | 'stages' | 'progress'>) {
  return (
    <StagePipeline
      run={run}
      stages={stages}
      progress={progress}
      copy={{ more: 'More actions' }}
      onRerun={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onPromote={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onRollBack={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `rerun`, `demoData`, `copyRun`, `copied`, `state`, `total`, `revision`, `source`, `stageLabel`, `stageOf`, `log`, `lines`, `follow`, `pause`, `newLines`, `queuedLog`, `skippedLog`, `started`, `runner`, `promote`, `promoteAfter`, `promoteBlocked`, `promoting`, `promoted`, `rollBack`, `rollingBack`, `rolledBack`, `announcePromoted`, `announceRolledBack`, `locale`.

### Stage pipeline run timing

A finished run read as time: steps grouped as Build and Deploy with when each started and how long it took, a strip across the top cutting the run into its groups, and the result line. Pass each step's `previous` time and it is compared: the earlier time is a longer ghost bar where the step got faster, an overshoot in the danger tone where it got slower, and a skipped step has only the word. It is `StagePipelineRunTiming`, a second part of the Stage pipeline block: it installs with it and is imported from `blocks/app/stage-pipeline/run-timing`.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-stage-pipeline
```

```tsx
'use client'

import { StagePipeline, type StagePipelineProps } from '@/blocks/app/stage-pipeline'

**Props**

### Step trace

One run as a graph of steps lit by state as it goes, with steps, elapsed time, size and cost counting up: an AI agent, a web request or a lab sample. Pick a step for its inputs and outputs, then approve the result.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-step-trace
```

It brings `async-button`, `badge`, `button`, `card`, `code-block`, `dropdown-menu`, `flow-graph`, `icon-copy`, `icon-download`, `icon-more-horizontal`, `icon-rotate-ccw`, `icon-x`, `typography`, `use-announcer`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { StepTrace, type StepTraceProps } from '@/blocks/app/step-trace'

export function StepTraceView({ run, kinds, steps }: Pick<StepTraceProps, 'run' | 'kinds' | 'steps'>) {
  return (
    <StepTrace
      run={run}
      kinds={kinds}
      steps={steps}
      copy={{ title: 'v4.2 release notes' }}
      onApprove={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `demoData`, `subtitle`, `more`, `copyId`, `copied`, `download`, `state`, `steps`, `stepsOf`, `elapsed`, `size`, `cost`, `failed`, `graph`, `graphHint`, `status`, `closeStep`, `duration`, `sizeInOut`, `attempts`, `input`, `output`, `waiting`, `skippedOff`, `skippedAfter`, `noOutput`, `footer`, `replay`, `approve`, `approving`, `approved`, `announceFailed`, `announceDone`, `announcePublished`, `locale`.

### Case file

One case as a card: its stage on a stepper, the verdict in a sentence with its confidence and the evidence behind it as one split bar, and the chain of events step by step, each step in its source's color with its offset from the first and a ribbon that shows the pace. The primary action finishes the current stage and moves the case on (a stage that stops things ends the step still running); Dismiss closes it. The demo is a security case (Triage, Investigate, Contain, Close, with Contain account ending the step still running), and Phishing case, Insurance claim and Fraud review show the same card with other stages and verdicts.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-case-file
```

It brings `async-button`, `badge`, `card`, `severity-timeline`, `share-bar`, `stepper`, `typography`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CaseFile, type CaseFileProps } from '@/blocks/app/case-file'

export function CaseFileView({ details, signals, steps, stages }: Pick<CaseFileProps, 'details' | 'signals' | 'steps' | 'stages'>) {
  return (
    <CaseFile
      details={details}
      signals={signals}
      steps={steps}
      stages={stages}
      copy={{ dismissed: 'Dismissed' }}
      onStageChange={(stage) => {
        // your code
      }}
      onAdvance={async (stage) => {
        // await your API here; the block shows progress until it settles
      }}
      onDismiss={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (448px at 100% scale). |
| `copy` | `Partial<CaseFileCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats ages, times and shares (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `details` | `CaseFileDetails` | `demo` | The case: its reference, when it opened, who it is about and the verdict. |
| `signals` | `CaseFileSignal[]` | `demo` | The evidence behind the verdict, split by weight. |
| `steps` | `CaseFileStep[]` |  | The chain of events, in any order: it is shown oldest first. |
| `stages` | `CaseFileStage[]` |  | The stages a case moves through, in order, each with the words of its action. Default: triage, investigate, contain, close. |
| `verdicts` | `CaseFileVerdict[]` | `malicious, suspicious, benign` | The verdicts a case can carry, with the tone of their badge. |
| `formatSpan` | `(minutes: number) => string` |  | Formats the chain's span, given in minutes. Default: the locale's short minutes ("470 min"). |
| `now` | `Date \| string \| number` |  | The time the card renders at, which the server and the browser agree on. Default: the demo's fixed time with the demo steps; with your own, the browser's clock once mounted. |
| `timeZone` | `string` |  | Clock times in this zone, e.g. "UTC"; set it when you render on the server. Default: the browser's. |
| `stage` | `string` |  | The id of the stage the case is in, or `closed`, when your app owns it; pair with `onStageChange`. |
| `defaultStage` | `string` |  | The stage at first, when the card owns it. Default: `contain` for the demo's stages, else the first stage. |
| `onStageChange` | `(stage: string) => void` |  | Called with the new stage's id (`closed` after the last) once an action has run. |
| `onAdvance` | `(stage: string) => Promise<unknown> \| unknown` |  | Runs the current stage's action (given its id); the card awaits it, then moves on. |
| `onDismiss` | `() => Promise<unknown> \| unknown` |  | Closes the case as a false positive; the card awaits it. |

**Strings:** `copy` takes `opened`, `dismissed`, `stagesLabel`, `verdictTitle`, `confidence`, `signals`, `signalsLabel`, `chainTitle`, `closed`, `dismiss`, `dismissing`, `failed`, `announceStage`, `announceClosed`, `announceDismissed`.

### Staged rollout

An item's rollout on a ruler cut into stages, snapped to gate by gate per environment, with exposure, a watched rate against its guardrail and a kill switch that rolls it back to zero. Feature flags in the demo; price variants by region or a firmware wave by ring of devices read the same, with the environments, stages and words yours. Every item is listed below with its own ruler.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-staged-rollout
```

It brings `async-button`, `badge`, `button`, `card`, `dropdown-menu`, `icon-more-horizontal`, `icon-power`, `icon-rotate-ccw`, `rollout-ruler`, `segmented-control`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { StagedRollout, type StagedRolloutProps } from '@/blocks/app/staged-rollout'

export function StagedRolloutView({ items, environments, stages }: Pick<StagedRolloutProps, 'items' | 'environments' | 'stages'>) {
  return (
    <StagedRollout
      items={items}
      environments={environments}
      stages={stages}
      copy={{ title: 'Rollout' }}
      onApply={async (item) => {
        // await your API here; the block shows progress until it settles
      }}
      onStop={(item, stopped) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `more`, `copyKey`, `auditLog`, `environment`, `ruler`, `status`, `exposed`, `rate`, `guardrail`, `items`, `itemCount`, `chipState`, `select`, `saved`, `unsaved`, `stop`, `stopped`, `restore`, `apply`, `applying`, `applied`, `locale`.

### Check gate

The checks that gate a candidate before it goes through: a mobile release, a loan application, a site inspection. Its pass rate against the bar, the last candidates as lollipops and every group of checks as a row. Filter to the blocking groups, then go ahead once they clear.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-check-gate
```

It brings `async-button`, `badge`, `button`, `card`, `counter`, `presence-list`, `segmented-control`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { CheckGate, type CheckGateProps } from '@/blocks/app/check-gate'

export function CheckGateView({ candidates, groups }: Pick<CheckGateProps, 'candidates' | 'groups'>) {
  return (
    <CheckGate
      candidates={candidates}
      groups={groups}
      copy={{ title: 'Release checks' }}
      onPromote={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subject`, `ran`, `clear`, `blockingCount`, `passRate`, `delta`, `checks`, `history`, `bar`, `chartLabel`, `candidate`, `groups`, `filter`, `all`, `blocking`, `noneBlocking`, `since`, `unchanged`, `failed`, `review`, `promote`, `promoting`, `promoted`, `locale`.

### Roadmap timeline

A year of dated items on one ruler of fine ticks; the default is a product's roadmap, and a wedding or a renovation reads the same way. A pin per item, taller for the big ones, solid once done, hollow while upcoming and amber when it needs attention, with a bright tick for today and a count where items crowd one week. Hover anywhere along it (the nearest pin answers, and the ticks near the pointer stretch) or walk the pins with the arrow keys, and the callout says the date, status, title and one line about it; the one you pick stays shown. The foot says how many are done, how soon the next lands and how many need attention. Your own statuses name those figures. It has loading and error states that keep its size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-roadmap-timeline
```

It brings `alert`, `button`, `card`, `milestone-ruler`, `skeleton`, `typography`, `use-controllable-state`, `use-now`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RoadmapTimeline, type RoadmapTimelineProps } from '@/blocks/app/roadmap-timeline'

export function RoadmapTimelineView({ items, statuses }: Pick<RoadmapTimelineProps, 'items' | 'statuses'>) {
  return (
    <RoadmapTimeline
      items={items}
      statuses={statuses}
      copy={{ subtitle: 'Relay' }}
      onRetry={() => {
        // your code
      }}
      onValueChange={(id) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `count`, `rulerLabel`, `doneValue`, `next`, `none`, `loadingLabel`, `retry`.

### Interval timer

Intervals of work and rest: a ring with an arc per interval, the item at hand or a rest countdown, and a logger with count and amount steppers. Start, Pause and Skip drive the clock. The demo is an evening HIIT session; stories show focus and break cycles and a pour-over brew.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-interval-timer
```

It brings `alert`, `button`, `card`, `empty`, `field`, `icon-check`, `icon-more-horizontal`, `icon-play`, `icon-rotate-ccw`, `icon-skip-forward`, `number-input`, `presence-list`, `segmented-ring`, `share-bar`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { IntervalTimer, type IntervalTimerProps } from '@/blocks/app/interval-timer'

export function IntervalTimerView({ intervals, items, entries }: Pick<IntervalTimerProps, 'intervals' | 'items' | 'entries'>) {
  return (
    <IntervalTimer
      intervals={intervals}
      items={items}
      entries={entries}
      copy={{ title: 'Evening HIIT' }}
      onLog={(entry) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `now`, `next`, `then`, `rest`, `restHint`, `addRest`, `addRestLabel`, `skipRest`, `target`, `log`, `logLabel`, `count`, `amount`, `unit`, `noAmount`, `noEntries`, `entryNumber`, `logged`, `total`, `start`, `pause`, `resume`, `restart`, `skip`, `skipLabel`, `left`, `done`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Event timeline reads out its level of urgency (hidden text beside the badge), the timeline is a labelled list, and failed actions use `role="alert"`. The open time is not announced as it ticks.

The step tracker lists its stages as an ordered list named for the item. Each stage is a button with a full spoken label, `aria-pressed` for the one you picked and `aria-current="step"` for where the parcel is; the arrow keys move along the road, and the stage details panel is linked with `aria-controls`. The item tabs and the Replay button are named, and the decorative dots are `aria-hidden`.

In Stage pipeline each stage is a labelled toggle with its name, state and duration, and the arrow keys, Home and End move between stages. The log is `role="log"` named by its title; it is a polite live region while it follows the newest line and goes silent once you scroll up or pause.

Step trace's steps are one tab stop, arrow keys follow the flow direction, and the detail's close button is labelled.

Case file shows its stage on a Stepper whose current step is `aria-current="step"` and whose every step says its state. The signals bar is a `meter` whose value text names every signal with its share, and the key under it repeats them as text. The chain of events is a named list, oldest first, each step with its clock time, how long after the first it came, its source and what it touched; the step still running says Ongoing. Contain, Close and Dismiss announce the new stage in a polite live region, and a failed action says why in its button.

Staged rollout puts a named meter on each ruler, with the stage spoken (for example "Internal at 1%"). The playhead steps with the keyboard, the environment switch is labelled, and each item in the list is a button with `aria-pressed`. The stories show other worlds, with their own names and words.

Check gate draws its history as an image with a text alternative that gives the candidate count, how many fell under the bar and the candidate's pass rate; the lollipops themselves are `aria-hidden`. The All / Blocking filter is a named control.

Roadmap timeline draws its year as a named listbox of items, one tab stop: the arrow keys walk the pins, Home and End go to the ends, and selection follows focus. Every pin is named with its title, day and status in words ("SSO and audit log, Oct 28, At risk"), a shared pin names all of its items, and the one-line description is the pin's description; the callout repeats it visually. Status is a word and a solid, hollow or amber dot, never color alone, and the foot's figures are a description list.

In both stories the progress path is a labelled group with one tab stop, and arrow keys move between steps, with a hidden hint. The points and daily goal meters are named, the week's flames are a labelled ordered list with each day's points written out, and finishing a step is announced in a status region.

Interval timer's ring is a labelled group, and the timer is `role="timer"` with live announcements off so it does not chatter every second; the ring announces each interval and ticks through the last three seconds. Add 15 seconds and Skip rest have explicit labels.

Under reduced motion numbers, rings and the trail are drawn in place.

Each card is a `section` named by its title. Under reduced motion cells and rows change in place.

---

# Trends & comparisons

> Numbers over time and side by side: KPIs, metric charts, running totals, retention, percentiles, curves and head-to-heads.

Source: https://www.youj.dev/docs/blocks/trends-and-comparisons

## Blocks

### KPI cards

The numbers at the top of a dashboard, each with its change on the period before, as figures on hairlines, a line with last period's ghost, or a bar per bucket. Move along any tile, or focus it and use the arrow keys, and every tile reads that day at once; a dashed segment marks a day still in progress.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-kpi-cards
```

It brings `alert`, `button`, `card`, `empty`, `icon-info`, `segmented-control`, `stat-card`, `tooltip`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { KpiCards, type KpiCardsProps } from '@/blocks/app/kpi-cards'

export function KpiCardsView({ kpis, dates, granularity, ranges }: Pick<KpiCardsProps, 'kpis' | 'dates' | 'granularity' | 'ranges'>) {
  return (
    <KpiCards
      kpis={kpis}
      dates={dates}
      granularity={granularity}
      ranges={ranges}
      copy={{ title: 'Overview' }}
      onRangeChange={(range) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `range`, `versus`, `soFar`, `weekOf`, `about`, `scrub`, `point`, `up`, `down`, `announcement`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Metric chart

One metric over time, stacked by the segments it adds up from, against the period before. The legend shows each series' total, or its value on the hovered day; press a series to hide it or Alt-press to show only that one. Annotations mark the dates that explain the turns, and View data shows the numbers as a table.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-metric-chart
```

It brings `alert`, `button`, `card`, `chart`, `dropdown-menu`, `empty`, `icon-download`, `icon-link`, `icon-more-horizontal`, `segmented-control`, `skeleton`, `stat-card`, `tooltip`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MetricChart, type MetricChartProps } from '@/blocks/app/metric-chart'

export function MetricChartView({ series, points, granularity, annotations }: Pick<MetricChartProps, 'series' | 'points' | 'granularity' | 'annotations'>) {
  return (
    <MetricChart
      series={series}
      points={points}
      granularity={granularity}
      annotations={annotations}
      copy={{ title: 'Signups' }}
      onRangeChange={(range) => {
        // your code
      }}
      onHiddenChange={(hidden) => {
        // your code
      }}
      onAnnotationSelect={(annotation) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<MetricChartCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats every figure and date (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `series` | `Series[]` | `the demo's signup channels` | The segments the metric adds up from, bottom of the stack first. |
| `points` | `Point[]` |  | One point per bucket of the range shown, oldest first. Default: the demo's points for the range. |
| `granularity` | `'day' \| 'hour' \| 'week' \| 'month'` |  | How long one point is, for the axis and the readout. Default: the demo's for the range, else `day`. |
| `partial` | `boolean` |  | The last point is still filling (today, this week): it's hatched and reads "so far". Default: true with the demo's data, else false. |
| `annotations` | `Annotation[]` | `the demo's launches and incidents` | Moments to mark on the chart; each pins to the bucket that holds its date. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options for every figure (currency, units). Default: whole numbers. |
| `invert` | `boolean` | `false` | Down is good for this metric (errors, churn): a fall takes the good ink. |
| `ranges` | `Range[]` | `7D, 30D, 90D and 12M` | The windows the range switch offers; fewer than two hides it. |
| `range` | `string` |  | The window shown, controlled: pair it with `onRangeChange`. Default: uncontrolled. |
| `defaultRange` | `string` | ``30d`` | The window shown first, uncontrolled. |
| `onRangeChange` | `(range: string) => void` |  | Called with the window picked; answer with that window's `points`. |
| `hidden` | `string[]` |  | The hidden series' ids (`previous` is the period before), controlled: pair it with `onHiddenChange`. |
| `defaultHidden` | `string[]` | `[]` | The series hidden at first, uncontrolled. |
| `onHiddenChange` | `(hidden: string[]) => void` |  | Called with the hidden series' ids after a legend press. |
| `onAnnotationSelect` | `(annotation: MetricChartAnnotation) => void` |  | An annotation's mark is pressed. Default: none. |
| `onExport` | `(rows: Record<string, string \| number>[], range: string) => void` |  | The menu's Download CSV, with the rows shown. Default: downloads them as a CSV file. |
| `onCopyLink` | `(range: string) => void` |  | The menu's Copy link, with the window shown. Default: the menu leaves it out. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures and the plot while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the plot when the data fails to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message for a range without data. Default: `copy.empty` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `description`, `per`, `range`, `versus`, `soFar`, `partial`, `weekOf`, `previous`, `series`, `shown`, `hidden`, `only`, `allShown`, `scrub`, `point`, `annotations`, `more`, `download`, `copyLink`, `table`, `dateColumn`, `viewData`, `hideData`, `summary`, `up`, `down`, `flat`, `announcement`, `empty`, `emptyDescription`, `allHidden`, `showAll`, `error`, `retry`, `loading`, `locale`.

### Running total

A total as it builds up against the period before: both running totals by day number, the gap between them washed (in danger where this period has fallen behind), each line ending in its value and a note beside its point, placed clear of both lines. Point along the plot, or use the arrow keys, to read a day against the last period; the footer gives the day it passed last period's total, the daily pace and the best day.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-running-total
```

It brings `card`, `empty`, `stat-card`, `use-resize-measure`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RunningTotal, type RunningTotalProps } from '@/blocks/app/running-total'

export function RunningTotalView({ current, previous, note }: Pick<RunningTotalProps, 'current' | 'previous' | 'note'>) {
  return (
    <RunningTotal
      current={current}
      previous={previous}
      note={note}
      copy={{ title: 'Signups' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `thisPeriod`, `previousPeriod`, `vsPrevious`, `chart`, `reading`, `passed`, `notYet`, `perDay`, `bestDay`, `empty`, `summary`, `locale`.

### Daily bars

A period read day by day: the total with its change on the period before, a bar per day with the busiest lit and the average as a dashed line with its tag. A note on a day is a callout above the bars, never touching one. Point at a day, or focus the chart and use the arrow keys, to read it; the footer gives the top day, the daily average and the quietest day.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-daily-bars
```

It brings `card`, `empty`, `stat-card`, `use-resize-measure`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { DailyBars, type DailyBarsProps } from '@/blocks/app/daily-bars'

export function DailyBarsView({ days, notes }: Pick<DailyBarsProps, 'days' | 'notes'>) {
  return (
    <DailyBars
      days={days}
      notes={notes}
      copy={{ title: 'Daily visits' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `vsPrevious`, `chart`, `reading`, `averageTag`, `topDay`, `dailyAverage`, `quietest`, `empty`, `summary`, `locale`.

### Live metric

What's happening right now: people on the site rolling digit by digit, the last five minutes as a strip that slides along as each bucket opens, and the pages they're on, re-ranking as traffic shifts. Pause holds it, and the count is read aloud every half minute rather than on every change. It runs demo traffic until you pass your feed.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-live-metric
```

It brings `alert`, `badge`, `button`, `card`, `icon-circle-pause`, `icon-circle-play`, `presence-list`, `skeleton`, `stat-card`, `use-announcer`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { LiveMetric, type LiveMetricProps } from '@/blocks/app/live-metric'

export function LiveMetricView({ snapshot }: Pick<LiveMetricProps, 'snapshot'>) {
  return (
    <LiveMetric
      snapshot={snapshot}
      copy={{ title: 'Right now' }}
      onPausedChange={(paused) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `people`, `versus`, `strip`, `ago`, `now`, `pages`, `pagePeople`, `page`, `pause`, `resume`, `paused`, `resumed`, `announcement`, `demoData`, `empty`, `loading`, `retry`, `locale`.

### Retention

Weekly or monthly cohorts as a triangle under their curve. Point at a cell, or move through the grid with the arrow keys, and the curve draws that cohort over the average with how many points above or below it sits. Periods still in progress are hatched and left out of every average.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-retention
```

It brings `alert`, `button`, `card`, `chart`, `empty`, `segmented-control`, `skeleton`, `stat-card`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Retention, type RetentionProps } from '@/blocks/app/retention'

export function RetentionView({ cohorts, granularities, granularity, measure }: Pick<RetentionProps, 'cohorts' | 'granularities' | 'granularity' | 'measure'>) {
  return (
    <Retention
      cohorts={cohorts}
      granularities={granularities}
      granularity={granularity}
      measure={measure}
      copy={{ title: 'Retention' }}
      onGranularityChange={(granularity) => {
        // your code
      }}
      onMeasureChange={(measure) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<RetentionCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats every figure and date (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `cohorts` | `Cohort[]` |  | The cohorts, oldest first, each with its size and active people per period. Default: the demo's weekly or monthly signups. |
| `partial` | `boolean` |  | Each cohort's last period is still running: hatched, and left out of averages and curves. Default: true with the demo's data, else false. |
| `granularities` | `Granularity[]` | `['week', 'month']` | The cohort sizes the switch offers; fewer than two hides it. |
| `granularity` | `'week' \| 'month'` |  | The cohort size shown, controlled: pair it with `onGranularityChange`. Default: uncontrolled. |
| `defaultGranularity` | `'week' \| 'month'` | `'week'` | The cohort size shown first, uncontrolled. |
| `onGranularityChange` | `(granularity: RetentionGranularity) => void` |  | Called with the cohort size picked; answer with its `cohorts`. |
| `measure` | `'people' \| 'percent'` |  | What the cells say, controlled: pair it with `onMeasureChange`. Default: uncontrolled. |
| `defaultMeasure` | `'people' \| 'percent'` | `'percent'` | What the cells say first: `percent` (the default) or `people`. |
| `onMeasureChange` | `(measure: RetentionMeasure) => void` |  | Called with the measure picked. |
| `loading` | `boolean` | `false` | Skeletons in place of the chart and the grid while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the card's body when the data fails to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message when there are no cohorts. Default: `copy.empty` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `description`, `per`, `granularity`, `granularities`, `measure`, `measures`, `measureNames`, `period`, `periodShort`, `keyPeriods`, `cohort`, `people`, `average`, `grid`, `chart`, `allCohorts`, `cell`, `readout`, `versus`, `inProgress`, `summary`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Percentile trend

How long things take, as a spread: the p99 in large mono with its change, then every sample as a dot on a log scale with p50, p90 and p99 flagged against a target, and each item's own p99. Latency, delivery times and wait times read the same way; the windows on the control are yours, and `format` writes the units.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-percentile-trend
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `counter`, `distribution-strip`, `dropdown-menu`, `empty`, `icon-download`, `icon-link`, `icon-more-horizontal`, `segmented-control`, `share-bar`, `skeleton`, `typography`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { PercentileTrend, type PercentileTrendProps } from '@/blocks/app/percentile-trend'

export function PercentileTrendView({ ranges, snapshots }: Pick<PercentileTrendProps, 'ranges' | 'snapshots'>) {
  return (
    <PercentileTrend
      ranges={ranges}
      snapshots={snapshots}
      copy={{ title: 'Latency' }}
      onRangeChange={(range) => {
        // your code
      }}
      onSetAlert={async (range) => {
        // await your API here; the block shows progress until it settles
      }}
      onCopyLink={(range) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (640px at 100% scale). |
| `copy` | `Partial<PercentileTrendCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `ranges` | `PercentileTrendRange[]` | `1H, 24H and 7D` | The windows on the control, in order. |
| `snapshots` | `Record<string, PercentileTrendSnapshot>` | `demo data` | A snapshot per window, by the range's `id`. |
| `defaultRange` | `string` |  | The window shown first, uncontrolled. Default: `24h` for the default ranges, else the first. |
| `range` | `string` |  | The window shown, controlled: pair it with `onRangeChange`. Default: uncontrolled. |
| `onRangeChange` | `(range: string) => void` |  | Called with the window picked. Default: none. |
| `subtitle` | `string` |  | What the card is about, under the title. Default: `copy.subtitle` ("checkout-api · us-east-1"). |
| `target` | `number` | `demo` | The target: a value at or under it is within. In the figures' unit; default 300 (milliseconds). |
| `format` | `(value: number) => string` |  | Writes a value as text: the headline, the percentiles, the strip and each item's figure. Default: milliseconds (seconds from 1 s), in the locale. |
| `onSetAlert` | `(range: string) => Promise<unknown> \| unknown` |  | "Set alert" for the window shown; resolve when it's saved. Default: a short demo wait. |
| `onCopyLink` | `(range: string) => void` |  | The menu's "Copy link", with the window shown. Default: none. |
| `onExport` | `(range: string) => void` |  | The menu's "Export samples", with the window shown. Default: none. |
| `onOpenTraces` | `(range: string) => void` |  | "Open traces", with the window shown. Default: none. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the figures when they fail to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message when the window has no samples. Default: `copy.emptyTitle` and `copy.emptyDescription`. |
| `locale` | `string` |  | Formats every number. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 1, or 2 when `embedded`. |
| `className` | `string` |  | Classes for the root element (the `section` when embedded, else the page), merged with its own. Default: none. |

**Strings:** `copy` takes `title`, `subtitle`, `more`, `copyLink`, `exportSamples`, `range`, `headline`, `change`, `slower`, `faster`, `stats`, `p50`, `p90`, `count`, `strip`, `items`, `itemColumns`, `overShare`, `status`, `announcement`, `sampled`, `updated`, `openTraces`, `setAlert`, `settingAlert`, `alertSet`, `loading`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Hour lanes

When things happen, by lane: a lane of dots per source, entrance or channel across the day, each swelling where it's busy on one scale, its share of the week under its name, and the busiest bucket flagged through every lane. The Off-hours switch keeps the night in color and quiets the working day; the foot says the peak, the share outside working hours, and which lane leads at night. The demo is security alerts; Store visits and Support calls show other lanes, hours and units, and Loading, Empty and Error hold the lanes' place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-hour-lanes
```

It brings `alert`, `badge`, `button`, `card`, `density-lanes`, `empty`, `skeleton`, `switch`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { HourLanes, type HourLanesProps } from '@/blocks/app/hour-lanes'

export function HourLanesView({ lanes, offHours }: Pick<HourLanesProps, 'lanes' | 'offHours'>) {
  return (
    <HourLanes
      lanes={lanes}
      offHours={offHours}
      copy={{ title: 'Alerts by hour' }}
      onRetry={() => {
        // your code
      }}
      onShowOffHoursChange={(show) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `zone`, `offHours`, `chartLabel`, `countLabel`, `peak`, `peakHour`, `offHoursShare`, `nightLead`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Quadrant

How two measures relate: accounts by usage and revenue, split into four groups by two lines you can drag or step with the keys. The chips count the groups and filter them. Movement draws where each account stood last month, and the list names who changed group.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-quadrant
```

It brings `alert`, `button`, `card`, `counter`, `empty`, `skeleton`, `switch`, `toggle`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Quadrant, type QuadrantProps } from '@/blocks/app/quadrant'

export function QuadrantView({ items, x, y }: Pick<QuadrantProps, 'items' | 'x' | 'y'>) {
  return (
    <Quadrant
      items={items}
      x={x}
      y={y}
      copy={{ title: 'Account health' }}
      onThresholdsChange={(thresholds) => {
        // your code
      }}
      onGroupChange={(group) => {
        // your code
      }}
      onMovementChange={(movement) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the card in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | Inside another app: a `section` named by an `h2`, without the page around the card. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (768px at 100% scale). |
| `headingLevel` | `1 \| 2 \| 3` |  | The title's level. Default: 2 when embedded, else 1. |
| `copy` | `Partial<QuadrantCopy>` |  | Any of the card's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats every figure (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `items` | `Item[]` |  | The items, each with its two figures, a size and where it stood last period. Default: the demo's 36 accounts. |
| `x` | `QuadrantAxis` |  | The measure across: its format, scale and ends. Default: the demo's percent of seats, 0 to 100, with the demo's items; else linear whole numbers. |
| `y` | `QuadrantAxis` |  | The measure up. Default: the demo's revenue on a log scale, with the demo's items; else linear whole numbers. |
| `thresholds` | `[number, number]` |  | Where the two lines split the measures, controlled: pair it with `onThresholdsChange`. Default: uncontrolled. |
| `defaultThresholds` | `[number, number]` |  | Where they split first, uncontrolled. Default: the demo's 55% and $5K, else the medians. |
| `onThresholdsChange` | `(thresholds: [number, number]) => void` |  | Called as a line is dragged or stepped. |
| `group` | `QuadrantGroup \| null` |  | The group shown alone, controlled (`null` for all): pair it with `onGroupChange`. Default: uncontrolled. |
| `defaultGroup` | `QuadrantGroup \| null` | `null` | The group shown alone first, uncontrolled. |
| `onGroupChange` | `(group: QuadrantGroup \| null) => void` |  | Called with the group picked, or `null` for all. |
| `movement` | `boolean` |  | Whether last period's places show, controlled: pair it with `onMovementChange`. Default: uncontrolled. |
| `defaultMovement` | `boolean` | `false` | Whether they show first, uncontrolled. |
| `onMovementChange` | `(movement: boolean) => void` |  | Called when Movement is switched. |
| `onItemSelect` | `(item: QuadrantItem) => void` |  | An item is pressed (a bubble or a row). Default: items aren't pickable. |
| `loading` | `boolean` | `false` | Skeletons in place of the field and the list while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the field when the data fails to load, with Retry when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message when there are no items. Default: `copy.empty` and `copy.emptyDescription`. |

**Strings:** `copy` takes `title`, `description`, `x`, `y`, `size`, `xValue`, `yValue`, `sizeValue`, `groups`, `filter`, `chip`, `movement`, `movedFrom`, `chart`, `points`, `point`, `splitX`, `splitY`, `splitXName`, `splitYName`, `all`, `list`, `counts`, `summary`, `loading`, `retry`, `empty`, `emptyDescription`, `locale`.

### Compare items

Two to four things side by side: a picker heads each column and its swatch is that column's color on the radar, and the overview under it lines up every spec by column. Highlight best marks the best value in each row with a dot; add a column from the ones not yet picked, or remove one down to two.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-compare-items
```

It brings `badge`, `button`, `card`, `icon-plus`, `icon-x`, `radar-chart`, `select`, `switch`, `table`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CompareItems, type CompareItemsProps } from '@/blocks/app/compare-items'

export function CompareItemsView({ items, axes, specs, value }: Pick<CompareItemsProps, 'items' | 'axes' | 'specs' | 'value'>) {
  return (
    <CompareItems
      items={items}
      axes={axes}
      specs={specs}
      value={value}
      copy={{ title: 'Compare models' }}
      onValueChange={(value) => {
        // your code
      }}
      onHighlightChange={(highlight) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `highlightBest`, `models`, `pickerOf`, `remove`, `add`, `chart`, `overview`, `yes`, `no`, `empty`, `best`, `locale`.

### Head to head

Two things side by side before you choose: who leads overall, every measure as a bar growing from a shared center with its own format and margin, and the trade-off between two figures on a quadrant. Models, job offers and supplier quotes read the same way. Choose a side and act on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-head-to-head
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `diff-bar`, `empty`, `icon-more-horizontal`, `segmented-control`, `skeleton`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { HeadToHead, type HeadToHeadProps } from '@/blocks/app/head-to-head'

export function HeadToHeadView({ contenders, metrics }: Pick<HeadToHeadProps, 'contenders' | 'metrics'>) {
  return (
    <HeadToHead
      contenders={contenders}
      metrics={metrics}
      copy={{ title: 'Compare' }}
      onRetry={() => {
        // your code
      }}
      onChoose={async (side, contender) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `contenders`, `sides`, `winner`, `wins`, `xUnit`, `metricsLabel`, `metrics`, `even`, `higher`, `lower`, `tradeoff`, `xAxis`, `yAxis`, `bestCorner`, `xChange`, `yChange`, `summary`, `points`, `chooseLabel`, `choose`, `choosing`, `chosen`, `status`, `loading`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Paired bars

Two things side by side: per row, two bars on one shared axis (log by default, so a row with a hundred and one with forty thousand both read), the numbers behind them in the row's own format, and optionally a second figure for each side with an old one struck through. Plans, schools and phones read the same way. Search narrows the rows; View all shows every row in the same room and scrolls inside it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-paired-bars
```

It brings `alert`, `badge`, `button`, `card`, `empty`, `icon-search`, `input`, `skeleton`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { PairedBars, type PairedBarsProps } from '@/blocks/app/paired-bars'

export function PairedBarsView({ sides, rows, scale }: Pick<PairedBarsProps, 'sides' | 'rows' | 'scale'>) {
  return (
    <PairedBars
      sides={sides}
      rows={rows}
      scale={scale}
      copy={{ title: 'Plan comparison' }}
      onExpandedChange={(expanded) => {
        // your code
      }}
      onQueryChange={(query) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `tableLabel`, `nameHeader`, `valuesHeader`, `chartHeader`, `figureHeader`, `was`, `noFigure`, `search`, `count`, `viewAll`, `showFewer`, `region`, `empty`, `emptyDescription`, `loading`, `retry`, `currency`, `locale`.

### Compound projection

What a steady addition grows into: set the monthly amount, the years and the yearly rate and the bars rise to the total at the end, one per year, the last highlighted. The demo is a savings plan; stories show a newsletter's readers and a forest's captured carbon.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-compound-projection
```

It brings `alert`, `async-button`, `badge`, `button`, `capsule-stepper`, `card`, `empty`, `label`, `select`, `skeleton`, `slider`, `stat-card`, `use-controllable-state`, `youj-core`, `youj-labels-growth-forecast`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { CompoundProjection, type CompoundProjectionProps } from '@/blocks/app/compound-projection'

export function CompoundProjectionView({ plan, rates }: Pick<CompoundProjectionProps, 'plan' | 'rates'>) {
  return (
    <CompoundProjection
      plan={plan}
      rates={rates}
      copy={{ title: 'Growth forecast' }}
      onPlanChange={(plan) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onStart={async (plan) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `currency`, `title`, `description`, `rateBadge`, `split`, `yearsValue`, `start`, `starting`, `started`, `disclaimer`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `contribution`, `rate`, `years`, `today`, `year`, `bars`, `bar`, `locale`.

### Curve window

One value against another over the recent parts, series by series (the demo: a station's bolts, torque against angle, with a battery discharge and a glucose response in the stories): pick a series, read the last curve as a number with its verdict, and see the recent curves against a dashed window. The last curve is the accent, and a part that ended outside the window is red with a callout that names it, its value and why. `axes` names and formats the two axes, and loading, error and empty states take the chart's place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-curve-window
```

It brings `alert`, `badge`, `button`, `card`, `empty`, `segmented-control`, `skeleton`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CurveWindow, type CurveWindowProps } from '@/blocks/app/curve-window'

export function CurveWindowView({ series, axes }: Pick<CurveWindowProps, 'series' | 'axes'>) {
  return (
    <CurveWindow
      series={series}
      axes={axes}
      copy={{ title: 'Tightening' }}
      onValueChange={(id) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `nokCount`, `allOk`, `seriesLabel`, `at`, `ok`, `nok`, `chartLabel`, `window`, `keyOk`, `keyLast`, `keyNok`, `keyWindow`, `callout`, `traceList`, `trace`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Drift histogram

Whether a process is walking away from nominal (the demo: a hole's position, with a fill weight and a delivery ETA error in the stories): the offset of the recent parts and the process capability, a 3D histogram of where parts landed (older, recent, and out of the dashed tolerance ring) with an arrow for the drift, and the correction that would bring them back, with Apply. `format` reads the offsets, and loading, error and empty states take the plate's place.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-drift-histogram
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `empty`, `iso-scene`, `iso-shapes`, `skeleton`, `use-announcer`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { DriftHistogram, type DriftHistogramProps } from '@/blocks/app/drift-histogram'

export function DriftHistogramView({ hits }: Pick<DriftHistogramProps, 'hits'>) {
  return (
    <DriftHistogram
      hits={hits}
      copy={{ title: 'True position' }}
      onRetry={() => {
        // your code
      }}
      onApply={async (offset) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `subject`, `stable`, `drifting`, `corrected`, `offsetLabel`, `capability`, `chartLabel`, `tolerance`, `keyOlder`, `keyRecent`, `keyOut`, `keyDrift`, `correction`, `axis`, `apply`, `applying`, `applied`, `announceApplied`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

### Coverage grid

Where coverage is thin: rows down the side and columns across the top, each cell filled by how deep the coverage goes in its column's color and hatched where there is none. Pick a row and its gaps turn red; the foot says how many it has, with a draft button for them and Review gaps. Drafts go live once reviewed, so the matrix keeps counting live ones only. The demo is detection rules by tactic and source; Test coverage and Course syllabus show other rows, columns and words.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-coverage-grid
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `coverage-matrix`, `empty`, `icon-sparkle`, `skeleton`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CoverageGrid, type CoverageGridProps } from '@/blocks/app/coverage-grid'

export function CoverageGridView({ columns, rows }: Pick<CoverageGridProps, 'columns' | 'rows'>) {
  return (
    <CoverageGrid
      columns={columns}
      rows={rows}
      copy={{ title: 'Detection coverage' }}
      onRetry={() => {
        // your code
      }}
      onRowChange={(id) => {
        // your code
      }}
      onDraft={async (row, gaps) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `coveredCount`, `coveredName`, `matrixLabel`, `depth`, `noDepth`, `depthLabel`, `suggestion`, `noGaps`, `drafted`, `draft`, `draftIdle`, `drafting`, `draftDone`, `review`, `failed`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The metric chart's legend entries are toggle buttons with `aria-pressed`, and hiding or soloing a series is announced. Annotations are buttons named with what happened, the date and the details. The breakdown's ring is decorative: its parts are a list of buttons named with figure, share, change and how many parts they hold, the path is a breadcrumb, and focus lands in the new level after a zoom. The retention grid is one tab stop: the arrow keys move along the triangle, Home and End move along a row, and every cell is named with its cohort, period, share and count, marked when still in progress. The goals are a radio group, so arrow keys pick the goal the burn-up shows.

The daily bars and the running total are each one tab stop, a group named for the chart and described by a sentence on the total and the extremes. Left and Right read a day, Home and End jump to either end and Escape lets go; the day is read out by a polite live region, and the callouts and end values are text.

The live card's count is announced politely every 30 seconds while it runs, and Pause stops every update (WCAG 2.2.2). Its demo timers stop while the tab is hidden or the card is off screen.

Percentile trend's strip has a visually hidden summary of its quantiles, the window switch is labelled, stats are a description list with a label, the items are a labelled section, and an item's status is added as hidden text. The new p99 is announced when the window changes.

Hour lanes draws a named grid with a row per lane (its header the name and share) and a cell per bucket named with its time and count, and "highlighted" while the Off-hours switch is on; the grid is one tab stop, the arrow keys walk hours and sources, and focus shows the same tooltip as hovering. Off-hours is a labelled switch, and the foot's figures are a description list.

Each of the quadrant's split lines has a handle that is a slider, named for the measure it splits and read with its value; the arrow keys, Page Up and Down, Home and End move it, and the new counts are announced once it stops. The bubbles are one tab stop, an arrow key goes to the nearest bubble that way, and each is named with its figures, its group and, with Movement on, the group it came from. The chips are toggle buttons named with their count.

Compare items' radar and overview are one reading: the radar names each point with the model, axis and score, and has its own hidden table, and the overview is a real table with the models as columns. Each column's picker is a labelled select ("Model 1"), the remove buttons are named with the model they remove, and a best value is marked in text for assistive tech ("best in this row"), not only by its dot. Highlight best is a switch.

Head to head groups contenders, metrics and the trade-off under labels. Each bar row carries a hidden verdict naming the winner, the quadrant is an image with a text alternative that states the trade-off, and the choose control is labelled.

Paired bars is a table: each number carries its side's name, and the bars are for the eye. Under reduced motion every value lands in place; the limit meters' bucket still refills a token at a time.

Curve window picks the series with one named choice, draws the curves as an image whose text gives the series, the number of parts, how many fell outside the window and the window itself, and lists every part with its result and where it ended in words. The failed part's callout is plain text on the page, not a hover tooltip.

Drift histogram draws the plate as an image whose text says how many holes landed, how many are older, recent and outside the tolerance, and how far the recent ones sit from nominal; the offset, the capability and the tool offset are text, and Apply announces that the offset was applied.

Coverage grid draws a named grid with a row per row (the picked one `aria-selected`) and every cell named with its column and depth ("Cloud: No rules"); the grid is one tab stop, the arrows move between rows and cells, and Enter picks a row. Gaps are hatched and dashed as well as colored. The suggestion is a polite live region, so picking a row or drafting is read out.

Under reduced motion every figure, line, ring and bar is drawn at its value, and the now line and hand move on each minute without gliding. Scrubbing still follows the pointer and keys, the breakdown changes level without zooming, and the live dot stops pulsing. The heatmap's days, the flow's ribbons and the quadrant's bubbles are drawn in place, and a new range or a moved split changes them at once.

---

# Call to action

> Closing and in-page calls to action, from a slim banner to a full form or a ledger of customer results.

Source: https://www.youj.dev/docs/blocks/cta

## Blocks

### Band

A closing call to action with a headline, reassurance under the button and room for a secondary link.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cta
```

It brings `button`, `icon-arrow-right`, `illustrations`, `magnetic`, `mesh-gradient`, `reveal`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingCta, type MarketingCtaProps } from '@/blocks/marketing/cta'

export function MarketingCtaView({ primaryCta }: Pick<MarketingCtaProps, 'primaryCta'>) {
  return (
    <MarketingCta
      primaryCta={primaryCta}
      copy={{ title: 'Your next deploy could be your first one here' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` |  | The headline. Overrides `copy.title`. |
| `description` | `string` |  | The line under the headline. Overrides `copy.description`. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The picture on the end side: a scene from the illustrations by id, your own node, or `null` for none. |
| `primaryCta` | `CtaBandCta` | `Start deploying → `#signup`` | The magnetic primary button. |
| `secondaryCta` | `CtaBandCta \| null` | `Talk to sales → `#sales`` | The quiet link beside it; `null` hides it. |
| `copy` | `Partial<MarketingCtaCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | The headline's level. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |

**Strings:** `copy` takes `title`, `description`.

### Banner

A slim banner for between sections, with a short line and a button. Pick it when a full closing section would be too much.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cta-banner
```

It brings `button`, `icon-arrow-right`, `icon-rocket`, `reveal`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CtaBanner, type CtaBannerProps } from '@/blocks/marketing/cta-banner'

export function CtaBannerView({ primaryCta }: Pick<CtaBannerProps, 'primaryCta'>) {
  return (
    <CtaBanner
      primaryCta={primaryCta}
      copy={{ title: 'Your next deploy is sixty seconds away.' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Default: the theme around it. The showcase passes the chosen preset here. |
| `embedded` | `boolean` | `false` | A section inside another page: the host lays it out, so the band becomes a rounded panel in its column instead of running edge to edge. |
| `primaryCta` | `CtaBannerCta` | `"Import a repository" to `#signup`` | The primary button. |
| `secondaryCta` | `CtaBannerCta \| null` | `"Read the quickstart" to `#quickstart`` | The quiet text link; `null` hides it. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | The headline's level. |
| `copy` | `Partial<CtaBannerCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `linkComponent` | `LinkComponent` | `'a'` | Renders every link, e.g. Next.js `Link`. |

**Strings:** `copy` takes `title`, `description`.

### Form

A work email and team size form beside the pitch, so interest turns into an inquiry on the spot.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cta-form
```

It brings `alert`, `async-button`, `button`, `card`, `content-swap`, `field`, `icon-arrow-right`, `icon-check`, `icon-engine`, `icon-git-branch`, `icon-mail-open`, `icon-users`, `input`, `reveal`, `skeleton`, `stagger`, `toggle-group`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CtaForm, type CtaFormProps } from '@/blocks/marketing/cta-form'

export function CtaFormView({ proof, teamSizes }: Pick<CtaFormProps, 'proof' | 'teamSizes'>) {
  return (
    <CtaForm
      proof={proof}
      teamSizes={teamSizes}
      copy={{ eyebrow: 'Team trial' }}
      onSubmit={async (data) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `cardTitle`, `cardDescription`, `emailLabel`, `emailPlaceholder`, `teamSizeLabel`, `emailMissing`, `emailInvalid`, `emailPersonal`, `failedTitle`, `failedDescription`, `submit`, `pending`, `success`, `failed`, `invalid`, `finePrint`, `loading`, `doneTitle`, `doneDescription`, `doneHeading`, `doneIntro`, `doneSteps`, `changeEmail`.

### Proof

A ledger of customer results and the words behind them, ending on the reader’s own line and the call to action. Pick it when evidence should lead into the ask.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cta-proof
```

It brings `avatar`, `button`, `counter`, `icon-arrow-right`, `icon-sparkle`, `reveal`, `sliding-indicator`, `typography`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CtaProof, type CtaProofProps } from '@/blocks/marketing/cta-proof'

export function CtaProofView({ customers, logos, primaryCta }: Pick<CtaProofProps, 'customers' | 'logos' | 'primaryCta'>) {
  return (
    <CtaProof
      customers={customers}
      logos={logos}
      primaryCta={primaryCta}
      copy={{ eyebrow: 'Customers' }}
      linkComponent={Link}
      onQuoteChange={(index) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `linesLabel`, `columns`, `from`, `to`, `readerName`, `readerMeasure`, `readerQualifier`, `readerAfter`, `moreCount`, `moreBefore`, `moreAfter`.

### Contact sales

Book a sales call the way a good scheduler does, one question at a time: a day and a time with the person the visitor's region puts forward, then three short rows of details with the time pinned on top, then a confirmation that says it in full. Writing instead is one link away and keeps what was typed.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-contact-sales
```

It brings `alert`, `async-button`, `avatar`, `button`, `field`, `icon-arrow-right`, `icon-check`, `icon-mail`, `icon-phone`, `input`, `native-select`, `reveal`, `select`, `stagger`, `textarea`, `toggle-group`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ContactSales, type ContactSalesProps } from '@/blocks/marketing/contact-sales'

export function ContactSalesView({ regions, slots, sizes, topics }: Pick<ContactSalesProps, 'regions' | 'slots' | 'sizes' | 'topics'>) {
  return (
    <ContactSales
      regions={regions}
      slots={slots}
      sizes={sizes}
      topics={topics}
      copy={{ eyebrow: 'Talk to sales' }}
      onSubmit={async (values) => {
        // await your API here; the block shows progress until it settles
      }}
      onModeChange={(mode) => {
        // your code
      }}
      onRegionChange={(region) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `proof`, `pickTitle`, `pickDescription`, `region`, `meet`, `meetRole`, `daysLabel`, `dayLabel`, `timesLabel`, `taken`, `timezone`, `noTimes`, `slotMissing`, `next`, `nextWith`, `toMessage`, `detailsTitle`, `detailsDescription`, `change`, `withWhom`, `name`, `email`, `emailPlaceholder`, `company`, `size`, `topic`, `messageTitle`, `messageDescription`, `replies`, `messageLabel`, `messageHint`, `toCall`, `nameMissing`, `emailMissing`, `emailInvalid`, `emailPersonal`, `companyMissing`, `messageTooLong`, `failedTitle`, `failedDescription`, `submitCall`, `submitMessage`, `pending`, `success`, `failed`, `invalid`, `finePrint`, `doneTitleCall`, `doneTitleMessage`, `doneCall`, `doneMessage`, `doneSent`, `doneNext`, `doneSteps`, `again`, `directTitle`, `directEmail`, `directPhone`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each call to action is a `<section>` named by its own heading (`aria-labelledby`). The heading is an `h2` by default; `headingLevel` changes it.

Form and Contact sales use real `form` elements with labelled fields. Contact sales moves focus to each step's heading as it arrives; its days and times are labelled toggle groups (one tab stop, arrow keys between them) that read each day's open times and say a taken time is taken; a missing time or field is said in an alert and focused; the region is a labelled menu. Proof marks its toggle with `aria-pressed`, announces changes in a live region and hides decorative marks from assistive technology.

Banner checks the reduced-motion setting. The links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Company

> Sections about the people and the answers behind the product: the story so far, the team, the open roles and an FAQ.

Source: https://www.youj.dev/docs/blocks/company

## Blocks

### About

Tell the story as something to scrub through: a rail of years under a growth line the block draws, where each year rolls the figures to how they stood, draws the line up to it and swaps the chapter in. It plays through once in view, holds while you point at it, and stops when you pick a year; then the values, numbered. Under reduced motion it rests on today.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-about
```

It brings `button`, `counter`, `icon-compass`, `icon-heart`, `icon-leaf`, `icon-lightbulb`, `icon-play`, `icon-refresh`, `reveal`, `stagger`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { About, type AboutProps } from '@/blocks/marketing/about'

export function AboutView({ milestones, metrics, values }: Pick<AboutProps, 'milestones' | 'metrics' | 'values'>) {
  return (
    <About
      milestones={milestones}
      metrics={metrics}
      values={values}
      copy={{ eyebrow: 'About us' }}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `mission`, `description`, `timeline`, `milestoneName`, `pause`, `play`, `replay`, `valuesTitle`.

### Team

Introduce the people with portraits that look designed even before there's a photo: their initials set large, where they work from and their local time, ticking. A bio rises over the portrait on hover or focus, the name pins it open, and a team filter re-flows the grid.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-team
```

It brings `button`, `icon-arrow-right`, `icon-moon`, `icon-sun`, `presence-list`, `reveal`, `segmented-control`, `select`, `use-controllable-state`, `use-mobile`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingTeam, type MarketingTeamProps } from '@/blocks/marketing/team'

export function MarketingTeamView({ people }: Pick<MarketingTeamProps, 'people'>) {
  return (
    <MarketingTeam
      people={people}
      copy={{ eyebrow: 'The team' }}
      linkComponent={Link}
      onTeamChange={(team) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `filterLabel`, `all`, `localTime`, `day`, `night`, `personLink`, `empty`.

### Careers

List the open roles so people find theirs: teams as tabs with live counts, a search that marks what it found, a location filter, and rows that line up the place, the kind and the salary band, with New on the last fortnight's. The open application closes it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-careers
```

It brings `badge`, `button`, `icon-arrow-right`, `icon-check`, `icon-map-pin`, `icon-search`, `icon-x`, `input-group`, `presence-list`, `reveal`, `segmented-control`, `select`, `use-controllable-state`, `use-mobile`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Careers, type CareersProps } from '@/blocks/marketing/careers'

export function CareersView({ roles, perks }: Pick<CareersProps, 'roles' | 'perks'>) {
  return (
    <Careers
      roles={roles}
      perks={perks}
      copy={{ eyebrow: 'Careers' }}
      linkComponent={Link}
      onTeamChange={(team) => {
        // your code
      }}
      onQueryChange={(query) => {
        // your code
      }}
      onLocationChange={(location) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `perksLabel`, `teamsLabel`, `all`, `search`, `searchPlaceholder`, `clearSearch`, `location`, `anywhere`, `remote`, `count`, `new`, `roleLabel`, `emptyTitle`, `emptyDescription`, `clearFilters`, `openTitle`, `openDescription`.

### FAQ

Answer common questions like a small help center: a search that marks its words and opens the answer that matched, topics with counts, a link to every answer that opens and flashes it, and “Was this helpful?” under each.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-faq
```

It brings `accordion`, `async-button`, `button`, `icon-arrow-right`, `icon-check`, `icon-link`, `icon-message`, `icon-search`, `icon-search-x`, `icon-thumbs-down`, `icon-thumbs-up`, `icon-x`, `input-group`, `presence-list`, `reveal`, `segmented-control`, `select`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Faq, type FaqProps } from '@/blocks/marketing/faq'

export function FaqView({ questions, value }: Pick<FaqProps, 'questions' | 'value'>) {
  return (
    <Faq
      questions={questions}
      value={value}
      copy={{ eyebrow: 'FAQ' }}
      linkComponent={Link}
      onValueChange={(value) => {
        // your code
      }}
      onTopicChange={(topic) => {
        // your code
      }}
      onQueryChange={(query) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `search`, `searchPlaceholder`, `clearSearch`, `results`, `topics`, `all`, `general`, `noResults`, `noResultsHint`, `helpful`, `yes`, `no`, `thanks`, `sorry`, `askPerson`, `copyLink`, `copied`, `copyFailed`, `stuckTitle`, `stuckDescription`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each section is a `<section>` named by its own heading (`aria-labelledby`); the heading is an `h2` by default and `headingLevel` changes it, with every part's heading a level below.

About's years are a tab list: the arrows, Home and End move along the rail and pick a year, and its chapter is the tab panel. Each figure ends on the same text a screen reader gets, and the tour holds while keyboard focus is in it, with a button to pause, play or replay it. The growth line is decorative; the figures carry its meaning.

Team's people are articles named for them. The name is a disclosure button (`aria-expanded`) that pins the bio open, and Escape lets it go; a bio's links only join the tab order while it's open. Local times are written out in full for screen readers, with day or night named.

Careers' rows are single links named with the role, its place and its kind; the team tabs are a labeled group, the search a search field (Escape clears it) and the count a polite status.

FAQ is the kit's Accordion, so every question is a heading button that reports `aria-expanded`; answers stay in the page for find-in-page. The search is a search field whose count sits in it, Escape clears it and ↓ moves to the first question; the topics are a labeled group. “Was this helpful?” is a labeled group and its thanks a status. Links and buttons are real `a` and `button` elements with the kit's focus ring.

---

# Features

> Feature sections that explain what your product does, as a bento, grid, spotlight, steps or tabs.

Source: https://www.youj.dev/docs/blocks/features

## Blocks

### Bento

Show what your product does with a grid of varied tiles and small working demos. Each tile spans the columns and rows you give it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-feature-bento
```

It brings `avatar-stack`, `badge`, `counter`, `icon-check`, `icon-command`, `icon-engine`, `icon-gauge`, `icon-git-pull-request`, `icon-globe`, `icon-layers`, `icon-lock`, `icon-message`, `icon-search`, `kbd`, `progress`, `reveal`, `sparkline`, `spinner`, `stagger`, `switch`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { FeatureBento, type FeatureBentoProps } from '@/blocks/marketing/feature-bento'

export function FeatureBentoView({ features }: Pick<FeatureBentoProps, 'features'>) {
  return (
    <FeatureBento
      features={features}
      copy={{ eyebrow: 'Platform' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`.

### Grid

List your features in a ruled grid, each read off a live instrument that takes a new reading when it is pointed at.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-feature-grid
```

It brings `badge`, `counter`, `day-ring`, `distribution-strip`, `hatched-bar`, `icon-arrow-right`, `icon-eye`, `icon-lock`, `lane-meter`, `reveal`, `rollout-ruler`, `scramble-text`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { FeatureGrid, type FeatureGridProps } from '@/blocks/marketing/feature-grid'

export function FeatureGridView({ features }: Pick<FeatureGridProps, 'features'>) {
  return (
    <FeatureGrid
      features={features}
      copy={{ eyebrow: 'Platform' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`.

### Spotlight

Show your features in action with alternating text and interactive demos, each with a link to learn more.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-feature-spotlight
```

It brings `async-button`, `badge`, `card`, `chart`, `icon-arrow-right`, `icon-git-commit`, `reveal`, `timeline`, `toggle-group`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { FeatureSpotlight, type FeatureSpotlightProps } from '@/blocks/marketing/feature-spotlight'

export function FeatureSpotlightView({ features }: Pick<FeatureSpotlightProps, 'features'>) {
  return (
    <FeatureSpotlight
      features={features}
      copy={{ eyebrow: 'How it works' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `copy` | `Partial<FeatureSpotlightCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `features` | `FeatureSpotlightFeature[]` | `the demo's three, each with a live demo` | The rows, alternating sides. |
| `linkComponent` | `ElementType` | `'a'` | Renders every link: pass your router's Link. |
| `headingLevel` | `1 \| 2 \| 3` | `2` | The heading's level; the rows' titles sit one level below. |

**Strings:** `copy` takes `eyebrow`, `title`, `learnMore`.

### Steps

Explain how your product works as a release visitors can watch: a lens rides the track from step to step, its ring running down while each step’s picture plays its moment, and anyone can pick a step to jump there.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-feature-steps
```

It brings `avatar`, `badge`, `button`, `counter`, `icon-arrow-right`, `icon-brand-github`, `icon-check`, `icon-git-pull-request`, `icon-message`, `icon-play`, `icon-rocket`, `reveal`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { FeatureSteps, type FeatureStepsProps } from '@/blocks/marketing/feature-steps'

export function FeatureStepsView({ steps }: Pick<FeatureStepsProps, 'steps'>) {
  return (
    <FeatureSteps
      steps={steps}
      copy={{ eyebrow: 'How it works' }}
      linkComponent={Link}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `stepsLabel`, `stepName`, `pause`, `play`.

### Tabs

Let visitors explore your features in tabs with a large demo for each choice. The tabs tour themselves until someone picks one.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-feature-tabs
```

It brings `badge`, `counter`, `icon-activity`, `icon-bell`, `icon-engine`, `icon-gauge`, `icon-history`, `icon-logs`, `reveal`, `sparkline`, `tabs`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { FeatureTabs, type FeatureTabsProps } from '@/blocks/marketing/feature-tabs'

export function FeatureTabsView({ features }: Pick<FeatureTabsProps, 'features'>) {
  return (
    <FeatureTabs
      features={features}
      copy={{ eyebrow: 'Observability' }}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `listLabel`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every section in this family is a `<section>` named by its own heading (`aria-labelledby`), so it shows up as a labelled region. The heading is an `h2` by default; set `headingLevel` to `1` or `3` where the page around it needs another. Feature spotlight sets its items’ headings one level deeper.

The pictures beside the text are decorative in Feature grid, Feature steps and Feature tabs: they are `aria-hidden` and `inert`, and a feature’s title and description carry the meaning, so say in the text whatever a `media` shows. Feature bento and Feature spotlight pass `media` through as you give it, so what you put there is read: give an image its `alt`, and keep a demo’s controls labelled. Feature steps is a named ordered list, so a screen reader announces the count; each number is a button named for its step (“Step 2 of 4: Push a branch”), with `aria-current="step"` on the step in play. Its tour has a Play and Pause button beside the call to action, holds while keyboard focus is in the steps, off screen or in a hidden tab, and never runs under reduced motion, where every step shows its finished picture.

Feature tabs is built on Tabs: the tab list is named (`copy.listLabel`), Left and Right Arrow move between tabs, Home and End jump to the ends, and the panel follows the selected tab. It tours itself until someone picks a tab, and pauses while the pointer or focus is inside it, while the page is hidden or the section is out of view; it never tours under reduced motion.

Everything animated stands still under reduced motion, and the links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Hero

> Opening sections for a landing page, from a centered headline to a terminal demo or a pointer-reactive motion panel.

Source: https://www.youj.dev/docs/blocks/hero

## Blocks

### Centered

Open with a centered headline, a badge and calls to action over a soft animated background. Pick it when the words should carry the page.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-hero-centered
```

It brings `aurora`, `badge`, `button`, `icon-arrow-right`, `stagger`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HeroCentered, type HeroCenteredProps } from '@/blocks/marketing/hero-centered'

export function HeroCenteredView({ primaryCta }: Pick<HeroCenteredProps, 'primaryCta'>) {
  return (
    <HeroCentered
      primaryCta={primaryCta}
      copy={{ badge: 'New' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `headline` | `string` |  | The headline. Same as `copy.headline`, which wins. |
| `description` | `string` |  | The sentence under the headline. Same as `copy.description`, which wins. |
| `copy` | `Partial<HeroCenteredCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `announcement` | `HeroCenteredCta \| null` | `the demo's launch note` | The announcement pill above the headline; `null` hides it. |
| `primaryCta` | `HeroCenteredCta` | `"Start deploying" to `#signup`` | The main call to action. |
| `secondaryCta` | `HeroCenteredCta \| null` | `"Talk to sales" to `#sales`` | The second call to action; `null` hides it. |
| `linkComponent` | `ElementType` | `'a'` | Renders every link: pass your router's Link. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The headline's level. |

**Strings:** `copy` takes `badge`, `headline`, `description`, `note`.

### Split

Put the pitch on one side and the product in a window on the other, and let the selling points steer it: pick a point, or let them tour, and the window’s camera glides to that part of the screen while it plays its moment. Point at the window to see all of it. Pick it when visitors should see what they get right away.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-hero-split
```

It brings `avatar`, `badge`, `button`, `icon-check`, `icon-play`, `icon-rotate-ccw`, `icon-trending-up`, `reveal`, `stagger`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HeroSplit, type HeroSplitProps } from '@/blocks/marketing/hero-split'

export function HeroSplitView({ points, primaryCta }: Pick<HeroSplitProps, 'points' | 'primaryCta'>) {
  return (
    <HeroSplit
      points={points}
      primaryCta={primaryCta}
      copy={{ badge: 'Analytics, now in every plan' }}
      linkComponent={Link}
      onValueChange={(value) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `badge`, `headline`, `description`, `url`, `pointsLabel`, `pause`, `play`.

### Product

Show the product itself in a browser frame beneath the headline. Pick it for a product whose screen sells it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-hero-product
```

It brings `avatar`, `badge`, `button`, `icon-activity`, `icon-arrow-right`, `icon-bar-chart`, `icon-engine`, `icon-git-branch`, `icon-globe`, `icon-history`, `icon-layout-dashboard`, `icon-logs`, `icon-play`, `icon-rocket`, `icon-search`, `icon-settings`, `kbd`, `reveal`, `stagger`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HeroProduct, type HeroProductProps } from '@/blocks/marketing/hero-product'

export function HeroProductView({ primaryCta, callouts }: Pick<HeroProductProps, 'primaryCta' | 'callouts'>) {
  return (
    <HeroProduct
      primaryCta={primaryCta}
      callouts={callouts}
      copy={{ badge: 'New' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `badge`, `headline`, `description`, `url`, `urlPath`.

### Terminal

Introduce a command-line tool with a copyable install command beside an animated terminal session that deploys, then lands what it deployed on the terminal’s corner: the live site, in a window of its own. Pick it when the product is used from a shell.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-hero-terminal
```

It brings `button`, `counter`, `icon-check`, `icon-copy`, `icon-rotate-ccw`, `icon-terminal`, `morph-label`, `stagger`, `use-visible`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HeroTerminal, type HeroTerminalProps } from '@/blocks/marketing/hero-terminal'

export function HeroTerminalView({ transcript, primaryCta }: Pick<HeroTerminalProps, 'transcript' | 'primaryCta'>) {
  return (
    <HeroTerminal
      transcript={transcript}
      primaryCta={primaryCta}
      copy={{ eyebrow: 'New in 4.2: instant rollback' }}
      linkComponent={Link}
      onCopyCommand={(command) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `headline`, `description`, `note`, `cwd`, `replay`, `copy`, `copied`, `copyAria`.

### Motion

A headline that rises word by word over a pointer-reactive dot matrix, beside a live panel where visitors change speed, reduced motion and theme and watch a checklist respond. Pick it to show the kit’s motion settings working.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-hero-motion
```

It brings `async-button`, `avatar`, `button`, `checkbox`, `dot-matrix-wave`, `icon-arrow-right`, `icon-plus`, `icon-rocket`, `kbd`, `magnetic`, `presence-list`, `reveal`, `segmented-control`, `select`, `stagger`, `switch`, `text-split`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HeroMotion, type HeroMotionProps } from '@/blocks/marketing/hero-motion'

export function HeroMotionView({ accents, facts, shortcut, primaryCta }: Pick<HeroMotionProps, 'accents' | 'facts' | 'shortcut' | 'primaryCta'>) {
  return (
    <HeroMotion
      accents={accents}
      facts={facts}
      shortcut={shortcut}
      primaryCta={primaryCta}
      copy={{ eyebrow: 'Youj UI · Motion-first components for React' }}
      linkComponent={Link}
      onShip={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `copy` | `Partial<HeroMotionCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `accents` | `string[]` | `the demo's three` | The phrases the headline's second line takes in turn; one is a still headline. |
| `facts` | `HeroMotionFact[]` | `the demo's three` | The figures under the calls to action; empty hides the row. |
| `shortcut` | `string[]` | `['⌘', 'K']` | The keys of the shortcut shown beside the calls to action; empty hides it. |
| `primaryCta` | `HeroMotionCta` | `"Get started" to `#get-started`` | The main call to action. |
| `secondaryCta` | `HeroMotionCta \| null` | `"Browse components" to `#components`` | The second call to action; `null` hides it. |
| `tuner` | `boolean` | `true` | Show the "Try the contract" panel. |
| `tasks` | `HeroMotionTask[]` | `the demo's release checklist` | The checklist in that panel, tickable. |
| `moreTasks` | `string[]` | `the demo's four` | What "Add a task" adds, in turn; the button disables when they run out. |
| `onShip` | `() => Promise<unknown> \| unknown` |  | Called when "Ship it" is pressed; the button shows it working until the promise settles. Default: a short demo wait. |
| `linkComponent` | `ElementType` | `'a'` | Renders every link: pass your router's Link. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The headline's level. |

**Strings:** `copy` takes `eyebrow`, `headlineLead`, `description`, `shortcutHint`, `tunerTitle`, `tunerHint`, `speed`, `speedOption`, `reducedMotion`, `theme`, `ownTheme`, `demoTitle`, `filterLabel`, `all`, `open`, `done`, `addTask`, `nothingHere`, `ship`, `shipping`, `tasksLabel`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each hero is a `<section>` named by its own heading (`aria-labelledby`). The heading is an `h1` by default and an `h2` when you set `embedded`; set `headingLevel` to `1`, `2` or `3` where the page around it needs another.

The product shots, browser frames, terminal sessions and Terminal’s landed site in Split, Product and Terminal are decorative: they are `inert` (Split’s demo screen and Product also `aria-hidden`), so the headline and copy have to carry the meaning; a `media` you pass to Split is read as you give it, so give an image its `alt`. Split’s points are a named list of buttons, with `aria-current` on the one on show; its tour has a Play and Pause button in the window’s title bar and holds while keyboard focus is on the points. Motion’s control panel uses labelled controls (a select and switches) under its own headings.

The animated heroes (Split, Terminal, Product, Motion) check the reduced-motion setting and hold a still frame when it is on: Split shows its whole window, with no tour and no camera. The buttons and links are real `a` and `button` elements with the kit’s focus ring.

---

# Navigation

> Website headers that are hard to get right by hand: mega menus that morph between panels, a floating bar that follows the page, a fullscreen menu with levels, a docs header, a shop's header, and the sitemap footer.

Source: https://www.youj.dev/docs/blocks/navigation

## Blocks

### Mega menu

Mega menus on one popup that morphs from panel to panel: a preview card that follows the link you point at, media cards for posts and guides, a strip for a launch. With search, an announcement bar, signed-in and signed-out states, and a drawer of folding sections on phones. Pick it for a product with many parts.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-navbar
```

It brings `accordion`, `app-header`, `avatar`, `badge`, `button`, `collapse`, `command`, `command-palette`, `dropdown-menu`, `icon-arrow-right`, `icon-bar-chart`, `icon-book-open`, `icon-briefcase`, `icon-building`, `icon-code`, `icon-credit-card`, `icon-database`, `icon-git-branch`, `icon-globe`, `icon-history`, `icon-layout-dashboard`, `icon-life-buoy`, `icon-log-out`, `icon-megaphone`, `icon-rocket`, `icon-search`, `icon-settings`, `icon-shield-check`, `icon-shopping-bag`, `icon-sparkles`, `icon-terminal`, `icon-users`, `icon-x`, `mega-menu`, `navigation-menu`, `sparkline`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingNavbar, type MarketingNavbarProps } from '@/blocks/marketing/navbar'

export function MarketingNavbarView({ links, brand, accountLinks, searchItems }: Pick<MarketingNavbarProps, 'links' | 'brand' | 'accountLinks' | 'searchItems'>) {
  return (
    <MarketingNavbar
      links={links}
      brand={brand}
      accountLinks={accountLinks}
      searchItems={searchItems}
      copy={{ navLabel: 'Main' }}
      linkComponent={Link}
      onMenuChange={(menu) => {
        // your code
      }}
      onDismissAnnouncement={() => {
        // your code
      }}
      onSignOut={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `current` | `string` |  | The link of the page being shown, marked as current; the trigger of the menu holding it carries a dot. |
| `menu` | `string \| null` |  | The open mega menu's label, `null` for none, to control it (close it on a route change, say). |
| `defaultMenu` | `string \| null` |  | The mega menu open at first, when uncontrolled. Default: none. |
| `onMenuChange` | `(menu: string \| null) => void` |  | Called with the label of the menu that opens, or `null` as it closes. |
| `sticky` | `boolean` | `true` | Stick to the top and condense on scroll. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the bar. Default: the page. |
| `links` | `MarketingNavbarItem[]` | `the demo's Product, Solutions, Resources, Customers and Pricing` | The top-level entries, in order: plain links and mega menus. |
| `brand` | `MarketingNavbarBrand` | `the demo's Northwind` | The product's name, logo and home link. |
| `announcement` | `MarketingNavbarAnnouncement \| null` | `the demo's launch notice` | The bar above the header; `null` hides it. |
| `onDismissAnnouncement` | `() => void` |  | The announcement was dismissed (the visitor's choice to remember is yours). |
| `user` | `MarketingNavbarUser \| null` | `null` | The signed-in person: the bar shows the dashboard button and the account menu instead of the sign-in calls to action. |
| `accountLinks` | `MarketingNavbarAccountLink[]` | `Dashboard, Billing and Settings` | The account menu's pages above Sign out. |
| `onSignOut` | `() => void` |  | Called when the visitor chooses Sign out. |
| `dashboardCta` | `MarketingNavbarCta \| null` | `Dashboard → `#dashboard`` | The signed-in button on the bar; `null` hides it. |
| `primaryCta` | `MarketingNavbarCta \| null` | `Start free → `#signup`` | The solid call to action when signed out, on the bar from `md` and first in the drawer; `null` hides it. |
| `secondaryCta` | `MarketingNavbarCta \| null` | `Sign in → `#login`` | The quiet call to action beside it; `null` hides it. |
| `search` | `boolean` | `true` | Show the ⌘K search. |
| `searchItems` | `MarketingNavbarSearchItem[]` | `Pricing, Customers, Security and Contact` | Pages the search finds beyond the menus' links. |
| `onSearchSelect` | `(item: MarketingNavbarSearchItem) => void` |  | Called when a search result is chosen. Default: go to its `href`. |
| `actions` | `ReactNode` |  | Extra controls on the inline end, before the search (a theme toggle, a GitHub star count). |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<MarketingNavbarCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `navLabel`, `menu`, `searchLabel`, `searchPlaceholder`, `searchTitle`, `searchPages`, `signIn`, `signUp`, `dashboard`, `signOut`, `account`, `dismissAnnouncement`, `announcementLabel`, `sections`.

### Floating

A floating island over the page that draws in around its links once you scroll, follows the section in view with a gliding pill and a progress line, steps aside as you read on and returns when you scroll back. On phones the island grows into its own menu. Pick it for a focused product or a one-page site.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-navbar-floating
```

It brings `badge`, `button`, `collapse`, `icon-menu`, `sliding-indicator`, `stagger`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { NavbarFloating, type NavbarFloatingProps } from '@/blocks/marketing/navbar-floating'

export function NavbarFloatingView({ links, brand }: Pick<NavbarFloatingProps, 'links' | 'brand'>) {
  return (
    <NavbarFloating
      links={links}
      brand={brand}
      copy={{ navLabel: 'Main' }}
      linkComponent={Link}
      onCurrentChange={(href) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `links` | `NavbarFloatingLink[]` | `the demo's Features, Pricing, Customers and Changelog` | The links, up to about six. In-page links (`#pricing`) follow the section in view. |
| `brand` | `NavbarFloatingBrand` | `the demo's Halden` | The product's name, mark and home link. |
| `primaryCta` | `NavbarFloatingCta \| null` | `Get started → `#signup`` | The solid call to action, on the island at every width; `null` hides it. |
| `secondaryCta` | `NavbarFloatingCta \| null` | `Sign in → `#login`` | The quiet one beside it at rest (and in the phone menu); `null` hides it. |
| `current` | `string` |  | The current link's `href`, when your router knows the page. Default: the in-page section in view. |
| `onCurrentChange` | `(href: string \| undefined) => void` |  | Called with the `href` of the section that comes into view (undefined above the first). |
| `condense` | `boolean` | `true` | Draw in once the page scrolls under it. |
| `hideOnScroll` | `boolean` | `true` | Hide while the page scrolls down, return on the way up. |
| `progress` | `boolean` | `true` | A hairline that fills with the reader's progress through the page, once condensed. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the island. Default: the page. |
| `skipTo` | `string \| null` | `'#content'` | Where the skip link goes: your main content's id as a hash; `null` leaves it out. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<NavbarFloatingCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `navLabel`, `openMenu`, `closeMenu`, `skipLink`.

### Docs

A documentation header in two rows: the version menu, a ⌘K search over every page that remembers what you opened, the repository with its stars, and the sections as tabs with a gliding underline. On phones a drawer holds the section's page tree, open to the current page. Pick it for docs, guides and API references.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-navbar-docs
```

It brings `app-header`, `badge`, `button`, `collapsible`, `command`, `command-palette`, `dropdown-menu`, `icon-arrow-up-right`, `icon-brand-github`, `icon-chevrons-up-down`, `icon-file-text`, `icon-history`, `icon-menu`, `sheet`, `sliding-indicator`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { NavbarDocs, type NavbarDocsProps } from '@/blocks/marketing/navbar-docs'

export function NavbarDocsView({ sections, versions, links, brand }: Pick<NavbarDocsProps, 'sections' | 'versions' | 'links' | 'brand'>) {
  return (
    <NavbarDocs
      sections={sections}
      versions={versions}
      links={links}
      brand={brand}
      copy={{ docs: 'Docs' }}
      linkComponent={Link}
      onSectionChange={(id) => {
        // your code
      }}
      onVersionChange={(id) => {
        // your code
      }}
      onSearchSelect={(result) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sections` | `NavbarDocsSection[]` | `the demo's Get started, Guides, API reference, CLI and Examples` | The docs' sections, each a tab with its page tree for the phone drawer and search. |
| `section` | `string` |  | The current section's id, to control it (from your route, say). |
| `defaultSection` | `string` |  | The section a page starts on, when uncontrolled. Default: the first. |
| `onSectionChange` | `(id: string) => void` |  | Called with the id of a section tab that was followed. |
| `current` | `string` |  | The `href` of the page being shown: marked, and opened to, in the drawer's tree. |
| `versions` | `NavbarDocsVersion[]` | `v4.3, v4.2, v3.x and v2.x` | The versions; one with an `href` is archived elsewhere. Empty hides the menu. |
| `version` | `string` |  | The version shown, to control it. |
| `defaultVersion` | `string` |  | The version shown first, when uncontrolled. Default: the one marked `latest`, else the first served here. |
| `onVersionChange` | `(id: string) => void` |  | Called with the id of the version chosen from the menu (archived ones are links and don't call it). |
| `links` | `NavbarDocsLink[]` | `Blog and Changelog` | Links on the bar from `lg` and in the drawer. |
| `repository` | `NavbarDocsRepository \| null` | `a GitHub link with 12.5k stars` | The repository and its star count; `null` hides it. |
| `brand` | `NavbarDocsBrand` | `the demo's Atlas` | The product's name, mark and home link. |
| `cta` | `NavbarDocsCta \| null` | `Dashboard → `#dashboard`` | The call to action on the bar from `md` and in the drawer; `null` hides it. |
| `search` | `boolean` | `true` | Show the search field and its ⌘K palette. |
| `onSearchSelect` | `(result: NavbarDocsResult) => void` |  | Called when a search result is chosen. Default: go to its `href`. |
| `actions` | `ReactNode` |  | Extra controls before the call to action (a theme toggle, Ask AI). |
| `locale` | `string` |  | BCP 47 locale for the star count. Default: the provider's. |
| `sticky` | `boolean` | `true` | Stick to the top and turn to glass on scroll. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the header. Default: the page. |
| `skipTo` | `string \| null` | `'#content'` | Where the skip link goes: your main content's id as a hash; `null` leaves it out. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<NavbarDocsCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `docs`, `navLabel`, `sectionsLabel`, `version`, `versionsTitle`, `archived`, `searchLabel`, `searchPlaceholder`, `searchTitle`, `recent`, `repository`, `menu`, `openMenu`, `skipLink`, `showPages`.

### Fullscreen

A slim bar whose Menu opens the whole screen: large entries that rise into place, levels that drill in and back with focus kept in step, and a picture that follows the entry you point at. Pick it for a studio, an editorial product or any site that leads with its brand.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-navbar-fullscreen
```

It brings `app-header`, `badge`, `button`, `icon-arrow-left`, `icon-arrow-right`, `icon-brand-github`, `icon-brand-linkedin`, `icon-brand-x`, `icon-menu`, `sheet`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { NavbarFullscreen, type NavbarFullscreenProps } from '@/blocks/marketing/navbar-fullscreen'

export function NavbarFullscreenView({ items, brand, footerLinks, socials }: Pick<NavbarFullscreenProps, 'items' | 'brand' | 'footerLinks' | 'socials'>) {
  return (
    <NavbarFullscreen
      items={items}
      brand={brand}
      footerLinks={footerLinks}
      socials={socials}
      copy={{ menu: 'Menu' }}
      linkComponent={Link}
      onOpenChange={(open) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `NavbarFullscreenItem[]` | `the demo's Work, Studio, Journal, Sound and Contact` | The menu's entries, in order: links, and levels of their own. |
| `brand` | `NavbarFullscreenBrand` | `the demo's Kestrel` | The name, mark and home link. |
| `cta` | `NavbarFullscreenCta \| null` | `Start a project → `#contact`` | The call to action on the bar (and at the menu's foot on phones); `null` hides it. |
| `footerLinks` | `NavbarFullscreenLink[]` | `Press, Imprint and Privacy` | Small links at the menu's foot. |
| `socials` | `NavbarFullscreenSocial[]` | `X, GitHub and LinkedIn` | Profiles elsewhere, as icon links at the menu's foot. |
| `contact` | `NavbarFullscreenLink \| null` | `hello@kestrel.studio` | A contact line at the menu's foot, usually a `mailto:`; `null` hides it. |
| `current` | `string` |  | The `href` of the page being shown: marked current, and the entries that lead to it carry a dot. |
| `open` | `boolean` |  | The menu is open, to control it (close it on a route change, say). |
| `defaultOpen` | `boolean` | `false` | The menu starts open, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the menu opens or closes. |
| `sticky` | `boolean` | `true` | Stick to the top and turn to glass on scroll. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the bar. Default: the page. |
| `skipTo` | `string \| null` | `'#content'` | Where the skip link goes: your main content's id as a hash; `null` leaves it out. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<NavbarFullscreenCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `menu`, `close`, `navLabel`, `back`, `footerLabel`, `skipLink`.

### Store

A shop's header: a strip with the delivery promise and the region and currency, departments with category columns and collection tiles, a search that suggests products priced in the shopper's currency, and a bag whose count drops in. Pick it for a storefront.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-navbar-store
```

It brings `accordion`, `app-header`, `button`, `command`, `dropdown-menu`, `icon-arrow-right`, `icon-chevron-down`, `icon-globe`, `icon-menu`, `icon-search`, `icon-shopping-bag`, `icon-trending-up`, `icon-user`, `navigation-menu`, `sheet`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { NavbarStore, type NavbarStoreProps } from '@/blocks/marketing/navbar-store'

export function NavbarStoreView({ departments, regions, utilityLinks, products }: Pick<NavbarStoreProps, 'departments' | 'regions' | 'utilityLinks' | 'products'>) {
  return (
    <NavbarStore
      departments={departments}
      regions={regions}
      utilityLinks={utilityLinks}
      products={products}
      copy={{ navLabel: 'Departments' }}
      linkComponent={Link}
      onRegionChange={(id) => {
        // your code
      }}
      onSearchSelect={(result) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `departments` | `NavbarStoreDepartment[]` | `the demo's Clothing, Home, Journal and Sale` | The departments: menus of columns and collection tiles, and plain links. |
| `current` | `string` |  | The `href` of the page being shown: marked, and its department carries a dot. |
| `regions` | `NavbarStoreRegion[]` | `the US, the UK, the EU and Japan` | Where the store ships, each with its currency. Empty hides the menu. |
| `region` | `string` |  | The region shown, to control it. |
| `defaultRegion` | `string` |  | The region shown first, when uncontrolled. Default: the first. |
| `onRegionChange` | `(id: string) => void` |  | Called with the id of the region chosen. |
| `promo` | `NavbarStorePromo \| null` | `free shipping and returns` | The strip's promise; `null` leaves the strip with the region and links alone. |
| `utilityLinks` | `NavbarStoreLink[]` | `Help and Stores` | Links at the strip's end (and the drawer's foot). |
| `products` | `NavbarStoreProduct[]` | `the demo's six products` | What the search suggests, priced in the region's currency. |
| `popularSearches` | `string[]` | `four of the demo's` | Searches offered before anything is typed. |
| `onSearchSelect` | `(result: NavbarStoreSearchResult) => void` |  | Called with the product or query a search ends on. Default: go to its `href`. |
| `searchHref` | `string` | `'#search'` | The results page; a query is added as `?q=`. |
| `accountHref` | `string \| null` | `'#account'` | The account page; `null` hides the link. |
| `bag` | `NavbarStoreBag \| null` | `2 items, `#bag`` | The bag and its count; `null` hides it. |
| `brand` | `NavbarStoreBrand` | `the demo's Marlowe` | The store's name, mark and home link. |
| `locale` | `string` |  | BCP 47 locale for prices. Default: the provider's. |
| `sticky` | `boolean` | `true` | Stick to the top and turn to glass on scroll. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls under the bar. Default: the page. |
| `skipTo` | `string \| null` | `'#content'` | Where the skip link goes: your main content's id as a hash; `null` leaves it out. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<NavbarStoreCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `navLabel`, `utilityLabel`, `region`, `regionTitle`, `searchLabel`, `searchPlaceholder`, `popular`, `products`, `allResults`, `noResults`, `account`, `bag`, `menu`, `openMenu`, `closeMenu`, `skipLink`.

### Footer

A sitemap: grouped links with tags, a newsletter sign-up, trust badges, legal links, a language switch and a live status pill.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-footer
```

It brings `async-button`, `badge`, `field`, `icon-brand-github`, `icon-brand-linkedin`, `icon-brand-x`, `icon-globe`, `icon-shield-check`, `input`, `native-select`, `use-controllable-state`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingFooter, type MarketingFooterProps } from '@/blocks/marketing/footer'

export function MarketingFooterView({ brand, columns, legalLinks, badges }: Pick<MarketingFooterProps, 'brand' | 'columns' | 'legalLinks' | 'badges'>) {
  return (
    <MarketingFooter
      brand={brand}
      columns={columns}
      legalLinks={legalLinks}
      badges={badges}
      copy={{ newsletter: 'Newsletter' }}
      linkComponent={Link}
      onSubscribe={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
      onLanguageChange={(language) => {
        // your code
      }}
      onCookieSettings={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubscribe` | `(email: string) => Promise<unknown> \| unknown` | `a short demo wait` | Resolve once subscribed; reject with an Error whose message says why not. |
| `newsletter` | `boolean` | `true` | Shows the newsletter sign-up. |
| `brand` | `FooterBrand` | `the demo's Northwind` | The product's name, logo, home link and tagline. |
| `columns` | `FooterLinkColumn[]` | `the demo's Product, Solutions, Developers and Company` | The link columns, in order. |
| `legalLinks` | `FooterLink[]` | `Privacy, Terms, Security and Accessibility` | The legal links beside the copyright. An empty array hides them. |
| `badges` | `FooterLink[]` | `SOC 2 Type II, ISO 27001 and GDPR` | Trust marks under the sign-up; an empty array hides them. |
| `social` | `FooterSocialLink[]` | `GitHub, X and LinkedIn` | The social profiles, as icon buttons. An empty array hides them. |
| `languages` | `FooterLanguage[]` | `the demo's five` | The languages offered; fewer than two hides the switch. |
| `language` | `string` |  | The language shown, controlled. |
| `defaultLanguage` | `string` | `the first` | The language shown at first, uncontrolled. |
| `onLanguageChange` | `(language: string) => void` |  | Called with the language the visitor picked. |
| `onCookieSettings` | `() => void` |  | Called when "Cookie settings" is pressed; without it the button is hidden. |
| `statusState` | `'operational' \| 'degraded' \| 'outage'` | `'operational'` | The live status's state: the pill's dot and words follow it. |
| `statusHref` | `string` | `'#status'` | Where the status pill goes. |
| `controls` | `ReactNode` |  | Extra controls at the end of the bottom bar, e.g. a theme toggle. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<MarketingFooterCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `newsletter`, `subscribeLabel`, `placeholder`, `subscribe`, `subscribing`, `subscribed`, `retry`, `subscribeHint`, `invalidEmail`, `subscribeFailed`, `subscribedNote`, `navLabel`, `legal`, `status`, `statusDegraded`, `statusOutage`, `legalLabel`, `languageLabel`, `badgesLabel`, `socialLabel`, `cookieSettings`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

Building an app rather than a site? Its navigation and the rest of its chrome are built in [Create](https://www.youj.dev/create): a sidebar, a top bar with breadcrumbs, search or tabs, the workspace switcher, notifications and the account menu, with the screens you add as the pages of its nav.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every header is a `<header>` landmark holding a labelled `nav`, and the page being shown is marked with `aria-current="page"`; the Floating bar marks the section in view with `aria-current="true"`. Each starts with a skip link to your content (`skipTo`, `#content` by default), hidden until it takes keyboard focus. Links and buttons are real `a` and `button` elements with the kit's focus ring.

The Mega menu and the Store's departments are built on the kit's navigation menu, and the version and region menus on its menu: Enter, Space or ↓ opens one, Tab moves through a panel's links and the arrow keys through a menu's items, and Escape closes it and returns focus to its trigger. The previews and pictures beside the links are decorative, so the link's own words carry the meaning. ⌘K or Ctrl+K opens the Mega menu's and the Docs search from anywhere; the search palettes are dialogs whose results are a listbox you move through with the arrow keys.

The Fullscreen menu is a modal dialog named Menu. Opened from the keyboard, focus lands on its first entry; a level that drills in is a group named after its parent, focus moves to its first entry, and Back returns focus to the entry it came from. Escape closes it from any level and focus returns to Menu. The phone drawers of the Mega menu, Docs and Store are modal sheets that trap focus and return it to their button. The Floating bar's phone menu is a disclosure: its button carries `aria-expanded`, Escape or a press outside folds it, and focus goes back to the button.

The Floating bar hides as you scroll down, never while focus or its menu is inside it, and never under reduced motion. With reduced motion every header keeps its states (condensed, current, open) and shows them at once: nothing glides, rises or slides.

Footer is a `<footer>` landmark with a labelled `nav` whose link groups sit under `h2` headings. The newsletter field has a label, and the result of signing up is announced in a status region. The language switch and trust badges are labelled.

---

# Pricing

> Pricing sections: plan cards with a billing toggle, a comparison table, a seat picker, a single plan and a usage estimator.

Source: https://www.youj.dev/docs/blocks/pricing

## Blocks

### Plans

Plan cards with a monthly or yearly price toggle and a feature comparison under them. Prices roll to the new period, and on yearly the monthly price stands struck through beside each paid plan, so the toggle shows what it saves. Pick it for the usual tiered pricing page; this story opens on yearly billing.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-pricing
```

It brings `badge`, `button`, `counter`, `icon-check`, `reveal`, `shimmer-border`, `table`, `toggle-group`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Pricing, type PricingProps } from '@/blocks/marketing/pricing'

export function PricingView({ period, plans, comparison }: Pick<PricingProps, 'period' | 'plans' | 'comparison'>) {
  return (
    <Pricing
      period={period}
      plans={plans}
      comparison={comparison}
      copy={{ eyebrow: 'Pricing' }}
      linkComponent={Link}
      onPeriodChange={(period) => {
        // your code
      }}
      onSelectPlan={(plan, period) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `periodLabel`, `monthly`, `yearly`, `saveBadge`, `mostPopular`, `perUnit`, `free`, `billedMonthly`, `billedYearly`, `monthlyPrice`, `compareTitle`, `featureColumn`, `included`, `notIncluded`.

### Compare

A full feature table that keeps the plan prices and sign-up buttons in view as you scroll, with groups that fold away; the recommended plan's column carries its marks filled. Pick it when plans differ in many small ways.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-pricing-compare
```

It brings `badge`, `button`, `collapse`, `icon-check`, `icon-chevron-down`, `icon-info`, `reveal`, `segmented-control`, `tooltip`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { PricingCompare, type PricingCompareProps } from '@/blocks/marketing/pricing-compare'

export function PricingCompareView({ plans, groups }: Pick<PricingCompareProps, 'plans' | 'groups'>) {
  return (
    <PricingCompare
      plans={plans}
      groups={groups}
      copy={{ eyebrow: 'Compare plans' }}
      linkComponent={Link}
      onPlanChange={(plan) => {
        // your code
      }}
      onSelectPlan={(plan) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `priceNote`, `recommended`, `planPicker`, `featureColumn`, `included`, `notIncluded`, `about`, `ctaLabel`.

### Seat picker

Plan choice as radio cards beside an order summary that holds the seats and rolls the total as visitors choose. Pick it for per-seat pricing.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-pricing-picker
```

It brings `badge`, `button`, `collapse`, `counter`, `field`, `icon-arrow-right`, `icon-check`, `morph-label`, `number-input`, `radio-group`, `reveal`, `segmented-control`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { PricingPicker, type PricingPickerProps } from '@/blocks/marketing/pricing-picker'

export function PricingPickerView({ period, plans }: Pick<PricingPickerProps, 'period' | 'plans'>) {
  return (
    <PricingPicker
      period={period}
      plans={plans}
      copy={{ eyebrow: 'Plans' }}
      linkComponent={Link}
      onPlanChange={(plan) => {
        // your code
      }}
      onSeatsChange={(seats) => {
        // your code
      }}
      onPeriodChange={(period) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `periodLabel`, `monthly`, `yearly`, `saveBadge`, `planLabel`, `perUnit`, `includes`, `seatsLabel`, `seatsHint`, `singleSeatHint`, `summaryTitle`, `product`, `seatLine`, `yearlyBilling`, `switchToSave`, `minus`, `totalLabel`, `free`, `billedYearly`, `billedMonthly`, `trialNote`.

### Single plan

One plan with its price, the features it includes and a choice of currencies. Pick it when there is only one thing to buy.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-pricing-simple
```

It brings `button`, `counter`, `icon-arrow-right`, `icon-check`, `icon-rotate-ccw`, `icon-shield-check`, `icon-users`, `reveal`, `segmented-control`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { PricingSimple, type PricingSimpleProps } from '@/blocks/marketing/pricing-simple'

export function PricingSimpleView({ prices, features, reassurances, questions }: Pick<PricingSimpleProps, 'prices' | 'features' | 'reassurances' | 'questions'>) {
  return (
    <PricingSimple
      prices={prices}
      features={features}
      reassurances={reassurances}
      questions={questions}
      copy={{ eyebrow: 'Pricing' }}
      linkComponent={Link}
      onCurrencyChange={(currency) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `currencyLabel`, `perUnit`, `billing`, `ctaNote`, `includedTitle`, `includedDescription`.

### Usage estimator

Usage sliders and a cost breakdown that updates as visitors drag. Pick it for pay-as-you-go pricing.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-pricing-usage
```

It brings `badge`, `button`, `counter`, `icon-arrow-right`, `morph-label`, `reveal`, `slider`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { PricingUsage, type PricingUsageProps } from '@/blocks/marketing/pricing-usage'

export function PricingUsageView({ usage, meters, plans }: Pick<PricingUsageProps, 'usage' | 'meters' | 'plans'>) {
  return (
    <PricingUsage
      usage={usage}
      meters={meters}
      plans={plans}
      copy={{ eyebrow: 'Usage pricing' }}
      linkComponent={Link}
      onUsageChange={(usage) => {
        // your code
      }}
      onSelectPlan={(plan, usage, total) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `rate`, `allowance`, `estimateTitle`, `fits`, `freeLine`, `baseLine`, `withinFree`, `over`, `included`, `total`, `announce`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each section is a `<section>` named by its own heading (`aria-labelledby`); the heading is an `h2` by default and `headingLevel` changes it.

Plans labels its billing period toggle and its “included” check marks, reads a struck-through monthly price as “billed monthly”, and each plan button is described by the plan it picks (`aria-describedby`). Seat picker is a radio group of plans, each named and described by its title and blurb, with a labelled period and plan selector. Compare is a real `table` with visually hidden text for the plan and feature columns, and its folding groups use `aria-expanded` and `aria-controls`. Usage estimator’s sliders are labelled and the new total is announced in a status region. Single plan’s currency choice is a labelled control.

The buttons and links are real `a` and `button` elements with the kit’s focus ring.

---

# Product grid

> A shop's catalog on real photographs, with filters, saves and a quick view, for a storefront or collection page.

Source: https://www.youj.dev/docs/blocks/product-grid

## Blocks

### Product grid

A shop's catalog on the editorial Product card: categories as tabs with live counts, a Saved view, a Filters popover (price over its histogram, colors as swatches) whose choices become chips you can remove, and a sort. The featured product takes a wide tile, cards that stop matching fade while the rest glide into place, and a long catalog shows a page at a time.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-product-grid
```

It brings `async-button`, `button`, `commerce-product-card`, `counter`, `dialog`, `empty`, `histogram-range`, `icon-alert-triangle`, `icon-arrow-right`, `icon-chevron-left`, `icon-chevron-right`, `icon-eye`, `icon-heart`, `icon-search`, `icon-shopping-bag`, `icon-sliders`, `icon-sort`, `icon-star`, `icon-x`, `popover`, `presence-list`, `segmented-control`, `select`, `skeleton`, `toggle`, `use-announcer`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ProductGrid, type ProductGridProps } from '@/blocks/commerce/product-grid'

export function ProductGridView({ products, colors, sort, saved }: Pick<ProductGridProps, 'products' | 'colors' | 'sort' | 'saved'>) {
  return (
    <ProductGrid
      products={products}
      colors={colors}
      sort={sort}
      saved={saved}
      copy={{ eyebrow: 'The shop' }}
      linkComponent={Link}
      onAdd={async (product, choice) => {
        // await your API here; the block shows progress until it settles
      }}
      onCategoryChange={(category) => {
        // your code
      }}
      onPriceChange={(price) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Default: the theme around it. The showcase passes the chosen preset here. |
| `embedded` | `boolean` | `false` | A section inside another page: the host lays it out (no page background, section padding or max width). |
| `products` | `Product[]` | `the demo's five photographed products` | The catalog, in its featured order. |
| `featured` | `string \| null` | `'bud-vases'` | The product shown wide in the Featured order (it should come first); `null` keeps every tile the same. |
| `onAdd` | `(product: Product, choice: { color: string; size?: string }) => Promise<unknown> \| unknown` |  | Called to put a product in the bag, from a card's quick add or quick view; awaited. Default: a short demo wait. |
| `category` | `string` |  | The category shown (`''` is all), controlled. |
| `defaultCategory` | `string` | `''` | The category shown first, uncontrolled. |
| `onCategoryChange` | `(category: string) => void` |  |  |
| `price` | `[number, number]` |  | The price range `[low, high]`, controlled; the top of the range means "and up". |
| `defaultPrice` | `[number, number]` |  | The price range first set, uncontrolled. Default the whole range. |
| `onPriceChange` | `(price: [number, number]) => void` |  |  |
| `priceMax` | `number` |  | The top of the price range. Default: the dearest product, rounded up to 10. |
| `colors` | `string[]` |  | The colorway names picked, controlled. |
| `defaultColors` | `string[]` | `[]` | The colorway names picked first, uncontrolled. |
| `onColorsChange` | `(colors: string[]) => void` |  |  |
| `sort` | `'featured' \| 'price-asc' \| 'price-desc' \| 'rating'` |  | The order, controlled. |
| `defaultSort` | `'featured' \| 'price-asc' \| 'price-desc' \| 'rating'` | `'featured'` | The order first shown, uncontrolled. |
| `onSortChange` | `(sort: ProductSort) => void` |  |  |
| `saved` | `string[]` |  | The saved products' ids, controlled. |
| `defaultSaved` | `string[]` | `[]` | The products saved at first, uncontrolled. |
| `onSavedChange` | `(saved: string[]) => void` |  |  |
| `quickView` | `string \| null` |  | The product in quick view (its id; `null` is closed), controlled. |
| `defaultQuickView` | `string \| null` | `null` | The product in quick view at first, uncontrolled. |
| `onQuickViewChange` | `(id: string \| null) => void` |  |  |
| `pageSize` | `number` | `12` | How many products show before Load more. |
| `loading` | `boolean` | `false` | Shows skeleton cards while the catalog loads. |
| `error` | `ReactNode` |  | Why the catalog didn't load: shown with a retry instead of the grid. |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Replaces the "no matches" message. |
| `renderItem` | `(product: Product) => ReactNode` |  | Draws each product instead of a Product card. |
| `currency` | `string` |  | An ISO 4217 code. Default: the format around it, else 'USD'. |
| `locale` | `string` |  | A BCP 47 locale for prices and counts. Default: the app's (YoujProvider). |
| `linkComponent` | `ElementType` | `'a'` | Renders each product link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The heading's level. |
| `copy` | `Partial<ProductGridCopy>` |  | Any of the grid's strings, to rewrite or translate. |
| `cardCopy` | `Partial<ProductCardCopy>` |  | The cards' strings. |

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `categories`, `all`, `filters`, `filtersSet`, `price`, `minPrice`, `maxPrice`, `color`, `clearFilters`, `clearAll`, `showResults`, `activeFilters`, `removeFilter`, `sortBy`, `sorts`, `saved`, `save`, `savedNotice`, `unsavedNotice`, `quickView`, `count`, `showing`, `loadMore`, `loading`, `list`, `emptyTitle`, `emptyDescription`, `savedEmptyTitle`, `savedEmptyDescription`, `showAll`, `errorTitle`, `retry`, `close`, `previous`, `next`, `position`, `views`, `front`, `side`, `size`, `soldOut`, `pickSize`, `addToBag`, `adding`, `added`, `addError`, `details`, `reviews`, `rated`.

### Quick view

Look closer without leaving the grid: the photo flies out of its tile into the dialog while the details rise around it, ← and → step through the grid's order, and closing flies it home onto its tile. Pick a colorway, a size and add it to the bag, or save it for later.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-product-grid
```

```tsx
'use client'

import Link from 'next/link'
import { ProductGrid, type ProductGridProps } from '@/blocks/commerce/product-grid'

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Default: the theme around it. The showcase passes the chosen preset here. |
| `embedded` | `boolean` | `false` | A section inside another page: the host lays it out (no page background, section padding or max width). |
| `products` | `Product[]` | `the demo's five photographed products` | The catalog, in its featured order. |
| `featured` | `string \| null` | `'bud-vases'` | The product shown wide in the Featured order (it should come first); `null` keeps every tile the same. |
| `onAdd` | `(product: Product, choice: { color: string; size?: string }) => Promise<unknown> \| unknown` |  | Called to put a product in the bag, from a card's quick add or quick view; awaited. Default: a short demo wait. |
| `category` | `string` |  | The category shown (`''` is all), controlled. |
| `defaultCategory` | `string` | `''` | The category shown first, uncontrolled. |
| `onCategoryChange` | `(category: string) => void` |  |  |
| `price` | `[number, number]` |  | The price range `[low, high]`, controlled; the top of the range means "and up". |
| `defaultPrice` | `[number, number]` |  | The price range first set, uncontrolled. Default the whole range. |
| `onPriceChange` | `(price: [number, number]) => void` |  |  |
| `priceMax` | `number` |  | The top of the price range. Default: the dearest product, rounded up to 10. |
| `colors` | `string[]` |  | The colorway names picked, controlled. |
| `defaultColors` | `string[]` | `[]` | The colorway names picked first, uncontrolled. |
| `onColorsChange` | `(colors: string[]) => void` |  |  |
| `sort` | `'featured' \| 'price-asc' \| 'price-desc' \| 'rating'` |  | The order, controlled. |
| `defaultSort` | `'featured' \| 'price-asc' \| 'price-desc' \| 'rating'` | `'featured'` | The order first shown, uncontrolled. |
| `onSortChange` | `(sort: ProductSort) => void` |  |  |
| `saved` | `string[]` |  | The saved products' ids, controlled. |
| `defaultSaved` | `string[]` | `[]` | The products saved at first, uncontrolled. |
| `onSavedChange` | `(saved: string[]) => void` |  |  |
| `quickView` | `string \| null` |  | The product in quick view (its id; `null` is closed), controlled. |
| `defaultQuickView` | `string \| null` | `null` | The product in quick view at first, uncontrolled. |
| `onQuickViewChange` | `(id: string \| null) => void` |  |  |
| `pageSize` | `number` | `12` | How many products show before Load more. |
| `loading` | `boolean` | `false` | Shows skeleton cards while the catalog loads. |
| `error` | `ReactNode` |  | Why the catalog didn't load: shown with a retry instead of the grid. |
| `onRetry` | `() => void` |  |  |
| `empty` | `ReactNode` |  | Replaces the "no matches" message. |
| `renderItem` | `(product: Product) => ReactNode` |  | Draws each product instead of a Product card. |
| `currency` | `string` |  | An ISO 4217 code. Default: the format around it, else 'USD'. |
| `locale` | `string` |  | A BCP 47 locale for prices and counts. Default: the app's (YoujProvider). |
| `linkComponent` | `ElementType` | `'a'` | Renders each product link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The heading's level. |
| `copy` | `Partial<ProductGridCopy>` |  | Any of the grid's strings, to rewrite or translate. |
| `cardCopy` | `Partial<ProductCardCopy>` |  | The cards' strings. |

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The grid is a `<section>` named by its own heading (`aria-labelledby`); the heading is an `h1` by default and `headingLevel` changes it, and every product is an article named by its link. The category tabs are a labeled group, the Filters popover's price is a two-thumb slider with named ends and its colors are checkboxes, and every chip is a button that says what it removes, handing focus to its neighbor (or the count) when it goes. The count of matching products is a polite status, and saving one is announced.

Each card's heart is a toggle button (`aria-pressed`) named for its product. Quick view is a modal dialog named by the product: focus moves to it and back to the card's quick view button when it closes, Escape closes it, ← and → step through the grid when focus isn't in a field, and its sizes are a radio group with the sold-out ones disabled. Under reduced motion nothing flies and the dialog simply appears.

---

# Product showcase

> Interactive and informational sections that show the product off: a guided tour, a live theme playground, role-based solutions, integrations, release news and a comparison table.

Source: https://www.youj.dev/docs/blocks/showcase

## Blocks

### Product tour

Let visitors try the product instead of watching it: a rail of steps beside a live window of real components, a beacon pinging on the control each step asks them to try, each step checked off as they do it and a progress line that fills.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-product-tour
```

It brings `async-button`, `avatar`, `badge`, `button`, `icon-arrow-right`, `icon-check`, `icon-check-circle`, `icon-git-branch`, `icon-message`, `icon-rocket`, `progress`, `reveal`, `slider`, `switch`, `tabs`, `textarea`, `use-controllable-state`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ProductTour, type ProductTourProps } from '@/blocks/marketing/product-tour'

export function ProductTourView({ steps, done }: Pick<ProductTourProps, 'steps' | 'done'>) {
  return (
    <ProductTour
      steps={steps}
      done={done}
      copy={{ eyebrow: 'Product tour' }}
      linkComponent={Link}
      onValueChange={(value) => {
        // your code
      }}
      onDoneChange={(done) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `stepsLabel`, `stepName`, `progress`, `address`, `back`, `next`, `finish`, `reset`, `try`, `stepDone`, `connectRepo`, `commentPin`, `replyPlaceholder`, `replyLabel`, `trafficLabel`.

### Theme playground

Let visitors re-theme a small landing page live with a preset, accent, corners, control size and style. Pick it to show how far the theme goes.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-theme-playground
```

It brings `async-button`, `badge`, `button`, `card`, `color-picker`, `icon-chart-spline`, `icon-copy`, `icon-layers`, `icon-moon`, `icon-rotate-ccw`, `icon-shield`, `icon-sparkles`, `icon-sun`, `input`, `label`, `progress`, `radio-group`, `segmented-control`, `switch`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the section in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | Inside another page: a `section` named by an `h2`. |
| `defaultPalette` | `'youj' \| 'meadow' \| 'sandstone' \| 'cinnabar' \| 'umber' \| 'seaglass' \| 'heather'` |  | The palette the preview starts on. Default: the page's own, or Youj. |
| `defaultStyle` | `'terminal' \| 'clean' \| 'classic' \| 'bezel' \| 'brutal'` |  | The style the preview starts on. Default: the page's own, or Clean. |
| `defaultMode` | `'light' \| 'dark'` |  | The preview's mode at first. Default: the page's own. |

### Solutions

Speak to each buyer on one page: pick a role and an industry, and the pitch, a customer quote, the call to action, the live numbers and the activity feed change to match.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-solutions
```

It brings `button`, `counter`, `icon-arrow-right`, `icon-check`, `icon-code`, `icon-palette`, `icon-quote`, `icon-target`, `presence-list`, `reveal`, `segmented-control`, `tabs`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Solutions, type SolutionsProps } from '@/blocks/marketing/solutions'

export function SolutionsView({ roles, industries }: Pick<SolutionsProps, 'roles' | 'industries'>) {
  return (
    <Solutions
      roles={roles}
      industries={industries}
      copy={{ eyebrow: 'Solutions' }}
      linkComponent={Link}
      onValueChange={(role) => {
        // your code
      }}
      onIndustryChange={(industry) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `roleLabel`, `industryLabel`, `cta`, `panel`, `feedLabel`, `statsLabel`, `noValue`, `showing`.

### Integrations

Show what the product connects to with searchable, categorized cards that each carry a status, and a detail sheet with the connection’s health and sync history.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-integrations
```

It brings `async-button`, `badge`, `button`, `empty`, `history-strip`, `icon-check`, `icon-check-circle`, `icon-chevron-right`, `icon-external-link`, `icon-search`, `icon-x`, `input-group`, `presence-list`, `reveal`, `sheet`, `skeleton`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingIntegrations, type MarketingIntegrationsProps } from '@/blocks/marketing/integrations'

export function MarketingIntegrationsView({ integrations }: Pick<MarketingIntegrationsProps, 'integrations'>) {
  return (
    <MarketingIntegrations
      integrations={integrations}
      copy={{ eyebrow: 'Integrations' }}
      linkComponent={Link}
      onQueryChange={(query) => {
        // your code
      }}
      onCategoryChange={(category) => {
        // your code
      }}
      onOpen={(integration) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `search`, `searchPlaceholder`, `categories`, `all`, `connected`, `results`, `status`, `health`, `popular`, `details`, `noResultsTitle`, `noResultsDescription`, `clearSearch`, `request`, `loadingLabel`, `about`, `whatItDoes`, `permissions`, `permissionsNote`, `connection`, `healthLabel`, `account`, `connectedBy`, `connectedOn`, `lastSync`, `syncHistory`, `docs`, `connect`, `connecting`, `disconnect`, `disconnecting`, `reconnect`, `notifyMe`, `failed`, `close`.

### What’s new

Show that the product keeps moving: the newest change as a feature card, earlier changes as a dated list with kind tags and expandable details, an area filter and a way to load more.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-whats-new
```

It brings `async-button`, `badge`, `button`, `collapse`, `icon-arrow-right`, `icon-check`, `icon-check-circle`, `icon-chevron-down`, `icon-history`, `icon-rss`, `presence-list`, `reveal`, `segmented-control`, `select`, `skeleton`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { WhatsNew, type WhatsNewProps } from '@/blocks/marketing/whats-new'

export function WhatsNewView({ entries }: Pick<WhatsNewProps, 'entries'>) {
  return (
    <WhatsNew
      entries={entries}
      copy={{ eyebrow: 'What’s new' }}
      linkComponent={Link}
      onCategoryChange={(category) => {
        // your code
      }}
      onLoadMore={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `filterLabel`, `all`, `kind`, `latest`, `release`, `readNotes`, `more`, `moreLabel`, `changelog`, `subscribe`, `loadMore`, `loadingMore`, `empty`, `loadingLabel`.

### Comparison

Put the product beside the alternatives in one table: yours raised on a panel of its own, a sticky head with price, coverage and a call to action, grouped features that explain themselves, a switch for only the differences, and one alternative at a time on a phone.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-product-comparison
```

It brings `badge`, `button`, `icon-check`, `icon-info`, `icon-minus`, `progress`, `reveal`, `segmented-control`, `switch`, `tooltip`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ProductComparison, type ProductComparisonProps } from '@/blocks/marketing/product-comparison'

export function ProductComparisonView({ products, groups }: Pick<ProductComparisonProps, 'products' | 'groups'>) {
  return (
    <ProductComparison
      products={products}
      groups={groups}
      copy={{ eyebrow: 'Compare' }}
      linkComponent={Link}
      onAlternativeChange={(id) => {
        // your code
      }}
      onDifferencesOnlyChange={(on) => {
        // your code
      }}
      onChoose={(product) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `verified`, `correct`, `featureColumn`, `differencesOnly`, `coverage`, `coverageLabel`, `ours`, `included`, `partial`, `notIncluded`, `about`, `picker`, `noDifferences`, `ctaLabel`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every section here is a `<section>` named by its own heading (`aria-labelledby`). The heading is an `h2` by default and `headingLevel` changes it; the pieces with items below the title (Product tour, Solutions, What’s new) set theirs one level deeper.

Product tour and Solutions are built on Tabs: the tab list is named, Left and Right Arrow move between tabs, Home and End jump to the ends, and the panel follows the selected tab. Product tour announces a finished tour in a polite status region; Solutions announces the role and industry in view the same way. Product tour’s beacon is decoration (`aria-hidden`, and it never takes a click): the step’s “Try it” prompt says the same in words, and under reduced motion the beacon is a still dot.

Integrations has a labelled search field, a categories `nav` whose buttons use `aria-pressed`, and a result count in a status region; its detail sheet traps focus and closes with Escape. What’s new’s area filter and Product comparison’s alternative picker and “only differences” switch are named controls, and Product comparison is a real `table` with visually hidden text in its cells and a labelled coverage bar. Theme playground groups its controls under a label, announces the applied recipe in a status region, and renders its preview as a decorative frame (`inert`) around a real page.

The links and buttons are real `a` and `button` elements with the kit’s focus ring.

App logos in the Integrations demo are trademarks of their owners, shown for illustration only.

---

# Social proof

> Sections that build trust: a wall of what customers say, logos and ratings, a logo cloud, a customer story, headline metrics and a security overview.

Source: https://www.youj.dev/docs/blocks/proof

## Blocks

### Testimonial wall

Let customers make the case in their own words: columns of quotes drift past each other with no seam, the column you point at eases to a stop while the others recede, and one button pauses the whole wall. Each quote sets the phrase that matters in full ink. Under reduced motion the columns stand still, folded, with Show all.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-testimonial-wall
```

It brings `avatar`, `button`, `icon-arrow-right`, `icon-play`, `icon-star`, `marquee`, `rating`, `reveal`, `skeleton`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { TestimonialWall, type TestimonialWallProps } from '@/blocks/marketing/testimonial-wall'

export function TestimonialWallView({ quotes }: Pick<TestimonialWallProps, 'quotes'>) {
  return (
    <TestimonialWall
      quotes={quotes}
      copy={{ eyebrow: 'Wall of love' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `wallLabel`, `outOf`, `reviews`, `sourcesLabel`, `rated`, `pause`, `play`, `showAll`, `showFewer`, `empty`, `loading`.

### Logos and ratings

Show who else uses the product in one section: a rating summary, the customers' wordmarks on a hairline grid lit by the pointer with an industry filter, and the featured customer story as an editorial panel whose results roll up. Pointing at a customer with a story says so.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-social-proof
```

It brings `avatar`, `counter`, `icon-arrow-right`, `presence-list`, `progress`, `rating`, `reveal`, `segmented-control`, `select`, `skeleton`, `spotlight`, `tabs`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { SocialProof, type SocialProofProps } from '@/blocks/marketing/social-proof'

export function SocialProofView({ logos, stories }: Pick<SocialProofProps, 'logos' | 'stories'>) {
  return (
    <SocialProof
      logos={logos}
      stories={stories}
      copy={{ eyebrow: 'Customers' }}
      linkComponent={Link}
      onIndustryChange={(industry) => {
        // your code
      }}
      onStoryChange={(id) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `filterLabel`, `all`, `wall`, `noLogos`, `openStory`, `storyEyebrow`, `readStory`, `results`, `ratingTitle`, `outOf`, `reviews`, `stars`, `sources`.

### Logo cloud

The customers' logos under one quiet line: a grid that trades its logos in place, one cell at a time (the leaving logo drifts up and blurs away as the next rises in), so twice the customers fit in the same room; or, with `variant="marquee"`, a row that drifts with no seam. It rests while pointed at or off screen, and a small button pauses it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-logo-cloud
```

It brings `button`, `icon-play`, `marquee`, `reveal`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { LogoCloud, type LogoCloudProps } from '@/blocks/marketing/logo-cloud'

export function LogoCloudView({ logos }: Pick<LogoCloudProps, 'logos'>) {
  return (
    <LogoCloud
      logos={logos}
      copy={{ title: 'Trusted by 40,000 teams, from two-person startups to the Fortune 500' }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `listLabel`, `pause`, `play`.

### Customer story

Tell a customer story as a long read: results as counting figures with a before and now bar, chapters with a contents that follows the reader, a pull quote and the next story.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-customer-story
```

It brings `anchor-nav`, `avatar`, `button`, `counter`, `icon-arrow-right`, `icon-check`, `icon-quote`, `icon-trending-down`, `icon-trending-up`, `reveal`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CustomerStory, type CustomerStoryProps } from '@/blocks/marketing/customer-story'

export function CustomerStoryView({ customer, facts, metrics, chapters }: Pick<CustomerStoryProps, 'customer' | 'facts' | 'metrics' | 'chapters'>) {
  return (
    <CustomerStory
      customer={customer}
      facts={facts}
      metrics={metrics}
      chapters={chapters}
      copy={{ eyebrow: 'Customer story' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `onThisPage`, `factsLabel`, `resultsTitle`, `down`, `up`, `from`, `before`, `after`, `quoteLabel`, `next`, `ctaTitle`, `ctaDescription`, `ctaPrimary`, `ctaSecondary`.

### Metrics

Back claims with numbers that come with context: figures that count up for a chosen period, the change on the one before, a trend line, a baseline and a footnote for the source.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-metrics
```

It brings `counter`, `icon-trending-down`, `icon-trending-up`, `reveal`, `segmented-control`, `skeleton`, `sparkline`, `stagger`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MarketingMetrics, type MarketingMetricsProps } from '@/blocks/marketing/metrics'

export function MarketingMetricsView({ metrics, periods, sources }: Pick<MarketingMetricsProps, 'metrics' | 'periods' | 'sources'>) {
  return (
    <MarketingMetrics
      metrics={metrics}
      periods={periods}
      sources={sources}
      copy={{ eyebrow: 'By the numbers' }}
      onPeriodChange={(period) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `periodLabel`, `baseline`, `ours`, `showing`, `up`, `down`, `noData`, `sourcesLabel`, `source`, `trend`.

### Security

Answer a security review in one place: live status with a strip of daily uptime, certifications with a report on request, data residency on a map, the practices behind it and the policy documents.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-security
```

It brings `async-button`, `badge`, `dot-map`, `history-strip`, `icon-alert-triangle`, `icon-arrow-up-right`, `icon-check`, `icon-check-circle`, `icon-clock`, `icon-external-link`, `icon-eye`, `icon-file-text`, `icon-fingerprint`, `icon-globe`, `icon-key`, `icon-lock`, `icon-server`, `icon-shield-check`, `reveal`, `segmented-control`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { MarketingSecurity, type MarketingSecurityProps } from '@/blocks/marketing/security'

export function MarketingSecurityView({ certifications, regions, practices, policies }: Pick<MarketingSecurityProps, 'certifications' | 'regions' | 'practices' | 'policies'>) {
  return (
    <MarketingSecurity
      certifications={certifications}
      regions={regions}
      practices={practices}
      policies={policies}
      copy={{ eyebrow: 'Security and trust' }}
      linkComponent={Link}
      onRegionChange={(region) => {
        // your code
      }}
      onRequestReport={async (certification) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `eyebrow`, `title`, `description`, `state`, `uptime`, `checked`, `statusPage`, `statusStrip`, `certifications`, `certified`, `inProgress`, `validThrough`, `auditedBy`, `requestReport`, `requesting`, `requested`, `requestLabel`, `residency`, `residencyDescription`, `regionLabel`, `staysIn`, `processedElsewhere`, `mapLabel`, `practices`, `policies`, `updated`, `open`, `failed`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each section is a `<section>` named by its own heading (`aria-labelledby`); the heading is an `h2` by default and `headingLevel` changes it. Customer story is an `article` with its own `header` and `footer`.

Testimonial wall is a named list that screen readers read once: the columns' repeats are `inert` and hidden from assistive technology. The moving wall has a Pause button (WCAG 2.2.2) and stops a column while it is pointed at or holds focus, bringing a focused link clear of the faded edge; stars are read as "Rated 5 out of 5", and the folded wall's Show all reports `aria-expanded`.

Logo cloud gives screen readers every customer once, as a named list, and hides the moving picture; its pause button names what it does, and it never moves under reduced motion.

Logos and ratings names its rating group and gives the logo wall a labelled filter whose buttons use `aria-pressed`; customers with a story are buttons named "read the story", the others images with a label, and the story tabs work from the keyboard. Metrics reads each figure with visually hidden context (the change and period) and announces a period switch in a status region. Customer story gives its results and contents nav labels. Security labels its lists, and the data residency list announces the selected region in a live region.

Figures that count up end on the same text a screen reader gets. The animated parts check the reduced-motion setting. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# API and integrations

> Developer-facing screens: API keys, webhooks and an integrations directory.

Source: https://www.youj.dev/docs/blocks/api-and-integrations

## Blocks

### API keys

Manage API keys in a table with scopes and recent use, and a dialog for creating a new key that shows its secret once.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-api-keys
```

It brings `alert`, `alert-dialog`, `app-page`, `async-button`, `avatar`, `badge`, `button`, `dialog`, `dropdown-menu`, `empty`, `field`, `icon-copy`, `icon-key`, `icon-more-horizontal`, `icon-plus`, `icon-refresh`, `icon-shield`, `icon-trash`, `input`, `presence-list`, `reveal`, `scramble-text`, `segmented-control`, `select`, `skeleton`, `sliding-indicator`, `sparkline`, `stat-card`, `table`, `toggle-group`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ApiKeys, type ApiKeysProps } from '@/blocks/app/api-keys'

export function ApiKeysView({ env, keys, resources, expiries }: Pick<ApiKeysProps, 'env' | 'keys' | 'resources' | 'expiries'>) {
  return (
    <ApiKeys
      env={env}
      keys={keys}
      resources={resources}
      expiries={expiries}
      copy={{ title: 'API keys' }}
      linkComponent={Link}
      onEnvChange={(env) => {
        // your code
      }}
      onCreate={async (key) => {
        // await your API here; the block shows progress until it settles
      }}
      onRoll={async (key) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `defaultEnv` | `'live' \| 'test'` | `'live'` | The environment shown when uncontrolled. |
| `env` | `'live' \| 'test'` |  | The environment shown, controlled. Pair it with `onEnvChange`. |
| `onEnvChange` | `(env: Env) => void` |  | Called with the environment the switch picks. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own. |
| `product` | `string` | `'Ledger'` | The product the keys are for, in the copy ("authenticate your server with …"). Prefer `brand`. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The product's name and mark: the top bar's brand and the name in the copy. Default: Ledger, with an "L/" mark. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's level. |
| `locale` | `string` |  | Formats relative times and counts. Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `keys` | `ApiKey[]` | `the demo's four live keys` | The keys, both environments; the block keeps its own copy as keys are created, rolled and revoked. |
| `resources` | `string[]` | `Charges, Customers, Payouts, Webhooks` | The resources a key can be granted read or write on. |
| `expiries` | `ApiKeyExpiry[]` | `never, 30 days, 90 days, a year` | The expiry choices in the create dialog; `'never'` reads as no expiry. |
| `nav` | `ApiKeysNavLink[]` | `the demo's five, on API keys` | The top bar's links (standalone only). |
| `now` | `Date \| number` | `a fixed demo instant` | "Now", for "last used" times and the unused count. |
| `onCreate` | `(key: ApiKeyDraft) => Promise<string> \| string` |  | Creates a key on your server and returns its full secret, which is shown once. Default: a demo wait and a random secret. |
| `onRoll` | `(key: ApiKey) => Promise<string> \| string` |  | Rolls a key's secret on your server and returns the new one. Default: a demo random secret. |
| `onRevoke` | `(key: ApiKey) => Promise<unknown> \| unknown` |  | Revokes a key; resolve when it's gone, throw to show why it failed. Default: a short demo wait. |
| `loading` | `boolean` | `false` | Shows skeleton rows in place of the table while keys load. |
| `empty` | `ReactNode` |  | Replaces the empty state shown when an environment has no keys. |
| `error` | `ReactNode` |  | A load failure, shown over the table with a Retry button when `onRetry` is set. |
| `onRetry` | `() => void` |  | Called from the error's Retry button. |
| `copy` | `Partial<ApiKeysCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `defaultCreateOpen` | `boolean` | `false` | Whether the create-key dialog is open when uncontrolled; true opens it with the page. |
| `createOpen` | `boolean` |  | Whether the create-key dialog is open, controlled. Pair it with `onCreateOpenChange`. |
| `onCreateOpenChange` | `(open: boolean) => void` |  | Called with the create-key dialog's new open state. |
| `linkComponent` | `ElementType` | `'a'` | Renders the top bar's links, e.g. Next.js `Link`. |

**Strings:** `copy` takes `title`, `description`, `environment`, `live`, `test`, `createKey`, `health`, `liveKeys`, `testKeys`, `active`, `requests`, `lastWeek`, `unused`, `unusedNote`, `keysRegion`, `emptyTitle`, `emptyDescription`, `emptyAction`, `loading`, `footnote`, `revokeTitle`, `revokeDescription`, `revokeConfirm`, `table`, `name`, `key`, `scopes`, `createdBy`, `lastUsed`, `traffic`, `actions`, `actionsFor`, `noExpiry`, `expiresIn`, `ending`, `fullAccess`, `trafficLabel`, `copyId`, `roll`, `revoke`, `never`, `justNow`, `newKey`, `newKeyDescription`, `ready`, `readyDescription`, `namePlaceholder`, `nameRequired`, `permissions`, `permissionsDescription`, `permissionsGroup`, `resourceAccess`, `none`, `read`, `write`, `permissionRequired`, `expires`, `cancel`, `minting`, `created`, `you`, `copyNow`, `shownOnce`, `secret`, `copySecret`, `copied`, `copyFailed`, `saved`, `rolledTitle`, `rolledDescription`, `errorTitle`, `retry`, `failed`, `brandBadge`, `nav`.

### Create key

The create-key flow: name the key, choose None, Read or Write for each resource, pick an expiry, then copy the secret, which is shown once. A key with no access, or without a name, is refused before anything is sent.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-api-keys
```

```tsx
'use client'

import Link from 'next/link'
import { ApiKeys, type ApiKeysProps } from '@/blocks/app/api-keys'

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `defaultEnv` | `'live' \| 'test'` | `'live'` | The environment shown when uncontrolled. |
| `env` | `'live' \| 'test'` |  | The environment shown, controlled. Pair it with `onEnvChange`. |
| `onEnvChange` | `(env: Env) => void` |  | Called with the environment the switch picks. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own. |
| `product` | `string` | `'Ledger'` | The product the keys are for, in the copy ("authenticate your server with …"). Prefer `brand`. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The product's name and mark: the top bar's brand and the name in the copy. Default: Ledger, with an "L/" mark. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's level. |
| `locale` | `string` |  | Formats relative times and counts. Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `keys` | `ApiKey[]` | `the demo's four live keys` | The keys, both environments; the block keeps its own copy as keys are created, rolled and revoked. |
| `resources` | `string[]` | `Charges, Customers, Payouts, Webhooks` | The resources a key can be granted read or write on. |
| `expiries` | `ApiKeyExpiry[]` | `never, 30 days, 90 days, a year` | The expiry choices in the create dialog; `'never'` reads as no expiry. |
| `nav` | `ApiKeysNavLink[]` | `the demo's five, on API keys` | The top bar's links (standalone only). |
| `now` | `Date \| number` | `a fixed demo instant` | "Now", for "last used" times and the unused count. |
| `onCreate` | `(key: ApiKeyDraft) => Promise<string> \| string` |  | Creates a key on your server and returns its full secret, which is shown once. Default: a demo wait and a random secret. |
| `onRoll` | `(key: ApiKey) => Promise<string> \| string` |  | Rolls a key's secret on your server and returns the new one. Default: a demo random secret. |
| `onRevoke` | `(key: ApiKey) => Promise<unknown> \| unknown` |  | Revokes a key; resolve when it's gone, throw to show why it failed. Default: a short demo wait. |
| `loading` | `boolean` | `false` | Shows skeleton rows in place of the table while keys load. |
| `empty` | `ReactNode` |  | Replaces the empty state shown when an environment has no keys. |
| `error` | `ReactNode` |  | A load failure, shown over the table with a Retry button when `onRetry` is set. |
| `onRetry` | `() => void` |  | Called from the error's Retry button. |
| `copy` | `Partial<ApiKeysCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `defaultCreateOpen` | `boolean` | `false` | Whether the create-key dialog is open when uncontrolled; true opens it with the page. |
| `createOpen` | `boolean` |  | Whether the create-key dialog is open, controlled. Pair it with `onCreateOpenChange`. |
| `onCreateOpenChange` | `(open: boolean) => void` |  | Called with the create-key dialog's new open state. |
| `linkComponent` | `ElementType` | `'a'` | Renders the top bar's links, e.g. Next.js `Link`. |

### Webhooks

Manage webhook endpoints with delivery status and subscribed events in one table, a delivery log with filters and a sheet for editing an endpoint.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-webhooks
```

It brings `alert-dialog`, `app-page`, `async-button`, `badge`, `button`, `checkbox`, `code-block`, `dropdown-menu`, `empty`, `field`, `icon-activity`, `icon-copy`, `icon-eye`, `icon-eye-off`, `icon-more-horizontal`, `icon-pencil`, `icon-plus`, `icon-power`, `icon-refresh`, `icon-send`, `icon-trash`, `icon-webhook`, `input`, `presence-list`, `reveal`, `scramble-text`, `segmented-control`, `sheet`, `switch`, `table`, `tabs`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Webhooks, type WebhooksProps } from '@/blocks/app/webhooks'

export function WebhooksView({ endpoints, deliveries }: Pick<WebhooksProps, 'endpoints' | 'deliveries'>) {
  return (
    <Webhooks
      endpoints={endpoints}
      deliveries={deliveries}
      copy={{ brand: 'Northwind' }}
      onTest={async (endpoint, event) => {
        // await your API here; the block shows progress until it settles
      }}
      onSaveEndpoint={async (endpoint) => {
        // await your API here; the block shows progress until it settles
      }}
      onDeleteEndpoint={async (endpoint) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width. |
| `copy` | `Partial<WebhooksCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `endpoints` | `Endpoint[]` |  | The endpoints to start with. Default: three demo endpoints. |
| `deliveries` | `Delivery[]` |  | Their recent deliveries, newest first; fresh ones you pass replace the log. Default: the demo's. |
| `now` | `Date \| number` |  | The time delivery ages are measured from, which the server and the browser agree on. Default: the demo's fixed time with the demo deliveries; with yours, the browser's clock once mounted. |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the page shows the demo's endpoints and deliveries (neither passed). |
| `onTest` | `(endpoint: Endpoint, event: string) => Promise<Delivery \| unknown> \| Delivery \| unknown` |  | Sends a test event to an endpoint; resolve with the resulting delivery to log it. Default: the demo logs a successful one. |
| `onSaveEndpoint` | `(endpoint: Endpoint) => Promise<unknown> \| unknown` |  | Saves an added or edited endpoint; the sheet closes once it resolves, and a rejection's message shows on its button. Default: a short demo wait. |
| `onDeleteEndpoint` | `(endpoint: Endpoint) => Promise<unknown> \| unknown` |  | Deletes an endpoint after the confirmation; it leaves the list once it resolves. Default: a short demo wait. |
| `onRotateSecret` | `(endpoint: Endpoint) => Promise<unknown> \| unknown` |  | Rotates an endpoint's signing secret; resolve with the new secret to show it (otherwise the demo makes one). Default: a short demo wait. |
| `onResend` | `(delivery: Delivery) => Promise<unknown> \| unknown` |  | Sends a delivery again; resolve with the new attempt to log it. Default: the demo logs a successful one. |

**Strings:** `copy` takes `brand`, `title`, `description`, `add`, `endpointsLabel`, `endpoint`, `events`, `status`, `lastDelivery`, `actions`, `actionsFor`, `enabled`, `disabled`, `failing`, `never`, `eventCount`, `edit`, `sendTest`, `enable`, `disable`, `remove`, `emptyTitle`, `emptyDescription`, `deleteTitle`, `deleteDescription`, `deleteConfirm`, `addTitle`, `editTitle`, `sheetDescription`, `url`, `urlPlaceholder`, `urlRequired`, `urlInvalid`, `urlInsecure`, `urlDuplicate`, `endpointDescription`, `endpointDescriptionPlaceholder`, `eventsHint`, `eventsRequired`, `selected`, `selectAll`, `clear`, `secret`, `secretHint`, `reveal`, `hide`, `copy`, `copied`, `rotate`, `rotateTitle`, `rotateDescription`, `rotateConfirm`, `rotated`, `active`, `activeHint`, `cancel`, `save`, `saving`, `saved`, `deliveries`, `deliveriesFor`, `filter`, `all`, `succeeded`, `failed`, `noDeliveries`, `noDeliveriesDescription`, `timeout`, `duration`, `attempt`, `sent`, `request`, `response`, `noResponse`, `resend`, `resending`, `resent`, `pickDelivery`, `demoData`, `locale`.

### Integrations

Help users find integrations and review what each one can access before installing it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-integrations
```

It brings `alert`, `app-page`, `async-button`, `badge`, `breadcrumb`, `button`, `card`, `carousel`, `counter`, `dropdown-menu`, `empty`, `field`, `icon-arrow-right`, `icon-badge-check`, `icon-check`, `icon-chevron-down`, `icon-plug`, `icon-search`, `icon-shield-check`, `input-group`, `mesh-gradient`, `presence-list`, `reveal`, `sheet`, `skeleton`, `sliding-indicator`, `spotlight`, `switch`, `toggle-group`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Integrations, type IntegrationsProps } from '@/blocks/app/integrations'

export function IntegrationsView({ integrations, categories, installed }: Pick<IntegrationsProps, 'integrations' | 'categories' | 'installed'>) {
  return (
    <Integrations
      integrations={integrations}
      categories={categories}
      installed={installed}
      copy={{ title: 'Integrations' }}
      onInstalledChange={(ids) => {
        // your code
      }}
      onConnect={async (app) => {
        // await your API here; the block shows progress until it settles
      }}
      onDisconnect={async (app) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `tagline`, `installedCount`, `search`, `searchPlaceholder`, `show`, `all`, `installed`, `categories`, `allCategories`, `count`, `inCategory`, `list`, `loading`, `emptyTitle`, `emptyInstalled`, `emptyAll`, `verified`, `installs`, `byVendor`, `screenshots`, `screenshot`, `abilities`, `permissions`, `install`, `installing`, `uninstall`, `removing`, `removed`, `featured`, `manage`, `seeHow`, `errorTitle`, `retry`, `failed`.

### Integration detail

One connected app as a page: a sample of what it posts, the connection's details with a status menu to pause, reconnect or disconnect, and a switch for each permission it holds.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-integrations
```

```tsx
'use client'

import { Integrations, type IntegrationsProps } from '@/blocks/app/integrations'

**Props**

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each screen is a `main` with labelled sections. API keys and Webhooks are tables whose row actions sit in a menu with arrow-key navigation. The create-key dialog and the secret reveal trap focus and close with Escape. Webhooks’ delivery filters use `aria-pressed` and its event picker is a labelled group. Integrations has a labelled search field, a category rail of toggle buttons (`aria-pressed`), a result count in a status region, and a detail sheet that lists the access an app asks for. The integration detail is a labelled region with a breadcrumb, a status menu button that names the current status, and a labelled switch for every permission (switches are disabled once the app is disconnected). Each resource in the create-key dialog is a labelled group of None, Read and Write buttons. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Assistant

> AI conversation screens: a streamed analyst workspace.

Source: https://www.youj.dev/docs/blocks/assistant

## Blocks

### AI workspace

Ask an AI analyst about your team’s data, with streamed answers that show their reasoning, tool calls and sources, a history sidebar and a sheet on phones.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-ai-workspace
```

It brings `app-page`, `async-button`, `avatar`, `button`, `chat`, `icon-file-text`, `icon-menu`, `icon-pencil`, `icon-search`, `icon-share`, `icon-sparkles`, `input-group`, `select`, `sheet`, `sliding-indicator`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) titled with the open chat, holding Share, over the chat list and the conversation filling the page; no `main` of its own. |
| `autoplay` | `boolean` | `true` | Answer the open chat's question live as the workspace opens. |
| `defaultModel` | `'deep' \| 'fast'` | `'deep'` | Atlas Deep thinks before it answers; Atlas Fast doesn't. |

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

AI workspace has a `main` with one `h1`, a labelled history `nav` that marks the current chat with `aria-current`, a status region for progress, and a sheet for the history on phones. The streamed answer starts on its own (set `autoplay` to `false` to start it still), and under reduced motion text lands a phrase at a time and the shimmer and carets hold still. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Authentication

> Authentication screens: sign in, sign up, password recovery, magic link, two-factor, device authorization and the whole flow, in a card or split shell.

Source: https://www.youj.dev/docs/blocks/auth

## Blocks

### Login

Welcome returning users with a sign-in page offering social login or email and password.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-login
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { Login, type LoginProps } from '@/blocks/auth/login'

export function LoginView({ providers, brand }: Pick<LoginProps, 'providers' | 'brand'>) {
  return (
    <Login
      providers={providers}
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onSignIn={async (values) => {
        // await your API here; the block shows progress until it settles
      }}
      onProvider={(provider) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSignIn` | `(values: LoginValues) => Promise<unknown>` | `a short demo wait` | Resolve to sign in; reject with an Error whose message says why not. |
| `onProvider` | `(provider: string) => unknown` |  | Starts a provider's redirect with its `id`. Default: a short demo wait. |
| `providers` | `AuthProvider[]` |  | The "Continue with…" buttons, in order; `[]` for the email form alone. Default: Google and GitHub. |
| `defaultValues` | `Partial<LoginValues>` |  | The fields' starting values (`email`, `password`, `remember`). Default: empty, with "Keep me signed in" on. |
| `error` | `ReactNode` |  | A server error to show above the form (from a failed redirect, say) until the next attempt. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

**Strings:** `copy` takes `legalBefore`, `legalTerms`, `legalAnd`, `legalPrivacy`, `legalAfter`, `quote`, `quoteName`, `quoteRole`, `providerPending`, `providerSuccess`, `or`, `email`, `emailPlaceholder`, `emailRequired`, `emailInvalid`, `genericError`, `signInTitle`, `signInDescription`, `signInFormLabel`, `signInFailed`, `password`, `passwordRequired`, `forgotPassword`, `remember`, `signIn`, `signingIn`, `signedIn`, `signInError`, `newHere`, `createAccountLink`, `magicLink`, `magicLinkSending`, `magicLinkSent`, `magicLinkError`, `signUpTitle`, `signUpDescription`, `signUpFormLabel`, `signUpFailed`, `name`, `namePlaceholder`, `nameRequired`, `workEmail`, `passwordRules`, `terms`, `termsRequired`, `createAccount`, `creatingAccount`, `accountCreated`, `createError`, `haveAccount`, `forgotTitle`, `forgotDescription`, `forgotEmailHint`, `sendResetLink`, `sending`, `sent`, `sendError`, `remembered`, `backToSignIn`, `checkEmailTitle`, `checkEmailBefore`, `checkEmailAfter`, `resendLink`, `differentEmail`, `resetTitle`, `resetDescription`, `resetFailed`, `newPassword`, `confirmPassword`, `confirmRequired`, `mismatch`, `updatePassword`, `saving`, `saved`, `saveError`, `resetDoneTitle`, `resetDoneDescription`, `continueToSignIn`, `twoFactorTitle`, `twoFactorDescription`, `recoveryDescription`, `verificationCode`, `recoveryCode`, `codeChecking`, `codeVerified`, `codeFailed`, `codeFailedHint`, `codeVerifiedHint`, `useRecovery`, `useApp`, `someoneElse`, `noText`, `inboxTitle`, `inboxBefore`, `inboxAfter`, `openGmail`, `openOutlook`, `nothingYet`, `sendAnother`, `deviceTitle`, `deviceDescription`, `deviceApp`, `deviceAccess`, `deviceAccount`, `deviceNotYou`, `deviceCode`, `deviceCodeMatch`, `deviceSafety`, `deviceAuthorize`, `deviceAuthorizing`, `deviceAuthorized`, `deviceAuthorizeError`, `deviceDeny`, `deviceDenying`, `deviceDenied`, `deviceDenyError`, `deviceEnterInstead`, `deviceEnterTitle`, `deviceEnterDescription`, `deviceEnterLabel`, `deviceChecking`, `deviceCodeFound`, `deviceCodeUnknown`, `deviceCodeUnknownHint`, `deviceApprovedTitle`, `deviceApprovedDescription`, `deviceDeniedTitle`, `deviceDeniedDescription`, `deviceExpiredTitle`, `deviceExpiredDescription`, `deviceTryAnother`, `deviceStartOver`.

### Sign up

Give new users a sign-up page with social login or a name, email and password form.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-signup
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { Signup, type SignupProps } from '@/blocks/auth/signup'

export function SignupView({ providers, brand }: Pick<SignupProps, 'providers' | 'brand'>) {
  return (
    <Signup
      providers={providers}
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onSignUp={async (values) => {
        // await your API here; the block shows progress until it settles
      }}
      onProvider={(provider) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSignUp` | `(values: SignupValues) => Promise<unknown>` | `a short demo wait` | Resolve once the account exists; reject with an Error whose message says why not. |
| `onProvider` | `(provider: string) => unknown` |  | Starts a provider's redirect with its `id`. Default: a short demo wait. |
| `providers` | `AuthProvider[]` |  | The "Continue with…" buttons, in order; `[]` for the email form alone. Default: Google and GitHub. |
| `defaultValues` | `Partial<SignupValues>` |  | The fields' starting values (an invited `email`, say). Default: empty. |
| `error` | `ReactNode` |  | A server error to show above the form until the next attempt. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Forgot password

Help users get back into their account with a form for requesting a password reset link.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-forgot-password
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { ForgotPassword, type ForgotPasswordProps } from '@/blocks/auth/forgot-password'

export function ForgotPasswordView({ brand }: Pick<ForgotPasswordProps, 'brand'>) {
  return (
    <ForgotPassword
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onSend={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSend` | `(email: string) => Promise<unknown>` | `a short demo wait` | Sends the reset link (and each resend); reject with an Error whose message says why not. |
| `defaultValues` | `{ email?: string }` |  | The field's starting value. Default: empty. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Reset password

Help users choose a new password, with clear rules, a strength indicator and confirmation.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-reset-password
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { ResetPassword, type ResetPasswordProps } from '@/blocks/auth/reset-password'

export function ResetPasswordView({ brand }: Pick<ResetPasswordProps, 'brand'>) {
  return (
    <ResetPassword
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onReset={async (password) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onReset` | `(password: string) => Promise<unknown>` | `a short demo wait` | Resolve once saved; reject with an Error whose message says why not (an expired link, say). |
| `email` | `string` | `'ada@northwind.dev'` | The account the reset link is for, named under the heading; `undefined` leaves it out. |
| `error` | `ReactNode` |  | A server error to show above the form (a link you already know has expired, say) until the next attempt. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Magic link sent

Show users where to look next after they request a passwordless sign-in link.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-magic-link-sent
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { MagicLinkSent, type MagicLinkSentProps } from '@/blocks/auth/magic-link-sent'

export function MagicLinkSentView({ brand }: Pick<MagicLinkSentProps, 'brand'>) {
  return (
    <MagicLinkSent
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onResend={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `email` | `string` | `'ada@northwind.dev'` | The address the link went to. |
| `onResend` | `() => unknown` | `a short demo wait` | Sends another link. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Two-factor

Guide users through a verification code, with clear feedback when it succeeds or needs another try.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-two-factor
```

It brings `auth-shell` with it.

```tsx
'use client'

import Link from 'next/link'
import { TwoFactor, type TwoFactorProps } from '@/blocks/auth/two-factor'

export function TwoFactorView({ brand }: Pick<TwoFactorProps, 'brand'>) {
  return (
    <TwoFactor
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onVerify={(code, kind) => {
        // your code
      }}
      onResend={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onVerify` | `(code: string, kind: 'totp' \| 'recovery') => unknown` | `a demo check that refuses all zeros` | Resolve true (or nothing) for a good code, false or throw for a bad one. |
| `onResend` | `() => unknown` | `a short demo wait` | Texts a new code. |
| `destination` | `string` | `'•••• 4821'` | Where the code went, e.g. "•••• 4821". |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Device authorization

Let someone approve a command-line tool from the browser: who is asking, what it can do, the account it would use, the code as tiles to compare with the terminal and a plain safety note, then Authorize or Deny. Without a code it asks for the one the terminal shows.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-device-authorization
```

It brings `async-button`, `auth-shell`, `button`, `field`, `icon-check`, `icon-clock`, `icon-shield-check`, `icon-shield-x`, `icon-terminal`, `input-otp`, `property-list`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { DeviceAuthorization, type DeviceAuthorizationProps } from '@/blocks/auth/device-authorization'

export function DeviceAuthorizationView({ app, access, account, brand }: Pick<DeviceAuthorizationProps, 'app' | 'access' | 'account' | 'brand'>) {
  return (
    <DeviceAuthorization
      app={app}
      access={access}
      account={account}
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
      onCheckCode={(code) => {
        // your code
      }}
      onAuthorize={(code) => {
        // your code
      }}
      onDeny={(code) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `app` | `DeviceApp` | `the Fernbit command-line tool` | The tool asking. |
| `access` | `string[]` | `demo` | What approving lets it do, one line each. |
| `account` | `DeviceAccount` | `the demo's Ada Lovelace` | Who is signed in. |
| `code` | `string` |  | The code the terminal printed, "TFXS-STXG" (the dash is optional). Omit it to ask for the user's own. |
| `defaultStep` | `'enter' \| 'review' \| 'approved' \| 'denied' \| 'expired'` |  | Where it opens. Default: `review` with a `code`, else `enter`. `approved`, `denied` and `expired` draw those endings. |
| `onCheckCode` | `(code: string) => unknown` | `a demo wait that refuses ZZZZ-ZZZZ` | Checks a typed code; resolve true (or nothing) for a live one, false or throw for one that isn't. |
| `onAuthorize` | `(code: string) => unknown` | `a short demo wait` | Lets the tool in; resolve when it has. |
| `onDeny` | `(code: string) => unknown` | `a short demo wait` | Turns the request down; resolve when it has. |
| `layout` | `'card' \| 'split'` | `'card'` | `card`: one centered card. `split`: the form beside an art panel from `lg` up. |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` |  | The product above the form: `{ name, logo?, href? }`. Default: the Northwind demo. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | ``'a'`` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

### Full flow

The whole way in as one flow: sign in or create an account, reset a forgotten password, confirm a second step or send a sign-in link, with each step sliding in as the card resizes.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-auth-flow
```

It brings `auth-shell`, `button`, `empty`, `icon-arrow-right`, `icon-check-circle`, `illustrations`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { AuthFlow, type AuthFlowProps } from '@/blocks/app/auth-flow'

export function AuthFlowView({ view }: Pick<AuthFlowProps, 'view'>) {
  return (
    <AuthFlow
      view={view}
      copy={{ signedInTitle: 'You’re signed in' }}
      onViewChange={(view) => {
        // your code
      }}
      onSignIn={async (values) => {
        // await your API here; the block shows progress until it settles
      }}
      onSignUp={async (values) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'page' \| 'card'` | `'page'` | `page`: the full page, form beside the art panel. `card`: a card for a modal or dialog. |
| `view` | `'sign-in' \| 'sign-up' \| 'forgot' \| 'forgot-sent' \| 'reset' \| 'reset-done' \| 'two-factor' \| 'magic-link-sent' \| 'signed-in'` |  | The step shown, when your router owns it. |
| `defaultView` | `'sign-in' \| 'sign-up' \| 'forgot' \| 'forgot-sent' \| 'reset' \| 'reset-done' \| 'two-factor' \| 'magic-link-sent' \| 'signed-in'` | `'sign-in'` | The first step, when the flow owns it. |
| `onViewChange` | `(view: AuthView) => void` |  |  |
| `illustration` | `IllustrationSlot` | `'deploy'` | The page's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthFlowCopy>` |  |  |
| `onSignIn` | `(values: LoginValues) => Promise<unknown>` | `demo` | Resolve `'two-factor'` to ask for a code, anything else to sign in; reject to say why not. |
| `onSignUp` | `(values: SignupValues) => Promise<unknown>` | `demo` |  |
| `onRequestReset` | `(email: string) => Promise<unknown>` | `demo` | Send the reset link. Resolve the same whether or not the address has an account. |
| `onReset` | `(password: string) => Promise<unknown>` | `demo` | Save the new password from the reset link. |
| `onVerifyCode` | `(code: string, kind: CodeKind) => unknown` | `demo` | Resolve true (or nothing) for a good code, false or throw for a bad one. |
| `onMagicLink` | `(email: string) => Promise<unknown>` | `demo` | Email a one-time sign-in link. |
| `onResendCode` | `() => unknown` | `demo` |  |
| `onProvider` | `(provider: 'github' \| 'google') => unknown` |  |  |
| `destination` | `string` | `'•••• 4821'` | Where the second factor's text went, e.g. "•••• 4821". |
| `email` | `string` |  | The account's address, when it's known up front (the reset link's). |
| `continueHref` | `string` | `'#dashboard'` | Where "Open your workspace" goes once signed in. |

**Strings:** `copy` takes `signedInTitle`, `signedInDescription`, `openWorkspace`, `announce`, `legalBefore`, `legalTerms`, `legalAnd`, `legalPrivacy`, `legalAfter`, `quote`, `quoteName`, `quoteRole`, `providerPending`, `providerSuccess`, `or`, `email`, `emailPlaceholder`, `emailRequired`, `emailInvalid`, `genericError`, `signInTitle`, `signInDescription`, `signInFormLabel`, `signInFailed`, `password`, `passwordRequired`, `forgotPassword`, `remember`, `signIn`, `signingIn`, `signedIn`, `signInError`, `newHere`, `createAccountLink`, `magicLink`, `magicLinkSending`, `magicLinkSent`, `magicLinkError`, `signUpTitle`, `signUpDescription`, `signUpFormLabel`, `signUpFailed`, `name`, `namePlaceholder`, `nameRequired`, `workEmail`, `passwordRules`, `terms`, `termsRequired`, `createAccount`, `creatingAccount`, `accountCreated`, `createError`, `haveAccount`, `forgotTitle`, `forgotDescription`, `forgotEmailHint`, `sendResetLink`, `sending`, `sent`, `sendError`, `remembered`, `backToSignIn`, `checkEmailTitle`, `checkEmailBefore`, `checkEmailAfter`, `resendLink`, `differentEmail`, `resetTitle`, `resetDescription`, `resetFailed`, `newPassword`, `confirmPassword`, `confirmRequired`, `mismatch`, `updatePassword`, `saving`, `saved`, `saveError`, `resetDoneTitle`, `resetDoneDescription`, `continueToSignIn`, `twoFactorTitle`, `twoFactorDescription`, `recoveryDescription`, `verificationCode`, `recoveryCode`, `codeChecking`, `codeVerified`, `codeFailed`, `codeFailedHint`, `codeVerifiedHint`, `useRecovery`, `useApp`, `someoneElse`, `noText`, `inboxTitle`, `inboxBefore`, `inboxAfter`, `openGmail`, `openOutlook`, `nothingYet`, `sendAnother`, `deviceTitle`, `deviceDescription`, `deviceApp`, `deviceAccess`, `deviceAccount`, `deviceNotYou`, `deviceCode`, `deviceCodeMatch`, `deviceSafety`, `deviceAuthorize`, `deviceAuthorizing`, `deviceAuthorized`, `deviceAuthorizeError`, `deviceDeny`, `deviceDenying`, `deviceDenied`, `deviceDenyError`, `deviceEnterInstead`, `deviceEnterTitle`, `deviceEnterDescription`, `deviceEnterLabel`, `deviceChecking`, `deviceCodeFound`, `deviceCodeUnknown`, `deviceCodeUnknownHint`, `deviceApprovedTitle`, `deviceApprovedDescription`, `deviceDeniedTitle`, `deviceDeniedDescription`, `deviceExpiredTitle`, `deviceExpiredDescription`, `deviceTryAnother`, `deviceStartOver`.

### Shell

The frame for your own sign-in screens: a centered card, or a split page with room for artwork.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add auth-shell
```

It brings `alert`, `async-button`, `button`, `card`, `checkbox`, `empty`, `field`, `form`, `icon-brand-github`, `icon-check`, `icon-check-circle`, `icon-mail-open`, `illustrations`, `input`, `input-otp`, `password-input`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { AuthShell, type AuthShellProps } from '@/blocks/auth/shell'

export function AuthShellView({ brand }: Pick<AuthShellProps, 'brand'>) {
  return (
    <AuthShell
      brand={brand}
      copy={{ legalBefore: 'By continuing you agree to our' }}
      linkComponent={Link}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'card' \| 'split'` | `'card'` |  |
| `children` (required) | `ReactNode` |  |  |
| `illustration` | `IllustrationSlot` | `'deploy'` | The split layout's art: a scene from the illustrations by id, your own node, or `null` for the plain band alone. |
| `copy` | `Partial<AuthCopy>` |  | Any of the strings (headings, labels, errors, the quote, the legal line), to rewrite or translate. Default: the Northwind demo's. |
| `brand` | `AuthBrand` | `the Northwind demo` | The product above the form: `{ name, logo?, href? }`. |
| `links` | `Partial<AuthLinks>` |  | Where the links go: `signIn`, `signUp`, `forgot`, `terms`, `privacy`, and the mail apps (`gmail`, `outlook`). Default: the demo's `#` anchors. |
| `linkComponent` | `ElementType` | `'a'` | Renders every internal link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The step heading's level. |

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every screen sits in a `main`; in the split layout the artwork is a separate `aside`, hidden below the `lg` breakpoint. Two-factor uses the kit’s one-time-code input and offers a resend. Device authorization shows its code as one image named letter by letter, or takes it in the same one-time-code input; Authorize and Deny are real buttons that report their progress, and the step you arrive on is announced. In the full flow the leaving step is `inert` and a status region announces the step you arrive on. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

The Google logo is a trademark of Google, shown for illustration only.

---

# Billing and team

> Screens for the paying workspace: plan and invoices, usage and charges, and members with roles and seats.

Source: https://www.youj.dev/docs/blocks/billing-and-team

## Blocks

### Billing

Give customers a place to manage their plan, payment details and invoices, with a dialog for changing plan and another for the card.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-billing
```

It brings `alert`, `app-page`, `async-button`, `badge`, `button`, `card`, `counter`, `dialog`, `field`, `icon-credit-card`, `icon-download`, `icon-lock`, `icon-refresh`, `input`, `presence-list`, `radio-group`, `reveal`, `skeleton`, `table`, `textarea`, `toast`, `toggle-group`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { Billing, type BillingProps } from '@/blocks/app/billing'

export function BillingView({ plans, cycle, card, invoices }: Pick<BillingProps, 'plans' | 'cycle' | 'card' | 'invoices'>) {
  return (
    <Billing
      plans={plans}
      cycle={cycle}
      card={card}
      invoices={invoices}
      copy={{ title: 'Billing' }}
      onRetry={() => {
        // your code
      }}
      onChangePlan={async (change) => {
        // await your API here; the block shows progress until it settles
      }}
      onUpdatePayment={async (input) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `breadcrumb`, `planBadge`, `errorTitle`, `retry`, `failedTitle`, `failedDescription`, `retryPayment`, `charging`, `paid`, `declined`, `paidToast`, `chargedTo`, `currentPlan`, `monthly`, `annual`, `changePlan`, `perSeat`, `perMonth`, `seats`, `nextInvoice`, `nextInvoiceDate`, `renews`, `renewsDate`, `billedMonthly`, `billedYearly`, `changePlanTitle`, `changePlanDescription`, `billingCycle`, `annualSaving`, `planLabel`, `currentBadge`, `perSeatMonth`, `noChange`, `changeFrom`, `cancel`, `updating`, `planUpdated`, `confirmChange`, `planChanged`, `invoicesHeading`, `invoicesLabel`, `showInvoices`, `filterAll`, `filterPaid`, `filterOpen`, `nothingOpen`, `emptyInvoices`, `loading`, `invoiceColumn`, `dateColumn`, `periodColumn`, `statusColumn`, `amountColumn`, `actionsColumn`, `status`, `retryCharge`, `retryFor`, `downloadAs`, `preparing`, `downloaded`, `paymentTitle`, `paymentDescription`, `update`, `endingIn`, `cardSummary`, `expires`, `cardUpdated`, `updateCardTitle`, `updateCardDescription`, `nameOnCard`, `cardNumber`, `cardNumberPlaceholder`, `expiry`, `expiryPlaceholder`, `cvc`, `cvcPlaceholder`, `nameError`, `numberError`, `expiryError`, `cvcError`, `processorNote`, `saving`, `cardSaved`, `saveCard`, `detailsTitle`, `detailsDescription`, `company`, `invoiceEmail`, `address`, `taxId`, `emailError`, `reset`, `saved`, `saveDetails`, `detailsSaved`, `detailsSavedNote`.

### Usage and charges

Show what the workspace used and what it was charged: a date range, a project filter and Export CSV over the total, the days as stacked bars by SKU with a tooltip, and a table of SKUs with usage against the allowance as a ring, the part past it, the charge and a total row.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-usage-charges
```

It brings `app-page`, `async-button`, `button`, `card`, `chart`, `counter`, `date-range-picker`, `empty`, `icon-download`, `select`, `skeleton`, `table`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { UsageCharges, type UsageChargesProps } from '@/blocks/app/usage-charges'

export function UsageChargesView({ skus, records, projects }: Pick<UsageChargesProps, 'skus' | 'records' | 'projects'>) {
  return (
    <UsageCharges
      skus={skus}
      records={records}
      projects={projects}
      copy={{ title: 'Usage charges' }}
      onRangeChange={(range) => {
        // your code
      }}
      onProjectChange={(project) => {
        // your code
      }}
      onExport={async (query) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) with the range, project and export as its actions, across the whole width. |
| `copy` | `Partial<UsageChargesCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers, money and dates (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `currency` | `string` | `'USD'` | The currency charges are in. |
| `skus` | `UsageChargesSku[]` | `demo` | The metered products, in the table's order. |
| `records` | `UsageChargesRecord[]` | `demo` | The metering, one record per day, project and SKU. |
| `projects` | `UsageChargesProject[]` | `demo` | The projects the filter offers, after All projects. |
| `range` | `DateRange \| null` |  | The days shown (controlled). Default: uncontrolled, opening on every day in `records`. |
| `onRangeChange` | `(range: DateRange \| null) => void` |  | Called when the range changes. |
| `project` | `string` |  | The project shown (controlled), a project's id or 'all'. Default: uncontrolled, opening on 'all'. |
| `onProjectChange` | `(project: string) => void` |  | Called when the project changes. |
| `onExport` | `(query: UsageChargesQuery) => Promise<unknown> \| unknown` |  | Export CSV for what the filters show; the button shows pending, success and failure. Default: a short demo wait. |
| `loading` | `boolean` | `false` | Shows skeletons in the figures, chart and table. |
| `error` | `ReactNode` |  | A message in place of the page's content when loading failed. |
| `onRetry` | `() => void` |  | Called by the error's Try again. |
| `empty` | `ReactNode` |  | Replaces the chart's empty state when no usage falls inside the filters. |

**Strings:** `copy` takes `title`, `subtitle`, `startDate`, `endDate`, `projectFilter`, `allProjects`, `export`, `exporting`, `exported`, `totalCharges`, `period`, `chartTitle`, `chartSummary`, `chartCaption`, `day`, `tableTitle`, `sku`, `usage`, `overage`, `charge`, `total`, `none`, `usageOf`, `emptyTitle`, `emptyDescription`, `loading`, `error`, `retry`.

### Team members

Manage workspace members, roles and pending invitations with seat usage in view.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-team-members
```

It brings `alert`, `alert-dialog`, `app-page`, `async-button`, `avatar`, `badge`, `button`, `collapse`, `counter`, `dialog`, `dropdown-menu`, `empty`, `field`, `icon-copy`, `icon-lock`, `icon-mail`, `icon-more-horizontal`, `icon-search`, `icon-user-minus`, `icon-user-plus`, `icon-users`, `icon-x`, `input-group`, `presence-list`, `reveal`, `segmented-meter`, `select`, `skeleton`, `table`, `tag-input`, `toast`, `typography`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { TeamMembers, type TeamMembersProps } from '@/blocks/app/team-members'

export function TeamMembersView({ members, invites, roles }: Pick<TeamMembersProps, 'members' | 'invites' | 'roles'>) {
  return (
    <TeamMembers
      members={members}
      invites={invites}
      roles={roles}
      copy={{ title: 'Team members' }}
      onRetry={() => {
        // your code
      }}
      onInvite={async (invite) => {
        // await your API here; the block shows progress until it settles
      }}
      onRoleChange={async (member, role) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `breadcrumb`, `plan`, `invitePeople`, `teamHeading`, `searchLabel`, `searchPlaceholder`, `filterLabel`, `allRoles`, `noMatchTitle`, `noMatch`, `noRole`, `clearFilters`, `emptyTitle`, `emptyDescription`, `loading`, `errorTitle`, `retry`, `tableLabel`, `memberColumn`, `lastActiveColumn`, `roleColumn`, `actionsColumn`, `you`, `roleFor`, `actionsFor`, `copyEmail`, `removeMember`, `online`, `minutesAgo`, `hoursAgo`, `yesterday`, `daysAgo`, `roleChanged`, `removeTitle`, `removeDescription`, `removeConfirm`, `removing`, `removed`, `undo`, `invitesHeading`, `invitesLabel`, `invitedBy`, `expiresToday`, `expiresIn`, `resend`, `resendTo`, `sending`, `sent`, `revokeTo`, `revoked`, `resent`, `invitedToast`, `invitedAs`, `seatsLabel`, `ofSeats`, `allSeatsTaken`, `seatsMeter`, `seatsUsed`, `membersStat`, `invitedStat`, `freeStat`, `inviteTitle`, `inviteDescription`, `emailsLabel`, `emailsPlaceholder`, `addAnother`, `emailsHint`, `notEmail`, `alreadyIn`, `alreadyListed`, `seatsShort`, `addOne`, `roleLabel`, `cancel`, `invitesSent`, `sendInvites`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The screens are a `main` with a `header` and labelled sections. The dialogs (change plan, payment method, invite) trap focus and close with Escape; payment errors appear in an alert and a plan change is announced in a live region. The members table has a label, a member’s role is a select labelled with their name, and each member’s actions are a menu labelled the same way. Seat usage is a labelled meter. Usage and charges names its chart and gives the same days as a table for screen readers; focus the chart and the arrow keys walk the days, opening the tooltip, and each SKU row says its usage and whether it is over the allowance in words, with the ring only decorative. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Checkout

> Checkout screens for a one-off order or a subscription, with an order summary in view.

Source: https://www.youj.dev/docs/blocks/checkout

## Blocks

### Subscription checkout

Take customers from choosing a subscription plan to payment, with a running order summary that updates as they choose.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-subscription-checkout
```

It brings `alert`, `badge`, `button`, `card`, `collapse`, `counter`, `empty`, `field`, `icon-arrow-right`, `icon-check`, `icon-check-circle`, `icon-credit-card`, `icon-lock`, `icon-tag`, `icon-x`, `input`, `input-group`, `number-input`, `radio-group`, `reveal`, `segmented-control`, `select`, `separator`, `use-controllable-state`, `wizard`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SubscriptionCheckout, type SubscriptionCheckoutProps } from '@/blocks/commerce/subscription-checkout'

export function SubscriptionCheckoutView({ plans, period, countries, promoCodes }: Pick<SubscriptionCheckoutProps, 'plans' | 'period' | 'countries' | 'promoCodes'>) {
  return (
    <SubscriptionCheckout
      plans={plans}
      period={period}
      countries={countries}
      promoCodes={promoCodes}
      copy={{ brand: 'Northwind' }}
      onPlanChange={(plan) => {
        // your code
      }}
      onPeriodChange={(period) => {
        // your code
      }}
      onSeatsChange={(seats) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `copy` | `Partial<SubscriptionCheckoutCopy>` |  | Any of the checkout's strings, to rewrite or translate. |
| `plans` | `Plan[]` | `the demo's three` | The plans to choose from. |
| `plan` | `string` |  | The chosen plan's id, controlled: pair it with `onPlanChange`. |
| `defaultPlan` | `string` | `'pro'` | The plan chosen first, when the checkout owns it. |
| `onPlanChange` | `(plan: string) => void` |  |  |
| `period` | `'monthly' \| 'yearly'` |  | The billing period, controlled: pair it with `onPeriodChange`. |
| `defaultPeriod` | `'monthly' \| 'yearly'` | `'yearly'` | The period first shown, when the checkout owns it. |
| `onPeriodChange` | `(period: Period) => void` |  |  |
| `seats` | `number` |  | The seat count, controlled: pair it with `onSeatsChange`. |
| `defaultSeats` | `number` | `5` | The seats first set, when the checkout owns them. |
| `onSeatsChange` | `(seats: number) => void` |  |  |
| `countries` | `Country[]` | `the demo's eight` | The countries you sell to, with the tax each adds. |
| `defaultPayment` | `Partial<Payment>` |  | The payment form's starting values (a signed-in buyer's email and country, say). |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The product in the header: `{ name, logo? }`. Default: `copy.brand` with its initial. |
| `currency` | `string` |  | An ISO 4217 code. Default: `copy.currency` ('USD'). |
| `locale` | `string` |  | A BCP 47 locale for prices. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `promoCodes` | `Record<string, number>` | `demo` | Codes and the share each takes off, like `{ LAUNCH20: 0.2 }`. |
| `onSubscribe` | `(order: SubscriptionOrder) => unknown` | `demo` | Takes the order to your payment provider. Reject to stay on the step. |
| `onDone` | `() => void` |  | The confirmation's "Go to your workspace". |

**Strings:** `copy` takes `currency`, `brand`, `secure`, `demo`, `title`, `subtitle`, `stepPlan`, `stepPlanDescription`, `stepPayment`, `stepPaymentDescription`, `billing`, `monthly`, `yearly`, `save`, `plan`, `popular`, `perSeat`, `seats`, `seatsHint`, `placeholderTitle`, `placeholderDescription`, `email`, `holder`, `card`, `cardPlaceholder`, `expiry`, `expiryPlaceholder`, `cvc`, `cvcPlaceholder`, `country`, `postal`, `emailInvalid`, `holderRequired`, `cardInvalid`, `expiryInvalid`, `cvcInvalid`, `postalRequired`, `back`, `next`, `subscribe`, `subscribed`, `summary`, `seatLine`, `yearlyDiscount`, `promo`, `promoPlaceholder`, `apply`, `removePromo`, `promoInvalid`, `promoApplied`, `subtotal`, `tax`, `total`, `renews`, `doneTitle`, `doneDescription`, `receipt`, `paidWith`, `open`, `locale`.

### Checkout

Guide shoppers through contact details, shipping and payment with the order summary beside the form. Pick it for a one-off order.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-checkout
```

It brings `button`, `card`, `checkbox`, `commerce-product-card`, `field`, `form`, `icon-check-circle`, `icon-lock`, `icon-package`, `input`, `phone-input`, `radio-group`, `select`, `separator`, `stagger`, `typography`, `wizard`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Checkout, type CheckoutProps } from '@/blocks/commerce/checkout'

export function CheckoutView({ lines, shippingOptions, countries }: Pick<CheckoutProps, 'lines' | 'shippingOptions' | 'countries'>) {
  return (
    <Checkout
      lines={lines}
      shippingOptions={shippingOptions}
      countries={countries}
      copy={{ title: 'Checkout' }}
      linkComponent={Link}
      onShippingOptionChange={(id) => {
        // your code
      }}
      onPlaceOrder={async (order) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `CheckoutLine[]` | `the demo's two lines` | What's being bought, in the order summary. |
| `shippingOptions` | `CheckoutShippingOption[]` | `free standard delivery` | The ways to ship; more than one shows a picker in the shipping step. |
| `shippingOption` | `string` |  | The chosen shipping option's id, controlled: pair it with `onShippingOptionChange`. |
| `defaultShippingOption` | `string` |  | The shipping option chosen first, when the checkout owns it. Default: the first. |
| `onShippingOptionChange` | `(id: string) => void` |  |  |
| `countries` | `Record<string, string>` | `six demo countries` | The countries you ship to, code to name. |
| `taxRate` | `number` | `0.08` | The share of the subtotal added as tax. |
| `currency` | `string` | `'USD'` | An ISO 4217 code. |
| `locale` | `string` | `'en-US'` | A BCP 47 locale for every amount. |
| `defaultValues` | `{ contact?: Partial<CheckoutContact>; shipping?: Partial<CheckoutShipping> }` |  | The forms' starting values (a signed-in shopper's email and address, say). Default: empty, shipping to the US. |
| `onPlaceOrder` | `(order: CheckoutOrder) => Promise<string> \| string` | `a short demo wait and 'NW-48213'` | Places the order and resolves with its number; reject with an Error to shake Pay. |
| `shopHref` | `string` | `'#shop'` | Where "Continue shopping" goes once confirmed. |
| `linkComponent` | `ElementType` | `'a'` | Renders the "Continue shopping" link, e.g. Next.js `Link`. |
| `copy` | `Partial<CheckoutCopy>` |  | Any of the checkout's strings, to rewrite or translate. |

**Strings:** `copy` takes `title`, `secure`, `summary`, `quantity`, `subtotal`, `shipping`, `free`, `tax`, `total`, `contactTitle`, `contactDescription`, `email`, `emailPlaceholder`, `emailRequired`, `emailInvalid`, `news`, `shippingTitle`, `shippingDescription`, `shippingMethod`, `name`, `namePlaceholder`, `nameRequired`, `address`, `addressPlaceholder`, `addressRequired`, `city`, `cityRequired`, `postal`, `postalRequired`, `country`, `countryRequired`, `phone`, `phoneDescription`, `phoneRequired`, `paymentTitle`, `paymentDescription`, `card`, `cardPlaceholder`, `cardInvalid`, `expiry`, `expiryPlaceholder`, `expiryInvalid`, `cvc`, `cvcPlaceholder`, `cvcInvalid`, `holder`, `holderRequired`, `reviewTitle`, `reviewDescription`, `shipTo`, `cardEnding`, `edit`, `editLabel`, `pay`, `placed`, `confirmedTitle`, `receiptBefore`, `receiptAfter`, `order`, `totalPaid`, `arrives`, `continueShopping`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Checkout has one `h1` and puts the order summary under its own `h2`, with the order as a real list; fields are labelled. Subscription checkout wraps the page in `main` under a `header`, labels its plan choices, and announces the changing total in a live region (`aria-live`). Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Dashboards

> Overview screens: analytics, a conversion funnel, a usage report, a spend overview and a personal bank’s home.

Source: https://www.youj.dev/docs/blocks/dashboards

## Blocks

### Analytics

See how a store did over any date range: headline numbers, a trend against the previous period, channels, categories and top products.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-analytics-overview
```

It brings `alert`, `app-page`, `badge`, `button`, `card`, `chart`, `counter`, `date-range-picker`, `empty`, `field`, `icon-pencil`, `reveal`, `skeleton`, `sparkline`, `stat-card`, `table`, `toggle-group`, `treemap`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { AnalyticsOverview, type AnalyticsOverviewProps } from '@/blocks/app/analytics-overview'

export function AnalyticsOverviewView({ range, summary, kpis, metric }: Pick<AnalyticsOverviewProps, 'range' | 'summary' | 'kpis' | 'metric'>) {
  return (
    <AnalyticsOverview
      range={range}
      summary={summary}
      kpis={kpis}
      metric={metric}
      copy={{ title: 'Analytics overview' }}
      onRangeChange={(range) => {
        // your code
      }}
      onMetricChange={(metric) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no store header of its own. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's level. |
| `range` | `DateSpan` |  | The span shown (controlled); pair it with `onRangeChange`. |
| `defaultRange` | `DateSpan` |  | The span shown first. Default: the last 30 days. |
| `onRangeChange` | `(range: DateSpan) => void` |  | Called with each complete span the picker settles on. |
| `summary` | `Summary` |  | The page's figures for the span shown, from your analytics API. Default: the demo store's, computed for the span. |
| `kpis` | `AnalyticsKpi[]` | `revenue, orders, conversion rate and average order` | The headline numbers, in order. |
| `metric` | `'revenue' \| 'orders' \| 'visitors'` |  | The trend chart's metric (controlled); pair it with `onMetricChange`. |
| `defaultMetric` | `'revenue' \| 'orders' \| 'visitors'` | `'revenue'` | The trend chart's first metric. |
| `onMetricChange` | `(metric: Metric) => void` |  | Called with the metric the trend switch lands on. |
| `today` | `Date \| number` |  | Today, the last day the picker offers. Default: the browser's today once mounted (a fixed demo day before, so hydration matches). |
| `minDate` | `Date` | `the demo store's launch, Jan 6, 2025` | The first day the picker offers. |
| `currency` | `string` | `'USD'` | The currency of every amount. |
| `locale` | `string` |  | Formats dates and numbers. Default: the YoujProvider locale. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The store in the standalone header: its name and mark. Default: Fieldnote Supply and a pencil. |
| `actions` | `ReactNode` |  | Beside the date picker: an export button, a filter. Default: none. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures while your data loads; the layout holds. |
| `error` | `ReactNode` |  | Shown in place of the figures when they fail to load, with a retry button when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries loading after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message for a span without visitors or orders. Default: `copy.empty` and `copy.emptyDetail`. |
| `copy` | `Partial<AnalyticsOverviewCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the demo's English strings. |

**Strings:** `copy` takes `title`, `section`, `badge`, `comparedWith`, `dateRange`, `announce`, `loading`, `empty`, `emptyDetail`, `retry`, `kpis`, `vsPrevious`, `byUnit`, `metric`, `metrics`, `overTime`, `per`, `against`, `thisPeriod`, `previousPeriod`, `trendSummary`, `period`, `trendCaption`, `channelsTitle`, `channelsDescription`, `channelsSummary`, `channels`, `revenue`, `productsTitle`, `productsDescription`, `productsTable`, `rank`, `product`, `units`, `change`, `trend`, `categoriesTitle`, `categoriesLead`, `noSales`, `categoriesLabel`.

### Funnel report

Follow trial teams to paid: a conversion funnel, step changes against the previous period, cohort retention, time to paid and daily upgrades.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-funnel-report
```

It brings `alert`, `app-page`, `badge`, `button`, `calendar-heatmap`, `card`, `chart`, `counter`, `diff-bar`, `empty`, `histogram-range`, `icon-funnel`, `reveal`, `segmented-control`, `skeleton`, `stat-card`, `table`, `typography`, `use-announcer`, `use-controllable-state`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { FunnelReport, type FunnelReportProps } from '@/blocks/app/funnel-report'

export function FunnelReportView({ report, segments }: Pick<FunnelReportProps, 'report' | 'segments'>) {
  return (
    <FunnelReport
      report={report}
      segments={segments}
      copy={{ title: 'Activation funnel' }}
      onSegmentChange={(segment) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no product header of its own. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's level. |
| `report` | `Report` |  | The figures for the segment shown: steps (the first is the funnel's entry, the second trials, the last paid), cohorts, days to paid and daily upgrades. Default: the demo's, computed for the segment. |
| `segments` | `FunnelSegment[]` | `All, Web, iOS and Android` | The cuts in the switch. |
| `segment` | `string` |  | The segment shown (controlled); pair it with `onSegmentChange`. |
| `defaultSegment` | `Segment \| (string & {})` | `'all'` | The segment shown first. |
| `onSegmentChange` | `(segment: string) => void` |  | Called with the segment the switch lands on. |
| `today` | `Date \| number` |  | The last day of the period. Default: the browser's today once mounted (a fixed demo day before, so hydration matches). |
| `locale` | `string` |  | Formats dates and numbers. Default: the YoujProvider locale. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The product in the standalone header: its name and mark. Default: Loopwork and a funnel. |
| `actions` | `ReactNode` |  | Beside the segment switch: an export button, a date filter. Default: none. |
| `loading` | `boolean` | `false` | Skeletons in place of the figures while your data loads; the layout holds. |
| `error` | `ReactNode` |  | Shown in place of the figures when they fail to load, with a retry button when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries loading after an `error`. Default: none. |
| `empty` | `ReactNode` |  | Replaces the message for a period nobody entered. Default: `copy.empty` and `copy.emptyDetail`. |
| `copy` | `Partial<FunnelReportCopy>` |  | Any of the report's strings, to rewrite or translate. Default: the demo's English strings. |

**Strings:** `copy` takes `title`, `description`, `section`, `badge`, `platform`, `headline`, `visitorToPaid`, `trialsStarted`, `newPaying`, `trialToPaid`, `announce`, `loading`, `empty`, `emptyDetail`, `retry`, `funnelTitle`, `funnelDescription`, `funnelChart`, `funnelSummary`, `reached`, `dropped`, `step`, `funnelCaption`, `stepsTitle`, `stepsDescription`, `stepsList`, `previousPeriod`, `thisPeriod`, `cohortsTitle`, `cohortsDescription`, `cohortsTable`, `cohort`, `teams`, `weekShort`, `week`, `notYet`, `average`, `fewer`, `more`, `timeTitle`, `timeDescription`, `days`, `daysTick`, `timeLabel`, `inside`, `upgradesTitle`, `streak`, `upgradesDescription`, `upgradesLabel`.

### Usage overview

Track cloud spending against a budget with a projected bill, usage breakdown, a spend cap and invoices.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-usage-overview
```

It brings `app-page`, `async-button`, `badge`, `button`, `card`, `chart`, `collapse`, `counter`, `icon-alert-triangle`, `icon-cloud`, `icon-cpu`, `icon-database`, `icon-download`, `icon-gauge`, `icon-globe`, `icon-zap`, `progress`, `reveal`, `skeleton`, `slider`, `stagger`, `toggle-group`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { UsageOverview, type UsageOverviewProps } from '@/blocks/app/usage-overview'

export function UsageOverviewView({ resources, daily, meters, invoices }: Pick<UsageOverviewProps, 'resources' | 'daily' | 'meters' | 'invoices'>) {
  return (
    <UsageOverview
      resources={resources}
      daily={daily}
      meters={meters}
      invoices={invoices}
      copy={{ title: 'Usage & billing' }}
      onRangeChange={(range) => {
        // your code
      }}
      onCapChange={(cap) => {
        // your code
      }}
      onSaveCap={async (cap) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `workspace`, `plan`, `cycle`, `monthToDate`, `ofBudget`, `budget`, `budgetUsed`, `projected`, `overBudget`, `withinBudget`, `billingCycle`, `resets`, `daysLeft`, `dailyCost`, `over`, `range`, `ranges`, `chartTitle`, `chartSummary`, `day`, `chartCaption`, `included`, `overage`, `meterLabel`, `alertAt`, `meterDetail`, `spendCap`, `capDescription`, `perCycle`, `headroom`, `headroomAtPace`, `projectedOverage`, `capWarning`, `saveCap`, `savingCap`, `capSaved`, `invoices`, `invoicesDescription`, `invoiceStatus`, `download`, `downloaded`, `emptyInvoices`, `loadFailed`, `retry`.

### Spend overview

See where a workspace’s money is going and whether it lasts the month: the spend so far with its change and one plain status, the running total carried to the period’s end against the limit, the latest requests with their failures, the audit trail, and cards for your usage, the top spenders and billing.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-spend-overview
```

It brings `app-page`, `avatar`, `badge`, `button`, `card`, `empty`, `forecast-band`, `icon-chevron-right`, `skeleton`, `stat-card`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SpendOverview, type SpendOverviewProps } from '@/blocks/app/spend-overview'

export function SpendOverviewView({ daily, requests, audit, personal }: Pick<SpendOverviewProps, 'daily' | 'requests' | 'audit' | 'personal'>) {
  return (
    <SpendOverview
      daily={daily}
      requests={requests}
      audit={audit}
      personal={personal}
      copy={{ title: 'Spend overview' }}
      onOpen={(section) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no canvas or `main` of its own. |
| `copy` | `Partial<SpendOverviewCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers, money and dates (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `currency` | `string` | `'USD'` | The currency amounts are in. |
| `daily` | `number[]` | `demo` | What was spent on each elapsed day of the period, oldest first. |
| `start` | `string` | `demo` | The period's first day, `YYYY-MM-DD`. |
| `periodDays` | `number` | `31` | The days in the period. |
| `limit` | `number` | `demo` | The workspace's spend limit for the period. |
| `previous` | `number` | `demo` | What the same stretch of the last period cost, for the change. |
| `paceDays` | `number` | `7` | How many of the latest days set the forecast's pace. |
| `requests` | `SpendRequest[]` | `demo` | The latest requests, newest first: the strip draws the first 40 and the list shows the first 4. |
| `audit` | `SpendAuditEvent[]` | `demo` | The latest changes to the workspace, newest first. |
| `personal` | `SpendPersonal` | `demo` | The signed-in member's own spend. |
| `members` | `SpendMember[]` | `demo` | The members spending the most, biggest first. |
| `averageSpend` | `number` | `demo` | What the average member spends. |
| `billing` | `SpendBilling` | `demo` | The credit left and when the period turns over. |
| `now` | `Date \| string \| number` | `a fixed demo moment` | The moment relative times count to (a date, a date-time string or a timestamp). |
| `onOpen` | `(section: SpendSection) => void` |  | Adds a button to each card that opens its section; called with which one. |
| `loading` | `boolean` | `false` | Shows skeletons in place of the figures, chart and lists. |
| `error` | `ReactNode` |  | A message in place of the page's content when loading failed. |
| `onRetry` | `() => void` |  | Called by the error's Try again. |

**Strings:** `copy` takes `title`, `subtitle`, `workspaceSpend`, `change`, `lastPeriod`, `onTrack`, `willExceed`, `overLimit`, `projected`, `legendSpent`, `legendForecast`, `legendLimit`, `chart`, `open`, `requests`, `requestsLatest`, `failed`, `requestStrip`, `failedRequest`, `audit`, `auditCount`, `by`, `personal`, `personalSub`, `requestsLabel`, `tokensLabel`, `personalLimit`, `personalBars`, `leaderboard`, `leaderboardSub`, `average`, `billing`, `billingSub`, `credit`, `resets`, `workspaceLimit`, `limitOf`, `limitLeft`, `loading`, `error`, `retry`, `emptyRequests`, `emptyAudit`, `emptyMembers`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each screen sits in a `main` or a labelled region with one page heading (`headingLevel` changes it), and its panels are labelled regions or sections (`aria-labelledby`) that set `aria-busy` while they load. Analytics and Funnel report add visually hidden text for loading, ranks, trends and empty cohort cells. Spend overview states its status in words (on track, or the day it will exceed the limit), names the forecast chart with a text summary, draws the request strip as one image that says how many requests failed, and lists the audit trail and the top spenders as ordered lists. Usage shows budget warnings as alerts and labels its spend-cap slider. Money overview names its balance and cards as regions, hides every amount behind a labeled toggle that reports its state, and reviews a payment in a drawer before it sends. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Freight

> One screen for running freight: the fleet on a map, the dispatch board and one shipment in full, as views in tabs.

Source: https://www.youj.dev/docs/blocks/freight

## Blocks

### Logistics

Run freight from one screen: the ocean fleet on a map beside its ships, the dispatch board with its queue, route and the agent’s proposals, and one shipment in full, each a tab of the same size. Opening the at-risk load from Dispatch shows its shipment, and its reroute is one decision in both views.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-logistics
```

It brings `app-dispatch-board`, `app-fleet-overview`, `app-page`, `app-shipment-detail`, `badge`, `button`, `card`, `icon-arrow-right`, `segmented-control`, `tabs`, `toast`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { Logistics, type LogisticsProps } from '@/blocks/app/logistics'

export function LogisticsView({ view }: Pick<LogisticsProps, 'view'>) {
  return (
    <Logistics
      view={view}
      onViewChange={(view) => {
        // your code
      }}
      onReroute={async (ships) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage, with New load) and the frame's gutter, filling the frame's height. |
| `view` | `'fleet' \| 'dispatch' \| 'shipment'` |  | The view shown (controlled). |
| `defaultView` | `'fleet' \| 'dispatch' \| 'shipment'` | `'fleet'` | The view shown at first. |
| `onViewChange` | `(view: View) => void` |  | Called with the view chosen. |
| `onReroute` | `(ships: Tracked[]) => Promise<unknown> \| unknown` |  | Reroutes the ships held by the storm; resolve when the request is done. Default: a short demo wait. |

### Fleet overview

Track an ocean-freight fleet on a map: ships steaming along their lanes, a list of what is sailing, holding or in port, a voyage panel with route, ETA, log and manifest, and a storm to reroute around.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-fleet-overview
```

It brings `alert`, `app-page`, `async-button`, `avatar`, `badge`, `button`, `card`, `counter`, `drawer`, `empty`, `icon-arrow-right`, `icon-check-circle`, `icon-cloud-lightning`, `icon-crosshair`, `icon-flag`, `icon-map`, `icon-map-pin`, `icon-minus`, `icon-navigation`, `icon-package`, `icon-plus`, `icon-route`, `icon-search`, `icon-share`, `icon-shield-check`, `icon-waves`, `icon-x`, `input-group`, `kbd`, `pagination`, `presence-list`, `progress`, `reveal`, `spotlight`, `stat-card`, `tabs`, `timeline`, `toast`, `tooltip`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { FleetOverview } from '@/blocks/app/fleet-overview'

export function FleetOverviewView() {
  return (
    <FleetOverview
      onReroute={async (ships) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, with the map filling the page under it. |
| `defaultSelectedId` | `string \| null` | `'nordic-tern'` | The voyage open on the map at first (on wide screens), by ship id. `null` opens on the whole fleet. |
| `onReroute` | `(ships: Tracked[]) => Promise<unknown> \| unknown` |  | Reroutes the held ships; resolve when the request is done. Default: a short demo wait. |

### Dispatch board

Run a freight dispatch board: a queue of loads, the selected one on a route map with a reroute to approve or compare, every driver’s day as lanes with proposed runs dashed, and the dispatch agent’s proposals.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-dispatch-board
```

It brings `app-page`, `avatar`, `badge`, `button`, `card`, `icon-alert-triangle`, `icon-calendar`, `icon-check`, `icon-check-circle`, `icon-clock`, `icon-engine`, `icon-hammer`, `icon-leaf`, `icon-lock`, `icon-plus`, `icon-shopping-cart`, `icon-sparkles`, `icon-store`, `icon-truck`, `icon-waves`, `popover`, `proposal-card`, `route-map`, `stat-card`, `time-lanes`, `toast`, `toggle-group`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage, with New load) and the frame's gutter, across the whole width. |
| `defaultLoad` | `string` |  | The load drawn on the map at first. Default 'LD-4821', the one at risk. |

### Shipment detail

Follow one shipment: the route as a stage rail with a detour, the vehicle with its readings called out, the route agent’s reroute to approve, the timeline, the record and the documents.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-shipment-detail
```

It brings `annotated-image`, `app-page`, `badge`, `button`, `card`, `icon-alert-triangle`, `icon-building`, `icon-calendar-clock`, `icon-check`, `icon-check-circle`, `icon-clock`, `icon-download`, `icon-eye`, `icon-file-text`, `icon-hash`, `icon-lock`, `icon-map-pin`, `icon-package`, `icon-phone`, `icon-share`, `icon-sparkles`, `icon-thermometer`, `icon-truck`, `icon-user`, `property-list`, `proposal-card`, `stepper`, `timeline`, `toast`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ShipmentDetail, type ShipmentDetailProps } from '@/blocks/app/shipment-detail'

export function ShipmentDetailView({ shipment, route, readings, events }: Pick<ShipmentDetailProps, 'shipment' | 'route' | 'readings' | 'events'>) {
  return (
    <ShipmentDetail
      shipment={shipment}
      route={route}
      readings={readings}
      events={events}
      onDecisionChange={(decision) => {
        // your code
      }}
      onShareTracking={() => {
        // your code
      }}
      onCallDriver={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage, with the shipment's actions) and the frame's gutter, across the whole width. |
| `shipment` | `ShipmentDetailShipment` | `demo` | The shipment: lane, window and ETAs, driver, equipment and its record. |
| `route` | `ShipmentDetailRoute` | `demo` | The stops, where the vehicle is, and the detour on offer. |
| `readings` | `ImageAnnotation[]` | `demo` | The vehicle's readings, called out on its picture. |
| `events` | `ShipmentDetailEvent[]` | `demo` | What happened, newest first. |
| `documents` | `ShipmentDetailDocument[]` | `demo` | The shipment's paperwork. |
| `proposal` | `ShipmentDetailProposal` | `demo` | The agent's case for the detour. |
| `now` | `number` | `the demo's clock` | The moment the timeline reads from. |
| `decision` | `'pending' \| 'approved' \| 'dismissed'` |  | The reroute's state (controlled). |
| `defaultDecision` | `'pending' \| 'approved' \| 'dismissed'` | `'pending'` | The reroute's state at first. |
| `onDecisionChange` | `(decision: Decision) => void` |  | Approve, dismiss or undo (back to 'pending'). |
| `onShareTracking` | `() => void` |  |  |
| `onCallDriver` | `() => void` |  |  |
| `onViewRoute` | `() => void` |  |  |
| `onEdit` | `(field: 'driver' \| 'window') => void` |  |  |
| `onDownloadDocument` | `(document: ShipmentDetailDocument) => void` |  |  |

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Logistics is one page heading over a tablist of three views (Fleet, Dispatch and Shipment); each view is a tab panel, and the fleet's keys answer only while Fleet is shown. Each of the other screens is a `main` with one page heading. Fleet overview names the map as an image that says how many ships are at sea and how many are holding, keeps its panels as labeled complementary regions, announces the voyage that opens in a polite live region, and answers the keyboard: `/` searches, `J` and `K` step through the list, `+` and `−` zoom, `0` frames the fleet and `Esc` closes the voyage. Dispatch board groups its figures, names the queue and the map’s route, draws proposed runs dashed as well as in a different color, and decides every proposal with buttons that can be undone. Shipment detail lists the vehicle’s readings and the route as named lists, marks the agent’s case as an article whose state is in its `data-status`, and reads its timeline as of the demo’s clock. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Help and search

> Screens for finding answers: a help center and a search results page.

Source: https://www.youj.dev/docs/blocks/help-and-search

## Blocks

### Help center

Help customers find answers with live search, topic cards and a contact form.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add content-help-center
```

It brings `accordion`, `alert`, `app-page`, `badge`, `button`, `card`, `content-swap`, `counter`, `field`, `file-upload`, `icon-arrow-right`, `icon-banknote`, `icon-check-circle`, `icon-code-xml`, `icon-credit-card`, `icon-file-text`, `icon-mail`, `icon-messages`, `icon-phone-call`, `icon-search`, `icon-shield-alert`, `icon-shield-check`, `icon-x`, `input`, `input-group`, `morph-label`, `presence-list`, `radio-group`, `reveal`, `select`, `skeleton`, `spotlight`, `textarea`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { HelpCenter, type HelpCenterProps } from '@/blocks/content/help-center'

export function HelpCenterView({ categories, articles, popular, questions }: Pick<HelpCenterProps, 'categories' | 'articles' | 'popular' | 'questions'>) {
  return (
    <HelpCenter
      categories={categories}
      articles={articles}
      popular={popular}
      questions={questions}
      copy={{ brandSuffix: 'Help' }}
      linkComponent={Link}
      onSearch={async (query) => {
        // await your API here; the block shows progress until it settles
      }}
      onSubmit={async (request) => {
        // await your API here; the block shows progress until it settles
      }}
      onUpload={async (file) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `brandSuffix`, `status`, `statusLink`, `title`, `description`, `search`, `searchPlaceholder`, `clearSearch`, `popular`, `results`, `resultCount`, `minutes`, `noResultsBefore`, `noResultsLink`, `noResultsAfter`, `topics`, `articles`, `faqTitle`, `faqDescription`, `contactTitle`, `contactDescription`, `channel`, `typicalReply`, `sending`, `doneTitle`, `ticket`, `doneBody`, `another`, `form`, `topic`, `topicPlaceholder`, `topicRequired`, `reference`, `referencePlaceholder`, `referenceHint`, `message`, `messagePlaceholder`, `messageTooShort`, `attachments`, `attachmentsTitle`, `attachmentsHint`, `replyBy`, `replyChannel`, `send`, `sendFailed`.

### Search results

A results screen for an app or knowledge base, with a query field and suggestions, filters in a side column or a sheet, result cards and empty and error states.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-search-results
```

It brings `app-page`, `async-button`, `avatar`, `badge`, `button`, `checkbox`, `collapse`, `command`, `content-swap`, `counter`, `empty`, `field`, `icon-arrow-up-right`, `icon-corner-down-left`, `icon-file-text`, `icon-history`, `icon-kanban`, `icon-link`, `icon-search`, `icon-sliders`, `icon-trending-up`, `icon-user`, `icon-x`, `input-group`, `kbd`, `popover`, `presence-list`, `progress`, `radio-group`, `reveal`, `select`, `sheet`, `skeleton`, `toast`, `toggle`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { SearchResults, type SearchResultsProps } from '@/blocks/app/search-results'

export function SearchResultsView({ items, people, popular, brand }: Pick<SearchResultsProps, 'items' | 'people' | 'popular' | 'brand'>) {
  return (
    <SearchResults
      items={items}
      people={people}
      popular={popular}
      brand={brand}
      copy={{ title: 'Search' }}
      linkComponent={Link}
      onSearchChange={(search) => {
        // your code
      }}
      onOpen={(item) => {
        // your code
      }}
      onRecentChange={(recent) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own and no / shortcut, so the app owns its keys. Default true; `false` draws its own page (the top bar, a centered canvas and the / shortcut). |
| `initialSearch` | `string` | `'?q=onboarding'` | The search to start from, as a query string. Same as `defaultSearch`, its earlier name. |
| `defaultSearch` | `string` | `"?q=onboarding"` | The search to start from, uncontrolled, as a query string ("?q=sso&type=document"). |
| `search` | `string` |  | The search, controlled, as a query string: pair it with `onSearchChange` (your router's query). Default: uncontrolled. |
| `onSearchChange` | `(search: string) => void` |  | Called with the query string each time the search changes: hand it to your router. |
| `loading` | `boolean` | `false` | Hold the loading state (skeleton rows), e.g. while your API answers. |
| `onOpen` | `(item: SearchItem) => void` |  | Called when a result is opened. Default: a toast. |
| `items` | `SearchItem[]` | `Kestrel's sample workspace` | The index to search. |
| `people` | `Record<string, SearchPerson>` | `Kestrel's people` | Who owns the items, by id: names, faces and facets read from here. |
| `popular` | `string[]` | `six demo searches` | Searches offered before typing and when nothing matches. |
| `defaultRecent` | `string[]` | `three demo searches` | The recent searches at first. |
| `onRecentChange` | `(recent: string[]) => void` |  | Called with the recent searches whenever one is added or they're cleared. Default: none. |
| `onLoadMore` | `(page: number) => Promise<unknown> \| unknown` |  | Loads the next page of results; resolve when it's in `items`. Called with the page number about to show. Default: a short demo wait. |
| `today` | `Date \| number` | `the demo's fixed day` | The day items' `updated` (days before) counts from, so server and browser agree. |
| `error` | `ReactNode` |  | Replaces the results with an error panel; a string is its message. Default: none. |
| `onRetry` | `() => void` |  | Adds a retry button to the error panel. Default: none. |
| `empty` | `ReactNode` |  | Replaces the no-results state. Default: `copy.noResults` with a spelling fix and popular searches. |
| `copy` | `Partial<SearchCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the English demo copy. |
| `brand` | `SearchBrand` | `Kestrel` | The product in the top bar and in the strings that name it. |
| `locale` | `string` |  | Formats dates and local times. Default: the app's locale (YoujProvider), else en-US. |
| `origin` | `string` | `'kestrel.so/search'` | The search page's address, shown and copied with the query string. |
| `linkComponent` | `ElementType` | `'a'` | Renders every result link (e.g. Next.js `Link`); it gets `href`, `onClick` and `className`. |
| `getHref` | `(item: SearchItem) => string` | `its `href`` | A result's link. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page heading's level; the results' headings follow it. |
| `className` | `string` |  | Classes for the page's root element, merged with its own. Default: none. |

**Strings:** `copy` takes `title`, `section`, `fieldLabel`, `placeholder`, `clear`, `suggestions`, `groupSearch`, `searchFor`, `jumpTo`, `recentSearches`, `clearRecent`, `popularIn`, `popular`, `filters`, `filtersApplied`, `filtersHint`, `results`, `searching`, `resultsWord`, `resultsFor`, `typeToSearch`, `sortResults`, `sorts`, `sheetDescription`, `sheetEmpty`, `clearAll`, `showResults`, `opening`, `linkToSearch`, `copyLink`, `copied`, `copyFailed`, `activeFilters`, `facetType`, `facetOwner`, `facetUpdated`, `facetTag`, `facetTags`, `removeFilter`, `types`, `updatedOptions`, `noOwners`, `noTags`, `startTitle`, `startDescription`, `noResults`, `filtersHide`, `checkSpelling`, `tryBroader`, `didYouMean`, `clearFilters`, `errorTitle`, `retry`, `showing`, `showingLabel`, `loadingMore`, `loaded`, `showMore`, `everything`, `keyMove`, `keyOpen`, `keySearch`, `updated`, `today`, `yesterday`, `daysAgo`, `minRead`, `person`, `localTime`, `ledBy`, `projectStatus`, `progress`, `members`, `shipped`, `due`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Help center has a `main` with one `h1`, a labelled search field and a status region that announces the result count as you type; the contact form announces its outcome in a live region. Search results has a `main`, a labelled `aside` of filters (a sheet on phones), labelled active-filter chips and a status region for the result count. Its query field offers suggestions in a popover, the arrow keys move between result links, and the empty and error states use a list and an alert. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Landing page

> A whole landing page stacked from ten section blocks: the header, a hero, features, metrics, customer proof, pricing, an FAQ, a closing call to action and the footer.

Source: https://www.youj.dev/docs/blocks/landing

## Blocks

### Landing page

A complete landing page, top to bottom: the mega-menu header with its announcement bar; a centered hero with two calls to action over a soft animated aurora; a ruled grid of features, each read off a live instrument; features again as alternating text and interactive demos; headline metrics that count up for a chosen period; logos and ratings with a featured customer story; plans with a monthly and a yearly price; an FAQ with its own search; a closing call to action; and the sitemap footer. Pick it as the first draft of a product's site, then swap any band for another of its kind or leave it out.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-cta marketing-faq marketing-feature-grid marketing-feature-spotlight marketing-footer marketing-hero-centered marketing-navbar marketing-pricing marketing-metrics marketing-social-proof
```

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

Each band is a block of its own, with its alternatives on its page: the [header](https://www.youj.dev/docs/blocks/navigation) and [footer](https://www.youj.dev/docs/blocks/navigation#footer), the [hero](https://www.youj.dev/docs/blocks/hero), [features](https://www.youj.dev/docs/blocks/features), [metrics](https://www.youj.dev/docs/blocks/proof#metrics) and [logos and ratings](https://www.youj.dev/docs/blocks/proof#logos), [pricing](https://www.youj.dev/docs/blocks/pricing), the [FAQ](https://www.youj.dev/docs/blocks/company#faq) and the [closing call to action](https://www.youj.dev/docs/blocks/cta). The page installs as those section blocks, which Built from under Reference lists with the components they use; the page itself is the composition under Code.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

The page is the header, one `main` that holds the eight sections, and the footer, so the header and the footer sit outside `main` as landmarks. The hero's headline is the page's one `h1`; every section below it is a region named by its own `h2` (`headingLevel` changes a section's). Each section keeps the keyboard and screen reader behavior its own page describes.

Under reduced motion the hero's aurora holds one frame and its text is already in place.

---

# List and detail

> Screens that pair a list with a reading pane: notifications, a list with detail and a record drawer.

Source: https://www.youj.dev/docs/blocks/list-detail

## Blocks

### Notifications

An inbox for mentions, replies and alerts, with filters, read states and the channels each kind reaches you on.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-notification-inbox
```

It brings `app-page`, `avatar`, `badge`, `button`, `card`, `empty`, `field`, `icon-archive`, `icon-at-sign`, `icon-bell`, `icon-check-check`, `icon-credit-card`, `icon-engine`, `icon-inbox`, `icon-mail`, `icon-mail-open`, `icon-message`, `icon-rocket`, `icon-shield-alert`, `illustrations`, `notification-center`, `presence-list`, `skeleton`, `switch`, `tabs`, `toggle`, `tooltip`, `use-announcer`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { NotificationInbox, type NotificationInboxProps } from '@/blocks/app/notification-inbox'

export function NotificationInboxView({ notifications, incoming, preferences, systemKinds }: Pick<NotificationInboxProps, 'notifications' | 'incoming' | 'preferences' | 'systemKinds'>) {
  return (
    <NotificationInbox
      notifications={notifications}
      incoming={incoming}
      preferences={preferences}
      systemKinds={systemKinds}
      copy={{ brand: 'Northwind' }}
      onPreferencesChange={(preferences, quiet) => {
        // your code
      }}
      onOpen={(notification) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own. |
| `copy` | `Partial<NotificationsCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `notifications` | `InboxNotification[]` |  | The notifications it opens with. Default: a demo workspace's, timed from when the page opens. |
| `incoming` | `Arrival[]` | `two demo arrivals` | Notifications that arrive while the page is open, `after` ms from when it opens. Pass [] for none. |
| `preferences` | `Preferences` | `demo` | Where each kind reaches you, to start with. |
| `systemKinds` | `readonly Kind[]` | `deploy, billing and security` | The kinds the System tab lists. |
| `lockedChannels` | `Partial<Record<Kind, readonly Channel[]>>` | `security's email` | Channels a kind always uses, whatever the switches say; those kinds also ignore Do not disturb. |
| `kindIcons` | `Record<string, ComponentType<IconProps>>` | `the five built-in kinds'; any other kind gets a bell` | The icon for each kind, on its notification and in the bell. |
| `onPreferencesChange` | `(preferences: Preferences, quiet: boolean) => void` |  | Fires with every change to the switches. |
| `onOpen` | `(notification: InboxNotification) => void` |  | Opening a notification (it's marked read too). |
| `illustration` | `IllustrationSlot` |  | The picture for an empty inbox: a scene by id, or your own node; `null` for none. Default: the notifications scene. |
| `locale` | `string` |  | Formats its times (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |

**Strings:** `copy` takes `brand`, `account`, `title`, `subtitle`, `inbox`, `unreadCount`, `loading`, `filters`, `all`, `mentions`, `system`, `unreadOnly`, `markAllRead`, `markRead`, `markUnread`, `archive`, `open`, `unreadPrefix`, `today`, `earlier`, `justNow`, `announceRead`, `announceUnread`, `announceArchived`, `announceAllRead`, `emptyTitle`, `emptyDescription`, `noUnreadTitle`, `noUnreadDescription`, `showAll`, `noMentionsTitle`, `noMentionsDescription`, `noSystemTitle`, `noSystemDescription`, `preferences`, `preferencesDescription`, `kind`, `channels`, `kinds`, `channelFor`, `required`, `quiet`, `quietDescription`, `savedHint`, `locale`.

### List and detail

Read feature requests beside the list they come from: move with the arrow keys, drag rows into priority order, resize the panes, and open a request in a drawer on a phone.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-list-detail
```

It brings `app-page`, `avatar`, `badge`, `button`, `drawer`, `icon-chevron-up`, `icon-git-merge`, `icon-message`, `icon-plus`, `icon-search`, `illustrations`, `input-group`, `kbd`, `resizable`, `reveal`, `scroll-area`, `segmented-control`, `select`, `skeleton`, `sortable-list`, `toast`, `use-announcer`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ListDetail, type ListDetailProps } from '@/blocks/app/list-detail'

export function ListDetailView({ requests, brand }: Pick<ListDetailProps, 'requests' | 'brand'>) {
  return (
    <ListDetail
      requests={requests}
      brand={brand}
      copy={{ title: 'Requests' }}
      onSelectedChange={(id) => {
        // your code
      }}
      onStatusChange={async (request, status) => {
        // await your API here; the block shows progress until it settles
      }}
      onReorder={async (ids) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `section`, `newRequest`, `resizeList`, `detailRegion`, `search`, `sortBy`, `sorts`, `statuses`, `noMatch`, `clearSearch`, `emptyTitle`, `emptyDescription`, `loading`, `errorTitle`, `retry`, `votes`, `hint`, `keyMove`, `keyOpen`, `keyReorder`, `moved`, `statusChanged`, `undo`, `mergePrompt`, `replyDraft`, `ago`, `status`, `replyToAskers`, `merge`, `figureVotes`, `figureRevenue`, `figureOpened`, `updated`, `theAsk`, `whereItStands`, `ownedBy`, `whosAsking`, `pickTitle`, `pickMove`, `pickOpen`.

### Record drawer

Open a deal from the pipeline in a floating drawer over the list: its owner, stage, odds, dates and value, then its meetings, progress, notes and activity.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-record-drawer
```

It brings `app-page`, `async-button`, `badge`, `button`, `icon-activity`, `icon-banknote`, `icon-bar-chart`, `icon-briefcase`, `icon-building`, `icon-calendar-check`, `icon-calendar-clock`, `icon-circle-dashed`, `icon-circle-user`, `icon-file-text`, `icon-flag`, `icon-hash`, `icon-list-checks`, `icon-plus`, `icon-user-check`, `icon-video`, `item-pager`, `property-list`, `sheet`, `tables-data-grid`, `toast`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { RecordDrawer, type RecordDrawerProps } from '@/blocks/app/record-drawer'

export function RecordDrawerView({ deals }: Pick<RecordDrawerProps, 'deals'>) {
  return (
    <RecordDrawer
      deals={deals}
      copy={{ title: 'Deals' }}
      linkComponent={Link}
      onValueChange={(id, deal) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onEdit={async (deal) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `description`, `section`, `period`, `noun`, `newDeal`, `columns`, `stages`, `properties`, `sections`, `viewAll`, `viewAllLabel`, `nothingYet`, `videoCall`, `edit`, `open`, `close`, `today`, `yesterday`, `editing`, `opening`, `editingProperty`, `viewing`, `failed`, `emptyTitle`, `emptyDescription`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Notifications has one `h1`, tabs for its filters, a live region for new items and a preferences table with a labelled switch per channel. List and detail moves through requests with Arrow Up and Down, Home, End and Enter, reorders with Alt plus the arrow keys, reports loading and errors in status and alert regions, and closes its phone drawer with Escape. Record drawer opens a sheet that traps focus and closes with Escape. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Onboarding

> Screens for getting started: onboarding, creating a workspace, accepting an invite and a multi-step setup wizard.

Source: https://www.youj.dev/docs/blocks/onboarding

## Blocks

### Onboarding

Welcome users with a guided flow for naming a workspace, choosing a theme and inviting teammates.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-onboarding
```

It brings `async-button`, `button`, `card`, `empty`, `field`, `grid-backdrops`, `icon-check-circle`, `icon-rocket`, `icon-sparkles`, `icon-user-plus`, `icon-x`, `illustrations`, `input`, `input-group`, `presence-list`, `radio-group`, `stepper`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Onboarding, type OnboardingProps } from '@/blocks/app/onboarding'

export function OnboardingView({ presets }: Pick<OnboardingProps, 'presets'>) {
  return (
    <Onboarding
      presets={presets}
      copy={{ page: 'Set up your workspace' }}
      linkComponent={Link}
      onFinish={(setup) => {
        // your code
      }}
      onStepChange={(step) => {
        // your code
      }}
      onOpenDashboard={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onFinish` | `(setup: OnboardingSetup) => unknown` | `a demo wait` | Creates the workspace from the answers; resolve to show "You're all set", throw to show why it failed. |
| `illustration` | `IllustrationSlot` | `'team'` | The welcome step's picture: a scene from the illustrations by id, your own node, or `null` for the sparkles icon. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Northwind` | The product the welcome names. |
| `defaultValues` | `Partial<OnboardingSetup>` |  | Answers filled in at the start, e.g. the company name from sign-up. |
| `presets` | `string[]` | `every preset` | The theme presets to choose from, by id. |
| `step` | `number` |  | The open step (0–3), controlled. Pair it with `onStepChange`. |
| `defaultStep` | `number` | `0` | The step open at first, uncontrolled. |
| `onStepChange` | `(step: number) => void` |  | Called with the step a Back, Get started or Continue moves to. |
| `dashboardHref` | `string` |  | Where "Open your dashboard" goes; without it the button calls `onOpenDashboard`. |
| `onOpenDashboard` | `() => void` |  | Called from "Open your dashboard". |
| `linkComponent` | `ElementType` | `'a'` | Renders the dashboard link, e.g. Next.js `Link`. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page title's level (visually hidden); step titles sit one below. |
| `copy` | `Partial<OnboardingCopy>` |  | Any of the flow's strings, to rewrite or translate. |

**Strings:** `copy` takes `page`, `stepper`, `stepWelcome`, `stepWorkspace`, `stepTheme`, `stepInvite`, `welcomeTitle`, `welcomeDescription`, `nameTitle`, `nameDescription`, `nameLabel`, `namePlaceholder`, `nameRequired`, `url`, `urlPrefix`, `urlFallback`, `urlDescription`, `themeTitle`, `themeDescription`, `themeGroup`, `themePreview`, `inviteTitle`, `inviteDescription`, `email`, `emailPlaceholder`, `emailInvalid`, `emailTaken`, `add`, `invites`, `remove`, `back`, `start`, `continue`, `finishing`, `finished`, `finish`, `failed`, `doneTitle`, `doneDescription`, `openDashboard`.

### Create workspace

Walk users through creating a workspace, choosing its address and inviting their team, with the address checked as they type.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-create-workspace
```

It brings `async-button`, `avatar-upload`, `button`, `card`, `empty`, `field`, `icon-alert-triangle`, `icon-arrow-right`, `icon-check`, `icon-check-circle`, `input`, `input-group`, `morph-label`, `reveal`, `select`, `spinner`, `tag-input`, `wizard`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { CreateWorkspace } from '@/blocks/app/create-workspace'

export function CreateWorkspaceView() {
  return (
    <CreateWorkspace
      copy={{ brand: 'Northwind' }}
      onCreate={(workspace) => {
        // your code
      }}
      onOpen={(workspace) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `copy` | `Partial<CreateWorkspaceCopy>` |  | Any of the flow's strings, to rewrite or translate. |
| `checkSlug` | `(slug: string) => Promise<boolean>` | `a demo that treats a few names (acme, admin, api…) as taken` | Resolves true when a slug is free. |
| `onCreate` | `(workspace: CreateWorkspaceResult) => unknown` | `demo` | Creates the workspace (and sends invites). Reject to stay on the step. |
| `onOpen` | `(workspace: CreateWorkspaceResult) => void` |  | "Open workspace" on the done state. |

**Strings:** `copy` takes `brand`, `title`, `subtitle`, `stepWorkspace`, `stepWorkspaceDescription`, `stepTeam`, `stepTeamDescription`, `stepInvite`, `stepInviteDescription`, `name`, `namePlaceholder`, `nameRequired`, `url`, `urlPrefix`, `slugHint`, `slugChecking`, `slugAvailable`, `slugTaken`, `slugInvalid`, `logo`, `logoHint`, `teamSize`, `teamSizePlaceholder`, `teamSizeRequired`, `useCase`, `useCasePlaceholder`, `useCaseRequired`, `emails`, `emailsPlaceholder`, `emailsHint`, `emailInvalid`, `role`, `invitesRequired`, `back`, `next`, `skip`, `sendInvites`, `creating`, `created`, `doneTitle`, `doneDescription`, `open`, `teamSizes`, `useCases`, `roles`.

### Accept invite

Help a new teammate join a workspace with an invitation page that shows who invited them.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-accept-invite
```

It brings `async-button`, `avatar`, `badge`, `button`, `card`, `field`, `icon-arrow-right`, `icon-check`, `icon-hourglass`, `input`, `password-input`, `reveal`, `tabs`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { AcceptInvite, type AcceptInviteProps } from '@/blocks/app/accept-invite'

export function AcceptInviteView({ status, invite }: Pick<AcceptInviteProps, 'status' | 'invite'>) {
  return (
    <AcceptInvite
      status={status}
      invite={invite}
      copy={{ brand: 'Northwind' }}
      onAccept={(details) => {
        // your code
      }}
      onRequestNew={() => {
        // your code
      }}
      onOpen={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `'valid' \| 'expired' \| 'member'` | `'valid'` | Which page the link resolves to. |
| `invite` | `Invite` | `demo` |  |
| `defaultMode` | `'create' \| 'sign-in'` | `'sign-in'` | The tab it opens on: sign in when the address has an account. |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `copy` | `Partial<AcceptInviteCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `onAccept` | `(details: AcceptInviteDetails) => unknown` | `demo` | Signs in or signs up, and accepts. Reject with an Error to stay on the form. |
| `onRequestNew` | `() => unknown` | `demo` | "Request a new invite" on an expired one. |
| `onOpen` | `() => void` |  | "Open <workspace>", once in. |
| `onSignIn` | `() => void` |  | "Go to sign in" and "Use another account". |

**Strings:** `copy` takes `brand`, `joinTitle`, `joinDescription`, `invitedAs`, `role`, `members`, `memberCount`, `expires`, `choice`, `signInTab`, `createTab`, `email`, `password`, `passwordRequired`, `fullName`, `fullNamePlaceholder`, `nameRequired`, `newPassword`, `newPasswordHint`, `passwordTooShort`, `signInAndJoin`, `createAndJoin`, `joining`, `joinFailed`, `wrongAccount`, `joinedTitle`, `joinedDescription`, `open`, `expiredTitle`, `expiredDescription`, `requestNew`, `requesting`, `requested`, `signIn`, `memberTitle`, `memberDescription`, `switchAccount`.

### Setup wizard

A multi-step setup with checks at each step, a review, a saved draft and a finished state.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-setup-wizard
```

It brings `async-button`, `button`, `card`, `date-picker`, `field`, `form`, `icon-arrow-right`, `icon-pencil`, `icon-save`, `icon-user-plus`, `illustrations`, `input`, `phone-input`, `progress`, `reveal`, `segmented-control`, `select`, `switch`, `textarea`, `use-mobile`, `wizard`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SetupWizard, type SetupWizardProps } from '@/blocks/app/setup-wizard'

export function SetupWizardView({ teams, laptops, accounts, today }: Pick<SetupWizardProps, 'teams' | 'laptops' | 'accounts' | 'today'>) {
  return (
    <SetupWizard
      teams={teams}
      laptops={laptops}
      accounts={accounts}
      today={today}
      copy={{ section: 'People' }}
      onSaveDraft={async (draft) => {
        // await your API here; the block shows progress until it settles
      }}
      onSubmit={async (hire) => {
        // await your API here; the block shows progress until it settles
      }}
      onViewProfile={(hire) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the page in this theme. Default: the theme around it. |
| `draft` | `Partial<NewHire>` |  | A saved draft to pick up from. |
| `onSaveDraft` | `(draft: NewHire) => Promise<unknown> \| unknown` | `a short demo wait` | Keeps a draft; resolve when it's stored. |
| `onSubmit` | `(hire: NewHire) => Promise<unknown> \| unknown` | `a short demo wait` | Sends the invite; reject to stay on the review. |
| `onViewProfile` | `(hire: NewHire) => void` |  | "View profile" on the success state. |
| `illustration` | `IllustrationSlot` |  | The success state's picture: a scene by id, or your own node; `null` for none. Default: the success scene. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Northwind, with an "N" mark` | The company in the header. |
| `teams` | `Record<string, string>` | `the demo's six` | The teams to choose from, by id. |
| `laptops` | `Record<string, string>` | `Pro, Air or their own` | The laptops to choose from, by id; `byod` reads as bringing their own. |
| `accounts` | `NewHireAccount[]` | `Slack, GitHub and Figma` | The accounts the setup step can switch on. |
| `today` | `Date` |  | The earliest start date offered. Default: today, read after mount. |
| `step` | `number` |  | The open step (0–3), controlled. Pair it with `onStepChange`. |
| `onStepChange` | `(step: number) => void` |  | Called with the step Continue, Back or a review edit moves to. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page title's level; step titles sit one below. |
| `locale` | `string` |  | Formats dates and times. Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `copy` | `Partial<WizardCopy>` |  | Any of the page's strings, including validation messages, to rewrite or translate. |

**Strings:** `copy` takes `section`, `title`, `description`, `progress`, `continue`, `send`, `sent`, `saveDraft`, `saving`, `saved`, `unsaved`, `notSaved`, `draftSaved`, `draftRestored`, `failed`, `personalTitle`, `personalDescription`, `roleTitle`, `roleDescription`, `setupTitle`, `setupDescription`, `reviewTitle`, `reviewDescription`, `firstName`, `firstNamePlaceholder`, `firstNameRequired`, `lastName`, `lastNamePlaceholder`, `lastNameRequired`, `email`, `emailDescription`, `emailPlaceholder`, `emailRequired`, `emailInvalid`, `phone`, `phoneDescription`, `phoneInvalid`, `jobTitle`, `jobTitlePlaceholder`, `jobTitleRequired`, `team`, `teamPlaceholder`, `teamRequired`, `startDate`, `startDateDescription`, `startDateRequired`, `startDatePast`, `employment`, `fullTime`, `partTime`, `contract`, `laptop`, `laptopDescription`, `laptopPlaceholder`, `laptopRequired`, `accounts`, `accountsDescription`, `baseAccount`, `note`, `noteDescription`, `notePlaceholder`, `noteTooLong`, `name`, `edit`, `editSection`, `jobTitleShort`, `starts`, `doneTitle`, `doneDescription`, `another`, `viewProfile`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each screen is a `main` with one heading (`h1` by default; `headingLevel` changes it). Onboarding’s step indicator is labelled, its theme choice is a labelled radio group, and Enter moves to the next step from its text fields. Create workspace announces the result of the address check in a live region. Setup wizard announces step changes in a live region and labels its review sections. Accept invite shows the inviter’s avatar with `alt` text. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Planning

> Screens for planning work and time: a Kanban board and a week calendar.

Source: https://www.youj.dev/docs/blocks/planning

## Blocks

### Board

Help a team track tasks through their stages with a Kanban board and a sprint summary above it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-task-board
```

It brings `alert`, `app-page`, `avatar`, `avatar-stack`, `badge`, `button`, `icon-calendar`, `icon-list-checks`, `icon-message`, `icon-plus`, `kanban`, `segmented-meter`, `share-bar`, `skeleton`, `youj-ui-core` with it.

```tsx
'use client'

import { TaskBoard, type TaskBoardProps } from '@/blocks/app/task-board'

export function TaskBoardView({ columns, tasks, labelTones }: Pick<TaskBoardProps, 'columns' | 'tasks' | 'labelTones'>) {
  return (
    <TaskBoard
      columns={columns}
      tasks={tasks}
      labelTones={labelTones}
      copy={{ newTask: 'New task' }}
      onMove={async (move, tasks) => {
        // await your API here; the block shows progress until it settles
      }}
      onOpen={(task) => {
        // your code
      }}
      onCreate={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width. |
| `title` | `string` | `'My tasks'` | The page's heading. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The heading's level. |
| `classNames` | `Partial<Record<'header' \| 'content', string>>` |  | Extra classes for the header and the board. |
| `columns` | `KanbanColumn[]` | `Backlog, In progress (4), In review and Done` | The columns, left to right; a `limit` warns past it. |
| `tasks` | `BoardTask[]` | `Northwind's fifteen` | The cards, each placed by its `column`. A new array replaces them. |
| `labelTones` | `Record<string, BoardTone>` |  | Tints for your own labels, by label: a task's own `labelTone` still wins. Default: every label in one quiet neutral pill. |
| `sprint` | `BoardSprint \| null` | `Northwind's Sprint 14` | The sprint over the board; null leaves it out. |
| `onMove` | `(move: KanbanMove<BoardTask>, tasks: BoardTask[]) => Promise<unknown> \| unknown` |  | A card moved; receives the move and every task after it. Return a promise to put the card back if it rejects. |
| `onOpen` | `(task: BoardTask) => void` |  | Enter, or a click, on a card. |
| `onCreate` | `() => void` |  | The New task button. |
| `actions` | `ReactNode` |  | The header's buttons, in place of New task. |
| `loading` | `boolean` | `false` | Shows skeleton columns in place of the board. |
| `error` | `ReactNode` |  | A load error, shown in place of the board with `onRetry`. |
| `onRetry` | `() => void` |  | The error's "Try again". |
| `empty` | `ReactNode` |  | Replaces the board when there are no tasks at all. Default: the board's empty columns. |
| `copy` | `Partial<BoardCopy>` |  | Any of the page's strings, to rewrite or translate. |

**Strings:** `copy` takes `subtitle`, `newTask`, `urgent`, `high`, `medium`, `low`, `due`, `assigned`, `today`, `doneColumn`, `points`, `subtasks`, `comments`, `with`, `pointsDone`, `daysLeft`, `team`, `errorTitle`, `retry`, `failed`.

### Calendar

Plan a week on a time grid, with what is up next today and a Slot Grid to find a free hour.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-week-calendar
```

It brings `alert`, `app-page`, `avatar`, `badge`, `button`, `icon-chevron-left`, `icon-chevron-right`, `popover`, `segmented-control`, `skeleton`, `slot-grid`, `typography`, `youj-core`, `youj-labels`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { WeekCalendar, type WeekCalendarProps } from '@/blocks/app/week-calendar'

export function WeekCalendarView({ events, calendars, view }: Pick<WeekCalendarProps, 'events' | 'calendars' | 'view'>) {
  return (
    <WeekCalendar
      events={events}
      calendars={calendars}
      view={view}
      copy={{ previous: 'Previous week' }}
      onDateChange={(date) => {
        // your code
      }}
      onViewChange={(view) => {
        // your code
      }}
      onSelect={(event) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter. |
| `title` | `string` | `'Calendar'` | The page's heading. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The heading's level; the agenda's days sit one below it. |
| `classNames` | `Partial<Record<'header' \| 'content', string>>` |  | Extra classes for the header and the views. |
| `events` | `CalendarEvent[]` | `Northwind's week` | The events. A recurring one shows every week on its weekday. |
| `calendars` | `CalendarSource[]` | `Team, Focus and External` | The calendars events belong to, listed as a legend. |
| `now` | `Date \| number` | `10:42 on Monday 28 September 2026` | The current time: today's column, the line at now and which events are over. |
| `date` | `string` |  | Any day of the week shown ("2026-10-05"), controlled. Pair with `onDateChange`. |
| `defaultDate` | `string` |  | Any day of the week shown first, uncontrolled. Default: today. |
| `onDateChange` | `(date: string) => void` |  | Previous, Next or Today moved the week; receives its Monday. |
| `view` | `'week' \| 'agenda'` |  | The view, controlled. Pair with `onViewChange`. |
| `defaultView` | `'week' \| 'agenda'` | `'week'` | The view shown first, uncontrolled. |
| `onViewChange` | `(view: CalendarView) => void` |  | Week or Agenda was chosen. |
| `onSelect` | `(event: CalendarEvent) => void` |  | An event's details were opened. |
| `onFindTime` | `(time: FreeTime) => void` |  | A free hour was picked in Find a time. |
| `aside` | `boolean` | `true` | The rail beside the week (Up next and Find a time) in a wide page. |
| `hours` | `{ start: number; end: number }` | `8 to 18` | The grid's first and last hour. |
| `locale` | `string` |  | How weekday and month names read (BCP 47). Default: the app's (YoujProvider's `locale`), else en-US. |
| `loading` | `boolean` | `false` | Keeps the layout while the events load. |
| `error` | `ReactNode` |  | A load error, shown in place of the views with `onRetry`. |
| `onRetry` | `() => void` |  | The error's "Try again". |
| `empty` | `ReactNode` |  | Shown in place of the views when the week has no events. Default: the views, each day saying it's free. |
| `actions` | `ReactNode` |  | The header's buttons, after the week controls. |
| `fill` | `boolean` | `false` | Take the frame's whole width instead of stopping at the page width (1280px at 100% scale). |
| `copy` | `Partial<CalendarCopy>` |  | Any of the page's strings, to rewrite or translate. |

**Strings:** `copy` takes `previous`, `next`, `viewLabel`, `week`, `agenda`, `calendars`, `range`, `eventLabel`, `calendar`, `where`, `with`, `repeats`, `every`, `asideLabel`, `upNext`, `dayDone`, `startsIn`, `now`, `findTime`, `findTimeHint`, `errorTitle`, `retry`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Board has a `header` and one heading. Cards can be moved without a pointer: arrow keys walk the cards, Space picks one up, the arrows carry it and Space drops it, and each step is announced. Calendar’s week is a labelled group whose events open in a popover, with `aria-busy` while it loads and a live region for week changes. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Product and order

> Screens for the shopper: a product detail page and an order detail with delivery progress.

Source: https://www.youj.dev/docs/blocks/storefront

## Blocks

### Product detail

Let shoppers see a product from every side in the color they pick, choose a size and know when it will arrive.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-product-detail
```

It brings `accordion`, `async-button`, `badge`, `breadcrumb`, `card`, `carousel`, `commerce-product-card`, `commerce-product-render`, `field`, `icon-heart`, `icon-rotate-ccw`, `icon-ruler`, `icon-shopping-cart`, `icon-star`, `icon-store`, `icon-truck`, `number-input`, `toggle`, `typography`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ProductDetail, type ProductDetailProps } from '@/blocks/commerce/product-detail'

export function ProductDetailView({ product, breadcrumbs, perks, sections }: Pick<ProductDetailProps, 'product' | 'breadcrumbs' | 'perks' | 'sections'>) {
  return (
    <ProductDetail
      product={product}
      breadcrumbs={breadcrumbs}
      perks={perks}
      sections={sections}
      copy={{ breadcrumb: 'Shop' }}
      linkComponent={Link}
      onAddToCart={async (line) => {
        // await your API here; the block shows progress until it settles
      }}
      onSave={(product, saved) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `product` | `Product` | `a sample kettle (swap in yours)` | The product; required in practice. |
| `onAddToCart` | `(line: { product: Product; color: string; size?: string; quantity: number }) => Promise<unknown>` | `a short demo wait` | Resolve once the line is in the cart; reject to shake the button. `color` is the colorway's id. |
| `onSave` | `(product: Product, saved: boolean) => void` |  | Hears "Save for later" being turned on or off. |
| `breadcrumbs` | `{ label: string; href: string; }[]` |  | The trail above the title, as links. Default: Shop › the product's category. |
| `sizeGuideHref` | `string \| null` | `'#size-guide'` | The size guide's page; `null` hides the link. |
| `perks` | `ProductPerk[]` |  | The delivery panel's lines. Default: free delivery (arriving three working days from `today`), pickup and returns. |
| `sections` | `ProductSection[]` |  | The folds at the foot. Default: details, shipping and returns. |
| `today` | `Date \| number` | `the demo's day` | Today, for the delivery day. |
| `currency` | `string` | `'USD'` | An ISO 4217 code. |
| `locale` | `string` | `'en-US'` | A BCP 47 locale for prices, dates and counts. |
| `linkComponent` | `ElementType` | `'a'` | Renders breadcrumb and size-guide links, e.g. Next.js `Link`. |
| `copy` | `Partial<ProductDetailCopy>` |  | Any of the page's strings, to rewrite or translate. |

**Strings:** `copy` takes `breadcrumb`, `photos`, `views`, `slide`, `thumb`, `rated`, `reviews`, `each`, `was`, `now`, `color`, `size`, `sizeGuide`, `soldOut`, `quantity`, `addToCart`, `adding`, `added`, `addError`, `save`, `freeDelivery`, `arrives`, `pickUp`, `pickUpDetail`, `returns`, `returnsDetail`, `details`, `detailsBody`, `shipping`, `shippingBody`, `returnsTitle`, `returnsBody`.

### Order detail

Help customers check an order and see where it is on its way to them, with its items, details, a return flow in a dialog and a menu of actions.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add commerce-order-detail
```

It brings `alert`, `async-button`, `badge`, `button`, `checkbox`, `commerce-product-card`, `counter`, `dialog`, `dropdown-menu`, `field`, `icon-alert-triangle`, `icon-arrow-left`, `icon-banknote`, `icon-check-circle`, `icon-circle-x`, `icon-copy`, `icon-download`, `icon-mail`, `icon-message-dots`, `icon-package`, `icon-phone`, `icon-receipt`, `icon-refresh`, `icon-shopping-bag`, `icon-truck`, `icon-undo`, `morph-label`, `number-input`, `radio-group`, `reveal`, `stagger`, `stepper`, `tabs`, `textarea`, `timeline`, `toast`, `typography`, `wizard`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { OrderDetail } from '@/blocks/commerce/order-detail'

export function OrderDetailView() {
  return (
    <OrderDetail
      copy={{ brandSection: 'Orders' }}
      linkComponent={Link}
      onTrack={async (shipment) => {
        // await your API here; the block shows progress until it settles
      }}
      onReturn={async (request) => {
        // await your API here; the block shows progress until it settles
      }}
      onDownloadInvoice={async (order) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `false` | A view inside another app (an account page): no store bar, a `section` named by an `h2` instead of the page's `main` and `h1`, and no page height or padding, so the host lays it out. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (1088px at 100% scale). |
| `order` | `OrderState \| Order` | `'split'` | The order: yours, or a demo state (split across two packages, one package in transit, delivered, or canceled). |
| `onTrack` | `(shipment: Shipment) => Promise<boolean> \| boolean` |  | Asks the carrier for news about a package. Resolve true when there was (then pass the updated `order`), false when not. Default: the demo's next scan. |
| `onReturn` | `(request: ReturnRequest) => Promise<ReturnRequest \| void> \| ReturnRequest \| void` | `a short demo wait` | Starts a return; resolve with the request as recorded (your RMA, say) or nothing. Reject to keep the dialog open. |
| `onDownloadInvoice` | `(order: Order) => Promise<unknown> \| unknown` |  | Downloads the invoice. Default: a short demo wait and a toast. |
| `onContact` | `(channel: 'chat' \| 'email' \| 'phone', order: Order) => void` |  | Opens a support channel. Default: a toast per channel. |
| `support` | `{ email: string; phone: string }` | `Fieldwork's` | Support's email and phone in the contact menu. |
| `brand` | `{ name: string; logo?: ReactNode }` |  | The store's name and mark in the top bar. Default: Fieldwork. |
| `ordersHref` | `string \| null` | `'#orders'` | "All orders"; `null` hides it. |
| `linkComponent` | `ElementType` | `'a'` | Renders "All orders", e.g. Next.js `Link`. |
| `currency` | `string` | `'USD'` | An ISO 4217 code. |
| `locale` | `string` |  | A BCP 47 locale for money, dates and times. Default: the app's (YoujProvider's `locale`), else en-US. |
| `now` | `Date \| number` | `the demo's now` | Now, for "today" and "tomorrow" and the return's drop-off date. |
| `copy` | `Partial<OrderDetailCopy>` |  | Any of the page's strings, to rewrite or translate. |

**Strings:** `copy` takes `brandSection`, `allOrders`, `title`, `placed`, `canceled`, `delivered`, `someDelivered`, `onItsWay`, `downloadInvoice`, `preparing`, `downloaded`, `downloadedToast`, `downloadedCancelled`, `downloadedFor`, `returnItems`, `contactSupport`, `chat`, `chatToast`, `chatToastDetail`, `emailUs`, `emailToast`, `emailToastDetail`, `callUs`, `callToast`, `callToastDetail`, `returnStarted`, `returnNote`, `toCard`, `asCredit`, `cancellation`, `delivery`, `deliveryPackages`, `canceledOn`, `canceledRefund`, `packages`, `packageDelivered`, `packageOnItsWay`, `noNewScans`, `lastScan`, `deliveredOn`, `arriving`, `estimated`, `copyTracking`, `copied`, `copyFailed`, `track`, `checking`, `updated`, `upToDate`, `progress`, `inPackage`, `itemCount`, `trackingHistory`, `today`, `tomorrow`, `yesterday`, `items`, `qty`, `each`, `returnStartedBadge`, `returning`, `payment`, `subtotal`, `discount`, `shipping`, `free`, `tax`, `total`, `refunded`, `refundedOn`, `charged`, `addresses`, `shippingTo`, `billingTo`, `receipts`, `returnTitle`, `returnDoneTitle`, `returnDescription`, `returnDoneDescription`, `startReturn`, `cancel`, `itemsStep`, `itemsStepDescription`, `chooseItem`, `backEach`, `howMany`, `stillOnItsWay`, `reasonStep`, `reasonStepDescription`, `chooseReason`, `reasons`, `note`, `notePlaceholder`, `refundStep`, `refundStepDescription`, `refundTo`, `cardTitle`, `cardHint`, `creditTitle`, `creditHint`, `handOver`, `storeTitle`, `storeHint`, `pickupTitle`, `pickupHint`, `refundFor`, `confirmation`, `yourCredit`, `done`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Product detail has one `h1`. The size choices are radio inputs with a label each (a sold-out size says so in its label), the gallery is a labelled carousel whose slides are labelled by position, and the rating is read as text. Order detail is a `main` under a `header` with labelled sections for items, details and shipment, and the shipment progress is a list with a status region. The return flow opens in a dialog that closes with Escape, and row actions sit in a menu with arrow-key navigation. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Product updates

> Screens that show where the product is heading: a versioned changelog and a public roadmap.

Source: https://www.youj.dev/docs/blocks/product-updates

## Blocks

### Roadmap

A public roadmap by stage, with a place to submit and vote on feature requests, each request opening in a sheet.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add content-roadmap
```

It brings `app-page`, `async-button`, `avatar`, `badge`, `button`, `collapse`, `counter`, `dialog`, `empty`, `field`, `icon-arrow-up`, `icon-calendar`, `icon-circle-dashed`, `icon-engine`, `icon-filter`, `icon-hammer`, `icon-lightbulb`, `icon-message`, `icon-plus`, `icon-rocket`, `icon-trending-up`, `input`, `presence-list`, `reveal`, `select`, `sheet`, `tabs`, `textarea`, `timeline`, `toast`, `toggle`, `toggle-group`, `typography`, `use-announcer`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Roadmap, type RoadmapProps } from '@/blocks/content/roadmap'

export function RoadmapView({ requests, view, categories }: Pick<RoadmapProps, 'requests' | 'view' | 'categories'>) {
  return (
    <Roadmap
      requests={requests}
      view={view}
      categories={categories}
      copy={{ brandSection: 'Roadmap' }}
      onViewChange={(view) => {
        // your code
      }}
      onVote={(request, voted) => {
        // your code
      }}
      onSubmit={async (draft) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `brandSection`, `changelog`, `eyebrow`, `title`, `description`, `stats`, `submit`, `view`, `requestsTab`, `roadmapTab`, `statusFilter`, `areaFilter`, `sort`, `allStatuses`, `allAreas`, `sorts`, `status`, `votes`, `upvote`, `upvoted`, `unvoted`, `emptyTitle`, `emptyDescription`, `noMatchesTitle`, `noMatches`, `clearFilters`, `postedTitle`, `postedDescription`, `noDetails`, `list`, `comments`, `thisWeek`, `boardEmpty`, `submitted`, `movedTo`, `team`, `released`, `aiming`, `requestedBy`, `following`, `follow`, `history`, `commentsTitle`, `noComments`, `commentOn`, `yourComment`, `commentPlaceholder`, `postingAs`, `posting`, `posted`, `comment`, `dialogDescription`, `titleLabel`, `titlePlaceholder`, `titleTooShort`, `similarFound`, `similarHeading`, `details`, `detailsPlaceholder`, `detailsHint`, `area`, `cancel`, `postRequest`.

### Changelog

Release notes organized by version and date, with a way to subscribe to new ones.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add content-changelog
```

It brings `app-page`, `async-button`, `badge`, `button`, `collapsible`, `counter`, `field`, `icon-bell`, `icon-rss`, `input`, `popover`, `presence-list`, `reveal`, `scroll-progress`, `skeleton`, `toggle-group`, `typography`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Changelog, type ChangelogProps } from '@/blocks/content/changelog'

export function ChangelogView({ releases, filter }: Pick<ChangelogProps, 'releases' | 'filter'>) {
  return (
    <Changelog
      releases={releases}
      filter={filter}
      copy={{ section: '/ changelog' }}
      linkComponent={Link}
      onSubscribe={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
      onFilterChange={(filter) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `section`, `rss`, `readingProgress`, `eyebrow`, `title`, `description`, `filter`, `filters`, `count`, `list`, `smallerFixes`, `archiveBefore`, `archiveLink`, `archiveAfter`, `empty`, `loading`, `subscribe`, `subscribeTitle`, `subscribeDescription`, `email`, `emailPlaceholder`, `emailInvalid`, `subscribing`, `subscribed`, `subscribeError`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Changelog is a `main` with one `h1` and a status region for the subscribe result; the subscribe form opens in a popover. Roadmap is a `main` under a `header` with tabs that follow the kit’s Tabs keyboard pattern. Each vote button is labelled with the request it upvotes, the request sheet and the submit dialog trap focus and close with Escape, and a submitted request is announced in a status region. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Reading

> A screen for long-form reading: documentation with a page tree.

Source: https://www.youj.dev/docs/blocks/reading

## Blocks

### Docs

Documentation with a page tree beside each article and an outline of its headings, a search palette, code tabs and a feedback prompt.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add content-docs
```

It brings `alert`, `anchor-nav`, `async-button`, `badge`, `breadcrumb`, `button`, `collapsible`, `command`, `command-palette`, `icon-arrow-left`, `icon-arrow-right`, `icon-bookmark`, `icon-check`, `icon-code`, `icon-copy`, `icon-menu`, `icon-pencil`, `icon-search`, `icon-sparkle`, `icon-thumbs-down`, `icon-thumbs-up`, `kbd`, `morph-label`, `reveal`, `sheet`, `sliding-indicator`, `table`, `tabs`, `use-controllable-state`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Docs, type DocsProps } from '@/blocks/content/docs'

export function DocsView({ pages, brand }: Pick<DocsProps, 'pages' | 'brand'>) {
  return (
    <Docs
      pages={pages}
      brand={brand}
      copy={{ openNavigation: 'Open navigation' }}
      linkComponent={Link}
      onPageChange={(page) => {
        // your code
      }}
      onFeedback={(page, vote) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `pages` | `Page[]` | `Northstar's SDK docs` | The pages, in nav order; their `group`s become the nav's folds. |
| `page` | `string` |  | The open page's id, controlled: pair it with `onPageChange`. |
| `defaultPage` | `string` | `'installation'` | The page open first, when the docs own it. |
| `onPageChange` | `(page: string) => void` |  |  |
| `getHref` | `(page: Page) => string` |  | Each page's route; links then navigate instead of switching in place. |
| `linkComponent` | `ElementType` | `'a'` | Renders page links, e.g. Next.js `Link`. |
| `brand` | `DocsBrand` | `Northstar` | The product in the header: `{ name, logo?, href? }`. |
| `version` | `string \| null` | `'v2.4'` | The version badge; `null` hides it. |
| `getEditHref` | `((page: Page) => string) \| null` | `'#edit'` | Where "Edit this page" goes; `null` (or no function) hides it. |
| `onFeedback` | `(page: string, vote: 'yes' \| 'no') => void` |  | Hears "Was this page helpful?". |
| `copy` | `Partial<DocsCopy>` |  | Any of the docs' strings, to rewrite or translate. |

**Strings:** `copy` takes `openNavigation`, `search`, `searchTitle`, `searchPlaceholder`, `navigation`, `menuTitle`, `onThisPage`, `updated`, `editPage`, `pagination`, `previous`, `next`, `helpful`, `yes`, `no`, `thanksYes`, `thanksNo`, `feedbackSent`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Docs has a `main`, a labelled page-tree `nav` that marks the current page with `aria-current`, a sheet for the tree on phones, code tabs that follow the kit’s Tabs keyboard pattern, and a feedback result announced in a status region. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Settings and profile

> Account screens: a tabbed settings page and a public profile.

Source: https://www.youj.dev/docs/blocks/settings

## Blocks

### Settings

A tabbed settings page that brings account, team, billing and notification preferences together; this story opens on the Profile tab.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-settings
```

It brings `alert`, `alert-dialog`, `app-page`, `async-button`, `avatar`, `avatar-upload`, `badge`, `button`, `card`, `checkbox`, `dialog`, `dropdown-menu`, `field`, `icon-bell`, `icon-check`, `icon-credit-card`, `icon-download`, `icon-more-horizontal`, `icon-shield`, `icon-user`, `icon-user-plus`, `icon-users`, `input`, `input-group`, `password-input`, `presence-list`, `radio-group`, `segmented-control`, `select`, `skeleton`, `spotlight`, `switch`, `table`, `tabs`, `textarea`, `typography`, `use-controllable-state`, `use-mobile`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { Settings, type SettingsProps } from '@/blocks/app/settings'

export function SettingsView({ user, members, roles, plans }: Pick<SettingsProps, 'user' | 'members' | 'roles' | 'plans'>) {
  return (
    <Settings
      user={user}
      members={members}
      roles={roles}
      plans={plans}
      copy={{ title: 'Settings' }}
      onTabChange={(tab) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onSaveProfile={async (profile) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultTab` | `string` | `'profile'` | The tab open at first, when uncontrolled. |
| `tab` | `string` |  | The open tab, to control it. Pair with `onTabChange`. |
| `onTabChange` | `(tab: string) => void` |  | Called with the tab's id when the person switches tabs. |
| `sections` | `Array<SettingsSectionId \| SettingsSection>` | `the five built-in tabs` | The tabs, in order: a built-in id (`'profile' \| 'account' \| 'team' \| 'billing' \| 'notifications'`) or your own `{ id, label, icon, panel }`. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Northwind Labs` | The workspace, named in the page's description, the team count and the invite, and its `logo` over the standalone title. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page title's level. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, in a readable column centered in the content area, with no logo of its own. |
| `fill` | `boolean` | `false` | Embedded, take the frame's whole width instead of stopping at a readable 1024px (at 100% scale). |
| `user` | `SettingsUser` | `Ada Lovelace` | The signed-in person: profile fields and account email. |
| `members` | `SettingsMember[]` | `the demo's four` | The team, in order. |
| `roles` | `SettingsRole[]` | `Owner, Admin, Member, Viewer` | The roles a member can hold; `owner` rows are locked. |
| `plans` | `SettingsPlan[]` | `Hobby, Pro, Enterprise` | The plans, cheapest first. |
| `plan` | `string` |  | The current plan's id, to control it. |
| `defaultPlan` | `string` | `'pro'` | The current plan's id at first, when uncontrolled. |
| `paymentMethod` | `SettingsPaymentMethod \| null` | `a Visa ending 4242` | The card on file, or `null` for none. |
| `invoices` | `SettingsInvoice[]` | `the demo's three` | Past invoices, newest first. |
| `notifications` | `SettingsNotificationGroup[]` | `Email and Push` | Notification switches, by channel. |
| `loading` | `boolean` | `false` | Shows skeleton rows in the team and invoice tables while data loads. |
| `copy` | `Partial<SettingsCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `error` | `ReactNode` |  | A load failure, shown above the tabs with a Retry button when `onRetry` is set. |
| `onRetry` | `() => void` |  | Called from the error's Retry button. |
| `classNames` | `Partial<Record<'header' \| 'tabs' \| 'content', string>>` |  | Classes for key parts: the page header, the tab list and each tab's panel. |
| `onSaveProfile` | `(profile: SettingsProfile) => Promise<unknown> \| unknown` |  | Saves the profile form; resolve when saved, throw to show the error. Default: a demo wait. |
| `onSaveAvatar` | `(file: File) => Promise<unknown> \| unknown` |  | Uploads a new photo. Default: a demo wait. |
| `onRemoveAvatar` | `() => Promise<unknown> \| unknown` |  | Removes the photo. Default: a demo wait. |
| `onUpdatePassword` | `(passwords: { current: string; next: string; }) => Promise<unknown> \| unknown` |  | Changes the password once both new fields match. Default: a demo wait. |
| `onDeleteAccount` | `() => Promise<unknown> \| unknown` |  | Deletes the account after the typed confirmation. Default: a demo wait. |
| `onInvite` | `(invite: { email: string; role: string; }) => Promise<unknown> \| unknown` |  | Sends an invite; the row joins the table once it resolves. Default: a demo wait. |
| `onRoleChange` | `(member: SettingsMember, role: string) => Promise<unknown> \| unknown` |  | Called when a member's role changes. |
| `onRemoveMember` | `(member: SettingsMember) => Promise<unknown> \| unknown` |  | Removes a member or revokes an invite; the row leaves once it resolves. |
| `onResendInvite` | `(member: SettingsMember) => Promise<unknown> \| unknown` |  | Sends a pending invite again. |
| `onChangePlan` | `(plan: SettingsPlan) => Promise<unknown> \| unknown` |  | Switches plan; the badge moves once it resolves. Default: a demo wait. |
| `onContactSales` | `(plan: SettingsPlan) => void` |  | Called from a plan marked `contactSales`. |
| `onUpdatePayment` | `() => void` |  | Called from the payment method's Update button. |
| `onDownloadInvoice` | `(invoice: SettingsInvoice) => void` |  | Called from an invoice's download button. |
| `onNotificationChange` | `(notification: SettingsNotification, on: boolean) => void` |  | Called when a notification switch flips. |

**Strings:** `copy` takes `title`, `description`, `tabsLabel`, `profileTab`, `accountTab`, `teamTab`, `billingTab`, `notificationsTab`, `profileTitle`, `profileDescription`, `photo`, `name`, `username`, `usernamePrefix`, `bio`, `bioHint`, `saveProfile`, `saving`, `saved`, `emailTitle`, `emailDescription`, `emailLabel`, `verified`, `passwordTitle`, `passwordDescription`, `currentPassword`, `newPassword`, `confirmPassword`, `passwordMismatch`, `updatePassword`, `updating`, `updated`, `checkFields`, `deleteTitle`, `deleteDescription`, `deleteAccount`, `deleteConfirmTitle`, `deleteConfirmDescription`, `deleteConfirm`, `teamTitle`, `teamCount`, `memberColumn`, `roleColumn`, `actionsColumn`, `invitedBadge`, `roleFor`, `actionsFor`, `resendInvite`, `revokeInvite`, `removeMember`, `emptyTeam`, `invite`, `inviteTitle`, `inviteDescription`, `inviteEmail`, `inviteEmailPlaceholder`, `inviteRole`, `cancel`, `sendInvite`, `sending`, `invited`, `checkEmail`, `invalidEmail`, `currentPlan`, `perMember`, `yourPlan`, `talkToSales`, `downgrade`, `upgrade`, `switching`, `switched`, `paymentTitle`, `paymentDescription`, `cardEnding`, `cardExpires`, `noPaymentMethod`, `updatePayment`, `invoicesTitle`, `invoicesDescription`, `invoiceColumn`, `dateColumn`, `amountColumn`, `statusColumn`, `downloadColumn`, `downloadInvoice`, `invoiceStatus`, `emptyInvoices`, `loading`, `errorTitle`, `retry`, `notificationsTitle`, `notificationsDescription`.

### Notification preferences

Notification preferences as one card: a master Off / On, what to be told about, reminders and channels. Turning the master off mutes the rest, and nothing is stored until Save changes.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-settings
```

```tsx
'use client'

import { Settings, type SettingsProps } from '@/blocks/app/settings'

**Props**

### Profile

A public profile for creators, with a cover, follow controls, tabs of work and a link visitors can copy.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-profile
```

It brings `app-page`, `avatar`, `avatar-stack`, `badge`, `button`, `card`, `counter`, `icon-badge-check`, `icon-check`, `icon-external-link`, `icon-heart`, `icon-link`, `icon-map-pin`, `icon-message`, `icon-package`, `icon-plus`, `icon-star`, `icon-type`, `morph-label`, `stagger`, `tabs`, `timeline`, `tooltip`, `typography`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { Profile, type ProfileProps } from '@/blocks/app/profile'

export function ProfileView({ user, stats, work, activity }: Pick<ProfileProps, 'user' | 'stats' | 'work' | 'activity'>) {
  return (
    <Profile
      user={user}
      stats={stats}
      work={work}
      activity={activity}
      copy={{ title: 'Profile' }}
      onFollowingChange={(following) => {
        // your code
      }}
      onMessage={() => {
        // your code
      }}
      onCopyLink={(url) => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `verified`, `follow`, `following`, `message`, `copyLink`, `copied`, `followers`, `tabsLabel`, `workTab`, `activityTab`, `aboutTab`, `likes`, `emptyWork`, `asideLabel`, `followedBy`, `followedByDescription`, `mutualFollowers`, `elsewhere`, `contributions`, `heatmapDescription`, `heatmapLabel`, `noContributions`, `dayContributions`, `less`, `more`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Settings and Profile use the kit’s Tabs, so the tab list is named, Left and Right Arrow move between tabs and the panel follows the selected one. Settings has one page heading (`headingLevel` changes it) and labelled fields and switches. The invite and confirm steps open in dialogs. Profile has a labelled `aside` and `nav`, the avatar is decorative (`alt=""`) because the name sits beside it, and the activity heatmap is one image with a text label. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Status

> Screens for when a page can't do its job: sign in, no access, not found, errors, maintenance, loading, a launch, tracking, a public status page and a pre-launch waitlist, most beside a miniature that plays the page's state.

Source: https://www.youj.dev/docs/blocks/status

## Blocks

### Service unavailable (503)

Say the service is temporarily down and nothing was lost. The page tries again on its own, waiting longer each time, with the countdown under Try now, while the server cabinet beside it runs with two nodes down; they recover when a retry gets through.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

It brings `async-button`, `button`, `icon-external-link`, `icon-home`, `icon-key`, `icon-log-in`, `icon-refresh`, `progress`, `reveal`, `stagger`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

export function StatusScreenView({ status, retryDelays }: Pick<StatusScreenProps, 'status' | 'retryDelays'>) {
  return (
    <StatusScreen
      status={status}
      retryDelays={retryDelays}
      copy={{ home: 'Back to home' }}
      linkComponent={Link}
      onSignIn={() => {
        // your code
      }}
      onRequestAccess={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={async () => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `'401' \| '403' \| '503' \| 'loading'` | `'401'` | Which page: `401` sign in, `403` no access, `503` temporarily unavailable, `loading` still on its way. |
| `media` | `ReactNode` |  | The picture beside the text: your own node, or `null` for the plain page. Default: the status's miniature, playing the page's state. |
| `actions` | `ReactNode` |  | Replaces the page's buttons with your own. Default: the status's own actions. |
| `signInHref` | `string` | `'#sign-in'` | 401: where the sign-in page lives; 403: where Switch account goes. |
| `onSignIn` | `MouseEventHandler<HTMLAnchorElement>` |  | 401: runs when Sign in is pressed, before the link is followed. |
| `returnTo` | `string` | `'/settings/billing'` | 401: the page they return to, shown under the buttons. Empty hides it. |
| `permission` | `string` | `'billing:read'` | 403: the permission they lack, shown on the page. Empty hides it. |
| `account` | `string` | `'ana@northwind.io'` | 403: the account that's signed in, with Switch account beside it. Empty hides it. |
| `onRequestAccess` | `() => Promise<unknown> \| unknown` | `a short demo wait` | 403: ask for access; resolve when sent, reject with an Error whose message says why not. |
| `onRetry` | `() => Promise<unknown> \| unknown` | `a short demo wait that fails` | 503: try the request again; resolve when it worked, reject when it didn't. |
| `retryDelays` | `number[]` | ``[5, 15, 30, 60]`` | 503: seconds before each automatic retry, the last one repeating; `[]` retries only when asked. |
| `statusHref` | `string` | `'#status'` | 503: where the status page lives. |
| `homeHref` | `string` | `'#home'` | Where Back to home goes. |
| `progress` | `number` |  | Loading: how far along, 0 to 100. Default: unknown, so the bar sweeps. |
| `slowAfter` | `number` | `10000` | Loading: after this many ms, say it's slow and offer Reload; 0 never does. |
| `onReload` | `() => Promise<unknown> \| unknown` | `a short demo wait` | Loading: what Reload does once it's slow. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The headline's level. |
| `linkComponent` | `ElementType` | `'a'` | The element every link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<StatusScreenCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `theme` | `ThemeInput` |  | Default: the host's theme. |

**Strings:** `copy` takes `home`, `errorCode`, `unauthorizedTitle`, `unauthorizedDescription`, `signIn`, `returnHint`, `forbiddenTitle`, `forbiddenDescription`, `permissionLabel`, `requestAccess`, `requesting`, `requested`, `requestFailed`, `requestedHint`, `signedInAs`, `switchAccount`, `unavailableTitle`, `unavailableDescription`, `retry`, `retrying`, `backOnline`, `stillDown`, `statusPage`, `retryIn`, `retryHint`, `loadingTitle`, `loadingDescription`, `loadingLabel`, `loadingSlow`, `reload`.

### Unauthorized (401)

Ask for a sign-in, beside a parcel locker whose keypad waits for its code. Sign in goes to your sign-in page, and the line under the buttons says where the visitor comes back to.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Unauthorized (401), plain

The same page without the miniature (`media={null}`): the code set large over the headline.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Forbidden (403)

Explain that the visitor is signed in but not allowed, beside a firewall in lockdown. The page names the permission they lack and the account they're signed in with (Switch account beside it), asks an admin for access and says what happens next.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Forbidden (403), plain

The 403 without the miniature.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Not found (404)

Give visitors a way forward when a page has moved or never existed: a lighthouse sweeps the fog beside a search field, the way home and a few likely destinations.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-not-found
```

It brings `async-button`, `button`, `counter`, `field`, `icon-arrow-left`, `icon-arrow-right`, `icon-bookmark`, `icon-home`, `icon-message`, `icon-search`, `input`, `mesh-gradient`, `reveal`, `stagger`, `text-split`, `use-now`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { NotFound, type NotFoundProps } from '@/blocks/marketing/not-found'

export function NotFoundView({ destinations, homeCta }: Pick<NotFoundProps, 'destinations' | 'homeCta'>) {
  return (
    <NotFound
      destinations={destinations}
      homeCta={homeCta}
      copy={{ code: '404' }}
      linkComponent={Link}
      onSearch={async (query) => {
        // await your API here; the block shows progress until it settles
      }}
      onNotify={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
      onBack={() => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'not-found' \| 'coming-soon'` | `'not-found'` | `not-found`: the 404. `coming-soon`: a launch countdown with a notify-me form. |
| `media` | `ReactNode` |  | Not found: the picture beside the text: your own node, or `null` for the plain page. Default: a lighthouse sweeping the fog. |
| `onSearch` | `(query: string) => Promise<unknown> \| unknown` | `a short demo wait` | Not found: search the site; route to your results page, or reject with an Error whose message shows under the field. |
| `launch` | `Date \| number` |  | Coming soon: the launch time. Default: 12 days, 7 hours and 42 minutes after the page opens in the browser. |
| `onNotify` | `(email: string) => Promise<unknown> \| unknown` | `a short demo wait` | Coming soon: resolve once the address is on the list; reject with an Error whose message says why not. |
| `destinations` | `NotFoundDestination[]` |  | Not found: the cards under the 404; an empty array hides them. Default: Documentation, Changelog and Support. |
| `homeCta` | `NotFoundCta` |  | Not found: the way home. Default: Back to home → `#home`. |
| `onBack` | `() => void` | ``history.back()`` | Not found: what Go back does. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page heading's level. |
| `linkComponent` | `LinkComponent` | `'a'` | The element every internal link renders as, e.g. Next.js `Link`. |
| `copy` | `Partial<NotFoundCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `code`, `errorCode`, `title`, `description`, `searchLabel`, `searchPlaceholder`, `search`, `back`, `destinationsLabel`, `docsTitle`, `docsDescription`, `changelogTitle`, `changelogDescription`, `supportTitle`, `supportDescription`, `home`, `eyebrow`, `comingTitle`, `comingDescription`, `countdownLabel`, `days`, `hours`, `minutes`, `seconds`, `notifyLabel`, `emailLabel`, `placeholder`, `notify`, `notifying`, `notified`, `retry`, `notifyHint`, `invalidEmail`, `notifyFailed`.

### Not found (404), plain

The 404 without the miniature: its digits rise out of their masks.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-not-found
```

```tsx
'use client'

import Link from 'next/link'
import { NotFound, type NotFoundProps } from '@/blocks/marketing/not-found'

**Props**

### Server error (500)

Apologize plainly when the server fails. The mainframe stands in machine check; Try again resets it and feeds its cards, and it runs again once the retry works. The status page, each service's state and the incident ID to copy for support sit under it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

It brings `async-button`, `badge`, `button`, `countdown`, `counter`, `field`, `icon-arrow-right`, `icon-check`, `icon-circle-dashed`, `icon-copy`, `icon-external-link`, `icon-loader-ring`, `icon-refresh`, `input`, `progress`, `reveal`, `stagger`, `text-split`, `use-now`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

export function ErrorScreenView({ services, steps }: Pick<ErrorScreenProps, 'services' | 'steps'>) {
  return (
    <ErrorScreen
      services={services}
      steps={steps}
      copy={{ statusPage: 'Status page' }}
      linkComponent={Link}
      onRetry={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onSubscribe={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
      onRedeem={async (code) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'500' \| 'maintenance' \| 'launch'` | `'500'` | `500` for an unexpected server error; `maintenance` for a planned window; `launch` for the page before you open. |
| `media` | `ReactNode` |  | The picture beside the text: your own node, or `null` for the plain page. Default: the page's miniature (a mainframe, a repair bench, a drone dock), playing its state. |
| `incidentId` | `string` | `'inc_7Hq2Kx9mWp'` | 500: the ID support can trace. |
| `onRetry` | `() => Promise<unknown> \| unknown` | `a short demo wait` | 500: try the request again; resolve when it worked, reject when it didn't (its message shows under the buttons). |
| `services` | `ErrorScreenService[]` | `four demo services` | 500: the services on the status card, with their state. |
| `supportHref` | `string` | `'#support'` | 500: where Contact support goes, beside the incident ID. |
| `window` | `{ start: number; end: number }` |  | Maintenance: the window, in ms since the epoch. Default: began 38 minutes before `now`, ends 52 minutes after. |
| `steps` | `ErrorScreenStep[]` | `the demo's database upgrade` | Maintenance: the window's steps and where each stands. |
| `onSubscribe` | `(email: string) => Promise<unknown> \| unknown` | `a short demo wait` | Maintenance: email them when it's back; resolve once they're on the list, reject with an Error whose message says why not. |
| `launchAt` | `Date \| number \| string` |  | Launch: when it opens, as a Date, ms since the epoch or an ISO string. Default: 6 days and 4 hours after `now`. |
| `now` | `Date \| number` |  | The time the demo window and launch are set from. Only the browser renders anything timed, so this never mismatches on hydration. Default: the time of the first render. |
| `brand` | `ErrorScreenBrand \| ReactNode` |  | Launch: the product above the headline, as `{ name, logo }` or your own node. |
| `title` | `ReactNode` |  | Launch: the headline and the line under it. Default: `copy.launchTitle` and `copy.launchDescription`. |
| `description` | `ReactNode` |  |  |
| `onRedeem` | `(code: string) => Promise<unknown> \| unknown` |  | Launch: check an early-access code; resolve to let them in, reject with a message when it's wrong. Default: a demo that accepts `EARLY`. |
| `codeForm` | `ReactNode` |  | Launch: your own code form in place of the built-in one, e.g. a plain form that posts to your server. |
| `statusHref` | `string` | `'#status'` | Where the status page lives. |
| `linkComponent` | `LinkComponent` | `'a'` | What the status and support links render as, e.g. Next.js `Link`. |
| `copy` | `Partial<ErrorScreenCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `locale` | `string` |  | The locale times read in. Default: the app's (YoujProvider), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The headline's level; the status card's heading sits one under it. |
| `theme` | `ThemeInput` |  | Default: the host's theme. |

**Strings:** `copy` takes `statusPage`, `errorCode`, `code`, `serverTitle`, `serverDescription`, `retry`, `retrying`, `backOnline`, `stillDown`, `currentStatus`, `updated`, `serviceStates`, `incident`, `copyIdLabel`, `copyId`, `copied`, `copyFailed`, `contactSupport`, `maintenanceBadge`, `timeLeft`, `backIn`, `maintenanceTitle`, `maintenanceDescription`, `started`, `backBy`, `progress`, `stepStates`, `subscribeLabel`, `emailPlaceholder`, `subscribe`, `subscribing`, `subscribed`, `subscribeRetry`, `invalidEmail`, `subscribeFailed`, `launchTitle`, `launchDescription`, `launching`, `live`, `opens`, `opened`, `codeLabel`, `codePlaceholder`, `getIn`, `admitted`, `codeFailed`.

### Server error (500), plain

The 500 without the miniature: the code set large.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

**Props**

### Service unavailable (503), plain

The 503 without the miniature.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Maintenance

Announce a planned window: the time left, how far along it is and each step, a field to be emailed when it's back, and a repair bench whose checklist lights up as the window passes. Its beacon turns green when the window ends.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

**Props**

### Maintenance, plain

Maintenance without the miniature.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

**Props**

### Loading

Hold the page while it loads. The hourglass's sand is the progress (it turns over on its own while that's unknown), a polite live region says what is happening, and past `slowAfter` the page offers a reload.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Loading, plain

Loading without the miniature: the headline over a progress bar that sweeps until you pass `progress`.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-status-screen
```

```tsx
'use client'

import Link from 'next/link'
import { StatusScreen, type StatusScreenProps } from '@/blocks/app/status-screen'

**Props**

### Launch countdown

The page before a launch: the time left in rolling digits and a field for early-access codes, beside a drone charging on its pad that takes off when the countdown reaches zero. The demo accepts `EARLY`.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

**Props**

### Launch countdown, plain

The launch countdown without the miniature.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-error
```

```tsx
'use client'

import Link from 'next/link'
import { ErrorScreen, type ErrorScreenProps } from '@/blocks/app/error'

**Props**

### Tracking

Let people look up an order, request or incident by its reference and see where it stands, step by step, with when each step happened and what comes next. The packaging line beside it fills its pallet as the order moves through its steps and wraps it once it's delivered.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-request-tracking
```

It brings `async-button`, `badge`, `field`, `icon-check`, `icon-circle-alert`, `icon-clock`, `icon-search`, `input`, `reveal`, `stagger`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RequestTracking } from '@/blocks/app/request-tracking'

export function RequestTrackingView() {
  return (
    <RequestTracking
      copy={{ title: 'Track your order' }}
      onTrack={async (reference) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `result` | `TrackingResult \| null` | `an order being packed` | The request shown first; `null` starts on the bare lookup. |
| `onTrack` | `(reference: string) => Promise<TrackingResult> \| TrackingResult` | `any `ORD-…` reference finds the sample order` | Find a request by its reference; resolve to it, or reject with an Error whose message says why not. |
| `defaultReference` | `string` |  | The reference in the field to begin with. Default: the shown request's. |
| `media` | `ReactNode` |  | The picture beside the request: your own node, or `null` for the plain page. Default: a packaging line that follows the request's steps. |
| `timeZone` | `string` | `'UTC'` | The time zone times read in (IANA, e.g. `Europe/Berlin`). |
| `locale` | `string` |  | The locale times read in. Default: the app's (YoujProvider), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The page heading's level. |
| `copy` | `Partial<RequestTrackingCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `theme` | `ThemeInput` |  | Default: the host's theme. |

**Strings:** `copy` takes `title`, `description`, `lookupLabel`, `referenceLabel`, `placeholder`, `referenceHint`, `track`, `tracking`, `tracked`, `retry`, `emptyReference`, `notFound`, `resultLabel`, `stepsLabel`, `expected`, `found`, `states`.

### Tracking, plain

Tracking without the miniature.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-request-tracking
```

It brings `async-button`, `badge`, `field`, `icon-check`, `icon-circle-alert`, `icon-clock`, `icon-search`, `input`, `reveal`, `stagger`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RequestTracking } from '@/blocks/app/request-tracking'

**Props**

### Public status

Keep your customers informed with a public status page for the same services, their uptime and incident updates. It has no miniature: people scan it for one answer, so the answer leads.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-public-status
```

It brings `alert`, `app-status`, `async-button`, `badge`, `button`, `card`, `collapsible`, `counter`, `field`, `history-strip`, `icon-activity`, `icon-alert-triangle`, `icon-bell`, `icon-check-circle`, `icon-circle-x`, `icon-copy`, `icon-rss`, `icon-search`, `icon-webhook`, `input`, `input-group`, `popover`, `reveal`, `skeleton`, `sparkline`, `tabs`, `timeline`, `toggle-group`, `tooltip`, `use-controllable-state`, `use-now`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { PublicStatus, type PublicStatusProps } from '@/blocks/app/public-status'

export function PublicStatusView({ services, groups, responseTimes, range }: Pick<PublicStatusProps, 'services' | 'groups' | 'responseTimes' | 'range'>) {
  return (
    <PublicStatus
      services={services}
      groups={groups}
      responseTimes={responseTimes}
      range={range}
      copy={{ product: 'Status' }}
      linkComponent={Link}
      onRangeChange={(range) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
      onSubscribe={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `incident` | `boolean \| PublicStatusIncident` | `false` | The open incident the page leads with, or `true` for the demo one (storage failing uploads today). |
| `services` | `StatusService[]` | `the card's six demo services` | Each service with a day per entry, oldest first, the last today. |
| `groups` | `PublicStatusGroup[]` | `Platform and Data` | The page's sections, each naming its services by id; services no group names go under `copy.otherGroup`. |
| `responseTimes` | `Partial<Record<PublicStatusRange, number[]>>` |  | API response times per range, in ms, oldest first. Default: the demo's generated series. |
| `range` | `'24h' \| '7d' \| '30d'` |  | The response-time range shown (controlled). |
| `defaultRange` | `'24h' \| '7d' \| '30d'` | `'24h'` | The range shown first. |
| `onRangeChange` | `(range: PublicStatusRange) => void` |  | Called with the range the visitor picks. |
| `now` | `number` |  | The time the page is rendered at, in ms, which the server and client agree on; the incident's age counts from it. Default: the browser's clock once mounted (a fixed demo time before, so hydration matches). |
| `loading` | `boolean` | `false` | Shows skeletons in place of the services and response times while your data loads. |
| `error` | `ReactNode` |  | Shown in place of the services when they fail to load, with a retry button when `onRetry` is set. Default: none. |
| `onRetry` | `() => void` |  | Retries loading after an `error`. Default: none. |
| `empty` | `ReactNode` | ``copy.emptyServices`` | Replaces the empty-services message. |
| `copy` | `Partial<PublicStatusCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the demo's English strings. |
| `locale` | `string` |  | Formats dates and numbers. Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Orbit and its ring` | The product the page is for: its name, and a mark before it. |
| `feedUrl` | `string` | `'https://status.orbit.dev/feed.rss'` | The RSS feed's address, in the Subscribe popover. |
| `onSubscribe` | `(email: string) => Promise<unknown> \| unknown` |  | Subscribes an email address; resolve when done, throw to show the error. Default: a short demo wait. |
| `onSaveWebhook` | `(url: string) => Promise<unknown> \| unknown` |  | Saves a webhook endpoint; resolve when done. Default: a short demo wait. |
| `historyHref` | `string` | `'#'` | Where the footer's incident-history link goes. |
| `linkComponent` | `ElementType` | `'a'` | Renders the page's internal links, e.g. Next.js `Link`. |

**Strings:** `copy` takes `product`, `heading`, `operational`, `partial`, `operationalDetail`, `degradedDetail`, `updated`, `affects`, `started`, `incidentUpdates`, `updateTypes`, `services`, `legend`, `otherGroup`, `status`, `stripLabel`, `uptime`, `loading`, `emptyServices`, `retry`, `responseTitle`, `responseDescription`, `responseLabel`, `ranges`, `range`, `ms`, `noResponseTimes`, `pastIncidents`, `resolvedCount`, `affected`, `lasted`, `disruption`, `noPastIncidents`, `footer`, `history`, `subscribe`, `subscribeBy`, `email`, `rss`, `webhook`, `emailPlaceholder`, `emailHint`, `subscribing`, `subscribed`, `invalidEmail`, `failed`, `subscribeToUpdates`, `feedUrl`, `copyFeed`, `copied`, `feedHint`, `endpoint`, `endpointPlaceholder`, `webhookHint`, `saveWebhook`, `webhookSaved`, `webhookFailed`.

### Waitlist

Build interest before launch with a waitlist page, a countdown and a referral link. The demo shows your place in line after you join.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add marketing-waitlist
```

It brings `async-button`, `avatar-stack`, `badge`, `button`, `content-swap`, `countdown`, `counter`, `field`, `icon-aperture`, `icon-arrow-right`, `icon-check`, `icon-copy`, `icon-mail`, `icon-share`, `icon-sparkles`, `input`, `morph-label`, `skeleton`, `text-split`, `use-visible`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Waitlist, type WaitlistProps } from '@/blocks/marketing/waitlist'

export function WaitlistView({ brand, people }: Pick<WaitlistProps, 'brand' | 'people'>) {
  return (
    <Waitlist
      brand={brand}
      people={people}
      copy={{ badge: 'Private beta · opens this winter' }}
      linkComponent={Link}
      onJoin={async (email) => {
        // await your API here; the block shows progress until it settles
      }}
      onShare={(method, link) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `brand` | `WaitlistBrand` |  | The product's name and logo in the header. Default: Aperture. |
| `cta` | `WaitlistCta \| null` | `"Read the manifesto"` | The header's link; `null` hides it. |
| `launchAt` | `Date \| number` |  | The launch moment the countdown runs to. Default: 23 days and some hours after the page opens. |
| `onJoin` | `(email: string) => Promise<WaitlistPlace \| void> \| WaitlistPlace \| void` |  | Adds the email to the list. Resolve with the visitor's place (or nothing, for the demo's); reject to explain under the field. Default: a short demo wait. |
| `onShare` | `(method: 'share' \| 'email', link: string) => void` |  | Called when the visitor shares their referral link. Default: the demo moves them up 100 places. |
| `defaultValues` | `{ email?: string }` |  | The values the form starts with. Default: empty. |
| `people` | `WaitlistPerson[]` |  | Faces in the avatar stack. Default: the demo's six. |
| `waitingCount` | `number` |  | How many people are waiting. Default 4,812. |
| `live` | `boolean` | `true` | Ticks the waiting count up now and then, as people join. |
| `locale` | `string` |  | BCP 47 locale for the numbers. Default: the app's (YoujProvider's `locale`), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The headline's level. |
| `copy` | `Partial<WaitlistCopy>` |  | Any of the page's strings, to rewrite or translate. |
| `linkComponent` | `LinkComponent` | ``'a'`` | Renders the header link, e.g. Next.js `Link`. |

**Strings:** `copy` takes `badge`, `title`, `description`, `timerLabel`, `days`, `hours`, `minutes`, `seconds`, `emailLabel`, `emailPlaceholder`, `emailInvalid`, `joinFailed`, `join`, `joining`, `joined`, `joinError`, `placeLabel`, `saving`, `placeIntro`, `shareHint`, `copyLink`, `copied`, `share`, `emailFriend`, `waitingLabel`, `waiting`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Every screen is a `main` with one heading (an `h1` by default; set `headingLevel` where the page around it needs another). The miniatures are decoration: each is a still, unfocusable picture (`interactive={false}`) inside an `aria-hidden` stage, so the headline, the text and the live regions carry the meaning, and each follows reduced motion, showing its states at once. The status code is read as plain text: a small line over the headline beside a miniature, set large on the plain page.

Status screen's loading state sets `aria-busy` on the page and announces its headline through a `status` region; its progress bar is a labelled `progressbar`, with no value while the wait is unknown, and the line that offers a reload is a `status` as well. The 503's automatic retries run through its Try now button, so each attempt and its outcome are announced (Retrying…, Still down, Back online); the countdown to the next one is plain text, never read out every second. After a 403 request, the line saying what happens next is a `status`. The 404's search is a `search` landmark with a labelled field. Request tracking announces a found request politely, lists the steps as an ordered list with the current one marked `aria-current="step"` and each step's state spelled out for screen readers, and shows lookup errors under the field (`aria-describedby`).

Actions that wait on a server (Try again, Try now, Request access, Notify me, Track) are Buttons with `onAction` or a `status`: they show progress and the result in text as well as motion. Links and buttons are real `a` and `button` elements with the kit's focus ring. Everything animated stands still under reduced motion.

---

# Surveys

> Both sides of a survey: the builder where it's written, branched, styled and published, and the ways people answer it (one question at a time, a single page, a deck of cards for the phone, a widget in your product), all from one survey definition, with its results at a glance.

Source: https://www.youj.dev/docs/blocks/surveys

## Blocks

### Builder

The admin's side. The outline holds every question in order: drag a row by its grip, or Tab to the grips and move one with Space and the arrows. Add question opens a palette of fourteen kinds, from single and multiple choice to NPS, a star rating, faces, a slider, a matrix and a ranking, and the new one lands after the selected question. The middle edits it in place: its kind, its words, its answers (paste a list to make options), whether it's required, and show-if logic on earlier answers. The preview beside it is the real question on a phone or a desktop, in the survey's design. Every change is a step of ⌘Z and saves itself a beat later. Publish picks a link, an embed or in-app (with its audience and the share of it asked), when it opens and closes, and ends on the live link with a share card. Keep the survey with `value` and `onValueChange` or `onSave`, publish through `onPublish`.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-builder
```

It brings `async-button`, `badge`, `button`, `dialog`, `dropdown-menu`, `empty`, `field`, `icon-align-left`, `icon-arrow-down`, `icon-arrow-left`, `icon-arrow-up`, `icon-at-sign`, `icon-calendar`, `icon-check`, `icon-chevron-left`, `icon-circle-alert`, `icon-circle-dot`, `icon-cloud-off`, `icon-code`, `icon-copy`, `icon-copy-plus`, `icon-external-link`, `icon-flag`, `icon-gauge`, `icon-git-branch`, `icon-hash`, `icon-layout-grid`, `icon-link`, `icon-list-ordered`, `icon-monitor`, `icon-more-horizontal`, `icon-palette`, `icon-panel-bottom`, `icon-play`, `icon-plus`, `icon-redo`, `icon-rocket`, `icon-sliders`, `icon-smartphone`, `icon-smile`, `icon-square-check`, `icon-star`, `icon-thumbs-up`, `icon-trash`, `icon-type`, `icon-undo`, `icon-x`, `input`, `input-group`, `kbd`, `morph-label`, `number-input`, `popover`, `presence-list`, `progress`, `radio-group`, `segmented-control`, `select`, `slider`, `sortable-list`, `spinner`, `surveys-conversational`, `surveys-deck`, `surveys-form`, `surveys-question`, `switch`, `textarea`, `toast`, `tooltip`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyBuilder, type SurveyBuilderProps } from '@/blocks/surveys/builder'

export function SurveyBuilderView({ value, segments }: Pick<SurveyBuilderProps, 'value' | 'segments'>) {
  return (
    <SurveyBuilder
      value={value}
      segments={segments}
      copy={{ surveys: 'Surveys' }}
      onValueChange={(survey) => {
        // your code
      }}
      onSelectedChange={(id) => {
        // your code
      }}
      onSave={async (survey) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | Hosted inside another page: a panel of fixed height instead of the whole screen. |
| `copy` | `Partial<SurveyBuilderCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats the reach and dates (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `value` | `Survey` |  | The survey being built, controlled: pair it with `onValueChange`. |
| `defaultValue` | `Survey` | `Tern's product survey` | The survey to start from, when the block owns it. |
| `onValueChange` | `(survey: Survey) => void` |  | Called with the survey on every change. |
| `selected` | `string` |  | The question being edited (its id, or `'ending'`), controlled: pair it with `onSelectedChange`, to give each question a route. |
| `defaultSelected` | `string` |  | The question selected at first, when the block owns it. Default: the first. |
| `onSelectedChange` | `(id: string) => void` |  | Called when another question is selected. |
| `onSave` | `(survey: Survey) => Promise<unknown> \| unknown` |  | Saves the survey, a beat after the last change; reject to show "Couldn’t save" with Retry. Default: a short demo wait. |
| `onPublish` | `(deployment: SurveyDeployment) => Promise<SurveyPublished \| void> \| SurveyPublished \| void` |  | Publishes it; resolve with its `url` to show that link. Reject to stay on the step and say why. Default: a demo wait and a demo link. |
| `segments` | `SurveySegment[]` | `the demo product's four` | The groups an in-app survey can be shown to. |
| `publishedUrl` | `string` |  | Starts already published at this link (to edit a live survey). Default: a draft. |
| `qrCode` | `(url: string) => ReactNode` |  | A real QR code for the share card, from your QR library. Default: QR-like art. |

**Strings:** `copy` takes `surveys`, `titleLabel`, `draft`, `live`, `scheduled`, `changes`, `saving`, `saved`, `saveFailed`, `retry`, `undo`, `redo`, `undone`, `redone`, `design`, `preview`, `test`, `publish`, `publishChanges`, `share`, `more`, `questions`, `questionCount`, `addQuestion`, `ending`, `endingHint`, `untitled`, `rowLabel`, `hasLogic`, `backToQuestions`, `groups`, `kinds`, `hints`, `starters`, `option`, `row`, `matrixColumns`, `scaleLow`, `scaleHigh`, `questionOf`, `type`, `title`, `titlePlaceholder`, `description`, `descriptionPlaceholder`, `answers`, `options`, `rows`, `columns`, `addOption`, `addRow`, `addColumn`, `pasteHint`, `optionLabel`, `removeOption`, `reorderOption`, `settings`, `required`, `requiredHint`, `multipleAnswers`, `maxAnswers`, `noLimit`, `otherOption`, `otherHint`, `randomize`, `randomizeHint`, `longAnswer`, `maxLength`, `placeholder`, `from`, `to`, `step`, `unit`, `unitPlaceholder`, `stars`, `faces`, `lowLabel`, `highLabel`, `yesLabel`, `noLabel`, `logic`, `show`, `always`, `when`, `matchAll`, `matchAny`, `addCondition`, `removeCondition`, `conditionQuestion`, `conditionOp`, `conditionValue`, `noEarlier`, `later`, `ops`, `duplicate`, `moveUp`, `moveDown`, `delete`, `deleted`, `endingTitle`, `endingDescription`, `emptyTitle`, `emptyDescription`, `previewLabel`, `ok`, `respondent`, `desktop`, `phone`, `device`, `testTitle`, `testDescription`, `layout`, `layouts`, `designTitle`, `accent`, `accentInherit`, `accentLabel`, `corners`, `cornerNames`, `font`, `fontNames`, `publishTitle`, `publishDescription`, `stepWhere`, `stepWhen`, `channel`, `channels`, `channelHints`, `address`, `linkBase`, `audience`, `audiences`, `segment`, `sample`, `reach`, `trigger`, `triggers`, `once`, `start`, `startNow`, `startLater`, `startAt`, `close`, `closeNever`, `closeDate`, `closeResponses`, `closeDateLabel`, `responsesLabel`, `back`, `continue`, `publishing`, `published`, `publishFailed`, `liveTitle`, `scheduledTitle`, `liveDescriptions`, `link`, `copyLink`, `copied`, `openLink`, `shareCard`, `shareCardHint`, `embedCode`, `copyCode`, `done`.

### Conversational

One question at a time, as fast as the keyboard: a letter picks a choice, a digit a point on a scale or a face, Y or N answers yes or no, and Enter goes on. A pick on a single-answer question goes on by itself after a beat. It opens on a welcome, each question fills the screen in large type, and the bar at the top counts only the questions this person's answers lead to. It ends on a review of every answer, each with an Edit that comes back to the review, then the thanks. On a phone the action sits at the foot of the screen, in the thumb's reach.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-conversational
```

It brings `async-button`, `button`, `icon-arrow-left`, `icon-arrow-right`, `icon-check`, `icon-chevron-down`, `icon-chevron-up`, `icon-clock`, `icon-corner-down-left`, `kbd`, `progress`, `surveys-question`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { ConversationalSurvey, type ConversationalSurveyProps } from '@/blocks/surveys/conversational'

export function ConversationalSurveyView({ survey, value }: Pick<ConversationalSurveyProps, 'survey' | 'value'>) {
  return (
    <ConversationalSurvey
      survey={survey}
      value={value}
      copy={{ progress: 'Progress' }}
      onValueChange={(answers) => {
        // your code
      }}
      onSubmit={async (answers) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | Hosted inside another page: a card with an `h2` (each question an `h3`) instead of the whole screen. |
| `fill` | `boolean` | `false` | Take the whole width it's given, embedded, instead of stopping at its natural width (640px at 100% scale). |
| `copy` | `Partial<ConversationalSurveyCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats answers in the review (lists, dates) (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `survey` | `Survey` | `Tern's product survey` | The survey: its questions, logic, ending and design. |
| `value` | `SurveyAnswers` |  | The answers, controlled: pair it with `onValueChange` (to save progress and resume it). |
| `defaultValue` | `SurveyAnswers` |  | The answers to start from, when the block owns them. A survey resumed with answers skips the welcome. |
| `onValueChange` | `(answers: SurveyAnswers) => void` |  | Called with every answer as it changes. |
| `onSubmit` | `(answers: SurveyAnswers) => Promise<unknown> \| unknown` |  | Sends the answers to the questions that were asked; reject to keep them and say so. Default: a short demo wait. |
| `welcome` | `boolean` | `true` | Open on a welcome with the title and how long it takes. |
| `review` | `boolean` | `true` | End on a review of every answer before sending. |
| `autoAdvance` | `boolean` | `true` | A single pick goes on by itself after a beat. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tern` | The product, at the top of the page. |
| `seed` | `string` |  | A respondent's id, so randomized options keep their order across visits. |

**Strings:** `copy` takes `position`, `questionLabel`, `progress`, `length`, `start`, `back`, `navigate`, `previous`, `next`, `ok`, `skip`, `toReview`, `backToReview`, `pressEnter`, `pressModEnter`, `reviewTitle`, `reviewDescription`, `edit`, `editLabel`, `send`, `sending`, `sent`, `failed`, `failedTitle`, `failedDescription`, `again`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `pick`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`, `doneTitle`, `doneDescription`.

### Single page

Every question on one page, numbered, the way people fill in a form they can see the end of. A question an answer reveals rises into its place and the rest are renumbered; the header counts what's answered. Enter moves on to the next question. Send checks every answer, says each problem under its question and gathers them in a summary at the top that takes focus and links to each one. The questions scroll under a header that stays, so the page never jumps.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-form
```

It brings `async-button`, `button`, `presence-list`, `progress`, `surveys-conversational`, `surveys-question`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyForm, type SurveyFormProps } from '@/blocks/surveys/form'

export function SurveyFormView({ survey, value }: Pick<SurveyFormProps, 'survey' | 'value'>) {
  return (
    <SurveyForm
      survey={survey}
      value={value}
      copy={{ pick: 'Choose an answer.' }}
      onValueChange={(answers) => {
        // your code
      }}
      onSubmit={async (answers) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `pick`, `progress`, `answered`, `problemsTitle`, `problemLink`, `send`, `sending`, `sent`, `failed`, `checkAnswers`, `failedTitle`, `failedDescription`, `again`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`, `doneTitle`, `doneDescription`.

### Card deck

For the phone in your hand: a deck of question cards with answers as large as a thumb, the cards still ahead peeking out below the one on top. Throw the card towards the reading start to go on and the other way to go back, or use the two buttons where the thumb rests. A throw that can't go on springs back and shakes, and the reason is said under the question. Progress fills in segments along the top, one per question this person will be asked.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-deck
```

It brings `async-button`, `button`, `icon-arrow-left`, `icon-arrow-right`, `icon-clock`, `surveys-conversational`, `surveys-question`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyDeck, type SurveyDeckProps } from '@/blocks/surveys/deck'

export function SurveyDeckView({ survey, value }: Pick<SurveyDeckProps, 'survey' | 'value'>) {
  return (
    <SurveyDeck
      survey={survey}
      value={value}
      copy={{ pick: 'Choose an answer to go on.' }}
      onValueChange={(answers) => {
        // your code
      }}
      onSubmit={async (answers) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `pick`, `position`, `questionLabel`, `progress`, `length`, `start`, `back`, `next`, `skip`, `send`, `sending`, `sent`, `failed`, `failedTitle`, `failedDescription`, `swipeHint`, `again`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`, `doneTitle`, `doneDescription`.

### In-app widget

A short survey in a corner of your product, the way in-app research asks: it rises in without taking focus, asks one question at a time and keeps one size while it does, and thanks you in place. Minimize folds it into a pill that remembers where you were; × and Escape dismiss it and the app hears it through `onOpenChange`. On a phone it's a sheet along the bottom edge.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-widget
```

It brings `async-button`, `button`, `card`, `icon-arrow-left`, `icon-chevron-down`, `icon-chevron-up`, `icon-x`, `progress`, `surveys-question`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyWidget, type SurveyWidgetProps } from '@/blocks/surveys/widget'

export function SurveyWidgetView({ survey, value }: Pick<SurveyWidgetProps, 'survey' | 'value'>) {
  return (
    <SurveyWidget
      survey={survey}
      value={value}
      copy={{ pick: 'Choose an answer.' }}
      onValueChange={(answers) => {
        // your code
      }}
      onSubmit={async (answers) => {
        // await your API here; the block shows progress until it settles
      }}
      onOpenChange={(open) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `false` | In the flow of the page (a preview, a settings page) instead of floating in its corner. |
| `fill` | `boolean` | `false` | Take the whole width it's given, embedded, instead of its natural width (352px at 100% scale). |
| `children` | `ReactNode` |  | Your page, behind the widget. Default: none, so the widget floats over whatever is on screen. |
| `copy` | `Partial<SurveyWidgetCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats answers (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `survey` | `Survey` | `an NPS pulse whose follow-up depends on the score` | The survey: a short one. |
| `value` | `SurveyAnswers` |  |  |
| `defaultValue` | `SurveyAnswers` |  |  |
| `onValueChange` | `(answers: SurveyAnswers) => void` |  |  |
| `onSubmit` | `(answers: SurveyAnswers) => Promise<unknown> \| unknown` |  | Sends the answers; reject to keep them and say so. Default: a short demo wait. |
| `open` | `boolean` |  | Whether it's showing, controlled: pair it with `onOpenChange`. |
| `defaultOpen` | `boolean` | `true` | Showing at first, when the block owns it. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when × or Escape dismisses it, or the thanks is closed. |
| `defaultMinimized` | `boolean` | `false` | Starts folded into its pill. |
| `delay` | `number` | `0` | Waits this many milliseconds after mounting before it rises in. |
| `side` | `'start' \| 'end'` | `'end'` | The corner it floats in. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tern` | The product, at the top of the card. |
| `seed` | `string` |  |  |

**Strings:** `copy` takes `pick`, `position`, `questionLabel`, `progress`, `minimize`, `expand`, `close`, `back`, `next`, `skip`, `send`, `sending`, `sent`, `failed`, `failedTitle`, `failedDescription`, `dismiss`, `reviewTitle`, `reviewDescription`, `edit`, `editLabel`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`, `doneTitle`, `doneDescription`.

### Results

What a survey heard: responses, completion and the median time, then any question's answers in the shape its type calls for, bars for choices and ratings, the average place for a ranking, NPS as its score over the split of detractors, passives and promoters, with every score drawn out. It's computed from the raw responses, so pass them as they're stored; moving between questions keeps the card's size.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-results
```

It brings `badge`, `card`, `counter`, `empty`, `select`, `skeleton`, `surveys-question`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyResults, type SurveyResultsProps } from '@/blocks/surveys/results'

export function SurveyResultsView({ survey, responses }: Pick<SurveyResultsProps, 'survey' | 'responses'>) {
  return (
    <SurveyResults
      survey={survey}
      responses={responses}
      copy={{ title: 'Results' }}
      onQuestionChange={(id) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | The card alone, its title an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of its natural width (576px at 100% scale). |
| `copy` | `Partial<SurveyResultsCopy>` |  |  |
| `locale` | `string` |  | Formats counts and shares (BCP 47). Default: the app's locale (YoujProvider), else en-US. |
| `survey` | `Survey` | `Tern's product survey` | The survey the responses answer. |
| `responses` | `SurveyResponse[]` |  | Every response, as stored. Default: 312 demo responses. |
| `question` | `string` |  | The question shown (its id), controlled: pair it with `onQuestionChange`. |
| `defaultQuestion` | `string` |  | The question shown at first, when the block owns it. Default: the NPS question, else the first. |
| `onQuestionChange` | `(id: string) => void` |  |  |
| `loading` | `boolean` | `false` | Responses are on their way: the card keeps its shape with placeholders. |

**Strings:** `copy` takes `title`, `live`, `responses`, `completion`, `time`, `duration`, `question`, `answeredBy`, `promoters`, `passives`, `detractors`, `npsLabel`, `average`, `range`, `amount`, `points`, `latest`, `noAnswers`, `emptyTitle`, `emptyDescription`, `loading`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `pick`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`, `doneTitle`, `doneDescription`.

### Question

One question anywhere: a rating under an article, a poll, a check-in after a chat, in any of the fourteen kinds. A pick that needs nothing more sends itself and the thanks takes its place. Its folder is the kit the other blocks share: the survey definition and its show-if logic, validation, and the question renderers, so a survey answers the same way in every layout.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add surveys-question
```

It brings `alert`, `async-button`, `button`, `card`, `checkbox`, `collapse`, `date-picker`, `field`, `icon-check`, `icon-thumbs-down`, `icon-thumbs-up`, `input`, `kbd`, `radio-group`, `rating`, `segmented-control`, `slider`, `sortable-list`, `textarea`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { SurveyQuestionCard, type SurveyQuestionCardProps } from '@/blocks/surveys/question'

export function SurveyQuestionCardView({ question, value, design }: Pick<SurveyQuestionCardProps, 'question' | 'value' | 'design'>) {
  return (
    <SurveyQuestionCard
      question={question}
      value={value}
      design={design}
      copy={{ send: 'Send' }}
      onValueChange={(answer) => {
        // your code
      }}
      onSubmit={async (answer) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | The card alone, its title an `h2`. |
| `fill` | `boolean` | `false` | Take the whole width it's given instead of stopping at its natural width (448px at 100% scale). |
| `question` | `SurveyQuestion` | `how an article was, on five faces` | The question. |
| `value` | `SurveyAnswer` |  | The answer, controlled: pair it with `onValueChange`. |
| `defaultValue` | `SurveyAnswer` |  | The answer to start from, when the block owns it. |
| `onValueChange` | `(answer: SurveyAnswer \| undefined) => void` |  | Called with the answer as it changes. |
| `onSubmit` | `(answer: SurveyAnswer) => Promise<unknown> \| unknown` |  | Sends the answer; reject to keep it and say so. Default: a short demo wait. |
| `autoSubmit` | `boolean` | `true` | A pick that needs nothing more sends itself. |
| `design` | `SurveyDesign` |  | The survey's design (an accent, corners, a typeface) to wear. Default: the app's look. |
| `seed` | `string` |  | A respondent's id, so a randomized question's options keep their order. |
| `copy` | `Partial<SurveyQuestionCardCopy>` |  | Any of the block's strings, to rewrite or translate. |

**Strings:** `copy` takes `send`, `sending`, `sent`, `failed`, `failedDescription`, `doneTitle`, `doneDescription`, `change`, `other`, `otherPlaceholder`, `textPlaceholder`, `emailPlaceholder`, `scaleEnds`, `npsLabels`, `upTo`, `yes`, `no`, `faces`, `ratingUnit`, `ratingValue`, `sliderValue`, `sliderHint`, `rankHint`, `rankKeep`, `ranked`, `matrixAnswer`, `required`, `pick`, `tooMany`, `otherMissing`, `tooLong`, `emailInvalid`, `matrixRows`, `rankMissing`, `optional`, `skipped`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### The survey definition

Every block here reads the same `Survey`: a title, a description, its `questions`, an `ending` and an optional `design`. It's plain data, so it can be stored as JSON and sent anywhere. A question has an `id`, a `type` and a `title`, may be optional (`required: false`) and may carry `showIf`: conditions on earlier answers (`is`, `isNot`, `includes`, `excludes`, `lte`, `gte`, `answered`, `skipped`), matched all or any. A condition only reads a question that comes earlier and was itself asked, so the count and the progress always follow this person's path. The types are `choice` (single or `multiple`, with `max`, `other` and `randomize`), `text` (short or `long`, with `maxLength`), `email`, `nps`, `scale`, `rating`, `emoji`, `slider`, `matrix`, `ranking`, `yesno` and `date`. Answers are keyed by question id: an option's value, a list of them, a number, true or false, text, a date as `YYYY-MM-DD`, or a matrix's row → column.

### Keyboard

| Where | Keys | What they do |
| --- | --- | --- |
| A choice | A, B, C… | Pick an option (toggle it in a multiple choice); the next letter is “Other” |
| A scale, NPS or faces | 0–9 | Pick a point; 1 then 0 is ten |
| Yes or no | Y, N | Answer |
| Any question | Enter | Go on (in Single page, move to the next question) |
| A long answer | ⌘/Ctrl + Enter | Go on |
| A ranking or the outline | Space, ↑ ↓, Space | Pick a row up, move it, drop it (Esc puts it back) |
| An option in the builder | Enter, Backspace | Add the next option; remove an empty one |
| The builder | ⌘/Ctrl + Z, ⇧⌘/Ctrl + Z | Undo, redo (outside a text field) |
| The widget | Esc | Dismiss it |

### Accessibility

Each question is named by its title and described by its description and its problem: a choice is a radio group or a group of checkboxes, a scale and the faces are radio groups, each matrix row is a radio group named by its statement, a ranking is a sortable list, and a slider says its value with its unit. Shortcuts only work while focus is on the question's answers, never in a text field or with a modifier key, and arrow keys move a pick without going on. Focus moves to each new question (its field, or its heading) and a polite status says which question it is; the review's Edit buttons name the question they change. Single page's summary takes focus and links to each problem. The deck's throws have buttons beside them, and the widget never takes focus when it appears.

In the builder every reorder has a keyboard twin with each step announced, every icon button is named (with its shortcut in a tooltip), undo and redo are announced, a deleted question offers Undo in a toast, and the publish steps are labelled with focus moved into each. Under reduced motion questions and steps swap in place, the deck's cards cross-fade, the widget appears and folds without travelling, and the results are drawn at their values.

---

# Tables

> Table screens for any list of records: customers and a virtualized orders grid.

Source: https://www.youj.dev/docs/blocks/tables

## Blocks

### Customers

Browse every customer account with health, revenue, seats, usage trends and owners in one grid, then assign, tag or archive them in bulk.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-customers
```

It brings `app-page`, `async-button`, `avatar`, `badge`, `button`, `icon-archive`, `icon-arrow-up-right`, `icon-download`, `icon-mail`, `icon-plus`, `icon-tag`, `icon-upload`, `icon-user-plus`, `icon-users`, `reveal`, `sparkline`, `stat-card`, `tables-data-grid`, `toast`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { Customers, type CustomersProps } from '@/blocks/app/customers'

export function CustomersView({ customers, tags, healths, renewals }: Pick<CustomersProps, 'customers' | 'tags' | 'healths' | 'renewals'>) {
  return (
    <Customers
      customers={customers}
      tags={tags}
      healths={healths}
      renewals={renewals}
      copy={{ section: 'Revenue' }}
      linkComponent={Link}
      onRetry={() => {
        // your code
      }}
      onViewChange={(view) => {
        // your code
      }}
      onSelectedChange={(ids, rows) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's heading level. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tessera, with its initial as the logo` | The product in the standalone top bar. |
| `customers` | `Customer[]` |  | The accounts, one row each. Passing a new array replaces the rows. Default: `count` seeded demo accounts. |
| `count` | `number` | `64` | How many demo accounts to show without `customers`. |
| `loading` | `boolean` | `false` | Loading, before the accounts arrive: skeleton stats and rows. |
| `error` | `ReactNode` |  | Replaces the rows with an error panel; a string is its message. Default: none. |
| `onRetry` | `() => void` |  | The error panel's Retry. Default: none. |
| `empty` | `ReactNode` |  | Replaces the grid when there are no accounts. Default: the grid's empty state from `copy.empty…`, with an import. |
| `copy` | `Partial<CustomersCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the demo's English. |
| `locale` | `string` |  | Formats numbers, money and dates. Default: the app's locale (YoujProvider's `locale`), else en-US. |
| `currency` | `string` | `'USD'` | The currency MRR is in. |
| `summary` | `Partial<CustomersSummary>` |  | The quarter's target and last month's figures, for the stats. Default: the demo's. |
| `tags` | `Record<string, { label: string }>` | `the demo's seven` | The tags rows can carry, by key, with their labels. |
| `healths` | `DataGridStatusOptions` |  | The health values rows can carry, by key, with their labels and tones, in sort order. Default: healthy, trial, at risk and churning (labels from `copy.health`). The stat cards still count those four. |
| `renewals` | `DataGridStatusOptions` |  | The renewal values rows can carry, by key, with their labels and tones, in sort order. Default: overdue, this month, next quarter and later (labels from `copy.renewal`). The stat cards still count overdue and this month. |
| `views` | `DataGridView[]` |  | The saved views, as tabs. Default: All, At risk, Enterprise and Renewing soon, counted from the rows. |
| `view` | `string` |  | The open view's id (controlled). Default: uncontrolled. |
| `defaultView` | `string` |  | The view open at first, uncontrolled. Default: the first. |
| `onViewChange` | `(view: string) => void` |  | Called when another view opens. |
| `selected` | `string[]` |  | The selected rows' ids (controlled). Default: uncontrolled. |
| `defaultSelected` | `string[]` |  | The rows selected at first, uncontrolled. Default: none. |
| `onSelectedChange` | `(ids: string[], rows: CustomerRow[]) => void` |  | Called when the selection changes, with the ids and the rows. |
| `now` | `Date \| number` | `the demo's fixed Sep 29, 2026, so server and browser agree` | The moment relative dates count from. |
| `onRowClick` | `(row: CustomerRow) => void` |  | A click on a row, anywhere but its own controls. Default: none (the row's chevron opens its panel). |
| `getHref` | `(row: CustomerRow) => string` |  | An account's page: the panel's View account becomes a link to it. Default: no links. |
| `linkComponent` | `ElementType` | `'a'` | Renders internal links, e.g. Next.js `Link`. |
| `onOpen` | `Row` |  | Open account (row menu) and View account (panel). Default: a demo toast. |
| `onEmail` | `Row` |  | Email contact. Default: a demo toast. |
| `onAssign` | `Rows` |  | Assign owner, from a row or the selection. Default: a demo toast. |
| `onTag` | `Rows` |  | Add tag, from a row or the selection. Default: a demo toast. |
| `onExport` | `Rows` |  | Export the selection. Default: a demo toast. |
| `onArchive` | `Rows` |  | Archive: the rows leave at once and come back if it rejects. Default: archived here only. |
| `onRestore` | `Rows` |  | Undo after an archive: the rows come back. Default: restored here only. |
| `onAutoRenewChange` | `(row: CustomerRow, value: boolean) => Promise<unknown> \| unknown` |  | A row's auto-renew switch: it flips at once and flips back if this rejects. Default: a demo toast. |
| `onImport` | `() => Promise<unknown> \| unknown` |  | The header's (and the empty state's) Import button. Default: does nothing. |
| `onCreate` | `() => Promise<unknown> \| unknown` |  | The header's New customer button. Default: does nothing. |
| `actions` | `ReactNode` |  | Header actions, replacing Import and New customer. Default: those two. |
| `classNames` | `Partial<Record<'header' \| 'stats' \| 'grid', string>>` |  | Classes on key parts. |

**Strings:** `copy` takes `section`, `period`, `title`, `description`, `import`, `create`, `noun`, `emptyTitle`, `emptyDescription`, `emptyAction`, `views`, `columns`, `perMonth`, `health`, `renewal`, `actions`, `bulk`, `undo`, `failed`, `many`, `archived`, `autoRenewOn`, `autoRenewOff`, `drafting`, `opening`, `chooseOwner`, `tagging`, `exported`, `exportFile`, `stats`, `customers`, `vsLastMonth`, `noAccounts`, `mrr`, `nothingBilled`, `toGo`, `ofTarget`, `atRisk`, `accounts`, `nothingAtRisk`, `exposed`, `renewing`, `upForRenewal`, `overdue`, `dueThisMonth`, `contact`, `email`, `viewAccount`, `usage`, `usageHeading`, `usageLabel`, `tickets`, `nps`, `region`, `seats`, `seatsOf`.

### Records grid

Work through every order in one virtualized grid: filter by payment, fulfillment or channel, open an order in a side sheet, and pack, ship or print labels in bulk.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-records-grid
```

It brings `app-page`, `async-button`, `avatar`, `badge`, `button`, `icon-arrow-up-right`, `icon-check`, `icon-download`, `icon-mail`, `icon-package`, `icon-plus`, `icon-printer`, `icon-rotate-ccw`, `icon-truck`, `illustrations`, `reveal`, `sheet`, `stat-card`, `tables-data-grid`, `toast`, `use-mobile`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { RecordsGrid, type RecordsGridProps } from '@/blocks/app/records-grid'

export function RecordsGridView({ orders, tags, views, selected }: Pick<RecordsGridProps, 'orders' | 'tags' | 'views' | 'selected'>) {
  return (
    <RecordsGrid
      orders={orders}
      tags={tags}
      views={views}
      selected={selected}
      copy={{ section: 'Orders' }}
      onRetry={() => {
        // your code
      }}
      onViewChange={(view) => {
        // your code
      }}
      onSelectedChange={(ids, rows) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no top bar of its own. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's heading level. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Fernhill, with its initial as the logo` | The shop in the standalone top bar. |
| `orders` | `Order[]` |  | The orders, newest first. Passing a new array replaces the rows. Default: `count` seeded demo orders. |
| `count` | `number` | `2400` | How many demo orders to load without `orders`. |
| `loading` | `boolean` | `false` | Loading, before the orders arrive. |
| `error` | `ReactNode` |  | Replaces the rows with an error panel; a string is its message. Default: none. |
| `onRetry` | `() => void` |  | The error panel's Try again. Default: none. |
| `empty` | `ReactNode` |  | Replaces the grid when there are no orders. Default: the grid's empty state from `copy.empty…` and `illustration`. |
| `illustration` | `IllustrationSlot` | `'shopping-bag'` | The picture in the empty state: a scene from the illustrations by id, or your own node. |
| `copy` | `Partial<OrdersCopy>` |  | Any of the page's strings, to rewrite or translate. Default: the demo's English. |
| `locale` | `string` |  | Formats money. Default: the app's locale (YoujProvider), else en-US. |
| `currency` | `string` | `'USD'` | The currency totals are in. |
| `formatDate` | `(date: Date) => string` |  | Formats when an order was placed, in its sheet. Default: "29 Sep, 15:40", in UTC. |
| `tags` | `Record<string, { label: string }>` | `the demo's five` | The tags orders can carry, by key, with their labels. |
| `views` | `DataGridView[]` |  | The saved views, as tabs. Default: All, To ship, Payment issues and Returns, counted from the rows. |
| `view` | `string` |  | The open view's id (controlled). Default: uncontrolled. |
| `defaultView` | `string` |  | The view open at first, uncontrolled. Default: the first. |
| `onViewChange` | `(view: string) => void` |  | Called when another view opens. |
| `selected` | `string[]` |  | The selected rows' ids (controlled). Default: uncontrolled. |
| `defaultSelected` | `string[]` |  | The rows selected at first, uncontrolled. Default: none. |
| `onSelectedChange` | `(ids: string[], rows: OrderRow[]) => void` |  | Called when the selection changes, with the ids and the rows. |
| `openOrder` | `string \| null` |  | The id of the order open in the sheet, or null (controlled). Default: uncontrolled. |
| `defaultOpenOrder` | `string \| null` | `null` | The order open at first, uncontrolled. |
| `onOpenOrderChange` | `(id: string \| null) => void` |  | Called when an order opens in the sheet, or it closes (null). |
| `now` | `Date \| number` | `the demo's fixed Sep 29, 2026, 15:40 UTC, so server and browser agree` | The moment the stats and relative dates count from. |
| `onRowClick` | `(row: OrderRow) => void` |  | A click on a row: replaces opening its sheet (e.g. to route to the order's page). Default: opens the sheet. |
| `onOpen` | `(row: OrderRow) => void` |  | An order opened in the sheet (row click, Enter, View order). Default: none. |
| `onFulfilmentChange` | `(rows: OrderRow[], fulfilment: Fulfilment) => Promise<unknown> \| unknown` |  | Mark as packed/shipped/delivered (row, sheet or selection), and Undo with each order's previous step. It moves at once and moves back if this rejects. Default: moved here only. |
| `onRefund` | `Row` |  | Refund: the order reads refunded at once and goes back if this rejects. Default: refunded here only, with Undo. |
| `onPrintLabel` | `Rows` |  | Print label, for a row or the selection. Default: a demo toast. |
| `onEmail` | `Row` |  | Email the customer, from the sheet. Default: a demo toast. |
| `onExport` | `Rows` |  | Export: the selection, or every order from the header. Default: a demo toast. |
| `onCreate` | `() => Promise<unknown> \| unknown` |  | The header's Draft order. Default: does nothing. |
| `onShare` | `() => Promise<unknown> \| unknown` |  | The empty state's Share your shop. Default: does nothing. |
| `actions` | `ReactNode` |  | Header actions, replacing Export and Draft order. Default: those two. |
| `classNames` | `Partial<Record<'header' \| 'stats' \| 'grid', string>>` |  | Classes on key parts. |

**Strings:** `copy` takes `section`, `station`, `title`, `description`, `export`, `create`, `search`, `noun`, `emptyTitle`, `emptyDescription`, `emptyAction`, `views`, `columns`, `payment`, `fulfilment`, `markAs`, `marked`, `viewOrder`, `printLabel`, `nothingToShip`, `refund`, `bulk`, `undo`, `failed`, `markedOne`, `markedMany`, `nothingToMark`, `nothingToMarkHint`, `printing`, `printingMany`, `printingTo`, `exported`, `exportFile`, `refunded`, `drafting`, `stats`, `ordersToday`, `hours24`, `vsYesterday`, `noneYesterday`, `noneYet`, `ordersByHour`, `revenue`, `days7`, `vsLastWeek`, `paidOnly`, `revenueByDay`, `toShip`, `orders`, `waiting`, `caughtUp`, `toPack`, `packed`, `returns`, `weeks8`, `vsFourBefore`, `noReturns`, `returnsByWeek`, `progress`, `placed`, `done`, `toDo`, `customer`, `emailCustomer`, `items`, `subtotal`, `shipping`, `free`, `total`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

Each screen has a `header` and one heading (`headingLevel` changes it). The records sit in the [Data grid](https://www.youj.dev/docs/blocks/tables-and-lists#data-grid) block, a `role="grid"` that reports `aria-sort` on sorted columns and `aria-multiselectable` when rows can be selected. Records grid opens a record in a sheet that traps focus and closes with Escape. Records grid shows an order’s progress as an ordered list with the current stage marked by `aria-current`. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

---

# Workspace tools

> Task-specific tools: a file manager, a music studio and a collaborative canvas.

Source: https://www.youj.dev/docs/blocks/workspace-tools

## Blocks

### File manager

Browse, upload and preview files with folders and a choice of grid or list views; this story opens on the grid.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-file-manager
```

It brings `app-page`, `async-button`, `badge`, `breadcrumb`, `button`, `checkbox`, `context-menu`, `counter`, `empty`, `icon-archive`, `icon-check`, `icon-cloud-upload`, `icon-copy`, `icon-download`, `icon-eye`, `icon-file`, `icon-file-text`, `icon-film`, `icon-folder`, `icon-image`, `icon-layout-grid`, `icon-layout-list`, `icon-link`, `icon-menu`, `icon-music`, `icon-search`, `icon-table`, `icon-trash`, `icon-upload`, `icon-x`, `illustrations`, `input-group`, `morph-label`, `presence-list`, `progress`, `resizable`, `select`, `sheet`, `skeleton`, `switch`, `toast`, `toggle-group`, `tree-view`, `typography`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { FileManager, type FileManagerProps } from '@/blocks/app/file-manager'

export function FileManagerView({ files, folders, storage }: Pick<FileManagerProps, 'files' | 'folders' | 'storage'>) {
  return (
    <FileManager
      files={files}
      folders={folders}
      storage={storage}
      copy={{ titleSuffix: ' files' }}
      onFolderChange={(folder) => {
        // your code
      }}
      onViewChange={(view) => {
        // your code
      }}
      onUpload={(file, folder, onProgress) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) with search and Upload, and the frame's gutter, with no top bar of its own. |
| `brand` | `{ name: string; logo?: ReactNode }` | `Stash` | The product in the header, the breadcrumb root and the demo logo files. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The title's level. |
| `copy` | `Partial<FileManagerCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats dates and sizes. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `files` | `FileManagerFile[]` | `the demo's seventeen` | Every file, each naming its folder by id. Uploads and deletes change the list from here. |
| `folders` | `FileManagerFolder[]` | `Brand, Campaigns (Autumn 26, Orbit launch), Contracts, Research` | The folder tree. |
| `storage` | `FileManagerStorage[]` | `media, documents, archives` | What the storage meter splits the space used into. |
| `quota` | `number` | `100 GB` | The storage quota, in bytes. |
| `now` | `Date \| number` | `a fixed demo date` | The moment "Today" and "3 days ago" count from, in epoch ms. |
| `folder` | `string` |  | The open folder, to control it. Pair with `onFolderChange`. |
| `defaultFolder` | `string` |  | The folder open at first, when uncontrolled. Default: Autumn 26 in the demo, else the first folder. |
| `onFolderChange` | `(folder: string) => void` |  | Called with the folder's id when the person opens another. |
| `view` | `'grid' \| 'list'` |  | Grid or list, to control it. Pair with `onViewChange`. |
| `defaultView` | `'grid' \| 'list'` | `'grid'` | Grid or list at first, when uncontrolled. |
| `onViewChange` | `(view: 'grid' \| 'list') => void` |  | Called when the person switches between grid and list. |
| `onUpload` | `(file: File, folder: string, onProgress: (percent: number) => void) => ReturnType<FileManagerUploadHandler>` |  | Uploads one dropped or picked file into the open folder; report progress and resolve with the stored file. A rejection drops it from the tray with its message. Default: a demo transfer. |
| `onDelete` | `(files: FileManagerFile[]) => Promise<unknown> \| unknown` |  | Moves files to trash. They leave at once; a rejection puts them back and shows its message. |
| `onRestore` | `(files: FileManagerFile[]) => Promise<unknown> \| unknown` |  | Undo after a delete: the files are back in the list. |
| `onDownload` | `(files: FileManagerFile[]) => Promise<unknown> \| unknown` |  | Downloads one file (the preview) or the selection; resolve when it's done. Default: a demo wait. |
| `onCopyLink` | `(file: FileManagerFile) => Promise<unknown> \| unknown` |  | Copies a file's link (the tile's menu); resolve when copied. Default: a "Link copied" toast. |
| `getShareUrl` | `(file: FileManagerFile) => string` |  | The share link the preview shows and copies. Default: a demo stash.app link. |
| `onOpen` | `(file: FileManagerFile) => void` |  | Called when a file's preview opens. |
| `loading` | `boolean` | `false` | Shows skeleton tiles in place of the files while they load. |
| `error` | `ReactNode` |  | A load failure, shown in place of the files, with Try again when `onRetry` is set. |
| `onRetry` | `() => void` |  | Called from the error's Try again button. |
| `empty` | `ReactNode` |  | Replaces the empty folder's state. Default: a drop hint from `copy.emptyTitle`. |

**Strings:** `copy` takes `titleSuffix`, `search`, `searchPlaceholder`, `upload`, `folders`, `resizeFolders`, `storage`, `storageOf`, `files`, `sortBy`, `sortModified`, `sortName`, `sortSize`, `view`, `grid`, `list`, `noMatchTitle`, `noMatchDescription`, `emptyTitle`, `emptyDescription`, `errorTitle`, `retry`, `dropTo`, `preview`, `select`, `deselect`, `selectFile`, `copyLink`, `linkCopied`, `copied`, `delete`, `movedOne`, `movedMany`, `undo`, `actionFailed`, `selection`, `selected`, `download`, `downloadSelected`, `zipped`, `downloaded`, `deleteSelected`, `clearSelection`, `uploads`, `uploading`, `uploadingFile`, `uploadFailed`, `you`, `shareTitle`, `shareSwitch`, `location`, `modified`, `owner`, `size`, `today`, `kinds`, `locale`.

### Music studio

Run a music session from controls that float over the song: play, change the tempo, snap the grid and search for clips.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-music-studio
```

It brings `app-page`, `capsule`, `capsule-player`, `capsule-search`, `capsule-stepper`, `capsule-toggle`, `icon-activity`, `icon-audio-lines`, `icon-cpu`, `icon-repeat`, `icon-timer`, `stat-pill`, `toggle`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MusicStudio, type MusicStudioProps } from '@/blocks/app/music-studio'

export function MusicStudioView({ session }: Pick<MusicStudioProps, 'session'>) {
  return (
    <MusicStudio
      session={session}
      copy={{ session: 'Session' }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the block in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) titled with the session, its search and vitals as the header's actions, the arrangement across the whole width and the transport docked at the foot; no capsule or `main` of its own. |
| `copy` | `Partial<MusicStudioCopy>` |  | Any of the block's strings, to rewrite or translate. |
| `locale` | `string` |  | Formats numbers and dates (BCP 47). Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `session` | `Session` | `demo` |  |
| `start` | `number` | `two bars into the drop` | Where the playhead starts, in beats. |
| `autoPlay` | `boolean` | `false` | Starts playing on mount. |

**Strings:** `copy` takes `session`, `arrangement`, `search`, `bar`, `section`, `noMatch`, `matches`, `dsp`, `latency`, `loudness`, `tempo`, `snap`, `snaps`, `transport`, `loop`, `click`, `locale`.

### Meeting booking

Let visitors choose a meeting time on a booking page that accounts for duration and time zone.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-meeting-booking
```

It brings `async-button`, `avatar`, `button`, `calendar`, `content-swap`, `field`, `icon-arrow-left`, `icon-calendar-plus`, `icon-check`, `icon-clock`, `icon-globe`, `icon-refresh`, `icon-video`, `input`, `select`, `skeleton`, `stagger`, `textarea`, `toggle-group`, `use-controllable-state`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import { MeetingBooking, type MeetingBookingProps } from '@/blocks/app/meeting-booking'

export function MeetingBookingView({ host, meeting, durations, zones }: Pick<MeetingBookingProps, 'host' | 'meeting' | 'durations' | 'zones'>) {
  return (
    <MeetingBooking
      host={host}
      meeting={meeting}
      durations={durations}
      zones={zones}
      copy={{ meeting: 'Meeting' }}
      onDateChange={(date) => {
        // your code
      }}
      onDurationChange={(duration) => {
        // your code
      }}
      onZoneChange={(zone) => {
        // your code
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | A theme to force on the block. Default: none, so it inherits the app's (YoujProvider or a ThemeScope around it). |
| `className` | `string` |  | Classes for the page's root; any other prop lands on it too. |
| `embedded` | `boolean` | `false` | Inside another page: the booking card alone, without the page around it (its canvas and the brand in the corner). |
| `fill` | `boolean` | `false` | Embedded, take the whole width it's given instead of stopping at its natural width (1024px at 100% scale). |
| `brand` | `{ name: string; logo?: ReactNode }` | `Tempo, with a clock` | The product in the corner: its name and logo. |
| `locale` | `string` |  | The locale dates read in. Default: `copy.locale`, else the app's locale (YoujProvider), else en-US. |
| `headingLevel` | `1 \| 2 \| 3` | `1` | The meeting title's level; the steps' headings sit one under it. |
| `copy` | `Partial<BookingCopy>` |  | Any of the page's strings, to rewrite or translate; `formatTime` sets how slots read. |
| `host` | `BookingHost` | `Maya Okafor, design lead at Fieldwork` | Who the visitor meets. |
| `meeting` | `BookingMeeting` | `a portfolio review over video` | What they book: its title, description and where it happens. |
| `durations` | `readonly number[]` | `15, 30 and 45` | The lengths on offer, in minutes. |
| `zones` | `readonly BookingZone[]` | `five, from Lisbon` | The time zones the visitor can read the slots in, as offsets from the host's. |
| `availability` | `(date: Date, duration: number) => readonly number[]` |  | The host's free start times for a day and length, in minutes after midnight in the host's zone. Default: demo weekday slots. |
| `isDayOpen` | `(date: Date) => boolean` |  | Whether a day can be picked. Default: the demo's open weekdays; with your `availability`, days after `today` that have a slot. |
| `today` | `Date` | `Sep 28, 2026` | Today, at local midnight: the calendar starts here and the first open day after it is picked. A prop so server and browser agree. |
| `date` | `Date` |  | The chosen day (controlled). |
| `defaultDate` | `Date` |  | The day chosen at first. Default: the first open day after `today`. |
| `onDateChange` | `(date: Date) => void` |  | Runs when the visitor picks a day. |
| `duration` | `number` |  | The chosen length, in minutes (controlled). |
| `defaultDuration` | `number` | `30` | The length chosen at first, in minutes. |
| `onDurationChange` | `(duration: number) => void` |  | Runs when the visitor picks a length. |
| `zone` | `string` |  | The visitor's zone, a `zones` value (controlled). |
| `defaultZone` | `string` | `'lisbon'` | The zone chosen at first. |
| `onZoneChange` | `(zone: string) => void` |  | Runs when the visitor picks a zone. |
| `onBook` | `(booking: BookingRequest) => Promise<unknown> \| unknown` |  | Books the slot with the visitor's details; resolve when it's booked, throw to show the error. Default: a short demo wait. |
| `onAddToCalendar` | `(booking: BookingRequest) => void` |  | Runs from "Add to calendar" on the confirmation. |
| `onReschedule` | `(booking: BookingRequest) => void` |  | Runs from "Reschedule" on the confirmation, as the page goes back to the times. |

**Strings:** `copy` takes `meeting`, `length`, `durationOption`, `durationValue`, `timeZone`, `when`, `pickDay`, `slotsOpen`, `availableTimes`, `noTimes`, `next`, `nextLabel`, `formatTime`, `backToTimes`, `details`, `holding`, `name`, `email`, `emailPlaceholder`, `notes`, `notesPlaceholder`, `notesHint`, `nameRequired`, `emailInvalid`, `confirm`, `booking`, `booked`, `checkDetails`, `bookFailed`, `done`, `doneDetail`, `yourInbox`, `addToCalendar`, `reschedule`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

### Accessibility

File manager is a `main` under a `header` with labelled toolbar controls, a selection bar and an upload tray; the preview opens in a sheet that traps focus and closes with Escape, and file actions sit in menus with arrow-key navigation. Music studio’s controls are a labelled group and its arrangement is a labelled ordered list. Collaborative canvas is a `main` named by its board, with breadcrumbs, a labelled group of who is here and a Share button that reports the copied link; the board is the [Whiteboard](https://www.youj.dev/docs/components/whiteboard), its shapes a listbox walked with Tab, its cards regions of their own, and each comment pin a button that opens its thread in a popover that takes and returns focus. Links and buttons are real `a` and `button` elements with the kit’s focus ring.

Meeting booking is a `main` with time slots that use `aria-pressed`, field errors in an alert and the confirmation in a status region.

---

# Specialized

> Distinct, single-purpose pieces with their own look. Use them as they are or as a starting point.

Source: https://www.youj.dev/docs/blocks/specialized

## Blocks

### Step path

A course as a trail of steps in sections, each ringed by its mastery with the current one ready to start; here a coding course, halfway through Functions with today's goal already met, so the streak reads kept and the next level is 40 XP away. Beside it sit the points to the next level, the week's streak and today's goal. The same path lays out an onboarding by weeks and tasks or a fitness program by phases and workouts.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-step-path
```

It brings `alert`, `badge`, `button`, `card`, `counter`, `empty`, `icon-arrow-right`, `icon-flame`, `icon-more-horizontal`, `progress-path`, `segmented-meter`, `skeleton`, `typography`, `use-announcer`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { StepPath, type StepPathProps } from '@/blocks/app/step-path'

export function StepPathView({ sections, level, week }: Pick<StepPathProps, 'sections' | 'level' | 'week'>) {
  return (
    <StepPath
      sections={sections}
      level={level}
      week={week}
      copy={{ title: 'Spanish' }}
      onOpenStep={(step) => {
        // your code
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `title`, `subtitle`, `more`, `path`, `steps`, `practice`, `continue`, `continueTo`, `finished`, `completed`, `progress`, `week`, `level`, `points`, `total`, `toLevel`, `toGo`, `dailyGoal`, `goalMet`, `streak`, `streakDays`, `streakHint`, `streakKept`, `thisWeek`, `dayPoints`, `loadingLabel`, `errorTitle`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

### Money overview

Show a personal bank’s home: the balance with its hide-amounts toggle, a swipeable card carousel, spending by category, budgets and a day-grouped activity list, with a send-money flow that adds the payment to today.

**Demo only.** Its content is fixed in the block: it takes no data or `copy` props, only the few settings and callbacks listed in its props. Copy the source to build on it.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-money-overview
```

It brings `app-page`, `async-button`, `avatar`, `badge`, `button`, `card`, `carousel`, `chart`, `counter`, `drawer`, `empty`, `field`, `icon-arrow-down-left`, `icon-arrow-left-right`, `icon-arrow-up-right`, `icon-car`, `icon-check-circle`, `icon-coffee`, `icon-engine`, `icon-eye`, `icon-eye-closed`, `icon-leaf`, `icon-plus`, `icon-receipt`, `icon-search`, `icon-send`, `icon-shopping-bag`, `icon-zap`, `input`, `input-group`, `morph-label`, `number-input`, `presence-list`, `progress`, `reveal`, `toggle-group`, `typography`, `use-mobile`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { MoneyOverview } from '@/blocks/app/money-overview'

export function MoneyOverviewView() {
  return (
    <MoneyOverview
      onSend={async (payment) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) and the frame's gutter, across the whole width, with no `main` or canvas of its own. |
| `onSend` | `(payment: { payee: string; amount: number; note: string }) => Promise<unknown> \| unknown` |  | Sends a payment; resolve when the bank has taken it, and the balance and today's list follow. Default: a short demo wait. |

### Collaborative canvas

Review work together on one board: live chart and stat cards among sticky notes and connectors, teammates’ cursors moving with the board, and comment pins that open a thread to answer and resolve, under breadcrumbs, who is here and Share.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-collaborative-canvas
```

It brings `activity-comment-thread`, `app-daily-bars`, `app-page`, `badge`, `breadcrumb`, `button`, `icon-check`, `icon-link`, `live-cursors`, `sparkline`, `stat-card`, `whiteboard`, `youj-core`, `youj-ui-core` with it.

```tsx
'use client'

import Link from 'next/link'
import { CollaborativeCanvas, type CollaborativeCanvasProps } from '@/blocks/app/collaborative-canvas'

export function CollaborativeCanvasView({ path, value, people, threads }: Pick<CollaborativeCanvasProps, 'path' | 'value' | 'people' | 'threads'>) {
  return (
    <CollaborativeCanvas
      path={path}
      value={value}
      people={people}
      threads={threads}
      copy={{ path: 'Board location' }}
      linkComponent={Link}
      onValueChange={(scene) => {
        // your code
      }}
      onShare={async () => {
        // await your API here; the block shows progress until it settles
      }}
      onPost={async (draft) => {
        // await your API here; the block shows progress until it settles
      }}
    />
  )
}
```

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `ThemeInput` |  | Wraps the screen in this theme. Default: the theme around it. |
| `embedded` | `boolean` | `true` | A page in your app's frame: the shared page header (AppPage) titled with the board's name and holding who is here and Share, over the board filling the page; no breadcrumbs of its own. |
| `locale` | `string` |  | Formats the threads' times. Default: the app's locale (YoujProvider). |
| `copy` | `Partial<CollaborativeCanvasCopy>` |  | Any of the screen's strings, to rewrite or translate. |
| `path` | `CollaborativeCanvasCrumb[]` | `the demo's "Acme / Growth / Q4 activation review"` | Where the board is; the last step is its name. |
| `value` | `WhiteboardScene` |  | The board's scene, when your app owns it; pair with `onValueChange`. |
| `defaultValue` | `WhiteboardScene` | `the demo's review board` | The scene at first. |
| `onValueChange` | `(scene: WhiteboardScene) => void` |  |  |
| `people` | `WhiteboardCursor[]` |  | Everyone else on the board, their cursors in board coordinates. Default: two demo collaborators, moving (a demo, marked). |
| `threads` | `Record<string, CommentThreadItem[]>` | `the demo's two threads` | The threads behind each comment pin, by pin id. |
| `team` | `CommentThreadPerson[]` | `demo` | Who can be |
| `user` | `CommentThreadPerson` | `the demo's Jordan` | The signed-in person: new comments are theirs. |
| `embeds` | `Record<string, ReactNode>` |  | What the board's embeds hold, by id. Default: the demo's sign-ups chart and activation card. |
| `now` | `Date \| number` |  | The time the threads are read against. Default: the demo's, or the browser's clock with your `threads`. |
| `demoMarker` | `boolean` | `true` | Shows a dashed "Demo data" badge while the screen runs its demo collaborators. |
| `onShare` | `() => Promise<unknown> \| unknown` |  | Share. Default: the demo's (it reports the link copied). |
| `onPost` | `(draft: CommentThreadDraft) => Promise<Partial<CommentThreadComment> \| void> \| Partial<CommentThreadComment> \| void` |  | A new comment or reply in a pin's thread. |
| `onResolve` | `(threadId: string, resolved: boolean) => Promise<unknown> \| unknown` |  | A pin's thread resolved or reopened from inside it. |
| `linkComponent` | `ElementType` | `'a'` | Renders the breadcrumbs' links. |

**Strings:** `copy` takes `path`, `people`, `share`, `shared`, `demoData`, `thread`, `signups`, `signupsSubtitle`, `activation`, `activationNote`, `locale`.

### Chapter player

A recording as a listening instrument, whether a podcast episode, a lecture or an audiobook: chapter and clock, a waveform scrubber with chapter ticks, a transport with back 15 and forward 30, a speed fader and a Clip tool that brackets half a minute to share.

Copy the source into your app with the Youj CLI:

```bash
npx @youj/cli add app-chapter-player
```

It brings `alert`, `async-button`, `badge`, `button`, `card`, `collapse`, `empty`, `icon-file-text`, `icon-more-horizontal`, `icon-play`, `icon-rotate-ccw`, `icon-rotate-cw`, `icon-scissors`, `skeleton`, `slider`, `typography`, `use-announcer`, `waveform-scrubber`, `youj-core`, `youj-presets`, `youj-ui-core` with it.

```tsx
'use client'

import { ChapterPlayer } from '@/blocks/app/chapter-player'

export function ChapterPlayerView() {
  return (
    <ChapterPlayer
      copy={{ more: 'More options' }}
      onShareClip={async (range) => {
        // await your API here; the block shows progress until it settles
      }}
      onRetry={() => {
        // your code
      }}
    />
  )
}
```

**Props**

**Strings:** `copy` takes `subtitle`, `more`, `byline`, `play`, `pause`, `back`, `forward`, `left`, `speed`, `speedValue`, `clip`, `clipping`, `clipLength`, `share`, `sharing`, `shared`, `sharedAnnounce`, `cancel`, `chapters`, `chapterCount`, `now`, `minutes`, `status`, `timeLeft`, `transcript`, `idleTitle`, `loadingLabel`, `retry`, `emptyTitle`, `emptyDescription`, `locale`.

## Installation & usage

Each story's install, usage, props and strings are under Blocks.

## Description

Each example's description is under Examples.

## Code

Each story's install, usage, props and strings are under Blocks.

## Reference

Each story's install, usage, props and strings are under Blocks.

---

# Miniatures

> Interactive isometric models of real things, for React: a turntable that plays, a server cabinet that fails over, an hourglass that is also a progress indicator.

Source: https://www.youj.dev/docs/miniatures

> **New:** Miniatures are new. They're ready to use; names, props and visuals may still change between releases before 1.0.

Miniatures are interactive isometric models of real things. Where an [illustration](https://www.youj.dev/docs/illustrations) is a scene to look at, a miniature is a machine you can work: parts that move, keys that switch it, a live readout, light and dark. Each one is a React component drawn in SVG, and React is the only dependency.

The [miniatures page](https://www.youj.dev/miniatures) shows them all live: pick one, press its keys, read its readout, then copy its import.

## Installation

```bash
pnpm add @youj/miniatures
```

Each miniature is its own entry, so an app bundles only the ones it imports, plus the engine they share once (about 8 KB gzipped). Each one adds 7 to 13 KB.

## Usage

```tsx
import { MiniatureTurntable } from '@youj/miniatures/turntable'

export function Hero() {
  return <MiniatureTurntable size={420} stage />
}
```

Without `size` it fills its container's width at its own aspect ratio. On the server it renders an empty host at that ratio, so the page doesn't shift, and it draws once mounted.

## Props

Every miniature takes these. Other HTML attributes (`className`, `style`, `id`, handlers) go to the host `<div>`.

| Prop | Default | |
| --- | --- | --- |
| `mode` | `'system'` | `'light'`, `'dark'`, or `'system'`: a `.dark`/`.light` class or `data-theme` on an ancestor, else the OS. |
| `size` | | The side of the square it's fitted into, in pixels or any CSS length. |
| `stage` | `false` | Paints its stage behind it: warm paper, or warm charcoal in the dark. |
| `interactive` | `true` | `false` draws a still picture (`role="img"`): no focus, pointer or keys. The ref still drives it. |
| `keyboard` | `'scoped'` | Where its keys work: `'scoped'`, `'global'` or `'off'` (see [Keys](#keys)). |
| `sound` | `false` | Lets it make its sounds, from the first click or key on it, never before. |
| `autoPlay` | `true` | `false` shows its first frame and waits for an interaction or `play()`. For pages of many. |
| `reducedMotion` | `'user'` | `'user'` follows `prefers-reduced-motion`; `'always'` and `'never'` force it. Reduced, every change jumps to its end. |
| `onStateChange` | | Called with the new snapshot after the readout changes. |
| `aria-label` | its name and model | Overrides the accessible name. |

Offscreen, a miniature's clock holds (and its sound pauses), so a page of them costs only what's in view.

## Readout and keys

The component is the drawing and its behavior; your page presents the rest. The root import is a catalogue of every miniature's metadata (name, model, spec, description, key hints, first readout) with no drawing code, safe in a server component. The ref's handle presses keys and reads the snapshot:

```tsx
'use client'

import { useRef, useState } from 'react'
import type { AnyMiniatureHandle, MiniatureSnapshot } from '@youj/miniatures'
import { MiniatureTurntable, turntable } from '@youj/miniatures/turntable'

export function Exhibit() {
  const ref = useRef<AnyMiniatureHandle>(null)
  const [snapshot, setSnapshot] = useState<MiniatureSnapshot>(turntable.initial)
  return (
    <figure>
      <MiniatureTurntable ref={ref} onStateChange={setSnapshot} stage />
      <figcaption>
        {turntable.name} · {snapshot.readout} · {snapshot.state}
        {turntable.keys.map((hint) => (
          <button
            key={hint.label}
            aria-pressed={'toggle' in hint ? snapshot.pressed[hint.keys[0]] : undefined}
            onClick={() => ref.current?.press(hint.keys[0])}
          >
            {hint.caps.join(' ')} {hint.label}
          </button>
        ))}
      </figcaption>
    </figure>
  )
}
```

`press(key)` takes a `KeyboardEvent.key` (`' '`, `'c'`, `'ArrowUp'`, `'shift+w'`) or a name (`'space'`, `'up'`). `getSnapshot()` and `subscribe()` fit `useSyncExternalStore`; `pause()` and `play()` hold and release its clock.

### Keys

A miniature never takes the page's keys by default. With `keyboard="scoped"` its keys work while focus is inside it (Tab reaches it and each of its parts), or while the pointer is over it and nothing else has focus. `"global"` takes them anywhere except text fields and another control's own keys (Space on a button, arrows in a slider). `"off"` leaves only its parts' own Enter and Space, and `press()`. It lists its keys in `aria-keyshortcuts`.

## As a progress indicator

The hourglass, the packaging line and the repair bench are also progress indicators (`meta.progress`). They take `progress`, a share from 0 to 1 (or `null` for indeterminate), and `done`:

```tsx
import { MiniatureHourglass } from '@youj/miniatures/hourglass'

<MiniatureHourglass interactive={false} size={160} progress={uploaded / total} done={finished} aria-label="Uploading" />
```

Without `progress` it runs on its own. With it, it follows the share: the sand settles, the pallet fills, the checklist lights up. `done` finishes the job: the glass makes a last turn and glows, the pallet is wrapped, the case closes and its beacon turns green. Their handle adds `setProgress(p | null)` and `done()`.

## Theming

Each miniature wears its own palette: a product drawing on warm paper in light, the same materials relit on a warm charcoal stage in dark. Every token a miniature declares yields to the same name with a `--yjm-` prefix set on any ancestor: `--yjm-accent` recolors its lit parts and focus ring, `--yjm-bg` its stage, `--yjm-wood` its walnut.

```css
.exhibit {
  --yjm-accent: #e5484d;
}
.dark .exhibit {
  --yjm-accent: #ff6b6f;
}
```

Each miniature draws in its own shadow root, so your CSS can't reach its drawing and its CSS can't reach your page; the host element styles like any `<div>`. `palette`, `stage` and `relight(hex, role)` are exported from the root for pages that match its colors.

---

# Using icons

> Use animated icons to show actions and states in your interface.

Source: https://www.youj.dev/docs/icons

Every icon is drawn on the same grid and moves on the same clock as the rest of your interface. Here's one taken apart: the grid it's drawn on, its resting state, the path it travels and where it lands. Pick another to see how it moves.

Browse every icon, search by meaning and copy code at https://www.youj.dev/icons.

Use icons to identify actions and states in buttons, menus, tabs and status lines. Their animation gives feedback on hover and keyboard focus. For inline text or dense tables, use `trigger="none"` to keep them still.

## Installation

The package ships the whole set from one entry.

```bash
pnpm add @youj/icons
```

```tsx
import { BellIcon, MenuIcon } from '@youj/icons'
```

Or copy icons in one at a time with the Youj CLI. Each is its own item, `icon-<name>`, and brings the icon engine with it.

```bash
npx @youj/cli add icon-bell icon-menu
```

## Usage

Every icon is a component. It's decorative by default (`aria-hidden`); give it an `aria-label` when it carries meaning on its own.

```tsx
import { BellIcon } from '@youj/icons'

<button type="button">
  <BellIcon size={18} />
  Notifications
</button>
```

Icons play on hover by default, and they listen to their closest interactive parent, so hovering or keyboard-focusing the button above rings the bell. Mark any other container with `data-yj-trigger` to make it the trigger.

## Examples

### Triggers

```tsx
'use client'

import { useState, type ReactNode } from 'react'
import { BellIcon, CheckCircleIcon, LoaderRingIcon, MicIcon, RefreshIcon } from '@youj/icons'

function Card({ trigger, note, children }: { trigger: string; note: string; children: ReactNode }) {
  return (
    <div className="flex flex-col overflow-hidden rounded-xl border border-line bg-surface">
      <div className="flex h-28 items-center justify-center gap-3 border-b border-line bg-canvas px-3">{children}</div>
      <div className="px-3.5 py-3">
        <p className="font-mono text-xs text-fg">{trigger}</p>
        <p className="mt-1 text-xs leading-relaxed text-fg-muted">{note}</p>
      </div>
    </div>
  )
}

const button =
  'inline-flex h-8 items-center gap-1.5 rounded-lg border border-line bg-surface px-3 text-sm font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none'

export default function IconTriggers() {
  const [muted, setMuted] = useState(false)

return (
    <div className="@container w-full max-w-3xl">
      <div className="grid grid-cols-1 gap-3 @md:grid-cols-2 @3xl:grid-cols-4">
        <Card trigger={'trigger="hover"'} note="Plays while its button is hovered or keyboard-focused.">
          <button type="button" className={button}>
            <BellIcon size={16} strokeWidth={1.75} />
            Notifications
          </button>
        </Card>

<Card trigger={'trigger="mount"'} note="Plays once as it appears. Press Replay above.">
          <p className="flex items-center gap-2 text-sm font-medium text-fg">
            <CheckCircleIcon trigger="mount" size={18} strokeWidth={1.75} className="text-success" />
            Deployed
          </p>
        </Card>

<Card trigger={'trigger="loop"'} note="Repeats while on screen, and pauses offscreen and in hidden tabs.">
          <span className="flex items-center gap-1.5 text-xs text-fg-muted">
            <LoaderRingIcon size={18} />
            continuous
          </span>
          <span className="flex items-center gap-1.5 text-xs text-fg-muted">
            <RefreshIcon trigger="loop" size={18} />
            cycle
          </span>
        </Card>

<Card trigger="active={muted}" note="Controlled from state. It wins over any trigger.">
          <button type="button" aria-pressed={muted} onClick={() => setMuted(!muted)} className={`${button} aria-pressed:bg-raised [&[aria-pressed=true]>svg]:text-danger`}>
            <MicIcon size={16} strokeWidth={1.75} active={muted} />
            Mute
          </button>
        </Card>
      </div>
    </div>
  )
}
```

- `hover` plays the choreography while the trigger is hovered or keyboard-focused, and settles back when it's released. The trigger is the closest ancestor with `data-yj-trigger`, otherwise the closest button, link, `summary`, `label` or element with a button, link, menu item, tab, switch or option role, otherwise the icon itself. Only keyboard focus counts, so a button that keeps focus after a click still settles when the pointer leaves.
- `mount` plays once, as the icon appears.
- `loop` repeats while the icon is on screen and the tab is visible, and pauses otherwise. Most icons cycle: they play for two `deliberate` steps and rest for one. Loaders (`LoaderRingIcon`, `LoaderDotsIcon` and `HourglassIcon`) run continuously instead, and they loop by default.
- `none` holds the resting pose.

A controlled `active` wins over every trigger. `true` holds the icon in its active pose, `false` at rest.

### State icons

State icons carry two states, such as menu and close, play and pause, muted and live, or saved and unsaved. Drive them from your own state with `active`. The icon shows the state, and the button around it carries the meaning for assistive technology. [useIconState](https://www.youj.dev/docs/icons/use-icon-state) wires up both.

```tsx
'use client'

import { MicIcon, PhoneCallIcon, useIconState, VideoIcon } from '@youj/icons'

const control =
  'grid size-10 place-items-center rounded-full transition-colors duration-(--yj-duration-fast) ease-standard focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none'
const toggle = `${control} border border-line bg-surface text-fg hover:bg-raised aria-pressed:bg-raised`

export default function IconStateControls() {
  // Pressed toggles keep one name and announce the state with aria-pressed.
  const mic = useIconState({ label: 'Mute' })
  const camera = useIconState({ label: 'Camera off' })
  // An action names what happens next, so its name follows the state instead.
  const call = useIconState({ labels: ['Join call', 'Leave call'], defaultActive: true })

return (
    <div className="w-full max-w-sm overflow-hidden rounded-2xl border border-line bg-surface">
      <div className="relative grid h-40 place-items-center bg-raised">
        <span className="grid size-16 place-items-center rounded-full bg-surface text-lg font-semibold text-fg">AL</span>
        <p className="absolute start-3 bottom-3 flex items-center gap-1.5 rounded-md bg-surface px-2 py-1 text-xs font-medium text-fg">
          {mic.active && <MicIcon active size={13} strokeWidth={2} className="text-danger" />}
          Ana Lima
        </p>
      </div>
      <div className="flex items-center justify-center gap-2.5 px-4 py-3.5">
        <button {...mic.buttonProps} className={toggle}>
          <MicIcon {...mic.iconProps} size={18} className={mic.active ? 'text-danger' : undefined} />
        </button>
        <button {...camera.buttonProps} className={toggle}>
          <VideoIcon {...camera.iconProps} size={18} />
        </button>
        <button {...call.buttonProps} className={`${control} text-on-accent ${call.active ? 'bg-danger' : 'bg-success'}`}>
          <PhoneCallIcon {...call.iconProps} size={18} />
        </button>
      </div>
    </div>
  )
}
```

Reversing plays the opposite choreography, and a toggle mid-morph turns back from wherever the icon is. [Morphs](https://www.youj.dev/docs/icons/morphs) has all of them.

### Size and stroke

`size` sets the width and height. It takes a number of pixels or any CSS length, so `size="100%"` fills its box. `strokeWidth` is in view-box units, so it scales with the icon: the default 1.5 draws 1px lines at 16px and 2px lines at 32px.

```tsx
'use client'

import { SettingsIcon } from '@youj/icons'

// Size and stroke that sit well with each control height and type size.
const CONTROLS = [
  { icon: 14, stroke: 1.75, className: 'h-6 gap-1 px-2 text-xs' },
  { icon: 16, stroke: 1.75, className: 'h-8 gap-1.5 px-3 text-sm' },
  { icon: 20, stroke: 1.5, className: 'h-10 gap-2 px-4 text-base' },
]

const DISPLAY = [
  { icon: 24, stroke: 1.5 },
  { icon: 32, stroke: 1.5 },
  { icon: 48, stroke: 1.25 },
]

const caption = 'font-mono text-[11px] text-fg-muted'

export default function IconSizes() {
  return (
    <div className="flex w-full max-w-2xl flex-col items-center gap-10">
      <div className="flex flex-wrap items-end justify-center gap-5">
        {CONTROLS.map(({ icon, stroke, className }) => (
          <figure key={icon} className="flex flex-col items-center gap-2.5">
            <button
              type="button"
              className={`inline-flex items-center rounded-lg border border-line bg-surface font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none ${className}`}
            >
              <SettingsIcon size={icon} strokeWidth={stroke} />
              Settings
            </button>
            <figcaption className={caption}>
              {icon}px · {stroke}
            </figcaption>
          </figure>
        ))}
      </div>
      {/* Not in a control: data-yj-trigger makes each figure the hover target. */}
      <div className="flex items-end gap-8 text-fg">
        {DISPLAY.map(({ icon, stroke }) => (
          <figure key={icon} data-yj-trigger className="flex flex-col items-center gap-2.5">
            <SettingsIcon size={icon} strokeWidth={stroke} />
            <figcaption className={caption}>
              {icon}px · {stroke}
            </figcaption>
          </figure>
        ))}
      </div>
    </div>
  )
}
```

| Where | Size | Stroke |
| --- | --- | --- |
| 24px controls, 12px text | 14 | 1.75 |
| 28–32px controls, 13–14px text | 16 | 1.75 |
| 40px controls, 16px text | 20 | 1.5 |
| On its own | 24–32 | 1.5 |
| Display, 40px and up | 40+ | 1.25 |

Inside Youj's UI controls, leave `size` alone: a [Button](https://www.youj.dev/docs/components/button), a menu item or a tab sizes its icons to the control. Pass only the stroke.

### Brand marks

Brand marks sit in their own `brand` category, for signing in with a service or linking to it: `BrandGithubIcon`, `BrandXIcon`, `BrandLinkedinIcon`, `BrandDiscordIcon` and `BrandFigmaIcon`. Each is drawn from its owner's official asset, in one color, and never animates: the guidelines don't allow a mark to be altered, and a moving mark is an altered one.

```tsx
import { Button } from '@youj/react'
import { BrandGithubIcon } from '@youj/icons'

<Button variant="outline">
  <BrandGithubIcon />
  Continue with GitHub
</Button>
```

- Use a mark only to refer to its service: a sign-in button, a link to a profile or project, a row of social links. Never as your own logo, and never so it suggests the service endorses you.
- Keep it as drawn, in black or white (the foreground color). GitHub also allows gray or green, LinkedIn its blue, Discord its Blurple. Don't recolor it in your accent, stretch it or combine it with other marks or words.
- Name the service beside the mark where you can; Discord asks for it.
- Google, Apple, Microsoft, Slack and GitLab aren't in the set. Their guidelines require their own artwork (Google's full-color G, Apple's and Microsoft's sign-in buttons) or don't allow their logos to be redistributed, so use the sign-in button artwork each one provides.

#### Continue with Google

Google is the one exception to the single-color rule, so it isn't an icon here. The [auth blocks](https://www.youj.dev/docs/blocks/auth) draw Google's button from its [Sign in with Google guidelines](https://developers.google.com/identity/branding-guidelines), in `blocks/auth/shell/google-mark.tsx`:

- The standard four-color G, never monochrome, recolored or resized out of proportion.
- Google's own button colors, not your theme's: the light theme (white fill, `#747775` stroke, `#1F1F1F` text) in a light scope and the dark theme (`#131314`, `#8E918F`, `#E3E3E3`) in a dark one, following each scope's `color-scheme`. `googleButton.neutral` is the neutral theme (`#F2F2F2`, no stroke).
- An approved label: "Continue with Google", "Sign in with Google" or "Sign up with Google", translated where the page is.
- The same size and weight as the other sign-in buttons beside it.

Those colors are the one raw-color exception to Youj's token lint, allowlisted for that file alone. Google specifies Google Sans Medium for the label; the block uses your UI font, so load Google Sans if you need strict compliance.

The marks are their owners' trademarks, used under each owner's brand guidelines, and aren't covered by Youj's MIT license. [Credits](https://www.youj.dev/docs/contributing#credits-and-licenses) links every guideline.

### How an icon is built

Each icon is a `createIcon` definition. `variants(k)` receives the Youj timing object, so every duration and spring comes from the tokens, and the Speed control and reduced motion reach every part. Each part defines a `rest` and an `active` pose, and optionally a `from` pose for `trigger="mount"`. `render` draws the parts as Motion elements. This is the complete source of `CheckIcon`:

```tsx
import { motion } from 'motion/react'
import { createIcon, drawIn, drawn, hidden, origin } from '@youj/icons'

/** Draws its stroke with a decisive ease-out, then settles with a tiny spring. */
export const CheckIcon = createIcon({
  name: 'check',
  category: 'actions',
  keywords: ['done', 'complete', 'confirm', 'ok', 'success', 'tick'],
  variants: (k) => ({
    mark: {
      from: { ...hidden, scale: 0.9 },
      rest: { ...drawn(k), scale: 1 },
      active: {
        ...drawIn(k, 'slow'),
        scale: [0.88, 1],
        transition: { ...drawIn(k, 'slow').transition, scale: { ...k.spring('settle'), delay: k.duration('base') } },
      },
    },
  }),
  render: (v) => <motion.path d="M4 12.5 L9 17.5 L20 6.5" variants={v.mark} style={origin(12, 12)} />,
})
```

The engine does the rest: it resolves the trigger, pauses loops offscreen, sets the ARIA attributes, and under reduced motion turns every variant into its final pose with no transition. A state icon adds `states: ['menu', 'close']`, and its `active` pose is the second state.

The choreography helpers come from the same entry:

| Helper | Does |
| --- | --- |
| `origin(x, y)` | Pivots a part around a point in view-box units. |
| `seq(k, token, times, eases?)` | A keyframed tween over one duration token, with one easing token per segment. `seqFor` takes seconds instead. |
| `after(k, delay, token, ease?)` | A tween that starts after a delay, for sequenced steps. |
| `drawIn`, `drawOut`, `drawn`, `hidden` | Stroke draw-on, retract, fully drawn and hidden poses for `pathLength`. |

Every component carries `meta` with its `name`, `category`, `keywords`, `states` and `defaultTrigger`. The `icons` array holds the whole set in alphabetical order, and `ICON_CATEGORIES` lists the categories the [explorer](https://www.youj.dev/icons) groups them by.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number \| string` | `24` | Rendered width and height. |
| `strokeWidth` | `number` | `1.5` | Stroke width in viewBox units. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |
| `aria-label` | `string` |  | Gives the icon role="img". Without it the icon is decorative (aria-hidden). |
| `trigger` | `'hover' \| 'mount' \| 'loop' \| 'none'` |  | What plays the choreography. Hover also listens to a hovered/focused parent button or `data-yj-trigger` group. |
| `active` | `boolean` |  | Controlled state for state icons (menu → close, play → pause…). Overrides the trigger. |
| `ref` | `Ref<SVGSVGElement>` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Choreography steps | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | most parts move in short tweens |
| Feedback | `spring.snappy` | 0.2s, bounce 0 | flips, snaps and presses |
| Draw on | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | `drawIn`, a stroke writing itself |
| Retract | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | `drawOut` |
| Arrival and success | `spring.settle` | 0.45s, bounce 0.3 | a check landing, a bookmark filling |
| Loop cycle | `duration.deliberate` | 560ms | plays for 2 steps, rests for 1 |

**Reduced motion:** Icons hold their resting pose and never play. State icons switch instantly, and loops stop.

#### Reduced motion

An icon holds its resting pose and never plays, and loops stop. A controlled `active` still sets the pose, so a state icon switches straight to its new state: a muted microphone still shows its slash. The meaning survives; only the motion goes.

### Accessibility

- Icons are decorative by default: `aria-hidden`, and never focusable. Inside a labeled button, leave them that way, so the button has one name.
- `aria-label` turns an icon into `role="img"` with that name. Use it only for an icon that stands alone and means something, like a status mark with no text beside it.
- Hover choreography also plays on visible keyboard focus, so keyboard users get the same feedback as pointer users.
- A state icon shows its state but doesn't announce it. Put the state on the control, with `aria-pressed` or a name that changes, as [useIconState](https://www.youj.dev/docs/icons/use-icon-state) does.

---

# YoujIcon

> Animate lucide-react icons with the same triggers as Youj icons.

Source: https://www.youj.dev/docs/icons/youj-icon

```tsx
'use client'

import {
  ArrowRight,
  Bell,
  Box,
  Check,
  Cloud,
  Coins,
  Download,
  Eraser,
  Hand,
  Heart,
  HeartPulse,
  ListChecks,
  Orbit,
  PenLine,
  Radio,
  RefreshCw,
  Route,
  Search,
  Stamp,
  Tag,
  TriangleAlert,
  ZoomIn,
  type LucideIcon,
} from 'lucide-react'
import { YoujIcon, type YoujIconEffect } from '@youj/icons'

// One lucide icon per effect, picked so the motion reads as what the icon means.
const EFFECTS: [YoujIconEffect, LucideIcon][] = [
  ['pop', Heart],
  ['wiggle', Hand],
  ['spin', RefreshCw],
  ['nudge', ArrowRight],
  ['pulse', Radio],
  ['ring', Bell],
  ['bounce', Download],
  ['flip', Coins],
  ['swing', Tag],
  ['float', Cloud],
  ['heartbeat', HeartPulse],
  ['shake', TriangleAlert],
  ['jelly', Box],
  ['orbit', Orbit],
  ['tilt', Search],
  ['zoom-in', ZoomIn],
  ['zoom-out', Stamp],
  ['draw', PenLine],
  ['draw-in', Check],
  ['draw-out', Eraser],
  ['draw-sequence', Route],
  ['stagger-draw', ListChecks],
]

export default function YoujIconDemo() {
  return (
    <div className="@container w-full max-w-2xl">
      <div className="grid grid-cols-3 gap-2 @md:grid-cols-4 @xl:grid-cols-6">
        {EFFECTS.map(([effect, Icon]) => (
          <button
            key={effect}
            type="button"
            className="flex h-22 flex-col items-center justify-center gap-2.5 rounded-xl border border-line bg-surface text-fg transition-colors yj-duration-fast ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            {/* draw-in rests undrawn, so it keeps its default mount trigger here and plays as the grid appears. */}
            <YoujIcon icon={Icon} effect={effect} trigger={effect === 'draw-in' ? 'mount' : 'hover'} size={24} strokeWidth={1.5} />
            <span className="font-mono text-[11px] text-fg-muted">{effect}</span>
          </button>
        ))}
      </div>
    </div>
  )
}
```

Use YoujIcon to animate a [lucide-react](https://lucide.dev) icon with hover, mount or loop triggers. When a Youj icon fits, use it for animation designed around that icon’s meaning.

## Installation

```bash
pnpm add @youj/icons
```

```tsx
import { YoujIcon } from '@youj/icons'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add youj-icon
```

It brings `icon-engine` with it.

This integration is optional. Youj icons need no Lucide dependency. To use the Lucide examples below, add it to your app:

```bash
pnpm add lucide-react
```

## Usage

Pass the lucide component itself, not an element, and pick an effect.

```tsx
import { Rocket } from 'lucide-react'
import { YoujIcon } from '@youj/icons'

export function DeployButton() {
  return (
    <button type="button">
      <YoujIcon icon={Rocket} effect="bounce" size={16} />
      Deploy
    </button>
  )
}
```

It plays on hover by default and follows the same trigger rules as Youj's icons: hovering or keyboard-focusing the button bounces the rocket. `size` and `strokeWidth` pass through to the lucide icon.

## Examples

### Effects

Seventeen move the whole glyph, and five animate each stroke's `pathLength`.

| Effect | What it does |
| --- | --- |
| `pop` | Squeezes, pops past full size and settles. The default. |
| `wiggle` | A damped rotation, back and forth. |
| `spin` | One full turn, always forwards. Two when `strong`. |
| `nudge` | Out and back along `direction`. |
| `pulse` | Swells and dims, then returns. |
| `ring` | Swings from near the top, like a bell. |
| `bounce` | Two hops, the second smaller. |
| `flip` | A coin turned once on its vertical axis, with perspective. |
| `swing` | A pendulum hung from the top edge, dying away. |
| `float` | Lifts, then bobs for as long as it's active. |
| `heartbeat` | A strong beat, a softer one, then a long release. |
| `shake` | A hard horizontal shake that decays, for errors. |
| `jelly` | Squash and stretch on the ground line. Use it sparingly. |
| `orbit` | One lap around its own center. |
| `tilt` | Cocks to one side and holds while active. |
| `zoom-in` | Dips away and returns from small. On mount, arrives from small. |
| `zoom-out` | Dips away and lands from large, like a stamp. On mount, arrives from large. |
| `draw` | Re-traces every stroke. |
| `draw-in` | Rests undrawn, draws on while active, and retracts when it ends. |
| `draw-out` | Strokes run out through their ends while active, and grow back after. |
| `draw-sequence` | Writes the icon one stroke at a time, at a constant pen speed. |
| `stagger-draw` | A wave through the strokes: each rewinds and redraws in turn, so the icon never goes blank. |

Four effects hold while active instead of playing once: `float`, `tilt`, `draw-in` and `draw-out`. The rest are one-shots. Every effect starts from the icon's current pose, so triggering it again mid-flight carries on from where the icon is instead of jumping.

### Intensity

`intensity` scales each effect in the way that suits it.

- **Transforms:** the amplitude is 0.55× at `subtle`, 1× at `default` and 1.6× at `strong`.
- **Draws:** the pace is `base`, `slow` or `deliberate`, and `draw` and `stagger-draw` offset their strokes by the `tight`, `base` or `loose` stagger step. `draw-sequence` takes 1.4, 2 or 2.8 times `deliberate` for the whole icon.
- **Turns:** `spin` and `flip` turn once, and twice at `strong`.

```tsx
'use client'

import { ArrowRight, Route, TriangleAlert, type LucideIcon } from 'lucide-react'
import { YoujIcon, type YoujIconEffect, type YoujIconIntensity } from '@youj/icons'

const LEVELS: YoujIconIntensity[] = ['subtle', 'default', 'strong']
const ROWS: { effect: YoujIconEffect; icon: LucideIcon; scales: string }[] = [
  { effect: 'shake', icon: TriangleAlert, scales: 'amplitude' },
  { effect: 'nudge', icon: ArrowRight, scales: 'travel' },
  { effect: 'draw-sequence', icon: Route, scales: 'pace' },
]

export default function IntensityTable() {
  return (
    <div className="w-full max-w-lg overflow-hidden rounded-xl border border-line bg-surface">
      <div className="grid grid-cols-[1.2fr_repeat(3,1fr)] border-b border-line text-xs text-fg-muted">
        <span className="px-4 py-2.5">Hover a cell</span>
        {LEVELS.map((level) => (
          <span key={level} className="px-2 py-2.5 text-center font-mono">
            {level}
          </span>
        ))}
      </div>
      {ROWS.map(({ effect, icon, scales }) => (
        <div key={effect} className="grid grid-cols-[1.2fr_repeat(3,1fr)] items-center border-b border-line last:border-b-0">
          <p className="px-4 py-3">
            <span className="block font-mono text-[13px] text-fg">{effect}</span>
            <span className="block text-xs text-fg-muted">scales its {scales}</span>
          </p>
          {LEVELS.map((level) => (
            <button
              key={level}
              type="button"
              aria-label={`${effect}, ${level}`}
              className="grid h-full min-h-14 place-items-center text-fg transition-colors yj-duration-fast ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none focus-visible:ring-inset"
            >
              <YoujIcon icon={icon} effect={effect} intensity={level} size={22} />
            </button>
          ))}
        </div>
      ))}
    </div>
  )
}
```

```tsx
<YoujIcon icon={CircleAlert} effect="shake" intensity="strong" />
```

### Direction

`direction` steers `nudge`: `up`, `down`, `left` or `right`, the default. Left and right follow the reading direction, so under `dir="rtl"` they swap. `orbit` and `tilt` mirror the same way. A glyph that's already mirrored with CSS `scale` isn't flipped twice.

```tsx
<YoujIcon icon={ArrowRight} effect="nudge" direction="right" />
```

### Triggers

YoujIcon takes the same `trigger` values as every Youj icon: `hover` (the default), `mount`, `loop` and `none`. `draw-in` rests undrawn, so it defaults to `mount` and draws on as it appears.

```tsx
'use client'

import { useEffect, useState, type ReactNode } from 'react'
import { Check, CloudUpload, Radio, Rocket } from 'lucide-react'
import { useYouj } from '@youj/core'
import { YoujIcon } from '@youj/icons'
import { Button } from '@youj/react'

function Cell({ label, note, children }: { label: string; note: string; children: ReactNode }) {
  return (
    <div className="flex flex-col justify-between gap-4 rounded-xl border border-line bg-surface p-4">
      <div>
        <p className="font-mono text-[13px] text-fg">{label}</p>
        <p className="mt-0.5 text-xs text-fg-muted">{note}</p>
      </div>
      <div className="flex h-9 items-center">{children}</div>
    </div>
  )
}

export default function YoujIconTriggers() {
  const k = useYouj()
  const [syncing, setSyncing] = useState(false)

// A stand-in for real work: the sync runs for four deliberate steps, so Speed stretches it too.
  useEffect(() => {
    if (!syncing) return
    const timer = setTimeout(() => setSyncing(false), k.ms('deliberate') * 4)
    return () => clearTimeout(timer)
  }, [syncing, k])

return (
    <div className="grid w-full max-w-2xl gap-2.5 sm:grid-cols-2">
      <Cell label='trigger="hover"' note="Plays while the button is hovered or keyboard-focused.">
        <Button variant="outline">
          <YoujIcon icon={Rocket} effect="nudge" direction="up" />
          Deploy
        </Button>
      </Cell>
      <Cell label='trigger="mount"' note="Plays once, as the icon appears.">
        <p className="inline-flex items-center gap-1.5 text-sm text-fg">
          <YoujIcon icon={Check} effect="draw-in" size={16} strokeWidth={2} className="text-success" />
          Build passed
        </p>
      </Cell>
      <Cell label='trigger="loop"' note="Repeats while on screen, and pauses offscreen and in hidden tabs.">
        <p className="inline-flex items-center gap-1.5 text-sm text-fg">
          <YoujIcon icon={Radio} effect="pulse" trigger="loop" size={16} className="text-accent" />
          Live
        </p>
      </Cell>
      <Cell label="active={syncing}" note="Follows your state: it floats for as long as the sync runs.">
        <Button variant="outline" onClick={() => setSyncing(true)}>
          <YoujIcon icon={CloudUpload} effect="float" active={syncing} />
          {syncing ? 'Syncing…' : 'Sync now'}
        </Button>
      </Cell>
    </div>
  )
}
```

A controlled `active` plays the effect each time it turns `true`, and a held effect holds for as long as it stays `true`. That suits effects that answer your app rather than the pointer:

```tsx
import { CloudUpload } from 'lucide-react'
import { YoujIcon } from '@youj/icons'

// Bobs while a sync runs, and settles when it ends.
<YoujIcon icon={CloudUpload} effect="float" active={syncing} />
```

To replay a one-shot for every event, even when the state stays the same, remount it with a new `key` and let `mount` play it:

```tsx
// Shakes once for every failed attempt.
<YoujIcon key={attempts} icon={CircleAlert} effect="shake" trigger="mount" aria-label="Invalid" />
```

`float` pauses offscreen and in hidden tabs even while `active` or `mount` holds it on.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` (required) | `LucideLikeIcon` |  | Any lucide-react icon component (or one shaped like it). |
| `effect` | `'pop' \| 'wiggle' \| 'spin' \| 'draw' \| 'nudge' \| 'pulse' \| 'ring' \| 'bounce' \| 'flip' \| 'swing' \| 'float' \| 'heartbeat' \| 'shake' \| 'jelly' \| 'orbit' \| 'tilt' \| 'zoom-in' \| 'zoom-out' \| 'draw-in' \| 'draw-out' \| 'draw-sequence' \| 'stagger-draw'` | `'pop'` |  |
| `trigger` | `'hover' \| 'mount' \| 'loop' \| 'none'` |  | Default hover; `draw-in` defaults to mount, since it rests undrawn. |
| `active` | `boolean` |  | Controlled: plays the effect whenever this turns true (held effects hold while it stays true). |
| `intensity` | `'subtle' \| 'default' \| 'strong'` | `'default'` |  |
| `direction` | `'up' \| 'down' \| 'left' \| 'right'` | `'right'` |  |
| `size` | `number \| string` | `24` |  |
| `strokeWidth` | `number` | `1.5` |  |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |
| `aria-label` | `string` |  | Gives the icon role="img". Without it the icon is decorative (aria-hidden). |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| One-shots | `duration.deliberate` | 560ms | pop, wiggle, pulse, ring, bounce, shake, jelly, zoom-in, zoom-out |
| Longer one-shots | `duration.deliberate` | 560ms | heartbeat ×1.25, orbit ×1.4, swing ×1.5 |
| Nudge | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | out and back |
| Spin | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | one turn |
| Flip | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | one turn in 3D |
| Tilt | `spring.snappy` | 0.2s, bounce 0 | cocks and holds |
| Float | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | lifts, then bobs on a 3 × deliberate cycle |
| Draws | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | the default pace |
| Stroke offset | `stagger.base` | 40ms step | between strokes at the default intensity |
| Release | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | back to rest when the trigger ends |

**Reduced motion:** The icon stays still and fully drawn. A controlled `draw-in` that's off, or `draw-out` that's on, stays hidden while that state holds.

#### Reduced motion

The icon stays still and fully drawn, so it reads exactly like the plain lucide icon. A controlled `draw-in` that's off, or `draw-out` that's on, stays hidden, because hidden is the state it describes.

### Accessibility

- The icon is decorative by default (`aria-hidden`) and never focusable. Inside a labeled button, leave it that way.
- `aria-label` makes it `role="img"` with that name, for an icon that stands alone and means something, like an error mark.
- Hover effects also play on keyboard focus of the trigger, so keyboard users see the same feedback.
- An effect doesn't announce anything. If `shake` reports an error, the error text still has to be in the page, tied to its field.

---

# Icons in your components

> Add icons to controls with the right triggers, sizes and accessible labels.

Source: https://www.youj.dev/docs/icons/in-your-components

Add icons to your buttons, menus, tabs and fields. They animate when someone hovers or keyboard-focuses the control. This guide covers placement, sizing, triggers, state and accessible labels.

## Picking an icon

Browse the [explorer](https://www.youj.dev/icons) and search by name or keyword; each icon describes its choreography. Pick for meaning first. Motion reinforces an icon that already fits, and a lively choreography can't rescue one that doesn't.

- **Actions** (save, share, delete) take an icon that plays on hover, as a preview of the action.
- **States** (muted, pinned, expanded) take a [state icon](https://www.youj.dev/docs/icons/morphs) driven by your state.
- **Two different icons for one control** (notify and muted) take an [IconSwap](https://www.youj.dev/docs/icons/icon-swap).
- **An icon Youj doesn't draw** can use the optional [YoujIcon wrapper](https://www.youj.dev/docs/icons/youj-icon) with an icon from Lucide.

## In buttons

Put the icon inside the button, before the label. The button is its trigger, so hover and keyboard focus play it, and the icon inherits the button's text color through `currentColor`.

```tsx
'use client'

import { DownloadIcon, PlusIcon, RocketIcon, SettingsIcon, ShareIcon, TrashIcon } from '@youj/icons'
import { Button } from '@youj/react'

export default function IconsInButtons() {
  return (
    <div className="flex w-full max-w-lg flex-col items-center gap-6">
      {/* The button sizes its icon, and its hover and focus play it. Pass only the stroke. */}
      <div className="flex flex-wrap items-center justify-center gap-2">
        <Button>
          <RocketIcon strokeWidth={1.75} />
          Deploy
        </Button>
        <Button variant="outline">
          <PlusIcon strokeWidth={1.75} />
          New project
        </Button>
        <Button variant="outline">
          <ShareIcon strokeWidth={1.75} />
          Share
        </Button>
        {/* Icon-only: the button needs a name, the icon stays decorative. */}
        <Button variant="ghost" size="icon" aria-label="Settings">
          <SettingsIcon strokeWidth={1.75} />
        </Button>
        <Button variant="ghost" size="icon" aria-label="Delete project">
          <TrashIcon strokeWidth={1.75} />
        </Button>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-2">
        {(['xs', 'sm', 'default', 'lg'] as const).map((size) => (
          <Button key={size} variant="secondary" size={size}>
            <DownloadIcon strokeWidth={size === 'lg' ? 1.5 : 1.75} />
            Export
          </Button>
        ))}
      </div>
    </div>
  )
}
```

Youj's [Button](https://www.youj.dev/docs/components/button) sizes its icons to the control: 16px at most sizes, 14px at `xs` and `icon-xs`, and 20px at `icon-lg`. It also pulls a leading or trailing icon 2px toward its edge, because a glyph reads as more padding than text does. So pass only the stroke: 1.75 keeps 14–16px icons crisp next to 13px text, and the default 1.5 suits 20px and up.

An icon-only button needs a name, and the icon stays decorative:

```tsx
<Button variant="ghost" size="icon" aria-label="Delete project">
  <TrashIcon strokeWidth={1.75} />
</Button>
```

## In menus and tabs

Menu items and tabs are triggers too, since they carry the `menuitem` and `tab` roles. Highlighting a row with the pointer or the arrow keys plays its icon. Youj's menu rows and tabs size icons to 16px, and a menu row keeps its icon muted until the row is highlighted.

```tsx
'use client'

import { useState } from 'react'
import { ArchiveIcon, LayersIcon, MoreHorizontalIcon, PencilIcon, PinIcon, ShareIcon, TrashIcon } from '@youj/icons'
import {
  Button,
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from '@youj/react'

export default function IconsInMenu() {
  const [open, setOpen] = useState(false)
  const [pinned, setPinned] = useState(true)

return (
    <div className="flex w-full max-w-sm items-start gap-3 rounded-xl border border-line bg-surface p-4">
      <div className="grid size-9 shrink-0 place-items-center rounded-lg bg-band font-mono text-ui-sm font-semibold text-fg">OR</div>
      <div className="min-w-0 flex-1">
        <p className="text-ui font-semibold text-fg">Orion</p>
        <p className="text-ui-sm text-fg-muted">Marketing site · 3 environments</p>
      </div>
      <DropdownMenu open={open} onOpenChange={setOpen}>
        <DropdownMenuTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Project actions" />}>
          {/* A state icon that follows the menu: more ↔ close. */}
          <MoreHorizontalIcon active={open} strokeWidth={1.75} />
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end" className="w-52">
          {/* Rows are menu items, so highlighting a row plays its icon. */}
          <DropdownMenuItem>
            <PencilIcon strokeWidth={1.75} />
            Rename
            <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <LayersIcon strokeWidth={1.75} />
            Duplicate
          </DropdownMenuItem>
          <DropdownMenuItem>
            <ShareIcon strokeWidth={1.75} />
            Share
          </DropdownMenuItem>
          <DropdownMenuCheckboxItem checked={pinned} onCheckedChange={setPinned}>
            <PinIcon active={pinned} strokeWidth={1.75} />
            Pin to sidebar
          </DropdownMenuCheckboxItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem>
            <ArchiveIcon strokeWidth={1.75} />
            Archive
          </DropdownMenuItem>
          <DropdownMenuItem variant="danger">
            <TrashIcon strokeWidth={1.75} />
            Delete project
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  )
}
```

The trigger above uses a state icon: `MoreHorizontalIcon active={open}` turns the dots into a close mark while the menu is open. The pin row does the same with its checked state.

```tsx
'use client'

import { GitBranchIcon, LayoutGridIcon, LineChartIcon, SettingsIcon } from '@youj/icons'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@youj/react'

const TABS = [
  { value: 'overview', label: 'Overview', Icon: LayoutGridIcon, body: 'Production is healthy. The last deploy went out 12 minutes ago.' },
  { value: 'deployments', label: 'Deployments', Icon: GitBranchIcon, body: '3 preview deployments are waiting for review.' },
  { value: 'analytics', label: 'Analytics', Icon: LineChartIcon, body: 'Visitors are up 18% on last week.' },
  { value: 'settings', label: 'Settings', Icon: SettingsIcon, body: 'Domains, environment variables and access.' },
]

export default function IconsInTabs() {
  return (
    <Tabs defaultValue="overview" className="w-full max-w-lg">
      <TabsList>
        {/* Each tab is the trigger for its own icon: hover or arrow to it and it plays. */}
        {TABS.map(({ value, label, Icon }) => (
          <TabsTrigger key={value} value={value}>
            <Icon strokeWidth={1.75} />
            {label}
          </TabsTrigger>
        ))}
      </TabsList>
      {TABS.map(({ value, body }) => (
        <TabsContent key={value} value={value} className="px-1 py-2 text-fg-muted">
          {body}
        </TabsContent>
      ))}
    </Tabs>
  )
}
```

## In fields, rows and cards

An icon plays for its closest button, link, `summary`, `label`, or element with a button, link, menu item, tab, switch or option role. A field group, a list row or a card is none of those, so its icon would only play when the pointer is right over the glyph. Mark the container with `data-yj-trigger` and it becomes the trigger: hovering anywhere on it, or focusing anything inside it, plays the icon.

```tsx
'use client'

import { CalendarIcon, MailIcon, MessageIcon, SearchIcon } from '@youj/icons'
import { InputGroup, InputGroupAddon, InputGroupInput, Switch } from '@youj/react'

const CHANNELS = [
  { title: 'Email', detail: 'Deploys, invites and billing', Icon: MailIcon, on: true },
  { title: 'Comments', detail: 'Replies and mentions on previews', Icon: MessageIcon, on: true },
  { title: 'Weekly digest', detail: 'Every Monday at 9:00', Icon: CalendarIcon, on: false },
]

export default function IconsInGroups() {
  return (
    <div className="w-full max-w-md space-y-3">
      {/* A group isn't a control, so data-yj-trigger makes the whole field the trigger. */}
      <InputGroup data-yj-trigger>
        <InputGroupAddon>
          <SearchIcon strokeWidth={1.75} />
        </InputGroupAddon>
        <InputGroupInput placeholder="Search settings" aria-label="Search settings" />
      </InputGroup>
      <ul className="divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface">
        {CHANNELS.map(({ title, detail, Icon, on }) => (
          // The row is the trigger: hovering anywhere on it, or focusing its switch, plays the icon.
          <li key={title} data-yj-trigger className="flex items-center gap-3 px-4 py-3">
            <span className="grid size-8 shrink-0 place-items-center rounded-lg bg-band text-fg">
              <Icon size={16} strokeWidth={1.75} />
            </span>
            <div className="min-w-0 flex-1">
              <p className="text-ui font-medium text-fg">{title}</p>
              <p className="text-ui-sm text-fg-muted">{detail}</p>
            </div>
            <Switch defaultChecked={on} aria-label={title} />
          </li>
        ))}
      </ul>
    </div>
  )
}
```

```tsx
<InputGroup data-yj-trigger>
  <InputGroupAddon>
    <SearchIcon strokeWidth={1.75} />
  </InputGroupAddon>
  <InputGroupInput placeholder="Search settings" aria-label="Search settings" />
</InputGroup>
```

Focus counts from anywhere inside the container, so tabbing to a row's switch plays that row's icon. An explicit `data-yj-trigger` also wins over a closer control, so a whole card can be the trigger for an icon inside one of its buttons.

## Driven by state

When an icon shows a state, bind `active` to it. A controlled icon ignores hover and follows only your state, so it can't show a preview that contradicts it. Here the arrow folds to point down when the newest deployments are first, and the column header carries `aria-sort`.

```tsx
'use client'

import { useState } from 'react'
import { ArrowUpIcon } from '@youj/icons'

const DEPLOYS = [
  { id: 'dpl_8f2k', branch: 'main', minutes: 4 },
  { id: 'dpl_7h1c', branch: 'feat/pricing', minutes: 38 },
  { id: 'dpl_6a9x', branch: 'fix/og-image', minutes: 125 },
  { id: 'dpl_5b0q', branch: 'chore/deps', minutes: 1440 },
]

const ago = (m: number) => (m < 60 ? `${m}m ago` : m < 1440 ? `${Math.round(m / 60)}h ago` : `${Math.round(m / 1440)}d ago`)

export default function IconsSort() {
  // The arrow is a state icon: up ↔ down. It follows the sort, it doesn't decide it.
  const [newestFirst, setNewestFirst] = useState(true)
  const rows = [...DEPLOYS].sort((a, b) => (newestFirst ? a.minutes - b.minutes : b.minutes - a.minutes))

return (
    <table className="w-full max-w-md border-separate border-spacing-0 overflow-hidden rounded-xl border border-line bg-surface text-sm">
      <thead>
        <tr className="text-start text-xs text-fg-muted">
          <th scope="col" className="border-b border-line px-4 py-2.5 text-start font-medium">
            Deployment
          </th>
          <th scope="col" aria-sort={newestFirst ? 'descending' : 'ascending'} className="border-b border-line px-2 py-1.5 text-end font-medium">
            <button
              type="button"
              onClick={() => setNewestFirst(!newestFirst)}
              className="inline-flex h-7 items-center gap-1.5 rounded-md px-2 text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
            >
              Updated
              {/* Newest first reads as "down": the arrow folds to point down. */}
              <ArrowUpIcon active={newestFirst} size={14} strokeWidth={2} />
            </button>
          </th>
        </tr>
      </thead>
      <tbody>
        {rows.map((d) => (
          <tr key={d.id}>
            <td className="border-b border-line px-4 py-2.5 [tr:last-child>&]:border-b-0">
              <span className="font-medium text-fg">{d.branch}</span>
              <span className="ms-2 font-mono text-xs text-fg-muted">{d.id}</span>
            </td>
            <td className="border-b border-line px-4 py-2.5 text-end text-fg-muted tabular-nums [tr:last-child>&]:border-b-0">{ago(d.minutes)}</td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}
```

```tsx
<th aria-sort={newestFirst ? 'descending' : 'ascending'}>
  <button type="button" onClick={() => setNewestFirst(!newestFirst)}>
    Updated
    <ArrowUpIcon active={newestFirst} size={14} strokeWidth={2} />
  </button>
</th>
```

Don't leave a state icon on hover inside a control that changes that state. A copy button whose icon previews "copied" on hover says the copy already happened. Drive it with `active`, or hold it with `trigger="none"`. For toggle buttons, [useIconState](https://www.youj.dev/docs/icons/use-icon-state) wires the state, the icon and the ARIA together.

## Labels

- **Inside a named control, the icon is decorative.** Youj icons are `aria-hidden` by default, so the control's text or `aria-label` is its one name. Don't also label the icon.
- **An icon that stands alone and means something gets `aria-label`.** It becomes `role="img"` with that name, like a status mark with no text beside it.
- **State lives on the control.** Use `aria-pressed`, `aria-expanded`, `aria-sort` or a name that changes. The icon's morph is only what sighted users see.

## Adding icons one at a time

Copying source in instead of using the package, add only the icons you use. Each icon is its own item, `icon-<name>`, and the CLI brings the icon engine with the first one.

```bash
npx @youj/cli add icon-search icon-trash icon-arrow-up
```

The files land in `components/youj/icons/`, one per icon, and import each other relatively, so they work wherever your components live.

## Reduced motion

Nothing to wire up. Under reduced motion every icon holds its resting pose, loops stop, and a controlled `active` switches state instantly, so the sort arrow still points the right way and the menu trigger still shows its close mark. Test with the Reduced motion switch on any preview above.

---

# Morphs

> Show a control’s state with icons that morph between meanings, such as play and pause.

Source: https://www.youj.dev/docs/icons/morphs

Browse every icon, search by meaning and copy code at https://www.youj.dev/icons.

Use a state icon when the icon itself should show which state a control is in: a menu that opens, a track that plays, a microphone that's muted, a page that's saved. When the two states are two different icons with no state icon between them, use [IconSwap](https://www.youj.dev/docs/icons/icon-swap). For a one-off confirmation, like a check after a save, a plain icon with `trigger="mount"` says it with less.

## Installation

State icons ship with the rest of the set.

```bash
pnpm add @youj/icons
```

Or copy one in with the Youj CLI. Each is its own item and brings the icon engine with it.

```bash
npx @youj/cli add icon-menu
```

## Usage

Pass your state to `active`. `false` is the first state, `true` the second.

```tsx
import { useState } from 'react'
import { MenuIcon } from '@youj/icons'

export function NavToggle() {
  const [open, setOpen] = useState(false)
  return (
    <button type="button" aria-expanded={open} aria-controls="site-nav" aria-label="Menu" onClick={() => setOpen(!open)}>
      <MenuIcon active={open} />
    </button>
  )
}
```

Each icon names its two states in `meta.states`, for example `MenuIcon.meta.states` is `['menu', 'close']`. The morph shows the state, and the button carries it for assistive technology, here with `aria-expanded`.

## Examples

### Three kinds of morph

Every pair is choreographed on its own, and the choreographies fall into three kinds.

- **Shared-structure path morphs.** The two states share strokes, and the rest reshape. Play folds into pause, a plus swings into a check, a sun's rays retract as the moon's bite sweeps in.
- **Sequenced choreography.** One move after another: the menu's outer bars converge before they cross, the phone's signal arcs retract before the handset turns to hang up, an upload arrow launches before its cloud seals.
- **Masked slashes.** For off states, a slash is drawn through the icon and a matching gap is cut behind it with a mask, so the strokes never collide: the eye, the microphone, the bell and the camera.

Success and arrival states, such as saved, added, invited and verified, land with the `settle` spring, the one overshoot Youj allows.

### Reversal

Turning a state off plays the opposite choreography, not the same one backwards: the menu's bars uncross before they separate. Toggle again mid-morph and the icon turns back from wherever it is, without a jump. Set the preview to ¼ speed and interrupt the morph to watch it.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { useYouj } from '@youj/core'
import { MenuIcon, PlayIcon, ThemeIcon } from '@youj/icons'

const ICONS = [MenuIcon, PlayIcon, ThemeIcon]

const button =
  'h-8 rounded-lg border border-line bg-surface px-3 text-sm font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none'

export default function IconReversal() {
  const k = useYouj()
  const [active, setActive] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)
  useEffect(() => () => clearTimeout(timer.current), [])

// Toggle, then toggle straight back while the morph is still in flight.
  const interrupt = () => {
    clearTimeout(timer.current)
    setActive((a) => !a)
    timer.current = setTimeout(() => setActive((a) => !a), k.ms('fast'))
  }

return (
    <div className="flex w-full max-w-md flex-col items-center gap-8">
      <div className="flex items-center gap-10 text-fg" aria-hidden>
        {ICONS.map((Icon) => (
          <Icon key={Icon.meta.name} active={active} size={56} strokeWidth={1.25} />
        ))}
      </div>
      <div className="flex gap-2">
        <button type="button" aria-pressed={active} onClick={() => setActive(!active)} className={button}>
          Toggle
        </button>
        <button type="button" onClick={interrupt} className={button}>
          Interrupt mid-morph
        </button>
      </div>
      <p className="font-mono text-xs text-fg-muted">
        {ICONS.map((Icon) => Icon.meta.states![active ? 1 : 0]).join(' · ')}
      </p>
    </div>
  )
}
```

### Driving them from state

A state icon follows your state; it doesn't hold its own. That keeps it honest when the state changes from somewhere else, like a keyboard shortcut or the server. In this editor, each toolbar button is a pressed toggle, and its icon shows the formatting it applies.

```tsx
'use client'

import { AlignLeftIcon, BoldIcon, ListIcon, useIconState } from '@youj/icons'

const tool =
  'grid size-8 place-items-center rounded-md text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:bg-raised aria-pressed:text-fg'

const TASKS = ['Ship the pricing page', 'Record the launch demo', 'Update the changelog']

export default function IconEditor() {
  // Each toolbar button is a pressed toggle, and each icon shows the state it sets.
  const bold = useIconState({ label: 'Bold' })
  const center = useIconState({ label: 'Center' })
  const checklist = useIconState({ label: 'Checklist' })

return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <div role="group" aria-label="Formatting" className="flex gap-0.5 border-b border-line p-1.5">
        <button {...bold.buttonProps} className={tool}>
          <BoldIcon {...bold.iconProps} size={16} strokeWidth={1.75} />
        </button>
        <button {...center.buttonProps} className={tool}>
          <AlignLeftIcon {...center.iconProps} size={16} strokeWidth={1.75} />
        </button>
        <button {...checklist.buttonProps} className={tool}>
          <ListIcon {...checklist.iconProps} size={16} strokeWidth={1.75} />
        </button>
      </div>
      <div className={`px-5 py-4 text-sm text-fg ${center.active ? 'text-center' : ''}`}>
        <p className={bold.active ? 'font-semibold' : undefined}>Launch week</p>
        <ul className="mt-2 space-y-1.5 text-fg-muted">
          {TASKS.map((task) => (
            <li key={task} className={`flex items-center gap-2 ${center.active ? 'justify-center' : ''}`}>
              <span
                aria-hidden
                className={checklist.active ? 'size-3.5 rounded-[4px] border border-line-strong' : 'size-1 rounded-full bg-fg-muted'}
              />
              {task}
            </li>
          ))}
        </ul>
      </div>
    </div>
  )
}
```

[useIconState](https://www.youj.dev/docs/icons/use-icon-state) builds the state, the button props and the icon props in one call:

```tsx
import { BoldIcon, useIconState } from '@youj/icons'

const bold = useIconState({ label: 'Bold' })

<button {...bold.buttonProps}>
  <BoldIcon {...bold.iconProps} />
</button>
```

## Reference

### Props

State icons take the same props as every icon. `active` is the one that matters here: it overrides the trigger and holds the icon in its second state while it's `true`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Morph steps | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | each move in a sequence |
| Second beat | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | starts one `fast` step after the first |
| Snaps and flips | `spring.snappy` | 0.2s, bounce 0 | parts that turn or click into place |
| Success and arrival | `spring.settle` | 0.45s, bounce 0.3 | saved, added, invited, verified |
| Draw on | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | checks, slashes and marks writing themselves |

**Reduced motion:** The icon switches straight to its new state, with no morph.

Each icon's choreography is its own, built from these tokens. The [explorer's Morph view](https://www.youj.dev/icons?type=morph) describes what each one does, and toggles them all in a wave.

#### Reduced motion

The icon switches to its new state instantly. The state is still visible, since the slash, the pause bars or the close mark all appear, just without the morph.

### Accessibility

- A state icon is decorative. It shows the state; it doesn't announce it. Put the state on the control: `aria-pressed` for a toggle with one name (mute, bold, save), a name that changes for an action that flips (play and pause), or `aria-expanded` for a disclosure (menu).
- Keep the control's name in step with what the icon shows. A button whose icon shows "close" should be named for closing, or carry `aria-expanded="true"`.
- Toggling from the keyboard morphs the icon the same way as a click.

---

# IconSwap

> Transition between icons to show a change of state, including morphing one shape into another.

Source: https://www.youj.dev/docs/icons/icon-swap

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { useYouj } from '@youj/core'
import { BellIcon, BellOffIcon, IconSwap, type IconSwapTransition } from '@youj/icons'

const TRANSITIONS: IconSwapTransition[] = ['scale-blur', 'rotate', 'morph', 'draw', 'flip', 'fold', 'slide', 'wipe', 'zoom', 'pop']

export default function IconSwapTransitions() {
  const k = useYouj()
  const [on, setOn] = useState<boolean[]>(() => TRANSITIONS.map(() => false))
  const timers = useRef<ReturnType<typeof setTimeout>[]>([])
  useEffect(() => () => timers.current.forEach(clearTimeout), [])

const all = on.every(Boolean)
  const set = (i: number, value: boolean) => setOn((s) => s.map((v, j) => (j === i ? value : v)))

// One gesture across the grid: each card starts a stagger step after the one before.
  const swapAll = () => {
    timers.current.forEach(clearTimeout)
    timers.current = TRANSITIONS.map((_, i) => setTimeout(() => set(i, !all), i * k.stagger('base') * 1000))
  }

return (
    <div className="@container w-full max-w-3xl">
      <div className="mb-4 flex items-center justify-between gap-4">
        <p className="text-sm text-fg-muted">Notifications on → muted, ten ways.</p>
        <button
          type="button"
          onClick={swapAll}
          className="h-8 shrink-0 rounded-lg border border-line bg-surface px-3 text-sm font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          {all ? 'Reset all' : 'Swap all'}
        </button>
      </div>
      <div className="grid grid-cols-2 gap-2 @lg:grid-cols-5">
        {TRANSITIONS.map((id, i) => (
          <button
            key={id}
            type="button"
            aria-pressed={on[i]}
            onClick={() => set(i, !on[i])}
            className="flex flex-col items-center gap-3.5 rounded-xl border border-line bg-surface px-2 pt-6 pb-3.5 text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:border-line-strong aria-pressed:text-fg"
          >
            <IconSwap from={BellIcon} to={BellOffIcon} active={on[i]} transition={id} size={32} />
            <span className="font-mono text-xs text-fg">{id}</span>
          </button>
        ))}
      </div>
    </div>
  )
}
```

Use it when a control's two states are two different icons: notify and muted, invite and invited, a file and the link that opens it. It takes Youj icons and lucide-react icons alike. When a [state icon](https://www.youj.dev/docs/icons/morphs) already covers the pair, use that instead: its morph is choreographed for those two states.

## Installation

```bash
pnpm add @youj/icons
```

```tsx
import { IconSwap } from '@youj/icons'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add icon-swap
```

It brings `youj-core`, `icon-engine`, `icon-morph` with it.

## Usage

Give it the two icons and a state. `active={false}` shows `from`, `true` shows `to`.

```tsx
import { BellIcon, BellOffIcon, IconSwap } from '@youj/icons'

<IconSwap from={BellIcon} to={BellOffIcon} active={muted} transition="morph" />
```

Pass the components, not elements. Youj icons are held still inside the swap, so only the transition moves.

## Examples

### Transitions

Every transition is a pure function of one progress value, from 0 (showing `from`) to 1 (showing `to`). Toggling mid-swap reverses from exactly where it is, and rapid toggles never jump. The default is `scale-blur`.

| Transition | What it does |
| --- | --- |
| `scale-blur` | The old icon shrinks out of focus as the new one sharpens in. |
| `rotate` | One continuous quarter turn: out turns away as in turns in from the other side. |
| `morph` | A true path morph from one icon's strokes to the other's. |
| `draw` | The old strokes run out through their ends, then the new strokes draw on. |
| `flip` | A card turned on its vertical axis. |
| `fold` | Hinged flaps: out folds back on its bottom edge, in swings down from the top. |
| `slide` | One strip: the new icon pushes the old one out through the edge of the box. |
| `wipe` | A hard edge sweeps across, with the new icon behind it. |
| `zoom` | Out flies past the viewer, in arrives from far away. |
| `pop` | Out shrinks away, in overshoots once and settles. Keep it for success. |

`direction` steers `slide` (default `up`) and `wipe` (default `right`). Left and right follow the reading direction, so they swap under `dir="rtl"`.

Chain up to ten icons in any transition, and copy the code, in [Chain](https://www.youj.dev/icons?chain=bell~bell-off).

### Driving the progress

Instead of a state, pass `progress`: a number from 0 (showing `from`) to 1 (showing `to`), or a MotionValue, which repaints on every change without a render. The swap holds that moment of the transition, so a scrubber, a drag or the scroll can drive it. While `progress` is set, `active` and `trigger` are ignored, and `labels` name whichever icon it's nearer.

```tsx
import { useScroll } from 'motion/react'
import { ArrowDownIcon, CheckIcon, IconSwap } from '@youj/icons'

const { scrollYProgress } = useScroll()

<IconSwap from={ArrowDownIcon} to={CheckIcon} transition="morph" progress={scrollYProgress} />
```

It's painted as given under reduced motion too: the value is yours, and the swap adds no motion of its own. If the scroll drives it, decide what reduced motion should show, for example `progress={reduced ? 1 : scrollYProgress}`.

### True morph

`morph` reshapes one icon into another, even two that share nothing, with no dependency. Each icon's strokes are flattened into contours. Strokes the two icons share hold still, and a stroke cut by a slash is carved out of the original, so a bell loses a gap exactly where the slash lands. The remaining strokes pair up by position and length and bend into place, turning rather than collapsing. Anything left over draws on or retracts from where it meets the rest of the icon.

```tsx
'use client'

import { useState } from 'react'
import {
  ArrowRightIcon,
  CheckCircleIcon,
  CheckIcon,
  FilterIcon,
  HeartIcon,
  IconSwap,
  InboxIcon,
  MailIcon,
  SearchIcon,
  SendIcon,
  StarIcon,
  UserCheckIcon,
  UserPlusIcon,
  type SwapIcon,
} from '@youj/icons'

// Any two icons, even ones that share nothing: shared strokes hold, the rest bend or draw.
const PAIRS: { from: SwapIcon; to: SwapIcon; states: [string, string] }[] = [
  { from: ArrowRightIcon, to: CheckIcon, states: ['next', 'done'] },
  { from: UserPlusIcon, to: UserCheckIcon, states: ['invite', 'invited'] },
  { from: SendIcon, to: CheckCircleIcon, states: ['send', 'sent'] },
  { from: SearchIcon, to: FilterIcon, states: ['search', 'filter'] },
  { from: MailIcon, to: InboxIcon, states: ['mail', 'inbox'] },
  { from: HeartIcon, to: StarIcon, states: ['heart', 'star'] },
]

export default function IconSwapMorph() {
  const [on, setOn] = useState<boolean[]>(() => PAIRS.map(() => false))
  const all = on.every(Boolean)

return (
    <div className="@container w-full max-w-2xl">
      <div className="grid grid-cols-2 gap-2 @md:grid-cols-3">
        {PAIRS.map(({ from, to, states }, i) => (
          <button
            key={states[0]}
            type="button"
            aria-pressed={on[i]}
            onClick={() => setOn((s) => s.map((v, j) => (j === i ? !v : v)))}
            className="flex flex-col items-center gap-4 rounded-xl border border-line bg-surface px-3 pt-6 pb-3.5 text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:border-line-strong aria-pressed:text-fg"
          >
            <IconSwap from={from} to={to} active={on[i]} transition="morph" size={44} strokeWidth={1.25} />
            <span className="font-mono text-xs">
              <span className={on[i] ? 'text-fg-muted' : 'text-fg'}>{states[0]}</span>
              <span aria-hidden> → </span>
              <span className="sr-only"> to </span>
              <span className={on[i] ? 'text-fg' : 'text-fg-muted'}>{states[1]}</span>
            </span>
          </button>
        ))}
      </div>
      <div className="mt-4 flex justify-center">
        <button
          type="button"
          onClick={() => setOn(PAIRS.map(() => !all))}
          className="h-8 rounded-lg border border-line bg-surface px-3 text-sm font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          {all ? 'Reset all' : 'Morph all'}
        </button>
      </div>
    </div>
  )
}
```

The plan for each pair of icons is worked out once and shared by every instance.

### In a button

Drive a swap in a button from [useIconState](https://www.youj.dev/docs/icons/use-icon-state). The button carries the name and the state, so the swap stays decorative.

```tsx
'use client'

import { BellIcon, BellOffIcon, IconSwap, useIconState, UserCheckIcon, UserPlusIcon } from '@youj/icons'

const action =
  'inline-flex h-8 items-center gap-1.5 rounded-lg border border-line bg-surface px-2.5 text-sm font-medium text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:border-line-strong aria-pressed:text-fg'

export default function IconSwapButton() {
  // Pressed toggles: the name stays put and aria-pressed carries the state,
  // so the swap itself is decorative (no `labels`).
  const mute = useIconState({ label: 'Mute' })
  const assign = useIconState({ label: 'Assign to me' })

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-4">
      <p className="font-mono text-xs text-fg-muted">KIN-482 · opened by Priya Raman</p>
      <p className="mt-1.5 text-sm font-medium text-fg">Checkout button flickers on slow networks</p>
      <div className="mt-4 flex gap-2">
        <button {...mute.buttonProps} className={action}>
          <IconSwap {...mute.iconProps} from={BellIcon} to={BellOffIcon} transition="morph" size={16} strokeWidth={1.75} />
          Mute
        </button>
        <button {...assign.buttonProps} className={action}>
          <IconSwap {...assign.iconProps} from={UserPlusIcon} to={UserCheckIcon} transition="pop" size={16} strokeWidth={1.75} />
          Assign to me
        </button>
      </div>
    </div>
  )
}
```

```tsx
const mute = useIconState({ label: 'Mute' })

<button {...mute.buttonProps}>
  <IconSwap {...mute.iconProps} from={BellIcon} to={BellOffIcon} transition="morph" size={16} />
  Mute
</button>
```

### On hover

Leave `active` out and the swap follows its `trigger`, `hover` by default. Like any Youj icon, it listens to its closest button, link or `data-yj-trigger` parent, so a row can reveal the action it will take.

```tsx
'use client'

import { ExternalLinkIcon, FileTextIcon, FilmIcon, IconSwap, ImageIcon, type SwapIcon } from '@youj/icons'

const FILES: { name: string; meta: string; icon: SwapIcon }[] = [
  { name: 'Q3 planning.md', meta: '12 KB · edited 2h ago', icon: FileTextIcon },
  { name: 'Launch hero.png', meta: '2.4 MB · edited yesterday', icon: ImageIcon },
  { name: 'Demo cut v4.mp4', meta: '84 MB · edited Monday', icon: FilmIcon },
]

export default function IconSwapHover() {
  return (
    <ul className="w-full max-w-sm divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface">
      {FILES.map(({ name, meta, icon }) => (
        <li key={name}>
          {/* Uncontrolled: the swap follows the row's hover and keyboard focus. */}
          <button
            type="button"
            className="group flex w-full items-center gap-3 px-3.5 py-3 text-start transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none focus-visible:ring-inset"
          >
            <span className="grid size-8 shrink-0 place-items-center rounded-lg border border-line bg-canvas text-fg-muted group-hover:text-fg group-focus-visible:text-fg">
              <IconSwap from={icon} to={ExternalLinkIcon} transition="slide" size={16} strokeWidth={1.75} />
            </span>
            <span className="min-w-0 flex-1">
              <span className="block truncate text-sm font-medium text-fg">{name}</span>
              <span className="block text-xs text-fg-muted">{meta}</span>
            </span>
            <span className="text-xs text-fg-muted opacity-0 transition-opacity duration-(--yj-duration-fast) ease-standard group-hover:opacity-100 group-focus-visible:opacity-100">
              Open
            </span>
          </button>
        </li>
      ))}
    </ul>
  )
}
```

### With Lucide icons

`from` and `to` also accept Lucide icons, including for morph transitions. This optional integration needs `lucide-react` installed in your app. Here Eye changes to EyeOff as the lock opens.

```tsx
'use client'

import { useState } from 'react'
import { Eye, EyeOff, Lock, LockOpen } from 'lucide-react'
import { IconSwap } from '@youj/icons'
import { Field, FieldDescription, FieldLabel, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@youj/react'

export default function IconSwapLucide() {
  const [shown, setShown] = useState(false)

return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Deploy hook secret</FieldLabel>
      <InputGroup>
        <InputGroupAddon>
          {/* Decorative: the button below carries the state. */}
          <IconSwap from={Lock} to={LockOpen} active={shown} transition="morph" size={16} />
        </InputGroupAddon>
        <InputGroupInput readOnly type={shown ? 'text' : 'password'} defaultValue="whsec_demo_notreal0" className="font-mono text-ui-sm" />
        <InputGroupAddon align="inline-end">
          <InputGroupButton size="icon-xs" aria-label="Show secret" aria-pressed={shown} onClick={() => setShown((s) => !s)}>
            <IconSwap from={Eye} to={EyeOff} active={shown} transition="morph" />
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
      <FieldDescription>Signs every payload sent to your deploy hook. Keep it server-side.</FieldDescription>
    </Field>
  )
}
```

```tsx
import { Eye, EyeOff } from 'lucide-react'
import { IconSwap } from '@youj/icons'

<button type="button" aria-label="Show secret" aria-pressed={shown} onClick={() => setShown(!shown)}>
  <IconSwap from={Eye} to={EyeOff} active={shown} transition="morph" />
</button>
```

### On its own

A swap that stands alone and means something needs a name for each state. `labels` gives it `role="img"` and names it for the current state.

```tsx
<IconSwap from={CloudIcon} to={CheckCircleIcon} active={saved} labels={['Saving', 'Saved']} transition="pop" />
```

Without `labels` the swap is `aria-hidden`, which is right inside a labeled button.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `from` (required) | `SwapIcon` |  | Shown while inactive. |
| `to` (required) | `SwapIcon` |  | Shown while active. |
| `active` | `boolean` |  | Controlled state: false shows `from`, true shows `to`. Overrides the trigger. |
| `trigger` | `'hover' \| 'mount' \| 'loop' \| 'none'` | `'hover'` | What swaps an uncontrolled IconSwap. |
| `progress` | `number \| MotionValue<number>` |  | Drives the swap directly instead of a state: 0 shows `from`, 1 shows `to`, and a value between holds that moment of the transition (a scrubber, scroll progress). A MotionValue repaints on every change without re-rendering. When set, `active` and `trigger` are ignored, and the state (labels, `data-state`) is whichever icon it's nearer. It's painted as given under reduced motion too, as ScrollProgress tracks scroll: the value is the caller's, and the swap adds no motion of its own. |
| `transition` | `'rotate' \| 'scale-blur' \| 'draw' \| 'flip' \| 'slide' \| 'fold' \| 'wipe' \| 'zoom' \| 'pop' \| 'morph'` | `'scale-blur'` |  |
| `direction` | `'up' \| 'down' \| 'left' \| 'right'` |  | Travel direction for `slide` (default up) and `wipe` (default right). Left and right follow the reading direction: under dir="rtl" they swap. |
| `labels` | `readonly [string, string]` |  | Accessible names for [from, to]. Without them the swap is decorative (aria-hidden), e.g. inside a labeled button. |
| `size` | `number \| string` | `24` |  |
| `strokeWidth` | `number` | `1.5` |  |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| scale-blur, rotate, zoom | `ease.enter` | cubic-bezier(0.16, 1, 0.3, 1); slow + fast: 480ms | out on `exit`, in on `enter` |
| slide, wipe | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1); slow + fast: 480ms | one push across the box |
| flip, fold | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | out to edge-on, then in |
| pop | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | in overshoots to 114%, then settles |
| draw | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | strokes retract, then new ones draw on |
| morph | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1); deliberate + fast: 700ms | strokes bend into place |
| Reversal |  | length × distance left | takes the remaining share of the length |

**Reduced motion:** The swap is instant: the new icon replaces the old one with no transition.

#### Reduced motion

The swap switches instantly to the icon for the new state. Nothing moves, and the state reads the same.

### Accessibility

- Without `labels`, the swap is decorative (`aria-hidden`). Inside a button, put the name and the state on the button, with `aria-pressed` or a name that changes, as [useIconState](https://www.youj.dev/docs/icons/use-icon-state) does.
- With `labels`, it's `role="img"` named for its current state. A new name isn't announced on its own, so pair a change that matters with a status message.
- The swap never takes focus, and its hover trigger also answers keyboard focus on the parent.

---

# useIconState

> Keep a toggle button’s state, icon and accessible labels in sync.

Source: https://www.youj.dev/docs/icons/use-icon-state

```tsx
'use client'

import { BookmarkIcon, HeartIcon, PlayIcon, useIconState, VolumeIcon, type IconState } from '@youj/icons'

const control =
  'grid size-9 place-items-center rounded-full text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none'

/** What assistive technology gets from each button: its name, and its pressed state if it has one. */
function Announced({ state }: { state: IconState }) {
  const { 'aria-label': name, 'aria-pressed': pressed } = state.buttonProps
  return (
    <li className="flex items-center gap-2 font-mono text-xs">
      <span className="text-fg-muted">button</span>
      <span className="text-fg">“{name}”</span>
      {pressed !== undefined && <span className={pressed ? 'text-accent' : 'text-fg-muted'}>{pressed ? 'pressed' : 'not pressed'}</span>}
    </li>
  )
}

export default function UseIconStateDemo() {
  // An action names what it will do next: Play, then Pause. No aria-pressed.
  const play = useIconState({ labels: ['Play', 'Pause'] })
  // Pressed toggles keep one name and report their state with aria-pressed.
  const save = useIconState({ label: 'Save episode' })
  const like = useIconState({ label: 'Like' })
  const mute = useIconState({ label: 'Mute' })

return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <div className="flex items-center gap-3 rounded-2xl border border-line bg-surface p-3">
        <button {...play.buttonProps} className="grid size-11 shrink-0 place-items-center rounded-full bg-fg text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none">
          <PlayIcon {...play.iconProps} size={20} />
        </button>
        <div className="min-w-0 flex-1">
          <p className="truncate text-sm font-medium text-fg">Shipping motion at scale</p>
          <p className="truncate text-xs text-fg-muted">Interface Notes · Episode 42</p>
        </div>
        <button {...save.buttonProps} className={`${control} aria-pressed:text-fg`}>
          <BookmarkIcon {...save.iconProps} size={18} />
        </button>
        <button {...like.buttonProps} className={`${control} aria-pressed:text-danger`}>
          <HeartIcon {...like.iconProps} size={18} />
        </button>
        <button {...mute.buttonProps} className={`${control} aria-pressed:text-fg`}>
          <VolumeIcon {...mute.iconProps} size={18} />
        </button>
      </div>
      <ul aria-label="Accessible names" className="space-y-1.5 rounded-xl border border-dashed border-line-strong px-4 py-3">
        {[play, save, like, mute].map((state, i) => (
          <Announced key={i} state={state} />
        ))}
      </ul>
    </div>
  )
}
```

Use it for any button whose icon changes with its state: save, like, mute, play and pause, show and hide. It keeps the state, the icon and the button's ARIA in step, so the icon never says one thing while assistive technology hears another. For a menu or a panel that opens, use `aria-expanded` on the trigger instead, with the icon's `active` bound to the open state.

## Installation

```bash
pnpm add @youj/icons
```

```tsx
import { useIconState } from '@youj/icons'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add use-icon-state
```

## Usage

Spread `buttonProps` on a native `<button>` and `iconProps` on the icon.

```tsx
import { BookmarkIcon, useIconState } from '@youj/icons'

export function SaveButton() {
  const save = useIconState({ label: 'Save episode' })
  return (
    <button {...save.buttonProps}>
      <BookmarkIcon {...save.iconProps} />
    </button>
  )
}
```

`buttonProps` sets `type="button"`, the click handler and the ARIA. `iconProps` is `{ active }`, which a state icon or an [IconSwap](https://www.youj.dev/docs/icons/icon-swap) takes as it is.

## Examples

### Two kinds of toggle

The accessible pattern depends on what the button does, and the options decide it.

- **A pressed toggle** (`label`): save, like, mute, bold. The button keeps one name, and `aria-pressed` reports whether it's on, so a screen reader announces "Save episode" and whether it's pressed.
- **An action that flips** (`labels`): play and pause, show and hide password. The name says what the button will do next, so it changes with the state, and there's no `aria-pressed`. While a track plays, the button is announced as "Pause".

```tsx
const like = useIconState({ label: 'Like' })
const play = useIconState({ labels: ['Play', 'Pause'] })
```

Never combine the two: a pressed button whose name also changes reads as "Pause, pressed", which means the opposite of what it does. The types allow `label` or `labels`, not both.

### Controlled

Pass `active` to let your app own the state, and `onActiveChange` to hear presses. Here the host can mute everyone, and the button follows.

```tsx
'use client'

import { useState } from 'react'
import { MicIcon, useIconState } from '@youj/icons'

export default function UseIconStateControlled() {
  // The call owns the state. The button reads it and reports presses back.
  const [muted, setMuted] = useState(false)
  const [notice, setNotice] = useState('')
  const mic = useIconState({
    label: 'Mute',
    active: muted,
    onActiveChange: (next) => {
      setMuted(next)
      setNotice('')
    },
  })

const muteEveryone = () => {
    setMuted(true)
    setNotice('Jonas muted everyone')
  }

return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-3 px-4 py-3">
        <div>
          <p className="text-sm font-medium text-fg">Design review</p>
          <p className="text-xs text-fg-muted">6 people · hosted by Jonas Weber</p>
        </div>
        <button
          {...mic.buttonProps}
          className="grid size-10 place-items-center rounded-full border border-line bg-surface text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:border-transparent aria-pressed:bg-danger aria-pressed:text-on-accent"
        >
          <MicIcon {...mic.iconProps} size={18} />
        </button>
      </div>
      <div className="flex items-center justify-between gap-3 border-t border-line bg-canvas px-4 py-2.5">
        <p role="status" className="min-w-0 truncate text-xs text-fg-muted">
          {notice || (muted ? 'You’re muted' : 'Your microphone is on')}
        </p>
        <button
          type="button"
          onClick={muteEveryone}
          className="shrink-0 rounded-md px-2 py-1 text-xs font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          Host: mute everyone
        </button>
      </div>
    </div>
  )
}
```

```tsx
import { useState } from 'react'
const [muted, setMuted] = useState(false)
const mic = useIconState({ label: 'Mute', active: muted, onActiveChange: setMuted })
```

Without the owner updating `active`, a controlled button stays where it is. `defaultActive` sets the starting state of an uncontrolled one.

### A confirmation that reverts

The hook keeps no timer. For a state that should undo itself, like a copy button's "copied", call `setActive` from your own code and schedule the revert. Here it waits three `deliberate` steps, read from `useYouj()` so the Speed control reaches it too.

```tsx
'use client'

import { useEffect, useRef } from 'react'
import { useYouj } from '@youj/core'
import { CopyIcon, useIconState } from '@youj/icons'

const KEY = 'yk_demo_key_0000000000'

export default function UseIconStateCopy() {
  const k = useYouj()
  // An action: the name says what the button does now, then what just happened.
  const copy = useIconState({ labels: ['Copy API key', 'Copied'] })
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)
  useEffect(() => () => clearTimeout(timer.current), [])

const onCopy = () => {
    navigator.clipboard?.writeText(KEY).catch(() => {})
    copy.setActive(true)
    // The hook holds no timer: the revert is app logic, on the token clock so Speed reaches it.
    clearTimeout(timer.current)
    timer.current = setTimeout(() => copy.setActive(false), k.ms('deliberate') * 3)
  }

return (
    <div className="w-full max-w-sm rounded-xl border border-line bg-surface p-4">
      <p className="text-sm font-medium text-fg">Production key</p>
      <p className="mt-0.5 text-xs text-fg-muted">Use it from your server only.</p>
      <div className="mt-3 flex items-center gap-2 rounded-lg border border-line bg-canvas ps-3 pe-1">
        <code className="min-w-0 flex-1 truncate font-mono text-xs text-fg">{KEY}</code>
        <button
          {...copy.buttonProps}
          onClick={onCopy}
          className="grid size-8 place-items-center rounded-md text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          <CopyIcon {...copy.iconProps} size={16} strokeWidth={1.75} />
        </button>
      </div>
      {/* A changed name isn't announced by itself, so the result gets a polite status. */}
      <p role="status" className="sr-only">
        {copy.active ? 'API key copied to the clipboard' : ''}
      </p>
    </div>
  )
}
```

A name that changes isn't announced on its own, so the example adds a polite status message for the result.

## Reference

### API

#### Options

| Option | Type | Description |
| --- | --- | --- |
| `label` | `string` | A pressed toggle's one name. It gets `aria-pressed`. |
| `labels` | `readonly [string, string]` | An action's names for `[inactive, active]`. No `aria-pressed`. |
| `active` | `boolean` | Controlled state. |
| `defaultActive` | `boolean` | Starting state when uncontrolled. Default `false`. |
| `onActiveChange` | `(active: boolean) => void` | Called with the next state on every press, and on `setActive`. |

Pass exactly one of `label` and `labels`.

#### Returns

| Value | Type | Description |
| --- | --- | --- |
| `active` | `boolean` | The current state. |
| `toggle` | `() => void` | Flips the state. |
| `setActive` | `(active: boolean) => void` | Sets the state. |
| `buttonProps` | `IconStateButtonProps` | `type`, `onClick`, `aria-label`, and `aria-pressed` for a pressed toggle. Spread onto a native `<button>`. |
| `iconProps` | `{ active: boolean }` | Spread onto a state icon or an IconSwap. |

### Reduced motion

The hook has no motion of its own. The icon it drives switches state instantly under reduced motion, and the ARIA is the same either way.

### Accessibility

- `buttonProps` gives the button its name through `aria-label`, so an icon-only button is named. If the button also shows text, make the text match the name.
- Space and Enter toggle it, as with any native button.
- The icon stays decorative. The button carries the state, so there's one source of truth for assistive technology.

---

# Illustrations

> Ready-made isometric scenes for the moments every product has, drawn from your theme. Install one on its own, draw it by id, or hand it to a block.

Source: https://www.youj.dev/docs/illustrations

Put a scene in an empty state, an onboarding step or a hero, and it's drawn in your theme's colors, light or dark. This one assembles as it comes into view. Point at it and it lifts off.

```tsx
'use client'

import { Illustration, LineGrid } from '@youj/illustrations'

/* One scene by id, named for assistive tech. It assembles as it scrolls
 * into view and the rocket bobs over its pad; hover it and it lifts off. */

export default function IllustrationsDemo() {
  return (
    <div className="relative isolate mx-auto w-fit max-w-full p-6 sm:p-8">
      <LineGrid gap={20} />
      <Illustration scene="deploy" explode="hover" unit={28} title="A rocket hovering over its launch pad" />
    </div>
  )
}
```

Each illustration is a small isometric scene: plinths, boxes, cylinders, stacks, turned solids and extruded profiles, shaded from your tokens, with one part in the accent. They cover the moments a product is built around (where its data lives, the machines that serve it, the screens people spend the day in, shipping, safety and the states nobody plans for) and the things people use products for, from shopping and money to travel, food, pets and the weather.

They all frame the same volume, so one scene swaps for another without the layout moving. Draw one by id with `<Illustration>`, import it as its own component, or pass its id to a block's `illustration` prop. Each assembles as it comes into view, and comes apart on hover when you ask it to.

The [illustrations explorer](https://www.youj.dev/illustrations) is the gallery: search every scene by name, category or tag, preview one live in any preset, light or dark, copy its code or its install command, and download it as SVG or PNG.

To make a scene of your own, use the [illustration builder](https://www.youj.dev/illustrations/build) (experimental): drag the kit's parts into place, preview it assembling, and export code, SVG or PNG. [Draw your own](https://www.youj.dev/docs/illustrations/draw-your-own) covers the same parts in code.

## Installation

### From the package

Every scene ships in `@youj/illustrations`. Draw one by id, or import its component:

```bash
pnpm add @youj/illustrations
```

```tsx
import { Illustration, IllustrationCoffee } from '@youj/illustrations'
```

Then add the package's stylesheet to your global CSS, after Tailwind and the tokens. Its sheet points Tailwind at the scenes; without it the classes they use are never generated:

```css title="app/globals.css"
@import 'tailwindcss';
@import '@youj/react/styles.css';
@import '@youj/illustrations/styles.css';
```

### One scene, as source

To own and edit a single scene, copy it in with the Youj CLI in an app set up from source (`npx @youj/cli init --mode registry`). Every scene is its own item, `illustration-<id>`. It brings the kit the scenes are drawn with (`illustration-kit`) and the shapes it uses, and nothing else. In an app on the packages, the same command installs `@youj/illustrations` and adds its stylesheet instead:

```bash
npx @youj/cli add illustration-coffee
```

It lands in `components/youj/graphics/illustrations/scenes/<id>.tsx`, and you import it from there through your `@/` alias:

```tsx
import { IllustrationCoffee } from '@/components/youj/graphics/illustrations/scenes/coffee'
```

Each scene's id and install command are on its card in the [explorer](https://www.youj.dev/illustrations).

### Every scene

A scene's id is what `<Illustration scene>` takes, and its component is `Illustration` and the id in PascalCase (`server-rack` is `IllustrationServerRack`). The ids, by category:

| Category | Ids |
| --- | --- |
| Data | `backups` `database` `pipeline` `storage` `warehouse` |
| Infrastructure | `cloud` `edge` `load-balancer` `network` `server-rack` |
| App | `analytics` `calendar` `documents` `mail` `notifications` `search` |
| Lifecycle | `deploy` `empty` `not-found` `security` `success` `team` |
| Commerce | `delivery` `shopping-bag` `storefront` |
| Finance | `calculator` `coins` `invoice` `payment` `savings` `stock-chart` `wallet` |
| Health | `first-aid` `fitness` `heart-rate` `pills` `stethoscope` `tooth` `yoga` |
| Education | `abacus` `books` `globe` `graduation` `idea` `library` `school-backpack` |
| Travel | `flight` `map` `suitcase` |
| Food | `bakery` `cocktail` `coffee` `cooking` `groceries` `pizza` `restaurant` |
| Media | `camera` `design-tools` `easel` `film-reel` `guitar` `music` `video` |
| Social | `announcement` `chat` `community` `newsletter` `phone-call` `podcast` `reactions` `video-call` |
| Home | `gift` `home` `plant` |
| Work | `briefcase` `checklist` `trophy` |
| Sports | `basketball` `bicycle` `stopwatch` `tennis` |
| Play | `arcade` `dice` `game-controller` `puzzle` |
| Events | `cake` `party` `stage` `ticket` |
| Pets | `cat-tree` `dog-house` `fish-bowl` `pet-bowl` |
| Weather | `lightning` `rain` `snowflake` `sun-cloud` |
| Nature | `flower` `greenhouse` `island` `mountain` `recycling` `tree` `water-drop` |
| Energy | `battery` `ev-charger` `solar-panel` `wind-turbine` |
| Transport | `bus` `car` `scooter` `ship` `train` |
| Places | `bank` `hospital` `lighthouse` `museum` `office-tower` `school` |
| Outdoors | `beach` `binoculars` `compass` `hot-air-balloon` `tent` |
| Science | `atom` `dna` `lab-flask` `microscope` `telescope` |
| Security | `fingerprint` `key` `padlock` `shield` `vault` |
| Devices | `drone` `laptop` `phone` `printer` `smartwatch` `vr-headset` |
| Business | `contract` `handshake` `meeting` `org-chart` `presentation` `scales` `target` |

```bash
pnpm add @youj/illustrations
```

```tsx
import { Illustration } from '@youj/illustrations'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add illustrations
```

It brings `youj-core`, `iso-shapes`, `iso-stack` with it.

From the package, everything on this page comes from `@youj/illustrations` (`pnpm add @youj/illustrations`).

```css title="app/globals.css"
@import 'tailwindcss';
@import '@youj/react/styles.css';   /* or '@youj/core/styles.css' without the components */
@import '@youj/illustrations/styles.css';
```

Its sheet points Tailwind at the built scenes, so it generates the classes they use; it goes after the tokens, in the same file. `npx @youj/cli add` adds it for you.

From the registry, the `illustrations` item copies every scene into `@/components/youj/graphics/illustrations/`, with the kit's shapes they're built from.

## Usage

```tsx
import { Illustration } from '@youj/illustrations'

export function NoInvoices() {
  return <Illustration scene="documents" title="No invoices yet" />
}
```

Each scene is also its own component, for when you know which one you want and would rather import it directly:

```tsx
import { IllustrationDatabase } from '@youj/illustrations'

<IllustrationDatabase explode="hover" />
```

An id that names no scene draws `fallback` instead, so an id you stored that outlives its scene still draws something:

```tsx
import { Illustration } from '@youj/illustrations'

function Empty({ sceneId }: { sceneId: string }) {
  return <Illustration scene={sceneId} fallback="empty" />
}
```

Every scene frames one volume, so swapping never moves the layout. Keyed on the id, the new one assembles in place:

```tsx
'use client'

import { useState } from 'react'
import { Illustration, type IllustrationId } from '@youj/illustrations'
import { Button, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, SegmentedControl, SegmentedControlItem } from '@youj/react'

/* One slot, four scenes. Every scene frames the same volume, so swapping one
 * for another never moves the layout: the new one assembles in place. */

const SCENES: { id: IllustrationId; label: string }[] = [
  { id: 'empty', label: 'Empty' },
  { id: 'search', label: 'Search' },
  { id: 'mail', label: 'Mail' },
  { id: 'not-found', label: 'Not found' },
]

export default function IllustrationsSwap() {
  const [scene, setScene] = useState<IllustrationId>('empty')
  return (
    <div className="mx-auto flex w-full max-w-md flex-col gap-4 p-4 sm:p-6">
      <SegmentedControl aria-label="Scene" value={scene} onValueChange={(value) => setScene(value as IllustrationId)} className="w-full">
        {SCENES.map((s) => (
          <SegmentedControlItem key={s.id} value={s.id} className="flex-1">
            {s.label}
          </SegmentedControlItem>
        ))}
      </SegmentedControl>
      <Empty className="rounded-xl border border-line bg-surface py-8">
        <EmptyHeader>
          <EmptyMedia className="mb-1">
            {/* Keyed on the scene, so the new one assembles as it arrives. */}
            <Illustration key={scene} scene={scene} unit={16} />
          </EmptyMedia>
          <EmptyTitle>Nothing here yet</EmptyTitle>
          <EmptyDescription>The same empty state, with whichever scene fits the moment.</EmptyDescription>
        </EmptyHeader>
        <EmptyContent>
          <Button variant="outline">Get started</Button>
        </EmptyContent>
      </Empty>
    </div>
  )
}
```

## Colour

Scenes are gray by default, with the accent as the one coloured part. Turn colour on with `colors="theme"` and each scene's subject takes one soft hue, and a second hue sets apart a second kind of thing, such as raw and processed data in a pipeline or two people shaking hands. The structure stays neutral and the accent is still the one lit part.

```tsx
<Illustration scene="pipeline" colors="theme" />
```

The theme's pair is derived from the accent, so it follows every preset, light or dark:

- **Hue 1** is the accent's hue at a muted chroma, the scene's main colour.
- **Hue 2** is the hue opposite the accent, for the second kind of thing.
- **Hue 3** is a quarter turn away. It is rare, for a third kind.

Hues are mixed toward the surface, so they always sit quieter than the accent.

```tsx
'use client'

import { useState } from 'react'
import { Illustration } from '@youj/illustrations'
import { SegmentedControl, SegmentedControlItem } from '@youj/react'

/* One scene three ways: gray (the default), the theme's hues, and hues of your
 * own. The accent stays the hero in all three. */

const LOOKS = {
  mono: {},
  theme: { colors: 'theme' },
  own: { colors: ['var(--color-success)', 'var(--color-warning)'] },
} as const

type Look = keyof typeof LOOKS

export default function IllustrationsColour() {
  const [look, setLook] = useState<Look>('mono')
  return (
    <div className="mx-auto flex w-full max-w-md flex-col gap-4 p-4 sm:p-6">
      <SegmentedControl aria-label="Colour" value={look} onValueChange={(value) => setLook(value as Look)} className="w-full">
        <SegmentedControlItem value="mono" className="flex-1">
          Mono
        </SegmentedControlItem>
        <SegmentedControlItem value="theme" className="flex-1">
          Theme
        </SegmentedControlItem>
        <SegmentedControlItem value="own" className="flex-1">
          Your colors
        </SegmentedControlItem>
      </SegmentedControl>
      <div className="rounded-xl border border-line bg-surface py-6">
        <Illustration scene="pipeline" assemble={false} unit={18} {...LOOKS[look]} />
      </div>
    </div>
  )
}
```

`colors` also takes your own colours, in hue order: tokens, brand colours or `oklch()`. They're softened the same way, and an empty string or a missing entry keeps the theme's:

```tsx
<Illustration scene="pipeline" colors={['var(--color-success)', 'var(--color-warning)']} />
```

When you [draw your own](https://www.youj.dev/docs/illustrations/draw-your-own), give a shape `hue={1}` or `hue={2}` on top of its `tone`, and set `colors` on the scene. Without `colors` the shape shows its `tone`.

## Examples

### In a block

Blocks with room for a picture take an `illustration` prop: a scene's id, your own node, or `null` for the block's plainer look. Each opens on a scene that fits it.

```tsx
<AuthShell variant="split" illustration="security">…</AuthShell>
<NoResults illustration="not-found" />
<MarketingCta illustration={<img src="/launch.svg" alt="" />} />
<NoProjects illustration={null} /> {/* the icon on its plates instead */}
```

| Block | Default | `null` |
| --- | --- | --- |
| [App / Empty states](https://www.youj.dev/docs/blocks/onboarding-and-states) | `empty`, `search`, `security` and `cloud`, one per state | The icon on its fanned plates |
| [App / First source](https://www.youj.dev/docs/blocks/onboarding-and-states#first-source) | Its own floor, with the chosen source waiting to land | No picture |
| [App / Onboarding](https://www.youj.dev/docs/blocks/onboarding) | `team`, on the welcome step | The sparkles icon |
| [Auth / Layout](https://www.youj.dev/docs/blocks/auth#shell) and [Login](https://www.youj.dev/docs/blocks/auth) | `deploy`, in the split layout's art panel | The gradient and the quote alone |
| [Marketing / CTA](https://www.youj.dev/docs/blocks/cta) | `deploy`, beside the call to action from `lg` up | No picture |

On those blocks' pages, the preview's **Illustration** menu swaps the scene live. An id that names no scene falls back to the block's own.

### Listing the scenes

`illustrations` lists every scene as `{ id, name, category, tags, Component }`, in the explorer's order, for a picker or a gallery of your own. `illustrationCategories` lists the categories as `{ id, name }`, in the order the explorer shows them. `getIllustration(id)` returns one entry, or `undefined` for an id that isn't registered, and `isIllustrationId(value)` says whether a string names a scene.

```tsx
import { illustrationCategories, illustrations, isIllustrationId } from '@youj/illustrations'

const byCategory = illustrationCategories.map((category) => ({
  ...category,
  scenes: illustrations.filter((scene) => scene.category === category.id),
}))

// A scene from a URL or a setting, narrowed to one that exists.
const scene = isIllustrationId(params.scene) ? params.scene : 'empty'
```

## Reference

### Props

Every scene component, and `<Illustration>`, takes these.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` |  | Names the drawing for assistive tech; without it the scene is decorative (aria-hidden). |
| `description` | `string` |  | A longer description, read after the title. |
| `assemble` | `boolean` | `true` | Parts drop in, far ones first, the first time the scene comes into view. |
| `float` | `boolean` | `true` | The scene's hero part bobs gently. |
| `explode` | `number \| boolean \| 'hover'` | `0` | Take it apart: a number from 0 to 1, a boolean, or 'hover' (stacks part and the lit part rises while the pointer is over it). |
| `unit` | `number` | `22` | CSS px per grid unit at the drawing's natural size. |
| `grow` | `boolean` | `false` | Scale up past the natural size to fill a wider box. |
| `colors` | `readonly string[] \| 'theme'` |  | Colour for the scene's parts: 'theme' for the theme's pair (derived from the accent), or any CSS colours, its main colour first (an empty entry takes the theme's). Default off: gray, with the accent the only colour. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

`<Illustration>` adds the scene to draw:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scene` | `IllustrationSlot \| string` |  | A scene by id, or a node drawn as given. `null` or `false` draws nothing. |
| `fallback` | `'security' \| 'target' \| 'key' \| 'success' \| 'database' \| 'home' \| 'storage' \| 'warehouse' \| 'analytics' \| 'pipeline' \| 'backups' \| 'server-rack' \| 'cloud' \| 'network' \| 'load-balancer' \| 'edge' \| 'mail' \| 'newsletter' \| 'calendar' \| 'meeting' \| 'documents' \| 'search' \| 'notifications' \| 'deploy' \| 'ship' \| 'vault' \| 'team' \| 'not-found' \| 'empty' \| 'storefront' \| 'shopping-bag' \| 'delivery' \| 'payment' \| 'wallet' \| 'coins' \| 'savings' \| 'heart-rate' \| 'fitness' \| 'first-aid' \| 'books' \| 'library' \| 'graduation' \| 'school' \| 'idea' \| 'suitcase' \| 'flight' \| 'map' \| 'coffee' \| 'restaurant' \| 'groceries' \| 'camera' \| 'music' \| 'video' \| 'chat' \| 'video-call' \| 'laptop' \| 'announcement' \| 'tree' \| 'plant' \| 'gift' \| 'checklist' \| 'briefcase' \| 'trophy' \| 'bicycle' \| 'basketball' \| 'stopwatch' \| 'tennis' \| 'game-controller' \| 'arcade' \| 'dice' \| 'puzzle' \| 'party' \| 'ticket' \| 'stage' \| 'cake' \| 'dog-house' \| 'fish-bowl' \| 'pet-bowl' \| 'cat-tree' \| 'sun-cloud' \| 'rain' \| 'snowflake' \| 'lightning' \| 'mountain' \| 'island' \| 'beach' \| 'flower' \| 'recycling' \| 'greenhouse' \| 'water-drop' \| 'solar-panel' \| 'wind-turbine' \| 'battery' \| 'ev-charger' \| 'car' \| 'bus' \| 'train' \| 'scooter' \| 'office-tower' \| 'bank' \| 'hospital' \| 'museum' \| 'lighthouse' \| 'tent' \| 'compass' \| 'binoculars' \| 'hot-air-balloon' \| 'microscope' \| 'lab-flask' \| 'atom' \| 'telescope' \| 'dna' \| 'padlock' \| 'fingerprint' \| 'shield' \| 'phone' \| 'smartwatch' \| 'vr-headset' \| 'printer' \| 'drone' \| 'handshake' \| 'presentation' \| 'easel' \| 'org-chart' \| 'contract' \| 'scales' \| 'stock-chart' \| 'calculator' \| 'invoice' \| 'phone-call' \| 'podcast' \| 'community' \| 'reactions' \| 'pizza' \| 'bakery' \| 'cocktail' \| 'cooking' \| 'pills' \| 'stethoscope' \| 'tooth' \| 'yoga' \| 'globe' \| 'school-backpack' \| 'abacus' \| 'guitar' \| 'film-reel' \| 'design-tools'` |  | The scene drawn when `scene` is left out or names no registered scene. |
| `title` | `string` |  | Names the drawing for assistive tech; without it the scene is decorative (aria-hidden). |
| `description` | `string` |  | A longer description, read after the title. |
| `assemble` | `boolean` | `true` | Parts drop in, far ones first, the first time the scene comes into view. |
| `float` | `boolean` | `true` | The scene's hero part bobs gently. |
| `explode` | `number \| boolean \| 'hover'` | `0` | Take it apart: a number from 0 to 1, a boolean, or 'hover' (stacks part and the lit part rises while the pointer is over it). |
| `unit` | `number` | `22` | CSS px per grid unit at the drawing's natural size. |
| `grow` | `boolean` | `false` | Scale up past the natural size to fill a wider box. |
| `colors` | `readonly string[] \| 'theme'` |  | Colour for the scene's parts: 'theme' for the theme's pair (derived from the accent), or any CSS colours, its main colour first (an empty entry takes the theme's). Default off: gray, with the accent the only colour. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

### Motion

Scenes move on their [stage's](https://www.youj.dev/docs/illustrations/draw-your-own#assemble-part-and-float) shared springs and clock, so the Speed control and the theme's personality reach them.

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Assemble | `spring.settle`, `stagger.loose` | 0.45s, bounce 0.3; 72ms step | parts drop in, far ones first, the first time the scene is seen |
| Float |  | one bob per 10 × deliberate | the hero part bobs, out of step with its neighbors, paused offscreen |
| Explode | `spring.smooth` | 0.36s, bounce 0 | `explode="hover"`: stacks part and the lit part rises; a reversal carries on from where it is |

**Reduced motion:** The finished scene, drawn once: nothing drops, nothing bobs, and a scene that's apart is shown apart.

#### Reduced motion

Scenes are drawn finished and still. Nothing drops in, nothing bobs, and with `explode` set they're shown apart.

### Accessibility

- Scenes are decorative by default (`aria-hidden`): the words beside them carry the meaning, as in an empty state. Give one a `title`, and a `description` if it needs one, when the picture itself says something, and it becomes a named image.
- The accent marks one part, never the only difference: the lit part is also the one that floats, rises or is named nearby.
- Hues are decoration, not information: every part keeps its shape and its edges in any colour, and with colour off.
- Coming apart on hover is a flourish, not a control: it answers a mouse pointer only.

---

# Draw your own

> Draw isometric scenes of your own with the stage, shapes, exploded stacks and illustration kit that every ready-made scene is built from.

Source: https://www.youj.dev/docs/illustrations/draw-your-own

```tsx
'use client'

import { DotGrid, IsoBox, IsoCylinder, IsoFloor, IsoPlatform, IsoScene, IsoStack } from '@youj/illustrations'

/* An ingest pod: a queue of jobs on a plinth, feeding a worker at its end.
 * It assembles the first time it scrolls into view; hover it to take the
 * worker apart, and its parts are named on the rail beside the drawing. */

const JOBS = [0, 1, 2, 3]

export default function IsoSceneDemo() {
  return (
    <div className="relative isolate mx-auto w-fit max-w-full p-6 sm:p-8">
      <DotGrid gap={18} />
      <IsoScene assemble explode="hover" unit={22} title="An ingest pod: four jobs queued on a plinth, feeding a worker">
        <IsoFloor w={13} d={8} kind="dots" />
        <IsoPlatform x={0.5} y={0.5} w={12} d={7} h={0.4} grid={1}>
          {/* The next job's place in the queue, marked out. */}
          <IsoBox x={1.1} y={4.4} z={0.6} w={1.2} d={1.2} h={0} variant="ghost" />
        </IsoPlatform>
        {JOBS.map((i) => (
          <IsoBox key={i} x={2.9 + i * 1.7} y={4.4} z={0.6} w={1.2} d={1.2} h={0.9} tone={i === JOBS.length - 1 ? 'accent' : 'neutral'} />
        ))}
        <IsoStack
          x={8.4}
          y={1.2}
          z={0.6}
          w={3.2}
          d={2.6}
          gap={1.2}
          layers={[
            { id: 'chassis', h: 0.6, label: 'worker', detail: 'pulls one job at a time' },
            { id: 'runtime', h: 0.3, inset: 0.35, label: 'runtime', detail: 'isolated per job', lit: true },
            { id: 'cover', h: 0.5, variant: 'wire', label: 'cover' },
          ]}
        />
        <IsoCylinder x={5.4} y={1.3} z={0.6} r={0.7} h={0.5} tone="raised" float />
      </IsoScene>
    </div>
  )
}
```

The [ready-made scenes](https://www.youj.dev/docs/illustrations) are drawn with a small kit you can draw with too. Use it when a screen explains a thing: what a device is made of, where a system's parts sit, what an empty warehouse will hold. It draws in isometric, the view of a technical drawing, so parts line up and read at a glance, and every color comes from the theme, so a drawing looks at home in any preset and either scheme. Don't use it for decoration alone. A drawing earns its space by saying something the copy beside it can't.

Four blocks draw with the kit directly, and each is a worked example:

- [First source](https://www.youj.dev/docs/blocks/onboarding-and-states#first-source): a floor with a ghost bay, and the chosen source waiting to land in it.
- [Tiered capacity](https://www.youj.dev/docs/blocks/meters-and-limits): each region's use as a stack of tiers on a plinth.
- [Exploded view](https://www.youj.dev/docs/blocks/media#exploded-view): an exploded view whose layers are named on the rail beside it.
- [Setup picker](https://www.youj.dev/docs/blocks/onboarding-and-states#setup-picker): option cards whose drawings frame alike, so their floors sit on one line.

## The builder

To draw a scene without writing it, use the [illustration builder](https://www.youj.dev/illustrations/build) (experimental). Drag the kit's parts onto the shared 8 × 8 floor: boxes and tiles, cylinders, plinths, prisms with a preset outline, and turned solids. Move them in half units and size them by their handles, or type the numbers. Light the part the scene is about, and give parts a lift for when the scene comes apart and a float. Preview shows it assembling and coming apart, in any preset, light or dark, and as reduced motion draws it.

Then take it home. **Copy code** writes a component the way the scenes below are written: the stage and the kit's shapes, imported from where `npx @youj/cli add illustration-kit iso-shapes` copies them. It draws exactly what the builder showed. The Export panel also downloads the frame as SVG or PNG and copies the scene as JSON. The scene lives in the page's address as you work, so a link opens it again, and the builder keeps your last scene in this browser. Everything works from the keyboard: the layers list chooses parts, the arrows move them on the canvas, and the keyboard button lists the shortcuts.

The builder makes new scenes. The ready-made ones are code, not data, so they open in the [explorer](https://www.youj.dev/illustrations) rather than in the builder.

## What the drawings share

- **Grid units in, pixels out.** You place shapes on a grid (`x` to the lower right, `y` to the lower left, `z` up), and one function, `project`, turns a grid point into a point on screen. Faces, edges, callout anchors and the frame all come from it, so they agree to the pixel.
- **The theme's light.** Every face is mixed from your tokens: the top face lightest, the left a step down, the right the darkest, in both schemes. The accent is kept for the part that matters.
- **One scene, one clock.** Shapes assemble, part and float on motion the scene shares, from the motion tokens, so the Speed control and the theme's personality reach them.
- **Hairlines stay hairlines.** A drawing is crispest at its natural size and scales down to fit a narrow screen. Its lines stay 1 px and its labels keep their size.

## Installation

The kit is `@youj/illustrations`, a package of its own on `@youj/core`: `pnpm add @youj/illustrations`.

```css title="app/globals.css"
@import 'tailwindcss';
@import '@youj/react/styles.css';   /* or '@youj/core/styles.css' without the components */
@import '@youj/illustrations/styles.css';
```

Its sheet points Tailwind at the built scenes, so it generates the classes they use; it goes after the tokens, in the same file. `npx @youj/cli add` adds it for you.

```bash
pnpm add @youj/illustrations
```

```tsx
import { IsoScene } from '@youj/illustrations'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add iso-scene
```

It brings `youj-core` with it.

Import everything below from `@youj/illustrations`. To copy the source in instead, `npx @youj/cli add <item>` copies these items, each bringing what it needs:

| Item | Brings |
| --- | --- |
| `iso-scene` | `IsoScene`, `IsoPiece`, the projection helpers and the face tones |
| `iso-shapes` | `IsoBox`, `IsoCylinder` and `IsoPlatform` |
| `iso-stack` | `IsoStack` and `IsoCallout` |
| `grid-backdrops` | The [backdrops](https://www.youj.dev/docs/illustrations/grid-backdrops) and `IsoFloor` |
| `illustration-kit` | [The illustration kit](#the-illustration-kit): the stage, groups, turned and extruded solids, marks and links. Copy-in only: the package doesn't export it. |

## Examples

### The scene

`IsoScene` is one SVG that holds a drawing. Put shapes inside it: boxes, cylinders and plinths, exploded stacks, a floor grid. The scene decides where they land on screen and in what order they're painted, and gives them one set of motion.

```tsx
import { IsoBox, IsoFloor, IsoPlatform, IsoScene } from '@youj/illustrations'

export function EmptyBay() {
  return (
    <IsoScene title="An empty bay on a plinth" assemble>
      <IsoFloor w={8} d={6} kind="dots" />
      <IsoPlatform x={0.5} y={0.5} w={7} d={5} grid={1}>
        <IsoBox x={3} y={2} z={0.7} w={2} d={2} h={0} variant="ghost" />
      </IsoPlatform>
      <IsoBox x={1} y={1} z={0.7} w={1.5} d={1.5} h={1.2} tone="accent" />
    </IsoScene>
  )
}
```

Shapes are placed in grid units: `x` runs to the lower right, `y` to the lower left and `z` straight up, and `(0, 0, 0)` is the far corner of the floor. A box's `x`, `y` and `z` are its corner nearest the origin, and `w`, `d` and `h` its size along each axis.

#### Framing

The scene frames what's in it. Each shape reports its extent on screen, including where it reaches when it's apart (a stack at full separation, a shape's `lift`, the top of a bob), and the scene's viewBox is the union of those, plus `pad` (one number, or `[top, right, bottom, left]`, in user units). An exploded stack is never clipped, and the drawing stays centered in its container whatever it holds.

Scenes that must line up, such as a row of option cards, frame alike with `size`: a volume in grid units, `[w, d, h]`, that each scene frames instead of its content, so their floors sit on one line and their shapes at one scale. Every ready-made illustration frames the same volume this way, which is why one swaps for another.

```tsx
'use client'

import { IsoBox, IsoCylinder, IsoFloor, IsoScene, IsoStack } from '@youj/illustrations'

/* Three small scenes that must line up in a row. Fitted to their content,
 * each would frame differently; `size` gives them one volume, so their
 * floors sit on the same line and their shapes at the same scale. */

const SIZE = [4, 4, 3.4] as const

export default function IsoSceneFraming() {
  return (
    <div className="mx-auto grid w-fit max-w-full grid-cols-3 gap-3 p-6">
      <figure className="rounded-xl border border-line bg-canvas p-3">
        <IsoScene size={SIZE} unit={20} pad={8}>
          <IsoFloor w={4} d={4} />
          <IsoBox x={1} y={1} w={2} d={2} h={1.2} />
        </IsoScene>
      </figure>
      <figure className="rounded-xl border border-line bg-canvas p-3">
        <IsoScene size={SIZE} unit={20} pad={8}>
          <IsoFloor w={4} d={4} />
          <IsoCylinder x={1} y={1} r={1} h={2.2} tone="accent" />
        </IsoScene>
      </figure>
      <figure className="rounded-xl border border-line bg-canvas p-3">
        <IsoScene size={SIZE} unit={20} pad={8}>
          <IsoFloor w={4} d={4} />
          <IsoStack
            x={0.8}
            y={0.8}
            w={2.4}
            d={2.4}
            layers={[
              { id: 'a', h: 0.5 },
              { id: 'b', h: 0.5, inset: 0.2 },
              { id: 'c', h: 0.5, inset: 0.4 },
            ]}
          />
        </IsoScene>
      </figure>
    </div>
  )
}
```

A drawing is crispest at its natural size, where one grid unit is `unit` CSS px (24 by default). In a narrower container it scales down to fit; with `grow` it also scales up to fill a wider one. Either way, its hairlines stay 1 px and its labels keep their size: the scene writes its scale to `--kg-px` (user units per CSS px), and the strokes and text are sized by it. Below about three quarters of its natural size, callouts drop their detail lines and keep their names.

#### Painter's order

SVG paints in document order, so nearer shapes must come later. The scene sorts its direct children that are shapes far to near with `isoSort` before it paints them, so you can write a scene in any order. Anything else keeps its place: write the floor first and it stays under everything, write an `IsoCallout` last and it stays on top. Shapes drawn as another shape's children (a chip on a board) are painted with their parent, after it.

Two boxes are ordered when one lies wholly behind the other along an axis. When neither does (they interpenetrate) or a rare cycle of long boxes forms, the one whose center is farther goes first.

#### The rail

When a shape names its parts (an [exploded stack](#exploded-stacks) with labeled layers, or an `IsoCallout`), the scene keeps a rail beside the drawing, `rail` CSS px wide (168 by default) at every scale, at the end of the line: on the right, or on the left on an RTL page. Leaders run from the parts to the rail's edge, and the labels stand in it, so a label never sits on the geometry. Each label has a knockout halo in the surface color; set `--kg-halo` on the scene when it sits on another color. `rail={false}` leaves the rail out.

#### Assemble, part and float

- **Assemble.** With `assemble`, shapes drop in from above the first time the scene scrolls into view, far ones first, a stack's layers one after another. Each lands on the `settle` spring, the arrival moment the motion tokens keep a little overshoot for, and fades in on the enter curve.
- **Separation.** `explode` is one value from 0 (together) to 1 (apart) that stacks and any shape's `lift` follow. Give it a number, a boolean, or `"hover"`, which parts the drawing while a mouse pointer is over it. It moves on the `smooth` spring, so changing it mid-way turns the parts round from where they are, with no jump.
- **Float.** Shapes with `float` bob gently on one clock the scene runs only while one is mounted and the scene is on screen, each a little out of step with the next.

### Shapes

```tsx
'use client'

import { IsoBox, IsoCylinder, IsoPlatform, IsoScene } from '@youj/illustrations'

/* A bench of parts on a gridded plinth: a solid enclosure with a board on
 * its top face, a wireframe spare beside it, a lit spool, a wire canister,
 * and a ghost where the next enclosure goes. */

export default function IsoShapesDemo() {
  return (
    <div className="mx-auto w-fit max-w-full p-6 sm:p-8">
      <IsoScene unit={24} assemble>
        <IsoPlatform x={0} y={0} w={11} d={7} h={0.5} grid={1}>
          <IsoBox x={7.6} y={3.8} z={0.7} w={2.6} d={2.4} h={0} variant="ghost" />
        </IsoPlatform>
        <IsoBox x={0.9} y={0.9} z={0.7} w={3} d={2.6} h={1.3}>
          {/* Children draw on the top face and move with it. */}
          <IsoBox x={1.2} y={1.2} z={2} w={1.6} d={1.2} h={0.12} tone="raised" />
          <IsoBox x={3.1} y={1.3} z={2} w={0.5} d={0.5} h={0.18} tone="accent" />
        </IsoBox>
        <IsoBox x={4.6} y={0.9} z={0.7} w={2.2} d={2.6} h={1.3} variant="wire" />
        <IsoCylinder x={1.2} y={4.2} z={0.7} r={1} h={0.9} tone="accent" />
        <IsoCylinder x={4.3} y={4.2} z={0.7} r={1} h={1.6} variant="wire" />
      </IsoScene>
    </div>
  )
}
```

Three shapes build most drawings. `IsoBox` is a box, or a tile when it has no height. `IsoCylinder` is a cylinder, or a disc. `IsoPlatform` is a plinth for the rest to stand on.

```tsx
import { IsoBox, IsoCylinder, IsoPlatform, IsoScene } from '@youj/illustrations'

export function Bench() {
  return (
    <IsoScene>
      <IsoPlatform x={0} y={0} w={8} d={5} grid={1} />
      <IsoBox x={1} y={1} z={0.7} w={3} d={2} h={1.2} />
      <IsoCylinder x={5} y={1.5} z={0.7} r={0.9} h={1.6} tone="accent" />
    </IsoScene>
  )
}
```

A box is placed by its corner nearest the origin (`x`, `y`, `z`) and sized along each axis (`w`, `d`, `h`). A cylinder stands in the square footprint from `x, y` to `x + 2r, y + 2r`, so a cylinder of radius 1 at `(4, 4)` is centered on `(5, 5)`, and it sorts beside boxes by that footprint.

#### Faces from your tokens

Every face is mixed from the theme's tokens at paint time, so a drawing re-colors with the theme and needs no JavaScript to do it. Light comes from above and a little to the left: the top face is the lightest, the left face a step down and the right face the darkest. The same holds in the dark scheme, where each face is a lift of the surface toward the ink rather than a shade of it, and a light scope inside a dark page shades itself correctly.

```tsx
'use client'

import { IsoBox, IsoFloor, IsoScene, type IsoTone } from '@youj/illustrations'

/* Every tone in the same light: top lightest, left a step down, right the
 * darkest, in either scheme. The last three take any CSS color; token
 * references (the chart palette here) follow the theme. */

const TONES: IsoTone[] = ['neutral', 'raised', 'sunken', 'accent', 'success', 'warning', 'danger']
const SERIES = ['var(--color-chart-2)', 'var(--color-chart-3)', 'var(--color-chart-4)']

export default function IsoShapesTones() {
  return (
    <div className="mx-auto w-fit max-w-full p-6">
      <IsoScene unit={20}>
        <IsoFloor w={(TONES.length + SERIES.length) * 2.6 + 0.6} d={3.2} />
        {TONES.map((tone, i) => (
          <IsoBox key={tone} x={0.6 + i * 2.6} y={0.6} w={2} d={2} h={1.6} tone={tone} />
        ))}
        {SERIES.map((color, i) => (
          <IsoBox key={color} x={0.6 + (TONES.length + i) * 2.6} y={0.6} w={2} d={2} h={1.6} color={color} />
        ))}
      </IsoScene>
    </div>
  )
}
```

- **`tone`** picks the color: `neutral` (the default), `raised` (a lighter object, for the thing in hand), `sunken` (a darker one, for bases and wells), `accent`, or a status ink, `success`, `warning` or `danger`. The accent is for the part that matters. One lit part reads; three compete.
- **`hue`** (`1`, `2` or `3`) gives a neutral tone one of the scene's [colours](https://www.youj.dev/docs/illustrations#colour): the theme's pair (derived from the accent, softened under it) or the scene's own `colors`. It takes effect when the scene has `colors`; without them the part shows its `tone`. The tone still shades it, so a `raised` part is a step lighter. The ready-made scenes colour their subject this way and leave plinths and bases neutral.
- **`color`** takes any CSS color and derives the three faces from it: lifted on top, as given on the left, shaded on the right. Token references follow the theme, so `color="var(--color-chart-2)"` paints a chart series in its own shade in every preset.
- The colors are custom properties on the shape's group (`--kg-top`, `--kg-left`, `--kg-right`, `--kg-edge`, `--kg-lit`), so a `style` can override any of them. `faceVars(tone, variant, color)` returns the same set, for a part you draw yourself.

#### Solid, wire and ghost

- **`solid`** (the default) fills the faces, rules every edge with a hairline, and lights the two near edges of the top face, the way a machined edge catches the light.
- **`wire`** draws a wireframe: the faces a breath of color, the edges strong, and the hidden edges dashed. Use it for a cover you can see through, a part that isn't there yet, or a technical view. With a `tone` or `color`, the lines take it.
- **`ghost`** is only a dashed outline: a place something will go, such as an empty bay or the next item in a queue. At `h={0}` it's a dashed footprint on the floor.

`hidden` turns the dashed hidden edges on or off for any variant.

#### Tiles, discs and parts on top

A box with `h={0}` is a tile, and a cylinder with `h={0}` a disc: flat marks on a plane, such as a pad, a label plate or a status light. A shape's children draw on its top face and move with it, so parts placed on a board travel with the board when it rises, and don't drop in on their own when the scene assembles. Children are placed in the scene's coordinates: on a board 0.4 high, a part sits at `z={0.4}`.

```tsx
<IsoBox x={0} y={0} w={6} d={4} h={0.4} tone="sunken">
  <IsoBox x={0.5} y={0.5} z={0.4} w={2} d={2} h={0.3} tone="raised" />
  <IsoCylinder x={4} y={1} z={0.4} r={0.25} h={0} tone="success" />
</IsoBox>
```

#### Plinths

`IsoPlatform` is a base slab with a thinner plate set in from its edge by `inset`, so the edge reads as a lip. It's `sunken` by default, so what stands on it carries the light. A square plinth can engrave its plate with a `grid` in the scene's own units, so shapes placed on whole numbers line up with its lines. `shape="round"` makes a turntable of two tiers. Its children draw on the plate, which is where ghost bays go.

Every shape also takes `float` (a gentle bob, `true` or its height in grid units) and `lift` (how far it rises, in grid units, at the scene's full separation).

### Exploded stacks

```tsx
'use client'

import { useState } from 'react'
import { IsoBox, IsoScene, IsoStack, LineGrid } from '@youj/illustrations'

/* An e-reader, taken apart. The separation springs to the toggle's value, so
 * pressing it again mid-way turns the parts round from where they are. The
 * display is the part that matters here: it's lit, and the rest dim. */

export default function IsoStackDemo() {
  const [apart, setApart] = useState(true)
  return (
    <div className="relative isolate mx-auto w-fit max-w-full p-6 sm:p-8">
      <LineGrid gap={20} />
      <IsoScene explode={apart} unit={26} title="An e-reader, exploded: back cover, battery, logic board, display and front glass">
        <IsoStack
          x={0}
          y={0}
          w={4.4}
          d={3.2}
          gap={1.25}
          dim
          layers={[
            { id: 'back', h: 0.35, label: 'back cover', detail: 'recycled aluminum' },
            { id: 'battery', h: 0.3, inset: 0.35, label: 'battery', detail: '1,700 mAh' },
            {
              id: 'board',
              h: 0.12,
              inset: 0.25,
              label: 'logic board',
              detail: 'one SoC, no fan',
              content: ({ x, y, z }) => (
                <>
                  <IsoBox x={x + 0.4} y={y + 0.4} z={z} w={1.1} d={1.1} h={0.12} tone="raised" />
                  <IsoBox x={x + 1.8} y={y + 0.5} z={z} w={0.6} d={0.9} h={0.08} />
                </>
              ),
            },
            { id: 'display', h: 0.14, label: 'display', detail: '7 in, 300 ppi', lit: true },
            { id: 'glass', h: 0.12, variant: 'wire', label: 'front glass', detail: 'etched, anti-glare' },
          ]}
        />
      </IsoScene>
      <button
        type="button"
        aria-pressed={apart}
        onClick={() => setApart((a) => !a)}
        className="mx-auto mt-4 flex rounded-full border border-line bg-surface px-3.5 py-1.5 text-sm font-medium text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
      >
        {apart ? 'Put it together' : 'Take it apart'}
      </button>
    </div>
  )
}
```

Use `IsoStack` to explain what a thing is made of: a device's layers, a product's tiers, a system's parts. Together, it's one object. As the scene's separation rises, each layer rises in proportion to its height in the stack, so the top goes furthest, and each named layer gets a callout on the scene's [rail](#the-rail). Light one layer to say which part the screen is about.

```tsx
import { IsoScene, IsoStack } from '@youj/illustrations'

export function BatteryModule() {
  return (
    <IsoScene explode="hover" title="A battery module: base plate, cells and cover">
      <IsoStack
        x={0}
        y={0}
        w={4}
        d={3}
        layers={[
          { id: 'base', h: 0.6, label: 'base plate', detail: 'aluminium, 3 mm' },
          { id: 'cells', h: 0.9, inset: 0.25, label: 'cell pack', detail: '4 × 21700', lit: true },
          { id: 'cover', h: 0.8, variant: 'wire', label: 'cover' },
        ]}
      />
    </IsoScene>
  )
}
```

Layers go bottom to top. Each has an `id`, a height `h`, and optionally an `inset` (a board inside its case sits in from the stack's footprint), a `tone`, `color` or `variant`, a `label` and `detail` for its callout, `lit`, and `content`: a function that gets the layer's top footprint in grid units and draws on it, moving with the layer.

#### Taking it apart

The stack follows its scene's `explode`: a number from 0 to 1, a boolean, or `"hover"`. At full separation each layer has traveled its index times `gap` grid units along `axis` (`z` by default: straight up), and the scene frames that reach, so the stack never clips. The value moves on the `smooth` spring, so reversing it mid-way, from a toggle or a pointer leaving, turns the layers round from where they are.

Drive it from a control when readers need it, as the demo's toggle does: hover answers a mouse pointer only.

```tsx
import { useState } from 'react'
const [apart, setApart] = useState(true)

<IsoScene explode={apart}>…</IsoScene>
<button aria-pressed={apart} onClick={() => setApart((a) => !a)}>Take it apart</button>
```

`axis="x"` or `"y"` lays the layers out side by side instead, for a sequence rather than an assembly. Callouts are drawn for `z`.

#### Callouts

Along `z`, each layer with a `label` gets a callout: a dot at the layer's outermost point, at half its height, and a hairline leader to the edge of the scene's rail, where its name stands in small mono capitals with the `detail` below in a quieter ink. The callouts fade in as the layers part and out as they come together: assembled, the thing is one object, and its parts aren't named. A `lit` layer takes the accent, with a solid leader and an accent label; `dim` quiets the other layers around it.

`IsoCallout` names any other point: give it a grid point `at`, a `label` and an optional `detail`, and write it after the shapes, so it's painted on top. Its leader runs to the same rail.

```tsx
'use client'

import { IsoBox, IsoCallout, IsoCylinder, IsoScene } from '@youj/illustrations'

/* IsoCallout names any point, not just a stack's layers: here the status
 * light and the uplink port of a small router. Each leader runs to the rail. */

export default function IsoStackCallout() {
  return (
    <div className="mx-auto w-fit max-w-full p-6">
      <IsoScene unit={28}>
        <IsoBox x={0} y={0} w={4.4} d={3} h={0.9}>
          <IsoCylinder x={3.6} y={0.3} z={0.9} r={0.2} h={0.05} tone="success" />
          <IsoBox x={0.4} y={0.4} z={0.9} w={2.2} d={0.6} h={0.04} tone="sunken" />
        </IsoBox>
        <IsoCallout at={[3.8, 0.5, 0.95]} label="status" detail="green: online" lit />
        <IsoCallout at={[4.4, 1.5, 0.45]} label="uplink" detail="2.5 GbE" />
      </IsoScene>
    </div>
  )
}
```

#### Disks

`shape="disk"` stacks cylinders instead of slabs: a puck, a lens, a round sensor. A disk takes the smaller of `w` and `d` as its diameter, and its leader leaves from the rim.

```tsx
'use client'

import { IsoScene, IsoStack } from '@youj/illustrations'

/* A charging puck in disks, parted on hover. Only the coil is named in the
 * accent; `dim` quiets the rest around it. */

export default function IsoStackDisks() {
  return (
    <div className="mx-auto w-fit max-w-full p-6">
      <IsoScene explode="hover" unit={26} assemble>
        <IsoStack
          x={0}
          y={0}
          w={3.6}
          d={3.6}
          shape="disk"
          gap={1.1}
          dim
          layers={[
            { id: 'foot', h: 0.3, label: 'foot', detail: 'silicone, non-slip' },
            { id: 'coil', h: 0.25, inset: 0.35, label: 'coil', detail: '15 W, Qi2', lit: true },
            { id: 'magnets', h: 0.15, inset: 0.2, label: 'magnet ring' },
            { id: 'cap', h: 0.3, variant: 'wire', label: 'cap' },
          ]}
        />
      </IsoScene>
    </div>
  )
}
```

### The illustration kit

The ready-made scenes add a few pieces on top of the shapes, and they're yours to draw with. They are copy-in only, as the item `illustration-kit` (every `illustration-<id>` brings it along), which the CLI writes to `components/youj/graphics/illustrations/kit.tsx` beside the scenes. The package draws its scenes with them but doesn't export them.

```bash
npx @youj/cli add illustration-kit
```

- **`IllustrationStage`** is the stage every scene draws on: an `IsoScene` framed to the shared volume (`VOLUME`, an 8 × 8 floor with room above it), with no rail, assembling by default, and decorative unless titled. It takes the scene props (`IllustrationProps`) and an `id`. Draw on it and your scene swaps with any ready-made one without the layout moving.
- **`Group`** holds several shapes that drop, bob and rise as one object (a rocket, a figure), painted far to near among themselves. It takes `float`, `lift` and `delay`, extra steps of stagger in the assemble.
- **`Lathe`** turns a profile about an axis: a cup, a bulb, a globe. The profile is `[radius, height]` pairs from the bottom up; it stands on `z` by default, and `axis="x"` or `"y"` lays it down, its end facing you. `convex` outlines it as the hull of its rings, exact for a solid that bulges; `orb(r)` is a ball's profile.
- **`Prism`** extrudes a profile toward you from a plane: a heart, a speech bubble, a roof. Its front face takes the plane's shade, each side is shaded by the way it faces, and its children draw on the front face.
- **`Mark`** is a flat mark on a face or the floor: a label, a door, a glyph. Draw it as a shape's child so it moves with the shape.
- **`Link`** is a hairline through points in the scene: a cable, a route, a drop line. `lit` draws it in the accent and `dashed` dashes it.
- **`Hollow`** is the inside of an open box, seen through its opening: the two far walls and the floor, clipped to the rim. Draw it as the box's child.

Marks and prisms are drawn on a plane, in plane units from the point `at`: the `top` plane runs along `x` and `y`, the `left` face (the one toward `+y`) runs `x` along and `z` up, and the `right` face (toward `+x`) runs `y` along and `z` up. `rect`, `rounded`, `circle`, `arc`, `band`, `curve` and `smooth` make the points; `flat(x, y)` places a point on a top face as it should look on screen, for a glyph that must read upright, such as a check. `INK` holds the inks for marks, which read on any face in either scheme. `bob(props, height)` is the float for a scene's hero part, and `false` when the scene was asked to hold still, so a scene of your own answers `float={false}` as the ready-made ones do.

```tsx
import { IsoPlatform } from '@/components/youj/graphics/iso-platform'
import { bob, circle, INK, IllustrationStage, Lathe, Mark, type IllustrationProps } from '@/components/youj/graphics/illustrations/kit'

/** A jar on its plinth, and its lid in the accent, lifting off when it's taken apart. */
export function IllustrationJar(props: IllustrationProps) {
  const [cx, cy] = [4, 4]
  return (
    <IllustrationStage id="jar" {...props}>
      <IsoPlatform x={1} y={1} w={6} d={6} shape="round" />
      <Lathe cx={cx} cy={cy} z={0.7} profile={[[1.1, 0], [1.3, 0.4], [1.3, 1.6], [1, 1.9]]} convex />
      <Lathe cx={cx} cy={cy} z={2.6} profile={[[1.05, 0], [1.05, 0.35]]} tone="accent" float={bob(props, 0.12)} lift={0.8}>
        <Mark plane="top" at={[cx, cy, 2.95]} points={circle(0, 0, 0.6)} stroke={INK.line} closed />
      </Lathe>
    </IllustrationStage>
  )
}
```

The kit is copied source. In an app set up from source it imports the scene and the shapes from beside it; in an app on the packages `npx @youj/cli add` copies it and the shapes (`iso-shapes`, `grid-backdrops`) too, their scene pointed at `@youj/illustrations`. Either way, draw with what `add` wrote: a stage from one copy and shapes from another don't share a scene.

### Drawing by hand

Anything you draw inside a scene can use its maths. `useIsoScene()` returns the scene's `unit`, its separation and clock, and the rail's position; `useIsoPoint(x, y, z)` turns a grid point into a point on screen. Wrap a hand-drawn part in `IsoPiece` to give it the same drop, `lift` and `float` as the built-in shapes.

```tsx
import { IsoPiece, useIsoPoint } from '@youj/illustrations'

function Beacon({ x, y, z }: { x: number; y: number; z: number }) {
  const [cx, cy] = useIsoPoint(x, y, z)
  return (
    <IsoPiece float>
      <circle cx={cx} cy={cy} r={3} style={{ fill: 'var(--color-accent)' }} />
    </IsoPiece>
  )
}
```

A component that should be sorted and framed like a shape carries static `isoBounds(props)` (its box at rest) and `isoFit(props, unit)` (its screen extent, apart); `isoRail(props)` returning true asks for the rail. The type `IsoShape` describes them.

The same functions the shapes use, for drawing by hand or laying out data:

| Helper | What it gives |
| --- | --- |
| `project(x, y, z, unit)` | the screen point of a grid point, in user units |
| `axisStep(axis, unit)` | the screen direction of one grid unit along `x`, `y` or `z` |
| `boxFaces(bounds, unit)` | a box's top, left and right faces as point lists |
| `isoEllipse(cx, cy, z, r, unit)` | the screen ellipse a level circle projects to (its height is its width × tan 30°) |
| `isoSort(items, boundsOf)` | items in painter's order, far to near |
| `sceneViewBox(size, unit, pad)` | the viewBox that holds a volume, plus padding |
| `toPoints(points)` | a point list as a polygon's `points` attribute |

```tsx
import { boxFaces, isoSort, project, toPoints } from '@youj/illustrations'

const [x, y] = project(2, 1, 0.5, 24) // [20.78, 24]
const { top } = boxFaces({ x: 0, y: 0, z: 0, w: 2, d: 2, h: 1 }, 24)
const face = <polygon points={toPoints(top)} />
const ordered = isoSort(racks, (rack) => rack.bounds)
```

## Reference

### Props

#### IsoScene

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `size` | `IsoSize` |  | Frame this volume, in grid units: [w (x), d (y), h (z)], instead of fitting the shapes. For scenes that must frame alike (a row of option cards). |
| `unit` | `number` | `24` | User units per grid unit: the drawing's natural size, in CSS px. |
| `pad` | `ScenePad` | `16` | Room round the drawing, in user units: one number, or [top, right, bottom, left]. |
| `rail` | `number \| false` | `168` | Width of the callout rail beside the drawing, CSS px, when a shape names its parts; false for none. |
| `title` | `string` |  | Names the drawing for assistive tech; without it the scene is decorative (aria-hidden). |
| `description` | `string` |  | A longer description, read after the title. |
| `assemble` | `boolean` | `false` | Shapes drop in, far ones first, the first time the scene comes into view. |
| `explode` | `number \| boolean \| 'hover'` | `0` | Separation for IsoStack layers and shapes with `lift`: a number from 0 to 1, a boolean, or 'hover' (apart while the pointer is over the scene). |
| `grow` | `boolean` | `false` | Scale up past the natural size to fill a wider box. |
| `colors` | `readonly string[] \| 'theme'` |  | Colour for shapes that carry a `hue`: 'theme' for the theme's pair (derived from the accent), or any CSS colours for hue 1, 2 and 3 in order (an empty entry takes the theme's). Default off: gray, with the accent the only colour. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

Also takes the props of `SVGProps<SVGSVGElement>`.

#### IsoPiece

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `lift` | `number` | `0` | How far it rises at full separation, in grid units along z (IsoStack sets this per layer). |
| `float` | `boolean \| number` | `false` | Bob gently: true, or the height of the bob in grid units. |
| `delay` | `number` | `0` | Extra delay in the assemble, in stagger steps (a stack's layers land one after another). |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

#### IsoBox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` (required) | `number` |  | Size along x, y and z, in grid units. `h` 0 draws only the top: a tile. |
| `d` (required) | `number` |  |  |
| `h` (required) | `number` |  |  |
| `x` (required) | `number` |  | The near-origin corner, in grid units. |
| `y` (required) | `number` |  |  |
| `z` | `number` | `0` | Height of its base above the floor. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `color` | `string` |  | Any CSS color for the faces (token references such as `var(--color-chart-2)` stay in step with the theme); it wins over `tone`. |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours: the faces take it when the scene has `colors`, and show `tone` otherwise. |
| `variant` | `'solid' \| 'wire' \| 'ghost'` |  |  |
| `hidden` | `boolean` |  | Draw the hidden edges, dashed. Default: true for a wireframe or a ghost. |
| `float` | `boolean \| number` |  | Bob gently: true, or the bob's height in grid units. |
| `lift` | `number` |  | Rise this far (grid units) at the scene's full separation. |
| `children` | `ReactNode` |  | Drawn on the top face, moving with the shape: tiles, cylinders, marks. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

#### IsoCylinder

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `r` (required) | `number` |  | Radius in grid units; the footprint is 2r on a side. |
| `h` (required) | `number` |  | Height in grid units; 0 draws a disc. |
| `x` (required) | `number` |  | The near-origin corner, in grid units. |
| `y` (required) | `number` |  |  |
| `z` | `number` | `0` | Height of its base above the floor. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `color` | `string` |  | Any CSS color for the faces (token references such as `var(--color-chart-2)` stay in step with the theme); it wins over `tone`. |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours: the faces take it when the scene has `colors`, and show `tone` otherwise. |
| `variant` | `'solid' \| 'wire' \| 'ghost'` |  |  |
| `hidden` | `boolean` |  | Draw the hidden edges, dashed. Default: true for a wireframe or a ghost. |
| `float` | `boolean \| number` |  | Bob gently: true, or the bob's height in grid units. |
| `lift` | `number` |  | Rise this far (grid units) at the scene's full separation. |
| `children` | `ReactNode` |  | Drawn on the top face, moving with the shape: tiles, cylinders, marks. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

#### IsoPlatform

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` (required) | `number` |  | Footprint along x and y, grid units. A round plinth takes the smaller as its diameter. |
| `d` (required) | `number` |  |  |
| `h` | `number` | `0.5` | The base slab's height. |
| `shape` | `'box' \| 'round'` |  |  |
| `inset` | `number` | `0.35` | How far the plate sits in from the base's edge. |
| `lip` | `number` | `0.2` | The plate's height; 0 leaves a single slab. |
| `grid` | `number` |  | Engrave the plate with a grid at this spacing (grid units), square plinths only. Default none. |
| `children` | `ReactNode` |  | Drawn on the plate's top face. |
| `float` | `boolean \| number` |  | Bob gently: true, or the bob's height in grid units. |
| `className` | `string` |  |  |
| `color` | `string` |  | Any CSS color for the faces (token references such as `var(--color-chart-2)` stay in step with the theme); it wins over `tone`. |
| `style` | `CSSProperties` |  |  |
| `x` (required) | `number` |  | The near-origin corner, in grid units. |
| `y` (required) | `number` |  |  |
| `z` | `number` | `0` | Height of its base above the floor. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours: the faces take it when the scene has `colors`, and show `tone` otherwise. |
| `variant` | `'solid' \| 'wire' \| 'ghost'` |  |  |
| `hidden` | `boolean` |  | Draw the hidden edges, dashed. Default: true for a wireframe or a ghost. |
| `lift` | `number` |  | Rise this far (grid units) at the scene's full separation. |

#### IsoStack

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` (required) | `number` |  |  |
| `y` (required) | `number` |  |  |
| `z` | `number` |  |  |
| `w` (required) | `number` |  | Footprint along x and y, grid units. Disks take the smaller as their diameter. |
| `d` (required) | `number` |  |  |
| `layers` (required) | `readonly IsoStackLayer[]` |  | Bottom to top. |
| `shape` | `"box" \| "disk"` |  |  |
| `gap` | `number` | `1.4` | The distance each layer adds at full separation, grid units. |
| `axis` | `"x" \| "y" \| "z"` | `'z'` | The direction the layers part in. Callouts are drawn for z. |
| `variant` | `'solid' \| 'wire' \| 'ghost'` | `'solid'` | The layers' variant when they don't set one. |
| `dim` | `boolean` | `false` | Dim the other layers while one is lit. |
| `className` | `string` |  |  |

#### Stack layer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `h` (required) | `number` |  | Height in grid units. |
| `inset` | `number` | `0` | Brings the footprint in on every side (a board inside its case), grid units. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `color` | `string` |  |  |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours (see IsoBox's `hue`). |
| `variant` | `'solid' \| 'wire' \| 'ghost'` |  |  |
| `label` | `string` |  | The callout's label, a mono capital eyebrow, and a quieter line under it. |
| `detail` | `string` |  |  |
| `lit` | `boolean` |  | Emphasize this layer: the accent, a solid leader. |
| `content` | `(top: { x: number; y: number; z: number; w: number; d: number; }) => ReactNode` |  | Drawn on the layer's top face, moving with it: chips, vents, a port. Gets the layer's top footprint in grid units. |

#### IsoCallout

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` (required) | `readonly [x: number, y: number, z: number]` |  | The point it marks, in grid units. |
| `label` (required) | `string` |  |  |
| `detail` | `string` |  |  |
| `lit` | `boolean` |  |  |

> **Copy-in only from here down:** Group, Lathe, Prism, Mark and Link come with the copied kit (`npx @youj/cli add illustration-kit`); `@youj/illustrations` doesn't export them.

#### Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `float` | `boolean \| number` |  | Bob as one object: true, or the bob's height in grid units. |
| `lift` | `number` |  | Rise this far (grid units) at the scene's full separation. |
| `delay` | `number` |  | Extra delay in the assemble, in stagger steps. |

#### Lathe

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cx` (required) | `number` |  | The center of its footprint, grid units. Laid down, where its axis starts. |
| `cy` (required) | `number` |  |  |
| `z` | `number` | `0` | Height of its base. Laid down, the height of its axis. |
| `profile` (required) | `readonly (readonly [r: number, h: number])[]` |  | Its outline, bottom up: [radius, height above the base] at each step, heights rising. Laid down, the heights run along the axis. |
| `axis` | `'x' \| 'y' \| 'z'` |  | The axis it's turned about: 'z' stands it up (the default); 'x' or 'y' lays it down along +x or +y, its end facing you. |
| `convex` | `boolean` |  | Outline it as the hull of its rings: exact for a convex solid (a globe, a dome, a cup), and always so when it's laid down. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours (see IsoBox's `hue`). |
| `float` | `boolean \| number` |  |  |
| `lift` | `number` |  |  |
| `children` | `ReactNode` |  |  |

#### Prism

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `plane` (required) | `'top' \| 'left' \| 'right'` |  | The plane its profile lies in. It's extruded toward you along the plane's normal: up from the top plane, +y from the left, +x from the right. |
| `at` (required) | `readonly [number, number, number]` |  | The plane's origin, grid units: the back of the solid. |
| `points` (required) | `readonly PlanePoint[]` |  | Its profile, in plane units, as a Mark's points. Curves are fine: fine steps shade smoothly, and only corners and the silhouette get a line. |
| `depth` (required) | `number` |  | How far it's extruded, grid units. |
| `tone` | `'neutral' \| 'raised' \| 'sunken' \| 'accent' \| 'success' \| 'warning' \| 'danger'` |  |  |
| `hue` | `1 \| 2 \| 3` |  | One of the scene's colours (see IsoBox's `hue`). |
| `float` | `boolean \| number` |  |  |
| `lift` | `number` |  |  |
| `children` | `ReactNode` |  | Drawn on its front face, moving with it: marks on the plane `depth` in front of `at`. |

#### Mark

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `plane` (required) | `'top' \| 'left' \| 'right'` |  |  |
| `at` (required) | `readonly [number, number, number]` |  | The plane's origin, in grid units. |
| `points` (required) | `readonly PlanePoint[]` |  | The outline, in plane units. |
| `fill` | `string` |  |  |
| `stroke` | `string` |  |  |
| `dashed` | `boolean` |  |  |
| `closed` | `boolean` |  | Join the last point to the first. Default: true when filled. |
| `weight` | `number` |  | Stroke width in CSS px at any scale. Default 1, a hairline. |
| `opacity` | `number` |  |  |

#### Link

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` (required) | `readonly (readonly [number, number, number])[]` |  | The path's corners, in grid units. |
| `lit` | `boolean` |  |  |
| `dashed` | `boolean` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Assemble | `spring.settle`, `stagger.loose` | 0.45s, bounce 0.3; 72ms step | each shape drops from 3 grid units above, far ones first; a stack’s layers land bottom first |
| Assemble fade | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | opacity, with the drop |
| Separation | `spring.smooth` | 0.36s, bounce 0 | `explode`, `"hover"` and `lift`, translate only; a stack’s layers by their index × `gap` |
| Callouts |  | follows the separation | opacity, from 30% to 75% of the separation |
| Float |  | one bob per 10 × deliberate | a sine bob, out of step with its neighbors, paused offscreen |

**Reduced motion:** The final state, drawn once: nothing drops, nothing bobs, and the separation jumps to its target, so a drawing that's apart is shown apart, with its callouts.

#### Reduced motion

The scene draws its final state and holds it. Shapes that would assemble are already in place, a scene set apart is shown apart with its callouts, one set together is drawn together, and nothing floats or fades. Switch on Reduced motion in the previews above to compare.

### Accessibility

- A scene is decorative by default: the SVG is `aria-hidden` and not focusable. Keep what it shows in the text around it.
- When the drawing carries meaning the text doesn't, give it a `title` (and a `description` for more). It becomes `role="img"`, named by its `<title>` and described by its `<desc>`. For a stack, a title that lists the parts, as the demo's does.
- Hover to part is a flourish, not a control: it answers a mouse pointer only. Put anything a reader needs behind a real control, as the stack demo's toggle does.
- Labels and callouts are real SVG text in the theme's inks, read with the scene when it's a named image. They keep their CSS size when the drawing scales down; keep them short, a name and a detail of a few words.
- Don't make color the only difference. A ghost is dashed as well as pale, a lit layer's leader is solid where the others are dashed, and a lit part should also be named in the text or a callout.

---

# Grid Backdrops

> Add dot, line or isometric grids behind your content using theme colors.

Source: https://www.youj.dev/docs/illustrations/grid-backdrops

```tsx
'use client'

import { DotGrid, IsoGrid, LineGrid } from '@youj/illustrations'

/* The three papers, each filling its panel behind the caption and fading
 * toward the edges. */

const PANELS = [
  { name: 'Dot grid', Grid: DotGrid },
  { name: 'Line grid', Grid: LineGrid },
  { name: 'Iso grid', Grid: IsoGrid },
]

export default function GridBackdropsDemo() {
  return (
    <div className="grid w-full gap-3 p-6 sm:grid-cols-3">
      {PANELS.map(({ name, Grid }) => (
        <figure key={name} className="relative isolate grid h-44 place-items-center overflow-hidden rounded-xl border border-line bg-surface">
          <Grid gap={20} />
          <figcaption className="font-mono text-xs tracking-[0.12em] text-fg-muted uppercase">{name}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

A grid tells the reader they're looking at a drawing: something measured, with parts in their places. Put one behind an isometric scene, a hero figure, or an empty state's illustration. Use one grid per surface, and keep it faint: it's paper, not content.

## Installation

```bash
pnpm add @youj/illustrations
```

```tsx
import { DotGrid, LineGrid, IsoGrid } from '@youj/illustrations'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add grid-backdrops
```

It brings `youj-core`, `iso-scene` with it.

## Usage

Each backdrop fills its nearest positioned ancestor and paints behind the content, like the [background components](https://www.youj.dev/docs/components/mesh-gradient), so give the container `relative isolate`.

```tsx
import { IsoScene, IsoStack, LineGrid } from '@youj/illustrations'

export function Figure() {
  return (
    <figure className="relative isolate rounded-xl border border-line bg-surface p-8">
      <LineGrid gap={20} />
      <IsoScene explode>…</IsoScene>
    </figure>
  )
}
```

- **`DotGrid`**: dots on a square grid, `gap` px apart, of radius `size`.
- **`LineGrid`**: hairlines `gap` px apart, a stronger line every `major` cells, and a small registration cross where two strong lines meet. `major={0}` leaves only the fine lines.
- **`IsoGrid`**: the isometric rhombi of a scene's floor, one grid unit every `gap` px, for a backdrop that shares the drawing's angles.

## Examples

### Fading

`fade` sets how a backdrop meets the edge of its container. `radial` (the default) fades out from the middle, so the paper is densest behind the figure. `edges` fades a band along each side and keeps the middle even, for a wide panel. `none` runs it to the edge, for a container that clips it with its own border.

### A scene's floor

`IsoFloor` goes inside an [IsoScene](https://www.youj.dev/docs/illustrations/draw-your-own#the-scene): the scene's own grid on the floor, in its units, from the origin to `w` by `d`, every `step` units. Shapes placed on whole numbers stand on its lines. Draw it first, so it stays under the shapes, as lines or, with `kind="dots"`, as dots at the crossings.

```tsx
'use client'

import { IsoBox, IsoFloor, IsoScene } from '@youj/illustrations'

/* IsoFloor draws a scene's own grid in its units, so shapes land on its
 * lines: the same slab on lines, and on dots at the crossings. */

export default function GridBackdropsFloor() {
  return (
    <div className="mx-auto grid w-fit max-w-full grid-cols-2 gap-6 p-6">
      <IsoScene unit={22}>
        <IsoFloor w={6} d={5} />
        <IsoBox x={1} y={1} w={3} d={2} h={1} />
      </IsoScene>
      <IsoScene unit={22}>
        <IsoFloor w={6} d={5} kind="dots" />
        <IsoBox x={1} y={1} w={3} d={2} h={1} tone="accent" />
      </IsoScene>
    </div>
  )
}
```

### Color

The lines and dots are the ink at a low strength over transparent, so they read on a surface, a raised panel or the canvas, in either scheme and every preset, and a theme change repaints them with no JavaScript.

## Reference

### Props

#### DotGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `1` | Dot radius, CSS px. |
| `gap` | `number` | `16` | Distance between grid points or lines, CSS px. |
| `fade` | `'none' \| 'edges' \| 'radial'` | `'radial'` | Fade out toward the edges ('edges'), from the center ('radial'), or not at all. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

#### LineGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `major` | `number` | `4` | A stronger line every this many cells, with a registration cross where two meet; 0 for none. |
| `gap` | `number` | `24` | Distance between grid points or lines, CSS px. |
| `fade` | `'none' \| 'edges' \| 'radial'` | `'radial'` | Fade out toward the edges ('edges'), from the center ('radial'), or not at all. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

#### IsoGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `gap` | `number` | `24` | Distance between grid points or lines, CSS px. |
| `fade` | `'none' \| 'edges' \| 'radial'` | `'radial'` | Fade out toward the edges ('edges'), from the center ('radial'), or not at all. |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

Also takes the props of `SVGProps<SVGSVGElement>`.

#### IsoFloor

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` (required) | `number` |  | The floor's extent in grid units, from the origin. |
| `d` (required) | `number` |  |  |
| `step` | `number` | `1` | Grid spacing in grid units. |
| `kind` | `'lines' \| 'dots'` | `'lines'` | Draw lines, or dots at the crossings. |
| `className` | `string` |  |  |

### Reduced motion

Nothing here moves, so there's nothing to stop: a backdrop looks the same with reduced motion on.

### Accessibility

- Backdrops are decorative: each is `aria-hidden` and ignores pointer events.
- They sit at a low strength, but check the contrast of any text you set over the densest part of a grid.

---

# Loaders

> Loaders are loading animations with depth, drawn in your theme. Particle fields in perspective, wireframes and lit solids, waveforms, the youj letterforms and moments from the tools people wait in, each a polite status and a still frame under reduced motion.

Source: https://www.youj.dev/docs/loaders

```tsx
'use client'

import { LoaderBuild } from '@youj/loaders/build'
import { LoaderInscribe } from '@youj/loaders/inscribe'
import { LoaderSustain } from '@youj/loaders/sustain'
import { LoaderTittle } from '@youj/loaders/tittle'

/* Four of the set, one from each corner of it, each a polite status with its
 * label shown under it and moving in time with its loop: the youj o in depth,
 * a field of waveforms, the wordmark inscribing itself (its label typed) and
 * a build going through its stages. Solid planes paint over --yj-anim-paper,
 * set here to the canvas they sit on. */

export default function AnimationsDemo() {
  return (
    <div className="grid gap-x-16 gap-y-8 p-6 text-sm [--yj-anim-paper:var(--color-canvas)] sm:grid-cols-2 sm:p-8">
      <LoaderTittle size="lg" label="Loading" showLabel />
      <LoaderSustain size="lg" label="Listening" showLabel />
      <LoaderInscribe size="lg" label="Writing" showLabel labelEffect="type" />
      <LoaderBuild size="lg" label="Building" showLabel />
    </div>
  )
}
```

When something takes a moment (a workspace being prepared, a model thinking, a build, an upload), show it at work. Each loader is a small scene in perspective, drawn live in your text color with one mark in your accent and a few touches of your theme's colors, on the motion tokens' tempo. It's a status that announces its label politely, and under reduced motion it holds one still frame that still reads as busy.

The [loaders gallery](https://www.youj.dev/loaders) shows every one of them live: filter them by category, set the size, the length of a loop, the colors and the labels, then copy the code or the install command.

> **New:** Loaders are new. The set is still growing, and a loader may be refined or renamed before 1.0.

## The set

| Category | What it draws |
| --- | --- |
| Color | Built around your theme's colors: hue travelling through a structure, layered tints, color as state |
| Depth | Particle fields in perspective, nearer marks larger and brighter |
| Geometry | Wireframes, planes lit by their facets, surfaces drawn in lines |
| Signal | Waveforms and live data, drawn as they arrive |
| Glyph | The youj letterforms, drawing, turning and assembling |
| Interface | Cursors, focus rings, pipelines and construction marks |

### Every loader

A loader's id is its entry, `@youj/loaders/<id>`, and its component is `Loader` and the id in PascalCase (`tittle` is `LoaderTittle`). The ids, by category:

| Category | Ids |
| --- | --- |
| Color | `prism` `overprint` `spectrum` `gyre` `bloom` `litmus` `weave` `swatch` `beacon` `chord` `isotherm` |
| Depth | `tittle` `drop` `layers` `corridor` `slice` `vortex` `murmur` `reeve` |
| Geometry | `nacre` `draft` `carton` `extrude` `section` `ridge` `contour` `pleat` `lathe` `saddle` `torsion` `facet` `core` `band` `curl` `tenon` `selvedge` `meniscus` `atlas` `arbor` `banyan` `tessera` `vault` `knead` `lacuna` `stave` `suture` `ravel` `throat` `truss` `mosaic` `tributary` `alveole` `calyx` `quarry` `newel` `infill` `atrium` `shingle` `carve` `lamella` `simplex` `ashlar` `laminate` `loft` `stayed` `reciprocal` `envelope` `retile` `cupola` `coarea` `corbel` `notch` `datum` `arris` `cast` `ogive` |
| Orbs | `gores` `lamina` `vesicle` `cleave` `chordal` `armature` `brim` `cincture` `respire` `pith` |
| Mechanics | `mesh` `dwell` `yoke` `impulse` `iris` `tackle` `heddle` `gimbal` `lattice` `siphon` `detent` `bellows` `tread` `fulcrum` `auger` `epicycle` `bolus` `nutate` |
| Science | `ligate` `valence` `halite` `chaperone` `lobule` `chamber` `adduct` `exchange` `kekule` `catenate` |
| Waves | `fulgur` `tensor` `duplex` `chirp` `overtone` `fletch` `sounding` `evanesce` `bragg` `whisper` |
| Signal | `cue` `phosphor` `sustain` `isobar` `tail` `tempo` `locus` `vitals` `harmonics` `delta` `least-squares` `bell` `spool` `wick` `caustic` `umbra` `flux` `fringe` `capillary` `refract` `azimuth` `apsis` `nodal` `analyzer` `descent` `quantile` `leader` `overturn` `barcode` `blossom` |
| Glyph | `inscribe` `jot` `spell` `compose` `kern` `hint` `plumb` |
| Interface | `marquee` `tabstop` `build` `prompt` `measure` `register` `queue` `gantry` `sift` `conflux` `parity` `stow` `fathom` `refine` `lexicon` `raster` `alcove` `escrow` `sachet` `swizzle` `medoid` `schema` `prefix` `trellis` `collate` `docket` `stencil` `coalesce` `folio` `occlude` `accord` `tensile` `adjoint` `isoline` `radix` `pivot` `stride` `bisect` `reduce` `meander` `entail` `condense` `minify` `traverse` `splice` `salvage` |
| Software | `mullion` `tangent` `scion` `quire` `graft` `verdict` `chorus` `casement` `cadence` `ledger` `winnow` `offshoot` `outpost` `amanuensis` `valance` `pipette` `portico` `raccord` `elide` `attest` `satchel` |

## Installation

### From the package

Every loader ships in `@youj/loaders`, at its own entry, as `Loader` and its name:

```bash
pnpm add @youj/loaders
```

```tsx
import { LoaderTittle } from '@youj/loaders/tittle'
```

### One loader, as source

To own and edit one loader, copy it in with the Youj CLI in an app set up from source (`npx @youj/cli init --mode registry`). Every loader is its own item, `loader-<id>`. It brings the kit the loaders are drawn with (`loader-kit`: the status, the shared ticker and the engine that draws in depth) and nothing else. In an app on the packages, the same command installs `@youj/loaders` instead and names the entry to import:

```bash
npx @youj/cli add loader-tittle
```

It lands in `components/youj/loaders/<category>/<id>.tsx`, and you import it from there through your `@/` alias:

```tsx
import { LoaderTittle } from '@/components/youj/loaders/depth/tittle'
```

Each loader's id, import and install command are on its card in the [gallery](https://www.youj.dev/loaders).

## Usage

```tsx
import { LoaderSustain } from '@youj/loaders/sustain'

export function Transcript({ busy }: { busy: boolean }) {
  if (busy) return <LoaderSustain size="lg" label="Transcribing" showLabel />
  // …
}
```

### Size

`size` is the drawing's height: `sm` (24px, beside text), `default` (40px, in a control or a card), `lg` (64px, on a panel) or any number of pixels. The wordmark loaders and most of the signals are wider than they are tall. Each draws for its size: fewer, bolder marks when it's small, finer detail when it's large.

### Color

A loader's structure is drawn in its ink, the text color (`currentColor`) by default, so it takes the color of whatever it sits in; `color` sets it to any CSS color, token references included. Its accent is on the one mark that matters (lit accent faces included) and in a shown label's light and caret: the theme's accent by default, and `accentColor` sets it the same way.

That is all a loader uses unless you ask for more. Pass `colors="theme"` and a few parts take colors derived from your accent: what moves or works (a trail, a path being traced) in one, a second layer in another, and a finished state (a check, an arrival) in your success color. The color is quiet: thin marks and small particles, never more than about a third of the drawing, and it moves with the loop, a part warming toward its color on the beat, new marks arriving in color and settling to the ink, a hue travelling once through a structure. The colors are muted and follow your theme's accent, in light and dark, so the accent stays the brightest thing in the drawing.

```tsx
'use client'

import { LoaderGantry } from '@youj/loaders/gantry'
import { LoaderPrompt } from '@youj/loaders/prompt'
import { LoaderTabstop } from '@youj/loaders/tabstop'

/* Loaders in the theme's colors: a few parts that mean something (a
 * prompt and its check, a button and a tick, a machine and its plot) in
 * the theme's roles, the accent still the brightest mark. `colors="theme"`
 * turns them on, and a list of colors sets them; without it a loader
 * keeps its two colors, the ink and the accent. */

export default function MulticolorLoaders() {
  return (
    <div className="grid gap-x-12 gap-y-8 p-6 text-sm [--yj-anim-paper:var(--color-canvas)] sm:grid-cols-3 sm:p-8">
      <LoaderPrompt size="lg" colors="theme" label="Installing" showLabel />
      <LoaderTabstop size="lg" colors="theme" label="Checking the form" showLabel />
      <LoaderGantry size="lg" colors="theme" label="Laying out" showLabel />
    </div>
  )
}
```

```tsx
<LoaderIsobar color="var(--color-fg-muted)" />
<LoaderTittle color="var(--color-fg-muted)" accentColor="var(--color-success)" />
```

`colors` is off by default: a loader draws in its ink and its accent alone. `colors="theme"` turns the colored parts on in the theme's colors. A list sets their colors instead, in order, with any CSS color or token reference; an empty entry, or one you leave out, keeps the theme color. A loader without colored parts ignores it. A loader's parts are named in the [gallery](https://www.youj.dev/loaders), whose Color control switches between Mono (the default) and Theme and, with Theme on, picks each part's color.

```tsx
<LoaderPrompt colors="theme" />
<LoaderGantry colors={['var(--color-fg-muted)', 'var(--color-success)']} />
<LoaderGantry colors={['', 'var(--color-success)']} />
```

Solid planes and lit faces hide what's behind them by painting on a paper: `--yj-anim-paper`, the surface by default. On another background, set it to that background, so the faces sit on what's really there:

```tsx
<div className="bg-canvas [--yj-anim-paper:var(--color-canvas)]">
  <LoaderCarton size="lg" />
</div>
```

### Pace

A loop lasts a few beats of the `deliberate` duration, so the theme's personality and the provider's time scale reach it: in a precise theme a beat is 560ms, and a loop takes a few seconds. `speed` multiplies on top (2 is twice as fast). A change of speed carries on from the frame it's on, and `paused` holds the frame.

### Announcing the wait

The status is named by `label`, "Loading" by default (from the [labels](https://www.youj.dev/docs/guides/i18n), so it's translated with the rest). When something around it already says what's happening (a button that reads "Saving…"), pass `label={null}` and the loader is only a picture.

### Showing the label

`showLabel` shows the label with the drawing: centered under it by default, in the theme's label voice, with the space between them (and on a large drawing, the type) growing with `size`. `labelPosition` puts it over the drawing (`top`), or beside it, before (`start`) or after (`end`) it in the reading direction, so it changes sides in a right-to-left language. Beside the drawing it takes the text style of the line it sits in. Over or under it, one loader's label can take its own type through the theme's label properties and `--yj-label-size`: `className="[--yj-label-case:uppercase] [--yj-label-font:var(--font-mono)] [--yj-label-size:15px]"`.

```tsx
<LoaderBuild size="lg" label="Building" showLabel />
<LoaderTittle size="sm" label="Syncing" showLabel labelPosition="end" />
```

A shown label moves in time with the drawing, on its clock: it holds when the drawing is paused or off screen, and keeps its pace through `speed` and the time scale. `labelEffect` picks how:

| Effect | What it does |
| --- | --- |
| `pulse` (default) | A soft light, the ink with a touch of the accent, sweeps through the muted label once a loop, then rests. |
| `wave` | A gentle lift travels through the letters, first to last, once a loop, then rests. |
| `type` | The label types itself a letter at a time behind a square-cornered caret in the accent, holds while the caret blinks, and is cleared by the caret gliding home, so each loop starts on an empty line. |
| `scramble` | The line fills with glyph noise and the letters resolve out of it one at a time, first to last; the word holds, then breaks back into noise that clears before the loop ends. |
| `slide` | At the loop's seam the line rolls up, like a counter: the label rises out as the next rises in. It's made for [several labels](#rotating-labels); one label rolls over to itself. |
| `none` | The label holds still. |

```tsx
<LoaderPrompt size="lg" label="Thinking" showLabel labelEffect="type" />
```

The drawn label is only a picture of the words: assistive technology hears the plain label once, never letters arriving. It's static in the server's HTML, and starts moving at a moment of the loop that looks just like it, so nothing jumps when the script arrives. In a right-to-left language the effects run from the right. Letters move one by one (`wave`, and `scramble`'s noise) only in scripts whose letters stand on their own; a joined script such as Arabic keeps its letters whole, `wave` passing a light through the word and `scramble` resolving it as a plain reveal.

### Rotating labels

A wait that takes a while can say more than one thing. Give `label` a list, and a shown label turns through it: each one shows for `labelEvery` loops (one by default), and the next takes over at the loop's seam, the effect carrying the change: the light dips, the letters lift away and rise in, the caret clears one and types the next, the noise resolves into it, or the line rolls up. Then it starts again from the first.

```tsx
'use client'

import { LoaderBuild } from '@youj/loaders/build'
import { LoaderSustain } from '@youj/loaders/sustain'
import { LoaderTittle } from '@youj/loaders/tittle'

/* Waits that say more than one thing: each animation turns through its
 * labels, the next taking over at the loop's seam (the second label of the
 * last after two loops), each change carried by its effect. The status says
 * the first, and only now and then a later one. */

export default function RotatingLabels() {
  return (
    <div className="grid gap-x-12 gap-y-8 p-6 text-sm [--yj-anim-paper:var(--color-canvas)] sm:grid-cols-3 sm:p-8">
      <LoaderBuild size="lg" label={['Building', 'Bundling', 'Optimizing images', 'Deploying']} showLabel labelEffect="slide" />
      <LoaderSustain size="lg" label={['Listening', 'Transcribing', 'Summarizing']} showLabel labelEffect="scramble" />
      <LoaderTittle size="lg" label={['Loading', 'Generating results', 'Almost there']} labelEvery={2} showLabel labelEffect="wave" />
    </div>
  )
}
```

```tsx
<LoaderBuild
  size="lg"
  label={['Building', 'Bundling', 'Optimizing images', 'Deploying']}
  showLabel
  labelEffect="slide"
/>

<LoaderTittle
  size="lg"
  label={['Loading', 'Generating results', 'Almost there']}
  labelEvery={2}
  showLabel
  labelEffect="wave"
/>
```

The labels sit in one place as wide as the longest, so nothing around them moves as they change. The status doesn't read each one out: it says the first, then a later one only as it shows, in order, once each and at least ten seconds after the last, and then it stays quiet, however long the wait. When the state really changes (an upload finishes and processing starts), pass a new `label`: that's said at once. Without `showLabel`, the labels still take turns for assistive technology the same way. Under reduced motion the first label shows, still, and stays.

### Performance

Each loader draws on one small canvas, on a ticker every loader on the page shares, and only while it's on screen in a visible tab: offscreen, hidden or paused, it costs nothing. Its colors are read once, and again when the theme changes. The server sends its still frame as SVG, so it's never blank before the script runs.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `LoaderSize` | ``default`` | The drawing's height: `sm`, `default` or `lg`, or px. |
| `color` | `string` |  | The primary color: its ink. Any CSS color, token references included (`var(--color-fg-muted)`). Default: the text color. |
| `accentColor` | `string` |  | The secondary color: the accent, on the one mark that matters (lit accent faces included) and in a shown label's light and caret. Any CSS color or token reference. Default: the theme's accent. |
| `colors` | `readonly string[] \| 'theme'` |  | Turns color on for the loader's colored parts (its extra tones; see its docs for which is which). `'theme'` gives each its theme color, derived from the accent; a list gives them any CSS colors or token references, in part order, an empty or missing entry keeping the theme color. Left out, it draws in its two colors only, the ink (`color`) and the accent (`accentColor`). A loader without colored parts ignores it. |
| `speed` | `number` | `1` | Playback rate over the theme's tempo: 2 is twice as fast, 0.5 half. It multiplies with the provider's time scale. |
| `label` | `string \| readonly string[]` |  | The accessible name, announced politely: one label, or several that take turns (a shown label rotates through them, one every `labelEvery` loops; the status says the first, then a later one only now and then). Default: the `loading` label, "Loading". `null` when something around it already announces the wait. |
| `labelEvery` | `number` | `1` | With several labels: how many loops each one shows for before the next takes over, at the seam. |
| `showLabel` | `boolean` | `false` | Shows the label with the drawing, not only to assistive technology. |
| `labelPosition` | `'bottom' \| 'top' \| 'start' \| 'end'` | ``bottom`` | Where a shown label sits: centred under the drawing (`bottom`) or over it (`top`), or beside it, before (`start`) or after (`end`) it in the reading direction. |
| `labelEffect` | `'pulse' \| 'wave' \| 'type' \| 'scramble' \| 'slide' \| 'none'` | ``pulse`` | How a shown label moves, in time with the loop, and changes to the next: `pulse` sweeps a soft light through it once a loop; `wave` lifts its letters in a gentle wave; `type` types it behind an accent caret and clears it at the seam; `scramble` resolves it from glyph noise, first letter to last; `slide` rolls the line up at the seam; `none` holds it still. Under reduced motion it's still. |
| `paused` | `boolean` | `false` | Holds the current frame. |
| `fps` | `number` |  | The most frames a second it draws: a cap for ambient use (a loader that plays for a long time beside others), where 30 looks the same at a fraction of the cost. Time still runs at the drawing's tempo. Default: every frame the screen shows. |

Also takes the props of `HTMLAttributes<HTMLSpanElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Loop | `duration.deliberate` | 560ms; × 2.25 to 6.5 beats per loop | the whole scene, seamless: its last frame is its first |
| Moves | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1) | travel with intent: a cursor, a fold, a plate coming into register |
| Arrivals | `ease.enter` | cubic-bezier(0.16, 1, 0.3, 1) | what lands or settles: a tittle, a packet, a closing lid |
| Departures | `ease.exit` | cubic-bezier(0.4, 0, 1, 1) | what lets go or leaves the frame |
| Label pulse | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1) | a soft light crosses the shown label once a loop, then rests |
| Label wave |  | a raised cosine per letter | a lift of a fifth of an em travels through the letters, first to last, no overshoot |
| Label type | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1) | a letter at a time at an even cadence, then the caret glides home, taking the word before the seam |
| Label scramble | `ease.linear` | cubic-bezier(0, 0, 1, 1) | noise fills the line, the letters lock in one at a time at an even cadence, then break back into noise |
| Label slide | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1) | at the seam the line rolls up through a soft-edged window the height of the line |
| Next label | `duration.deliberate` | 560ms; × the loop | at the seam, every labelEvery loops; the effect carries the change |

**Reduced motion:** One still frame, chosen to read as busy (mid-move, its depth showing), drawn as SVG. Nothing moves, a shown label holds still (the first of several, which don't turn), and the label is still announced.

#### Reduced motion

It holds one still frame that still reads as busy: mid-move, with its depth showing. It's the same SVG the server sends, so nothing moves and nothing flashes when the script arrives. A shown label stays whole and still: no light, no lift, no caret, no noise. Of several labels, the first shows and stays: a caption that kept changing on its own would be just the distraction reduced motion asks to be spared, and the first label already says what's happening.

### Accessibility

- Each loader is `role="status"` with `aria-live="polite"`, named by its label: assistive technology hears "Loading" (or your label) once, not the drawing, which is `aria-hidden`.
- A shown label is drawn `aria-hidden` too: the status keeps the plain label as its name and what it announces, so a typed or scrambled label is never read out letter by letter.
- Several labels don't make a talkative status: it says the first, then a later one only as it shows, in order, once each and at least ten seconds apart, then stays quiet. A new `label` is said at once.
- `label={null}` makes it decorative (`aria-hidden`, no status), for when the thing around it already announces the wait.
- The accent and the theme's colors mark parts of the drawing, never the only difference: the drawing reads the same without `colors` and in forced colors.
- It shows that something is happening, not how far along it is: when you know, show a [Progress](https://www.youj.dev/docs/components/progress).

---

# Motion

> Animate your interface with shared timing, speed controls and reduced-motion support.

Source: https://www.youj.dev/docs/motion

Use shared durations, curves, springs and stagger steps to animate your own elements. `YoujProvider` controls speed and reduced motion across them. This section covers those settings and the animation tools that use them. For ready-made UI, see [Components](https://www.youj.dev/docs/components).

## Foundations

- [Motion principles](https://www.youj.dev/docs/motion/principles): The rules behind every piece, shown as live pairs.

- [Motion tokens](https://www.youj.dev/docs/motion/tokens): Every duration, easing, spring and stagger step, with the time scale and reduced motion.

- [Motion playground](https://www.youj.dev/docs/motion/playground): Every spring, tween, stagger, personality and preset on a stage, with the code it takes.

- [Motion in your components](https://www.youj.dev/docs/motion/in-your-components): useYouj, the provider and the CSS utilities, for motion of your own.

- [Overlay presets](https://www.youj.dev/docs/motion/presets): CSS utilities that animate Base UI's popovers, dialogs, sheets and toasts.

Sound has a section of its own: components emit cues as their motion starts, and [`@youj/sound`](https://www.youj.dev/docs/sound) plays them.

## Pieces

- [Primitives](https://www.youj.dev/docs/motion/primitives): Reveals, text, numbers, loops and scroll: small pieces you wrap around your content.

- [Transitions](https://www.youj.dev/docs/motion/transitions): The motion inside components: gliding indicators, morphing labels, height and lists.

- [Entrances](https://www.youj.dev/docs/motion/entrances): Build real UI in front of the viewer, part by part, ending on the real thing.

---

# Motion principles

> The motion principles behind Youj shown side by side, then a duration and curve for each kind of interaction, reduced motion, and when to leave content still.

Source: https://www.youj.dev/docs/motion/principles

Youj uses short, precise motion to show what changed. These principles explain when to animate, how to time it and how to keep the result clear. Further down, the guidelines pick a duration and a curve for each interaction and check how it behaves with reduced motion. Those values are tokens, so they follow the theme's motion settings and Speed; try them in the [Motion playground](https://www.youj.dev/docs/motion/playground).

## Shown, not described

Each pair plays the same moment twice: once in the Youj language, and once the way it usually goes wrong. The "don't" side deliberately uses values that aren't tokens, and it still follows the time scale, so the comparison stays fair.

## Timing lives in tokens

No component hard-codes a duration or a curve. Every value comes from one set of motion tokens, and every component reads it through `useYouj()`, so tuning a token retunes the whole library. The durations form a short geometric scale, and anything that answers direct input finishes within `base`. Feedback takes the `snappy` spring, layout changes `smooth`, and only success and arrival get `settle`, the one spring that overshoots.

[Motion tokens](https://www.youj.dev/docs/motion/tokens) lists every duration, easing, spring and stagger step, with which one each moment takes and how the time scale and reduced motion reach them.

## In code

Timing comes from the hook, never from literals.

```tsx
import { m } from 'motion/react'
import { MotionFeatures, useYouj } from '@youj/core'

export function Panel({ open }: { open: boolean }) {
  const k = useYouj()
  return (
    <MotionFeatures>
      <m.div
        animate={{ opacity: open ? 1 : 0, y: open ? 0 : 8 }}
        transition={k.reduced ? { duration: 0 } : k.tween('base', open ? 'enter' : 'exit')}
      />
    </MotionFeatures>
  )
}
```

- `k.tween(duration, ease)` and `k.spring(token)` return ready Motion transitions.
- `k.stagger(token)` is a step in seconds, and `k.ms(token)` a duration in milliseconds for CSS, WAAPI and `requestAnimationFrame` code.
- `k.reduced` is true when motion should give way to an instant or static alternative.
- `k.timeScale` multiplies every duration. Loops and shaders divide elapsed time by it.

In CSS, use the `yj-duration-*` utilities (`yj-duration-fast` and its siblings) with the `ease-standard`, `ease-enter`, `ease-exit` and `ease-emphasized` utilities. They follow the provider's speed and reduced motion. The raw `var(--yj-duration-fast)` follows the speed but not reduced motion, so keep it for loops you stop yourself.

## Durations by interaction

| Interaction | Band | Tokens | Curve |
| --- | --- | --- | --- |
| Press and hover (buttons, rows, tints, focus rings) | 80–140 ms | press in on `instant`, out on `fast`; hover `fast` | `standard` |
| Toggle and select (switches, checkboxes, tabs, segments) | 200–360 ms | a thumb on `spring.snappy`; an indicator on `spring.smooth` | spring, no overshoot |
| Tooltip (`yj-tooltip`) | 80–140 ms | in on `fast`, out on `instant` | `enter` in, `exit` out |
| Menu and popover (menus, selects, popovers: `yj-pop`) | 80–140 ms | in on `fast`, out on `instant` | `enter` in, `exit` out |
| Dialog and sheet (`yj-dialog`, `yj-sheet-*`, toasts) | 140–340 ms | a dialog `base` in, `fast` out; a sheet or toast `slow` in | `enter` in, `exit` out |
| List insert, remove, reorder (PresenceList rows, cards) | 140–360 ms | in on `base`, out on `fast`, moves on `spring.smooth`; `stagger.base` between | `enter`, `exit`, spring |
| Page and hero (route changes, a landing reveal) | 340–560 ms | `slow` for a route, `deliberate` for a hero | `emphasized` |
| Success and arrival (a save lands, a task completes) | 450 ms | `spring.settle` | the one overshoot |

Three rules hold the table together:

- **Feedback lands within `base`.** The answer to a press, a toggle or a menu shows inside `base` (220 ms with the `precise` character, 300 ms with `calm`, 190 ms with `lively`), even while an indicator is still gliding. Later than that reads as lag, however good the curve.
- **Farther is longer, never slow.** A sheet crossing the screen gets `slow`; nothing a person waits on gets more than `deliberate`.
- **Out is shorter than in.** An exit takes the next token down and accelerates away on `exit`. Nobody waits for something to leave.

Springs for anything that can be interrupted or moves with the hand: toggles, indicators, rows that reorder. Tweens for things that come and go on their own: overlays, toasts, entrances. `settle`'s one overshoot is for a success or an arrival, once per moment.

## Should this animate?

1. **Does it explain a change?** Motion earns its place by showing where something came from, where it went or what changed. Decoration gets one moment per screen, if any.
2. **Will people see it all day?** The more often it plays, the shorter it gets. A menu opened fifty times a day pops in on `fast`; a list that filters as you type doesn't animate its results at all.
3. **Is anyone waiting on it?** Motion never delays input or content. Start on the press, not the release, and let the next action interrupt it from where it is.
4. **Does it hold up at ¼ speed and under reduced motion?** If a state only makes sense while it's moving, the design is in the motion, not the state. Fix the state.
5. **Is something else already moving?** One focal motion at a time. A second competes; a third is noise.

## Reduced motion: keep the meaning, remove the travel

Under reduced motion nothing travels, scales or bounces, and nothing is lost: every state still changes, the same words and icons appear, focus moves and announcements are made. It isn't motion switched off. It's a designed state.

- **Do:** reduced: the toast is simply there.
- **Don't:** reduced: the toast still slides in.

How Youj does it:

- **In JavaScript**, `useYouj().reduced` is true when the OS asks or a provider sets `reducedMotion="always"`. Components render their end state and swap every transition for `{ duration: 0 }`.
- **In CSS**, every overlay preset and `yj-duration-*` utility multiplies its token by `--yj-motion`, which is 0 when reduced, so transitions become instant state changes and Base UI unmounts at once.
- **Loops** stop on a designed frame; live data still updates, in steps. **Pointer and scroll effects** switch off.
- **Direct manipulation** still follows the finger: a swiped sheet or toast tracks it, because that isn't animation.

## Do and don't

### Grow from the trigger

An overlay scales from where it was asked for, so the eye never has to find it.

- **Do:** grows from its trigger: `yj-pop`, `fast` · `enter`.
- **Don't:** grows from the middle of the page, 360 ms.

### Move only what changed

A new row enters and the others make room. Replaying every entrance on every change says everything changed.

- **Do:** the new row enters, the rest make room.
- **Don't:** every row plays its entrance again.

### Hover keeps up with the pointer

A hover state is where the pointer is, now. A slow fade leaves a trail of half-lit rows.

- **Do:** the highlight is where the pointer is, on `fast`.
- **Don't:** a 400 ms fade trails behind the pointer.

To feel every token against its curve, open the [Motion playground](https://www.youj.dev/docs/motion/playground).

---

# Motion tokens

> Reference for the motion tokens: every duration, easing curve, spring and stagger step, per motion personality, with the time scale and reduced motion.

Source: https://www.youj.dev/docs/motion/tokens

Every animation in Youj takes its timing from a small set of motion tokens: five durations, five easing curves, three springs and three stagger steps. No component hard-codes a duration or a curve, so the time scale, reduced motion and the theme's motion personality reach all of them. The token names are the contract; their values come from the [motion personality](#motion-personalities) in effect.

The values below are read from the [token source](https://github.com/youj-dev/ui/blob/main/packages/core/src/lib/youj/tokens.ts) and the stylesheet that mirrors it, so they match the version these docs describe.

## Which token for which moment

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Feedback | `spring.snappy` | 0.2s, bounce 0 | presses, toggles, icon states |
| Layout | `spring.smooth` | 0.36s, bounce 0 | position and size changes |
| Arrival and success | `spring.settle` | 0.45s, bounce 0.3 | the one earned overshoot |
| Hover and focus | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | tints, rings |
| Enter | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | decelerate hard into place |
| Exit | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | shorter, accelerating away |
| Hero | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | wind up, fast middle, long landing |
| Cascade | `stagger.base` | 40ms step | one gesture, not a queue |

**Reduced motion:** Every token has an instant counterpart. Transitions become state changes, loops stop, and scroll and pointer effects switch off, while the information stays the same.

The [Motion principles](https://www.youj.dev/docs/motion/principles) give a duration and a curve for each kind of interaction, and the [Motion playground](https://www.youj.dev/docs/motion/playground) plays every token against its curve.

## Durations

Durations form a short, roughly geometric scale. Anything that answers direct input, like a press or a toggle, finishes within `base`. Values are in milliseconds, before the time scale.

| Token | Precise | Calm | Lively | CSS |
| --- | --- | --- | --- | --- |
| `instant` | 80ms | 110ms | 70ms | `yj-duration-instant`, `var(--yj-duration-instant)` |
| `fast` | 140ms | 190ms | 120ms | `yj-duration-fast`, `var(--yj-duration-fast)` |
| `base` | 220ms | 300ms | 190ms | `yj-duration-base`, `var(--yj-duration-base)` |
| `slow` | 340ms | 460ms | 290ms | `yj-duration-slow`, `var(--yj-duration-slow)` |
| `deliberate` | 560ms | 760ms | 480ms | `yj-duration-deliberate`, `var(--yj-duration-deliberate)` |

## Easings

Easing curves are cubic-bezier control points. Use `enter` for things arriving, `exit` for things leaving, and `standard` between two resting states.

| Token | Precise | Calm | Lively | Use it for |
| --- | --- | --- | --- | --- |
| `standard` | `cubic-bezier(0.2, 0, 0, 1)` | `cubic-bezier(0.4, 0, 0.2, 1)` | `cubic-bezier(0.2, 0, 0, 1)` | Moving between two resting states. `ease-standard` |
| `enter` | `cubic-bezier(0.16, 1, 0.3, 1)` | `cubic-bezier(0.33, 1, 0.68, 1)` | `cubic-bezier(0.34, 1.3, 0.64, 1)` | Arriving: decelerates hard into place. `ease-enter` |
| `exit` | `cubic-bezier(0.4, 0, 1, 1)` | `cubic-bezier(0.4, 0, 0.6, 1)` | `cubic-bezier(0.4, 0, 1, 1)` | Leaving: accelerates away. `ease-exit` |
| `emphasized` | `cubic-bezier(0.6, 0, 0.1, 1)` | `cubic-bezier(0.65, 0, 0.35, 1)` | `cubic-bezier(0.6, 0, 0.2, 1.15)` | Hero moments: a short wind-up, a fast middle, a long landing. `ease-emphasized` |
| `linear` | `cubic-bezier(0, 0, 1, 1)` | `cubic-bezier(0, 0, 1, 1)` | `cubic-bezier(0, 0, 1, 1)` | Constant-rate loops, such as spinners and marquees. |

## Springs

Springs are defined by how long they feel (`visualDuration`, in seconds) and how much they bounce, not by stiffness and damping, so the time scale reaches them like everything else. They're for JavaScript animations, through `k.spring()`; CSS has no spring tokens.

| Token | Precise | Calm | Lively | Use it for |
| --- | --- | --- | --- | --- |
| `snappy` | 0.2s, bounce 0 | 0.3s, bounce 0 | 0.18s, bounce 0.15 | Feedback: presses, toggles, icon state flips. |
| `smooth` | 0.36s, bounce 0 | 0.5s, bounce 0 | 0.32s, bounce 0.12 | Layout and position changes. |
| `settle` | 0.45s, bounce 0.3 | 0.6s, bounce 0 | 0.4s, bounce 0.4 | Success and arrival: the one allowed overshoot. |

Under the default personality, `snappy` and `smooth` never overshoot, and `settle` overshoots once, by about 4.6%. Keep it for success and arrival: a save confirmation earns it, a menu opening doesn't.

## Stagger

The step between siblings in a sequence, in milliseconds. A cascade should read as one gesture, not a queue.

| Token | Precise | Calm | Lively |
| --- | --- | --- | --- |
| `tight` | 24ms | 34ms | 20ms |
| `base` | 40ms | 56ms | 32ms |
| `loose` | 72ms | 100ms | 56ms |

On a device in the low [motion budget](https://www.youj.dev/docs/motion/in-your-components#the-motion-budget) tier, [Stagger](https://www.youj.dev/docs/motion/stagger) and [Text Split](https://www.youj.dev/docs/motion/text-split) compress sequences longer than six steps into six.

## Motion personalities

A theme picks one personality, and it re-values every token above. The names never change.

- **Precise** is the default and the values the package exports as `durations`, `easings`, `springs` and `staggers`. It's fast and lands precisely, with overshoot only on `settle`. All four presets use it.
- **Calm** is about 1.4× longer, with gentle curves at both ends and no overshoot anywhere, `settle` included.
- **Lively** is about 15% shorter. Arrivals overshoot by about 3%, and springs keep a little bounce.

Set it with a theme's `motionPersonality` field (`defineTheme({ ...basalt, motionPersonality: 'calm' })`; it was `motion` before 0.1, which `YoujProvider` now uses only for on and off), or in CSS with a `data-yj-motion` attribute on `<html>` or any element. `motionPersonalities` holds all three sets in JavaScript. [Theming](https://www.youj.dev/docs/theming#motion-personality) covers it in full.

## Time scale

`YoujProvider`'s `timeScale` multiplies every duration, spring and stagger step: `2` plays everything twice as slowly. It's what the Speed control on every preview changes. The nearest provider wins, so a subtree can run at its own speed.

```tsx
import { YoujProvider } from '@youj/core'

<YoujProvider timeScale={2}>{children}</YoujProvider>
```

In CSS, the provider sets `--yj-time-scale` on its wrapper, and each `--yj-duration-*` is the personality's value times it. Loops, canvas and shader code divide elapsed time by `k.timeScale` themselves, as [Motion in your components](https://www.youj.dev/docs/motion/in-your-components#loops-canvas-and-requestanimationframe) shows.

## Reduced motion

To turn motion off for a whole app, `<YoujProvider motion={false}>` renders every resting state and never downloads Motion's engine; see [Motion loads on demand](https://www.youj.dev/docs/installation#motion-loads-on-demand). Reduced motion, below, keeps the engine and gentle feedback.

Reduced motion isn't motion switched off. Every Youj item has a designed static or instant alternative that tells the reader the same thing: a success state still appears, it just doesn't bounce in.

It follows the operating system's `prefers-reduced-motion` setting unless the provider's `reducedMotion` says otherwise: `'user'` (the default) follows the OS, `'always'` forces the reduced state, and `'never'` ignores it.

- **In JavaScript**, `k.reduced` is `true` when motion should give way. Render the alternative: a `{ duration: 0 }` transition, the final state, or a still frame.
- **In CSS**, `--yj-motion` is `1` with motion and `0` when reduced. Youj sets it from the OS on `:root`, and each provider sets it for its subtree. The `yj-duration-*` utilities and the [overlay presets](https://www.youj.dev/docs/motion/presets) multiply their durations by it, so under reduced motion the state still changes, instantly.
- **`var(--yj-duration-*)`** follows the time scale but not reduced motion. Use it for loop durations, which you stop separately under reduced motion. For transitions between states, use the `yj-duration-*` utilities.
- **Portals** render outside the provider's wrapper. Spread `{...useYoujScope()}` on them so they inherit `--yj-time-scale` and `--yj-motion`.

## In code

Timing comes from the hook, never from literals:

```tsx
import { m } from 'motion/react'
import { MotionFeatures, useYouj } from '@youj/core'

| Member | Returns |
| --- | --- |
| `k.tween(duration, ease?)` | A Motion tween. `ease` defaults to `standard`. |
| `k.spring(token)` | A Motion spring. |
| `k.stagger(token)` | The step in seconds. |
| `k.duration(token)` | A duration in seconds. |
| `k.ms(token)` | A duration in milliseconds, for timers, WAAPI and `requestAnimationFrame`. |
| `k.ease(token)` | The curve's four control points. |
| `k.reduced` | Whether to render the reduced alternative. |
| `k.timeScale` | The current multiplier. |
| `k.motion` | The personality in effect: `precise`, `calm` or `lively`. |

Every value is already scaled and re-valued for the personality. In CSS:

```tsx
<button className="transition-colors yj-duration-fast ease-standard hover:bg-hover">…</button>
```

| CSS | What it is |
| --- | --- |
| `yj-duration-{token}` | A `transition-duration`: the token × `--yj-time-scale` × `--yj-motion`. |
| `var(--yj-duration-{token})` | The token × `--yj-time-scale`. Doesn't follow reduced motion. |
| `ease-{standard,enter,exit,emphasized}` | The curve, as a `transition-timing-function` utility. `var(--ease-{name})` is the value. |
| `--yj-time-scale` | The provider's `timeScale`. |
| `--yj-motion` | `1` with motion, `0` when reduced. |
| `data-yj-motion` | The personality: `precise`, `calm` or `lively`. |

Don't use stock durations like `duration-150` or `transition-all duration-300`: they ignore both the time scale and reduced motion. [Motion in your components](https://www.youj.dev/docs/motion/in-your-components) walks through each way in.

---

# Overlay presets

> Animate Base UI overlays and panels with CSS utilities that follow speed and reduced-motion settings.

Source: https://www.youj.dev/docs/motion/presets

```tsx
'use client'

import type { ReactNode } from 'react'
import { LinkIcon } from '@youj/icons'
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Drawer,
  DrawerContent,
  DrawerDescription,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
  Sheet,
  SheetBody,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
  Toaster,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
  toast,
} from '@youj/react'

// Each @youj/react overlay is a Base UI part wearing one preset. Try them at ¼ speed.
function Tile({ preset, part, children }: { preset: string; part: string; children: ReactNode }) {
  return (
    <div className="flex flex-col items-start justify-between gap-4 rounded-xl border border-line bg-surface p-3.5">
      <div>
        <p className="font-mono text-[13px] text-fg">{preset}</p>
        <p className="mt-0.5 text-xs text-fg-muted">{part}</p>
      </div>
      {children}
    </div>
  )
}

const trigger = <Button variant="outline" size="sm" />

export default function PresetsDemo() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-2 gap-2.5 sm:grid-cols-3">
      <Tile preset="yj-pop" part="Popover, Menu, Select">
        <Popover>
          <PopoverTrigger render={trigger}>Share</PopoverTrigger>
          <PopoverContent>
            <PopoverHeader>
              <PopoverTitle>Share preview</PopoverTitle>
              <PopoverDescription>Anyone with the link can view this deployment.</PopoverDescription>
            </PopoverHeader>
          </PopoverContent>
        </Popover>
      </Tile>
      <Tile preset="yj-tooltip" part="Tooltip">
        <TooltipProvider>
          <Tooltip>
            <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Copy link" />}>
              <LinkIcon />
            </TooltipTrigger>
            <TooltipContent>Copy link</TooltipContent>
          </Tooltip>
        </TooltipProvider>
      </Tile>
      <Tile preset="yj-dialog" part="Dialog, with yj-backdrop">
        <Dialog>
          <DialogTrigger render={trigger}>Rename</DialogTrigger>
          <DialogContent>
            <DialogHeader>
              <DialogTitle>Rename project</DialogTitle>
              <DialogDescription>The new name shows in URLs and on every deployment.</DialogDescription>
            </DialogHeader>
            <DialogFooter>
              <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
              <DialogClose render={<Button />}>Rename</DialogClose>
            </DialogFooter>
          </DialogContent>
        </Dialog>
      </Tile>
      <Tile preset="yj-sheet-end" part="Sheet">
        <Sheet>
          <SheetTrigger render={trigger}>Activity</SheetTrigger>
          <SheetContent>
            <SheetHeader>
              <SheetTitle>Activity</SheetTitle>
              <SheetDescription>What changed in youj-web today.</SheetDescription>
            </SheetHeader>
            <SheetBody>
              <p className="text-sm text-fg-muted">Priya promoted a41f9e2 to production.</p>
            </SheetBody>
          </SheetContent>
        </Sheet>
      </Tile>
      <Tile preset="yj-sheet-bottom" part="Drawer, swipe to close">
        <Drawer>
          <DrawerTrigger render={trigger}>Details</DrawerTrigger>
          <DrawerContent>
            <DrawerHeader>
              <DrawerTitle>Deployment details</DrawerTitle>
              <DrawerDescription>Built in 38s from main, 4 minutes ago.</DrawerDescription>
            </DrawerHeader>
          </DrawerContent>
        </Drawer>
      </Tile>
      <Tile preset="yj-toast" part="Toast stack">
        <Button variant="outline" size="sm" onClick={() => toast.success('Deployed to production', { description: 'youj-web · 4f2a91c · 38s' })}>
          Deploy
        </Button>
        <Toaster />
      </Tile>
    </div>
  )
}
```

Use a preset on any Base UI part that mounts and unmounts: popups, backdrops, sheets, toasts and collapsible panels. Base UI marks the start and end of each transition with `data-starting-style` and `data-ending-style`, and the preset animates between them. Each preset is a CSS transition, not a keyframe animation, so reopening an overlay mid-close continues from where it is. For motion Base UI doesn't mount, use a block instead: [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator) for selection indicators and [Collapse](https://www.youj.dev/docs/motion/collapse) for disclosure outside Base UI.

## Installation

With the package, the presets ship inside its stylesheet, so there's nothing to add:

```css title="app/globals.css"
@import '@youj/react/styles.css';
```

With source copied in, they're their own item, `youj-presets`, and there's usually nothing to add either. Every UI item that animates with a preset depends on it, and the CLI writes the utilities straight into your app's stylesheet. To use the presets on overlays of your own before you've added one of those items, add the item directly:

```bash
npx @youj/cli add youj-presets
```

## Usage

Put the preset on the part that appears, and spread `useYoujScope()` on its portal:

This example uses Base UI's primitives directly, so install `@base-ui/react` in your app (`pnpm add @base-ui/react`), as pnpm won't resolve it through Youj.

```tsx
import { Popover } from '@base-ui/react/popover'
import { useYoujScope } from '@youj/core'

export function SharePopover() {
  const scope = useYoujScope()
  return (
    <Popover.Root>
      <Popover.Trigger>Share</Popover.Trigger>
      <Popover.Portal {...scope}>
        <Popover.Positioner sideOffset={6}>
          <Popover.Popup className="yj-pop rounded-lg border bg-overlay p-4 shadow-md">…</Popover.Popup>
        </Popover.Positioner>
      </Popover.Portal>
    </Popover.Root>
  )
}
```

Every `@youj/react` overlay already does both. The preview above is those components, one preset each. Open them at ¼ speed to see each one move.

### Why every portal needs the scope

`YoujProvider` sets the Speed and reduced-motion settings as CSS custom properties on its wrapper element. A portal renders into `<body>`, outside that wrapper, so without the scope an overlay ignores Speed and a provider's `reducedMotion="always"`. `useYoujScope()` returns the same properties for the portal element. Call it inside the component that renders the portal, so it reads the nearest provider.

## Examples

### The presets

| Utility | Put it on | Motion |
| --- | --- | --- |
| `yj-pop` | Popover, Menu, Select, Combobox, Context Menu and Preview Card popups | Scales from 0.96 and fades in from the anchor point in `--transform-origin`. Leaves faster than it came. |
| `yj-tooltip` | Tooltip popups | Scales from 0.97 and travels 3px from the trigger's side, mirrored under right-to-left text. |
| `yj-dialog` | Dialog and Alert Dialog popups | Rises 6px while scaling from 0.96. A parent with a nested dialog open recedes one step per level: 0.875rem down, 6% smaller, and dimmed under a wash that keeps its text above 4.5:1. Retune the wash with `--yj-dialog-dim`. |
| `yj-backdrop` | Every backdrop | Fades. Thins as a drawer is swiped away, tracking the finger. Bring your own color, such as `bg-scrim`. |
| `yj-sheet-top`, `-right`, `-bottom`, `-left` | Dialog-based sheets and Drawer popups | Slides fully off its edge. With Drawer it follows the finger, and a flick leaves faster. |
| `yj-sheet-start`, `yj-sheet-end` | The same, in right-to-left-aware layouts | As above, flipped under `dir="rtl"`. |
| `yj-toast`, `yj-toast-top` | Toast roots, stacked against the bottom or top edge | Peeks and shrinks behind the front toast, spreads on hover or focus, rises in, and leaves in the swipe direction. |
| `yj-toast-content` | Toast content | Hides the text of toasts behind the front one until the stack spreads. |
| `yj-collapse` | Collapsible and Accordion panels | Height to and from the size Base UI measures, with a fade. The panel clips while it moves, so keep focus rings inside its padding. |
| `yj-fade` | Tabs panels, item indicators, scroll arrows | Opacity only. |

Replace shadcn's tw-animate classes (`data-open:animate-in`, `fade-in-0`, `zoom-in-95`, `slide-in-from-*`, `duration-*`) with the preset. Don't combine them. The presets animate `transform` and `opacity` and leave the individual `translate` and `scale` properties to you, so centering with `-translate-x-1/2 -translate-y-1/2` keeps working.

Sheet classes must appear in full somewhere in your source, for example in a lookup object, because Tailwind can't see a class built with a template string.

```tsx
const side = { top: 'yj-sheet-top inset-x-0 top-0', right: 'yj-sheet-right inset-y-0 right-0', bottom: 'yj-sheet-bottom inset-x-0 bottom-0', left: 'yj-sheet-left inset-y-0 left-0' }
```

#### Tuning the toast stack

`yj-toast` owns the stack's geometry: position, width and a height clamped to the front toast while collapsed. The viewport only needs a position and a width. Two custom properties set the spacing:

| Property | Default | Sets |
| --- | --- | --- |
| `--yj-toast-gap` | `0.75rem` | Space between toasts when the stack spreads. |
| `--yj-toast-peek` | `0.75rem` | How far each toast behind shows while collapsed. |

#### Instant when Base UI asks

Base UI sets `data-instant` when a transition shouldn't play: opening from the keyboard, closing with Escape, or moving between grouped tooltips. `yj-fade`, `yj-pop` and `yj-tooltip` honor it with a zero duration, so menus, popovers and tooltips opened from the keyboard never wait on an animation. The dialog, backdrop, sheet, toast and collapse presets still play their transitions.

### Durations for your own transitions

For a transition that isn't an overlay, like a chevron that turns, a switch thumb or a hover tint, the same timing is available as utilities: `yj-duration-instant`, `yj-duration-fast`, `yj-duration-base`, `yj-duration-slow` and `yj-duration-deliberate`. Each is the token, times the Speed setting, times `--yj-motion`, so it slows with Speed and turns instant under reduced motion. Pair it with an `ease-*` utility.

```tsx
'use client'

import { useId, useState } from 'react'

const SETTINGS = [
  { id: 'comments', label: 'Preview comments', detail: 'Reviewers can pin notes to any preview.' },
  { id: 'alerts', label: 'Deploy alerts', detail: 'Email the team when a production build fails.' },
]

export default function PresetsDurations() {
  const uid = useId()
  const [on, setOn] = useState<Record<string, boolean>>({ comments: true, alerts: false })

return (
    <div className="w-full max-w-md divide-y divide-line rounded-xl border border-line bg-surface">
      {SETTINGS.map(({ id, label, detail }) => (
        <div key={id} className="flex items-center justify-between gap-4 px-4 py-3">
          <div>
            <p id={`${uid}-${id}`} className="text-sm font-medium text-fg">
              {label}
            </p>
            <p className="text-xs text-fg-muted">{detail}</p>
          </div>
          {/* A bespoke transition: yj-duration-fast is the token × Speed × --yj-motion, so it slows
              with the Speed control and turns instant under reduced motion. */}
          <button
            type="button"
            role="switch"
            aria-checked={on[id]}
            aria-labelledby={`${uid}-${id}`}
            onClick={() => setOn((s) => ({ ...s, [id]: !s[id] }))}
            className="group relative inline-flex h-5 w-9 shrink-0 items-center rounded-full bg-fg-subtle p-0.5 outline-none transition-colors yj-duration-fast ease-standard focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface aria-checked:bg-accent"
          >
            <span className="size-4 rounded-full bg-canvas shadow-sm transition-transform yj-duration-fast ease-standard group-aria-checked:translate-x-4 rtl:group-aria-checked:-translate-x-4" />
          </button>
        </div>
      ))}
    </div>
  )
}
```

```tsx
<ChevronDownIcon className="transition-transform yj-duration-base ease-standard data-panel-open:rotate-180" />
```

Don't use `duration-(--yj-duration-fast)` for movement. The raw variable follows Speed but not reduced motion.

## Reference

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Pop in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | `yj-pop`: opacity, scale 0.96 → 1 |
| Pop out | `duration.instant`, `ease.exit` | 80ms; cubic-bezier(0.4, 0, 1, 1) | `yj-pop`, `yj-tooltip` |
| Tooltip in | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | `yj-tooltip`: opacity, 3px travel, scale 0.97 → 1 |
| Dialog in | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | `yj-dialog`: opacity, rise 6px, scale 0.96 → 1 |
| Dialog out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Nested recede | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | parent dialog behind a child |
| Backdrop | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | `yj-backdrop` in; out on `fast` |
| Sheet in | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `yj-sheet-*`: off the edge to rest |
| Sheet out | `duration.base`, `ease.exit` | 220ms; cubic-bezier(0.4, 0, 1, 1) | shorter after a flick |
| Toast | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `yj-toast`: rise, stack and spread |
| Toast height | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | collapsed and spread heights |
| Toast content | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | `yj-toast-content` |
| Collapse | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | `yj-collapse`: height and opacity |
| Fade | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | `yj-fade` |

**Reduced motion:** Every preset duration is multiplied by --yj-motion, which is 0 under reduced motion. Overlays appear and disappear at once, and Base UI unmounts them immediately because there's nothing to wait for.

#### Reduced motion

Under reduced motion every preset's duration is zero, so overlays appear and disappear at once, panels open to full height immediately, and toasts take their place in the stack without travel. The overlays still open, close, trap focus and announce themselves. Only the movement goes. It follows the OS setting, and a provider's `reducedMotion="always"` too, as long as the portal carries the scope.

### Accessibility

- The presets are visual only. Roles, focus trapping, focus return and Escape come from Base UI, and they work the same with or without motion.
- Exits are shorter than entrances (`instant` for popups, `fast` for dialogs), so a dismissed overlay is out of the way almost at once and never covers what the reader went back to.
- Swipe gestures on drawers and toasts track the finger even under reduced motion, because that movement is direct manipulation, not animation.

---

# Motion in your components

> Use Youj timing in your components so they follow shared speed and reduced-motion settings.

Source: https://www.youj.dev/docs/motion/in-your-components

Use Youj’s shared durations, curves, springs and stagger steps in your own components. A theme’s [motion personality](https://www.youj.dev/docs/theming#motion-personality) adjusts these tokens. `YoujProvider` supplies speed and reduced-motion settings, so your animations can follow the rest of the app.

This guide covers the four ways in, from the least code to the most: reuse a block, write a CSS transition, time a Motion animation, or drive a loop.

## The provider

`YoujProvider` is optional. Without it, every component runs at normal speed and follows the operating system's reduced-motion setting. Add it at the root to control those two settings, or around one subtree, since the nearest provider wins.

```tsx
import { YoujProvider } from '@youj/core'

<YoujProvider timeScale={1} reducedMotion="user">
  {children}
</YoujProvider>
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeScale` | `number` | `1` | Multiplies every duration. `4` plays everything four times slower. |
| `reducedMotion` | `'user' \| 'always' \| 'never'` | `'user'` | `'user'` follows `prefers-reduced-motion`. `'always'` forces the reduced state, for a setting in your app, and `'never'` ignores the OS. |
| `quality` | `'auto' \| 'high' \| 'low'` | inherited, else `'auto'` | The [motion budget](#the-motion-budget). `'auto'` measures the device once per visit; `'high'` and `'low'` force a tier. |

These are the motion props. The provider also takes `theme` (see [Theming](https://www.youj.dev/docs/theming)), `mode` (see [Color mode](https://www.youj.dev/docs/theming#color-mode)), `motion` (`false` turns animation off; see [Motion loads on demand](https://www.youj.dev/docs/installation#motion-loads-on-demand)), `style` (see [Looks](https://www.youj.dev/docs/looks)), `density` and `scaling` (see [Density and scaling](https://www.youj.dev/docs/theming#density-and-scaling)), and `locale` and `labels` (see [Translating built-in text](https://www.youj.dev/docs/guides/i18n)).

The provider sets the same two settings for CSS, as custom properties on a wrapper element with `display: contents`: `--yj-time-scale`, and `--yj-motion`, which is `1` with motion and `0` when reduced.

## Reuse a block first

Before writing motion, check whether a block already solves it. Blocks are interruptible, follow Speed, and have a designed reduced state, which is most of the work.

| You need | Block |
| --- | --- |
| A highlight that glides between tabs, segments or nav items | [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator) |
| A label that changes while its box morphs | [Morph Label](https://www.youj.dev/docs/motion/morph-label) |
| A disclosure that animates to and from `height: auto` | [Collapse](https://www.youj.dev/docs/motion/collapse) |
| A skeleton that resolves into content | [Content Swap](https://www.youj.dev/docs/motion/content-swap) |
| List items or table rows that enter, leave and reorder | [Presence List](https://www.youj.dev/docs/motion/presence-list) |
| Base UI popovers, dialogs, sheets and toasts | [Overlay presets](https://www.youj.dev/docs/motion/presets) |

[Composing components](https://www.youj.dev/docs/guides/composing-components) builds a full component from them.

## Transitions in CSS

Hover tints, pressed states, a chevron that turns: most interface motion is a CSS transition between two states. Take the duration from a `yj-duration-*` utility and the curve from an `ease-*` utility.

```tsx
'use client'

import { useYouj } from '@youj/core'
import { ChevronRightIcon, GitBranchIcon } from '@youj/icons'

const DEPLOYMENTS = [
  { branch: 'main', commit: 'Tighten cache headers', age: '2m ago', status: 'Ready' },
  { branch: 'feat/pricing', commit: 'New pricing page', age: '18m ago', status: 'Ready' },
  { branch: 'fix/og-images', commit: 'OG images for blog posts', age: '1h ago', status: 'Canceled' },
]

export default function CssTransitions() {
  const k = useYouj()

return (
    // data-reduced-motion lets the `reduced:` variant follow the provider, not just the OS.
    <ul data-reduced-motion={k.reduced || undefined} className="w-full max-w-md divide-y divide-line overflow-hidden rounded-xl border border-line bg-surface">
      {DEPLOYMENTS.map((d) => (
        <li key={d.branch}>
          <button
            type="button"
            className="group flex w-full items-center gap-3 px-4 py-3 text-start transition-[background-color,scale] yj-duration-fast ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none focus-visible:ring-inset active:scale-[0.99] active:yj-duration-instant reduced:active:scale-100"
          >
            <GitBranchIcon size={16} className="text-fg-muted" />
            <span className="min-w-0 flex-1">
              <span className="block truncate text-sm font-medium text-fg">{d.commit}</span>
              <span className="block text-xs text-fg-muted">
                {d.branch} · {d.age}
              </span>
            </span>
            <span className="text-xs text-fg-muted">{d.status}</span>
            {/* A CSS nudge toward where the row leads, in the reading direction. trigger="none" keeps
                the icon's own choreography out of it. */}
            <ChevronRightIcon
              size={16}
              trigger="none"
              className="text-fg-muted transition-transform yj-duration-fast ease-standard group-hover:translate-x-0.5 group-focus-visible:translate-x-0.5 rtl:-scale-x-100 rtl:group-hover:-translate-x-0.5"
            />
          </button>
        </li>
      ))}
    </ul>
  )
}
```

```tsx
<button className="transition-colors yj-duration-fast ease-standard hover:bg-hover">…</button>
<ChevronDownIcon className="transition-transform yj-duration-base ease-standard data-panel-open:rotate-180" />
```

- `yj-duration-instant | fast | base | slow | deliberate` is the token, times the time scale, times `--yj-motion`. Under reduced motion it becomes zero, so the state change is instant, and it still happens.
- `ease-standard | enter | exit | emphasized` are the curves. Use `enter` for things arriving, `exit` for things leaving, and `standard` between two resting states.
- `var(--yj-duration-fast)` and its siblings follow the time scale but not reduced motion. They suit loop durations, which you stop separately under reduced motion. For anything that moves between states, use the `yj-duration-*` utilities.

A transform with no duration still snaps. To drop a press scale entirely under reduced motion, as the rows above do, mark the element with `data-reduced-motion` from `useYouj()` and use the `reduced:` variant:

```tsx
const k = useYouj()

<ul data-reduced-motion={k.reduced || undefined}>
  <button className="active:scale-[0.99] reduced:active:scale-100">…</button>
</ul>
```

The `reduced:` variant ships in `@youj/react`'s stylesheet. With only `@youj/core` and `@youj/motion`, declare it once in your CSS:

```css
@custom-variant reduced (&:where([data-reduced-motion], [data-reduced-motion] *));
```

> **Don't use stock durations:** `duration-150` and `transition-all duration-300` ignore both Speed and reduced motion. Youj's own components are linted against them, and your own code deserves the same rule.

## Timing in JavaScript

For Motion animations, `useYouj()` returns ready transitions built from the tokens and scaled by the provider.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { AnimatePresence, m } from 'motion/react'
import { MotionFeatures, useYouj } from '@youj/core'
import { CheckIcon } from '@youj/icons'
import { Button, Switch } from '@youj/react'

const SETTINGS = [
  { id: 'previews', label: 'Protect preview deployments', hint: 'Visitors sign in before they see a preview.' },
  { id: 'production', label: 'Protect production', hint: 'Only your team can open the production URL.' },
] as const
type Settings = Record<(typeof SETTINGS)[number]['id'], boolean>

export default function SaveBar() {
  const k = useYouj()
  const [saved, setSaved] = useState<Settings>({ previews: true, production: false })
  const [draft, setDraft] = useState(saved)
  const [confirmed, setConfirmed] = useState(false)
  const card = useRef<HTMLDivElement>(null)
  const dirty = SETTINGS.some(({ id }) => draft[id] !== saved[id])

const settle = (next: Settings, didSave: boolean) => {
    setSaved(next)
    setDraft(next)
    setConfirmed(didSave)
    // The bar and its buttons are leaving: keep focus in the card rather than dropping it on <body>.
    card.current?.focus({ preventScroll: true })
  }

// The confirmation holds for three deliberate steps, so Speed stretches it too.
  useEffect(() => {
    if (!confirmed) return
    const timer = setTimeout(() => setConfirmed(false), k.ms('deliberate') * 3)
    return () => clearTimeout(timer)
  }, [confirmed, k])

// Arrivals decelerate into place; exits are shorter and accelerate away. Reduced motion: no travel.
  const enter = k.reduced ? { duration: 0 } : k.tween('base', 'enter')
  const exit = k.reduced ? { duration: 0 } : k.tween('fast', 'exit')

return (
    <MotionFeatures>
      <div className="w-full max-w-md">
        <div ref={card} tabIndex={-1} className="rounded-xl border border-line bg-surface outline-none">
          <div className="flex items-center justify-between border-b border-line px-4 py-3">
            <p className="text-sm font-medium text-fg">Deployment protection</p>
            <p role="status" className="h-6">
              <AnimatePresence>
                {confirmed && (
                  <m.span
                    initial={k.reduced ? false : { opacity: 0, scale: 0.9 }}
                    animate={{ opacity: 1, scale: 1, transition: k.reduced ? { duration: 0 } : k.spring('settle') }}
                    exit={{ opacity: 0, transition: exit }}
                    className="inline-flex h-6 items-center gap-1 rounded-full bg-success-subtle px-2 text-xs font-medium text-success-text"
                  >
                    <CheckIcon size={14} strokeWidth={2} trigger="mount" />
                    Saved
                  </m.span>
                )}
              </AnimatePresence>
            </p>
          </div>
          <div className="divide-y divide-line">
            {SETTINGS.map(({ id, label, hint }) => (
              <label key={id} className="flex cursor-pointer items-center justify-between gap-4 px-4 py-3">
                <span>
                  <span className="block text-sm text-fg">{label}</span>
                  <span className="block text-xs text-fg-muted">{hint}</span>
                </span>
                <Switch checked={draft[id]} onCheckedChange={(on) => setDraft((d) => ({ ...d, [id]: on }))} />
              </label>
            ))}
          </div>
        </div>

{/* A fixed slot, so the page below never jumps when the bar comes and goes. */}
        <div className="mt-3 h-12">
          <AnimatePresence>
            {dirty && (
              <m.div
                initial={k.reduced ? false : { opacity: 0, y: 8 }}
                animate={{ opacity: 1, y: 0, transition: enter }}
                exit={{ opacity: 0, y: 8, transition: exit }}
                className="flex h-12 items-center justify-between gap-3 rounded-lg border border-line bg-raised ps-4 pe-2 shadow-md"
              >
                <span className="text-sm text-fg-muted">Unsaved changes</span>
                <span className="flex gap-1.5">
                  <Button variant="ghost" size="sm" onClick={() => settle(saved, false)}>
                    Discard
                  </Button>
                  <Button size="sm" onClick={() => settle(draft, true)}>
                    Save
                  </Button>
                </span>
              </m.div>
            )}
          </AnimatePresence>
        </div>
      </div>
    </MotionFeatures>
  )
}
```

Toggle a setting to bring in the save bar, then save to see the confirmation arrive on the one spring that's allowed to overshoot.

```tsx
import { AnimatePresence, m } from 'motion/react'
import { MotionFeatures, useYouj } from '@youj/core'

function SaveBar({ dirty }: { dirty: boolean }) {
  const k = useYouj()
  const enter = k.reduced ? { duration: 0 } : k.tween('base', 'enter')
  const exit = k.reduced ? { duration: 0 } : k.tween('fast', 'exit')

return (
    <MotionFeatures>
      <AnimatePresence>
        {dirty && (
          <m.div
            initial={k.reduced ? false : { opacity: 0, y: 8 }}
            animate={{ opacity: 1, y: 0, transition: enter }}
            exit={{ opacity: 0, y: 8, transition: exit }}
          />
        )}
      </AnimatePresence>
    </MotionFeatures>
  )
}
```

`m` elements animate under `MotionFeatures`, which loads Motion's engine on demand and does nothing when the provider already has (see [Motion loads on demand](https://www.youj.dev/docs/installation#motion-loads-on-demand)). Use `features="max"` for layout and drag.

If you wrap content in `<AnimatePresence initial={false}>` and it holds `m` elements, put that content in `<PresenceSettled>` (from `@youj/core`). Motion skips the first animation of anything mounted there, and with the engine loading on demand, "first" can be the moment it arrives, so a value that changed in between would otherwise never animate to its target.

| Member | Returns | Use it for |
| --- | --- | --- |
| `k.tween(duration, ease?)` | a Motion tween transition | Enters, exits, anything between two states. `ease` defaults to `standard`. |
| `k.spring(token)` | a Motion spring transition | `snappy` for feedback, `smooth` for layout, `settle` for success and arrival. |
| `k.stagger(token)` | seconds | The step between siblings in a sequence. |
| `k.duration(token)` | seconds | Motion's unit, already scaled. |
| `k.ms(token)` | milliseconds | Timers, WAAPI and `requestAnimationFrame` code, already scaled. |
| `k.ease(token)` | `[x1, y1, x2, y2]` | A cubic-bezier for your own tween or WAAPI call. |
| `k.reduced` | `boolean` | Whether to render the static or instant alternative. |
| `k.timeScale` | `number` | The current multiplier, for loops. |

Two rules keep this honest. Exits are shorter than entrances and accelerate away (`fast` on `exit`), because nobody waits for something to leave. And every timer that paces an interface, like how long a confirmation holds, comes from `k.ms()`, so Speed stretches it too.

### Springs

Springs are defined by how long they feel and how much they bounce, not by stiffness and damping, so the time scale reaches them like everything else. `snappy` and `smooth` never overshoot. `settle` overshoots once, and it's reserved for success and arrival. A save confirmation earns it. A menu opening doesn't. The [Motion playground](https://www.youj.dev/docs/motion/playground) plays each against its curve, and the [Motion principles](https://www.youj.dev/docs/motion/principles) say which one each interaction takes.

## Loops, canvas and requestAnimationFrame

Code that animates frame by frame reads the same contract, by hand:

```tsx
'use client'

import { useEffect, useRef } from 'react'
import { useYouj } from '@youj/core'

const W = 320
const H = 72
const HISTORY = 12 // seconds on screen
const POINTS = 96

/** Deterministic traffic, a few sines, so the server and the client draw the same first frame. */
const traffic = (t: number) => 0.5 + 0.2 * Math.sin(t * 0.9) + 0.12 * Math.sin(t * 2.3 + 1) + 0.06 * Math.sin(t * 5.1 + 2)
const rps = (t: number) => Math.round(900 + traffic(t) * 800).toLocaleString('en-US')

function lineAt(time: number) {
  let d = ''
  for (let i = 0; i <= POINTS; i++) {
    const t = time - HISTORY + (i / POINTS) * HISTORY
    d += `${i ? 'L' : 'M'}${((i / POINTS) * W).toFixed(1)} ${(H - traffic(t) * H).toFixed(1)}`
  }
  return d
}

export default function LiveTraffic() {
  const k = useYouj()
  const root = useRef<HTMLDivElement>(null)
  const line = useRef<SVGPathElement>(null)
  const area = useRef<SVGPathElement>(null)
  const value = useRef<HTMLSpanElement>(null)

useEffect(() => {
    const draw = (time: number) => {
      const d = lineAt(time)
      line.current?.setAttribute('d', d)
      area.current?.setAttribute('d', `${d}L${W} ${H}L0 ${H}Z`)
      if (value.current) value.current.textContent = rps(time)
    }

// Reduced motion: no scrolling line. The chart still updates, in discrete steps.
    if (k.reduced) {
      let time = 0
      const step = setInterval(() => draw((time += 2)), k.ms('deliberate') * 4)
      return () => clearInterval(step)
    }

let elapsed = 0
    let last = 0
    let frame = 0
    let onScreen = true
    const tick = (now: number) => {
      // Divide elapsed time by the time scale: at ¼ speed the chart really moves four times slower.
      elapsed += (now - last) / 1000 / k.timeScale
      last = now
      draw(elapsed)
      frame = requestAnimationFrame(tick)
    }
    const start = () => {
      if (frame || !onScreen || document.visibilityState === 'hidden') return
      last = performance.now()
      frame = requestAnimationFrame(tick)
    }
    const stop = () => {
      cancelAnimationFrame(frame)
      frame = 0
    }
    // Pause offscreen and in hidden tabs.
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true
      if (onScreen) start()
      else stop()
    })
    const onVisibility = () => (document.visibilityState === 'hidden' ? stop() : start())
    io.observe(root.current!)
    document.addEventListener('visibilitychange', onVisibility)
    start()
    return () => {
      stop()
      io.disconnect()
      document.removeEventListener('visibilitychange', onVisibility)
    }
  }, [k])

const first = lineAt(0)
  return (
    <div ref={root} className="w-full max-w-sm rounded-xl border border-line bg-surface p-4">
      <div className="flex items-baseline justify-between">
        <p className="text-sm font-medium text-fg">Requests</p>
        <p className="text-xs text-fg-muted">
          <span ref={value} className="font-mono text-sm text-fg tabular-nums">
            {rps(0)}
          </span>{' '}
          per second
        </p>
      </div>
      <svg viewBox={`0 0 ${W} ${H}`} className="mt-3 h-18 w-full text-accent" preserveAspectRatio="none" aria-hidden>
        <path ref={area} d={`${first}L${W} ${H}L0 ${H}Z`} fill="currentColor" fillOpacity={0.08} />
        <path ref={line} d={first} fill="none" stroke="currentColor" strokeWidth={1.5} vectorEffect="non-scaling-stroke" />
      </svg>
      <p className="mt-2 text-xs text-fg-muted">Last {HISTORY} seconds</p>
    </div>
  )
}
```

```tsx
useEffect(() => {
  if (k.reduced) {
    drawStatic()
    return
  }
  let elapsed = 0
  let last = performance.now()
  let frame = requestAnimationFrame(function tick(now) {
    elapsed += (now - last) / 1000 / k.timeScale // Speed reaches the loop
    last = now
    draw(elapsed)
    frame = requestAnimationFrame(tick)
  })
  return () => cancelAnimationFrame(frame)
}, [k])
```

- **Time scale.** Divide elapsed time by `k.timeScale`. For shaders, pass the scaled time as the uniform.
- **Pause what nobody sees.** Stop the loop offscreen with an `IntersectionObserver`, and in hidden tabs with `visibilitychange`, as the chart above does.
- **Reduced motion.** Stop the loop and draw a designed frame. When the data is live, keep it current in discrete steps with no travel, like the chart does.
- **Clean up.** Cancel the frame and disconnect every observer on unmount. For WebGL, release the context too.
- **Colors.** A canvas can't read Tailwind classes. Read the tokens from computed style (`getComputedStyle(el).getPropertyValue('--color-accent')`) and read them again when the theme changes.

## The motion budget

Some devices can't afford the full treatment: a budget phone, a laptop on battery saver, a visitor on Data Saver. The motion budget gives every component one answer to "how much should I do here?", as a tier: `'high'` for the full treatment, `'low'` for a lighter one that still moves. It isn't reduced motion. Reduced motion is the visitor's request to stop movement; the low tier is the device's limit, so the motion keeps its meaning and sheds its cost.

```tsx
'use client'

import { useState } from 'react'
import { YoujProvider, useYouj, useMotionBudget, type QualitySetting } from '@youj/core'
import { TextSplit } from '@youj/motion'
import { ToggleGroup, ToggleGroupItem } from '@youj/react'

const HEADLINE = 'Every letter of this long headline rises on its own beat'

function Headline() {
  const { quality, tier } = useMotionBudget()
  return (
    <div className="flex flex-col items-center gap-4 text-center">
      <TextSplit key={tier} by="chars" as="p" className="max-w-md text-2xl font-semibold tracking-tight text-balance text-fg">
        {HEADLINE}
      </TextSplit>
      <p className="font-mono text-xs text-fg-muted">
        quality “{quality}” · tier “{tier}” · {tier === 'low' ? 'the stagger fits into six steps' : 'one step per letter'}
      </p>
    </div>
  )
}

export default function MotionBudget() {
  const [quality, setQuality] = useState<QualitySetting>('auto')
  // A nested provider sets all three settings, so carry the outer speed and reduced motion in.
  const k = useYouj()

return (
    <div className="flex w-full flex-col items-center gap-8">
      <ToggleGroup variant="segmented" aria-label="Quality" value={[quality]} onValueChange={(next) => next[0] && setQuality(next[0] as QualitySetting)}>
        <ToggleGroupItem value="auto">Auto</ToggleGroupItem>
        <ToggleGroupItem value="high">High</ToggleGroupItem>
        <ToggleGroupItem value="low">Low</ToggleGroupItem>
      </ToggleGroup>
      <YoujProvider quality={quality} timeScale={k.timeScale} reducedMotion={k.reduced ? 'always' : 'user'}>
        <Headline />
      </YoujProvider>
    </div>
  )
}
```

`useMotionBudget()` returns the provider's `quality` setting and the `tier` in effect. With `quality="auto"`, the default, the tier comes from the device, once per visit:

1. **Hints decide first.** Data Saver (`Save-Data`), `prefers-reduced-data`, two or fewer logical cores, or 2 GB of memory or less mean `'low'` straight away.
2. **Otherwise a short probe runs** once the page is idle: a fixed slice of animation-like work timed over a few frames. A main thread that takes over 5 ms for it, or can't hold frames under 34 ms while nearly idle, is `'low'`.
3. **The result is kept for the session**, so later pages start on the right tier.

The server render and the hydration render always see `'high'`. Hydrated components re-render with the real tier straight after, the same way the OS reduced-motion setting arrives, so server and client HTML never disagree.

```tsx
import { useMotionBudget } from '@youj/core'

function Sparks() {
  const { tier } = useMotionBudget()
  const count = tier === 'low' ? 12 : 48 // fewer particles, same idea
  return <ParticleField count={count} />
}
```

What Youj does on `'low'`:

- **Staggers** longer than six steps compress into six, in [Stagger](https://www.youj.dev/docs/motion/stagger) and [Text Split](https://www.youj.dev/docs/motion/text-split): a 40-letter headline lands in a few beats instead of trickling in.
- **Canvas backgrounds** cap the pixel ratio at 1 and render at 30 fps, and each piece may shed work of its own.
- **The [Cursor Follower](https://www.youj.dev/docs/components/cursor-follower)** turns off.

Force a tier with `quality`, for a performance setting in your app or to test the light path on a fast machine. Nested providers inherit `quality` unless they set their own.

```tsx
<YoujProvider quality={settings.lowPower ? 'low' : 'auto'}>{children}</YoujProvider>
```

## Overlays and portals

A portal renders outside the provider's wrapper element, so its CSS can't inherit `--yj-time-scale` or `--yj-motion`. Spread `useYoujScope()` on every portal you render, and the overlay follows Speed and reduced motion again:

```tsx
import { useYoujScope } from '@youj/core'

const scope = useYoujScope()
<Popover.Portal {...scope}>…</Popover.Portal>
```

Every `@youj/react` overlay already does this. For your own overlays, the [Overlay presets](https://www.youj.dev/docs/motion/presets) give you the entrance and exit, too.

## Checklist

- No literal durations, cubic-beziers or stock `duration-*` classes. Everything comes from `useYouj()`, the `yj-duration-*` and `ease-*` utilities, or a preset.
- Every animated state has a reduced alternative that carries the same information. Loops stop, and pointer and scroll effects switch off.
- Interrupt everything: reverse a toggle mid-animation, open and close quickly. Transitions and springs continue from where they are, and keyframes jump.
- Animate `transform`, `opacity`, `clip-path` and `filter`. Other properties trigger layout.
- Decorative motion is `aria-hidden`, and state changes that matter are announced, once.
- Check at ¼ speed. Anything still moving at full speed has a hard-coded duration.

---

# Primitives

> Animate your content with reveals, text effects, counters, loops and scroll effects.

Source: https://www.youj.dev/docs/motion/primitives

Use these pieces to animate content you provide: reveal it, animate its text or numbers, loop it, or link it to scrolling. Each is available in `@youj/motion` and the registry, and follows the shared Speed setting.

## Appear

- [Reveal](https://www.youj.dev/docs/motion/reveal): Fade, rise, blur, scale or wipe in, on mount or in view. Exits too.

- [Stagger](https://www.youj.dev/docs/motion/stagger): Plays a group of children in sequence on a stagger token.

## Text and numbers

- [TextSplit](https://www.youj.dev/docs/motion/text-split): Reveals text by character, word or measured line.

- [TextEffect](https://www.youj.dev/docs/motion/text-effect): One text renderer: split-flap, terminal, decode, blur-in or rolling reels.

- [ScrambleText](https://www.youj.dev/docs/motion/scramble-text): Decodes toward its text through random glyphs.

- [Counter](https://www.youj.dev/docs/motion/counter): An animated number that counts or rolls, and retargets mid-flight.

## Loops and scroll

- [Marquee](https://www.youj.dev/docs/motion/marquee): A seamless loop that eases to a stop on hover.

- [Parallax](https://www.youj.dev/docs/motion/parallax): Maps scroll onto translate, scale, rotate and opacity.

- [ScrollProgress](https://www.youj.dev/docs/motion/scroll-progress): A spring-smoothed bar or ring bound to scroll.

For pointer effects such as [Tilt](https://www.youj.dev/docs/components/tilt) and [Magnetic](https://www.youj.dev/docs/components/magnetic), see Visual effects in the Components sidebar.

---

# Reveal

> Animate content in as it loads or scrolls into view, and out as it leaves, with fades, slides, blur and more.

Source: https://www.youj.dev/docs/motion/reveal

```tsx
'use client'

import { Reveal } from '@youj/motion'

const STEPS = [
  { label: 'Install', width: '38%' },
  { label: 'Build', width: '72%' },
  { label: 'Checks', width: '54%' },
  { label: 'Promote', width: '88%' },
]

export default function RevealDemo() {
  return (
    // A container query, so the layout follows the space it gets rather than the viewport.
    <div className="@container w-full max-w-2xl">
      <div className="grid items-center gap-8 @xl:grid-cols-[1.1fr_1fr]">
        <div>
          <Reveal
            variant="fade"
            inView={false}
            className="mb-4 inline-flex items-center gap-2 rounded-full border border-line bg-surface px-2.5 py-1 text-xs text-fg-muted"
          >
            <span className="size-1.5 rounded-[1px] bg-accent" />
            Changelog 2.4
          </Reveal>
          <Reveal as="h2" variant="rise" inView={false} delay={1} delayStep="loose" className="text-2xl font-semibold tracking-tight text-balance text-fg">
            Deploys that land where you meant them.
          </Reveal>
          <Reveal as="p" variant="rise" inView={false} delay={2} delayStep="loose" className="mt-3 text-sm leading-relaxed text-fg-muted">
            Preview every change on a real URL, then promote it in one step.
          </Reveal>
          <Reveal variant="rise" inView={false} delay={3} delayStep="loose" className="mt-5 flex gap-2">
            <button
              type="button"
              className="rounded-lg bg-fg px-3.5 py-2 text-sm font-medium whitespace-nowrap text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
            >
              Start deploying
            </button>
            <button
              type="button"
              className="rounded-lg border border-line bg-surface px-3.5 py-2 text-sm font-medium whitespace-nowrap text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
            >
              Read the docs
            </button>
          </Reveal>
        </div>

<Reveal variant="wipe-up" inView={false} delay={3} delayStep="loose">
          <div className="rounded-xl border border-line bg-surface p-4 shadow-sm">
            <p className="mb-3 font-mono text-[11px] text-fg-muted">deploy · 4f2a91c</p>
            <div className="space-y-2.5">
              {STEPS.map((step, i) => (
                <div key={step.label} className="grid grid-cols-[64px_1fr] items-center gap-3">
                  <span className="text-xs text-fg-muted">{step.label}</span>
                  <div className="h-1.5 rounded-full bg-raised">
                    <Reveal variant="wipe-right" inView={false} delay={6 + i} className="h-full rounded-full bg-accent" style={{ width: step.width }} />
                  </div>
                </div>
              ))}
            </div>
          </div>
        </Reveal>
      </div>
    </div>
  )
}
```

Use it for content that should arrive rather than appear: a hero's headline, a section as it scrolls in, a panel that opens. One Reveal moves one element. For a group, use [Stagger](https://www.youj.dev/docs/motion/stagger), and for a headline that assembles word by word, [TextSplit](https://www.youj.dev/docs/motion/text-split). Don't reveal what people came to read or act on, like form fields, table rows or navigation. It should be there when they look.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Reveal, RevealMotionOptions } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add reveal
```

It brings `youj-core`, `settled-entrances` with it.

## Usage

Wrap anything. By default it rises into place the first time 30% of it is on screen.

```tsx
import { Reveal } from '@youj/motion'

export function Feature() {
  return (
    <Reveal>
      <FeatureCard />
    </Reveal>
  )
}
```

Use `inView={false}` for content that should arrive as soon as it renders, and `as` to reveal a heading or list item without an extra wrapper.

```tsx
<Reveal as="h2" inView={false} className="text-4xl font-semibold">
  Motion that lands where you meant it.
</Reveal>
```

## Examples

### Variants

Eight arrivals share one timing model. `rise`, `fade` and `scale` take the `slow` duration. The four `wipe-*` variants and `blur-in` travel further, so they take `deliberate`. Everything that travels decelerates hard into place on the `enter` curve. `fade` doesn't travel, so it uses `standard`.

```tsx
'use client'

import { Reveal, revealVariantNames } from '@youj/motion'

export default function RevealVariants() {
  return (
    <div className="@container w-full max-w-2xl">
      <div className="grid grid-cols-2 gap-3 @lg:grid-cols-4">
        {revealVariantNames.map((variant, i) => (
          <Reveal key={variant} variant={variant} inView={false} delay={i} delayStep="loose">
            <div className="flex h-24 flex-col justify-between rounded-xl border border-line bg-surface p-3">
              <div className="h-8 rounded-md bg-accent-subtle" />
              <span className="font-mono text-xs text-fg-muted">{variant}</span>
            </div>
          </Reveal>
        ))}
      </div>
    </div>
  )
}
```

### Choreography

`delay` is a count of stagger steps, not milliseconds. `delay={2}` waits two `delayStep` steps. The whole sequence stays on the token grid, so it scales with the Speed control and never drifts out of rhythm.

```tsx
<Reveal inView={false} delay={0} delayStep="loose">Eyebrow</Reveal>
<Reveal inView={false} delay={1} delayStep="loose">Headline</Reveal>
<Reveal inView={false} delay={2} delayStep="loose">Body</Reveal>
```

For lists, reach for [Stagger](https://www.youj.dev/docs/motion/stagger): it hands each child its cue, and a `Reveal` inside it takes its timing and delay from the parent.

### Exits

Inside `AnimatePresence`, a Reveal leaves with the `fast` duration on the `exit` curve. Exits are shorter than arrivals, because nobody waits for something to leave. Toggle quickly: a re-entry mid-exit retargets from wherever the element is, without a jump.

```tsx
'use client'

import { useState } from 'react'
import { AnimatePresence } from 'motion/react'
import { Reveal } from '@youj/motion'

export default function RevealPresence() {
  const [open, setOpen] = useState(true)

return (
    <div className="flex h-52 w-full max-w-sm flex-col items-center justify-between">
      <button
        type="button"
        onClick={() => setOpen((o) => !o)}
        className="rounded-lg bg-fg px-4 py-2 text-sm font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
      >
        {open ? 'Dismiss' : 'Deploy'}
      </button>
      <AnimatePresence>
        {open && (
          <Reveal key="toast" variant="rise" inView={false} role="status" className="flex w-full items-start gap-3 rounded-xl border border-line bg-surface p-4 shadow-sm">
            <span className="mt-1.5 size-2 shrink-0 rounded-[2px] bg-success" />
            <div>
              <p className="text-sm font-medium text-fg">Deployed to production</p>
              <p className="mt-0.5 text-xs text-fg-muted">youj-web · 4f2a91c · 38s</p>
            </div>
          </Reveal>
        )}
      </AnimatePresence>
    </div>
  )
}
```

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `'div' \| 'span' \| 'section' \| 'article' \| 'header' \| 'footer' \| 'li' \| 'p' \| 'h1' \| 'h2' \| 'h3' \| 'figure'` | `'div'` |  |
| `variant` | `'fade' \| 'rise' \| 'blur-in' \| 'scale' \| 'wipe-up' \| 'wipe-down' \| 'wipe-left' \| 'wipe-right'` | `'rise'` |  |
| `inView` | `InView` |  | When it plays: `false` on mount; `true` (the default) when scrolled into view, once, at 30% visible; or `{ once, amount, margin }`. |
| `delay` | `number` | `0` | Delay as a multiple of the `delayStep` stagger token. `delay={2}` = two steps. |
| `delayStep` | `'tight' \| 'base' \| 'loose'` | `'base'` |  |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` |  |  |
| `ease` | `'standard' \| 'enter' \| 'exit' \| 'emphasized' \| 'linear'` |  |  |
| `distance` | `number \| string` | `12` | Travel for `rise` (px or any CSS length, e.g. '110%' for masked lines). |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLMotionProps<'div'>`.

`distance`, how far `rise` travels, defaults to `12` (px).

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `rise`, `scale` |
| Enter, long travel | `duration.deliberate`, `ease.enter` | 560ms; cubic-bezier(0.16, 1, 0.3, 1) | `blur-in`, `wipe-*` |
| Fade | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | opacity only |
| Exit | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) |  |
| Delay step | `stagger.base` | 40ms step | default `delayStep` |

**Reduced motion:** Renders in its final state: no fade, no travel. Presence exits remove the element immediately.

It animates only `opacity`, `transform`, `filter` and `clip-path`, so a reveal never triggers layout.

#### Reduced motion

A Reveal renders in its final state from the first frame: no fade, no travel and no wait. Inside `AnimatePresence`, it's removed at once. Nothing is hidden behind a scroll position, so the page reads the same either way.

### Accessibility

- The content is in the document from the first render, so assistive technology reads it whether or not it has animated in.
- Reveal adds no roles. Put semantics on the element itself, with `as`.
- Scroll reveals are one-shot by default (`inView={{ once: true }}`). Content that disappears as it scrolls away makes a page feel unstable, so opt out only with a reason.

---

# Stagger

> Animate a group of elements in sequence, with shared timing and order controls.

Source: https://www.youj.dev/docs/motion/stagger

```tsx
'use client'

import { Stagger } from '@youj/motion'
import {
  CloudIcon,
  DatabaseIcon,
  GitMergeIcon,
  KeyIcon,
  LineChartIcon,
  MailIcon,
  MessagesIcon,
  ShieldCheckIcon,
} from '@youj/icons'

const INTEGRATIONS = [
  { name: 'GitHub', detail: 'Deploy on push', Icon: GitMergeIcon, connected: true },
  { name: 'Postgres', detail: 'A branch per preview', Icon: DatabaseIcon, connected: true },
  { name: 'Slack', detail: 'Deploy notifications', Icon: MessagesIcon, connected: true },
  { name: 'Edge Config', detail: 'Read at the edge', Icon: CloudIcon },
  { name: 'Analytics', detail: 'Core Web Vitals', Icon: LineChartIcon },
  { name: 'Secrets', detail: 'Encrypted variables', Icon: KeyIcon, connected: true },
  { name: 'Firewall', detail: 'Managed rules', Icon: ShieldCheckIcon },
  { name: 'Resend', detail: 'Transactional email', Icon: MailIcon },
]

export default function StaggerDemo() {
  return (
    <div className="@container w-full max-w-2xl">
      <div className="mb-5 flex items-end justify-between gap-4">
        <div>
          <p className="text-lg font-semibold tracking-tight text-fg">Integrations</p>
          <p className="mt-0.5 text-sm text-fg-muted">Connect the services your project already uses.</p>
        </div>
        <span className="shrink-0 text-xs text-fg-muted">4 connected</span>
      </div>
      {/* `center` ripples out from the middle of the sequence, so the grid arrives as one gesture. */}
      <Stagger as="ul" itemAs="li" order="center" inView={false} className="grid grid-cols-2 gap-2.5 @lg:grid-cols-4">
        {INTEGRATIONS.map(({ name, detail, Icon, connected }) => (
          <div key={name} className="flex h-full flex-col gap-3.5 rounded-xl border border-line bg-surface p-3.5">
            <div className="flex items-center justify-between">
              <span className="grid size-8 place-items-center rounded-lg border border-line bg-raised text-fg">
                <Icon size={16} strokeWidth={1.75} />
              </span>
              {connected && <span className="rounded-full bg-accent-subtle px-2 py-0.5 text-[11px] font-medium text-accent">Connected</span>}
            </div>
            <div>
              <p className="text-sm font-medium text-fg">{name}</p>
              <p className="text-xs text-fg-muted">{detail}</p>
            </div>
          </div>
        ))}
      </Stagger>
    </div>
  )
}
```

Use it when a group arrives together: a grid of cards, a feature list, a row of stats. The offsets are tens of milliseconds, so the group reads as one gesture, not a queue. Don't stagger content people are waiting to read, like search results or a table that has just loaded. Show those at once.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Stagger } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add stagger
```

It brings `youj-core`, `reveal`, `settled-entrances` with it.

## Usage

Every child gets its own cue. A child that isn't a [Reveal](https://www.youj.dev/docs/motion/reveal) is wrapped in one, using the group's `variant`.

```tsx
import { Stagger } from '@youj/motion'

export function Features() {
  return (
    <Stagger className="grid grid-cols-3 gap-4">
      <FeatureCard title="Previews" />
      <FeatureCard title="Rollbacks" />
      <FeatureCard title="Analytics" />
    </Stagger>
  )
}
```

The wrapper is the grid item. Each child sits inside its own `div`, so a layout class on the child (`col-span-2`, `justify-self-end`) no longer reaches the grid: the wrapper is what the grid lays out. Two ways to put it where it counts:

- **The same class for every item:** `itemClassName` goes on each wrapper, for example `itemClassName="h-full"` so the cards fill their cells and match heights.
- **A different class per item:** wrap that child in a `Reveal` yourself and give the `Reveal` the class. A `Reveal` child isn't wrapped again, so it is the grid item.

```tsx
<Stagger className="grid grid-cols-3 gap-4" itemClassName="h-full">
  <Reveal className="col-span-2">
    <FeatureCard title="Previews" />
  </Reveal>
  <FeatureCard title="Rollbacks" />
  <FeatureCard title="Analytics" />
</Stagger>
```

`itemClassName` goes on the wrappers Stagger makes, not on a `Reveal` you wrote. Give your own `Reveal` the classes it needs, `h-full` included.

A `Reveal` child keeps its own variant, and its own `delay` adds to the cue the group gives it. Mix them when one item should arrive differently:

```tsx
<Stagger step="loose">
  <Reveal as="h2" variant="blur-in">Pricing</Reveal>
  <PlanCard plan="hobby" />
  <PlanCard plan="pro" />
</Stagger>
```

## Examples

### Order

`order` decides which child moves first. `start` reads top to bottom, `end` runs in reverse, and `center` ripples out from the middle of the sequence. `random` shuffles the cues with a `seed`, so the server and the client agree on the order and the page hydrates without a jump.

```tsx
'use client'

import { Stagger, type StaggerOrder } from '@youj/motion'

const ORDERS: StaggerOrder[] = ['start', 'end', 'center', 'random']

export default function StaggerOrders() {
  return (
    <div className="grid grid-cols-2 gap-x-12 gap-y-8 sm:grid-cols-4 sm:gap-x-8">
      {ORDERS.map((order) => (
        <figure key={order} className="flex flex-col items-center gap-3">
          {/* The same 25 tiles each time. Only the order of their cues changes. */}
          <Stagger aria-hidden order={order} variant="scale" inView={false} className="grid grid-cols-5 gap-1">
            {Array.from({ length: 25 }, (_, i) => (
              <div key={i} className="size-5 rounded-[5px] bg-accent" />
            ))}
          </Stagger>
          <figcaption className="font-mono text-xs text-fg-muted">{order}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

Ranks follow the children's order in the source, not their position on screen. In a grid, `center` starts from the middle item and works outward in both directions.

### Lists

Pass `as="ul"` and `itemAs="li"` to keep list semantics. Each child is wrapped in an animated `li`, so screen readers still announce a list and its length. A `tight` step with `fade` suits dense rows.

```tsx
'use client'

import { Stagger } from '@youj/motion'
import { CheckCircleIcon } from '@youj/icons'

const LOG = [
  { step: 'Cloned youj-web at 4f2a91c', time: '0.4s' },
  { step: 'Installed 312 packages', time: '6.1s' },
  { step: 'Compiled 48 routes', time: '11.8s' },
  { step: 'Uploaded 1.4 MB of static assets', time: '2.2s' },
  { step: 'Assigned youj.io', time: '0.3s' },
]

export default function StaggerList() {
  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <p className="border-b border-line px-4 py-2.5 text-xs font-medium text-fg-muted">Build log</p>
      {/* A real list: `as="ul"` and `itemAs="li"` keep the semantics, and the tight step reads as one sweep. */}
      <Stagger as="ul" itemAs="li" step="tight" variant="fade" inView={false} className="divide-y divide-line">
        {LOG.map(({ step, time }) => (
          <div key={step} className="flex items-center gap-3 px-4 py-2.5 text-sm">
            <CheckCircleIcon size={16} className="text-success" />
            <span className="min-w-0 flex-1 truncate text-fg">{step}</span>
            <span className="font-mono text-xs text-fg-muted">{time}</span>
          </div>
        ))}
      </Stagger>
    </div>
  )
}
```

### When it plays

With the default `inView`, the group plays once, when 20% of it is on screen. Pass an object to change that: `inView={{ amount: 0.5 }}`, `margin` to start earlier or later, and `once: false` to replay every time it comes back into view. `inView={false}` plays as soon as the group renders. Use it for content that is already on screen when the page opens.

`delay` holds the whole sequence back by a number of steps, so it stays on the same grid as the cues. `delay={3}` with `step="base"` waits three base steps before the first child moves.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `ElementType` | `'div'` |  |
| `itemAs` | `'div' \| 'span' \| 'section' \| 'article' \| 'header' \| 'footer' \| 'li' \| 'p' \| 'h1' \| 'h2' \| 'h3' \| 'figure'` | `'div'` | Tag for the Reveal wrapper around children that aren't already a Reveal. |
| `itemClassName` | `string` |  |  |
| `variant` | `'fade' \| 'rise' \| 'blur-in' \| 'scale' \| 'wipe-up' \| 'wipe-down' \| 'wipe-left' \| 'wipe-right'` | `'rise'` | Variant for wrapped children. Reveal children keep their own. |
| `step` | `'tight' \| 'base' \| 'loose'` | `'base'` |  |
| `order` | `'start' \| 'end' \| 'center' \| 'random'` | `'start'` |  |
| `seed` | `number` | `1` | Seed for 'random' order. |
| `delay` | `number` | `0` | Initial delay, in `step`s. |
| `inView` | `InView` |  | When it plays: `false` on mount; `true` (the default) when scrolled into view, once, at 20% visible; or `{ once, amount, margin }`. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Cue offset | `stagger.base` | 40ms step | between neighboring ranks, default `step` |
| Dense lists | `stagger.tight` | 24ms step | `step="tight"` |
| Hero sections | `stagger.loose` | 72ms step | `step="loose"` |
| Each child | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the default `rise` variant |

**Reduced motion:** Every child renders in its final state at once. There's no sequence and no travel.

Each child animates with its Reveal variant, so the timing of one item is the same as a lone Reveal. Only the start times differ.

#### Reduced motion

The group appears complete, with no cascade. Nothing is hidden or delayed, so the page reads the same with or without motion. Switch on Reduced motion in any preview above to compare.

### Accessibility

- Every child is in the document from the first render, in source order, so assistive technology reads the whole group whether or not it has played.
- Stagger adds no roles. Use `as` and `itemAs` to give the group and its items their semantics.
- The sequence plays once by default. Content that re-animates each time it scrolls past distracts, and it's hard to read for people with attention or vestibular conditions.

---

# TextSplit

> Reveal text by character, word or line while keeping one readable copy for assistive technology.

Source: https://www.youj.dev/docs/motion/text-split

```tsx
'use client'

import { TextSplit } from '@youj/motion'

export default function TextSplitDemo() {
  return (
    <article className="w-full max-w-xl">
      {/* Three cues, one gesture: the kicker by character, the headline by measured line, the deck by word. */}
      <TextSplit as="p" by="chars" variant="fade" inView={false} className="font-mono text-xs tracking-[0.18em] text-accent uppercase">
        Launch week · Day 3
      </TextSplit>
      <TextSplit
        as="p"
        by="lines"
        mask
        inView={false}
        delay={1}
        duration="deliberate"
        className="mt-4 text-3xl leading-[1.1] font-semibold tracking-tight text-balance text-fg sm:text-4xl"
      >
        Every branch gets a preview you can share in seconds.
      </TextSplit>
      <TextSplit
        as="p"
        by="words"
        variant="blur-in"
        step="tight"
        inView={false}
        delay={14}
        className="mt-5 text-[15px] leading-relaxed text-fg-muted"
      >
        Previews build from every push with their own URL, logs and analytics, and promote to production without a rebuild.
      </TextSplit>
      <div className="mt-7 flex items-center gap-3 border-t border-line pt-5 text-sm text-fg-muted">
        <span aria-hidden className="grid size-8 place-items-center rounded-full bg-raised text-xs font-medium text-fg">
          PR
        </span>
        <span>Priya Raman · 4 min read</span>
      </div>
    </article>
  )
}
```

Use it on display type that earns an entrance: a launch headline, a hero, a section opener. Keep it off body copy, labels and anything people need to read the moment the page opens. For a block of content use [Reveal](https://www.youj.dev/docs/motion/reveal), and for a group of elements use [Stagger](https://www.youj.dev/docs/motion/stagger).

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { TextSplit } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add text-split
```

It brings `youj-core`, `reveal` with it.

## Usage

Pass the text as a string and choose what to split it by. By default it splits by word and rises into place the first time 40% of it is on screen.

```tsx
import { TextSplit } from '@youj/motion'

export function Headline() {
  return (
    <TextSplit as="h1" by="lines" mask className="text-5xl font-semibold tracking-tight">
      Every branch gets a preview you can share in seconds.
    </TextSplit>
  )
}
```

`as` sets the element, so a heading stays a heading. `children` must be a plain string: the split needs the characters themselves.

## Examples

### Split modes

`by` chooses the unit. Each mode has its own default step, because a character is small and a line is large: `chars` uses `tight`, `words` uses `base` and `lines` uses `loose`. Any [Reveal variant](https://www.youj.dev/docs/motion/reveal#variants) works for the units, and `step` overrides the default.

```tsx
'use client'

import { TextSplit, type RevealVariant, type SplitBy } from '@youj/motion'

const MODES: { by: SplitBy; variant: RevealVariant; text: string; className: string }[] = [
  { by: 'chars', variant: 'rise', text: 'Instant rollbacks', className: 'text-2xl font-semibold tracking-tight text-fg' },
  { by: 'words', variant: 'blur-in', text: 'Word by word, into focus', className: 'text-2xl font-semibold tracking-tight text-fg' },
  {
    by: 'lines',
    variant: 'wipe-right',
    text: 'Line mode groups words by where they actually wrapped, and measures again when the container resizes or web fonts finish loading.',
    className: 'text-base leading-relaxed text-fg-muted',
  },
]

export default function TextSplitModes() {
  return (
    <div className="w-full max-w-xl space-y-8">
      {MODES.map(({ by, variant, text, className }) => (
        <div key={by}>
          <p className="mb-2 font-mono text-xs text-fg-muted">
            by="{by}" · {variant}
          </p>
          <TextSplit as="p" by={by} variant={variant} inView={false} className={className}>
            {text}
          </TextSplit>
        </div>
      ))}
    </div>
  )
}
```

In `chars` mode, each word stays in one unbreakable span, so a word never wraps in the middle.

### Masks

`mask` clips each unit to its own box. With `rise`, the travel grows from 12px to 105% of the unit's height, so each piece slides up from behind its own baseline instead of fading as it moves. Masked lines are the classic editorial headline.

```tsx
'use client'

import { TextSplit } from '@youj/motion'

export default function TextSplitMask() {
  return (
    <div className="grid w-full max-w-xl gap-10 sm:grid-cols-2">
      <figure>
        <TextSplit as="p" by="chars" inView={false} duration="slow" className="text-5xl font-semibold tracking-tight text-fg">
          Shipped
        </TextSplit>
        <figcaption className="mt-3 font-mono text-xs text-fg-muted">rise</figcaption>
      </figure>
      <figure>
        {/* Each character slides up from behind its own line box: travel defaults to 105% of its height. */}
        <TextSplit as="p" by="chars" mask inView={false} duration="slow" className="text-5xl font-semibold tracking-tight text-fg">
          Shipped
        </TextSplit>
        <figcaption className="mt-3 font-mono text-xs text-fg-muted">rise + mask</figcaption>
      </figure>
    </div>
  )
}
```

### Lines follow layout

Line mode groups words by where they actually wrapped. It measures an invisible copy of the text before the first paint, then again when the element's width changes and when web fonts finish loading. A regroup after the first play lands in place, already settled, so resizing never replays the entrance. Change the width below to see it.

```tsx
'use client'

import { useState } from 'react'
import { TextSplit } from '@youj/motion'
import { Slider } from '@youj/react'

export default function TextSplitResize() {
  const [width, setWidth] = useState(100)

return (
    <div className="w-full max-w-xl">
      <div className="mb-6 flex items-center gap-4">
        <span className="shrink-0 text-xs text-fg-muted">Column width</span>
        <Slider value={width} onValueChange={(v) => setWidth(v as number)} min={40} max={100} aria-label="Column width" />
        <span className="w-10 shrink-0 text-end font-mono text-xs text-fg-muted tabular-nums">{width}%</span>
      </div>
      <div style={{ width: `${width}%` }} className="rounded-xl border border-dashed border-line-strong p-5">
        {/* Lines are grouped from real layout. A new width regroups them in place, already settled. */}
        <TextSplit as="p" by="lines" mask inView={false} className="text-xl leading-snug font-medium tracking-tight text-fg">
          Measured from real layout, so the split always matches what you see, at any width and in any font.
        </TextSplit>
      </div>
    </div>
  )
}
```

### Choreography

`delay` counts steps of the unit's own step, like the units themselves, so several splits can share one grid. In the first preview the kicker plays by character, the headline starts one `loose` step later, and the deck follows on `tight` steps while the headline is still landing:

```tsx
<TextSplit as="p" by="chars" variant="fade" inView={false}>Launch week · Day 3</TextSplit>
<TextSplit as="h2" by="lines" mask inView={false} delay={1} duration="deliberate">…</TextSplit>
<TextSplit as="p" by="words" variant="blur-in" step="tight" inView={false} delay={14}>…</TextSplit>
```

`duration`, `ease` and `distance` tune the units the same way they tune a Reveal.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` |  | The text. Rendered once for assistive tech; the split copy is aria-hidden. |
| `as` | `ElementType` | `'span'` |  |
| `by` | `'chars' \| 'words' \| 'lines'` | `'words'` |  |
| `variant` | `'fade' \| 'rise' \| 'blur-in' \| 'scale' \| 'wipe-up' \| 'wipe-down' \| 'wipe-left' \| 'wipe-right'` | `'rise'` |  |
| `mask` | `boolean` | `false` | Clip each unit to its own box, so 'rise' slides up from behind a line. |
| `step` | `'tight' \| 'base' \| 'loose'` |  |  |
| `delay` | `number` | `0` | Initial delay, in `step`s. |
| `inView` | `InView` |  | When it plays: `false` on mount; `true` (the default) when scrolled into view, once, at 40% visible; or `{ once, amount, margin }`. |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` |  |  |
| `ease` | `'standard' \| 'enter' \| 'exit' \| 'emphasized' \| 'linear'` |  |  |
| `distance` | `number \| string` |  |  |

Also takes the props of `HTMLAttributes<HTMLElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Each unit | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | the default `rise`; `mask` travels 105% instead of 12px |
| Step, chars | `stagger.tight` | 24ms step |  |
| Step, words | `stagger.base` | 40ms step |  |
| Step, lines | `stagger.loose` | 72ms step |  |

**Reduced motion:** Renders the plain string in its final state, unsplit.

The units animate only `opacity`, `transform`, `filter` and `clip-path`, so a split never triggers layout while it plays.

#### Reduced motion

TextSplit renders the string as plain text in its element, with no split and no hidden copy, and skips line measurement entirely. The headline reads exactly as written, at once.

### Accessibility

- The full string is rendered once in a visually hidden span, and the split copy is `aria-hidden`. A screen reader reads the headline as a sentence, never letter by letter.
- With `as="h1"` or any other heading, the heading's accessible name is the whole string.
- Each unit is an element. Keep `chars` to short strings, and prefer `words` or `lines` for anything longer than a headline.

---

# TextEffect

> Render any text with a reveal: a split-flap board, a terminal, a decode, a blur-in or rolling reels.

Source: https://www.youj.dev/docs/motion/text-effect

```tsx
'use client'

import { useState } from 'react'
import { TextEffect, type TextEffectName } from '@youj/motion'

const EFFECTS: TextEffectName[] = ['blur-in', 'split-flap', 'terminal', 'decode', 'roll']
const LINES = ['Ship on Friday, calmly', 'Preview every change', 'Deploys that land']

export default function TextEffectDemo() {
  const [effect, setEffect] = useState<TextEffectName>('blur-in')
  const [line, setLine] = useState(0)

return (
    <div className="flex w-full max-w-xl flex-col items-center gap-8">
      <div role="radiogroup" aria-label="Effect" className="flex flex-wrap justify-center gap-1 rounded-lg border border-line bg-surface p-1">
        {EFFECTS.map((name) => (
          <button
            key={name}
            type="button"
            role="radio"
            aria-checked={effect === name}
            onClick={() => setEffect(name)}
            className="rounded-md px-2.5 py-1 font-mono text-xs text-fg-muted aria-checked:bg-selected aria-checked:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            {name}
          </button>
        ))}
      </div>
      {/* A new effect remounts it, so it plays from the start; a new line plays from the old one. */}
      <TextEffect
        key={effect}
        effect={effect}
        text={LINES[line]!}
        inView={false}
        prompt={effect === 'terminal' ? '$ ' : undefined}
        erase
        as="p"
        className="text-center font-mono text-2xl font-semibold tracking-tight text-fg sm:text-3xl"
      />
      <button
        type="button"
        onClick={() => setLine((n) => (n + 1) % LINES.length)}
        className="rounded-md bg-fg px-3 py-1.5 text-xs font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
      >
        Next line
      </button>
    </div>
  )
}
```

Use it wherever a short piece of text arrives or changes and the change is worth seeing: a hero headline, a stat, a status line, a departures row. Pick the effect by what the text is. A board or a code reads well as `split-flap` or `roll`, a command or log line as `terminal`, a technical label as `decode`, and a headline or sentence as `blur-in`. Keep it to a few words or one sentence, and don't animate text people need to read at once, like an error message.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { TextEffect } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add text-effect
```

It brings `youj-core`, `scramble-text` with it.

## Usage

```tsx
import { TextEffect } from '@youj/motion'

export function Hero() {
  return <TextEffect as="h1" text="Interfaces that move with intent" />
}
```

It plays when half of it is on screen (`inView`; `inView={false}` plays on mount) and again whenever `text` changes, from the text it showed to the new one. The final text holds its box from the first frame, so nothing around it moves.

## Examples

### Effects

`effect` picks one of five:

- `blur-in`, the default: word by word, each sharpening out of a blur as it rises a little.
- `split-flap`: each character on a tile that flips through its alphabet to land, top half then bottom, across a hinge.
- `terminal`: typed out a keystroke at a time behind an optional `prompt`, with a block cursor that blinks while it waits.
- `decode`: random glyphs resolving into place. This is [ScrambleText](https://www.youj.dev/docs/motion/scramble-text), with TextEffect's box and timing.
- `roll`: each character on a reel that rolls up to it, like a slot or an odometer.

`split-flap` and `roll` pass through the target's own digits or letters (A–Z, a–z or 0–9), or through `glyphs` when you set one. A space or punctuation mark changes in one step, and a character that stays the same doesn't move.

### Departures board

Each cell of a board is its own `split-flap`. Pad each field to a fixed number of characters (`padEnd`) so the board never changes size, and a new page flips only the characters that changed.

```tsx
'use client'

import { useEffect, useState } from 'react'
import { useYouj } from '@youj/core'
import { TextEffect } from '@youj/motion'

const PAGES = [
  [
    ['08:15', 'LONDON', 'BOARDING'],
    ['08:32', 'PARIS NORD', 'ON TIME'],
    ['08:47', 'BRUXELLES', 'DELAYED'],
  ],
  [
    ['08:32', 'PARIS NORD', 'BOARDING'],
    ['08:47', 'BRUXELLES', 'EXP 09:02'],
    ['09:05', 'AMSTERDAM', 'ON TIME'],
  ],
]

export default function TextEffectBoard() {
  const k = useYouj()
  const [page, setPage] = useState(0)

// Turn the page on the token grid, so Speed reaches the timeline too.
  useEffect(() => {
    const timer = setInterval(() => setPage((p) => (p + 1) % PAGES.length), k.ms('deliberate') * 9)
    return () => clearInterval(timer)
  }, [k])

return (
    <section aria-label="Departures" className="rounded-xl border border-line bg-surface p-4 font-mono text-sm text-warning sm:text-base">
      <ul className="flex flex-col gap-1.5">
        {PAGES[page]!.map(([time, to, status], row) => (
          <li key={row} className="flex gap-2">
            {/* Padded to a fixed number of tiles, so the board never changes size. */}
            <TextEffect effect="split-flap" inView={false} text={time!} />
            <TextEffect effect="split-flap" inView={false} text={to!.padEnd(10)} />
            <TextEffect effect="split-flap" inView={false} text={status!.padEnd(9)} />
          </li>
        ))}
      </ul>
    </section>
  )
}
```

The tiles are `bg-well` with your text color; style them through `[&_[data-yj-flap]]:bg-…` on a parent.

### Status line

With `erase`, a terminal line deletes back to what the old and new text share before it types the rest, so `deploy: building` becomes `deploy: ready` by deleting `building` only. Style the prompt through `[&_[data-yj-prompt]]`.

```tsx
'use client'

import { useState } from 'react'
import { TextEffect } from '@youj/motion'

const STAGES = ['deploy: queued', 'deploy: building', 'deploy: ready on www.youj.dev']

export default function TextEffectTerminal() {
  const [stage, setStage] = useState(0)

return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <div className="rounded-xl border border-line bg-surface p-4 font-mono text-sm text-fg [&_[data-yj-prompt]]:text-accent">
        <TextEffect as="div" effect="terminal" prompt="$ " text="youj deploy --prod" inView={false} cursor={false} />
        {/* A live region, so a screen reader hears each settled status once. */}
        <div role="status" className="mt-2 text-fg-muted">
          <TextEffect effect="terminal" text={STAGES[stage]!} erase inView={false} />
        </div>
      </div>
      <button
        type="button"
        onClick={() => setStage((s) => (s + 1) % STAGES.length)}
        className="self-start rounded-md bg-fg px-3 py-1.5 text-xs font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas focus-visible:outline-none"
      >
        Next status
      </button>
    </div>
  )
}
```

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` |  | The text. Changing it plays the effect from the old text to the new one. |
| `effect` | `'split-flap' \| 'terminal' \| 'decode' \| 'blur-in' \| 'roll'` | `'blur-in'` | How the text arrives. |
| `as` | `ElementType` | `'span'` |  |
| `inView` | `InView` |  | When the first play starts: `false` on mount; `true` (the default) when scrolled into view, at 50% visible; or `{ once, amount, margin }`. |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` |  | One unit's motion: a flap's flip (split-flap, default 'fast'), a reel's roll (roll, 'deliberate'), a word's blur-in ('slow') or the whole decode ('deliberate'). Terminal doesn't use it. |
| `stagger` | `'tight' \| 'base' \| 'loose'` |  | The gap between units: characters (split-flap 'base', roll 'tight'), words (blur-in 'loose') or keystrokes (terminal 'loose', varied per key). A long text is compressed to land within the `deliberate` token. Decode doesn't use it. |
| `glyphs` | `string` |  | The alphabet decode draws noise from, and the one split-flap and roll pass through. Default: per character, its own digits, upper- or lower-case letters. |
| `prompt` | `string` |  | Terminal: a prefix shown before the text and never typed, such as `$ `. |
| `cursor` | `boolean` | `true` | Terminal: the block cursor. |
| `erase` | `boolean` | `false` | Terminal: on a text change, delete back to the shared start before typing the new text. |
| `onComplete` | `() => void` |  | Called when a play lands on the text (at once under reduced motion). |

Also takes the props of `HTMLAttributes<HTMLElement>`.

### Motion

`duration` is one unit's motion and `stagger` the gap between units. Each effect has its own defaults:

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Split-flap flip | `duration.fast`, `stagger.base` | 140ms; 40ms step | each flip; up to six per character, characters staggered |
| Roll | `duration.deliberate`, `ease.enter`, `stagger.tight` | 560ms; cubic-bezier(0.16, 1, 0.3, 1); 24ms step | each reel, characters staggered |
| Blur-in | `duration.slow`, `ease.enter`, `stagger.loose` | 340ms; cubic-bezier(0.16, 1, 0.3, 1); 72ms step | each word: blur, rise and fade, words staggered |
| Terminal keystroke | `stagger.loose` | 72ms step | uneven per key, longer after punctuation; erase deletes at twice the speed |
| Decode | `duration.deliberate` | 560ms | the whole decode |

**Reduced motion:** The final text shows at once, and new text swaps in place. The cursor holds still.

A long text keeps its stagger within the `deliberate` token, so twenty tiles land about as soon as five. Every effect runs on one animation frame loop per instance and moves only transforms, opacity and filter; the cursor blinks only while it's on screen.

#### Reduced motion

The text renders as it is, with no flips, typing, glyphs, blur or reels, and `onComplete` is called at once. A board shows its tiles and a terminal its prompt and a still cursor, so the look stays.

### Accessibility

- The text is rendered once in a visually hidden span, and the animated layer is `aria-hidden`. A screen reader reads the text, never the tiles, keystrokes or noise.
- To announce a change, put TextEffect inside a live region such as `role="status"`, as the status line above does.
- At rest the visible text is plain text you can select and copy; the hidden copy is left out of the selection.
- `blur-in` and `terminal` follow the reading direction, so a right-to-left line types and sharpens from the right. `split-flap` and `roll` animate each character on its own tile or reel, which breaks the joining of connected scripts such as Arabic: use `blur-in` or `terminal` there.
- `data-state` on the root is `idle`, `playing` or `done`, and `data-yj-effect` names the effect.

---

# ScrambleText

> Reveal short text through changing random characters.

Source: https://www.youj.dev/docs/motion/scramble-text

```tsx
'use client'

import { useEffect, useState } from 'react'
import { useYouj } from '@youj/core'
import { ScrambleText } from '@youj/motion'

const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
const HEX = '0123456789abcdef'

const STAGES = [
  { label: 'Queued', tone: 'text-fg-muted' },
  { label: 'Building', tone: 'text-warning' },
  { label: 'Deploying', tone: 'text-accent' },
  { label: 'Ready', tone: 'text-success' },
]
const COMMITS = ['4f2a91c', 'b81e07d', '19ce4a2', 'e0d7f35']

export default function ScrambleTextDemo() {
  const k = useYouj()
  const [stage, setStage] = useState(0)
  const [run, setRun] = useState(0)

// Walk through the stages on the token grid, so Speed reaches the timeline too.
  useEffect(() => {
    if (stage === STAGES.length - 1) return
    const timer = setTimeout(() => setStage((s) => s + 1), k.ms('deliberate') * 3)
    return () => clearTimeout(timer)
  }, [stage, k])

const current = STAGES[stage]!
  const ready = stage === STAGES.length - 1

return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border border-line bg-surface font-mono text-sm">
      <div className="flex items-center justify-between gap-4 border-b border-line px-4 py-3.5">
        <div className="min-w-0">
          <p className="text-[11px] tracking-[0.16em] text-fg-muted uppercase">Production</p>
          <p className="mt-0.5 font-sans text-[15px] font-semibold text-fg">youj-web</p>
        </div>
        {/* The default triggers, mount and change: each new stage decodes from the last. */}
        <span role="status" className={`flex items-center gap-2 text-xs font-medium ${current.tone}`}>
          <span aria-hidden className="size-1.5 rounded-full bg-current" />
          <ScrambleText glyphs={LETTERS} className="inline-block w-[9ch] uppercase">
            {current.label}
          </ScrambleText>
        </span>
      </div>
      <dl className="grid grid-cols-[88px_1fr] gap-y-2.5 px-4 py-3.5 text-xs">
        <dt className="text-fg-muted">Commit</dt>
        <dd className="text-fg">
          <ScrambleText glyphs={HEX}>{COMMITS[run % COMMITS.length]!}</ScrambleText>
        </dd>
        <dt className="text-fg-muted">Regions</dt>
        <dd className="text-fg">
          <ScrambleText trigger="mount">iad1 · fra1 · hnd1</ScrambleText>
        </dd>
        <dt className="text-fg-muted">Checksum</dt>
        <dd className={ready ? 'text-success' : 'text-fg-muted'}>
          <ScrambleText glyphs="01" duration="slow">
            {ready ? 'SHA-256 verified' : 'Pending'}
          </ScrambleText>
        </dd>
      </dl>
      <div className="flex justify-end border-t border-line px-4 py-3">
        <button
          type="button"
          onClick={() => {
            setStage(0)
            setRun((r) => r + 1)
          }}
          className="rounded-md bg-fg px-3 py-1.5 font-sans text-xs font-medium text-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface focus-visible:outline-none"
        >
          Redeploy
        </button>
      </div>
    </div>
  )
}
```

Use it for short technical strings that change: a deploy status, a commit hash, a region code, a label that reacts to hover. The noise says "computed", so keep it to a few words, and don't use it on sentences, prices or numbers people compare. For a number that moves, use [Counter](https://www.youj.dev/docs/motion/counter).

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { ScrambleText } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add scramble-text
```

It brings `youj-core` with it.

## Usage

```tsx
import { ScrambleText } from '@youj/motion'

export function DeployStatus({ status }: { status: string }) {
  return (
    <span role="status" className="font-mono text-xs uppercase">
      <ScrambleText>{status}</ScrambleText>
    </span>
  )
}
```

By default it decodes when it mounts and again whenever its text changes, starting from whatever it showed last. A monospace face, or a fixed width such as `w-[9ch]`, keeps the layout still while the glyphs roll.

## Examples

### Triggers

`trigger` takes one of `mount`, `view`, `hover` and `change`, or an array of them.

- `mount` plays once, before the first paint.
- `view` plays once, when 60% of the element is on screen.
- `hover` plays when the pointer enters the element, and when the element itself takes focus.
- `change` plays when the text changes. Without it, new text swaps in place.

```tsx
'use client'

import { useState } from 'react'
import { ScrambleText } from '@youj/motion'

const SYMBOLS = '!<>-_\\/[]{}=+*^?#%&'
const ACTIONS = [
  { label: 'Redeploy', result: 'Redeploy of 4f2a91c queued' },
  { label: 'Roll back', result: 'Rolled back to b81e07d' },
  { label: 'Stream logs', result: 'Streaming logs from iad1' },
]

export default function ScrambleTextHover() {
  const [result, setResult] = useState('Hover or tab through the actions.')

return (
    <div className="flex w-full max-w-md flex-col items-center gap-5">
      <div className="flex flex-wrap justify-center gap-2">
        {ACTIONS.map(({ label, result }) => (
          // The scramble is the button itself, so keyboard focus plays it as well as the pointer.
          <ScrambleText
            key={label}
            as="button"
            trigger="hover"
            glyphs={SYMBOLS}
            duration="slow"
            onClick={() => setResult(result)}
            className="rounded-md border border-line bg-surface px-3 py-2 font-mono text-xs tracking-[0.12em] text-fg uppercase transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            {label}
          </ScrambleText>
        ))}
      </div>
      <p role="status" className="text-sm text-fg-muted">
        {result}
      </p>
    </div>
  )
}
```

`hover` listens on ScrambleText's own element. Render it as the control itself, with `as="button"`, so a keyboard user who tabs to it sees the same decode as the pointer. Focus on a wrapping button or link doesn't reach a child.

### Glyphs

`glyphs` is the alphabet the noise is drawn from. The default is upper-case letters and digits. Match it to the content, so the noise already looks like the answer: hex digits for a hash, `01` for a checksum, letters for a status.

```tsx
<ScrambleText glyphs="0123456789abcdef">{commit}</ScrambleText>
<ScrambleText glyphs="01" duration="slow">SHA-256 verified</ScrambleText>
```

Spaces stay spaces while the rest decodes, so the shape of the words reads early.

### Changing text

With `change` alone, nothing plays on mount, and every new string decodes from the one before. Here a secret decodes out of its mask and back.

```tsx
'use client'

import { useState } from 'react'
import { ScrambleText } from '@youj/motion'
import { EyeIcon } from '@youj/icons'

const VARIABLES = [
  { name: 'DATABASE_URL', value: 'postgres://app@db.youj.io/main' },
  { name: 'EDGE_CONFIG_ID', value: 'ecfg_7h1c4a9x2b8k' },
  { name: 'WEBHOOK_SECRET', value: 'kn_whsig_3d0q8Lm2Zr5t' },
]
const MASK = '•'.repeat(16)

function Variable({ name, value }: { name: string; value: string }) {
  const [shown, setShown] = useState(false)
  return (
    <li className="flex items-center gap-3 px-4 py-3">
      <div className="min-w-0 flex-1">
        <p className="font-mono text-xs text-fg-muted">{name}</p>
        <p className="mt-1 truncate font-mono text-sm text-fg">
          {/* Only `change`: nothing plays on mount, and each toggle decodes one way or the other. */}
          <ScrambleText trigger="change" aria-hidden={!shown || undefined}>
            {shown ? value : MASK}
          </ScrambleText>
          {!shown && <span className="sr-only">Hidden</span>}
        </p>
      </div>
      <button
        type="button"
        aria-pressed={shown}
        aria-label={`Show ${name}`}
        onClick={() => setShown((s) => !s)}
        className="grid size-8 shrink-0 place-items-center rounded-md text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none aria-pressed:text-accent"
      >
        <EyeIcon size={16} active={shown} />
      </button>
    </li>
  )
}

export default function ScrambleTextReveal() {
  return (
    <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <p className="border-b border-line px-4 py-2.5 text-xs font-medium text-fg-muted">Environment variables · Production</p>
      <ul className="divide-y divide-line">
        {VARIABLES.map((v) => (
          <Variable key={v.name} {...v} />
        ))}
      </ul>
    </div>
  )
}
```

The mask is hidden from assistive technology and replaced by the word "Hidden", so a screen reader never reads out sixteen bullets.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` |  | Target text. Changing it scrambles from the current text to the new one. |
| `as` | `ElementType` | `'span'` |  |
| `trigger` | `ScrambleTrigger \| ScrambleTrigger[]` | `['mount', 'change']` | When to play. |
| `glyphs` | `string` | `GLYPHS.alnum` | Characters used while decoding. |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` | `'deliberate'` | Total time for the last character to resolve. |
| `tick` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` | `'instant'` | How often unresolved glyphs re-roll. |
| `onComplete` | `() => void` |  | Called when a decode lands on the text (at once under reduced motion). |

Also takes the props of `HTMLAttributes<HTMLElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Decode | `duration.deliberate` | 560ms | positions resolve left to right with jitter; the last one lands at `duration` |
| Glyph re-roll | `duration.instant` | 80ms | unresolved positions redraw every half `tick` |

**Reduced motion:** The new text replaces the old at once. No glyphs.

Each position resolves at a time between 15% and 100% of `duration`, later for positions further right, with up to a quarter of the duration in random jitter. That reads as decoding rather than typing. Frames are written straight to the text node, so a decode never re-renders React.

#### Reduced motion

Text renders as it is and changes in place, instantly. Nothing decodes, on any trigger, and the status in the first preview simply reads Queued, Building, Deploying and Ready in turn.

### Accessibility

- The real text is rendered once in a visually hidden span, and the decoding copy is `aria-hidden`. A screen reader reads the text, never the noise.
- The hidden copy updates the moment the text changes. To announce a change, put ScrambleText inside a live region, as the status in the first preview does with `role="status"`.
- `hover` also plays on keyboard focus when ScrambleText is the focusable element. Give it `as="button"` rather than wrapping it.
- The effect is visual only. Keep it to short strings, because noise over a long string reads as broken.

---

# Counter

> A number that counts up, down or rolls to its new value, formatted for the provider's locale.

Source: https://www.youj.dev/docs/motion/counter

```tsx
'use client'

import { useState } from 'react'
import { Counter } from '@youj/motion'

const usd = { style: 'currency', currency: 'USD', maximumFractionDigits: 0 } as const

export default function CounterDemo() {
  const [yearly, setYearly] = useState(true)

return (
    <div className="w-full max-w-sm rounded-2xl border border-line bg-surface p-6 shadow-sm">
      <div className="flex items-center justify-between gap-4">
        <p className="text-sm font-medium text-fg">Pro</p>
        <div role="radiogroup" aria-label="Billing period" className="flex rounded-full border border-line bg-canvas p-0.5 text-xs">
          {[false, true].map((option) => (
            <button
              key={String(option)}
              type="button"
              role="radio"
              aria-checked={yearly === option}
              onClick={() => setYearly(option)}
              className={`rounded-full px-3 py-1 font-medium transition-colors duration-(--yj-duration-fast) ease-standard focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none ${
                yearly === option ? 'bg-fg text-canvas' : 'text-fg-muted hover:text-fg'
              }`}
            >
              {option ? 'Yearly' : 'Monthly'}
            </button>
          ))}
        </div>
      </div>
      <p className="mt-6 flex items-baseline gap-1.5">
        <Counter
          value={yearly ? 19 : 24}
          from={24}
          inView={false}
          format={usd}
          locale="en-US"
          className="text-5xl font-semibold tracking-tight text-fg"
        />
        <span className="text-sm text-fg-muted">/ seat / month</span>
      </p>
      <p className="mt-2 text-xs text-fg-muted">{yearly ? 'Billed yearly, save 20%' : 'Billed monthly, cancel anytime'}</p>
    </div>
  )
}
```

Use it where a number's change is the news: a price switching billing periods, a metric on a dashboard, a stat as it scrolls into view. Don't animate numbers people read in bulk or compare across rows, like table cells, and don't count a value the reader needs immediately, like a balance at checkout. Show those as plain text.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Counter } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add counter
```

It brings `youj-core`, `settled-entrances` with it.

## Usage

```tsx
import { Counter } from '@youj/motion'

export function Revenue({ total }: { total: number }) {
  return <Counter value={total} format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }} />
}
```

Formatting is plain `Intl.NumberFormat`, so currency, percent, compact notation, units and fraction digits all work, in any `locale`. Without one, it formats in the YoujProvider's locale (en-US without a provider). Numerals are tabular, so the width holds steady while the digits change.

## Examples

### Two modes

`tween`, the default, counts through every value in between. It suits a number's first arrival.

`roll` spins each digit in its own column, like an odometer. Columns are keyed by place value, so they keep their position as the number grows a digit. It suits values that update while you watch.

```tsx
'use client'

import { useState } from 'react'
import { Counter } from '@youj/motion'

export default function CounterRoll() {
  const [period, setPeriod] = useState(0)
  const stats = [
    { label: 'Revenue', value: 48210 + period * 1377, format: { style: 'currency', currency: 'USD', maximumFractionDigits: 0 } as const },
    { label: 'Requests', value: 1_240_000_000 + period * 83_000_000, format: { notation: 'compact', maximumFractionDigits: 2 } as const },
    { label: 'Uptime', value: 0.9998 - period * 0.0003, format: { style: 'percent', minimumFractionDigits: 2 } as const },
  ]

return (
    <div className="@container w-full max-w-xl">
      <div className="grid grid-cols-1 divide-y divide-line rounded-2xl border border-line bg-surface @lg:grid-cols-3 @lg:divide-x @lg:divide-y-0">
        {stats.map((stat) => (
          <div key={stat.label} className="p-5">
            <p className="text-xs text-fg-muted">{stat.label}</p>
            <Counter mode="roll" value={stat.value} format={stat.format} locale="en-US" className="mt-1.5 text-3xl font-semibold tracking-tight text-fg" />
          </div>
        ))}
      </div>
      <div className="mt-3 flex justify-end">
        <button
          type="button"
          onClick={() => setPeriod((p) => p + 1)}
          className="rounded-md border border-line bg-surface px-3 py-1.5 text-xs font-medium text-fg transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          Next period
        </button>
      </div>
    </div>
  )
}
```

### Changing values

Pass a new `value` at any time. The count retargets from the value it's showing, so there's no jump even mid-animation. Press the buttons below a few times in a row to see it.

```tsx
'use client'

import { useState } from 'react'
import { Counter } from '@youj/motion'

const compact = { notation: 'compact', maximumFractionDigits: 1 } as const

export default function CounterLive() {
  const [requests, setRequests] = useState(1_240_000)

return (
    <div className="w-full max-w-sm rounded-xl border border-line bg-surface p-5">
      <p className="text-sm text-fg-muted">Requests today</p>
      {/* A live region announces the settled value once, never the numbers in between. */}
      <p role="status" className="mt-1">
        <Counter value={requests} from={requests} inView={false} format={compact} locale="en-US" className="text-4xl font-semibold tracking-tight text-fg" />
      </p>
      <div className="mt-5 flex gap-2">
        {[25_000, 250_000].map((step) => (
          <button
            key={step}
            type="button"
            onClick={() => setRequests((r) => r + step)}
            className="rounded-lg border border-line bg-canvas px-3 py-1.5 text-xs font-medium text-fg transition-colors yj-duration-fast ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            +{new Intl.NumberFormat('en-US', compact).format(step)}
          </button>
        ))}
      </div>
      <p className="mt-3 text-xs text-fg-muted">Press quickly: each count retargets from where it is.</p>
    </div>
  )
}
```

In this demo the counter sits in a `role="status"` region, so a screen reader hears each settled total once. The counter doesn't add one itself.

### When it plays

The first play waits until half the number is on screen (`inView`), so a stat below the fold still gets its moment. Use `inView={false}` for numbers that are visible from the start, and `from` to set where the first count begins.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `from` | `number` | `0` | Starting value for the first play. |
| `mode` | `'tween' \| 'roll'` | `'tween'` | 'tween' counts through values; 'roll' spins each digit like an odometer. |
| `format` | `Intl.NumberFormatOptions` |  | Intl.NumberFormat options: currency, percent, compact notation, fraction digits. |
| `locale` | `string` |  | A BCP 47 locale. Default: the YoujProvider locale, en-US without one. |
| `inView` | `InView` |  | When the first play starts: `false` at once; `true` (the default) when scrolled into view, at 50% visible; or `{ amount, margin }` (it plays once). |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` | `'deliberate'` | Tween mode's duration. Roll mode rolls on the `smooth` spring. |
| `ease` | `'standard' \| 'enter' \| 'exit' \| 'emphasized' \| 'linear'` | `'emphasized'` | Tween mode's curve. |
| `cycle` | `number` |  | Roll mode, for a value that wraps around (60 for seconds or minutes, 24 for hours): a change of more than half the cycle is read as a wrap, so 00 → 59 rolls one step back, and the tens wheel holds only the digits the cycle reaches (0–5 for 60). |

Also takes the props of `HTMLAttributes<HTMLSpanElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Count | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | `tween` mode |
| Roll | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | `roll` mode, each digit column |
| Column offset | `stagger.tight` | 24ms step | per place value, ones first |

**Reduced motion:** Shows the formatted value immediately. New values swap in place.

The `emphasized` curve winds up briefly, moves fast through the middle and lands slowly, so the final digits are readable before the number stops.

#### Reduced motion

The formatted value shows at once, with no count and no roll. A new value swaps in place. The number is the information, and it's never delayed.

### Accessibility

- The formatted value is always in the document, in a visually hidden span, and the moving digits are `aria-hidden`. A screen reader hears "$48,210", never a run of intermediate numbers.
- A counter doesn't announce changes on its own. If a live value matters, wrap it in a live region such as `role="status"`, and it's announced once, at its final value.

---

# Marquee

> Loop supporting content horizontally or vertically, pausing on hover and focus.

Source: https://www.youj.dev/docs/motion/marquee

```tsx
'use client'

import { useState, type ComponentType } from 'react'
import { useYouj } from '@youj/core'
import { Marquee } from '@youj/motion'
import {
  CompassIcon,
  GaugeIcon,
  GlobeIcon,
  LayersIcon,
  PlayIcon,
  PuzzleIcon,
  RouteIcon,
  SnowflakeIcon,
  SparklesIcon,
  type IconProps,
} from '@youj/icons'

const CUSTOMERS: [string, ComponentType<IconProps>][] = [
  ['Northwind', LayersIcon],
  ['Halcyon', GlobeIcon],
  ['Vertex', CompassIcon],
  ['Orbital', SnowflakeIcon],
  ['Quanta', PuzzleIcon],
  ['Lumen', SparklesIcon],
  ['Parallel', RouteIcon],
  ['Cobalt', GaugeIcon],
]

function Logo({ name, Icon }: { name: string; Icon: ComponentType<IconProps> }) {
  return (
    <span className="flex items-center gap-2 text-fg-muted">
      <Icon size={22} strokeWidth={1.75} />
      <span className="text-lg font-semibold tracking-tight">{name}</span>
    </span>
  )
}

export default function MarqueeDemo() {
  const k = useYouj()
  const [paused, setPaused] = useState(false)
  const logos = CUSTOMERS.map(([name, Icon]) => <Logo key={name} name={name} Icon={Icon} />)

return (
    <div className="w-full max-w-2xl">
      <div className="mb-6 flex min-h-7 items-center justify-between gap-4 px-1">
        <p className="text-sm text-fg-muted">Trusted by product teams at</p>
        {/* Moving content needs a way to stop it: speed 0 holds the rows where they are. */}
        {!k.reduced && (
          <button
            type="button"
            onClick={() => setPaused((p) => !p)}
            className="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-fg-muted transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
          >
            <PlayIcon size={14} active={!paused} />
            {paused ? 'Play' : 'Pause'}
          </button>
        )}
      </div>
      <div className="space-y-6">
        <Marquee speed={paused ? 0 : 40} fade={64} gap={48}>
          {logos}
        </Marquee>
        {/* The second row repeats the first: hidden from assistive tech, and dropped when nothing moves. */}
        {!k.reduced && (
          <Marquee aria-hidden direction="right" speed={paused ? 0 : 32} fade={64} gap={48}>
            {[...logos].reverse()}
          </Marquee>
        )}
      </div>
    </div>
  )
}
```

Use it for supporting content that works as ambience: a wall of customer logos, a column of testimonials. Don't put anything people need to read or act on in a loop, like announcements, prices or the only link to a page. Show those in a static list.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Marquee } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add marquee
```

It brings `youj-core` with it.

## Usage

```tsx
import { Marquee } from '@youj/motion'

export function Customers() {
  return (
    <Marquee speed={40} fade={64}>
      <Logo name="Northwind" />
      <Logo name="Halcyon" />
      <Logo name="Vertex" />
    </Marquee>
  )
}
```

Marquee measures its content, repeats it just enough times to fill the track plus one, and moves the row by exactly one copy's length per cycle, so the seam never shows. It measures again when the track or the content resizes.

## Examples

### Direction and speed

`direction` is `left`, `right`, `up` or `down`. `speed` is in pixels per second at normal speed, so a long row and a short row move at the same pace. Two rows running opposite ways, at slightly different speeds, give a logo wall depth without drawing the eye.

`gap` spaces the items and the copies, and `fade` masks each edge over that many pixels. `fade={0}` turns the mask off.

### Fade

The same row in a frame, faded over 0, 48 and 96 pixels:

```tsx
'use client'

import type { ComponentType } from 'react'
import { Marquee } from '@youj/motion'
import { CompassIcon, GlobeIcon, LayersIcon, PuzzleIcon, SnowflakeIcon, SparklesIcon, type IconProps } from '@youj/icons'

export default function MarqueeFade() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      {[0, 48, 96].map((fade) => (
        <figure key={fade} className="flex flex-col gap-2">
          {/* The same row each time, in a frame. Only the width of the faded edges changes. */}
          <div className="overflow-hidden rounded-xl border border-line bg-surface py-3">
            <Marquee aria-hidden fade={fade} gap={32} speed={28}>
              {CUSTOMERS.map(([name, Icon]) => (
                <span key={name} className="flex items-center gap-1.5 text-fg-muted">
                  <Icon size={16} strokeWidth={1.75} />
                  <span className="text-sm font-semibold tracking-tight">{name}</span>
                </span>
              ))}
            </Marquee>
          </div>
          <figcaption className="font-mono text-xs text-fg-muted">
            {`fade={${fade}}`}
            {fade === 48 && ' · default'}
          </figcaption>
        </figure>
      ))}
    </div>
  )
}
```

`fade={0}` suits a row inside its own frame, where the frame's edge already ends it. On an open stage, a wider fade lets items drift in from nothing instead of crossing a line.

### Vertical

`up` and `down` stack the content in a column. A vertical marquee needs a height. This one is also a named, focusable region: focusing it with Tab stops it where it is, and under reduced motion, when the column becomes a scroll area, the keyboard can scroll it.

```tsx
'use client'

import { Marquee } from '@youj/motion'

const QUOTES = [
  { quote: 'Our previews went from a Slack thread to a link in every pull request.', who: 'Ana Lima', role: 'Design lead, Northwind' },
  { quote: 'Rollbacks take one click, and nobody holds their breath on release day.', who: 'Kenji Sato', role: 'Staff engineer, Halcyon' },
  { quote: 'We deleted three deploy scripts and a wiki page nobody trusted.', who: 'Sara Okafor', role: 'Platform, Quanta' },
  { quote: 'Edge config made feature flags boring, which is exactly what we wanted.', who: 'Jonas Weber', role: 'Frontend, Lumen' },
]

function Quote({ quote, who, role }: (typeof QUOTES)[number]) {
  return (
    <figure className="w-full rounded-xl border border-line bg-surface p-4">
      <blockquote className="text-sm leading-relaxed text-fg">“{quote}”</blockquote>
      <figcaption className="mt-3 text-xs text-fg-muted">
        <span className="font-medium text-fg">{who}</span> · {role}
      </figcaption>
    </figure>
  )
}

export default function MarqueeVertical() {
  return (
    <div className="grid w-full max-w-xl grid-cols-1 gap-3 sm:grid-cols-2">
      {/* The edge fade masks anything painted outside the marquee, so the focus ring sits on a wrapper. */}
      <div className="rounded-xl has-focus-visible:ring-2 has-focus-visible:ring-accent has-focus-visible:ring-offset-4 has-focus-visible:ring-offset-canvas">
        {/* Vertical loops need a height. Focusable and named: Tab eases the loop to a stop, and with
            reduced motion the column becomes a scroll area that keyboards can reach. */}
        <Marquee
          role="region"
          aria-label="Customer quotes"
          tabIndex={0}
          direction="up"
          speed={22}
          gap={12}
          fade={72}
          className="h-80 outline-none"
        >
          {QUOTES.map((q) => (
            <Quote key={q.who} {...q} />
          ))}
        </Marquee>
      </div>
      <Marquee aria-hidden direction="down" speed={16} gap={12} fade={72} className="hidden h-80 sm:block">
        {[...QUOTES].reverse().map((q) => (
          <Quote key={q.who} {...q} />
        ))}
      </Marquee>
    </div>
  )
}
```

### Pausing

Hover eases the loop to a stop, and leaving eases it back up, so a reader can finish a quote or reach a link. `pauseOnHover={false}` turns this off. Keyboard focus inside always stops it at once, and a focused item eases clear of the faded edges.

For anything that plays longer than five seconds, also give people a control to stop it. Setting `speed` to 0 holds the row where it is, as the Pause button in the first preview does:

```tsx
<Marquee speed={paused ? 0 : 40}>{logos}</Marquee>
```

The loop also pauses on its own while it's offscreen and while the tab is hidden, and a long frame, such as one after a tab switch, is clamped so the row never jumps.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `direction` | `'left' \| 'right' \| 'up' \| 'down'` | `'left'` | Which way the content travels. Left and right follow the reading direction: under RTL the row mirrors and they swap. |
| `speed` | `number` | `40` | Pixels per second at time scale 1. |
| `pauseOnHover` | `boolean` | `true` | Ease to a stop while hovered. Keyboard focus inside always stops it and brings the focused item into view. |
| `fade` | `number` | `48` | Width of the faded edges in px. 0 disables. |
| `gap` | `number` | `48` | Space between items and between copies, in px. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Loop |  | `speed` px/s, default 40 | constant velocity; divided by the time scale |
| Ease to a stop and back | `duration.slow` | 340ms | hover; the time constant of an exponential ease |
| Focused item into view | `duration.base` | 220ms | focus within stops the loop at once; the item eases clear of the fade |
| Frame clamp | `duration.instant` | 80ms | the longest step a single frame can take |

**Reduced motion:** One static row that wraps, or a scrollable column when vertical. No copies, no mask and no movement.

#### Reduced motion

Nothing moves. A horizontal marquee renders its content once, as a centered row that wraps onto new lines, and a vertical one becomes a column that scrolls. The edge fade is dropped, so every item is fully visible.

Design the rest of the section for it too. With nothing to pause, the first preview drops its Pause button, and it drops the second row, which would only repeat the first. Read `useYouj().reduced` to make choices like these.

### Accessibility

- One copy of the content is in the accessibility tree. The copies that fill the loop are `aria-hidden` and `inert`, so links inside them are never read or tabbed to twice.
- A second row that repeats the first should be hidden too, with `aria-hidden` on the Marquee, as in the first preview.
- Keyboard focus inside the marquee stops it, and Tab onto a link slides that link fully into view, so focus never lands on a half-hidden item. Pair it with a visible pause control for anything longer than a few seconds.
- The edge fade is a mask. It reaches a few pixels past the row on the other axis, so an item's own focus ring shows; a ring around the whole marquee goes on a wrapper, as the vertical preview does with `has-focus-visible:ring-2`.
- Don't put essential links or information only in a marquee: moving targets are hard to read and hard to hit.

---

# Parallax

> Add depth by moving, scaling, rotating or fading an element as the page scrolls.

Source: https://www.youj.dev/docs/motion/parallax

```tsx
'use client'

import { useRef, type CSSProperties } from 'react'
import { Parallax } from '@youj/motion'

// Each card drifts at its own depth: the larger the y range, the closer it feels.
const CARDS: { title: string; value: string; at: CSSProperties; y: number[]; rotate: number[] }[] = [
  { title: 'Deploys', value: '1,284', at: { insetInlineStart: '3%', top: '12%' }, y: [90, -90], rotate: [-4, 2] },
  { title: 'P95 latency', value: '84 ms', at: { insetInlineEnd: '3%', top: '6%' }, y: [160, -160], rotate: [3, -2] },
  { title: 'Error rate', value: '0.02%', at: { insetInlineEnd: '6%', top: '66%' }, y: [50, -50], rotate: [0, 0] },
  { title: 'Edge hits', value: '98.7%', at: { insetInlineStart: '6%', top: '70%' }, y: [200, -200], rotate: [2, -3] },
]

export default function ParallaxDemo() {
  const frame = useRef<HTMLDivElement>(null)

return (
    <div
      ref={frame}
      role="region"
      aria-label="Observability"
      tabIndex={0}
      className="relative h-[340px] w-full max-w-2xl overflow-y-auto rounded-xl border border-line bg-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
    >
      <p className="px-5 pt-5 text-xs text-fg-muted">Scroll inside the frame</p>
      <section className="relative mt-16 mb-24 h-[520px] overflow-hidden">
        {/* The backdrop moves least, so it reads as the far plane. */}
        <Parallax
          container={frame}
          y={[-30, 30]}
          aria-hidden
          className="absolute -inset-y-10 inset-x-0 [background-image:radial-gradient(var(--color-line)_1px,transparent_1px)] [background-size:20px_20px]"
        />
        <div className="absolute inset-0 flex flex-col items-center justify-center px-6 text-center">
          <p className="font-mono text-xs tracking-[0.2em] text-accent uppercase">Observability</p>
          <p className="mt-3 max-w-[13rem] text-3xl font-semibold tracking-tight text-balance text-fg">Every request, in view.</p>
        </div>
        {CARDS.map(({ title, value, at, y, rotate }) => (
          <Parallax
            key={title}
            container={frame}
            y={y}
            rotate={rotate}
            className="absolute w-28 rounded-xl border border-line bg-surface p-3 shadow-sm sm:w-36"
            style={at}
          >
            <p className="text-xs text-fg-muted">{title}</p>
            <p className="mt-0.5 text-lg font-semibold tracking-tight text-fg">{value}</p>
          </Parallax>
        ))}
      </section>
    </div>
  )
}
```

Use it to give a marketing scene depth: layered product shots, floating cards around a headline, a backdrop that moves slower than the content. Keep it off anything people read while they scroll, like articles, lists and app screens. Drifting text is tiring, and large movement can make some people feel unwell.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Parallax } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add parallax
```

It brings `youj-core` with it.

## Usage

Give it an output range for each property you want to move. With no `container`, it follows the page's scroll.

```tsx
import { Parallax } from '@youj/motion'

export function Hero() {
  return (
    <section className="relative">
      <Parallax y={[-60, 60]} className="absolute inset-0">
        <HeroBackdrop />
      </Parallax>
      <Parallax y={[40, -40]} rotate={[-3, 2]}>
        <ProductShot />
      </Parallax>
    </section>
  )
}
```

`x` and `y` are in pixels, `rotate` in degrees, and `scale` and `opacity` are plain numbers. A property you don't pass stays at rest.

## Examples

### Layers

Depth comes from contrast between speeds. Give far layers small ranges and near layers large ones, and let the ranges run against the scroll, so near things seem to rise past far ones.

```tsx
'use client'

import { useRef } from 'react'
import { Parallax } from '@youj/motion'
import { CheckCircleIcon } from '@youj/icons'

export default function ParallaxLayers() {
  const frame = useRef<HTMLDivElement>(null)

return (
    <div
      ref={frame}
      role="region"
      aria-label="Deploy preview"
      tabIndex={0}
      className="relative h-[300px] w-full max-w-lg overflow-y-auto rounded-xl border border-line bg-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
    >
      <div className="relative mx-auto my-24 h-72 w-72 max-w-full">
        {/* Far: the browser window barely moves. */}
        <Parallax container={frame} y={[30, -30]} className="absolute inset-x-0 top-6 rounded-xl border border-line bg-surface shadow-sm">
          <div className="flex gap-1.5 border-b border-line px-3 py-2.5">
            {[0, 1, 2].map((dot) => (
              <span key={dot} aria-hidden className="size-2 rounded-full bg-raised" />
            ))}
          </div>
          <div aria-hidden className="space-y-2 p-4">
            <div className="h-3 w-2/3 rounded bg-raised" />
            <div className="h-3 w-full rounded bg-raised" />
            <div className="h-3 w-5/6 rounded bg-raised" />
            <div className="mt-4 h-20 rounded-lg bg-accent-subtle" />
          </div>
        </Parallax>
        {/* Middle: the toast drifts further. */}
        <Parallax
          container={frame}
          y={[110, -110]}
          className="absolute -end-4 top-44 flex items-center gap-2.5 rounded-lg border border-line bg-surface px-3 py-2 shadow-md"
        >
          <CheckCircleIcon size={16} className="text-success" />
          <span className="text-xs font-medium text-fg">Deployed in 38s</span>
        </Parallax>
        {/* Near: the badge moves most, and a little sideways. */}
        <Parallax
          container={frame}
          y={[190, -190]}
          x={[-12, 12]}
          className="absolute -start-3 top-2 rounded-full bg-accent px-2.5 py-1 font-mono text-[11px] font-medium text-on-accent shadow-md"
        >
          main · 4f2a91c
        </Parallax>
      </div>
    </div>
  )
}
```

### Stops

By default each range maps across two stops, `input={[0, 1]}`: from the moment the element enters the viewport to the moment it leaves. Add stops to shape the curve. With three, each release below reaches full size as it crosses the middle of the frame, while a glow behind it fades up and away.

```tsx
'use client'

import { useRef } from 'react'
import { useYouj } from '@youj/core'
import { Parallax } from '@youj/motion'

const RELEASES = [
  { version: '2.4', title: 'Previews for every branch', date: 'Sep 12' },
  { version: '2.3', title: 'Instant rollbacks', date: 'Aug 21' },
  { version: '2.2', title: 'Edge config', date: 'Jul 30' },
  { version: '2.1', title: 'Webhooks, signed', date: 'Jul 02' },
  { version: '2.0', title: 'A new build pipeline', date: 'Jun 10' },
]

export default function ParallaxFocus() {
  const k = useYouj()
  const frame = useRef<HTMLDivElement>(null)

return (
    <div
      ref={frame}
      role="region"
      aria-label="Releases"
      tabIndex={0}
      className="relative h-[300px] w-full max-w-sm overflow-y-auto rounded-xl border border-line bg-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
    >
      <ol className="space-y-3 px-5 py-28">
        {RELEASES.map(({ version, title, date }) => (
          <li key={version} className="relative">
            {/* Three stops, peaking mid-frame. The glow fades; the text never does. With nothing
                moving, a glow on every card would mean nothing, so it's left out. */}
            {!k.reduced && (
              <Parallax
                container={frame}
                input={[0, 0.5, 1]}
                opacity={[0, 1, 0]}
                aria-hidden
                className="absolute -inset-1 rounded-2xl bg-accent-line blur-md"
              />
            )}
            <Parallax
              container={frame}
              input={[0, 0.5, 1]}
              scale={[0.94, 1, 0.94]}
              className="relative flex items-center gap-4 rounded-xl border border-line bg-surface p-4"
            >
              <span className="font-mono text-sm text-accent">{version}</span>
              <span className="min-w-0 flex-1 truncate text-sm font-medium text-fg">{title}</span>
              <span className="text-xs text-fg-muted">{date}</span>
            </Parallax>
          </li>
        ))}
      </ol>
    </div>
  )
}
```

```tsx
<li className="relative">
  <Parallax input={[0, 0.5, 1]} opacity={[0, 1, 0]} aria-hidden className="absolute -inset-1 rounded-2xl bg-accent-line blur-md" />
  <Parallax input={[0, 0.5, 1]} scale={[0.94, 1, 0.94]} className="relative">
    <ReleaseCard />
  </Parallax>
</li>
```

Values interpolate linearly between stops and hold at the ends. Only the glow fades: text that fades with the scroll drops below a readable contrast at the edges of the frame, and people can stop scrolling anywhere.

### Scroll containers and offsets

`container` takes a ref to an element that scrolls on its own. Every preview on this page uses one, so it works inside the frame. Give that element `tabIndex={0}` and a name, so it can be scrolled from the keyboard.

`offset` sets which scroll positions count as 0 and 1. The default, `['start end', 'end start']`, runs from the element's top meeting the bottom of the viewport to its bottom meeting the top. To finish a move by the time the element is centered, end it earlier:

```tsx
<Parallax offset={['start end', 'center center']} y={[80, 0]} opacity={[0, 1]}>
  <Screenshot />
</Parallax>
```

Parallax follows vertical scroll.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` | `number[]` | `[0, 1]` | Scroll progress stops (0..1 of the element's pass through `offset`). |
| `x` | `number[]` |  | Output ranges, one value per `input` stop. Translate values are px. |
| `y` | `number[]` |  |  |
| `scale` | `number[]` |  |  |
| `rotate` | `number[]` |  |  |
| `opacity` | `number[]` |  |  |
| `offset` | `ScrollOffset` | `['start end', 'end start']` | Scroll offsets defining progress 0 and 1. |
| `container` | `RefObject<HTMLElement \| null>` |  |  |
| `spring` | `SpringToken \| false` | `'smooth'` | Spring-smooth the scroll input. Pass false to track it exactly. |
| `style` | `MotionStyle` |  |  |

Also takes the props of `HTMLMotionProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Scroll input | `spring.smooth` | 0.36s, bounce 0 | smooths the scroll progress; `spring={false}` tracks it exactly |
| Mapping |  | no easing | linear between `input` stops, clamped at the ends |

**Reduced motion:** The element sits at rest: no translate, scale or rotation, and full opacity.

The spring gives the layers a moment of inertia, so a fast fling settles instead of snapping. Every output is a transform or an opacity, so scrolling never triggers layout.

#### Reduced motion

Every layer sits still at its resting position, fully opaque, as if the scene were a static composition. Scrolling moves the page and nothing else.

An element at rest isn't always the right static design. A glow that marks the card in focus would light every card at once, so the release list leaves the glows out when `useYouj().reduced` is true.

### Accessibility

- Parallax only transforms. The element keeps its place in the document and the reading order.
- Movement tied to scroll is a known trigger for vestibular disorders. Reduced motion turns it off completely, and keeping ranges modest helps everyone else.
- Don't fade text people need below a readable contrast. In the release list, the text stays at full contrast in every position, and only a decorative glow fades.
- A contained scene needs a focusable, named scroll container to be reachable from the keyboard.

---

# ScrollProgress

> Show reading progress through a page or scroll container as a bar or ring.

Source: https://www.youj.dev/docs/motion/scroll-progress

```tsx
'use client'

import { useRef } from 'react'
import { ScrollProgress } from '@youj/motion'

const SECTIONS = [
  [
    'Previews for every branch',
    'Every push builds its own preview with a stable URL, its own logs and its own analytics. Share it in the pull request, and reviewers see the change running, not a screenshot of it.',
    'Comments pin to the element they’re about, and they follow it across later pushes, so a thread never loses its place.',
  ],
  [
    'Promote without a rebuild',
    'A preview that passes review is promoted as it is. The bytes you tested are the bytes that ship, and promotion takes seconds instead of a full build.',
    'Promotion checks the same environment variables production uses, and it stops before anything goes live if one is missing.',
  ],
  [
    'Instant rollbacks',
    'Every production deployment stays warm. Rolling back points the domain at the previous one, so recovery is one click and no build at all.',
    'The rollback is recorded like a deploy, with who did it and why, so the incident timeline writes itself.',
  ],
  [
    'Edge config',
    'Flags and redirects are read at the edge in under a millisecond, and they change without a deploy.',
    'Every change is versioned. Diff two versions, or restore one, from the same page.',
  ],
]

export default function ScrollProgressDemo() {
  const article = useRef<HTMLDivElement>(null)

return (
    <div className="w-full max-w-xl overflow-hidden rounded-xl border border-line bg-surface">
      <div className="relative flex items-center justify-between gap-4 border-b border-line px-5 py-3.5">
        <div className="min-w-0">
          <p className="text-[11px] tracking-[0.16em] text-fg-muted uppercase">Changelog</p>
          <p className="truncate text-sm font-semibold text-fg">What shipped in 2.4</p>
        </div>
        {/* Both track the article's own scroll container, not the page. The bar repeats the ring, so only the ring is exposed. */}
        <ScrollProgress variant="ring" container={article} size={28} thickness={2.5} label="Reading progress" />
        <div aria-hidden className="absolute inset-x-0 -bottom-px">
          <ScrollProgress container={article} />
        </div>
      </div>
      <div
        ref={article}
        role="region"
        aria-label="What shipped in 2.4"
        tabIndex={0}
        className="h-64 overflow-y-auto px-5 py-5 focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none focus-visible:ring-inset"
      >
        {SECTIONS.map(([title, lead, detail], i) => (
          <section key={title} className={i > 0 ? 'mt-7' : undefined}>
            <p className="flex items-baseline gap-2.5 text-[15px] font-semibold text-fg">
              <span className="font-mono text-xs text-accent">0{i + 1}</span>
              {title}
            </p>
            <p className="mt-2 text-sm leading-relaxed text-fg-muted">{lead}</p>
            <p className="mt-2 text-sm leading-relaxed text-fg-muted">{detail}</p>
          </section>
        ))}
      </div>
    </div>
  )
}
```

Use it where reading position matters: long articles, docs, changelogs, a long settings page. It answers "how much is left?" at a glance. Skip it on short pages, where there's nothing to track, and don't use it for the progress of a task, like an upload or a build. That's [Progress](https://www.youj.dev/docs/components/progress).

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { ScrollProgress } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add scroll-progress
```

It brings `youj-core`, `youj-labels-scroll-progress` with it.

## Usage

With no `container`, it tracks the page. ScrollProgress doesn't position itself, so place it where it should sit:

```tsx
import { ScrollProgress } from '@youj/motion'

export function ArticleLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <ScrollProgress className="fixed inset-x-0 top-0 z-50" label="Reading progress" />
      <article>{children}</article>
    </>
  )
}
```

The bar fills its width with a 2px accent line, and grows by `scaleX` from the left.

## Examples

### Scroll containers

Pass a ref to track an element that scrolls on its own, like the article panel above. Give that element `tabIndex={0}` and a name, so keyboard users can reach and scroll it.

```tsx
const article = useRef<HTMLDivElement>(null)

<ScrollProgress variant="ring" container={article} size={28} thickness={2.5} />
<div ref={article} role="region" aria-label="Changelog" tabIndex={0} className="h-64 overflow-y-auto">…</div>
```

When two indicators show the same scroll, as the ring and the bar do here, expose one of them. The bar sits in an `aria-hidden` wrapper, so a screen reader finds one progress bar, not two.

### Ring

`variant="ring"` draws the progress around a circle, starting at twelve o'clock. `size` is its diameter and `thickness` its stroke, both in pixels. Around a back-to-top button, it shows how far down you are and offers the way back up.

```tsx
'use client'

import { useRef } from 'react'
import { useYouj } from '@youj/core'
import { ScrollProgress } from '@youj/motion'
import { ArrowUpIcon } from '@youj/icons'

const EVENTS = [
  'Ana Lima promoted b81e07d to production',
  'Build 1,284 passed in 38s',
  'Kenji Sato opened “Tighten cache headers”',
  'Preview ready for feat/pricing',
  'Sara Okafor rotated WEBHOOK_SECRET',
  'Edge config updated: checkout-v2 at 50%',
  'Build 1,283 failed: 2 type errors',
  'Jonas Weber rolled back to 4f2a91c',
  'Domain youj.io verified',
  'Preview ready for fix/og-images',
  'Priya Raman invited 3 teammates',
  'Build 1,282 passed in 41s',
]

export default function ScrollProgressBackToTop() {
  const k = useYouj()
  const feed = useRef<HTMLOListElement>(null)

return (
    <div className="relative w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
      <p className="border-b border-line px-4 py-2.5 text-xs font-medium text-fg-muted">Activity</p>
      <ol
        ref={feed}
        aria-label="Activity"
        tabIndex={0}
        className="h-60 divide-y divide-line overflow-y-auto pb-14 focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none focus-visible:ring-inset"
      >
        {EVENTS.map((event) => (
          <li key={event} className="px-4 py-2.5 text-sm text-fg">
            {event}
          </li>
        ))}
      </ol>
      {/* The ring doubles as the button's outline: progress on the way down, a way back up. */}
      <div className="absolute end-3 bottom-3 grid size-10 place-items-center">
        <ScrollProgress variant="ring" container={feed} size={40} thickness={2.5} label="Activity scrolled" className="absolute inset-0" />
        <button
          type="button"
          aria-label="Back to top"
          onClick={() => feed.current?.scrollTo({ top: 0, behavior: k.reduced ? 'auto' : 'smooth' })}
          className="relative grid size-8 place-items-center rounded-full bg-raised text-fg shadow-sm transition-colors duration-(--yj-duration-fast) ease-standard hover:bg-canvas focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
        >
          {/* ArrowUpIcon is a state icon (up or down): hold it up rather than letting hover flip it. */}
          <ArrowUpIcon size={16} trigger="none" />
        </button>
      </div>
    </div>
  )
}
```

The track uses the `line` token and the arc the `accent` token, so the ring follows the theme with no props.

### Horizontal

`axis="x"` follows horizontal scroll, for rails, carousels and wide tables.

```tsx
'use client'

import { useRef } from 'react'
import { ScrollProgress } from '@youj/motion'

const TEMPLATES = [
  { name: 'Commerce', stack: 'Next.js · Stripe' },
  { name: 'Docs', stack: 'MDX · Search' },
  { name: 'Blog', stack: 'Markdown · RSS' },
  { name: 'Dashboard', stack: 'Charts · Auth' },
  { name: 'Portfolio', stack: 'Images · Motion' },
  { name: 'Waitlist', stack: 'Forms · Email' },
  { name: 'Changelog', stack: 'Releases · Feeds' },
]

export default function ScrollProgressHorizontal() {
  const rail = useRef<HTMLUListElement>(null)

return (
    <div className="w-full max-w-xl">
      <ul
        ref={rail}
        aria-label="Templates"
        tabIndex={0}
        className="flex snap-x snap-mandatory gap-3 overflow-x-auto rounded-xl pb-4 focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
      >
        {TEMPLATES.map(({ name, stack }, i) => (
          <li key={name} className="w-44 shrink-0 snap-start overflow-hidden rounded-xl border border-line bg-surface">
            <div
              aria-hidden
              className="h-24 bg-raised"
              style={{ backgroundImage: `radial-gradient(90% 90% at ${15 + i * 12}% 20%, color-mix(in oklch, var(--color-accent) 32%, transparent), transparent 70%)` }}
            />
            <div className="p-3">
              <p className="text-sm font-medium text-fg">{name}</p>
              <p className="text-xs text-fg-muted">{stack}</p>
            </div>
          </li>
        ))}
      </ul>
      {/* axis="x" follows the rail's horizontal scroll. The track is a token-colored hairline. */}
      <div className="h-0.5 overflow-hidden rounded-full bg-line">
        <ScrollProgress container={rail} axis="x" label="Templates scrolled" />
      </div>
    </div>
  )
}
```

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'bar' \| 'ring'` | `'bar'` |  |
| `container` | `RefObject<HTMLElement \| null>` |  | Scroll container to track. Defaults to the page. |
| `axis` | `'y' \| 'x'` | `'y'` |  |
| `spring` | `'snappy' \| 'smooth' \| 'settle'` | `'smooth'` |  |
| `size` | `number` | `36` | Ring diameter in px. |
| `thickness` | `number` | `3` | Ring stroke width in px. |
| `label` | `string` |  |  |
| `className` | `string` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Progress | `spring.smooth` | 0.36s, bounce 0 | the bar scales on x; the ring draws its `pathLength` |
| Ring cap |  | progress 0 → 0.005 | fades in over the first 0.5%, so an empty ring never shows a dot |

**Reduced motion:** Tracks the scroll position directly, with no spring. The progress still shows.

`spring` swaps the default for another spring token: `snappy` follows the scroll more tightly. The spring only smooths the drawing, so a fast fling never makes the indicator lag behind the page for long.

#### Reduced motion

The indicator tracks the scroll position exactly, with no spring. Nothing else changes: the bar and the ring still show how far you've read, and the back-to-top button in the second preview jumps rather than scrolls smoothly.

### Accessibility

- It's a `progressbar` with a 0 to 100 range, named by `label`. Name it for what it measures, such as "Reading progress".
- `aria-valuenow` follows the raw scroll position, not the smoothed one, and it's written straight to the attribute, so scrolling never re-renders React.
- A scroll container needs `tabIndex={0}` and an accessible name to be reachable from the keyboard.
- The indicator is information, not decoration. It stays visible under reduced motion.

---

# Transitions

> Animate state changes in your components, from labels and selections to lists and pages.

Source: https://www.youj.dev/docs/motion/transitions

Use these transitions for changing labels, selections, lists and views. You supply the appearance and accessible behavior. Each transition supports interruption, follows Speed and has a reduced-motion state. They also power `@youj/react`.

- [Sliding Indicator](https://www.youj.dev/docs/motion/sliding-indicator): A highlight that glides to the selected item of any group, found from the attributes the items already carry.

- [Morph Label](https://www.youj.dev/docs/motion/morph-label): Content that crossfades between states while its box morphs to the new width.

- [Collapse](https://www.youj.dev/docs/motion/collapse): Height-auto disclosure that reverses from wherever it is.

- [Content Swap](https://www.youj.dev/docs/motion/content-swap): A skeleton that resolves into the content it stood in for.

- [Presence List](https://www.youj.dev/docs/motion/presence-list): List items and table rows that enter, leave and reorder without jumps.

- [Page Transition](https://www.youj.dev/docs/motion/page-transition): Fade-through, slide, clip reveal and curtain for routes and views.

## Where they're used

| Transition | For example, in `@youj/react` |
| --- | --- |
| Sliding Indicator | [Tabs](https://www.youj.dev/docs/components/tabs), [Toggle Group](https://www.youj.dev/docs/components/toggle-group), [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu), [Command](https://www.youj.dev/docs/components/command), [Pagination](https://www.youj.dev/docs/components/pagination), [Navigation Menu](https://www.youj.dev/docs/components/navigation-menu), [Sidebar](https://www.youj.dev/docs/components/sidebar) |
| Morph Label | [Async Button](https://www.youj.dev/docs/components/button#async-actions), through [Async Feedback](https://www.youj.dev/docs/components/async-feedback) |
| Collapse | [Alert](https://www.youj.dev/docs/components/alert) dismissal, [Field](https://www.youj.dev/docs/components/field) errors, [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists), [Tag Input](https://www.youj.dev/docs/components/tag-input), [Timeline](https://www.youj.dev/docs/components/timeline), [Tree View](https://www.youj.dev/docs/components/tree-view) |
| Content Swap | [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists) loading, [Stat Card](https://www.youj.dev/docs/components/stat-card) |
| Presence List | [Data tables](https://www.youj.dev/docs/blocks/tables-and-lists) rows, [Notification Center](https://www.youj.dev/docs/components/notification-center), [Prompt Input](https://www.youj.dev/docs/components/chat/prompt-input) |

For Base UI's own Collapsible, Accordion, popovers and dialogs, use the CSS [Overlay presets](https://www.youj.dev/docs/motion/presets) instead. [Composing components](https://www.youj.dev/docs/guides/composing-components) builds a full component from these.

---

# Sliding Indicator

> Highlight the selected item with an indicator that glides between options.

Source: https://www.youj.dev/docs/motion/sliding-indicator

```tsx
'use client'

import { useId, useState, type KeyboardEvent } from 'react'
import { SlidingIndicator } from '@youj/motion'
import { ActivityIcon, LayoutGridIcon, PuzzleIcon, SettingsIcon } from '@youj/icons'

const NAV = [
  { label: 'Projects', Icon: LayoutGridIcon },
  { label: 'Integrations', Icon: PuzzleIcon },
  { label: 'Activity', Icon: ActivityIcon },
  { label: 'Settings', Icon: SettingsIcon },
]
const TABS = ['Overview', 'Deployments', 'Analytics', 'Logs']
const RANGES = ['1h', '24h', '7d', '30d']

const item = 'rounded-md outline-none transition-colors yj-duration-fast ease-standard focus-visible:ring-2 focus-visible:ring-accent'

export default function SlidingIndicatorDemo() {
  const id = useId()
  const [page, setPage] = useState('Projects')
  const [tab, setTab] = useState(1)
  const [range, setRange] = useState('24h')

// Arrow keys move between tabs, and focus follows the selection.
  function onTabKey(e: KeyboardEvent<HTMLDivElement>) {
    if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return
    const next = (tab + (e.key === 'ArrowRight' ? 1 : TABS.length - 1)) % TABS.length
    setTab(next)
    document.getElementById(`${id}-tab-${next}`)?.focus()
  }

return (
    <div className="@container w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-surface">
      <div className="flex items-center justify-between gap-3 px-3 py-2">
        <p className="ps-1 text-sm font-medium text-fg">
          acme <span className="text-fg-muted">/</span> web
        </p>
        {/* A hover pill follows the pointer and keyboard focus, and fades out when both leave. */}
        <nav aria-label="Workspace" className="relative isolate flex items-center gap-0.5">
          <SlidingIndicator follow="hover" />
          {NAV.map(({ label, Icon }) => (
            <a
              key={label}
              href={`/acme/web/${label.toLowerCase()}`}
              aria-current={page === label ? 'page' : undefined}
              onClick={(e) => {
                e.preventDefault()
                setPage(label)
              }}
              className={`${item} inline-flex h-8 items-center gap-1.5 px-2.5 text-[13px] ${page === label ? 'text-fg' : 'text-fg-muted hover:text-fg'}`}
            >
              <Icon size={15} />
              <span className="sr-only @lg:not-sr-only">{label}</span>
            </a>
          ))}
        </nav>
      </div>

{/* The underline finds the tab with aria-selected="true". No wiring to state. */}
      <div role="tablist" aria-label="Project" onKeyDown={onTabKey} className="relative isolate flex gap-1 overflow-x-auto border-b border-line px-2 [scrollbar-width:none]">
        {TABS.map((label, i) => (
          <button
            key={label}
            id={`${id}-tab-${i}`}
            type="button"
            role="tab"
            aria-selected={tab === i}
            aria-controls={`${id}-panel`}
            tabIndex={tab === i ? 0 : -1}
            onClick={() => setTab(i)}
            className={`${item} my-1.5 px-2.5 py-1.5 text-sm ${tab === i ? 'text-fg' : 'text-fg-muted hover:text-fg'}`}
          >
            {label}
          </button>
        ))}
        <SlidingIndicator variant="underline" />
      </div>

<div role="tabpanel" id={`${id}-panel`} aria-labelledby={`${id}-tab-${tab}`} className="p-4">
        <div className="flex flex-wrap items-center justify-between gap-3">
          <div>
            <p className="text-sm font-medium text-fg">Requests</p>
            <p className="font-mono text-xs text-fg-muted">p95 82 ms · 0.02% errors</p>
          </div>
          {/* A segmented control: the pill sits on the button with aria-pressed="true". */}
          <div role="group" aria-label="Time range" className="relative isolate inline-flex rounded-lg bg-raised p-0.5">
            <SlidingIndicator className="rounded-md bg-surface shadow-sm ring-1 ring-line dark:bg-line" />
            {RANGES.map((r) => (
              <button
                key={r}
                type="button"
                aria-pressed={range === r}
                onClick={() => setRange(r)}
                className={`${item} h-7 min-w-10 px-2 font-mono text-xs ${range === r ? 'text-fg' : 'text-fg-muted hover:text-fg'}`}
              >
                {r}
              </button>
            ))}
          </div>
        </div>
        <div aria-hidden className="mt-4 flex h-20 items-end gap-1">
          {Array.from({ length: 32 }, (_, i) => (
            <span
              key={i}
              className="h-full flex-1 origin-bottom rounded-sm bg-accent-line transition-transform yj-duration-base ease-standard"
              style={{ transform: `scaleY(${(0.25 + 0.7 * Math.abs(Math.sin(i * 0.55 + RANGES.indexOf(range) * 1.3))).toFixed(3)})` }}
            />
          ))}
        </div>
      </div>
    </div>
  )
}
```

Use it for the selection or hover highlight of a group: tabs, segmented controls, toggle groups and navigation. It reads the selection from the items' ARIA and Base UI attributes, so it drops into a component with no wiring to its state. Don't use it as the only sign of selection. It's decoration, and the items must still carry their state, because that state is what it reads.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { SlidingIndicator } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add sliding-indicator
```

It brings `youj-core`, `youj-presets` with it.

## Usage

Render one inside the group's container, next to the items, and give the container `relative isolate`.

```tsx
import { SlidingIndicator } from '@youj/motion'

export function RangePicker({ value, onChange }: { value: string; onChange: (range: string) => void }) {
  return (
    <div role="group" aria-label="Time range" className="relative isolate inline-flex rounded-lg bg-well p-0.5">
      <SlidingIndicator className="rounded-md bg-surface shadow-sm" />
      {['24h', '7d', '30d'].map((range) => (
        <button key={range} type="button" aria-pressed={value === range} onClick={() => onChange(range)} className="h-7 px-2.5 text-xs">
          {range}
        </button>
      ))}
    </div>
  )
}
```

The indicator treats the container's other children as items and looks for the selected one, on each item or inside it:

- ARIA: `aria-selected="true"`, `aria-current` (any value but `false`), `aria-pressed="true"` and `aria-checked="true"`.
- Base UI: `data-active`, `data-pressed`, `data-checked` and `data-selected`.
- `data-state="active"`, `"on"` or `"checked"`, as Radix-style components write it.

A mutation observer watches exactly those attributes, so the indicator moves however the selection changes: a click, an arrow key, or a route change. When nothing matches, it fades out, and it fades back in place when something does.

## Examples

### The container

The container needs two classes, and each one does a job:

- `relative` makes the container the indicator's containing block. The indicator is absolutely positioned and measures each item against it.
- `isolate` starts a stacking context. The indicator sits at `-z-1`, behind the items' text. Without the stacking context, it would paint behind the group's own background, out of sight.

The selected item needs no background of its own, because the indicator is its background. Give the item a text color for its selected state and let the indicator do the rest.

### Variants

`pill`, the default, fills the item's box: `rounded-md bg-selected`. `underline` is a 2px bar along the item's bottom edge: `h-0.5 rounded-full bg-fg`. Restyle either with `className`, which merges over the defaults, as the segmented control in the first preview does. The corner radius is read from the computed style and set inline, so the corners stay round mid-glide.

### Hover, and two indicators

`follow="hover"` makes the indicator follow the pointer and keyboard focus instead of the selection. It skips disabled items, ignores touch, and fades out when the pointer and focus have both left the group. A group can hold two indicators. Here a hover pill and an underline for the current page share one nav, and each finds its own target.

```tsx
'use client'

import { useState } from 'react'
import { SlidingIndicator } from '@youj/motion'

const LINKS = ['Docs', 'Components', 'Templates', 'Changelog', 'Pricing']

export default function SlidingIndicatorHover() {
  const [current, setCurrent] = useState('Components')

return (
    <div className="w-full max-w-xl rounded-xl border border-line bg-surface px-1">
      {/* Two indicators in one group. The pill follows the pointer and keyboard focus;
          the underline stays on the current page. Each finds its own target. */}
      <nav aria-label="Site" className="relative isolate flex gap-0.5 overflow-x-auto px-1 py-2 [scrollbar-width:none]">
        <SlidingIndicator follow="hover" />
        <SlidingIndicator variant="underline" className="translate-y-2 bg-accent" />
        {LINKS.map((label) => (
          <a
            key={label}
            href={`/${label.toLowerCase()}`}
            aria-current={current === label ? 'page' : undefined}
            onClick={(e) => {
              e.preventDefault()
              setCurrent(label)
            }}
            className={`inline-flex h-8 shrink-0 items-center rounded-md px-3 text-sm outline-none transition-colors yj-duration-fast ease-standard focus-visible:ring-2 focus-visible:ring-accent ${
              current === label ? 'text-fg' : 'text-fg-muted hover:text-fg'
            }`}
          >
            {label}
          </a>
        ))}
      </nav>
    </div>
  )
}
```

The underline is moved to the bottom of the bar with `translate-y-2`. The `translate` property composes with the transform the glide uses, so the offset holds mid-flight.

In a menu, the pointer crosses separators, group labels and padding between rows, and the hover pill would blink out over each one. `linger` holds the pill on its last item for the `fast` token before it fades, so the next row takes it over in one glide. [Dropdown Menu](https://www.youj.dev/docs/components/dropdown-menu) uses it. Under reduced motion there's no hold.

### Any direction

Every position is measured, not assumed, so vertical lists, wrapping rows and right-to-left layouts need nothing extra. Resizes, font loads and reflows re-place the indicator without animating it. Only a change of target glides.

```tsx
'use client'

import { useState } from 'react'
import { SlidingIndicator } from '@youj/motion'
import { BellIcon, CreditCardIcon, KeyIcon, SettingsIcon, ShieldIcon, UsersIcon } from '@youj/icons'

const SECTIONS = [
  { label: 'General', Icon: SettingsIcon, detail: 'Project name, framework preset and root directory.' },
  { label: 'Members', Icon: UsersIcon, detail: 'Who can deploy, and who can only view.' },
  { label: 'Billing', Icon: CreditCardIcon, detail: 'Plan, usage and invoices for this team.' },
  { label: 'Security', Icon: ShieldIcon, detail: 'Deployment protection and trusted IPs.' },
  { label: 'Notifications', Icon: BellIcon, detail: 'Email and Slack alerts for failed builds.' },
  { label: 'API keys', Icon: KeyIcon, detail: 'Tokens for the CLI and CI pipelines.' },
]

export default function SlidingIndicatorVertical() {
  const [current, setCurrent] = useState('Billing')
  const section = SECTIONS.find((s) => s.label === current)!

return (
    <div className="@container w-full max-w-xl">
      <div className="grid gap-4 rounded-xl border border-line bg-surface p-2 @md:grid-cols-[180px_1fr]">
        {/* Measured, not assumed: the pill glides vertically as easily as across. */}
        <nav aria-label="Settings" className="relative isolate flex flex-col gap-0.5">
          <SlidingIndicator />
          {SECTIONS.map(({ label, Icon }) => (
            <a
              key={label}
              href={`/settings/${label.toLowerCase().replace(' ', '-')}`}
              aria-current={current === label ? 'page' : undefined}
              onClick={(e) => {
                e.preventDefault()
                setCurrent(label)
              }}
              className={`flex h-8 items-center gap-2.5 rounded-md px-2.5 text-sm outline-none transition-colors yj-duration-fast ease-standard focus-visible:ring-2 focus-visible:ring-accent ${
                current === label ? 'text-fg' : 'text-fg-muted hover:text-fg'
              }`}
            >
              <Icon size={15} />
              {label}
            </a>
          ))}
        </nav>
        <div className="rounded-lg border border-line bg-canvas p-4">
          <p className="text-sm font-medium text-fg">{section.label}</p>
          <p className="mt-1 text-sm text-fg-muted">{section.detail}</p>
        </div>
      </div>
    </div>
  )
}
```

### Matching your own state

When your items mark the selection some other way, pass a selector as `match`. The observer then watches the attributes, or the class, that the selector names.

```tsx
<SlidingIndicator match=".is-active" />
<SlidingIndicator match='[data-step="current"]' variant="underline" />
```

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'pill' \| 'underline'` | `'pill'` | 'pill' fills the item; 'underline' is a bar along its bottom edge. |
| `follow` | `'active' \| 'hover'` | `'active'` | 'active' follows the selected item; 'hover' follows the pointer and keyboard focus and fades out when they leave. |
| `match` | `string` | `ACTIVE` | Selector for the active item, tested on the items and inside them. |
| `linger` | `boolean` | `false` | When nothing matches (or the pointer leaves, with follow="hover"), hold the highlight on its last item for the fast token before fading, so crossing a gap, a separator or a group label glides on to the next item instead of blinking out. Menus want this. No hold under reduced motion. |

Also takes the props of `HTMLAttributes<HTMLSpanElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Glide | `spring.smooth` | 0.36s, bounce 0 | position and size, as a transform |
| Appear and fade | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | the hover pill, or no selection |
| Linger | `duration.fast` | 140ms | with `linger`, the hold before the pill fades |

**Reduced motion:** The indicator jumps to the new item. The hover pill appears and disappears without a fade.

The glide is Motion's layout projection: the indicator takes the new item's box, and a transform animates the difference, so nothing triggers layout. A new target mid-glide retargets from wherever the indicator is and keeps its velocity. Click through the tabs in the first preview quickly to see it.

#### Reduced motion

The indicator still marks the selected item. It moves there in one frame instead of gliding, and the hover pill shows and hides without a fade. The information is the same, it just doesn't travel.

### Accessibility

- The indicator is `aria-hidden` and ignores the pointer. The selection lives on the items, and that's what assistive technology announces.
- Keep a visible focus ring on the items. With `follow="hover"`, the pill follows keyboard focus as well as the pointer, but only for `:focus-visible` focus, so a mouse click doesn't leave a pill behind.
- Check the selected item's text against the indicator's color, not the group's background. That's the pair people read.

---

# Morph Label

> Change a label with a crossfade while its container adjusts to the new width.

Source: https://www.youj.dev/docs/motion/morph-label

```tsx
'use client'

import { useEffect, useState } from 'react'
import { motion } from 'motion/react'
import { useYouj } from '@youj/core'
import { MorphLabel, useMorphRoot } from '@youj/motion'
import { CheckIcon, CopyIcon, UserCheckIcon, UserPlusIcon } from '@youj/icons'

const box =
  'relative inline-flex h-8 shrink-0 items-center overflow-hidden px-3 text-[13px] font-medium outline-none transition-colors yj-duration-fast ease-standard focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface'

function CopyButton() {
  const k = useYouj()
  const morph = useMorphRoot(8)
  const [copied, setCopied] = useState(false)
  useEffect(() => {
    if (!copied) return
    const t = setTimeout(() => setCopied(false), k.ms('deliberate') * 3)
    return () => clearTimeout(t)
  }, [copied, k])
  return (
    <>
      <motion.button
        {...morph}
        type="button"
        onClick={() => {
          navigator.clipboard?.writeText('pnpm add @youj/motion').catch(() => {})
          setCopied(true)
        }}
        className={`${box} border border-line bg-surface text-fg hover:bg-raised`}
      >
        <MorphLabel value={copied ? 'copied' : 'copy'} contentClassName="gap-1.5">
          {copied ? <CheckIcon trigger="mount" size={14} strokeWidth={2} className="text-success" /> : <CopyIcon size={14} />}
          {copied ? 'Copied' : 'Copy install command'}
        </MorphLabel>
      </motion.button>
      {/* Outside the button: a button flattens its content, so a live region inside it isn't heard. */}
      <span role="status" className="sr-only">
        {copied ? 'Copied to clipboard' : ''}
      </span>
    </>
  )
}

function FollowButton() {
  const morph = useMorphRoot(9999)
  const [following, setFollowing] = useState(false)
  return (
    <motion.button
      {...morph}
      type="button"
      onClick={() => setFollowing((f) => !f)}
      className={`${box} ${following ? 'border border-line bg-raised text-fg' : 'bg-fg text-canvas'}`}
    >
      <MorphLabel value={following ? 'on' : 'off'} contentClassName="gap-1.5">
        {following ? <UserCheckIcon size={14} /> : <UserPlusIcon size={14} />}
        {following ? 'Following' : 'Follow'}
      </MorphLabel>
    </motion.button>
  )
}

const STATUSES = [
  { label: 'Draft', dot: 'bg-fg-muted' },
  { label: 'In review', dot: 'bg-warning' },
  { label: 'Changes requested', dot: 'bg-danger' },
  { label: 'Published', dot: 'bg-success' },
]

function StatusChip() {
  const morph = useMorphRoot(9999)
  const [i, setI] = useState(0)
  const status = STATUSES[i]!
  return (
    <div className="flex items-center gap-3">
      <motion.span {...morph} role="status" className="relative inline-flex h-6 items-center overflow-hidden border border-line bg-canvas px-2 text-xs text-fg">
        <MorphLabel value={status.label} contentClassName="gap-1.5">
          <span aria-hidden className={`size-1.5 rounded-full ${status.dot}`} />
          {status.label}
        </MorphLabel>
      </motion.span>
      <button
        type="button"
        onClick={() => setI((n) => (n + 1) % STATUSES.length)}
        className="rounded-sm text-xs text-fg-muted underline-offset-4 outline-none hover:text-fg hover:underline focus-visible:ring-2 focus-visible:ring-accent"
      >
        Next status
      </button>
    </div>
  )
}

export default function MorphLabelDemo() {
  return (
    <div className="w-full max-w-lg divide-y divide-line rounded-xl border border-line bg-surface">
      <div className="flex flex-wrap items-center justify-between gap-3 px-4 py-3.5">
        <div className="min-w-0">
          <p className="text-sm font-medium text-fg">@youj/motion</p>
          <p className="truncate font-mono text-xs text-fg-muted">pnpm add @youj/motion</p>
        </div>
        <CopyButton />
      </div>
      <div className="flex flex-wrap items-center justify-between gap-3 px-4 py-3.5">
        <div>
          <p className="text-sm font-medium text-fg">Ana Lima</p>
          <p className="text-xs text-fg-muted">Maintainer · 142 contributions</p>
        </div>
        <FollowButton />
      </div>
      <div className="flex flex-wrap items-center justify-between gap-3 px-4 py-3.5">
        <p className="text-sm font-medium text-fg">RFC 0042: Motion tokens</p>
        <StatusChip />
      </div>
    </div>
  )
}
```

Use it for controls that say something new once they're used: copy feedback, a follow toggle, a status chip, a save button that reports how it went. The label changes in place, so the eye stays where it was. Don't use it for content longer than a line, or for text that changes on a timer while nobody is interacting. It's for a change of state that someone caused.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { MorphLabel } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add morph-label
```

It brings `youj-core` with it.

## Usage

Key the label with `value`, and spread `useMorphRoot` on the box around it.

```tsx
import { useState } from 'react'
import { m } from 'motion/react'
import { MotionFeatures } from '@youj/core'
import { MorphLabel, useMorphRoot } from '@youj/motion'
import { CheckIcon, CopyIcon } from '@youj/icons'

export function CopyButton({ text }: { text: string }) {
  const [copied, setCopied] = useState(false)
  const morph = useMorphRoot(8) // the box's corner radius, in px

return (
    <MotionFeatures features="max">
      <m.button
        {...morph}
        type="button"
        onClick={() => {
          navigator.clipboard.writeText(text)
          setCopied(true)
        }}
        className="relative inline-flex h-8 items-center overflow-hidden rounded-md border px-3 text-sm"
      >
        <MorphLabel value={copied ? 'copied' : 'copy'} contentClassName="gap-1.5">
          {copied ? <CheckIcon trigger="mount" size={14} /> : <CopyIcon size={14} />}
          {copied ? 'Copied' : 'Copy'}
        </MorphLabel>
      </m.button>
    </MotionFeatures>
  )
}
```

- `value` keys the content. A new value crossfades to the new children. The same value re-renders in place, with no crossfade, so a count inside a label can update quietly.
- Give the box `overflow-hidden`. The outgoing label leaves the layout at once and fades where it was, so without clipping it would spill past a box that's shrinking.
- `contentClassName` styles each state's row. The default row is `inline-flex items-center gap-2 whitespace-nowrap`. Pass the gap your control uses, such as `gap-1.5`.

## Examples

### The box

`useMorphRoot(radius)` returns the props for the element that morphs: `layout`, a layout `transition` on the same spring the label uses, and an inline `borderRadius`. Spread them on an `m.button`, an `m.span` or any other Motion element, inside `<MotionFeatures features="max">` (layout animation needs the full feature set). The box's width animates as a transform while the label counter-scales, so text never squashes, and the inline radius keeps the corners round while the box scales.

With a Base UI part, render the Motion element through `render`:

```tsx
const morph = useMorphRoot(6)

<ButtonPrimitive render={<m.button {...morph} />}>
  <MorphLabel value={state}>…</MorphLabel>
</ButtonPrimitive>
```

Without a morph root, the label still crossfades and glides to its new position, but the box around it jumps to its new width.

### Async states

Key the label by the state of the work. Hold the outcome for a beat on the token grid, here `k.ms('deliberate') * 3`, so it scales with Speed. Then return to rest. Announce the outcome from a live region, because a changed label isn't read out on its own.

```tsx
'use client'

import { useEffect, useId, useState } from 'react'
import { motion } from 'motion/react'
import { useYouj } from '@youj/core'
import { MorphLabel, useMorphRoot } from '@youj/motion'
import { CheckIcon, LoaderRingIcon, SaveIcon } from '@youj/icons'

type State = 'idle' | 'saving' | 'saved'

const LABEL: Record<State, string> = { idle: 'Save changes', saving: 'Saving…', saved: 'Saved' }

// Stands in for a request to your API.
const save = () => new Promise((resolve) => setTimeout(resolve, 1400))

export default function MorphLabelAsync() {
  const k = useYouj()
  const id = useId()
  const morph = useMorphRoot(8)
  const [state, setState] = useState<State>('idle')
  const [name, setName] = useState('youj-web')

// Hold the outcome for a beat, on the token grid, then return to rest.
  useEffect(() => {
    if (state !== 'saved') return
    const t = setTimeout(() => setState('idle'), k.ms('deliberate') * 3)
    return () => clearTimeout(t)
  }, [state, k])

async function submit() {
    if (state === 'saving') return
    setState('saving')
    await save()
    setState('saved')
  }

return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        submit()
      }}
      className="w-full max-w-sm rounded-xl border border-line bg-surface p-4"
    >
      <label htmlFor={id} className="text-sm font-medium text-fg">
        Project name
      </label>
      <input
        id={id}
        value={name}
        onChange={(e) => setName(e.target.value)}
        className="mt-2 h-9 w-full rounded-md border border-line bg-canvas px-3 text-sm text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
      />
      <div className="mt-4 flex items-center justify-end gap-3">
        <motion.button
          {...morph}
          type="submit"
          aria-busy={state === 'saving' || undefined}
          className="relative inline-flex h-8 items-center overflow-hidden bg-fg px-3 text-[13px] font-medium text-canvas outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
        >
          {/* The key is the state: a new state crossfades while the box morphs to its width. */}
          <MorphLabel value={state} contentClassName="gap-1.5">
            {state === 'idle' && <SaveIcon size={14} />}
            {state === 'saving' && <LoaderRingIcon size={14} />}
            {state === 'saved' && <CheckIcon trigger="mount" size={14} strokeWidth={2} />}
            {LABEL[state]}
          </MorphLabel>
        </motion.button>
      </div>
      <span role="status" className="sr-only">
        {state === 'saved' ? 'Changes saved' : ''}
      </span>
    </form>
  )
}
```

For the full pattern, with a spinner, a drawn check, an error shake and announcements for each state, use [Async Feedback](https://www.youj.dev/docs/components/async-feedback). It's built on MorphLabel.

### Effects on the label

`ref` points at an inner span that stays the same element across values. Animate it for a shake or a nudge. It sits inside the layout projection rather than on it, so the effect doesn't fight the box's morph, and it can start on one value and finish on the next. Submit a wrong code below.

```tsx
'use client'

import { useId, useRef, useState } from 'react'
import { animate, motion } from 'motion/react'
import { useYouj } from '@youj/core'
import { MorphLabel, useMorphRoot } from '@youj/motion'
import { CheckIcon } from '@youj/icons'

type State = 'idle' | 'invalid' | 'applied'

export default function MorphLabelShake() {
  const k = useYouj()
  const id = useId()
  const morph = useMorphRoot(8)
  const label = useRef<HTMLSpanElement>(null)
  const [code, setCode] = useState('')
  const [state, setState] = useState<State>('idle')

function apply() {
    if (code.trim().toUpperCase() === 'YOUJ') return setState('applied')
    setState('invalid')
    // The ref is a stable inner span: it shakes without fighting the box's width morph.
    if (label.current && !k.reduced) animate(label.current, { x: [0, -4, 4, -3, 3, -2, 0] }, k.tween('base'))
  }

return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        apply()
      }}
      className="w-full max-w-sm rounded-xl border border-line bg-surface p-4"
    >
      <label htmlFor={id} className="text-sm font-medium text-fg">
        Promo code
      </label>
      <div className="mt-2 flex gap-2">
        <input
          id={id}
          value={code}
          placeholder="Try YOUJ"
          aria-invalid={state === 'invalid' || undefined}
          aria-describedby={`${id}-message`}
          onChange={(e) => {
            setCode(e.target.value)
            if (state !== 'idle') setState('idle')
          }}
          className="h-8 min-w-0 flex-1 rounded-md border border-line bg-canvas px-2.5 font-mono text-sm text-fg uppercase outline-none placeholder:text-fg-muted placeholder:normal-case aria-invalid:border-danger focus-visible:ring-2 focus-visible:ring-accent"
        />
        <motion.button
          {...morph}
          type="submit"
          className="relative inline-flex h-8 shrink-0 items-center overflow-hidden border border-line bg-raised px-3 text-[13px] font-medium text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
        >
          <MorphLabel ref={label} value={state} contentClassName="gap-1.5">
            {state === 'applied' && <CheckIcon trigger="mount" size={14} strokeWidth={2} className="text-success" />}
            {state === 'applied' ? 'Applied' : state === 'invalid' ? 'Try again' : 'Apply'}
          </MorphLabel>
        </motion.button>
      </div>
      {/* One live region for both outcomes, mounted from the start so its first message is heard. */}
      <p id={`${id}-message`} role="status" className={`mt-2 min-h-4 text-xs ${state === 'invalid' ? 'text-danger' : 'text-fg-muted'}`}>
        {state === 'invalid' && 'That code isn’t valid. Check it and try again.'}
        {state === 'applied' && '20% off your first year of Pro.'}
      </p>
    </form>
  )
}
```

```tsx
const label = useRef<HTMLSpanElement>(null)

if (label.current && !k.reduced) {
  animate(label.current, { x: [0, -4, 4, -3, 3, -2, 0] }, k.tween('base'))
}

<MorphLabel ref={label} value={state}>…</MorphLabel>
```

## Reference

### Props

#### MorphLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `Key` |  | Identifies the content. A new value crossfades to the new children. |
| `children` (required) | `ReactNode` |  |  |
| `className` | `string` |  | Classes for the positioned wrapper. |
| `contentClassName` | `string` |  | Classes for each state's content row. Default row: `inline-flex items-center gap-2 whitespace-nowrap`. |
| `ref` | `Ref<HTMLSpanElement>` |  | The inner span, stable across values: animate it (a shake, a nudge) without fighting the layout projection. |
| `rise` | `boolean` | `false` | How a new state arrives. `false` (default): it crossfades in place with a touch of scale and blur. `true`: it rises out of a blur while the old one lifts away, for labels that read as a step forward ("Send" → "Sent"). |
| `mode` | `'label' \| 'letters'` | `'label'` | `'label'` (default) swaps the whole content. `'letters'`, for plain-text children: letters the two labels share at the start or end (two or more) stay put and glide to their new place, and only the rest leave or arrive, one after another ("Copy" → "Copied", "Save" → "Saved"). |

#### useMorphRoot

`useMorphRoot(radius?: number | string)` returns these props. Spread all of them on the box.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` (required) | `true` |  |  |
| `transition` (required) | `{ layout: Transition }` |  |  |
| `style` | `CSSProperties` |  |  |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Crossfade | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | opacity, scale from `0.9` and a 2px blur, both ways |
| Width morph | `spring.snappy` | 0.2s, bounce 0 | the box and the label, as a transform |

**Reduced motion:** The new label replaces the old one at once, and the box takes its new width in the same frame.

Both halves share the `snappy` spring, which is why the box needs `useMorphRoot` rather than a transition of its own. On different curves, the label would drift against the edge of the box mid-morph.

#### Reduced motion

Every swap is instant. The new label and the box's new width arrive in the same frame, and any effect on the `ref` should check `k.reduced` and skip itself, as the shake above does. What the control says is unchanged.

### Accessibility

- Only the current label is in the accessibility tree. The outgoing row is `aria-hidden` while it fades, so a button's accessible name is never both labels at once.
- A changed label isn't announced on its own. When the change is news, such as "Copied" or "Saved", say it from a `role="status"` region outside the button. A button flattens its content, so a live region inside it isn't heard.
- Don't pair a changing label with `aria-pressed`. A toggle button's name should stay the same while its pressed state changes. When the label itself states the state, as Follow and Following do, leave `aria-pressed` off.
- Youj icons inside the label are decorative by default, so the text carries the meaning.

---

# Collapse

> Animate a panel’s height as it opens and closes, with support for mid-animation changes.

Source: https://www.youj.dev/docs/motion/collapse

```tsx
'use client'

import { useId, useState } from 'react'
import { Collapse } from '@youj/motion'
import { ChevronDownIcon, SlidersIcon } from '@youj/icons'

const GROUPS = [
  { legend: 'Environment', options: ['Production', 'Preview', 'Development'] },
  { legend: 'Status', options: ['Ready', 'Building', 'Error', 'Canceled'] },
]
const COMMITS = ['a41f9e2 Tighten cache headers', '9c02b1d Debounce the search query', '77e1a08 Keep the return path on sign-in']

const chip =
  'rounded-full border border-line px-2.5 py-1 text-xs text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:text-fg aria-pressed:border-accent aria-pressed:text-fg focus-visible:ring-2 focus-visible:ring-accent'

export default function CollapseDemo() {
  const id = useId()
  const [open, setOpen] = useState(false)
  const [picked, setPicked] = useState(['Production', 'Ready'])
  const toggle = (value: string) => setPicked((p) => (p.includes(value) ? p.filter((v) => v !== value) : [...p, value]))

return (
    <div className="flex min-h-[340px] w-full max-w-lg flex-col">
      <div className="w-full max-w-lg overflow-hidden rounded-xl border border-line bg-surface">
        <div className="flex items-center justify-between gap-3 px-4 py-3">
          <p className="text-sm font-medium text-fg">Deployments</p>
          {/* The trigger owns the state and points at the panel it controls. */}
          <button
            type="button"
            aria-expanded={open}
            aria-controls={id}
            onClick={() => setOpen((o) => !o)}
            className="inline-flex h-8 items-center gap-1.5 rounded-md border border-line px-2.5 text-xs font-medium text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:text-fg focus-visible:ring-2 focus-visible:ring-accent"
          >
            <SlidersIcon size={14} />
            Filters
            <span className={`inline-flex transition-transform yj-duration-base ease-standard ${open ? 'rotate-180' : ''}`}>
              <ChevronDownIcon size={14} trigger="none" />
            </span>
          </button>
        </div>

<Collapse id={id} open={open}>
          <div className="grid gap-4 border-t border-line p-4">
            {GROUPS.map(({ legend, options }) => (
              <fieldset key={legend}>
                <legend className="mb-2 text-xs font-medium text-fg-muted">{legend}</legend>
                <div className="flex flex-wrap gap-1.5">
                  {options.map((option) => (
                    <button key={option} type="button" aria-pressed={picked.includes(option)} onClick={() => toggle(option)} className={chip}>
                      {option}
                    </button>
                  ))}
                </div>
              </fieldset>
            ))}
          </div>
        </Collapse>

{/* The list below moves with the panel's height instead of jumping. */}
        <ul className="border-t border-line">
          {COMMITS.map((commit) => (
            <li key={commit} className="border-b border-line px-4 py-2.5 font-mono text-[13px] text-fg-muted last:border-b-0">
              {commit}
            </li>
          ))}
        </ul>
      </div>
    </div>
  )
}
```

Use it for disclosure you build yourself: a filter panel, "show more", an inline error, a settings section. The content below moves with the height instead of jumping. For Base UI's Collapsible and Accordion, use the [`yj-collapse`](https://www.youj.dev/docs/motion/presets) preset on the panel instead, or @youj/react's [Collapsible](https://www.youj.dev/docs/components/collapsible) and [Accordion](https://www.youj.dev/docs/components/accordion), which already do.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { Collapse } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add collapse
```

It brings `youj-core` with it.

## Usage

The trigger owns the state. Give the panel an `id`, and point the trigger's `aria-controls` and `aria-expanded` at it.

```tsx
import { useId, useState } from 'react'
import { Collapse } from '@youj/motion'

export function Filters() {
  const id = useId()
  const [open, setOpen] = useState(false)

return (
    <>
      <button type="button" aria-expanded={open} aria-controls={id} onClick={() => setOpen(!open)}>
        Filters
      </button>
      <Collapse id={id} open={open}>
        <FilterForm />
      </Collapse>
    </>
  )
}
```

Other attributes pass through to the panel, so it can carry a `role`, an `aria-labelledby` or a class.

## Examples

### Interrupting

The height eases to and from the content's own height, so there's nothing to measure or hard-code. Press Filters twice in quick succession: a reversal starts from the current height and heads back on the same curve, with no jump. Content added while the panel is open grows it normally, because at rest the height is `auto`.

The panel clips only while it moves or while it's closed. At rest nothing is clipped, so focus rings and popovers inside it aren't cut off.

### One at a time

Drive several panels from one piece of state for an accordion. One panel closes while the next opens, on the same duration and curve.

```tsx
'use client'

import { useId, useState } from 'react'
import { Collapse } from '@youj/motion'
import { ChevronDownIcon } from '@youj/icons'

const FAQ = [
  { q: 'What counts as a seat?', a: 'Anyone who can sign in to the team. Guests with view-only links are free.' },
  {
    q: 'Can I change plans mid-cycle?',
    a: 'Yes. Upgrades are prorated to the day and apply at once. Downgrades take effect at the end of the billing period, so nobody loses access they paid for.',
  },
  { q: 'Do previews count toward usage?', a: 'Preview builds share your plan’s build minutes. Bandwidth for previews is free.' },
]

export default function CollapseFaq() {
  const id = useId()
  const [open, setOpen] = useState<number | null>(1)

return (
    <div className="flex min-h-[250px] w-full max-w-lg flex-col">
      <div className="w-full max-w-lg divide-y divide-line rounded-xl border border-line bg-surface">
        {FAQ.map(({ q, a }, i) => (
          <div key={q}>
            <button
              type="button"
              id={`${id}-q${i}`}
              aria-expanded={open === i}
              aria-controls={`${id}-a${i}`}
              onClick={() => setOpen(open === i ? null : i)}
              className="flex w-full items-center justify-between gap-4 rounded-xl px-4 py-3 text-start text-sm font-medium text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-inset"
            >
              {q}
              <span className={`inline-flex shrink-0 text-fg-muted transition-transform yj-duration-base ease-standard ${open === i ? 'rotate-180' : ''}`}>
                <ChevronDownIcon size={16} trigger="none" />
              </span>
            </button>
            {/* One panel closes while the next opens, on the same curve, so the two moves read as one. */}
            <Collapse id={`${id}-a${i}`} role="region" aria-labelledby={`${id}-q${i}`} open={open === i}>
              <p className="px-4 pb-4 text-sm leading-6 text-fg-muted">{a}</p>
            </Collapse>
          </div>
        ))}
      </div>
    </div>
  )
}
```

### Keeping state

By default the content unmounts once it has collapsed. With `keepMounted`, it stays in the DOM while closed, hidden and inert, so a half-filled form or a scroll position survives. `duration` sets the height's duration token, `base` by default. This section uses `slow` for a taller panel.

```tsx
'use client'

import { useId, useState } from 'react'
import { Collapse } from '@youj/motion'
import { ChevronRightIcon } from '@youj/icons'

const field =
  'mt-1.5 h-8 w-full rounded-md border border-line bg-canvas px-2.5 font-mono text-[13px] text-fg outline-none placeholder:text-fg-muted focus-visible:ring-2 focus-visible:ring-accent'

export default function CollapseKeepMounted() {
  const id = useId()
  const [open, setOpen] = useState(true)

return (
    <div className="flex min-h-[310px] w-full max-w-sm flex-col">
      <form onSubmit={(e) => e.preventDefault()} className="w-full max-w-sm rounded-xl border border-line bg-surface p-4">
        <label className="block text-sm font-medium text-fg">
          Repository
          <input defaultValue="acme/web" className={field} />
        </label>

<button
          type="button"
          aria-expanded={open}
          aria-controls={id}
          onClick={() => setOpen((o) => !o)}
          className="mt-4 -ms-1 inline-flex items-center gap-1 rounded-md px-1 py-0.5 text-sm text-fg-muted outline-none hover:text-fg focus-visible:ring-2 focus-visible:ring-accent"
        >
          <span className={`inline-flex transition-transform yj-duration-base ease-standard ${open ? 'rotate-90' : ''}`}>
            <ChevronRightIcon size={14} trigger="none" />
          </span>
          Build settings
        </button>

{/* keepMounted: closed, the fields stay in the DOM (hidden and inert), so what was typed survives. */}
        <Collapse id={id} open={open} keepMounted duration="slow">
          <div className="grid gap-3 pt-3">
            <label className="block text-xs font-medium text-fg-muted">
              Build command
              <input placeholder="pnpm build" className={field} />
            </label>
            <label className="block text-xs font-medium text-fg-muted">
              Output directory
              <input placeholder=".next" className={field} />
            </label>
          </div>
        </Collapse>

<p className="mt-4 text-xs text-fg-muted">Type a build command, close the section and open it again.</p>
      </form>
    </div>
  )
}
```

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  | Whether the content is shown. |
| `keepMounted` | `boolean` | `false` | Keep the content mounted while closed (hidden and inert), e.g. to preserve its state. |
| `duration` | `'instant' \| 'fast' \| 'base' \| 'slow' \| 'deliberate'` | `'base'` | How long the height takes. |
| `children` (required) | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | to and from `auto`, both ways, default `duration` |
| Fade in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | the content, alongside the height |
| Fade out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | faster than the collapse, so text never looks squashed |

**Reduced motion:** The panel opens and closes in one frame. The content below moves at once, and closed content is hidden and inert as usual.

Height is a layout animation, and here that's the point: the content below has to move. Keep panels to the size of a section. For whole pages, use a route transition.

#### Reduced motion

The panel shows and hides at once, with no height animation and no fade. What's shown and what's reachable are exactly the same as with motion.

### Accessibility

- Collapse adds no roles or state of its own. The trigger carries `aria-expanded` and `aria-controls`, as in the examples. Add `role="region"` and `aria-labelledby` when a panel is a landmark worth jumping to.
- Closed content is `inert` from the first frame of the close, so it can't take focus or clicks while it collapses. It then unmounts or, with `keepMounted`, is hidden from assistive technology.
- Keep the trigger in place while the panel moves. It sits outside the panel, so it never shifts under the pointer.

---

# Content Swap

> Replace a loading placeholder with content and smoothly adjust the container’s height.

Source: https://www.youj.dev/docs/motion/content-swap

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ContentSwap } from '@youj/motion'
import { RefreshIcon } from '@youj/icons'
import { Skeleton } from '@youj/react'

const INVOICES = [
  { client: 'Acme Corp', detail: 'INV-2041 · Due Oct 12', amount: '$4,200.00', initials: 'AC' },
  { client: 'Globex', detail: 'INV-2040 · Paid Sep 28', amount: '$1,180.00', initials: 'GL' },
  { client: 'Initech', detail: 'INV-2039 · Paid Sep 21', amount: '$860.00', initials: 'IN' },
  { client: 'Umbrella', detail: 'INV-2038 · Overdue 4 days', amount: '$2,975.50', initials: 'UM' },
]

// Shaped like the rows it stands in for, so the swap reads as the same list resolving.
function InvoicesSkeleton() {
  return (
    <div className="flex flex-col gap-3.5 p-4">
      {[0, 1, 2].map((i) => (
        <div key={i} className="flex items-center gap-3">
          <Skeleton className="size-8 rounded-full" />
          <div className="flex flex-1 flex-col gap-1.5">
            <Skeleton className="h-3 w-2/5" />
            <Skeleton className="h-3 w-1/4" />
          </div>
          <Skeleton className="h-3 w-14" />
        </div>
      ))}
    </div>
  )
}

export default function ContentSwapDemo() {
  const [loading, setLoading] = useState(true)
  const [run, setRun] = useState(0)

// Stands in for a fetch: every run shows the skeleton, then the data.
  useEffect(() => {
    setLoading(true)
    const t = setTimeout(() => setLoading(false), 1200)
    return () => clearTimeout(t)
  }, [run])

return (
    <div className="flex min-h-[250px] w-full max-w-md flex-col">
      <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
        <div className="flex items-center justify-between gap-3 border-b border-line px-4 py-2.5">
          <p className="text-sm font-medium text-fg">Recent invoices</p>
          <button
            type="button"
            onClick={() => setRun((r) => r + 1)}
            className="inline-flex h-7 items-center gap-1.5 rounded-md px-2 text-xs font-medium text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent"
          >
            <RefreshIcon size={13} />
            Refetch
          </button>
        </div>
        <ContentSwap loading={loading} fallback={<InvoicesSkeleton />} loadingLabel="Loading invoices">
          <ul className="flex flex-col gap-3.5 p-4">
            {INVOICES.map(({ client, detail, amount, initials }) => (
              <li key={client} className="flex items-center gap-3">
                <span className="grid size-8 place-items-center rounded-full bg-raised text-[11px] font-medium text-fg-muted">{initials}</span>
                <div className="min-w-0 flex-1">
                  <p className="text-sm text-fg">{client}</p>
                  <p className="text-xs text-fg-muted">{detail}</p>
                </div>
                <span className="font-mono text-sm text-fg tabular-nums">{amount}</span>
              </li>
            ))}
          </ul>
        </ContentSwap>
      </div>
    </div>
  )
}
```

Use it wherever a region loads in place: a card of invoices, a profile, a chart panel, a filtered list. The skeleton drops away as the content resolves into focus, and the box morphs from one height to the other, so the page below moves instead of jumping. Don't use it for content that arrives in pieces, like rows that stream in one by one. Use [Presence List](https://www.youj.dev/docs/motion/presence-list) for those.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { ContentSwap } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add content-swap
```

It brings `youj-core` with it.

## Usage

```tsx
import { ContentSwap } from '@youj/motion'
import { Card } from '@youj/react'

export function Invoices({ invoices, isLoading }: { invoices: Invoice[]; isLoading: boolean }) {
  return (
    <Card>
      <ContentSwap loading={isLoading} fallback={<InvoicesSkeleton />} loadingLabel="Loading invoices">
        <InvoiceList invoices={invoices} />
      </ContentSwap>
    </Card>
  )
}
```

`loading` decides which side shows. `fallback` stands in while it's true, and `children` is the content. `loadingLabel` adds a polite announcement while loading, off by default.

## Examples

### Shape the skeleton like the content

The swap reads as one list resolving when the fallback has the content's shape: the same rows, avatars and column widths. When the content has more rows than the skeleton, as in the preview, the box grows the difference as the rows resolve in. Any skeleton works. The one in these examples is @youj/react's [Skeleton](https://www.youj.dev/docs/components/skeleton), which times its shimmer on the provider's Speed and stops it under reduced motion.

### Refetching

It works in both directions. Set `loading` back to `true` and the skeleton returns, and a swap that starts mid-morph continues from the current height. Change the filter below a few times in a row.

```tsx
'use client'

import { useEffect, useState } from 'react'
import { ContentSwap } from '@youj/motion'
import { Skeleton } from '@youj/react'

type Filter = 'All' | 'Paid' | 'Overdue'

const INVOICES = [
  { id: 'INV-2041', client: 'Acme Corp', amount: '$4,200.00', status: 'Open' },
  { id: 'INV-2040', client: 'Globex', amount: '$1,180.00', status: 'Paid' },
  { id: 'INV-2039', client: 'Initech', amount: '$860.00', status: 'Paid' },
  { id: 'INV-2038', client: 'Umbrella', amount: '$2,975.50', status: 'Overdue' },
  { id: 'INV-2037', client: 'Soylent', amount: '$640.00', status: 'Paid' },
]

export default function ContentSwapFilters() {
  const [filter, setFilter] = useState<Filter>('All')
  const [loading, setLoading] = useState(false)
  const rows = INVOICES.filter((i) => filter === 'All' || i.status === filter)

// Each filter refetches: the skeleton comes back, then the new rows resolve in.
  useEffect(() => {
    if (!loading) return
    const t = setTimeout(() => setLoading(false), 900)
    return () => clearTimeout(t)
  }, [loading])

return (
    <div className="flex min-h-[260px] w-full max-w-md flex-col">
      <div className="w-full max-w-md overflow-hidden rounded-xl border border-line bg-surface">
        <div role="group" aria-label="Filter invoices" className="flex gap-1 border-b border-line p-2">
          {(['All', 'Paid', 'Overdue'] as const).map((option) => (
            <button
              key={option}
              type="button"
              aria-pressed={filter === option}
              onClick={() => {
                if (option === filter) return
                setFilter(option)
                setLoading(true)
              }}
              className="h-7 rounded-md px-2.5 text-xs font-medium text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:text-fg focus-visible:ring-2 focus-visible:ring-accent aria-pressed:bg-raised aria-pressed:text-fg"
            >
              {option}
            </button>
          ))}
        </div>
        {/* The box morphs between the skeleton's height and each result's, so the page below moves with it. */}
        <ContentSwap loading={loading} loadingLabel={`Loading ${filter.toLowerCase()} invoices`} fallback={<RowsSkeleton />}>
          <ul className="divide-y divide-line">
            {rows.map(({ id, client, amount, status }) => (
              <li key={id} className="flex items-center gap-3 px-4 py-2.5 text-sm">
                <span className="w-20 font-mono text-xs text-fg-muted">{id}</span>
                <span className="min-w-0 flex-1 truncate text-fg">{client}</span>
                <span className={`text-xs ${status === 'Overdue' ? 'text-danger' : 'text-fg-muted'}`}>{status}</span>
                <span className="w-20 text-end font-mono text-fg tabular-nums">{amount}</span>
              </li>
            ))}
          </ul>
        </ContentSwap>
      </div>
    </div>
  )
}

function RowsSkeleton() {
  return (
    <div className="divide-y divide-line">
      {[0, 1, 2].map((i) => (
        <div key={i} className="flex items-center gap-3 px-4 py-3.5">
          <Skeleton className="h-3 w-20" />
          <Skeleton className="h-3 flex-1" />
          <Skeleton className="h-3 w-20" />
        </div>
      ))}
    </div>
  )
}
```

Every filter here refetches, so each result replaces the skeleton with a different height: five rows, three, then one. The rows below the card would follow the same curve.

### Failed loads

The content side is whatever the request settled on, so an error swaps in just as data does: here the first request fails, and Try again brings the skeleton back before the domains resolve.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { ContentSwap } from '@youj/motion'
import { AlertTriangleIcon, GlobeIcon, RefreshIcon } from '@youj/icons'
import { Skeleton } from '@youj/react'

const DOMAINS = [
  { name: 'northwind.dev', detail: 'Production', valid: true },
  { name: 'www.northwind.dev', detail: 'Redirects to northwind.dev', valid: true },
  { name: 'docs.northwind.dev', detail: 'Production', valid: true },
  { name: 'beta.northwind.dev', detail: 'Preview · main', valid: false },
]

function DomainsSkeleton() {
  return (
    <div className="divide-y divide-line">
      {[0, 1, 2].map((i) => (
        <div key={i} className="flex items-center gap-3 px-4 py-3">
          <Skeleton className="size-7 rounded-md" />
          <div className="flex flex-1 flex-col gap-1.5">
            <Skeleton className="h-3 w-2/5" />
            <Skeleton className="h-3 w-1/4" />
          </div>
          <Skeleton className="h-3 w-12" />
        </div>
      ))}
    </div>
  )
}

export default function ContentSwapFailedLoad() {
  const [attempt, setAttempt] = useState(0)
  const [status, setStatus] = useState<'loading' | 'failed' | 'ready'>('loading')
  const region = useRef<HTMLDivElement>(null)

// Stands in for a fetch: the first request times out, and the retry succeeds.
  useEffect(() => {
    setStatus('loading')
    const t = setTimeout(() => setStatus(attempt === 0 ? 'failed' : 'ready'), 1200)
    return () => clearTimeout(t)
  }, [attempt])

const retry = () => {
    // The button leaves with the error, so focus moves to the region instead of falling back to the page.
    region.current?.focus()
    setAttempt((a) => a + 1)
  }

return (
    <div className="flex min-h-[270px] w-full max-w-md flex-col">
      <div className="overflow-hidden rounded-xl border border-line bg-surface">
        <p className="border-b border-line px-4 py-2.5 text-sm font-medium text-fg">Domains</p>
        <div ref={region} tabIndex={-1} className="outline-none">
          <ContentSwap loading={status === 'loading'} fallback={<DomainsSkeleton />} loadingLabel="Loading domains">
            {status === 'failed' ? (
              <div className="flex flex-col items-center px-6 py-6 text-center">
                <span className="grid size-8 place-items-center rounded-full bg-danger-subtle text-danger">
                  <AlertTriangleIcon size={16} />
                </span>
                <div role="alert" className="mt-3">
                  <p className="text-sm font-medium text-fg">Couldn’t load domains</p>
                  <p className="mt-0.5 text-xs text-fg-muted">The request timed out after 10 seconds.</p>
                </div>
                <button
                  type="button"
                  onClick={retry}
                  className="mt-4 inline-flex h-7 items-center gap-1.5 rounded-md border border-line px-2.5 text-xs font-medium text-fg outline-none transition-colors yj-duration-fast ease-standard hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent"
                >
                  <RefreshIcon size={13} />
                  Try again
                </button>
              </div>
            ) : (
              <ul className="divide-y divide-line">
                {DOMAINS.map(({ name, detail, valid }) => (
                  <li key={name} className="flex items-center gap-3 px-4 py-2.5">
                    <span className="grid size-7 place-items-center rounded-md border border-line bg-raised text-fg-muted">
                      <GlobeIcon size={14} />
                    </span>
                    <div className="min-w-0 flex-1">
                      <p className="truncate text-sm text-fg">{name}</p>
                      <p className="truncate text-xs text-fg-muted">{detail}</p>
                    </div>
                    <span className="inline-flex shrink-0 items-center gap-1.5 text-xs text-fg-muted">
                      <span className={`size-1.5 rounded-full ${valid ? 'bg-success' : 'bg-warning'}`} />
                      {valid ? 'Valid' : 'Pending DNS'}
                    </span>
                  </li>
                ))}
              </ul>
            )}
          </ContentSwap>
        </div>
      </div>
    </div>
  )
}
```

Give the message `role="alert"` so it's announced as it appears. The retry button leaves with the error, and the outgoing side is inert, so move focus into the region before you refetch.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` (required) | `boolean` |  | Show the fallback instead of the content. |
| `fallback` (required) | `ReactNode` |  | Stands in while loading: usually a skeleton shaped like the content. Hidden from assistive tech. |
| `loadingLabel` | `string` |  | Announced politely while loading, e.g. "Loading invoices". Off by default. |
| `children` (required) | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Skeleton out | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | fades where it stands, out of the layout |
| Content in | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fade, 4px rise and a 4px blur, one step late |
| Delay | `stagger.base` | 40ms step | before the incoming side starts |
| Height | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | from the old height to the new one |

**Reduced motion:** The content replaces the skeleton in one frame, and the box takes its new height at once.

The incoming side waits one stagger step, so the two layers barely double-expose. The content ends on `filter: none`, not `blur(0px)`: a leftover filter would make it the containing block for any fixed-position element inside.

#### Reduced motion

The swap is instant in both directions and the height changes in the same frame. The busy state and the announcement are unchanged. Stop your skeleton's own shimmer or pulse too. @youj/react's Skeleton does this for you.

### Accessibility

- While loading, the region is `aria-busy`, and the skeleton is `aria-hidden`, so assistive technology waits for the content instead of reading placeholder shapes.
- `loadingLabel` renders a visually hidden `role="status"` that's mounted from the start and announces the label while loading. Give it the name of what's loading, like "Loading invoices".
- The outgoing side is inert while it fades, so it can't take focus or clicks on its way out.

---

# Presence List

> Animate items as they enter, leave or reorder in lists and tables.

Source: https://www.youj.dev/docs/motion/presence-list

```tsx
'use client'

import { useId, useState } from 'react'
import { PresenceItem, PresenceList } from '@youj/motion'
import { PinIcon, PlusIcon, TrashIcon } from '@youj/icons'

interface Note {
  id: number
  title: string
  body: string
  pinned: boolean
}

const SEED: Note[] = [
  { id: 1, title: 'Build failed on chore/deps', body: 'Type error in the motion typings.', pinned: false },
  { id: 2, title: 'Priya requested your review', body: 'feat/search: Debounce the query', pinned: false },
  { id: 3, title: 'Domain verified', body: 'acme.dev now serves production.', pinned: false },
]
const INCOMING = [
  { title: 'Usage at 80%', body: 'Image optimizations this month.' },
  { title: 'Kenji commented on #482', body: '“Ship it once the preview is green.”' },
  { title: 'Deploy promoted', body: 'a41f9e2 is live on production.' },
]

const iconButton =
  'grid size-7 shrink-0 place-items-center rounded-md text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent aria-pressed:text-accent'

export default function PresenceListDemo() {
  const addId = useId()
  const [notes, setNotes] = useState(SEED)
  const [next, setNext] = useState(0)
  // Pinned notes sort first, so a pin is a reorder: the row glides over the others (z-1) to its new slot.
  const ordered = [...notes].sort((a, b) => Number(b.pinned) - Number(a.pinned))

// A dismissed row turns inert at once, which would drop focus on the page body.
  // Hand focus to a neighbor's button first, so keyboard users keep their place.
  function dismiss(id: number, button: HTMLElement) {
    const list = button.closest('ul')
    const buttons = [...(list?.querySelectorAll<HTMLElement>('li:not([inert]) [data-action="dismiss"]') ?? [])]
    const i = buttons.indexOf(button)
    ;(buttons[i + 1] ?? buttons[i - 1] ?? document.getElementById(addId))?.focus()
    setNotes((all) => all.filter((n) => n.id !== id))
  }

function add() {
    const incoming = INCOMING[next % INCOMING.length]!
    setNotes((all) => [{ id: 100 + next, pinned: false, ...incoming }, ...all])
    setNext((n) => n + 1)
  }

return (
    <div className="flex min-h-[340px] w-full max-w-md flex-col">
      <div className="w-full max-w-md rounded-xl border border-line bg-surface p-2">
        <div className="flex items-center justify-between px-2 pb-2">
          <p className="text-xs font-medium text-fg-muted">Notifications</p>
          <button
            id={addId}
            type="button"
            onClick={add}
            className="inline-flex h-7 items-center gap-1 rounded-md px-2 text-xs font-medium text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:bg-raised hover:text-fg focus-visible:ring-2 focus-visible:ring-accent"
          >
            <PlusIcon size={13} />
            Simulate one
          </button>
        </div>
        <PresenceList className="flex flex-col gap-1">
          {ordered.map((note) => (
            <PresenceItem key={note.id} className={`flex items-center gap-2 rounded-lg bg-surface px-3 py-2.5 hover:bg-raised ${note.pinned ? 'z-1' : ''}`}>
              <div className="min-w-0 flex-1">
                <p className="truncate text-sm text-fg">{note.title}</p>
                <p className="truncate text-xs text-fg-muted">{note.body}</p>
              </div>
              <button
                type="button"
                aria-label={`Pin ${note.title}`}
                aria-pressed={note.pinned}
                onClick={() => setNotes((all) => all.map((n) => (n.id === note.id ? { ...n, pinned: !n.pinned } : n)))}
                className={iconButton}
              >
                <PinIcon size={14} />
              </button>
              <button
                type="button"
                data-action="dismiss"
                aria-label={`Dismiss ${note.title}`}
                onClick={(e) => dismiss(note.id, e.currentTarget)}
                className={iconButton}
              >
                <TrashIcon size={14} />
              </button>
            </PresenceItem>
          ))}
        </PresenceList>
        {notes.length === 0 && <p className="px-3 py-6 text-center text-sm text-fg-muted">You’re all caught up.</p>}
      </div>
    </div>
  )
}
```

Use it for lists that change while people watch: notifications, a queue, a filtered list, a table whose rows are added, removed or re-sorted. Each change happens where the eye can follow it. Don't use it when the whole list is replaced at once, like the next page of results. Key the list by page instead, or use [Content Swap](https://www.youj.dev/docs/motion/content-swap).

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { PresenceItem, PresenceList } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add presence-list
```

It brings `youj-core`, `settled-entrances` with it.

## Usage

```tsx
import { PresenceItem, PresenceList } from '@youj/motion'

export function Notifications({ items }: { items: Notification[] }) {
  return (
    <PresenceList className="flex flex-col gap-1">
      {items.map((item) => (
        <PresenceItem key={item.id} className="rounded-lg bg-surface px-3 py-2">
          {item.title}
        </PresenceItem>
      ))}
    </PresenceList>
  )
}
```

- Every `PresenceItem` is a direct, keyed child of its `PresenceList`. The key is how a row is recognized as the same row after a change, so use a stable id, never the index.
- `as` picks the elements: `ul` (the default), `ol`, `tbody` or `div` for the list, and `li` (the default), `tr`, `div`, `article` or `section` for items.
- Items on the first render start settled. Pass `initial` to animate them in as well.

## Examples

### Enter, leave, reorder

- **Enter:** the item takes its slot and fades down a few pixels, while the items below glide to make room.
- **Leave:** the item fades where it stands and keeps its space, so column widths hold, then it's removed and the items below glide up.
- **Reorder:** items glide to their new slots.

Movement is a translate-only FLIP, with no scale, so text, borders and cells never distort. Items are measured against the list, so when the list itself moves, because a toolbar appears above it or a card re-centers, the items don't glide for nothing. Each list is its own layout group, so two lists never fight, and memoized rows still animate.

### Reordering

Sort on every render. When a change moves an item, it glides to its new slot, and the items it passes glide the other way. Vote a few times.

```tsx
'use client'

import { useState } from 'react'
import { PresenceItem, PresenceList } from '@youj/motion'
import { ArrowUpIcon } from '@youj/icons'

const REQUESTS = [
  { id: 'dark-mode-charts', title: 'Dark mode for embedded charts', votes: 48 },
  { id: 'saml', title: 'SAML single sign-on', votes: 44 },
  { id: 'csv', title: 'Export any table as CSV', votes: 41 },
  { id: 'webhooks', title: 'Retry failed webhooks', votes: 37 },
  { id: 'regions', title: 'Pick a region per project', votes: 35 },
]

export default function PresenceListReorder() {
  const [votes, setVotes] = useState(() => Object.fromEntries(REQUESTS.map((r) => [r.id, r.votes])))
  const [last, setLast] = useState<string>()
  // Sorted on every render: when a vote changes the order, the rows glide to their new slots.
  const ranked = [...REQUESTS].sort((a, b) => votes[b.id]! - votes[a.id]!)

return (
    <div className="w-full max-w-md rounded-xl border border-line bg-surface p-2">
      <p className="px-2 pb-2 text-xs font-medium text-fg-muted">Feature requests · most wanted first</p>
      <PresenceList as="ol" className="flex flex-col gap-1">
        {ranked.map((request, i) => (
          // The row you voted for rides above the others as it climbs.
          <PresenceItem key={request.id} className={`flex items-center gap-3 rounded-lg bg-surface px-2 py-1.5 ${last === request.id ? 'z-1' : ''}`}>
            <span aria-hidden className="w-4 text-end font-mono text-xs text-fg-muted tabular-nums">{i + 1}</span>
            <span className="min-w-0 flex-1 truncate text-sm text-fg">{request.title}</span>
            <button
              type="button"
              aria-label={`Upvote ${request.title}, ${votes[request.id]} votes`}
              onClick={() => {
                setLast(request.id)
                setVotes((v) => ({ ...v, [request.id]: v[request.id]! + 5 }))
              }}
              className="inline-flex h-8 min-w-14 items-center justify-center gap-1 rounded-md border border-line font-mono text-xs text-fg tabular-nums outline-none transition-colors yj-duration-fast ease-standard hover:border-line-strong hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent"
            >
              <ArrowUpIcon size={13} />
              {votes[request.id]}
            </button>
          </PresenceItem>
        ))}
      </PresenceList>
    </div>
  )
}
```

### Table rows

Table rows rule out the usual tricks: an absolutely positioned `<tr>` loses table layout, and a row can't be clipped or collapsed by height. Presence List avoids both, and a table needs four rules of its own:

1. **`border-separate border-spacing-0`, with dividers on the cells.** `border-collapse`, Tailwind's default for tables, paints borders on the table grid, so they'd stay behind while rows move. A `border-b` on the row does nothing in separate mode.
2. **A background on every row**, such as `bg-surface`, so rows that cross during a re-sort cover each other cleanly.
3. **Fixed column widths**, with `table-fixed` or column sizing, so removing the widest row doesn't reflow every column mid-animation.
4. **A keyed `tbody` for whole-page swaps.** Key it by page for pagination, so a page change isn't twenty exits and twenty enters.

```tsx
'use client'

import { memo, useState } from 'react'
import { PresenceItem, PresenceList } from '@youj/motion'
import { ArrowUpDownIcon, PlusIcon, TrashIcon } from '@youj/icons'

interface Deploy {
  id: number
  branch: string
  commit: string
  age: number
  status: 'Ready' | 'Building' | 'Error'
}

const SEED: Deploy[] = [
  { id: 1, branch: 'main', commit: 'Tighten cache headers', age: 4, status: 'Ready' },
  { id: 2, branch: 'feat/search', commit: 'Debounce the query', age: 12, status: 'Building' },
  { id: 3, branch: 'fix/auth-redirect', commit: 'Keep the return path', age: 31, status: 'Ready' },
  { id: 4, branch: 'chore/deps', commit: 'Bump motion to 13', age: 58, status: 'Error' },
]
const INCOMING = ['feat/onboarding', 'fix/tooltips', 'perf/images']
const DOT = { Ready: 'bg-success', Building: 'bg-warning', Error: 'bg-danger' }
const button =
  'inline-flex h-7 items-center gap-1.5 rounded-md border border-line px-2 text-xs font-medium text-fg-muted outline-none transition-colors yj-duration-fast ease-standard hover:text-fg focus-visible:ring-2 focus-visible:ring-accent disabled:opacity-50'
// Dividers live on the cells: with border-collapse the table grid paints them, and they'd stay behind while rows move.
const cell = 'border-b border-line px-3 py-2 [tr:last-child>&]:border-b-0'

// Memoized on purpose: rows still glide, because PresenceItem re-measures whenever the list renders.
const Row = memo(function Row({ deploy, onRemove }: { deploy: Deploy; onRemove: (id: number) => void }) {
  return (
    <PresenceItem as="tr" className="bg-surface">
      <td className={`${cell} ps-4`}>
        <span className="inline-flex items-center gap-2 font-mono text-[13px] text-fg">
          <span aria-hidden className={`size-1.5 rounded-full ${DOT[deploy.status]}`} />
          {deploy.branch}
        </span>
        <span className="sr-only">, {deploy.status}</span>
      </td>
      <td className={`${cell} truncate text-fg-muted`}>{deploy.commit}</td>
      <td className={`${cell} text-end font-mono text-xs text-fg-muted tabular-nums`}>{deploy.age}m</td>
      <td className={`${cell} pe-2 text-end`}>
        <button type="button" aria-label={`Remove ${deploy.branch}`} onClick={() => onRemove(deploy.id)} className={`${button} w-7 justify-center border-transparent px-0`}>
          <TrashIcon size={13} />
        </button>
      </td>
    </PresenceItem>
  )
})

export default function PresenceListTable() {
  const [rows, setRows] = useState(SEED)
  const [byBranch, setByBranch] = useState(false)
  const [next, setNext] = useState(0)
  const sorted = [...rows].sort((a, b) => (byBranch ? a.branch.localeCompare(b.branch) : a.age - b.age))
  const remove = (id: number) => setRows((r) => r.filter((d) => d.id !== id))

return (
    <div className="flex min-h-[300px] w-full max-w-2xl flex-col">
      <div className="w-full max-w-2xl overflow-hidden rounded-xl border border-line bg-surface">
        <div className="flex items-center justify-between gap-2 border-b border-line px-4 py-2.5">
          <p className="text-sm font-medium text-fg">Deployments</p>
          <div className="flex gap-1.5">
            <button type="button" className={button} onClick={() => setByBranch((b) => !b)}>
              <ArrowUpDownIcon size={13} />
              Sort by {byBranch ? 'age' : 'branch'}
            </button>
            <button
              type="button"
              className={button}
              disabled={next >= INCOMING.length}
              onClick={() => {
                setRows((r) => [{ id: 100 + next, branch: INCOMING[next]!, commit: 'Preview build', age: 0, status: 'Building' }, ...r])
                setNext((n) => n + 1)
              }}
            >
              <PlusIcon size={13} />
              Deploy
            </button>
          </div>
        </div>
        <div className="overflow-x-auto">
          {/* border-separate + fixed columns: rows can move without dragging borders or reflowing widths. */}
          <table className="w-full min-w-[480px] table-fixed border-separate border-spacing-0 text-sm">
            <thead>
              <tr className="text-start text-xs text-fg-muted [&>th]:border-b [&>th]:border-line [&>th]:px-3 [&>th]:py-2 [&>th]:font-medium">
                <th className="w-[38%] ps-4 text-start">Branch</th>
                <th className="text-start">Commit</th>
                <th className="w-16 text-end">Age</th>
                <th className="w-12">
                  <span className="sr-only">Actions</span>
                </th>
              </tr>
            </thead>
            <PresenceList as="tbody">
              {sorted.map((d) => (
                <Row key={d.id} deploy={d} onRemove={remove} />
              ))}
            </PresenceList>
          </table>
        </div>
      </div>
    </div>
  )
}
```

```tsx
<table className="w-full table-fixed border-separate border-spacing-0">
  <thead>…</thead>
  <PresenceList as="tbody">
    {rows.map((row) => (
      <PresenceItem as="tr" key={row.id} className="bg-surface">
        <td className="border-b border-line [tr:last-child>&]:border-b-0">…</td>
      </PresenceItem>
    ))}
  </PresenceList>
</table>
```

Don't use it with a virtualizer such as TanStack Virtual, which positions rows itself.

## Reference

### Props

#### PresenceList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `'div' \| 'ol' \| 'tbody' \| 'ul'` | `'ul'` | The list element. |
| `initial` | `boolean` | `false` | Also animate the items present on first render. |
| `children` (required) | `ReactNode` |  | PresenceItems, keyed by a stable id. |

Also takes the props of `HTMLAttributes<HTMLElement>`.

#### PresenceItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `'div' \| 'section' \| 'article' \| 'li' \| 'tr'` | `'li'` | The element to render. |
| `children` | `ReactNode` |  |  |

Also takes the props of `HTMLAttributes<HTMLElement>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | fade and a 6px drop into the slot |
| Leave | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | fade in place, keeping the space |
| Move | `spring.smooth` | 0.36s, bounce 0 | making room, closing gaps, reordering |

**Reduced motion:** Items are added, removed and reordered in one frame, with no layout animation at all.

#### Reduced motion

Every change applies at once: new items appear in their slot, removed ones are gone, and reordered ones are in their new place. The list is the same as with motion. It just doesn't travel.

### Accessibility

- The list keeps its semantics: a `ul` or `ol` of `li`, or a real `tbody` of `tr`. Screen readers announce the list and its length, and a table stays navigable by row and column.
- A leaving item is `inert` from its first frame, so it can't take focus or clicks while it fades.
- Removing the focused item would drop focus on the page body. When an item is removed with a button inside it, move focus first, to a neighbor's matching button or to the list's own controls. The notifications example does this.
- The list doesn't announce changes. When a change is news, like a notification arriving, announce it from a live region.

---

# Page Transition

> Animate changes between routes or views and carry shared elements between them.

Source: https://www.youj.dev/docs/motion/page-transition

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { cn } from '@youj/core'
import { ArrowLeftIcon, ChevronRightIcon, GitCommitIcon } from '@youj/icons'
import { PageTransition, SharedElement, type PageDirection } from '@youj/motion/interactions'

const DEPLOYS = [
  { id: 'a41f9e2', message: 'Tighten cache headers', author: 'Priya Raman', when: '9:41', status: 'Ready', dot: 'bg-success', time: '38s' },
  { id: '7c02b1d', message: 'New pricing page', author: 'Jonas Weber', when: '9:12', status: 'Ready', dot: 'bg-success', time: '41s' },
  { id: 'e9d4a70', message: 'Bump the build image', author: 'Ana Lima', when: 'Tue', status: 'Failed', dot: 'bg-danger', time: '12s' },
  { id: '3b8f0c4', message: 'Edge config for the EU region', author: 'Kenji Sato', when: 'Mon', status: 'Ready', dot: 'bg-success', time: '36s' },
]

export default function PageTransitionDemo() {
  // A tiny router: the path is the routeKey, and the direction comes from the last move.
  const [path, setPath] = useState('/deployments')
  const [direction, setDirection] = useState<PageDirection>('forward')
  const open = DEPLOYS.find((d) => path === `/deployments/${d.id}`)
  const go = (next: string, dir: PageDirection) => {
    setDirection(dir)
    setPath(next)
  }

// Like a router would: after each navigation, focus lands on the new page, not on <body>.
  const shell = useRef<HTMLDivElement>(null)
  const last = useRef<string | null>(null)
  useEffect(() => {
    if (last.current === null) {
      last.current = path
      return
    }
    const target = open ? '[data-back]' : `[data-deploy="${last.current.split('/')[2]}"]`
    shell.current?.querySelector<HTMLElement>(target)?.focus()
    last.current = path
  }, [path, open])

return (
    <div ref={shell} className="w-full max-w-sm overflow-hidden rounded-2xl border border-line bg-surface">
      <div className="flex h-11 items-center gap-2 border-b border-line px-3">
        <button
          type="button"
          aria-label="Back"
          data-back=""
          disabled={!open}
          onClick={() => go('/deployments', 'back')}
          className="grid size-7 place-items-center rounded-md text-fg-muted outline-none enabled:hover:bg-raised enabled:hover:text-fg disabled:opacity-40 focus-visible:ring-2 focus-visible:ring-accent"
        >
          <ArrowLeftIcon size={15} />
        </button>
        <span className="font-mono text-xs text-fg-muted">{path}</span>
      </div>
      <PageTransition routeKey={path} direction={direction} className="h-68">
        {open ? (
          <article className="h-full bg-surface p-5">
            <SharedElement name={`title-${open.id}`} className="w-fit">
              <p className="text-lg font-semibold tracking-tight text-fg">{open.message}</p>
            </SharedElement>
            <SharedElement name={`status-${open.id}`} className="mt-2 w-fit">
              <span className="inline-flex items-center gap-1.5 rounded-full border border-line px-2 py-0.5 text-xs text-fg">
                <span className={cn('size-1.5 rounded-full', open.dot)} />
                {open.status}
              </span>
            </SharedElement>
            <dl className="mt-5 grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-sm">
              <dt className="text-fg-muted">Commit</dt>
              <dd className="flex items-center gap-1.5 font-mono text-[13px] text-fg">
                <GitCommitIcon size={14} className="text-fg-muted" />
                {open.id}
              </dd>
              <dt className="text-fg-muted">Author</dt>
              <dd className="text-fg">{open.author}</dd>
              <dt className="text-fg-muted">Build</dt>
              <dd className="text-fg">{open.time}</dd>
            </dl>
          </article>
        ) : (
          <ul className="h-full bg-surface py-1">
            {DEPLOYS.map((d) => (
              <li key={d.id}>
                <button
                  type="button"
                  data-deploy={d.id}
                  onClick={() => go(`/deployments/${d.id}`, 'forward')}
                  className="flex w-full items-center gap-3 px-4 py-3 text-start outline-none hover:bg-raised focus-visible:bg-raised focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-inset"
                >
                  <span className="min-w-0 flex-1">
                    <SharedElement name={`title-${d.id}`} className="w-fit max-w-full">
                      <span className="block truncate text-sm font-medium text-fg">{d.message}</span>
                    </SharedElement>
                    <span className="mt-0.5 block text-xs text-fg-muted">
                      {d.author} · {d.when}
                    </span>
                  </span>
                  <SharedElement name={`status-${d.id}`}>
                    <span className="inline-flex items-center gap-1.5 rounded-full border border-line px-2 py-0.5 text-xs text-fg">
                      <span className={cn('size-1.5 rounded-full', d.dot)} />
                      {d.status}
                    </span>
                  </SharedElement>
                  <ChevronRightIcon size={15} className="text-fg-muted" />
                </button>
              </li>
            ))}
          </ul>
        )}
      </PageTransition>
    </div>
  )
}
```

Use it where a change of view is a change of place: opening a record from a list, stepping through a wizard, switching the panes of an app. It keeps people oriented between the two views. Don't animate every route of a content site: most navigations should feel instant, and a transition on each one taxes every click. Open a deployment in the preview, then go back.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { PageTransition, SharedElement } from '@youj/motion/interactions'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add page-transition
```

It brings `youj-core` with it.

## Usage

Wrap the view in `PageTransition` and give it a `routeKey` that changes with the view, usually the path. A new key animates from the old children to the new ones.

```tsx
import { PageTransition } from '@youj/motion/interactions'

export function Pane({ path }: { path: string }) {
  return (
    <PageTransition routeKey={path} className="h-full">
      {path === '/deployments' ? <DeploymentList /> : <DeploymentDetail path={path} />}
    </PageTransition>
  )
}
```

Both pages stack in one grid cell while they overlap, so nothing is measured or positioned absolutely, and the container clips whatever travels out of it. Give the container a height when the pages differ in height. The first render doesn't animate.

## Variants

`fade-through`, the default, fades the old page out quickly and the new one in just after, growing from 98% scale. `slide` pushes: both pages travel together. `clip-reveal` wipes the new page in over the old one, and `curtain` sweeps a solid panel across, swaps the page while it's covered, then sweeps away. Pick a variant, then switch tabs.

```tsx
'use client'

import { useId, useState, type KeyboardEvent } from 'react'
import { cn } from '@youj/core'
import { PageTransition, type PageDirection, type PageVariant } from '@youj/motion/interactions'

const VARIANTS: PageVariant[] = ['fade-through', 'slide', 'clip-reveal', 'curtain']
const TABS = [
  { name: 'Overview', rows: [0.9, 0.62, 0.78] },
  { name: 'Activity', rows: [0.55, 0.85, 0.4, 0.7] },
  { name: 'Settings', rows: [0.72, 0.5] },
]

/** Arrow keys, Home and End move the selection within a radio group or tab list, and focus follows. */
function roving(e: KeyboardEvent<HTMLElement>, index: number, count: number, select: (i: number) => void) {
  const keys: Record<string, number> = { ArrowRight: index + 1, ArrowLeft: index - 1, Home: 0, End: count - 1 }
  const next = keys[e.key]
  if (next === undefined) return
  e.preventDefault()
  const i = (next + count) % count
  select(i)
  ;(e.currentTarget.parentElement?.children[i] as HTMLElement | undefined)?.focus()
}

export default function PageTransitionVariants() {
  const id = useId()
  const [variant, setVariant] = useState<PageVariant>('slide')
  const [tab, setTab] = useState(0)
  const [direction, setDirection] = useState<PageDirection>('forward')
  const selectTab = (i: number) => {
    // Tabs to the right go forward and tabs to the left go back, so a slide travels the right way.
    setDirection(i >= tab ? 'forward' : 'back')
    setTab(i)
  }

return (
    <div className="flex w-full max-w-sm flex-col items-center gap-4">
      <div role="radiogroup" aria-label="Transition" className="flex flex-wrap justify-center gap-1 rounded-lg border border-line bg-canvas p-0.5">
        {VARIANTS.map((v, i) => (
          <button
            key={v}
            type="button"
            role="radio"
            aria-checked={variant === v}
            tabIndex={variant === v ? 0 : -1}
            onClick={() => setVariant(v)}
            onKeyDown={(e) => roving(e, i, VARIANTS.length, (n) => setVariant(VARIANTS[n]!))}
            className={cn(
              'rounded-md px-2.5 py-1 font-mono text-xs outline-none focus-visible:ring-2 focus-visible:ring-accent',
              variant === v ? 'bg-surface text-fg shadow-xs' : 'text-fg-muted hover:text-fg',
            )}
          >
            {v}
          </button>
        ))}
      </div>
      <div className="w-full overflow-hidden rounded-2xl border border-line bg-surface">
        <div role="tablist" aria-label="Project" className="flex gap-1 border-b border-line p-1.5">
          {TABS.map((t, i) => (
            <button
              key={t.name}
              id={`${id}-tab-${i}`}
              type="button"
              role="tab"
              aria-selected={tab === i}
              aria-controls={`${id}-panel`}
              tabIndex={tab === i ? 0 : -1}
              onClick={() => selectTab(i)}
              onKeyDown={(e) => roving(e, i, TABS.length, selectTab)}
              className="rounded-md px-3 py-1.5 text-sm text-fg-muted outline-none aria-selected:bg-raised aria-selected:text-fg focus-visible:ring-2 focus-visible:ring-accent"
            >
              {t.name}
            </button>
          ))}
        </div>
        {/* Keyed by variant, so switching variants starts clean. */}
        <PageTransition key={variant} routeKey={TABS[tab]!.name} variant={variant} direction={direction} className="h-44">
          <div role="tabpanel" id={`${id}-panel`} aria-labelledby={`${id}-tab-${tab}`} className="h-full bg-surface p-5">
            <p className="text-sm font-medium text-fg">{TABS[tab]!.name}</p>
            <div className="mt-4 space-y-2.5">
              {TABS[tab]!.rows.map((w, i) => (
                <div key={i} className="h-2 rounded-full bg-raised" style={{ width: `${w * 100}%` }} />
              ))}
            </div>
          </div>
        </PageTransition>
      </div>
    </div>
  )
}
```

`direction` flips the travel of `slide`, `clip-reveal` and `curtain`. Pass `"back"` when the navigation goes back, like the Back button in the first preview or a tab to the left in this one. Color the curtain with `curtainClassName`, `bg-accent` by default.

## Shared elements

Wrap an element in `SharedElement` with the same `name` on both pages, and it flies from its old position to its new one while the pages fade through. In the first preview, the commit message and the status badge fly from the list to the detail page and back.

```tsx
import { SharedElement } from '@youj/motion/interactions'

// On the list
<SharedElement name={`title-${deploy.id}`}>{deploy.message}</SharedElement>

// On the detail page
<SharedElement name={`title-${deploy.id}`}>
  <h1>{deploy.message}</h1>
</SharedElement>
```

Shared elements only fly under `fade-through`. When the page itself travels, a flying element doubles the motion and the two copies visibly disagree, so under `slide`, `clip-reveal` and `curtain` they stay in place with their page.

## Card to page

A shared element can change size and shape on the way, so a card's cover can grow into the header of the page it opens.

```tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { ArrowLeftIcon } from '@youj/icons'
import { PageTransition, SharedElement } from '@youj/motion/interactions'

const TEMPLATES = [
  { slug: 'commerce', name: 'Commerce', stack: 'Next.js · Stripe', about: 'A storefront with a cart, checkout and order emails.', tone: 'bg-[radial-gradient(120%_100%_at_15%_15%,color-mix(in_oklch,var(--color-accent)_50%,transparent),transparent_70%)]' },
  { slug: 'docs', name: 'Docs', stack: 'Next.js · MDX', about: 'Versioned pages, full-text search and an API reference.', tone: 'bg-[linear-gradient(135deg,transparent_25%,color-mix(in_oklch,var(--color-accent)_40%,transparent))]' },
  { slug: 'dashboard', name: 'Dashboard', stack: 'React · Postgres', about: 'Sign-in, roles and charts over your own tables.', tone: 'bg-[radial-gradient(120%_100%_at_85%_90%,color-mix(in_oklch,var(--color-accent)_45%,transparent),transparent_65%)]' },
  { slug: 'blog', name: 'Blog', stack: 'Astro · RSS', about: 'Posts in Markdown, with feeds and social cards.', tone: 'bg-[linear-gradient(0deg,color-mix(in_oklch,var(--color-accent)_45%,transparent),transparent_75%)]' },
]

export default function PageTransitionGrow() {
  const [open, setOpen] = useState<string | null>(null)
  const template = TEMPLATES.find((t) => t.slug === open)

// After each navigation, focus moves to the new page: the Back button, or back to the card that was opened.
  const shell = useRef<HTMLDivElement>(null)
  const opened = useRef<string | null>(null)
  useEffect(() => {
    if (open) opened.current = open
    const target = open ? '[data-back]' : opened.current && `[data-template="${opened.current}"]`
    if (target) shell.current?.querySelector<HTMLElement>(target)?.focus()
  }, [open])

return (
    <div ref={shell} className="w-full max-w-sm overflow-hidden rounded-2xl border border-line bg-surface">
      <div className="flex h-11 items-center gap-2 border-b border-line px-3">
        <button
          type="button"
          aria-label="Back"
          data-back=""
          disabled={!template}
          onClick={() => setOpen(null)}
          className="grid size-7 place-items-center rounded-md text-fg-muted outline-none enabled:hover:bg-raised enabled:hover:text-fg disabled:opacity-40 focus-visible:ring-2 focus-visible:ring-accent"
        >
          <ArrowLeftIcon size={15} />
        </button>
        <span className="font-mono text-xs text-fg-muted">/templates{template && `/${template.slug}`}</span>
      </div>
      <PageTransition routeKey={open ?? 'templates'} className="h-72">
        {template ? (
          <article className="h-full bg-surface p-4">
            {/* The same name on both pages: the cover grows from its card into the header. The radius is set in
                style, not a class, so the corners stay round while it scales. */}
            <SharedElement name={`cover-${template.slug}`} className={`h-28 bg-raised ${template.tone}`} style={{ borderRadius: 12 }} />
            <SharedElement name={`name-${template.slug}`} className="mt-4 w-fit">
              <p className="text-lg font-semibold tracking-tight text-fg">{template.name}</p>
            </SharedElement>
            <p className="mt-1 text-sm text-fg-muted">{template.about}</p>
            <div className="mt-4 flex items-center justify-between">
              <span className="font-mono text-xs text-fg-muted">{template.stack}</span>
              <button
                type="button"
                className="h-8 rounded-lg bg-accent px-3 text-sm font-medium text-on-accent outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
              >
                Deploy
              </button>
            </div>
          </article>
        ) : (
          <ul className="grid h-full grid-cols-2 content-start gap-3 bg-surface p-4">
            {TEMPLATES.map((t) => (
              <li key={t.slug}>
                <button
                  type="button"
                  data-template={t.slug}
                  onClick={() => setOpen(t.slug)}
                  className="block w-full rounded-xl p-1.5 text-start outline-none hover:bg-raised focus-visible:ring-2 focus-visible:ring-accent"
                >
                  <SharedElement name={`cover-${t.slug}`} className={`h-16 bg-raised ${t.tone}`} style={{ borderRadius: 8 }} />
                  <SharedElement name={`name-${t.slug}`} className="mt-2 w-fit">
                    <span className="block text-sm font-medium text-fg">{t.name}</span>
                  </SharedElement>
                  <span className="block text-xs text-fg-muted">{t.stack}</span>
                </button>
              </li>
            ))}
          </ul>
        )}
      </PageTransition>
    </div>
  )
}
```

Set its corner radius in `style`, not with a class. Motion corrects a radius it knows about while the element scales, so the corners stay round in flight.

## Next.js App Router

In the App Router, key the transition by `usePathname()` in a client component that your layout renders around `children`. The router swaps a page's content as soon as the route changes, so the leaving page would show the new route while it animates out. Freeze it: give each page the router context it was rendered with.

```tsx title="app/route-transition.tsx"
'use client'

import { useContext, useRef, type ReactNode } from 'react'
import { usePathname } from 'next/navigation'
import { LayoutRouterContext } from 'next/dist/shared/lib/app-router-context.shared-runtime'
import { PageTransition } from '@youj/motion/interactions'

// Keeps a leaving page on the route it was rendered for while it animates out.
function FrozenRoute({ children }: { children: ReactNode }) {
  const context = useContext(LayoutRouterContext)
  const frozen = useRef(context).current
  return <LayoutRouterContext.Provider value={frozen}>{children}</LayoutRouterContext.Provider>
}

export function RouteTransition({ children }: { children: ReactNode }) {
  const pathname = usePathname()
  return (
    <PageTransition routeKey={pathname} className="min-h-dvh">
      <FrozenRoute>{children}</FrozenRoute>
    </PageTransition>
  )
}
```

`next/dist/shared/lib/app-router-context.shared-runtime` is an internal path of Next.js, not a public API. It can move in a minor release, so pin `next` and check this file when you upgrade. Next has no public way to freeze a leaving page.

```tsx title="app/layout.tsx"
<body>
  <RouteTransition>{children}</RouteTransition>
</body>
```

Keep persistent chrome, like a sticky header, in the layout outside `RouteTransition`. The transition clips its pages, so a sticky element inside one would stick to the transition's box, not the viewport.

> **An internal import:** `LayoutRouterContext` ships with Next.js 16 but isn't public API, so check your transitions when you upgrade. Client-side views, like tabs, wizards and panes keyed by state, need no workaround.

## Reference

### Props

#### PageTransition

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `routeKey` (required) | `string` |  | Changing this key transitions to the new children. Usually the route path. |
| `children` (required) | `ReactNode` |  |  |
| `variant` | `'fade-through' \| 'slide' \| 'clip-reveal' \| 'curtain'` | `'fade-through'` |  |
| `direction` | `'forward' \| 'back'` | `'forward'` | Navigation direction; flips slide / clip-reveal / curtain. Forward travels toward the reading start, so slide and curtain mirror under RTL. |
| `curtainClassName` | `string` | `'bg-accent'` | Classes for the curtain panel. |
| `className` | `string` |  |  |

#### SharedElement

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Matching names on two pages morph into each other across a PageTransition. |

Also takes the props of `HTMLMotionProps<'div'>`.

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Fade-through out | `duration.fast`, `ease.exit` | 140ms; cubic-bezier(0.4, 0, 1, 1) | `opacity` |
| Fade-through in | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | `opacity`, after an `instant` delay |
| Fade-through scale | `spring.smooth` | 0.36s, bounce 0 | 0.98 to 1 |
| Slide | `spring.smooth` | 0.36s, bounce 0 | both pages, a full width |
| Clip reveal wipe | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | `clip-path` |
| Clip reveal rise | `duration.deliberate`, `ease.emphasized` | 560ms; cubic-bezier(0.6, 0, 0.1, 1) | 32px |
| Clip reveal exit | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | the old page dims and drifts 16px |
| Curtain | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1); 2 × slow + instant | in on `emphasized`, a short hold, out on `standard` |
| Shared element | `spring.smooth` | 0.36s, bounce 0 | flies between positions |

**Reduced motion:** Every variant becomes a short crossfade on the fast token, with no travel and no curtain. Shared elements jump to their new place.

#### Reduced motion

Every variant becomes the same short crossfade, so the change of view is still visible, without travel, wipes or a curtain. Shared elements move to their new place instantly.

### Accessibility

- A transition doesn't move focus. After a navigation, focus belongs on the new page, not on an element that has just left: the first preview moves it forward to the Back button, and back to the item that was opened.
- The curtain panel is `aria-hidden` and ignores the pointer.
- The leaving page stays in the document only while it animates out, which is at most a few hundred milliseconds at normal speed.

---

# Entrances

> Build real UI in front of the viewer: each entrance reads the page's own parts and plays them in, ending on the real thing.

Source: https://www.youj.dev/docs/motion/entrances

An entrance plays over UI that's already rendered. It reads the parts on the page, orders them from the outside in, and builds them up in its own style. When it ends, the page is exactly the real UI: nothing moves, nothing is left behind, and it skips itself under reduced motion. Every entrance shares the same options for `duration`, `speed` and `phases`, and can be cancelled at any moment.

- [Blueprint](https://www.youj.dev/docs/motion/blueprint): Drafted in pencil with its measurements, then inked, toned and set into the real UI.

- [Generate](https://www.youj.dev/docs/motion/generate): Built in part by part: regions dragged out, text typed, controls popped.

- [Prism](https://www.youj.dev/docs/motion/prism): Each part locks in from its color channels.

- [Trace](https://www.youj.dev/docs/motion/trace): A signal runs the layout and lights each part as it arrives.

- [Inspector](https://www.youj.dev/docs/motion/inspector): Each part shows its box model first, then hands off to the real one.

- [Layers](https://www.youj.dev/docs/motion/layers): An exploded stack of layers collapses flat into the UI.

- [Render passes](https://www.youj.dev/docs/motion/render-passes): Layout, paint and composite, sweeping through the parts.

## On this site only

Code (experimental) types out a demo's source beside it, and each line becomes its part as it's typed. It needs the demo's source as text, which a running app doesn't have, so it isn't in the library yet. Try it from the Entrance menu on any preview in these docs, where every demo's source is published.

---

# Blueprint

> Draft real UI as an architect's blueprint, with its measurements, then build it up stage by stage into the real thing.

Source: https://www.youj.dev/docs/motion/blueprint

```tsx
'use client'

import { useState } from 'react'
import { BlueprintEntrance } from '@youj/motion'

export default function BlueprintDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <BlueprintEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </BlueprintEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that explains how a piece of UI is built: a hero demo, a product tour, a component on show. A draftsman lays out the frame, measures off its regions and pencils every part, while two columns beside it log the build and the values it applies. Then a ruled edge sweeps down and inks the real UI in, part by part. Keep it to one moment on a page: it asks to be watched, and a second one in view competes with the first.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { BlueprintEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add blueprint
```

It brings `youj-core`, `entrance`, `youj-labels-blueprint` with it.

## Usage

Wrap the UI in `BlueprintEntrance`. It drafts its first child and plays on mount.

```tsx
import { BlueprintEntrance } from '@youj/motion'

export function Hero() {
  return (
    <BlueprintEntrance>
      <SignInCard />
    </BlueprintEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

For an element you don't render with React, call the engine. It returns a `cancel()` and a `finished` promise, and an `AbortSignal` in `signal` cancels it too. To drive it from a clock of your own (a video rendered frame by frame, a scrubber), pass `paused: true` and call `seek(t)` with the time in ms from its start: it shows that moment and holds it. It only goes forwards, and a time at or past its end ends it.

```ts
import { blueprint } from '@youj/motion'

const run = blueprint(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished
```

## Pacing

The build goes through seven stages, each advancing through the parts in build order, so it is visibly in progress from the first mark to the last: **survey** (the paper, the bounds and their dimensions), **layout** (the main regions), **detail** (every part in dotted pencil), **ink** (each outline traced over solid), **tone** (filled boxes in flat greys, hatching or a screen), **set** (the text sets in grey, line by line, and icons and charts trace their real shapes) and **finish** (a ruled edge sweeps down, and behind it the real colour, radii, shadows and images come in). It stays black and white until the finish.

The length grows with the demo: about 2 seconds for a card, about 3.5 for a small screen, and at most about 6 for a large one. Three options tune it:

- `duration` fixes the whole run, in milliseconds.
- `speed` scales it: `2` plays twice as fast. It applies on top of `duration` and the provider's speed.
- `phases` shares the run out between the seven stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default (`{ survey: 10, layout: 10, detail: 20, ink: 13, tone: 12, set: 13, finish: 22 }`), and `0` skips it.

```tsx
// a 2.4 s run with a quick pencil draft and a long, readable build-up
<BlueprintEntrance duration={2400} phases={{ survey: 6, layout: 6, detail: 12, ink: 18, tone: 18, set: 22, finish: 18 }}>
  <PricingCard />
</BlueprintEntrance>
```

A demo with no regions gives the layout's share to the detail.

The side columns show when there are about 180 pixels free on a side, inside the nearest container that clips; `columns="none"` leaves them out.

## What it reads

The draft comes from the real DOM, read once before the first frame: roles, tags and `data-slot` first, then geometry. Boxes with a fill, a border or a shadow are drafted as dotted outlines, text as dotted baselines with a cap-height tick, icons as their square with a centre mark, charts as their axes, images as a crossed box, list rows as one line, and fields with a caret. The largest boxes become the numbered regions. Anything it can't classify, and open popovers, simply appear at the finish. Fills, borders and type are logged with the theme's token names, like `fill surface` and `ink fg-muted`.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to draft: its first element is the drawing's frame. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count, about 2 s for a card, about 3.5 s for a small screen, at most about 6 s. |
| `phases` | `BlueprintPhases` | ``{ survey: 10, layout: 10, detail: 20, ink: 13, tone: 12, set: 13, finish: 22 }`` | Each phase's share of the run, as weights (normalized, so they never change the total; a phase left out keeps its default). |
| `columns` | `'auto' \| 'none'` | `'auto'` | The side columns (build log and values), shown when there is room beside the demo. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### blueprint

```ts
function blueprint(node: HTMLElement, options?: BlueprintOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `BlueprintPhases` | `{ survey: 10, layout: 10, detail: 20, ink: 13, tone: 12, set: 13, finish: 22 }` | Each stage's share of the run, as weights. |
| `columns` | `'auto' \| 'none'` | `'auto'` | The build and values columns, when there is room. |
| `labels` | `Partial<BlueprintLabels>` | Youj's labels | The build column's words and the columns' titles. `<BlueprintEntrance>` takes them from `<YoujProvider labels>`. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the draft. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Survey |  | 10% of the run | paper grid, registration cross, dotted bounds, dimensions counting up |
| Layout |  | 10% | the main regions, outside-in, with index, size and corner |
| Detail |  | 20% | every part pencilled in reading order, region by region |
| Ink |  | 13% | each outline traced over in solid ink, part by part |
| Tone |  | 12% | filled boxes take flat greys, hatching or a screen, top to bottom |
| Set | `ease.linear` | cubic-bezier(0, 0, 1, 1); 13% | text sets in grey, line by line; icons and charts trace their shapes |
| Finish | `ease.linear` | cubic-bezier(0, 0, 1, 1); 22% | a ruled edge sweeps down at an even pace; the drawing clears in a soft band behind it |
| Piece in | `duration.slow`, `ease.standard` | 340ms; cubic-bezier(0.2, 0, 0, 1) | `opacity`, as the edge passes it: a card, a control, a row, a paragraph |
| Clear | `duration.slow`, `ease.exit` | 340ms; cubic-bezier(0.4, 0, 1, 1) | numbers, columns and the paper fade |

**Reduced motion:** No draft: the UI is just there, and nothing is added to the page.

The demo is never restyled. It is hidden and shown by Web Animations alone: an `opacity` hold while it's drafted, a `clip-path` wipe under the edge, and an `opacity` fade on each piece, created just before its moment so a screen only ever has a few in flight. The drawing lives on two canvases in an overlay beside the demo, and a frame only adds the marks due since the last one. When the run ends, or `cancel()` is called, the animations are cancelled and the overlay removed, so the page is exactly as it was. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `blueprint()` returns a run that has already finished.

### Accessibility

- The drawing and the columns are `aria-hidden` and never take the pointer. The demo stays in the accessibility tree the whole time, so a screen reader reads the real UI, not the drawing.
- Tabbing into the demo, or pressing on it, ends the run at once, so nobody uses a part that hasn't been inked yet.
- Nothing flashes: lines draw in pencil tones of the theme's foreground and the reveal is a slow sweep.

---

# Generate

> Build real UI in part by part, in its real colors: regions dragged out, text typed in, controls popped, icons drawn.

Source: https://www.youj.dev/docs/motion/generate

```tsx
'use client'

import { useState } from 'react'
import { GenerateEntrance } from '@youj/motion'

export default function GenerateDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <GenerateEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </GenerateEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that shows a screen being made: a hero demo, a product tour, an AI-builds-your-UI moment. The demo's own frame is dragged out first, then its main regions, each with a selection outline. Then every part arrives in build order, each its own way: a surface drags out, text types in line by line, a control pops, an icon draws its strokes, a chart and an image wipe in, a rule extends and a row slides up. It needs no script. Keep it to one moment on a page: it asks to be watched.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { GenerateEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add generate
```

It brings `youj-core`, `entrance` with it.

## Usage

Wrap the UI in `GenerateEntrance`. It builds its first child and plays on mount.

```tsx
import { GenerateEntrance } from '@youj/motion'

export function Hero() {
  return (
    <GenerateEntrance>
      <SignInCard />
    </GenerateEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

```ts
import { generate } from '@youj/motion'

const run = generate(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished
```

## Pacing

The build goes through three stages: **frame** (the demo's box and its main regions are dragged out, with selection outlines), **build** (every part arrives, in build order, starting once its region is half open) and **settle** (anything floating, like an open popover, fades in).

The length grows with the demo: about 2 seconds for a button, 3 for a card and up to 9 for a large screen. Three options tune it:

- `duration` fixes the whole run, in milliseconds.
- `speed` scales it: `2` plays twice as fast. It applies on top of `duration` and the provider's speed.
- `phases` shares the run out between the three stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default (`{ frame: 16, build: 72, settle: 12 }`), and `0` skips it.

```tsx
// a quick run that is nearly all build
<GenerateEntrance duration={1400} phases={{ frame: 8, build: 84, settle: 8 }}>
  <PricingCard />
</GenerateEntrance>
```

## Regions

With no options, the regions dragged out first are the demo's largest boxes. To choose them, give `order` selectors (relative to the demo) in the order they should appear, and `names` to label a region on its tab while it is dragged out. A selector that matches nothing is skipped.

```tsx
<GenerateEntrance order={['[data-slot=sidebar]', 'main']} names={{ '[data-slot=sidebar]': 'Navigation', main: 'Content' }}>
  <Dashboard />
</GenerateEntrance>
```

## What it reads

The parts come from the real DOM, read once before the first frame: roles, tags and `data-slot` first, then geometry. Each is built in its real colors, so a primary button arrives in your accent. Open popovers simply fade in at the end.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to build: its first element is the frame. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `order` | `string[]` |  | Selectors for the regions to drag out first, in this order (default: the demo's largest boxes). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count. |
| `phases` | `GeneratePhases` | ``{ frame: 16, build: 72, settle: 12 }`` | Each stage's share of the run: the frame dragged out, the parts arriving, the settle. |
| `names` | `Record<string, string>` |  | A name for a region (by its selector in `order`), shown on its tab while it's dragged out. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### generate

```ts
function generate(node: HTMLElement, options?: GenerateOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `GeneratePhases` | `{ frame: 16, build: 72, settle: 12 }` | Each stage's share of the run, as weights. |
| `order` | `string[]` | the demo's largest boxes | Selectors for the regions to drag out first, in this order. |
| `names` | `Record<string, string>` |  | A name for a region, by its selector in `order`, shown on its tab. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Frame | `ease.emphasized` | cubic-bezier(0.6, 0, 0.1, 1); 16% of the run | the demo’s box, then its regions, dragged out from the reading corner with selection outlines |
| Build |  | 72% | each part arrives its own way, in build order |
| Settle |  | 12% | open popovers fade in |
| Drag out | `duration.slow`, `ease.emphasized` | 340ms; cubic-bezier(0.6, 0, 0.1, 1) | `clip-path` from the reading corner, with `opacity`: surfaces and fields |
| Type | `duration.slow`, `ease.linear` | 340ms; cubic-bezier(0, 0, 1, 1) | a `clip-path` that shows the lines done and the current one, a character at a time |
| Pop | `duration.base`, `ease.enter` | 220ms; cubic-bezier(0.16, 1, 0.3, 1) | `scale` from 0.86 and `opacity`: controls |

**Reduced motion:** No build: the UI is just there, and nothing is added to the page.

The demo is never restyled. While a part waits it is held by its inline opacity (no animation, so no compositor layer), and it arrives by a Web Animation that replaces the hold, created just before its moment. When the run ends, or `cancel()` is called, the animations are cancelled, the holds are put back exactly and the selection outlines are removed, so the page is exactly as it was. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `generate()` returns a run that has already finished.

### Accessibility

- The selection outlines and tabs are `aria-hidden` and never take the pointer. The demo stays in the accessibility tree the whole time, so a screen reader reads the real UI.
- Tabbing into the demo, or pressing on it, ends the run at once, so nobody uses a part that hasn't arrived yet.
- Nothing flashes: parts fade, wipe and pop once, and the outlines are thin and fade out.

---

# Prism

> Lock real UI in piece by piece out of its color channels: three faint copies slide together and snap into register as the real thing.

Source: https://www.youj.dev/docs/motion/prism

```tsx
'use client'

import { useState } from 'react'
import { PrismEntrance } from '@youj/motion'

export default function PrismDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <PrismEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </PrismEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that feels engineered: a hero demo, a launch moment, a product tour. Registration marks lock off the frame's corners and the frame itself registers. Then each piece, in reading order, arrives as three faint copies a few pixels apart, one per color channel; they slide together, hang a hair apart and snap into register, and the real piece takes their place. Keep it to one moment on a page: it asks to be watched.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { PrismEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add prism
```

It brings `youj-core`, `entrance` with it.

## Usage

Wrap the UI in `PrismEntrance`. It builds its first child and plays on mount.

```tsx
import { PrismEntrance } from '@youj/motion'

export function Hero() {
  return (
    <PrismEntrance>
      <SignInCard />
    </PrismEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

```ts
import { prism } from '@youj/motion'

const run = prism(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished
```

## Color

The copies are the piece's own colors split into their channels. On a dark theme they are red, green and blue light, which add up; on a light theme they are cyan, magenta and yellow ink, which multiply down. Either way, three copies in register are exactly the piece's colors again, so the snap hands over to the real piece without a change of color, and a primary button arrives in your accent, not in grey. It needs no color of its own and works with any theme.

## Pacing

The build goes through three stages: **frame** (the marks lock in, then the frame's outline and its large panels), **build** (every piece locks in, in reading order, a region at a time) and **settle** (the marks clear and anything floating fades in).

The length grows with the demo: about 2 seconds for a card and about 3.5 for a small screen. Three options tune it:

- `duration` fixes the whole run, in milliseconds.
- `speed` scales it: `2` plays twice as fast. It applies on top of `duration` and the provider's speed.
- `phases` shares the run out between the three stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default (`{ frame: 16, build: 72, settle: 12 }`), and `0` skips it.

```tsx
// a quick run that is nearly all build
<PrismEntrance duration={1400} phases={{ frame: 8, build: 84, settle: 8 }}>
  <PricingCard />
</PrismEntrance>
```

`marks={false}` leaves out the registration marks.

## What it reads

The pieces come from the real DOM, read once before the first frame: roles, tags and `data-slot` first, then geometry. A piece is the outermost part small enough to read as one (a field, a button, a stat card, a list row, a paragraph) or a part with nothing inside it (a chart, an image); what's inside a piece comes with it. Panels too big to be a piece register with the frame. Each piece's copies are redrawn from what was read: its boxes with their fills and borders, its words in their own face, its icons' and charts' shapes. Open popovers simply fade in at the end.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to build: its first element is the frame. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count, about 2 s for a card, about 3.5 s for a small screen. |
| `phases` | `PrismPhases` | ``{ frame: 16, build: 72, settle: 12 }`` | Each stage's share of the run, as weights (normalized, so they never change the total; a stage left out keeps its default, and 0 skips it). |
| `marks` | `boolean` | `true` | Registration marks off the frame's corners while it builds. |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### prism

```ts
function prism(node: HTMLElement, options?: PrismOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `PrismPhases` | `{ frame: 16, build: 72, settle: 12 }` | Each stage's share of the run, as weights. |
| `marks` | `boolean` | `true` | Registration marks off the frame's corners while it builds. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Frame |  | 16% of the run | four registration marks, then the frame’s outline and panels, lock in |
| Build |  | 72% | each piece’s copies slide together and snap into register, in reading order |
| Settle |  | 12% | the marks clear; open popovers fade in |
| Slide | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `transform` on each channel’s copy, from a few px apart to a hair apart |
| Snap | `duration.fast`, `ease.enter` | 140ms; cubic-bezier(0.16, 1, 0.3, 1) | the copies jump into register in one frame and the real piece fades in under them |

**Reduced motion:** No copies: the UI is just there, and nothing is added to the page.

The demo is never restyled. While a piece waits it is held by its inline opacity (no animation, so no compositor layer), and it appears by a Web Animation that replaces the hold at its snap. A piece's three copies are drawn once, on small canvases made just before its moment, and from there only their `transform` and their group's `opacity` move, so a frame does no drawing at all. When the run ends, or `cancel()` is called, the animations are cancelled, the holds are put back exactly and the overlay is removed, so the page is exactly as it was. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `prism()` returns a run that has already finished.

### Accessibility

- The copies and marks are `aria-hidden` and never take the pointer. The demo stays in the accessibility tree the whole time, so a screen reader reads the real UI.
- Tabbing into the demo, or pressing on it, ends the run at once, so nobody uses a piece that hasn't locked in yet.
- Nothing flashes: the copies are faint, small and move a few pixels, and the color only ever resolves into the UI's own.

---

# Trace

> Light real UI up like a circuit: a thin signal runs its layout and each part appears as the signal reaches it.

Source: https://www.youj.dev/docs/motion/trace

```tsx
'use client'

import { useState } from 'react'
import { TraceEntrance } from '@youj/motion'

export default function TraceDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <TraceEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </TraceEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that shows how a piece of UI is wired: a hero demo, a launch moment, a dashboard coming online. A thin signal comes in from beside the frame and runs both ways round its border. Then it spreads down the layout: along each box's edge, across the gutter above what the box holds and down a short square connector into each region, round that region's border, and on to every part, all branches at once. Each part glows briefly on its edge as the signal reaches it, then appears. Keep it to one moment on a page: it asks to be watched.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { TraceEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add trace
```

It brings `youj-core`, `entrance` with it.

## Usage

Wrap the UI in `TraceEntrance`. It lights up its first child and plays on mount.

```tsx
import { TraceEntrance } from '@youj/motion'

export function Hero() {
  return (
    <TraceEntrance>
      <Dashboard />
    </TraceEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

```ts
import { trace } from '@youj/motion'

const run = trace(document.querySelector('#overview')!, { speed: 1.5 })
await run.finished
```

## Color

The signal is the theme's foreground, so it reads on every theme. `accent` draws it in the theme's accent instead. The path it has run stays etched faintly behind it until the run settles, then fades.

## Pacing

The run goes through three stages: **enter** (the signal comes in and runs round the frame, and the frame fills in behind it), **spread** (it runs down the layout and lights every part) and **settle** (the etched path fades and anything floating fades in). The signal runs at one speed through the spread, so near parts light first and the farthest part lights last.

The length grows with the demo: about 2 seconds for a card and about 3.5 for a small screen. Three options tune it:

- `duration` fixes the whole run, in milliseconds.
- `speed` scales it: `2` plays twice as fast. It applies on top of `duration` and the provider's speed.
- `phases` shares the run out between the three stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default (`{ enter: 14, spread: 74, settle: 12 }`), and `0` skips it.

```tsx
// a quick run that is nearly all spread
<TraceEntrance duration={1400} phases={{ enter: 8, spread: 84, settle: 8 }}>
  <PricingCard />
</TraceEntrance>
```

## What it reads

The layout comes from the real DOM, read once before the first frame: roles, tags and `data-slot` first, then geometry. The main regions and the panels too big to be one part are the branches, each inside the smallest one that holds it; their borders are traced on their own edges, rounded corners included, and a panel fills in as its border is traced. The parts are the leaves: a field, a button, a stat card, a list row, a paragraph, or a part with nothing inside it (a chart, an image). What's inside a part comes with it. Open popovers simply fade in at the end.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to light up: its first element is the frame. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `accent` | `boolean` | `false` | The signal in the theme's accent instead of its foreground. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count, about 2 s for a card, about 3.5 s for a small screen. |
| `phases` | `TracePhases` | ``{ enter: 14, spread: 74, settle: 12 }`` | Each stage's share of the run, as weights (normalized, so they never change the total; a stage left out keeps its default, and 0 skips it). |

Also takes the props of `HTMLAttributes<HTMLDivElement>`.

#### trace

```ts
function trace(node: HTMLElement, options?: TraceOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `TracePhases` | `{ enter: 14, spread: 74, settle: 12 }` | Each stage's share of the run, as weights. |
| `accent` | `boolean` | `false` | The signal in the theme's accent instead of its foreground. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Enter | `ease.linear` | cubic-bezier(0, 0, 1, 1); 14% of the run | in from beside the frame, then both ways round its border; the frame fills in |
| Spread | `ease.linear` | cubic-bezier(0, 0, 1, 1); 74% | down the layout at one speed, every branch at once; panels fill in as their borders are traced |
| Settle | `ease.exit` | cubic-bezier(0.4, 0, 1, 1); 12% | the etched path fades; open popovers fade in |
| Glow | `duration.slow`, `ease.linear` | 340ms; cubic-bezier(0, 0, 1, 1) | a part’s edge lights as the signal reaches it, then fades |
| Part in | `duration.base`, `ease.standard` | 220ms; cubic-bezier(0.2, 0, 0, 1) | `opacity`, just after its glow |

**Reduced motion:** No signal: the UI is just there, and nothing is added to the page.

The demo is never restyled. While a part waits it is held by its inline opacity (no animation, so no compositor layer), and it appears by a Web Animation that replaces the hold when the signal reaches it. The signal's heads are small elements moved by `transform` along their routes, made just before they set off; the etched path is drawn on one canvas, a frame adding only the few pixels run since the last one. When the run ends, or `cancel()` is called, the animations are cancelled, the holds are put back exactly and the overlay is removed, so the page is exactly as it was. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `trace()` returns a run that has already finished.

### Accessibility

- The signal and the etched path are `aria-hidden` and never take the pointer. The demo stays in the accessibility tree the whole time, so a screen reader reads the real UI.
- Tabbing into the demo, or pressing on it, ends the run at once, so nobody uses a part that hasn't appeared yet.
- Nothing flashes: the signal is a 1 px line with a small head, and each glow is faint and brief.

---

# Inspector

> Show real UI first as the browser's box model, part by part, with a hover reading out each size, then hand each part to the real thing.

Source: https://www.youj.dev/docs/motion/inspector

```tsx
'use client'

import { useState } from 'react'
import { InspectorEntrance } from '@youj/motion'

export default function InspectorDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <InspectorEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </InspectorEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that shows how a piece of UI is laid out: a hero demo, a component on show, a layout walkthrough. Each part appears first the way a devtools overlay draws it: its margin, padding and content in three soft tints with a crisp edge. A hover runs through the tree ahead of them with a mono size tag (`div 72 × 40`, `p 14/20`) and the element's path under the demo. Then each part hands off to the real one, the frame first. Keep it to one moment on a page.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { InspectorEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add inspector
```

It brings `youj-core`, `entrance` with it.

## Usage

Wrap the UI in `InspectorEntrance`. It plays on its first child, on mount.

```tsx
import { InspectorEntrance } from '@youj/motion'

export function Hero() {
  return (
    <InspectorEntrance>
      <PricingCard />
    </InspectorEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

For an element you don't render with React, call the look. It returns a `cancel()` and a `finished` promise, and an `AbortSignal` in `signal` cancels it too. To drive it from a clock of your own (a video rendered frame by frame, a scrubber), pass `paused: true` and call `seek(t)` with the time in ms from its start: it shows that moment and holds it. It only goes forwards, and a time at or past its end ends it.

```ts
import { inspector } from '@youj/motion'

const run = inspector(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished
```

## Pacing

Two stages: **inspect** (every box lays down its model in build order, wiping in from its reading corner, while the hover runs through them) and **handoff** (the frame, then each piece in build order, fades in under its model, and the model fades off it). The hover rests on a part a little longer than a base beat, so on a busy screen it reads a sample of the parts, evenly through the run.

The length grows with the demo: about 3 seconds for a card and about 5 for a small screen. `duration` fixes it in milliseconds, `speed` scales it, and `phases` shares it out as weights (default `{ inspect: 60, handoff: 40 }`).

## What it reads

The parts come from the real DOM, read once before the first frame (the same reading as Blueprint's). Margins, borders and padding come from each element's computed style. The content is tinted in the theme's info ink, the padding in whichever of success and warning sits farther from it (so an amber accent never makes the two alike), and the margin is hatched in a neutral. A box that holds others is drawn by its edges and bands alone, so nested tints never pile up. The tag names an element by its tag and its `data-slot` (or `id`); text shows its font size and line height.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to play: its first element is the demo. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count. |
| `phases` | `{ inspect?: number; handoff?: number }` | ``{ inspect: 60, handoff: 40 }`` | Each stage's share of the run: the box models drawn in with the hover running through them, then the hand-off to the real parts. |

#### inspector

```ts
function inspector(node: HTMLElement, options?: InspectorOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `{ inspect?: number; handoff?: number }` | `{ inspect: 60, handoff: 40 }` | Each stage's share of the run, as weights. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Inspect | `ease.standard` | cubic-bezier(0.2, 0, 0, 1); 60% of the run | each box model wipes in from its reading corner, in build order |
| Hover | `duration.fast`, `ease.standard` | 140ms; cubic-bezier(0.2, 0, 0, 1) | glides from box to box; the tag and path change halfway across |
| Handoff |  | 40% | the frame, then each piece: the part fades in, then its model fades off it |
| Part in | `ease.enter` | cubic-bezier(0.16, 1, 0.3, 1) | `opacity` |
| Model out | `ease.standard` | cubic-bezier(0.2, 0, 0, 1) | `opacity` on the piece’s own canvas |

**Reduced motion:** No overlay: the UI is just there, and nothing is added to the page.

The demo is never restyled. Its parts are held by their inline opacity while they wait (no animation, so no compositor layer) and each arrives as a Web Animation made just before its moment. Each piece's model is drawn once on a canvas of its own, so its hand-off is a single opacity animation. When the run ends, or `cancel()` is called, everything is put back exactly. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `inspector()` returns a run that has already finished.

### Accessibility

- The overlay is `aria-hidden` and never takes the pointer. The demo stays in the accessibility tree the whole time.
- Tabbing into the demo, or pressing on it, ends the run at once.
- Nothing flashes: the tints are soft and every change is a fade or a wipe.

---

# Layers

> Show real UI first as an exploded isometric stack of its layers, then settle the camera flat as the stack collapses into the real thing.

Source: https://www.youj.dev/docs/motion/layers

```tsx
'use client'

import { useState } from 'react'
import { LayersEntrance } from '@youj/motion'

export default function LayersDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <LayersEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </LayersEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance that shows how a piece of UI is put together: a hero demo, a product tour, a component on show. The demo starts as an exploded stack, the way a view-hierarchy debugger shows a screen: the frame at the bottom, its regions above it, its boxes above those and its content (text and icons) on top, each a thin plane with its depth label (`z2  boxes  19`). The planes come up one by one and draw their parts in build order. Then the camera settles from the isometric angle to flat while the gaps close layer by layer, and each plane hands over to the real parts it holds. Keep it to one moment on a page.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { LayersEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add layers
```

It brings `youj-core`, `entrance`, `youj-labels-layers` with it.

## Usage

Wrap the UI in `LayersEntrance`. It plays on its first child, on mount.

```tsx
import { LayersEntrance } from '@youj/motion'

export function Hero() {
  return (
    <LayersEntrance>
      <Dashboard />
    </LayersEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

```ts
import { layers } from '@youj/motion'

const run = layers(document.querySelector('#dashboard')!, { speed: 1.5 })
await run.finished
```

## Pacing

Three stages: **stack** (the planes come up one by one, each drawing its parts as it arrives), **collapse** (the camera turns flat while the gaps close, bottom first) and **resolve** (the frame, then each plane in turn: its real parts fade in, then the plane fades off them).

## What it reads

The parts come from the real DOM, read once before the first frame (the same reading as Blueprint's), and are drawn on the planes in their real fills, borders, radii, type and shapes, so the flat stack is already close to the UI it hands over to. The camera is fitted so the exploded stack stays inside the demo's box and a small margin around it. A demo with no regions has three planes.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to play: its first element is the demo. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count. |
| `phases` | `{ stack?: number; collapse?: number; resolve?: number }` | ``{ stack: 45, collapse: 33, resolve: 22 }`` | Each stage's share of the run: the stack built up, its collapse to flat, the hand-over to the real parts. |

#### layers

```ts
function layers(node: HTMLElement, options?: LayersOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `{ stack?: number; collapse?: number; resolve?: number }` | `{ stack: 45, collapse: 33, resolve: 22 }` | Each stage's share of the run, as weights. |
| `labels` | `Partial<LayersLabels>` | Youj's labels | The layers' names on the depth labels. `<LayersEntrance>` takes them from `<YoujProvider labels>`. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Plane up | `duration.slow`, `ease.enter` | 340ms; cubic-bezier(0.16, 1, 0.3, 1) | `transform` (translateZ) and `opacity`, one plane after another |
| Parts drawn | `ease.standard` | cubic-bezier(0.2, 0, 0, 1); the stack, 45% | each part wipes onto its plane in build order |
| Collapse | `ease.standard` | cubic-bezier(0.2, 0, 0, 1); 33% | the camera turns flat; the gaps close one at a time, bottom first |
| Resolve | `ease.enter` | cubic-bezier(0.16, 1, 0.3, 1); 22% | per plane: its real parts fade in, then the plane fades off them |

**Reduced motion:** No stack: the UI is just there, and nothing is added to the page.

The stack is one preserve-3d stage on the overlay, moved by `transform` and `opacity` only. The demo is never restyled: its parts are held by their inline opacity while they wait and each arrives as a Web Animation. When the run ends, or `cancel()` is called, everything is put back exactly. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `layers()` returns a run that has already finished.

### Accessibility

- The stack is `aria-hidden` and never takes the pointer. The demo stays in the accessibility tree the whole time.
- Tabbing into the demo, or pressing on it, ends the run at once.
- The camera move is slow and eased; under reduced motion there is none.

---

# Render passes

> Play real UI in as the browser's pipeline: a layout pass, a paint pass and a composite pass, each sweeping through the parts with its count.

Source: https://www.youj.dev/docs/motion/render-passes

```tsx
'use client'

import { useState } from 'react'
import { RenderPassesEntrance } from '@youj/motion'

export default function RenderPassesDemo() {
  const [play, setPlay] = useState(0)
  return (
    <div className="flex flex-col items-center gap-5">
      <RenderPassesEntrance play={play}>
        <form
          aria-label="Invite to Halcyon"
          className="flex w-80 flex-col gap-4 rounded-xl border border-line bg-surface p-5 shadow-sm"
          onSubmit={(e) => e.preventDefault()}
        >
          <div>
            <h3 className="text-base font-semibold text-fg">Invite your team</h3>
            <p className="mt-1 text-sm text-fg-muted">They get access to every Halcyon project.</p>
          </div>
          <label className="flex flex-col gap-1.5 text-sm font-medium text-fg">
            Email addresses
            <input
              defaultValue="mira@halcyon.dev, kenji@halcyon.dev"
              className="h-9 rounded-md border border-line bg-field px-3 text-sm font-normal text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
            />
          </label>
          <div className="flex justify-end gap-2">
            <button type="button" className="h-9 rounded-md border border-line px-3 text-sm text-fg focus-visible:ring-2 focus-visible:ring-accent">
              Cancel
            </button>
            <button
              type="submit"
              className="h-9 rounded-md bg-accent px-3 text-sm font-medium text-accent-contrast focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2"
            >
              Send invites
            </button>
          </div>
        </form>
      </RenderPassesEntrance>
      <button
        type="button"
        onClick={() => setPlay((n) => n + 1)}
        className="h-8 rounded-md border border-line px-3 text-xs text-fg-muted focus-visible:ring-2 focus-visible:ring-accent"
      >
        Replay
      </button>
    </div>
  )
}
```

Use it for an entrance with a technical voice: a hero demo, a launch page, a talk about rendering. The browser's pipeline is played as theatre, three passes, each named over the demo with its count (`layout 12/54`) and each sweeping through the parts in build order. **Layout** outlines every box with its size. **Paint** fills each in a flat grey, with its text and icons in grey: square, no shadows, no radii. **Composite** hands each piece to the real part, with its colour, radii, shadows and images. Keep it to one moment on a page.

## Installation

```bash
pnpm add @youj/motion
```

```tsx
import { RenderPassesEntrance } from '@youj/motion'
```

Or copy the source into your app with the Youj CLI (import the package as above unless you copy in):

```bash
npx @youj/cli add render-passes
```

It brings `youj-core`, `entrance`, `youj-labels-render-passes` with it.

## Usage

Wrap the UI in `RenderPassesEntrance`. It plays on its first child, on mount.

```tsx
import { RenderPassesEntrance } from '@youj/motion'

export function Hero() {
  return (
    <RenderPassesEntrance>
      <PricingCard />
    </RenderPassesEntrance>
  )
}
```

Change `play` to play it again (a counter works), or set it to `false` to show the UI as it is. `onFinish` is called when the run ends.

```ts
import { renderPasses } from '@youj/motion'

const run = renderPasses(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished
```

## Pacing

The three passes run in turn, each sweeping through the parts so the build is visibly in progress from the first box to the last. In paint, a box paints before anything inside it, as a browser does, so a filled panel covers its children's layout boxes and they paint again on top.

## What it reads

The parts come from the real DOM, read once before the first frame (the same reading as Blueprint's). Layout lines are the theme's info ink; the paint greys are mixed from its foreground and canvas, darker for a stronger fill, and type that sits on a strong fill is set light. The pass names are labels, so `<YoujProvider labels>` translates them.

## Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The UI to play: its first element is the demo. |
| `play` | `boolean \| number \| string` | `true` | Plays on mount and again whenever this changes; `false` shows the UI as it is. |
| `onFinish` | `() => void` |  | Called when a run ends, also early when focus moves into the UI (not when unmounting or a new play cancels it). |
| `speed` | `number` | `1` | Multiplies the pace: 2 plays twice as fast. |
| `duration` | `number` |  | The whole run in ms, before `speed`. Default: from the demo's size and part count. |
| `phases` | `{ layout?: number; paint?: number; composite?: number }` | ``{ layout: 30, paint: 30, composite: 40 }`` | Each pass's share of the run. |

#### renderPasses

```ts
function renderPasses(node: HTMLElement, options?: RenderPassesOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | from the demo's size | The whole run in ms, before `speed`. |
| `speed` | `number` | `1` | Multiplies the pace. |
| `phases` | `{ layout?: number; paint?: number; composite?: number }` | `{ layout: 30, paint: 30, composite: 40 }` | Each pass's share of the run, as weights. |
| `labels` | `Partial<RenderPassesLabels>` | Youj's labels | The passes' names. `<RenderPassesEntrance>` takes them from `<YoujProvider labels>`. |
| `signal` | `AbortSignal` |  | Aborting cancels the run. |
| `reduced` | `boolean` | the provider, else the OS | Skip the entrance. |
| `personality` | `MotionPersonality` | the theme's | The motion personality its timing and curves come from. |
| `paused` | `boolean` | `false` | Hold the run at its start until `seek(t)` moves it, for a clock of your own. |

### Motion

| Moment | Tokens | Value | Note |
| --- | --- | --- | --- |
| Layout | `ease.standard` | cubic-bezier(0.2, 0, 0, 1); 30% of the run | each box traces its 1px outline, its size typed in its corner |
| Paint | `ease.linear` | cubic-bezier(0, 0, 1, 1); 30% | each box wipes in its flat grey, text and icons in grey |
| Composite | `ease.enter` | cubic-bezier(0.16, 1, 0.3, 1); 40% | the frame, then each piece: the real part fades in, then its drawing fades off it |

**Reduced motion:** No passes: the UI is just there, and nothing is added to the page.

The demo is never restyled. Its parts are held by their inline opacity while they wait and each arrives as a Web Animation made just before its moment. Each piece draws on a canvas of its own, so compositing it is a single opacity animation. When the run ends, or `cancel()` is called, everything is put back exactly. Focus or a press in the demo ends the run at once.

#### Reduced motion

The UI shows as it is, with no overlay and no animation. `renderPasses()` returns a run that has already finished.

### Accessibility

- The passes are `aria-hidden` and never take the pointer. The demo stays in the accessibility tree the whole time.
- Tabbing into the demo, or pressing on it, ends the run at once.
- Nothing flashes: every change is a trace, a wipe or a fade.

---

# Sound

> Add interface sounds for actions and feedback. Audio loads only when sound is enabled and unmuted.

Source: https://www.youj.dev/docs/sound

Youj components can play a short, quiet sound as their motion starts, so a press, a toggle or a new toast can be heard as well as seen. Press a key below to hear each sound in the default pack.

The Beacon pack, the default (hear it at https://www.youj.dev/docs/sound):
- `tap`: One dry 36 ms E6 sine ping: a short, pure contact with a rounded onset and natural decay.
- `select`: One lighter 31 ms A6 sine ping, softly rounded and cleanly decaying at a steady pitch.
- `toggleOn`: Two distinct dry pings rise E5–B5, 38 ms apart; a lighter pickup lands on a clear upper note.
- `toggleOff`: Two distinct dry pings fall B5–E5, 38 ms apart, with a softer lower landing.
- `success`: Two dry sine pings rise E5–B5, 90 ms apart; a soft pickup resolves into a longer, satisfying upper note.
- `error`: Two lower dry sine pings fall G4–E4, 94 ms apart, with rounded onsets and a gentle lower answer.
- `notify`: One clear 105 ms A5 sine ping with a calm onset and natural decay.
- `open`: Two rounded dry pings rise E5–E6, 52 ms apart, with a brighter upper note opening the gesture.
- `close`: Two shorter dry pings fold E6–E5, 44 ms apart, settling into a softer lower note.
- `tick`: One tiny 18 ms A6 sine ping: high, softly rounded and immediately clean.

Add sound to actions and feedback such as presses, selections, outcomes, toasts and dialogs. Components emit a **cue**, an event that `@youj/sound` can play. **Beacon** is the pack to start with, and five more built-in packs (Halo, Rill, Glyph, Zephyr and Glass) are one prop away.

The sounds are rendered offline and checked for loudness and harshness. Audio downloads only when sound is enabled and unmuted. Without a `sound` prop, cues play nothing and no sound code is downloaded.

## Installation

```bash
pnpm add @youj/sound
```

Or `npx @youj/cli add sound`, which installs the package in an app on the packages and copies the source in an app on the registry.

## Usage

Give `YoujProvider` a pack with its `sound` option:

```tsx title="app/providers.tsx"
'use client'

import type { ReactNode } from 'react'
import { YoujProvider } from '@youj/core'
import { beacon } from '@youj/sound'

export function Providers({ children }: { children: ReactNode }) {
  return <YoujProvider sound={beacon}>{children}</YoujProvider>
}
```

A pack is an object of functions, so in the Next.js App Router it must reach the provider from a Client Component: that's why the file starts with `'use client'`, and the root layout (a Server Component) renders `<Providers>` instead of passing `sound={beacon}` itself. A theme such as `theme={basalt}` is plain data and can stay on the layout's provider. `npx @youj/cli add sound` writes this file and wires the layout for you. Vite and Pages Router apps need no directive.

That's all the components need. Button, Switch, Checkbox, Toggle, Tabs, Segmented Control, Dialog, Sheet, Toaster and the copy buttons play their cue as their motion starts. To silence one, pass `sound={false}`, as in `<Switch sound={false} />`. To silence part of the page, nest a `<YoujProvider sound={false}>` around it.

## Sound builder

Preview interface sounds, choose a sound for each cue and export your pack as code.

Pick, hear and export at https://www.youj.dev/docs/sound#sound-builder. A pick becomes `candidates.<cue>.<family>` in `definePack`.

**Tap** (`tap`): A button is pressed, a copy button, a toggle key.
- Soft wood (`candidates.tap.wood`): A rubber mallet on a small hollow block at 760 Hz: a warm tock with a breath of wood grain, over in 40 ms.
- Glass (`candidates.tap.glass`): A fingernail on a glass bead: a clear ping at D6 (1.2 kHz), its one overtone kept low, in a small bright room.
- Digital (`candidates.tap.digital`): A sine key at D6 that starts bright (1:1 FM) and settles to pure in 15 ms, with a whisper of a click. Dry.
- Muted felt (`candidates.tap.felt`): A felt-covered key: a low-mid thock at A4 and the soft thump of the felt. Nothing above 2 kHz.
- Beacon (`candidates.tap.beacon`, the default): One dry 36 ms E6 sine ping: a short, pure contact with a rounded onset and natural decay.
- Halo (`candidates.tap.halo`): A 52 ms E4/B4/E5 pad blooms as one soft chord, with opening harmonics and a trace of detuned shimmer.
- Rill (`candidates.tap.rill`): A wet sine droplet dives 1.4 kHz to E5 in 28 ms, with a trace of mono chorus: round but distinctly moving.
- Glyph (`candidates.tap.glyph`): A 29 ms pulse gate at E5 with a clocked B5 answer: clear square-wave harmonics and a hint of seven-bit grit.
- Zephyr (`candidates.tap.zephyr`): A 36 ms puff through a tiny E5 pipe, its soft harmonic body mixed with filtered pink breath. No room on frequent cues.

**Select** (`select`): A tab or segment is chosen.
- Soft wood (`candidates.select.wood`): A smaller block, higher (1.1 kHz) and quicker than the tap: a light tik.
- Glass (`candidates.select.glass`): A thin glass rod tapped at E6: a small, clear tink, quieter than the tap.
- Digital (`candidates.select.digital`): A sine blip at E6 with a faint octave, 25 ms, bright only at the very start.
- Muted felt (`candidates.select.felt`): A felt tick at E5: round and soft, a notch lighter than the felt tap.
- Beacon (`candidates.select.beacon`, the default): One lighter 31 ms A6 sine ping, softly rounded and cleanly decaying at a steady pitch.
- Halo (`candidates.select.halo`): A lighter 44 ms A4/E5 pad gently brightens and floats upward; a tiny chord with no impact layer.
- Rill (`candidates.select.rill`): A smaller droplet curls down from 1.9 kHz to A5 in 21 ms, leaving a tiny bubble.
- Glyph (`candidates.select.glyph`): A tiny A5–E6 two-step pulse selection, with exact pitches and no slide.
- Zephyr (`candidates.select.zephyr`): A lighter A5 breath-note on the same pipe, shaped into a 30 ms puff.

**Toggle on** (`toggleOn`): A switch, checkbox or toggle turns on.
- Soft wood (`candidates.toggleOn.wood`): A wooden latch catching: two block contacts 24 ms apart, G5 then a step up to A5, the second louder.
- Glass (`candidates.toggleOn.glass`): Two glass taps 20 ms apart, D6 then a step up to E6: a bright little click-in.
- Digital (`candidates.toggleOn.digital`): Two sine keys 28 ms apart, A5 then a step up to B5, each bright for an instant.
- Muted felt (`candidates.toggleOn.felt`): A felt switch: two soft contacts 26 ms apart, D5 then a step up to E5.
- Beacon (`candidates.toggleOn.beacon`, the default): Two distinct dry pings rise E5–B5, 38 ms apart; a lighter pickup lands on a clear upper note.
- Halo (`candidates.toggleOn.halo`): An E4/B4/E5 chord swells open in 31 ms, its upper voices blooming together into a calm 145 ms pad.
- Rill (`candidates.toggleOn.rill`): Two connected rising bloops, E5 then B5, with a high bubble as the water pops upward.
- Glyph (`candidates.toggleOn.glyph`): Three clocked pulse steps E5–A5–B5, with a slightly held final square gate.
- Zephyr (`candidates.toggleOn.zephyr`): Two short pipe breaths, A4–E5, 27 ms apart, with the upper note opening a little longer.

**Toggle off** (`toggleOff`): It turns off.
- Soft wood (`candidates.toggleOff.wood`): The latch letting go: A5 then down to G5, softer mallets, the second contact landing quieter.
- Glass (`candidates.toggleOff.glass`): E6 then down to D6, the second tap softer and duller.
- Digital (`candidates.toggleOff.digital`): B5 then down to A5, the second key purer and quieter.
- Muted felt (`candidates.toggleOff.felt`): E5 then down to D5, rounder and quieter, like a key let back up.
- Beacon (`candidates.toggleOff.beacon`, the default): Two distinct dry pings fall B5–E5, 38 ms apart, with a softer lower landing.
- Halo (`candidates.toggleOff.halo`): The same warm chord leans downward and fades inward over 125 ms, keeping its soft pad onset.
- Rill (`candidates.toggleOff.rill`): A rounded downward gulp from B5 to E5, then a quiet collapsing bubble.
- Glyph (`candidates.toggleOff.glyph`): The same chip latch steps B5–A5–E5, landing in a shorter square gate.
- Zephyr (`candidates.toggleOff.zephyr`): E5–A4 in 25 ms, the second breath shorter: the pipe gently exhales.

**Success** (`success`): An action succeeds, a copy lands, a success toast.
- Classic (`candidates.success.classic`): The first palette’s success, E5 then B5 a fifth up, 75 ms apart: sines with a soft octave, now struck (a breath of contact), ringing a little longer, in a small room.
- Glass (`candidates.success.glass`): E5 and B5 on glass rods, 70 ms apart, ringing out into a small bright room.
- Soft wood (`candidates.success.wood`): A marimba, E5 then B5: warm and round, the tube holding up each fundamental, the tuned overtone just audible.
- Muted felt (`candidates.success.felt`): A felt piano, E5 then B5: the softest of the four, a hammer’s thump under two round notes.
- Beacon (`candidates.success.beacon`, the default): Two dry sine pings rise E5–B5, 90 ms apart; a soft pickup resolves into a longer, satisfying upper note.
- Halo (`candidates.success.halo`): A full E4/G4/B4/E5 chord blooms over 58 ms, then rests in 330 ms of warm harmonic shimmer: a calm, satisfying arrival.
- Rill (`candidates.success.rill`): Three buoyant upward sine scoops land E5–B5–E6, with tiny bubbles and a gently chorused final bloop.
- Glyph (`candidates.success.glyph`): A quick five-step E5–G5–B5–E6–B5 pulse arpeggio resolves in a held E6 square: a tasteful game reward.
- Zephyr (`candidates.success.zephyr`): A tiny pentatonic pipe phrase, E5–G5–B5 at 0, 74 and 151 ms, the last breath resting in a quiet synthetic room.

**Error** (`error`): An action fails, an error toast.
- Classic (`candidates.error.classic`): The first palette’s error, G4 then E4 a minor third down, 80 ms apart, each knock bending down as it dies: now with a knuckle’s thump, under 1.5 kHz.
- Soft wood (`candidates.error.wood`): Two knocks on a hollow wooden door, G4 then E4: dull, short, unmistakable.
- Muted felt (`candidates.error.felt`): Two felt piano notes, G4 then E4, each sagging a little: a gentle no that never buzzes.
- Digital (`candidates.error.digital`): A soft square (odd partials, band-limited under 1.8 kHz), G4 then E4, short and sagging: the classic buzz, warmed.
- Beacon (`candidates.error.beacon`, the default): Two lower dry sine pings fall G4–E4, 94 ms apart, with rounded onsets and a gentle lower answer.
- Halo (`candidates.error.halo`): Two low chord swells gently fold G4/D5 into E4/B4 with downward tuning; a clear two-part refusal, softly voiced.
- Rill (`candidates.error.rill`): Two falling water bloops, 1.2 kHz to G5 and A5 to E5: a gentle double gulp, never a low knock.
- Glyph (`candidates.error.glyph`): Two gently rounded square gates step A5–G5–E5, with a rest before the last: a precise digital refusal.
- Zephyr (`candidates.error.zephyr`): Two contained breaths descend G4–E4, 87 ms apart, without room. A clear low answer, still soft and harmonic.

**Notify** (`notify`): Any other toast arrives.
- Glass (`candidates.notify.glass`): A small glass bell at A5, struck once, with a twin 4 cents sharp for a slow shimmer, ringing about 250 ms into a small room.
- Soft wood (`candidates.notify.wood`): A marimba grace note: E5 just before A5 (45 ms), soft mallets. Da-ding.
- Digital (`candidates.notify.digital`): A clean FM key at A5 and its octave answering 60 ms later, quieter: a small digital ding·ding.
- Pluck (`candidates.notify.pluck`): A plucked string (Karplus–Strong) at A5, a soft E5 plucked 40 ms before it: a small harp figure, thumbed near the middle so it’s round, not twangy.
- Beacon (`candidates.notify.beacon`, the default): One clear 105 ms A5 sine ping with a calm onset and natural decay.
- Halo (`candidates.notify.halo`): An A4/E5/B5 chord breathes into focus over 46 ms, with upper voices opening and a tiny detuned halo.
- Rill (`candidates.notify.rill`): A rising A5 water dome with two small falling bubbles: playful and softly wet.
- Glyph (`candidates.notify.glyph`): B5–E6–B5, three short pulse gates with a little space between: a compact digital message.
- Zephyr (`candidates.notify.zephyr`): A small A4–E5–A5 pipe figure at 0, 57 and 117 ms, airy and spacious but shorter than the success phrase.

**Open** (`open`): A dialog or sheet opens.
- Air (`candidates.open.air`): A breath of pink noise through a soft band sweeping 350 Hz → 1.6 kHz as it swells (60 ms in, 90 out), set down with a faint felt tick as the surface lands.
- Glass (`candidates.open.glass`): Two glass notes rolled 45 ms apart, A5 then a fourth up to D6, struck softly so they bloom rather than ping.
- Digital (`candidates.open.digital`): A sine gliding up a fourth (A5 → D6) in 60 ms under a 35 ms swell, a faint octave on top.
- Muted felt (`candidates.open.felt`): A soft fwoomp: pink noise swelling as a low-pass opens 300 Hz → 1.5 kHz, landing on a felt thock at E5.
- Beacon (`candidates.open.beacon`, the default): Two rounded dry pings rise E5–E6, 52 ms apart, with a brighter upper note opening the gesture.
- Halo (`candidates.open.halo`): A warm E4/A4/B4/E5 pad expands as one chord under a 52 ms attack, opening the filter and lifting its tuning slightly.
- Rill (`candidates.open.rill`): A continuous exponential sine scoop from E4 to B5, swelling as it rises, with two surface bubbles.
- Glyph (`candidates.open.glyph`): A four-step pulse staircase E5–G5–B5–E6, rising in exact 24 ms increments under a small global swell.
- Zephyr (`candidates.open.zephyr`): A5 and E6 pipe breaths bloom 35 ms apart, softly overlapping into the same quiet room.

**Close** (`close`): It closes.
- Air (`candidates.close.air`): The breath falling away: a faint tick as the surface lifts, then 1.4 kHz → 300 Hz, shorter and softer.
- Glass (`candidates.close.glass`): D6 then down to A5, quieter and shorter: the bloom folding back.
- Digital (`candidates.close.digital`): The same sine gliding back down, D6 → A5, faster (45 ms) and quieter.
- Muted felt (`candidates.close.felt`): The thock first (D5), then the breath closing down 1.2 kHz → 250 Hz.
- Beacon (`candidates.close.beacon`, the default): Two shorter dry pings fold E6–E5, 44 ms apart, settling into a softer lower note.
- Halo (`candidates.close.halo`): The same soft chord settles downward into a 210 ms fade, with a 38 ms swelling onset and inward-moving harmonics.
- Rill (`candidates.close.rill`): The water folds downward from E6 to E5 in 85 ms, with a small final bubble and no thump.
- Glyph (`candidates.close.glyph`): E6–B5–G5–E5, the pulse staircase folds down in 19 ms increments.
- Zephyr (`candidates.close.zephyr`): The pipe bloom folds E6–A5, 29 ms apart, with shorter breaths and a quieter room tail.

**Tick** (`tick`): A detent: a slider or stepper step, in your own controls.
- Soft wood (`candidates.tick.wood`): The smallest woodblock, at 1.5 kHz, 12 ms: a detent under the finger.
- Glass (`candidates.tick.glass`): A grain of glass at G6: 20 ms, barely a ring.
- Digital (`candidates.tick.digital`): Six cycles of a 1.6 kHz sine, shaped to a click: a clean 4 ms tick with no ring.
- Muted felt (`candidates.tick.felt`): A soft felt tk at A5, 15 ms.
- Beacon (`candidates.tick.beacon`, the default): One tiny 18 ms A6 sine ping: high, softly rounded and immediately clean.
- Halo (`candidates.tick.halo`): A 28 ms A4/E5 micro-pad: a 6 ms chord bloom with moving upper harmonics and the faintest shimmer.
- Rill (`candidates.tick.rill`): A crisp 20 ms microbubble, diving 2.2 kHz to B5; even the smallest cue has a wet pitch curl.
- Glyph (`candidates.tick.glyph`): A crisp E6–B5 pulse microstep in 15 ms: a real chip gate, with no falling sine or resonant knock.
- Zephyr (`candidates.tick.zephyr`): An 18 ms A5 breath-note, the pipe reduced to its smallest soft articulation.

### Your files

Add a WAV, MP3, OGG or M4A file to a cue, or drop it onto the cue. The builder decodes it in your browser without uploading it. It mixes the audio to mono, trims silence, adjusts loudness and fades the tail.

Loudness uses a K-weighted meter over the loudest 100 ms, with a peak limit below −1 dBTP. You’ll see warnings for sounds longer than 400 ms, clipping, or files that cannot match the pack’s loudness without clipping.

Your picks among the built-in sounds are in this page's link, so you can share them or come back to them. Your files stay in the tab: download the .zip to keep them.

### Use the export

The export is `lib/sounds.ts`, a [`definePack`](https://www.youj.dev/docs/sound/custom-sounds) that names each built-in pick by its candidate (`candidates.tap.halo`) and each of your files by the path it's served from (`/sounds/tap.wav`). The .zip adds your files as WAV, which every browser decodes, under `public/sounds/`, and a README. Copy them into your app and give the pack to the provider:

```tsx
import { YoujProvider } from '@youj/core'
import { sounds } from '@/lib/sounds'

export function Providers({ children }: { children: React.ReactNode }) {
  return <YoujProvider sound={sounds}>{children}</YoujProvider>
}
```

Only the sounds you changed load, each in a chunk of its own, and only once sound is on. The cues you left alone play the Beacon pack.

### How the candidates are made

Each cue has a candidate from each built-in pack, the default first. **Beacon**, the default, is pure, dry sine pings with a natural decay. **Halo** is soft chord swells with a slow shimmer. **Rill** is round droplets that rise and fall. **Glyph** is square pulses and quick arpeggios. **Zephyr** is a tiny blown pipe in a quiet room. **Glass** is a glass rod or bead, struck hard, in a small bright room. Glass's error is **Classic**, the first palette's two falling knocks. None is a sample: every sound is rendered by code in `packages/sound/scripts`, from seeded generators, so a render is the same on every machine.

The candidates of a cue are matched in loudness, stay under −1 dBTP after encoding, start and end at silence, and keep their energy out of the 2–5 kHz band where interface sounds turn shrill. The pitched sounds share the notes of E minor pentatonic, so any two that overlap agree.

## Examples

### Let people mute it

Offering sound is the app's choice, and muting it is the user's. `useSound()` (from `@youj/core`) reads and sets the mute from anywhere under the provider.

To start muted, so sound is there when someone turns it on, pass `defaultMuted` in the provider's `sound` object: `<YoujProvider sound={{ pack: beacon, defaultMuted: true }}>`. Without it, sound is on as soon as a pack is installed. The provider remembers the choice: once someone mutes or unmutes, their choice is stored in the browser and wins over `defaultMuted` on their next visit.

To keep the choice yourself instead, such as in a user's settings on your server, pass it as `muted` in the `sound` object and save it from `onMutedChange`:

```tsx
'use client'

import { useState, type ReactNode } from 'react'
import { YoujProvider, useSound } from '@youj/core'
import { beacon } from '@youj/sound'
import { Switch } from '@youj/react'

export function Providers({ children }: { children: ReactNode }) {
  const [muted, setMuted] = useState(false) // load it from your settings
  return (
    <YoujProvider sound={{ pack: beacon, muted, onMutedChange: setMuted }}>
      {children}
    </YoujProvider>
  )
}

export function SoundSetting() {
  const sound = useSound()
  return <Switch aria-label="Interface sounds" checked={!sound.muted} onCheckedChange={(on) => sound.setMuted(!on)} />
}
```

### The cues

| Cue | Plays when | In the Beacon pack |
| --- | --- | --- |
| `tap` | A button is pressed. | One short, dry sine ping at E6. |
| `select` | A tab or segment is chosen. | A lighter ping at A6, quieter than the tap. |
| `toggleOn`, `toggleOff` | A switch, checkbox or toggle turns on or off. | Two quick pings stepping up E5–B5, or back down and softer. |
| `success` | An action succeeds, a copy lands, a success toast arrives. | Two pings rising E5–B5, the upper one held a little longer. |
| `error` | An action fails, an error toast arrives. | Two lower pings falling G4–E4, gently. |
| `notify` | Any other toast arrives. | One clear ping at A5. |
| `open`, `close` | A dialog or sheet opens or closes. | Two pings opening up an octave, E5–E6, or folding back down, quieter. |
| `tick` | A detent in your own controls: a slider or stepper step. | A tiny ping at A6, barely there. |

### Packs

Pass any of these as `sound`. Each built-in pack is one instrument across all ten cues, and loads only when it's chosen and sound is on:

| Pack | Character |
| --- | --- |
| `beacon` | Pure, dry sine pings with a natural decay: calm and exact. |
| `halo` | Soft chord swells with a slow shimmer: ambient and warm. |
| `rill` | Round droplets that rise and fall: playful and wet. |
| `glyph` | Square pulses and quick arpeggios: precise, retro-modern. |
| `zephyr` | A tiny blown pipe in a quiet room: airy and pentatonic. |
| `glass` | Struck glass beads, rods and a small bell: the first default, still available. |

```tsx
import { YoujProvider } from '@youj/core'
import { halo } from '@youj/sound'

<YoujProvider sound={halo}>{children}</YoujProvider>
```

To change a few sounds, or all of them, pick from the built-in candidates or bring your own files in the [Sound builder](#sound-builder), which exports the result as a pack. Or write one with `definePack`: the cues you name play your sounds, and Beacon plays the rest. See [Custom sounds](https://www.youj.dev/docs/sound/custom-sounds).

### The rules

- **Opt-in, then on.** Nothing plays and nothing downloads without `sound` on `YoujProvider`. Once you set it, sound starts unmuted: every press is audible after the visitor's first gesture, until they mute it (pass `muted` to start muted). The player and the pack's audio load in chunks of their own, and not at all while sound is muted.
- **Tied to motion.** A sound starts with its animation: a press on pointer down, an outcome as its check draws. Speed never changes its pitch or length.
- **Silent under reduced motion,** because the sound belongs to the motion. `whenReduced` keeps it, and `motion={false}` silences it too for an app whose sounds carry meaning of their own.
- **Only after a gesture.** Browsers allow audio once someone has pressed or typed on the page, so nothing plays before that.
- **Never in a hidden tab.** The audio device is released while the tab is hidden and after half a minute of silence.
- **Never a machine gun.** A cue can't retrigger within its cooldown, quick repeats play quieter (a held arrow key ticks rather than hammers), and at most four sounds play at once.
- **Server-safe.** Nothing touches the browser until an effect or an event handler runs.

## Reference

### Accessibility

Sound never carries information on its own. Every cue doubles a visible change, such as the thumb moving, the check drawing or the dialog arriving, and, where there is one, an announcement, such as a button's outcome or a toast. Someone who can't hear it, or has muted it, misses nothing. Keep the same rule for your own sounds: play one only alongside a state change that is visible and announced.

- [Sound builder](https://www.youj.dev/docs/sound#sound-builder): Every candidate for every cue, or a file of your own: hear them as a set and export a pack.

- [Custom sounds](https://www.youj.dev/docs/sound/custom-sounds): definePack: your sounds for the cues you name, the Beacon pack for the rest.

- [API](https://www.youj.dev/docs/sound/api): YoujProvider's sound options, useSound, definePack, the pack format, and the cue bus for your own components.

---

# Custom sounds

> Replace built-in sounds with your own files or another sound from the library.

Source: https://www.youj.dev/docs/sound/custom-sounds

## definePack

Define a pack to replace the sounds you want to change. Each cue can use a built-in sound or your own file. Unchanged cues use the `base` pack, which defaults to Beacon. The [Sound builder](https://www.youj.dev/docs/sound#sound-builder) can generate the pack for you.

```ts title="lib/sounds.ts"
import { candidates, definePack } from '@youj/sound'

export const sounds = definePack({
  sounds: {
    tap: candidates.tap.halo,
    notify: candidates.notify.glyph,
    error: '/sounds/error.wav',
  },
})
```

Then give it to the provider: `<YoujProvider sound={sounds}>`. Define it at module scope, as above, so it's one pack for the page's life: each pack is loaded and decoded once.

A sound can be:

- **A candidate** from `candidates`, by cue and family: `candidates.tap.halo`, `candidates.error.glyph`. The [Sound builder](https://www.youj.dev/docs/sound#sound-builder) lists them all. Each is a chunk of its own, loaded only when a pack plays it.
- **A URL**, as a string or a `URL`: a file in your public folder, or on your CDN.
- **Bytes**, an `ArrayBuffer` or a `Uint8Array`.
- **A function** that loads one of those, called when sound first turns on: `() => import('./sounds/tap.mp3')` where your bundler serves an audio import as a URL (the module's `default` is used).

## When a file fails

Nothing loads until sound is on and unmuted. Then each sound is fetched or loaded once and decoded in the browser. A file that doesn't load (a 404, say) or won't decode (a page served in its place, or a format the browser can't read) leaves its cue to the base pack, and in development the console says which cue, which file and why. A cue that isn't one, or a source that isn't a URL, bytes or a function, is warned about as soon as the pack is defined. It's all server-safe: `definePack` only describes the pack, and fetches nothing on the server.

## Your files

Every browser decodes MP3 and WAV. Ogg and AAC play in most, but not all, so prefer MP3 or WAV. Keep your sounds short (a press under 60 ms, an outcome under 400), mono and free of leading silence and clicks, and level them to sit with the rest: the provider plays them at its volume, squared, so 0.5 is 12 dB down. The Sound builder does all of that for a file you add, and exports it as WAV.

## A pack from scratch

A `SoundPack` carries the player's `arm()` and `play()` as well as its sounds, so `definePack` is the way to make one. The cues you leave out play its `base`, Beacon by default:

```ts
import { definePack } from '@youj/sound'

export const studio = definePack({
  name: 'studio',
  sounds: { tap: '/sounds/tap.mp3', success: '/sounds/success.mp3' },
})
```

## A pack in Youj itself

In the repository, `packages/sound/packs.config.ts` names the candidate each built-in pack plays for each cue, and which pack is the default. After an edit, `pnpm -F @youj/sound render` renders every candidate, writes each pack to `src/packs/` and every candidate to `src/candidates/`, and fails if a file passes 6 KB or a pack 40 KB. A new key in the config is a new pack, exported from `@youj/sound` by its name.

---

# API

> Configure sound playback, trigger cues and define custom sound packs.

Source: https://www.youj.dev/docs/sound/api

## YoujProvider's sound options

`@youj/sound` exports packs; `YoujProvider` (from `@youj/core`) plays them. Without `sound`, no sound code is requested. With it, nothing downloads until sound is on and unmuted; then the player and the pack's audio load in chunks of their own, and sound starts at the user's first gesture.

`sound` takes a pack on its own (`sound={beacon}`), `false`, or an object that sets the rest:

- `pack: SoundPack | false`: The pack. `false` silences this subtree (a preview, an embedded editor). Nested providers inherit it.
- `volume: number`: Loudness, 0–1, on a perceptual curve. Default 0.5.
- `muted: boolean` and `onMutedChange: (muted: boolean) => void`: The user's mute, controlled. Left out, the provider keeps it, starting unmuted: setting `sound` is the opt-in, so cues play after the first gesture. Pass `muted: true` to start muted.
- `whenReduced: boolean`: Keep playing under reduced motion. Default false. Sound is always silent under `motion={false}`.

```tsx
<YoujProvider sound={{ pack: beacon, volume: 0.4, muted, onMutedChange: setMuted }}>{children}</YoujProvider>
```

Settings a nested provider leaves out come from the one above it, so a quieter region is `<YoujProvider sound={{ volume: 0.3 }}>` and a silent one `<YoujProvider sound={false}>`.

## useSound

`useSound()` (from `@youj/core`) returns the nearest provider's state, for a settings screen or a component of your own:

- `enabled: boolean`: Whether a provider above has sound on.
- `muted: boolean`: The user's mute.
- `setMuted: (muted: boolean) => void`: Mutes or unmutes. The provider reports it through `onMutedChange`; keeping it is the app's job.
- `volume: number`: The provider's volume, 0–1.
- `play: (cue: SoundCue) => boolean`: Plays a cue with every rule applied: silent when muted, under reduced motion, in a hidden tab, before the first gesture, and within the cue's cooldown. Returns whether it played (false too while the pack is still loading).

## Packs

The built-in packs are `beacon` (the one `definePack` falls back to), `halo`, `rill`, `glyph`, `zephyr` and `glass`; pass any of them as `sound`.

### definePack

`definePack(definition)` returns a `SoundPack` of your own. See [Custom sounds](https://www.youj.dev/docs/sound/custom-sounds).

- `sounds: Partial<Record<SoundCue, SoundSource>>`: Each cue's sound. The cues you leave out play the base pack's.
- `base: SoundPack`: Plays every cue `sounds` leaves out, and any whose file won't load or decode. Loaded only then. Default `beacon`.
- `name: string`: Names the pack in warnings. Default `'custom'`.

A `SoundSource` is a `SoundFile` (a URL as a string or `URL`, or bytes as an `ArrayBuffer` or `Uint8Array`), or a function that loads one when sound first turns on, resolving to the file or to a module whose `default` is the file.

### candidates

`candidates` holds every built-in sound by cue and family, for `definePack`: `candidates.tap.halo`, `candidates.error.glyph`. Each is a loader, `() => Promise<Uint8Array>`, whose MP3 is a chunk of its own, fetched only when a pack that plays it turns sound on. The [Sound builder](https://www.youj.dev/docs/sound#sound-builder) lists the six packs' sounds.

### SoundPack

A `SoundPack` is what `YoujProvider`'s `sound` takes: motion's small `SoundRuntime` interface (`arm()` fetches the player and audio, `play(cue, volume)` plays) plus a `name`, a `load()` that resolves to `SoundSources` (each cue's `SoundFile`), and an optional `base` that plays the cues it lacks. `load()` runs once, the first time sound turns on with the pack.

## Cues

`soundCues` lists the cues in order: `tap`, `select`, `toggleOn`, `toggleOff`, `success`, `error`, `notify`, `open`, `close` and `tick`. `SoundCue` is their type. Both live in `@youj/core`, where components emit them.

## In your own components

Components don't play sounds. They emit cues on motion's cue bus, and the provider above decides what plays. `useSoundCue()` from `@youj/core` returns the emitter. Call it where the motion starts, and only for a person's own action or an arrival, never on mount or hover. Without `sound` on the provider it does nothing, and your component carries no sound code:

```tsx
'use client'

import { useSoundCue } from '@youj/core'
import { BookmarkIcon } from '@youj/icons'

export function SaveButton({ saved, onSavedChange }: { saved: boolean; onSavedChange: (saved: boolean) => void }) {
  const cue = useSoundCue()
  return (
    <button
      type="button"
      aria-pressed={saved}
      aria-label="Save"
      onClick={() => {
        onSavedChange(!saved)
        cue(saved ? 'toggleOff' : 'toggleOn')
      }}
    >
      <BookmarkIcon active={saved} />
    </button>
  )
}
```

`YoujProvider` is the bus: components emit cues to it and the pack plays them. To send cues somewhere else, such as a haptics engine or a test's recorder, pass your own runtime as `sound`: a `{ name, arm, play }` object, which is what a pack is. Its `play(cue, volume)` is called for every cue that passes the rules above, and `arm()` when sound turns on.

---

# Motion playground

> Try motion settings, compare their timing curves and copy the code.

Source: https://www.youj.dev/docs/motion/playground

[Open the Motion playground](https://www.youj.dev/docs/motion/playground): every spring, tween, stagger, personality and overlay preset on a stage, plotted as it plays, with the code each takes. Its address holds the view, e.g. https://www.youj.dev/docs/motion/playground?tab=tweens&duration=slow&ease=emphasized.

## What each view shows

- **Springs**: `snappy`, `smooth` and `settle`, or a felt duration and bounce of your own, on a sidebar's selection. The plot is Motion's own solver; the trace is the highlight as it really moves, and it keeps its velocity when you press another item mid-glide.
- **Tweens**: the five durations against the `standard`, `enter`, `exit` and `emphasized` curves, or your own cubic-bezier, on a toast that comes and goes.
- **Stagger**: `tight`, `base` and `loose` steps on a list, in any order, with a timeline of when each row starts and lands.
- **Personalities**: `precise`, `calm` and `lively` side by side on the same moment. The code is the same in all three; the theme decides what the tokens mean.
- **Presence**: the overlay presets, `yj-pop`, `yj-dialog`, `yj-sheet-end` and `yj-toast`, in and out, and how much shorter the way out is.
- **Reduced motion**: the same interaction with reduced motion off and on, and what each keeps.

The views follow your system's reduced-motion setting, and the Speed beside the tabs slows them. Under reduced motion every stage shows its end state and the plots show the motion it replaces. The address is the view: copy it, or use the link button, to share exactly what's on screen.

When a value is a token, the code names the token. A custom value prints as numbers, scaled by `k.timeScale` so Speed still reaches it, with the closest token beside it. Prefer the token: it follows the theme's [motion personality](https://www.youj.dev/docs/theming#motion-personality) and keeps the kit consistent.