{label} {value} px

{/* The native range owns input, keys and a11y; its 16px thumb matches the drawn one. */} onChange(Number(e.target.value))} onPointerDown={onGrab} onKeyDown={onKey} className="absolute inset-x-0 top-1/2 z-10 h-11 w-full -translate-y-1/2 cursor-pointer appearance-none bg-transparent opacity-0 [&::-moz-range-thumb]:size-4 [&::-moz-range-thumb]:border-0 [&::-webkit-slider-thumb]:size-4 [&::-webkit-slider-thumb]:appearance-none" />

{/* A fixed cap plus a scaled run, so the fill ends under the thumb's centre. */}

); } function NaiveSwitch({ checked, onChange }: { checked: boolean; onChange: (v: boolean) => void }) { return ( ); } /* ---------- Rolling digits ---------- */ function RollingNumber({ value }: { value: number }) { const tens = Math.floor(value / 10) % 10; return ( <> {value} ); } function Digit({ digit, hidden = false }: { digit: number; hidden?: boolean }) { return ( ); } /* ---------- Player parts ---------- */ function PlayerButton({ label, primary = false, onClick, children, }: { label: string; primary?: boolean; onClick?: () => void; children: React.ReactNode; }) { return ( {children} ); } function Cover() { const id = useId().replace(/[^\w-]/g, ""); // safe inside url(#…) return ( ); } function SkipIcon({ className = "" }: { className?: string }) { return ( ); } function PlayIcon() { // Drawn ~1.5px right of centre so the triangle reads optically centred. return ( ); } function PauseIcon() { return ( ); } ``` --- # Accordion > Disclosures whose height springs open with no overshoot, content fading in as the height lands and the chevron turning on the same spring. Base UI Accordion behaviour. - Tier: Free (MIT) - Interaction: Press - Page: https://eased.dev/components/accordion - Installs: @base-ui/react - Registry: https://eased.dev/r/accordion.json ## Install ```bash npx shadcn add https://eased.dev/r/accordion.json ``` Disclosures on Base UI's Accordion (buttons in headings, `aria-expanded`/`aria-controls`, arrow keys, Home/End), animated by Auto Height. ```tsx import { Accordion, AccordionItem } from "@/components/eased/accordion/accordion"; On the day your trial ends, then on the same date every month. Within 14 days, in full. ``` | Prop | Type | Default | | |---|---|---|---| | `value` / `defaultValue` | `string[]` | | Open items, controlled or uncontrolled. | | `onValueChange` | `(value: string[]) => void` | | | | `multiple` | `boolean` | `false` | Allow several open at once. | | `disabled` | `boolean` | | | | `AccordionItem` | `value`, `title`, `children`, `headingLevel?` (default 3), `disabled?` | | | **Motion signature:** the height springs open with no overshoot, the content fades in as the height lands, and the chevron turns on the same spring; closing fades the content first and is quicker than opening. ## Example `components/eased/accordion/accordion-demo.tsx` ```tsx "use client"; import { DemoFrame } from "../lib/demo-frame"; import { Accordion, AccordionItem } from "./accordion"; export function AccordionDemo() { return (

On the day your trial ends, then on the same date every month. If that date doesn’t exist in a month, such as the 31st, we charge on the last day instead. Yes. Upgrades apply at once and you pay the difference for the days left in the cycle. Downgrades take effect at your next renewal, so you keep what you paid for. Within 14 days of any charge, in full, no questions asked.

Go to Settings → Billing → Tax details and enter it with its country prefix, for example DE123456789. We check it against VIES before saving.

New invoices show it from then on. To reissue a past invoice with the number on it, open the invoice and choose Regenerate.

); } ``` --- # Attachment Chip > A chat attachment: images as a thumbnail that sharpens from a blur once decoded, files as a typed chip. Upload progress is a ring that springs between reports; a failure shakes once and offers Retry; removing one lets its neighbours slide into the gap. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/attachment - Installs: motion - Registry: https://eased.dev/r/attachment.json ## Install ```bash npx shadcn add https://eased.dev/r/attachment.json ``` An image thumbnail or a typed file chip, with upload progress, errors and remove. **Motion signature:** the thumbnail sharpens from a 4px blur once it decodes, progress is a ring that springs between reports (spinning when the size is unknown), a failure shakes once, and a removed chip shrinks away while its neighbours slide into the gap. ```tsx const { attachments, add, remove, retry } = useAttachments({ upload }); ``` ## Props - `AttachmentChip`: `attachment`, `onRemove?`, `onRetry?`, `variant` (`auto` | `file`). - `AttachmentList`: `attachments`, `onRemove?`, `onRetry?`, `label` ("Attachments"), `children`. - `ProgressRing`: `value?` (0–1), `name`. The remove button shows on hover and focus with a mouse, and always on touch. Each chip is a labelled group that reads out its name and upload state. ## Example `components/eased/attachment/attachment-demo.tsx` ```tsx "use client"; import { useEffect, useRef } from "react"; import { useAttachments, type Attachment, type UploadFn } from "../_primitives/chat-core/chat-core"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { AttachmentList } from "./attachment-chip"; /** A small landscape as an SVG data URL, so the demo ships no image files. */ export function scene(sky: string, sun: string, far: string, near: string, sunX = 64) { const svg = ``; return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`; } /** * A pretend upload: progress in uneven steps over ~1.5–2.5s (like a real network), failing * when the name contains "fail". Respects the abort signal. */ export const fakeUpload: UploadFn = (file, { onProgress, signal }) => new Promise((resolve, reject) => { let p = 0; const id = window.setInterval(() => { p = Math.min(1, p + 0.06 + Math.random() * 0.14); onProgress(p); if (/fail/i.test(file.name) && p > 0.55) { clearInterval(id); reject(new Error("Connection lost")); } else if (p >= 1) { clearInterval(id); resolve({ url: URL.createObjectURL(file) }); } }, 220); signal.addEventListener("abort", () => clearInterval(id)); }); const SEED: Attachment[] = [ { id: "a1", name: "harbour-dawn.png", kind: "image", mediaType: "image/png", previewUrl: scene("#f6d6b8", "#f08a5d", "#7a8fb0", "#3e4f6e", 70), status: "done" }, { id: "a2", name: "Q3 board deck.pdf", kind: "file", mediaType: "application/pdf", size: 4_812_000, status: "done" }, { id: "a3", name: "dunes.jpg", kind: "image", mediaType: "image/jpeg", previewUrl: scene("#fbe7c6", "#e9a15a", "#d8a46c", "#a7683a", 40), status: "uploading", progress: 0.42 }, { id: "a4", name: "churn-by-cohort.csv", kind: "file", mediaType: "text/csv", size: 218_400, status: "error", error: "Connection lost" }, ]; /** Uploads in flight, a finished deck, a failed CSV with Retry; add your own files to watch the ring. */ export function AttachmentChipDemo() { const input = useRef(null); const { attachments, add, remove, retry, update } = useAttachments({ upload: fakeUpload, defaultValue: SEED, maxSize: 20_000_000 }); const timers = useRef([]); // Seeded chips have no File, so drive their "upload" here. const drive = (id: string, from: number) => { update(id, { status: "uploading", progress: from, error: undefined }); let p = from; const t = window.setInterval(() => { p = Math.min(1, p + 0.08 + Math.random() * 0.1); update(id, p >= 1 ? { status: "done", progress: 1 } : { progress: p }); if (p >= 1) clearInterval(t); }, 260); timers.current.push(t); }; useEffect(() => { const start = window.setTimeout(() => drive("a3", 0.42), 900); const list = timers.current; return () => { clearTimeout(start); list.forEach(clearInterval); }; // eslint-disable-next-line react-hooks/exhaustive-deps }, []); return (

Finance team

(attachments.find((a) => a.id === id)?.file ? retry(id) : drive(id, 0.05))} />

Up to 20 MB per file

{ add(Array.from(e.target.files ?? [])); e.target.value = ""; }} />

); } ``` --- # Avatar > Avatar and AvatarGroup on Base UI Avatar: images fade in from a 4px blur once loaded so initials never flash; overlapping stacks with a cut-out ring spread apart on hover; the overflow count rolls. - Tier: Free (MIT) - Interaction: Hover - Page: https://eased.dev/components/avatar - Installs: @base-ui/react - Registry: https://eased.dev/r/avatar.json ## Install ```bash npx shadcn add https://eased.dev/r/avatar.json ``` Avatar and AvatarGroup on Base UI Avatar. ```tsx import { Avatar, AvatarGroup } from "@/components/eased/avatar/avatar"; {people.map((p) => )} ``` ## Props `Avatar`: `name` (accessible name and initials), `src`, `initials` (override), `size` (`xs` 20 · `sm` 24 · `md` 32 · `lg` 40 · `xl` 48, default `md`), `shape` (`circle` or `square`; 48px squares get a superellipse), `className`. `AvatarGroup`: `children` (Avatars), `max` (the rest collapse into a rolling `+N`), `size`, `shape`, `aria-label`, `cutout` (the separating ring's colour; match the surface behind, default `var(--eased-surface)`), `className`. **Motion signature:** an image fades in from a 4px blur once it has loaded, and the initials wait 400ms (`duration.fallback`) before showing, so a quick image never flashes the fallback (a failed or missing image shows initials at once); a stack spreads apart on the snappy spring under a fine pointer or keyboard focus, and its overflow count rolls. ## Example `components/eased/avatar/avatar-demo.tsx` ```tsx "use client"; import { AnimatePresence, motion } from "motion/react"; import { useEffect, useRef, useState } from "react"; import { Badge } from "../badge/badge"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { useScrollFades } from "../lib/dom"; import { enter, reducedFade, smooth, useSafeReducedMotion } from "../lib/motion"; import { Avatar, AvatarGroup } from "./avatar"; /** Generated portraits (soft gradient blobs), inlined so the demo needs no image host. */ function portrait(a: string, b: string, c: string, x: number, y: number) { const svg = ``; return `data:image/svg+xml,${encodeURIComponent(svg)}`; } type Member = { id: string; name: string; email: string; role: "Owner" | "Admin" | "Member"; src?: string }; const TEAM: Member[] = [ { id: "1", name: "Maya Okafor", email: "maya@northwind.studio", role: "Owner", src: portrait("#f4c9a8", "#e0795b", "#f7e3b5", 18, 20) }, { id: "2", name: "Jonas Weber", email: "jonas@northwind.studio", role: "Admin", src: portrait("#b9d3e8", "#4e7fb3", "#d7ecd9", 44, 16) }, { id: "3", name: "Priya Raman", email: "priya@northwind.studio", role: "Member" }, { id: "4", name: "Leo Martín", email: "leo@northwind.studio", role: "Member", src: portrait("#d9cff1", "#8a6fd1", "#f2c6dc", 24, 40) }, // A broken image: the initials take over at once instead of waiting out the delay. { id: "5", name: "Hana Sato", email: "hana@northwind.studio", role: "Member", src: "data:image/png;base64,broken" }, ]; const INVITES: Member[] = [ { id: "6", name: "Amara Diallo", email: "amara@northwind.studio", role: "Member", src: portrait("#cfe7d2", "#3f9466", "#f1e6a6", 40, 38) }, { id: "7", name: "Tomás Rivera", email: "tomas@northwind.studio", role: "Member" }, { id: "8", name: "Elif Kaya", email: "elif@northwind.studio", role: "Member", src: portrait("#f6d0d6", "#d0566e", "#fbe2c4", 20, 44) }, { id: "9", name: "Noah Fischer", email: "noah@northwind.studio", role: "Member", src: portrait("#d2dcf0", "#5368b5", "#c9eef0", 46, 28) }, ]; const ROLE_TONE = { Owner: "brand", Admin: "info", Member: "neutral" } as const; export function AvatarDemo() { const reduced = useSafeReducedMotion(); const [members, setMembers] = useState(TEAM); const next = INVITES.find((m) => !members.some((x) => x.id === m.id)); const list = useRef(null); useScrollFades(list); // Bring a new member into view once it has been added (skipped on mount). const count = useRef(members.length); useEffect(() => { if (members.length > count.current) { list.current?.scrollTo({ top: list.current.scrollHeight, behavior: reduced ? "auto" : "smooth" }); } count.current = members.length; }, [members.length, reduced]); return ( next && setMembers((m) => [...m, next])}> Invite } >

{members.map((m) => ( ))}

Hover the stack

{members.map((m) => (

{m.name}

{m.email}

{m.role} ))}

); } ``` --- # Cells kit > Table cells that make rows look finished: avatar with name, status badge, number with a rolling value and coloured delta, a progress meter that fills on view, a self-updating relative time, and a mono ID with a copy button. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/cells - Installs: motion - Registry: https://eased.dev/r/cells.json ## Install ```bash npx shadcn add https://eased.dev/r/cells.json ``` Cells that make table rows look finished. They work in any table and size themselves to an Eased table's density. ```tsx import { DeltaCell, IdCell, PersonCell, ProgressCell, RelativeTimeCell, StatusCell } from "@/components/eased/cells/cells"; Active ``` | Cell | Props | | |---|---|---| | `PersonCell` | `name`, `src?`, `detail?` | 24px avatar when dense, 32px when comfortable. The second line shows only in comfortable rows. | | `StatusCell` | `children`, `tone?`, `live?` | A Badge with a dot. `live` makes the dot breathe. | | `DeltaCell` | `value`, `delta` (a fraction), `format?`, `locale?`, `invert?` | The value rolls. The delta sits in a fixed track: a rise is success and a fall is warning (`invert` swaps them). | | `ProgressCell` | `value`, `max?`, `label?`, `locale?` | A `role="meter"` bar with fixed widths for the track and the label. | | `RelativeTimeCell` | `date`, `now?`, `locale?` | `` with the full date as its title. It stays current on a 30s clock and shows the short date before hydration. | | `IdCell` | `id`, `copyable?` | Mono with slashed zeros. The copy button keeps its space while hidden. | Put numeric cells in `align: "end"` columns. **Motion signature:** values roll in the direction they change, and deltas change colour with them. Meters fill from empty the first time they scroll into view, then glide on the smooth spring and turn green at 100%. A live status dot breathes and pauses off-screen. The copy icon swaps to a tick with Eased's text-swap blur. Under reduced motion, everything is set at once. ## Example `components/eased/cells/cells-demo.tsx` ```tsx "use client"; import { useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { easedColumns, Table } from "../table/table"; import { DeltaCell, PersonCell, ProgressCell, RelativeTimeCell, StatusCell } from "./cells"; type Account = { id: string; name: string; mrr: number; delta: number; onboarding: number; state: "Active" | "Trial" | "Paused"; seen: number; }; const NOW = Date.UTC(2026, 9, 18, 12); const M = 60_000; const START: Account[] = [ { id: "a1", name: "Northwind", mrr: 12_480, delta: 0.124, onboarding: 100, state: "Active", seen: NOW - 4 * M }, { id: "a2", name: "Lumen Labs", mrr: 8_920, delta: -0.038, onboarding: 82, state: "Active", seen: NOW - 52 * M }, { id: "a3", name: "Fieldnote", mrr: 4_310, delta: 0.061, onboarding: 64, state: "Trial", seen: NOW - 3 * 60 * M }, { id: "a4", name: "Ostrava Co.", mrr: 3_750, delta: 0, onboarding: 45, state: "Active", seen: NOW - 26 * 60 * M }, { id: "a5", name: "Pine & Pixel", mrr: 2_180, delta: -0.117, onboarding: 30, state: "Paused", seen: NOW - 5 * 24 * 60 * M }, { id: "a6", name: "Halcyon", mrr: 1_640, delta: 0.219, onboarding: 18, state: "Trial", seen: NOW - 9 * M }, { id: "a7", name: "Brightwell", mrr: 1_205, delta: 0.042, onboarding: 72, state: "Active", seen: NOW - 7 * 60 * M }, { id: "a8", name: "Marlow Studio", mrr: 980, delta: -0.021, onboarding: 55, state: "Active", seen: NOW - 2 * 24 * 60 * M }, { id: "a9", name: "Quill", mrr: 640, delta: 0.087, onboarding: 9, state: "Trial", seen: NOW - 31 * M }, ]; const TONE = { Active: "success", Trial: "info", Paused: "neutral" } as const; const usd = { style: "currency", currency: "USD", maximumFractionDigits: 0 } as const; const col = easedColumns(); const columns = col.columns([ col.accessor("name", { header: "Account", cell: (c) => , meta: { emphasis: true, grow: true } }), col.accessor("mrr", { header: "MRR", cell: (c) => , meta: { align: "end" }, }), col.accessor("onboarding", { header: "Onboarding", cell: (c) => , meta: { className: "@max-[24rem]:hidden" }, }), col.accessor("state", { header: "Status", cell: (c) => ( {c.getValue()} ), meta: { className: "@max-[36rem]:hidden" }, }), col.accessor("seen", { header: "Last seen", cell: (c) => , meta: { align: "end", className: "@max-[36rem]:hidden" }, }), ]); // A month passes: revenue drifts, onboarding moves forward. const advance = (rows: Account[]) => rows.map((r) => { const delta = Math.round((Math.random() * 0.3 - 0.12) * 1000) / 1000; return { ...r, mrr: Math.max(200, Math.round(r.mrr * (1 + delta))), delta, onboarding: Math.min(100, r.onboarding + Math.round(Math.random() * 25)), }; }); export function CellsDemo() { const [rows, setRows] = useState(START); return ( setRows(advance)}> Next month } > r.id} className="min-h-0 flex-1" /> ); } ``` --- # Badge > A status or count chip. Counts roll their digits; a count-only badge pops in above zero and leaves when cleared; a live dot breathes slowly and stops under reduced motion. - Tier: Free (MIT) - Interaction: Press - Page: https://eased.dev/components/badge - Installs: motion - Registry: https://eased.dev/r/badge.json ## Install ```bash npx shadcn add https://eased.dev/r/badge.json ``` A status or count chip with rolling counts and a breathing live dot. ```tsx import { Badge } from "@/components/eased/badge/badge"; Operational {/* leaves at 0 */} Queued ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `children` | `ReactNode` | | The label. Optional for count-only badges. | | `count` | `number` | | Rolls when it changes. | | `max` | `number` | `99` | Above this shows `max+`. | | `showZero` | `boolean` | `false` | Keep a count-only badge at 0; otherwise it leaves (keep it mounted). | | `dot` | `boolean \| "live"` | `false` | Status dot; `"live"` breathes every 2.4s. | | `tone` | `neutral \| brand \| success \| warning \| danger \| info` | `neutral` | Subtle fill with state text. | | `size` | `"sm" \| "md"` | `"sm"` | 20px or 24px tall. | | `locale` | `Intl.LocalesArgument` | | Count formatting. | | `aria-label` | `string` | | Spoken instead of the visible text. | **Motion signature:** counts roll their digits in the direction of change; a count-only badge pops in from 0.85 on the snappy spring and leaves faster than it came; the live dot's halo breathes slowly, pauses off-screen and stops under reduced motion. ## Example `components/eased/badge/badge-demo.tsx` ```tsx "use client"; import { useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { rowGridRow } from "../lib/layout"; import { Badge } from "./badge"; type Folder = { id: string; name: string; count: number; icon: string }; const START: Folder[] = [ { id: "inbox", name: "Inbox", count: 12, icon: "M3 9.5h3.5l1 2h3l1-2H15M3 9.5V13a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V9.5M3 9.5 5 4h8l2 5.5" }, { id: "mentions", name: "Mentions", count: 3, icon: "M11.5 9a2.5 2.5 0 1 1-5 0 2.5 2.5 0 0 1 5 0Zm0 0v1a1.75 1.75 0 0 0 3.5 0V9a6 6 0 1 0-2.4 4.8" }, { id: "review", name: "Needs review", count: 98, icon: "M4 9.5 7.5 13 14 5" }, { id: "drafts", name: "Drafts", count: 0, icon: "M11.5 4.5l2 2L7 13H5v-2l6.5-6.5Z" }, ]; export function BadgeDemo() { const [folders, setFolders] = useState(START); const [selected, setSelected] = useState("inbox"); // Opening a folder reads it, and its badge leaves. const open = (id: string) => { setSelected(id); setFolders((f) => f.map((x) => (x.id === id ? { ...x, count: 0 } : x))); }; // New mail lands in the folders you're not looking at; "Needs review" crosses 99 → 99+. const deliver = () => setFolders((f) => f.map((x) => x.id === selected || x.id === "drafts" ? x : { ...x, count: x.count + 1 + Math.floor(Math.random() * 3) }, ), ); return ( Receive mail } >

Services

{/* The badge track is as wide as the widest badge, so every badge starts on one x. */}

Operational} /> Degraded} /> Beta} /> Queued} />

); } function Service({ name, badge }: { name: string; badge: React.ReactNode }) { return (

{name} {badge}

); } ``` --- # Button > A Base UI button whose press scale depends on its width, whose label swaps with y + blur while the width springs, and whose loading spinner overlays the label so the width never changes. Popover triggers never scale. - Tier: Free (MIT) - Interaction: Press - Page: https://eased.dev/components/button - Installs: @base-ui/react, motion - Registry: https://eased.dev/r/button.json ## Install ```bash npx shadcn add https://eased.dev/r/button.json ``` A button on Base UI's Button whose press scale follows its width, whose label swaps with y + blur while the width springs, and whose loading state keeps its width. ## When to use - Any action on the page: save, send, open, delete. One `primary` per region marks the main one. - Labels that change after the action ("Save" → "Saved"): the swap and the width spring are built in. - Async work: `loading` overlays Eased's Spinner without moving anything around it. - Square icon actions in toolbars and rows, with `size="icon-sm"` and an `aria-label`. ## When not to use - Navigation to another page: use a link (``), or pass `render={}` so it still looks like a button. - Choosing one of a few options: use [Segmented](/components/segmented) or [Toggle Group](/components/toggle-group). - An action that needs a second chance: pair the button with [Undo Pill](/components/undo-pill) instead of a confirm step, unless it cannot be reversed. ## Usage ```tsx save-button.tsx import { Button } from "@/components/eased/button/button"; export function SaveButton({ pending, saved, onSave }: { pending: boolean; saved: boolean; onSave: () => void }) { return ( ); } ``` ## Examples ### Icon button Square, with a 44×44 tap target around the 32px visual. Name it with `aria-label`. ```tsx ``` ### Popover trigger Triggers that anchor a popup never scale, so the popup's origin stays put. Passing the button as `render` is enough: `aria-haspopup` turns the scale off. ```tsx }>Share ``` ### Swapping element labels String labels swap on their own. When `children` are elements, give each state a `swapKey`. ```tsx ``` ## API reference | Prop | Type | Default | Description | |---|---|---|---| | `variant` | `"primary" \| "secondary" \| "ghost" \| "danger" \| "danger-solid"` | `"secondary"` | One `primary` per region. `danger` is outlined; `danger-solid` is for the final confirm step only. | | `size` | `"sm" \| "md" \| "lg" \| "icon-sm" \| "icon" \| "icon-lg"` | `"md"` | 32, 36 and 40px; icon sizes are square. | | `loading` | `boolean` | `false` | Eased's `Spinner` over a transparent label: width kept, focus kept, clicks ignored, `aria-busy`. | | `swapKey` | `string \| number` | | Swap the label when `children` are elements. String labels swap on their own. | | `scaleOnPress` | `boolean` | `true` | Off automatically for `aria-haspopup` triggers. | | `hitArea` | `boolean` | `true` for `icon-sm` | 44×44 tap target around a small button. Pass `false` when the button sits beside other targets (toolbars, rows), so the extended area does not cover them. | Plus every Base UI Button prop (`disabled`, `focusableWhenDisabled`, `render` …). `type` defaults to `"button"`. ## Keyboard | Key | Action | |---|---| | `Enter` / `Space` | Activates the button. Ignored while `loading`. | | `Tab` | Moves focus to the button, including while `loading`, and while disabled with `focusableWhenDisabled`. | ## Accessibility - A native `

} >

Billed to

Northwind Traders

Due 24 Oct

{money.format(total)}

{l.item} {l.qty} {money.format(l.amount)}

{announce} ); } ``` --- # Composer > A chat composer that grows on a spring, opens an attachments row with Auto Height, and morphs its Send arrow into a Stop square while a reply streams. Enter sends, Shift+Enter breaks the line, Escape stops; files can be picked, dropped or pasted. Wires straight into AI SDK useChat. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/composer - Installs: motion - Registry: https://eased.dev/r/composer.json ## Install ```bash npx shadcn add https://eased.dev/r/composer.json ``` A chat input: auto-growing textarea, attachments row and one Send/Stop button. **Motion signature:** the box grows on a smooth height spring, the attachments row opens with Auto Height while chips pop in from 0.9, and the Send arrow morphs point for point into a Stop square while a reply streams, without changing size. ```tsx import { useChat } from "@ai-sdk/react"; import { fromUseChat } from "@/components/eased/_primitives/chat-core/chat-core"; import { Composer } from "@/components/eased/composer/composer"; const { composer } = fromUseChat(useChat()); ``` ## Props - `value` / `defaultValue` / `onValueChange`: the text. - `onSubmit({ text, attachments, files })`: `files` are AI SDK `file` parts. Uncontrolled text and attachments clear after a send. - `status` (`useChat().status`), `onStop`: Stop button and Escape while busy. - Attachments: uncontrolled with `upload`, `accept`, `maxSize`, `maxFiles`; or controlled with `attachments`, `onAttach`, `onRemoveAttachment`, `onRetryAttachment`. `allowAttachments={false}` turns them off. Pick, drop or paste. - `placeholder`, `minRows` (1), `maxRows` (6, then it scrolls with soft edges), `disabled`, `autoFocus`, `submitOn` (`enter` | `mod-enter`), `onEditLast` (↑ when empty, ⌘↑). - Pro hooks: `onTrigger` (`/` and `@`), `triggerChars`, `interceptKey` (claim ↑ ↓ Enter Esc for an open menu), `header`, `toolbar`, `actions` (model picker), `ref` → `{ focus, textarea, openFilePicker }`. Keyboard: Enter sends, Shift+Enter breaks the line, Escape stops a reply, Tab reaches Add files and Send. ## Example `components/eased/composer/composer-demo.tsx` ```tsx "use client"; import { AnimatePresence, motion } from "motion/react"; import { useEffect, useRef, useState } from "react"; import { groupMessages, useStickToBottom, type ChatMessage, type ChatStatus, type ComposerSubmission } from "../_primitives/chat-core/chat-core"; import { fakeUpload } from "../attachment/attachment-demo"; import { DemoFrame } from "../lib/demo-frame"; import { enter, exitFast, reducedFade, snappy, useSafeReducedMotion } from "../lib/motion"; import { pressWide } from "../lib/press"; import { CopyAction, Message } from "../message/message"; import { Composer } from "./composer"; const SEED: ChatMessage[] = [ { id: "m1", role: "user", parts: [{ type: "text", text: "Can you turn last week’s churn numbers into three bullet points for the Monday sync?" }] }, { id: "m2", role: "assistant", parts: [ { type: "text", text: "Sure. Churn fell to 2.1% (from 2.6%), driven by the annual-plan nudge. Most cancellations still come from teams under 5 seats. Win-back emails recovered 38 accounts, about $4.2k MRR.", }, ], }, { id: "m3", role: "user", parts: [{ type: "text", text: "And trial to paid?" }] }, { id: "m4", role: "assistant", parts: [{ type: "text", text: "Up to 18.4% from 16.9%, mostly from the new onboarding checklist." }] }, ]; const REPLIES = [ "Here’s a tighter version for the slide: churn is down half a point to 2.1%; small teams remain the risk; win-back paid for itself twice over. Want me to add the cohort chart?", "Good question. The drop is mostly January cohorts renewing annually. If you exclude them, monthly churn is flat at 2.5%, so I’d frame the nudge as promising rather than proven.", "Done. I’ve also flagged the three accounts over 50 seats that downgraded, since those carry most of the revenue risk this quarter.", ]; const replyFor = (s: ComposerSubmission, n: number) => s.attachments.length ? `I’ve read ${s.attachments.map((a) => a.name).join(" and ")}. The headline is the same: churn is trending down, but the small-team segment needs its own onboarding. I can draft that plan next.` : REPLIES[n % REPLIES.length]; /** A working mini chat: type and press Enter, attach or drop a file, press Stop mid-reply, scroll up while it streams. */ export function ComposerDemo() { const reduced = useSafeReducedMotion(); const [messages, setMessages] = useState(SEED); const [status, setStatus] = useState("ready"); const count = useRef(0); const stream = useRef<{ timer?: number; stop: boolean }>({ stop: false }); const { scrollRef, contentRef, isAtBottom, scrollToBottom } = useStickToBottom(); useEffect(() => () => clearTimeout(stream.current.timer), []); const send = (s: ComposerSubmission) => { const id = `u${Date.now()}`; const reply = replyFor(s, count.current++); setMessages((m) => [...m, { id, role: "user", metadata: { live: true }, parts: [...s.files, ...(s.text ? [{ type: "text" as const, text: s.text }] : [])] }]); scrollToBottom(); setStatus("submitted"); stream.current = { stop: false }; const words = reply.split(/(?<=\s)/); const aid = `a${Date.now()}`; let i = 0; const tick = () => { if (stream.current.stop) return; if (i === 0) { setStatus("streaming"); setMessages((m) => [...m, { id: aid, role: "assistant", metadata: { live: true }, parts: [{ type: "text", text: "", state: "streaming" }] }]); } // Bursty, like a real stream: one to four words per chunk. i = Math.min(words.length, i + 1 + Math.floor(Math.random() * 4)); const text = words.slice(0, i).join(""); const done = i >= words.length; setMessages((m) => m.map((x) => (x.id === aid ? { ...x, parts: [{ type: "text", text, state: done ? "done" : "streaming" }] } : x))); if (done) setStatus("ready"); else stream.current.timer = window.setTimeout(tick, 60 + Math.random() * 90); }; stream.current.timer = window.setTimeout(tick, 700); }; const stop = () => { stream.current.stop = true; clearTimeout(stream.current.timer); setStatus("ready"); setMessages((m) => m.map((x) => (x.parts[0]?.type === "text" && "state" in x.parts[0] && x.parts[0].state === "streaming" ? { ...x, parts: [{ ...x.parts[0], state: "done" }] } : x))); }; const groups = groupMessages(messages); const last = messages[messages.length - 1]; return (

{groups.map((g) => (

{g.messages.map(({ message, position }) => { return ( p.type === "text" && "text" in p && p.text) ? : undefined} /> ); })}

))}

{!isAtBottom && ( scrollToBottom()} className={`absolute bottom-full left-1/2 z-10 mb-3 inline-flex h-7 -translate-x-1/2 cursor-pointer items-center gap-1.5 rounded-pill border border-line bg-surface-raised px-3 text-ui-xs font-medium text-text shadow-floating ${pressWide}`} initial={reduced ? { opacity: 0 } : { opacity: 0, y: 8, scale: 0.96 }} animate={{ opacity: 1, y: 0, scale: 1, transition: reduced ? reducedFade : { ...snappy, opacity: enter } }} exit={{ opacity: 0, y: reduced ? 0 : 4, transition: reduced ? reducedFade : exitFast }} > {status === "ready" ? "Jump to latest" : "New reply"} )}

); } ``` --- # Field > Label, control and one message line on Base UI Field. The description and the error share the line and swap with y + blur; inside Base UI's Form, submitting focuses the first invalid field. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/field - Registry: https://eased.dev/r/field.json ## Install ```bash npx shadcn add https://eased.dev/r/field.json ``` Label, control and one message line, on Base UI's Field. ```tsx import { Form } from "@base-ui/react/form"; import { Field } from "@/components/eased/field/field"; import { Input } from "@/components/eased/input/input"; ``` | Prop | Type | Default | | |---|---|---|---| | `label` | `ReactNode` | | Tied to the control for you. | | `description` | `ReactNode` | | Helper text; the error takes its place while invalid. | | `error` | `ReactNode` | | An error you control. Setting it marks the field invalid. | | `children` | `ReactNode` | | One control: Input, Textarea, Search Field or any Base UI control. | Plus every Base UI `Field.Root` prop: `name`, `validate`, `validationMode`, `invalid`, `disabled` … Also exports `FieldRoot`, `FieldLabel` and `FieldMessage` for custom layouts. **Motion signature:** the description and the error share one line and swap with y + blur while the line's height springs; inside Base UI's Form, submitting moves focus to the first invalid field, which shakes once. ## Example `components/eased/field/field-demo.tsx` ```tsx "use client"; import { Form } from "@base-ui/react/form"; import { useEffect, useRef, useState } from "react"; import { Button } from "../button/button"; import { Input } from "../input/input"; import { DemoFrame } from "../lib/demo-frame"; import { Field } from "./field"; const TAKEN = "maya@northwind.com"; const validateEmail = (value: unknown) => { const v = String(value ?? "").trim(); if (!v) return "Enter your work email."; if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return "That doesn’t look like an email address."; if (/@(gmail|yahoo|hotmail|outlook)\./i.test(v)) return "Use your work email, not a personal one."; return null; }; const validatePassword = (value: unknown) => { const v = String(value ?? ""); if (!v) return "Choose a password."; if (v.length < 8) return `Add ${8 - v.length} more character${8 - v.length === 1 ? "" : "s"}.`; return null; }; export function FieldDemo() { const [errors, setErrors] = useState>({}); const [state, setState] = useState<"idle" | "loading" | "done">("idle"); const timer = useRef(0); useEffect(() => () => clearTimeout(timer.current), []); const submit = (values: Record) => { setState("loading"); timer.current = window.setTimeout(() => { // A server reply: Base UI's Form routes it to the field and focuses it. if (String(values.email).trim().toLowerCase() === TAKEN) { setErrors({ email: "An account with this email already exists." }); setState("idle"); return; } setState("done"); }, 900); }; return ( errors.email && setErrors({})} >

Already have an account?{" "} Sign in

{state === "done" ? "Account created" : ""} ); } ``` --- # Input > A Base UI text input whose focus is the border alone. An error shakes it once, 6px, then the field's message opens with a height spring. Leading and trailing addons. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/input - Installs: @base-ui/react - Registry: https://eased.dev/r/input.json ## Install ```bash npx shadcn add https://eased.dev/r/input.json ``` A text input on Base UI's Input. ```tsx import { Input } from "@/components/eased/input/input"; ``` | Prop | Type | Default | | |---|---|---|---| | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 32, 36 or 40px. | | `start`, `end` | `ReactNode` | | Leading and trailing addons (icon, prefix, unit, button). | | `invalid` | `boolean` | | For use outside a Field; inside one, the field's validity drives it. | | `className` | `string` | | The bordered shell. | | `controlClassName` | `string` | | The ``. | Plus every Base UI Input prop (`value`, `defaultValue`, `onValueChange`, `type` …). Text is 16px on touch screens so iOS never zooms on focus. **Motion signature:** focus firms the border one step and a soft glow grows around it; an error does one 6px horizontal shake, then the message opens with a height spring. ## Example `components/eased/input/input-demo.tsx` ```tsx "use client"; import { useState } from "react"; import { Field } from "../field/field"; import { DemoFrame } from "../lib/demo-frame"; import { Input } from "./input"; const RESERVED = ["admin", "api", "app", "eased", "www"]; const validateSlug = (value: unknown) => { const v = String(value ?? ""); if (!v) return "Pick a URL for your workspace."; if (/[^a-z0-9-]/.test(v)) return "Use lowercase letters, numbers and hyphens."; if (v.length < 3) return "Use at least 3 characters."; if (RESERVED.includes(v)) return `“${v}” is reserved. Try another.`; return null; }; export function InputDemo() { const [name, setName] = useState("Northwind Traders"); const [slug, setSlug] = useState("northwind"); return (

eased.dev/} spellCheck={false} autoCapitalize="off" /> } />

); } ``` --- # Kbd > A keycap that presses down when the real key does: the face drops 1px onto its base and springs back on release. Glyphs are announced by name; useKeysHeld lights up whatever a chord belongs to. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/kbd - Registry: https://eased.dev/r/kbd.json ## Install ```bash npx shadcn add https://eased.dev/r/kbd.json ``` A keycap that presses when the real key does. ```tsx import { Kbd, useKeysHeld } from "@/components/eased/kbd/kbd"; / const held = useKeysHeld(["⌘", "K"]); // light up the row a shortcut belongs to ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `children` | `string` | | One key: `"K"`, `"⌘"`, `"Esc"`, `"↑"`… | | `keys` | `string[]` | | A chord, one cap per key. | | `listen` | `boolean` | `true` | Press the cap while the real key is held. | | `pressed` | `boolean` | | Force the pressed look (tutorials, replays). | | `size` | `"sm" \| "md"` | `"sm"` | 20px or 24px caps. | Glyphs map to keys (⌘ Meta, ⌥ Alt, ⇧ Shift, ⌃ Control, ↵ Enter, ⎋/Esc, ⌫, ⇥, arrows; letters and digits by physical key, so ⌥K still matches K) and are announced by name ("Command K"). One shared window listener serves every cap; letting go of ⌘ or leaving the window clears them all, because macOS drops key-ups while ⌘ is held. **Motion signature:** the face drops 1px onto its base and darkens in 100ms when the key goes down, then springs back on the snappy spring when it comes up; reduced motion keeps only the colour change. ## Example `components/eased/kbd/kbd-demo.tsx` ```tsx "use client"; import { DemoFrame } from "../lib/demo-frame"; import { modKey, useIsMac } from "../lib/platform"; import { Kbd, useKeysHeld } from "./kbd"; type Shortcut = { action: string; keys: string[]; then?: string[] }; const shortcuts = (mac: boolean): { group: string; items: Shortcut[] }[] => [ { group: "General", items: [ { action: "Open command menu", keys: [modKey(mac), "K"] }, { action: "Search", keys: ["/"] }, { action: "Show shortcuts", keys: ["⇧", "?"] }, ], }, { group: "Issues", items: [ { action: "New issue", keys: ["C"] }, { action: "Move up", keys: [mac ? "⌥" : "Alt", "↑"] }, { action: "Go to inbox", keys: ["G"], then: ["I"] }, { action: "Close panel", keys: ["Esc"] }, ], }, ]; export function KbdDemo() { const mac = useIsMac(); return ( {shortcuts(mac).map(({ group, items }) => ( {group} {items.map((s) => ( ))} ))} ); } /** The row lights up while its whole chord is held, the way a shortcuts overlay confirms a match. */ function Row({ shortcut }: { shortcut: Shortcut }) { const held = useKeysHeld(shortcut.keys); return ( {shortcut.action} {shortcut.then && ( <> then )} ); } ``` --- # Message > A chat message: the user's in a sunken bubble on the right, the assistant's flush on the left. Consecutive bubbles from one author merge, their touching corners tightening as the next one lands. Renders AI SDK UIMessage text and file parts. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/message - Installs: motion - Registry: https://eased.dev/r/message.json ## Install ```bash npx shadcn add https://eased.dev/r/message.json ``` A chat message for AI SDK `UIMessage`s: user messages in a sunken bubble, assistant messages flush. **Motion signature:** consecutive bubbles from one author merge, and the corners where they meet tighten from 16px to 6px as the next one lands, so the run reflows instead of snapping. New messages rise 8px once. ```tsx {groupMessages(messages).map((g) => ( {g.messages.map(({ message, position }) => ( } /> ))} ))} ``` ## Props - `message?`, `role?` (defaults to the message's), `position` (`single` | `first` | `middle` | `last`), `children` (replaces the text, e.g. a streaming Response), `actions`, `actionsVisible` (`hover` keeps its space while hidden | `always`), `animateIn`. - `MessageAction`: `label`, `onClick`, `pressed`, `children` (a 16px icon). - `CopyAction`: `message` or `text`; morphs to a check for 1.6s. The free bubble. The Pro thread (streaming markdown, branches, edit in place, the lift out of the composer) arrives with Conversation and Response. ## Example `components/eased/message/message-demo.tsx` ```tsx "use client"; import { useState } from "react"; import { groupMessages, useStickToBottom, type ChatMessage } from "../_primitives/chat-core/chat-core"; import { scene } from "../attachment/attachment-demo"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { CopyAction, Message } from "./message"; const SEED: ChatMessage[] = [ { id: "1", role: "user", parts: [ { type: "file", mediaType: "image/png", filename: "kitchen-before.png", url: scene("#e9e4dc", "#c9a27e", "#b7c4b0", "#6f7f6a", 30) }, { type: "text", text: "This is the kitchen now. What would make it feel bigger without moving walls?" }, ], }, { id: "2", role: "assistant", parts: [ { type: "text", text: "Three things do most of the work: paint the upper cabinets the wall colour so they recede, swap the pendant for a flush light, and run one floor finish through to the dining area.", }, ], }, ]; const FOLLOW_UPS = ["Love the cabinet idea.", "What colour would you pick?", "Something warm, not stark white."]; /** Send the follow-ups one by one: each new bubble tightens the corners where it meets the last. */ export function MessageDemo() { const [messages, setMessages] = useState(SEED); const [step, setStep] = useState(0); const { scrollRef, contentRef, scrollToBottom } = useStickToBottom(); const left = FOLLOW_UPS.length - step; const send = () => { if (step >= FOLLOW_UPS.length) { setStep(0); setMessages(SEED); return; } const text = FOLLOW_UPS[step]; setStep(step + 1); setMessages((m) => [...m, { id: `f${step}-${Date.now()}`, role: "user", metadata: { live: true }, parts: [{ type: "text", text }] }]); scrollToBottom(); }; return ( {groupMessages(messages).map((g) => ( {g.messages.map(({ message, position }) => { return ( : undefined} actionsVisible="always" /> ); })} ))} {left > 0 ? `“${FOLLOW_UPS[step]}”` : "All follow-ups sent"} ); } ``` --- # Number Roll > Tabular digits that roll in the direction of change: a 9 → 0 carry rolls forward, a value that changes mid-roll redirects, new places fade in while the rest slide over. Intl formatting, locale-aware separators. - Tier: Free (MIT) - Interaction: Select - Page: https://eased.dev/components/number-roll - Registry: https://eased.dev/r/number-roll.json ## Install ```bash npx shadcn add https://eased.dev/r/number-roll.json ``` Tabular digits that roll in the direction of change, with Intl formatting and locale-aware separators. ```tsx import { NumberRoll } from "@/components/eased/number-roll/number-roll"; ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `value` | `number` | | The number. | | `locale` | `Intl.LocalesArgument` | runtime | Grouping, decimal mark and numerals. `locales` is a deprecated alias, kept for one release. | | `format` | `Intl.NumberFormatOptions` | | Currency, percent, compact, units, fixed decimals. | | `formatter` | `(value) => string` | | Format it yourself; digits roll, everything else swaps. | | `direction` | `"auto" \| "up" \| "down"` | `"auto"` | Auto rolls up as the number's size grows, down as it shrinks. | | `animated` | `boolean` | `true` | False shows changes at once, e.g. while dragging. | | `transition` | Motion transition | `snappy` | The spring each digit rides. | | `aria-hidden` | `boolean` | `false` | Hide it when something else announces the value. | **Motion signature:** every digit is a ten-face cylinder on a snappy spring that turns only in the direction of change, so carries roll forward, interrupted rolls redirect from where they are, and new places fade in from the side they roll from while the rest slide over. ## Example `components/eased/number-roll/number-roll-demo.tsx` ```tsx "use client"; import { useInView } from "motion/react"; import { useEffect, useRef, useState } from "react"; import { Badge } from "../badge/badge"; import { DemoFrame } from "../lib/demo-frame"; import { Segmented } from "../segmented/segmented"; import { NumberRoll } from "./number-roll"; type Range = "7d" | "30d" | "90d"; const RANGES = [ { value: "7d", label: "7d" }, { value: "30d", label: "30d" }, { value: "90d", label: "90d" }, ] as const; const DATA: Record = { "7d": { revenue: 12_480.5, delta: 0.084, orders: 214, refunds: 0.012, returning: 0.36 }, "30d": { revenue: 48_210.4, delta: -0.031, orders: 869, refunds: 0.018, returning: 0.41 }, "90d": { revenue: 139_775.9, delta: 0.127, orders: 2_406, refunds: 0.015, returning: 0.44 }, }; const LOCALES = [ { value: "en-US", label: "en-US" }, { value: "de-DE", label: "de-DE" }, { value: "hi-IN", label: "hi-IN" }, ] as const; type Locale = (typeof LOCALES)[number]["value"]; export function NumberRollDemo() { const [range, setRange] = useState("30d"); const [locale, setLocale] = useState("en-US"); const [live, setLive] = useState({ revenue: 0, orders: 0 }); const root = useRef(null); const inView = useInView(root); // A new order every couple of seconds while the card is on screen: the total and the // order count tick up, and carries roll forward. The format switch shows grouping change // (hi-IN groups lakhs: 1,39,775.90) and digits slide to their new places. useEffect(() => { if (!inView) return; const t = window.setInterval(() => { setLive((l) => ({ revenue: l.revenue + 18 + Math.round(Math.random() * 6400) / 100, orders: l.orders + 1 })); }, 2200); return () => window.clearInterval(t); }, [inView]); const d = DATA[range]; const revenue = d.revenue + live.revenue; const orders = d.orders + live.orders; const currency = { style: "currency", currency: "USD" } as const; return ( { setRange(r); setLive({ revenue: 0, orders: 0 }); }} /> } > Live Net sales, all channels = 0 ? "success" : "danger"}> {d.delta >= 0 ? "↑" : "↓"} vs. previous {range === "7d" ? "week" : range === "30d" ? "month" : "quarter"} Format ); } function Row({ label, children }: { label: string; children: React.ReactNode }) { return ( {label} {children} ); } ``` --- # Popover > A panel that opens from its trigger's transform-origin with a 5px directional offset, closes at half the distance in 150ms, and reverses mid-flight. Its trigger presses by colour, never by scale. - Tier: Free (MIT) - Interaction: Press - Page: https://eased.dev/components/popover - Installs: @base-ui/react - Registry: https://eased.dev/r/popover.json ## Install ```bash npx shadcn add https://eased.dev/r/popover.json ``` A non-modal panel anchored to a button, built on Base UI Popover and the Eased floating layer. **Motion signature:** opens from the anchor's transform-origin with a 5px offset toward it, closes at half the distance in 150ms, and because both are transitions a close during the open reverses mid-flight; the trigger presses by colour and never scales. ## Usage ```tsx import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverFooter, PopoverClose, } from "@/components/eased/popover/popover"; Share Share “Q3 launch plan” People you invite can view and comment. … }>Done ``` Focus moves to the first field on open and back to the trigger on close; Escape and an outside click dismiss. ## Props - `Popover`: Base UI `Popover.Root` (`open`, `defaultOpen`, `onOpenChange`, `modal`, `actionsRef` …). - `PopoverTrigger`: an Eased `Button` (which never scales as a trigger). Base UI `Popover.Trigger` props plus the Button's `variant` (`"secondary"`) and `size` (`"sm"`; `"icon-sm"` for a square icon trigger). Pass `render` for a custom trigger and style it with `floatingTrigger`. `openOnHover`, `delay`, `closeDelay` make it a hover-intent trigger. - `PopoverContent`: `side` (`"bottom"`), `align` (`"center"`), `sideOffset` (6), `alignOffset`, `motion` (override distance, scale, fade, exit), `initialFocus`, `finalFocus`, `container`, `zIndex` (50), `className` (default width `w-80`, capped at the viewport). - `PopoverTitle`, `PopoverDescription`: label and describe the dialog. - `PopoverFooter`: a full-bleed sunken action bar; it sets `--pad: 8px`, so buttons using `radius-nested` get a concentric 7px corner. - `PopoverClose`: Base UI `Popover.Close`. ## Example `components/eased/popover/popover-demo.tsx` ```tsx "use client"; import { useEffect, useId, useRef, useState, type FormEvent } from "react"; import { Avatar } from "../avatar/avatar"; import { Button } from "../button/button"; import { Input } from "../input/input"; import { DemoFrame } from "../lib/demo-frame"; import { rowGrid, rowGridRow } from "../lib/layout"; import { TextSwap } from "../text-swap/text-swap"; import { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverFooter, PopoverTitle, PopoverTrigger } from "./popover"; type Person = { name: string; email: string; role: "Owner" | "Can edit" | "Can view" }; const PEOPLE: Person[] = [ { name: "Mara Lindqvist", email: "mara@northwind.io", role: "Owner" }, { name: "Devon Okafor", email: "devon@northwind.io", role: "Can edit" }, ]; export function PopoverDemo() { const [people, setPeople] = useState(PEOPLE); return ( Share {/* --col is the Invite button's width and the role column's, so the roles start under it. */} setPeople((list) => [...list, p])} /> } > Goals Ship offline sync to every workspace, cut first-load time under 1.2s and open the API to the waitlist. {[ ["Offline sync GA", "Aug 14"], ["Perf budget in CI", "Aug 28"], ["Public API beta", "Sep 18"], ].map(([label, date]) => ( {label} {date} ))} ); } function SharePanel({ people, onInvite }: { people: Person[]; onInvite: (p: Person) => void }) { const id = useId(); const [email, setEmail] = useState(""); const [copied, setCopied] = useState(false); const timer = useRef(0); useEffect(() => () => window.clearTimeout(timer.current), []); const valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.trim()); const invite = (e: FormEvent) => { e.preventDefault(); if (!valid) return; const address = email.trim().toLowerCase(); const name = address.split("@")[0].replace(/[._-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()); onInvite({ name, email: address, role: "Can view" }); setEmail(""); }; const copy = () => { void navigator.clipboard?.writeText("https://northwind.io/d/q3-launch").catch(() => {}); setCopied(true); window.clearTimeout(timer.current); timer.current = window.setTimeout(() => setCopied(false), 1600); }; return ( <> Share “Q3 launch plan” People you invite can view and comment. Email address {people.map((p) => ( {p.name} {p.email} {p.role} ))} }>Done ); } function ShareIcon() { return ( ); } function LinkIcon() { return ( ); } ``` --- # Progress > A progress bar on Base UI Progress: the bar rides a spring and its value rolls; an unknown length sweeps with an accelerate–decelerate curve and hands over to the bar when a value arrives. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/progress - Installs: motion, @base-ui/react - Registry: https://eased.dev/r/progress.json ## Install ```bash npx shadcn add https://eased.dev/r/progress.json ``` A progress bar on Base UI Progress, with a rolling value and an indeterminate sweep. ```tsx import { Progress } from "@/components/eased/progress/progress"; ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `value` | `number \| null` | | `null` is indeterminate. | | `min` / `max` | `number` | `0` / `100` | | | `label` | `ReactNode` | | Visible label and accessible name (else `aria-label`). | | `showValue` | `boolean` | `true` | The rolling value; hidden while indeterminate. | | `format` / `locale` | Intl options | percent | Formats the shown and spoken value. | | `getAriaValueText` | `(formatted, value) => string` | | Spoken value. | | `size` | `"sm" \| "md"` | `"md"` | 4px or 6px track. | | `successOnComplete` | `boolean` | `true` | Bar turns success-green at `max`. | **Motion signature:** the bar rides the smooth spring (no overshoot, so it never reads past the real value) as a full-width bar sliding in from the left, so its rounded end never squashes; the value rolls; an unknown length sweeps a 40% segment on an accelerate–decelerate curve and hands over to the bar the moment a value arrives. Reduced motion: the bar jumps and the sweep becomes a static tint. ## Example `components/eased/progress/progress-demo.tsx` ```tsx "use client"; import { useInView } from "motion/react"; import { useEffect, useRef, useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { NumberRoll } from "../number-roll/number-roll"; import { Spinner } from "../spinner/spinner"; import { TextSwap } from "../text-swap/text-swap"; import { Progress } from "./progress"; type Upload = { id: string; name: string; size: number; speed: number }; const FILES: Upload[] = [ { id: "a", name: "Launch film final.mov", size: 842, speed: 46 }, { id: "b", name: "Press kit.zip", size: 128, speed: 31 }, { id: "c", name: "Hero stills.fig", size: 64, speed: 22 }, { id: "d", name: "Captions (EN, DE, JA).srt", size: 3, speed: 1.4 }, ]; /** Megabytes sent per file, then ticks of server-side processing once the bytes are in. */ type State = Record; const fresh = (): State => Object.fromEntries(FILES.map((f) => [f.id, { sent: 0, processing: 0 }])); const PROCESSING_TICKS = 6; export function ProgressDemo() { const [state, setState] = useState(fresh); const root = useRef(null); const inView = useInView(root); // Uneven chunks, the way a real upload reports, then a short indeterminate processing step. useEffect(() => { if (!inView) return; const t = window.setInterval(() => { setState((s) => { const next = { ...s }; for (const f of FILES) { const cur = s[f.id]; if (cur.sent < f.size) { next[f.id] = { ...cur, sent: Math.min(f.size, cur.sent + f.speed * (0.4 + Math.random())) }; } else if (cur.processing < PROCESSING_TICKS) { next[f.id] = { ...cur, processing: cur.processing + 1 }; } } return next; }); }, 450); return () => window.clearInterval(t); }, [inView]); const done = FILES.filter((f) => state[f.id].processing >= PROCESSING_TICKS).length; const busy = done < FILES.length; return ( {busy && } {done} of {FILES.length} } actions={ } > {FILES.map((f) => { const { sent, processing } = state[f.id]; const phase = sent < f.size ? "uploading" : processing < PROCESSING_TICKS ? "processing" : "done"; return ( (phase === "processing" ? "Processing" : `${formatted} uploaded`)} /> / {f.size} MB ); })} ); } function Status({ phase }: { phase: "uploading" | "processing" | "done" }) { const text = phase === "uploading" ? "Uploading…" : phase === "processing" ? "Processing…" : "Uploaded"; return ( {phase === "done" && ( )} {text} ); } ``` --- # Progressive Blur > A blur that ramps from 0 to 20px over 80px toward an edge, from stacked masked backdrop layers, for headers, bottom bars and composers. Optionally scroll-linked so it appears only once content is underneath. - Tier: Free (MIT) - Interaction: Scroll - Page: https://eased.dev/components/progressive-blur - Installs: motion - Registry: https://eased.dev/r/progressive-blur.json ## Install ```bash npx shadcn add https://eased.dev/r/progressive-blur.json ``` A blur that ramps from nothing to 20px over 80px toward an edge, for sticky headers, bottom bars and composers. **Motion signature:** six stacked backdrop layers, each double the last one's radius and masked to an overlapping band, so content softens gradually instead of meeting a hard-edged frosted strip; linked to a scroller, the blur fades in only once content is actually underneath it. ## Usage ```tsx import { ProgressiveBlur } from "@/components/eased/progressive-blur/progressive-blur"; const scroller = useRef(null); … … ``` Place it as a sibling over the scroller (not inside it, or it scrolls away), in a positioned parent; it pins itself to `side`. Render your header or bar after it. It never takes pointer events. Do not put `opacity`, `filter` or `mask` on it or its ancestors up to the scroller: any of them becomes the backdrop root and the blur goes blank. Strength is applied as each layer's own opacity for that reason. ## Props | Prop | Default | | |---|---|---| | `side` | `"top"` | `"top"`, `"bottom"`, `"left"` or `"right"`: the edge the blur is strongest at. | | `size` | 80 | Ramp length in px. | | `maxBlur` | 20 | Blur at the edge, px. | | `layers` | 6 | More is smoother and costs more GPU. | | `tint` | true | A surface-coloured scrim under the ramp, so text over busy content stays legible. | | `scrollRef` | | A ref or the scroller element. Scroll-linked strength: top/left fade in as you scroll away from the start, bottom/right while there is more below. Rows added later re-measure at once. | | `scrollRange` | `size` | Scroll distance to full strength, px. | | `strength` | 1 | 0–1 number or MotionValue, when there is no `scrollRef`. | | `className` | | Position and stacking (e.g. `z-10`). | Strength follows scroll position directly, with no animation, so reduced motion needs no separate branch. Browsers without `backdrop-filter` show the tint only. ## Example `components/eased/progressive-blur/progressive-blur-demo.tsx` ```tsx "use client"; import { useRef, useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { ScrollArea } from "../scroll-area/scroll-area"; import { Segmented } from "../segmented/segmented"; import { ProgressiveBlur } from "./progressive-blur"; type Mode = "ramp" | "flat" | "off"; const MODES = [ { value: "ramp", label: "Ramp" }, { value: "flat", label: "Flat" }, { value: "off", label: "Off" }, ] as const; const TONES = [ "bg-info-subtle fill-info-text", "bg-warning-subtle fill-warning-text", "bg-success-subtle fill-success-text", "bg-danger-subtle fill-danger-text", "bg-surface-active fill-text-secondary", "bg-brand-subtle fill-brand-text", ]; const ALBUMS = [ ["Low Tide", "Mara Lindqvist"], ["Paper Suns", "The Overpass"], ["Northern Rooms", "Iso Kaito"], ["Glasshouse", "Dela Cruz"], ["Small Hours", "June Arden"], ["Field Notes", "Halden Rowe"], ["Static Bloom", "Neon Parish"], ["Slow Light", "Halden Rowe"], ["Copper Coast", "Mara Lindqvist"], ["Weather Report", "Sol Ferreira"], ["After Image", "Iso Kaito"], ["Open Water", "The Overpass"], ]; /** A music library whose header and mini player blur the covers scrolling under them. */ export function ProgressiveBlurDemo() { const [mode, setMode] = useState("ramp"); const scroller = useRef(null); return ( } > {ALBUMS.map(([title, artist], i) => ( {title} {artist} ))} {mode === "ramp" && } {mode === "ramp" && } {mode === "flat" && ( <> )} Library {ALBUMS.length} albums ); } function NowPlaying() { const [playing, setPlaying] = useState(false); return ( // Inset to the grid's 16px content line; the cover and button nest inside its 10px corner. Low Tide Mara Lindqvist ); } function Cover({ tone, shape, flat = false }: { tone: string; shape: number; flat?: boolean }) { return ( ); } ``` --- # Radio Group > Radios whose dot scales out from the centre on a snappy spring, and radio cards whose selected border travels between cards. Base UI RadioGroup behaviour. - Tier: Free (MIT) - Interaction: Select - Page: https://eased.dev/components/radio-group - Installs: @base-ui/react - Registry: https://eased.dev/r/radio-group.json ## Install ```bash npx shadcn add https://eased.dev/r/radio-group.json ``` Radios and radio cards on Base UI's RadioGroup: one tab stop, arrow keys move and select, form submission through `name`, Field validation. ```tsx import { Radio, RadioCard, RadioCards, RadioGroup } from "@/components/eased/radio-group/radio-group"; Leave it at the door Hand it to me ``` | Component | Props | | |---|---|---| | `RadioGroup` / `RadioCards` | `value`, `defaultValue`, `onValueChange`, `name`, `disabled`, `required`, `aria-label`/`aria-labelledby` | `RadioCards` adds `columns: 1 \| 2 \| 3` (container-query responsive). | | `Radio` | `value`, `children` (label), `description?`, `disabled?` | The whole row is the hit target. | | `RadioCard` | `value`, `title`, `description?`, `meta?`, `icon?`, `disabled?` | | Explain a disabled option in its description rather than a tooltip. **Motion signature:** the dot scales out from the centre on the snappy spring and leaves faster than it came; on cards, the selected border is one highlight that travels between cards (rows share a height, so it only ever translates). ## Example `components/eased/radio-group/radio-group-demo.tsx` ```tsx "use client"; import { useId, useState } from "react"; import { DemoFrame } from "../lib/demo-frame"; import { Radio, RadioCard, RadioCards, RadioGroup } from "./radio-group"; type Speed = "standard" | "express" | "overnight"; type DropOff = "door" | "hand"; const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }); const SPEEDS: { value: Speed; title: string; description: string; price: number }[] = [ { value: "standard", title: "Standard", description: "Arrives Fri, Oct 23 – Tue, Oct 27", price: 0 }, { value: "express", title: "Express", description: "Arrives Wed, Oct 21", price: 12 }, { value: "overnight", title: "Overnight", description: "Tomorrow by 10am if you order in 2h 14m", price: 29 }, ]; export function RadioGroupDemo() { const dropOffLabel = useId(); const [speed, setSpeed] = useState("express"); const [dropOff, setDropOff] = useState("door"); const handOff = speed !== "standard"; const chooseSpeed = (next: Speed) => { setSpeed(next); if (next === "standard") setDropOff("door"); }; const price = SPEEDS.find((s) => s.value === speed)!.price; return ( {SPEEDS.map((s) => ( ))} Drop-off aria-labelledby={dropOffLabel} name="drop-off" value={dropOff} onValueChange={setDropOff}> Leave it at the door Hand it to me ); } ``` --- # Scroll Area > A native scroller with a thin themed overlay scrollbar that thickens under the pointer, and edge fades that appear only when there is more to scroll. Base UI Scroll Area underneath. - Tier: Free (MIT) - Interaction: Scroll - Page: https://eased.dev/components/scroll-area - Installs: @base-ui/react - Registry: https://eased.dev/r/scroll-area.json ## Install ```bash npx shadcn add https://eased.dev/r/scroll-area.json ``` A native scroller with a thin themed overlay scrollbar and edge fades, built on Base UI Scroll Area. **Motion signature:** the scrollbar is a 4px pill that appears while you scroll or hover and thickens to 6px under the pointer, and each edge feathers in only as far as there is content past it, so a list at rest at its top shows no top fade at all. ## Usage ```tsx import { ScrollArea } from "@/components/eased/scroll-area/scroll-area"; … … ``` Size the root with `className` (`h-72`, `max-h-80`, or `flex-1 min-h-0` in a column). Put padding in `contentClassName` so it scrolls with the content. Scrolling, thumb dragging and keyboard scrolling are Base UI's: the viewport is a tab stop while it overflows, arrow keys and Page Up/Down scroll it, and the focus ring is drawn inset on the root (`-outline-offset-2`, a deliberate exception to the usual 2px outset ring, R65) because the faded, clipped viewport would mask an outline outside it. ## Props | Prop | Default | | |---|---|---| | `orientation` | `"vertical"` | `"horizontal"` or `"both"`; the other axis is locked. | | `fade` | 20 | Edge feather in px; 0 turns it off. Each feather grows with the distance left to scroll (`scrollFadeMask` from the scroll-fade primitive). | | `className` | | Root classes; size it here. | | `contentClassName` | | Content wrapper classes. | | `viewportRef` | | The scrolling element, for `scrollTo` or a scroll-linked Progressive Blur. | | `aria-label` / `aria-labelledby` | | Names the region; give one whenever it scrolls. | | `style` | | Root style. | Reduced motion: the bar and pill change without transitions. ## Example `components/eased/scroll-area/scroll-area-demo.tsx` ```tsx "use client"; import { useRef, useState } from "react"; import { Avatar } from "../avatar/avatar"; import { DemoFrame } from "../lib/demo-frame"; import { ToggleGroup, ToggleGroupItem } from "../toggle-group/toggle-group"; import { ScrollArea } from "./scroll-area"; type Kind = "merged" | "review" | "comment" | "deploy" | "issue"; const EVENTS: { who: string; kind: Kind; what: string; ago: string }[] = [ { who: "Maya Chen", kind: "merged", what: "Fix sheet scroll handoff on iOS", ago: "2m" }, { who: "Jonas Weber", kind: "review", what: "Requested changes on #482", ago: "9m" }, { who: "Priya Raman", kind: "deploy", what: "Shipped v0.14.2 to production", ago: "21m" }, { who: "Leo Martins", kind: "comment", what: "“Thumb should thicken on hover”", ago: "34m" }, { who: "Ana Sousa", kind: "issue", what: "Opened #491 Fades flicker in Safari 17", ago: "1h" }, { who: "Maya Chen", kind: "review", what: "Approved #479 Progressive blur", ago: "1h" }, { who: "Kenji Sato", kind: "merged", what: "Add superellipse fallback path", ago: "2h" }, { who: "Jonas Weber", kind: "comment", what: "“Can we pin the corner exponent?”", ago: "2h" }, { who: "Priya Raman", kind: "deploy", what: "Shipped v0.14.1 to staging", ago: "3h" }, { who: "Ana Sousa", kind: "merged", what: "Tokenise scrollbar colours", ago: "4h" }, { who: "Leo Martins", kind: "issue", what: "Opened #488 Rubber-band too loose", ago: "5h" }, { who: "Kenji Sato", kind: "review", what: "Commented on #476", ago: "6h" }, { who: "Maya Chen", kind: "deploy", what: "Rolled back v0.14.0", ago: "8h" }, { who: "Jonas Weber", kind: "merged", what: "Velocity projection for pagers", ago: "Yesterday" }, { who: "Ana Sousa", kind: "comment", what: "“Feather looks right at 20px”", ago: "Yesterday" }, { who: "Priya Raman", kind: "issue", what: "Closed #470 Focus ring clipped", ago: "Mon" }, ]; const FILTERS: { value: "all" | Kind; label: string }[] = [ { value: "all", label: "All" }, { value: "merged", label: "Merged" }, { value: "review", label: "Reviews" }, { value: "comment", label: "Comments" }, { value: "deploy", label: "Deploys" }, { value: "issue", label: "Issues" }, ]; /** An activity feed: a horizontal filter row and a vertical list, both in Scroll Areas. */ export function ScrollAreaDemo() { const [filter, setFilter] = useState<"all" | Kind>("all"); const list = useRef(null); const rows = filter === "all" ? EVENTS : EVENTS.filter((e) => e.kind === filter); return ( { if (!v[0]) return; // one filter is always on setFilter(v[0] as "all" | Kind); list.current?.scrollTo({ top: 0 }); }} aria-label="Filter activity" variant="chips" className="w-max px-4 py-2.5" > {FILTERS.map((f) => ( {f.label} ))} {rows.map((e, i) => ( {e.who} {e.what} {e.kind} {e.ago} ))} ); } ``` --- # Segmented > A single-choice segmented control whose thumb glides to the selection on a spring. Base UI RadioGroup behaviour, concentric thumb, labels that never change weight. - Tier: Free (MIT) - Interaction: Slide - Page: https://eased.dev/components/segmented - Installs: @base-ui/react - Registry: https://eased.dev/r/segmented.json ## Install ```bash npx shadcn add https://eased.dev/r/segmented.json ``` A single-choice control with a gliding thumb, on Base UI's RadioGroup: one tab stop, arrow keys move the selection, Home/End, and form submission through `name`. ## When to use - Picking one of two to five short options that change a value: a date range, a view density, a billing period. - Filters and settings where every option should stay visible, so people see what they are not choosing. - Inside forms: it submits its value through `name` like a radio group. ## When not to use - Swapping regions of content: use [Tabs](/components/tabs), which wire up panels. - More than five options, or long labels: use a [Radio Group](/components/radio-group) or a select. - Options that can be on at the same time: use [Toggle Group](/components/toggle-group). ## Usage ```tsx date-range.tsx import { useState } from "react"; import { Segmented } from "@/components/eased/segmented/segmented"; export function DateRange() { const [range, setRange] = useState("30d"); return ( ); } ``` ## Examples ### Icon-only segments Each icon-only segment needs its own `aria-label`. ```tsx , "aria-label": "List" }, { value: "grid", icon: , "aria-label": "Grid" }, ]} defaultValue="list" /> ``` ### Full width in a form `fullWidth` splits the container equally; `size="md"` matches 36px form fields. ```tsx ``` ## API reference | Prop | Type | Default | Description | |---|---|---|---| | `options` | `{ value, label?, icon?, "aria-label"?, disabled? }[]` | | Icon-only segments need an `aria-label`. | | `value` / `defaultValue` | `V` | first option | Controlled or uncontrolled. | | `onValueChange` | `(value: V) => void` | | | | `size` | `"sm" \| "md"` | `"sm"` | 32px for dense UI and headers, 36px for forms and settings. | | `fullWidth` | `boolean` | `false` | Fill the container and split it equally. | | `name` | `string` | | Submits the value with a form. | | `disabled` | `boolean` | | | | `aria-label` / `aria-labelledby` | `string` | | Name the group. | ## Keyboard | Key | Action | |---|---| | `Tab` | Moves focus to the selected segment; the whole control is one tab stop. | | `←` / `→` | Selects the previous or next segment. | | `Home` / `End` | Selects the first or last segment. | ## Accessibility - Base UI renders a `radiogroup` of `radio`s, so screen readers announce the group's name, the option and its position. - Name the group with `aria-label`, or `aria-labelledby` pointing at a visible label. - Labels only darken when selected; they never change weight, so the segments keep their width. ## Motion The thumb glides to the new segment on the snappy spring and stays concentric with the track: its radius is the track's minus the padding and border. Reduced motion jumps the thumb to the new segment with no glide. ## Notes for AI Use Segmented for a short, visible single choice that sets a value, controlled with `value` and `onValueChange` or submitted with `name`. Keep labels to one or two words; switch to `size="md"` beside form fields. Do not use it to switch views (that is Tabs), and do not add your own thumb, indicator or selected-weight styles: the component draws the thumb and keeps it concentric. ## Related - [Tabs](/components/tabs): switches a region of content. - [Toggle Group](/components/toggle-group): several options on at once. - [Radio Group](/components/radio-group): longer lists and labels. ## Example `components/eased/segmented/segmented-demo.tsx` ```tsx "use client"; import { motion } from "motion/react"; import { useState } from "react"; import { Badge } from "../badge/badge"; import { DemoFrame } from "../lib/demo-frame"; import { smooth, useSafeReducedMotion } from "../lib/motion"; import { NumberRoll } from "../number-roll/number-roll"; import { TextSwap } from "../text-swap/text-swap"; import { Segmented } from "./segmented"; type Range = "24h" | "7d" | "30d" | "12m"; type Metric = "visitors" | "views"; const RANGES = [ { value: "24h", label: "24h" }, { value: "7d", label: "7 days" }, { value: "30d", label: "30 days" }, { value: "12m", label: "12 mo" }, ] as const; const METRICS = [ { value: "visitors", label: "Visitors" }, { value: "views", label: "Views" }, ] as const; // Twelve buckets per range, as a share of the range's busiest bucket. const DATA: Record = { "24h": { total: 3_842, delta: 0.081, bars: [18, 12, 9, 14, 38, 62, 81, 100, 92, 74, 55, 31], axis: ["00:00", "22:00"] }, "7d": { total: 26_190, delta: -0.034, bars: [72, 80, 77, 91, 100, 46, 39, 70, 84, 88, 95, 52], axis: ["Oct 6", "Oct 17"] }, "30d": { total: 118_604, delta: 0.124, bars: [41, 48, 52, 50, 61, 66, 63, 72, 79, 85, 93, 100], axis: ["Sep 18", "Oct 17"] }, "12m": { total: 1_204_330, delta: 0.468, bars: [22, 26, 31, 30, 38, 44, 52, 57, 63, 74, 88, 100], axis: ["Nov", "Oct"] }, }; const pct = new Intl.NumberFormat("en-US", { style: "percent", maximumFractionDigits: 1, signDisplay: "always" }); export function SegmentedDemo() { const reduced = useSafeReducedMotion(); const [range, setRange] = useState("7d"); const [metric, setMetric] = useState("visitors"); const data = DATA[range]; const scale = metric === "views" ? 2.7 : 1; const total = Math.round(data.total * scale); return ( } > {metric === "views" ? "Page views" : "Unique visitors"} {pct.format(data.delta)} {data.bars.map((value, i) => ( ))} {data.axis[0]} {data.axis[1]} ); } ``` --- # Shimmer Text > A soft band of light sweeps across a label while something is working. Every shimmer on the page shares one phase, status changes swap in without restarting the band, and turning it off fades the band out in place. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/shimmer-text - Installs: motion - Registry: https://eased.dev/r/shimmer-text.json ## Install ```bash npx shadcn add https://eased.dev/r/shimmer-text.json ``` A soft band of light sweeps across a label while something is working: "Searching 14 sources…". ```tsx import { ShimmerText } from "@/components/eased/shimmer-text/shimmer-text"; Searching 14 sources… {status} A paragraph that may wrap onto a second line… ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `children` | `ReactNode` | | The text. Loading labels end with `…`. | | `active` | `boolean` | `true` | Turning it off fades the band out where it is (300ms) instead of cutting it mid-sweep. | | `duration` | `number` | `2.4` | Seconds per cycle: the sweep takes the first 70%, then the band rests off the right edge. | | `swap` | `boolean` | on for strings | Route changes through Text Swap: the old status lifts and blurs out, the new one rises in, and the box springs to its width with a left-to-right reveal. Swapped text does not wrap; pass `false` for multi-line copy. | | `className` | `string` | `text-text-muted` | The text colour is the base the band sweeps over. Set `[--shimmer-highlight:…]` to change the band (default the `text` token). | | `style` | `CSSProperties` | | | The text stays real text for selection and screen readers; forced-colours mode draws it plain. **Motion signature:** one 5em band of light, the same width on a short label and a long one, crosses the text on a soft in-out curve every 2.4s; every shimmer on the page shares one phase, so a status that swaps mid-sweep carries the band on, and a finished one lets its band fade where it is. It pauses off-screen; under reduced motion it is plain text. ## Example `components/eased/shimmer-text/shimmer-text-demo.tsx` ```tsx "use client"; import { useEffect, useState } from "react"; import { NumberRoll } from "../_primitives/number-roll/number-roll"; import { useElapsed, useStatusCarousel } from "../_primitives/thinking-core/thinking-core"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { Spinner } from "../spinner/spinner"; import { ShimmerText } from "./shimmer-text"; const RESEARCH = [ "Searching 14 sources…", "Reading stripe.com/pricing…", "Comparing three pricing tiers…", "Checking the 2026 fee changes…", "Drafting the summary…", ]; const TASKS = [ { id: "read", todo: "Read checkout-form.tsx", busy: "Reading checkout-form.tsx…", label: "Read checkout-form.tsx", took: 0.4 }, { id: "edit", todo: "Edit the coupon field", busy: "Editing the coupon field…", label: "Edited the coupon field", took: 3.2 }, { id: "test", todo: "Run pnpm test", busy: "Running pnpm test…", label: "Ran pnpm test, 48 passed", took: 4.1 }, { id: "types", todo: "Type check", busy: "Running the type check…", label: "Type check passed", took: 2.7 }, { id: "pr", todo: "Open a pull request", busy: "Opening a pull request…", label: "Opened pull request #412", took: 1.3 }, ]; function Check() { return ( ); } function Queued() { return ( ); } /** The live seconds of the running task, rolling. */ function Live({ running }: { running: boolean }) { const s = useElapsed({ running }); return `${v}s`} />; } export function ShimmerTextDemo() { const [playing, setPlaying] = useState(true); const [active, setActive] = useState(1); const line = useStatusCarousel(RESEARCH, { paused: !playing, loop: true }); // One task finishes every 3.4s; after the last, the list starts over. useEffect(() => { if (!playing) return; const t = window.setTimeout(() => setActive((i) => (i + 1) % (TASKS.length + 1)), active === TASKS.length ? 2200 : 3400); return () => clearTimeout(t); }, [active, playing]); return ( setPlaying((p) => !p)} swapKey={playing ? "pause" : "play"}> {playing ? "Pause" : "Resume"} } > Research · pricing comparison {line} Fix the coupon field of {TASKS.length} {TASKS.map((task, i) => { const state = i < active ? "done" : i === active ? "active" : "queued"; return ( {state === "done" ? : state === "active" ? : } {state === "done" ? task.label : state === "active" ? task.busy : task.todo} {state === "done" ? `${task.took}s` : state === "active" ? : ""} ); })} ); } ``` --- # Skeleton > Loading placeholders with one page-wide shimmer: every skeleton shares a viewport-space highlight and one phase, so a single band sweeps across all of them. Wrap the real content and it hands off in place, fading in from a soft blur. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/skeleton - Installs: motion - Registry: https://eased.dev/r/skeleton.json ## Install ```bash npx shadcn add https://eased.dev/r/skeleton.json ``` Loading placeholders with one page-wide shimmer that hand off to the real content in place. ```tsx import { Skeleton, SkeletonText } from "@/components/eased/skeleton/skeleton"; {user?.name ?? "Maya Okafor"} {/* a plain block */} ``` ## Props `Skeleton`: `loading` (default `true`), `children` (the real content, laid out invisibly while loading so nothing shifts at the handoff; pass stand-in text of typical length while data is missing), `text` (cover the middle 60% of each line box so it reads as text), `block` (lay out as a block instead of inline), `className` (size and radius; default `rounded-control-xs`). `SkeletonText`: `lines` (default 3, the last one shorter), `loading`, `className`. **Limits of the shared sweep:** the band is painted in viewport space with `background-attachment: fixed`. iOS Safari ignores `fixed`, so there each skeleton sweeps its own box (still on the shared beat). Inside an ancestor that keeps a `transform` or `will-change` (an entrance animation that never resets), the background becomes relative to that element; end entrances with `transitionEnd: { transform: "none" }`. The loop does not pause off-screen: skeletons are short-lived, and under reduced motion it stops. **Motion signature:** every skeleton paints the same viewport-space highlight and shares one animation phase, so a single band sweeps across the whole page instead of each block flashing on its own beat; when loading ends the shimmer fades out as the content fades in from a 4px blur in the same box. Reduced motion: a still tint and an opacity handoff. ## Example `components/eased/skeleton/skeleton-demo.tsx` ```tsx "use client"; import { useEffect, useState } from "react"; import { Avatar } from "../avatar/avatar"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { Skeleton, SkeletonText } from "./skeleton"; type Activity = { id: string; who: string; did: string; what: string; when: string }; const FEED: Activity[] = [ { id: "1", who: "Maya Okafor", did: "merged", what: "Checkout: smart address paste", when: "4m" }, { id: "2", who: "Jonas Weber", did: "commented on", what: "Pricing page copy, v3", when: "18m" }, { id: "3", who: "Priya Raman", did: "opened", what: "Skeleton flashes on fast networks", when: "1h" }, { id: "4", who: "Leo Martín", did: "shipped", what: "Changelog 2.4", when: "3h" }, ]; /** Simulates a request: 1.4s on the first load and on every reload. */ function useFeed() { const [attempt, setAttempt] = useState(0); const [data, setData] = useState<{ attempt: number; items: Activity[] } | null>(null); useEffect(() => { const t = window.setTimeout(() => setData({ attempt, items: FEED }), 1400); return () => window.clearTimeout(t); }, [attempt]); const loading = data?.attempt !== attempt; return { items: loading || !data ? null : data.items, loading, reload: () => setAttempt((a) => a + 1) }; } export function SkeletonDemo() { const { items, loading, reload } = useFeed(); return ( Reload } > {/* While loading, every row renders with stand-in text the length of a real one, so the handoff never moves a pixel. */} {(items ?? FEED).map((a) => ( {a.who} {a.did} {a.when} {a.what} ))} Release notes {loading ? ( ) : ( Skeletons now share one shimmer across the page, and hand off to content in place. )} ); } ``` --- # Spinner > A quarter arc turning on a faint ring, the eased.dev status-badge mark. Spins on the compositor, pauses off-screen, freezes under reduced motion, announces itself unless visible text already does. - Tier: Free (MIT) - Interaction: Loading - Page: https://eased.dev/components/spinner - Installs: motion - Registry: https://eased.dev/r/spinner.json ## Install ```bash npx shadcn add https://eased.dev/r/spinner.json ``` A quarter arc turning on a faint ring: the eased.dev status-badge mark. ```tsx import { Spinner } from "@/components/eased/spinner/spinner"; {/* role="status", "Loading" */} ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `size` | `"sm" \| "md" \| "lg" \| number` | `"md"` | `sm` 14px beside 12px text, `md` 16px beside 13–14px, `lg` 20px beside 16px, or any diameter in px (the one numeric `size` in Eased). The ring scales with it. | | `label` | `string \| false` | `"Loading"` | Announced name; `false` when visible text already says it. | | `className` | `string` | `text-text-muted` | Colour comes from `currentColor`. | **Motion signature:** one linear turn every 900ms on the compositor, so it keeps spinning while the main thread is busy; it pauses while off-screen, and under reduced motion the arc freezes in place. Button and Search Field render this same spinner. ## Example `components/eased/spinner/spinner-demo.tsx` ```tsx "use client"; import { AnimatePresence, motion, useInView } from "motion/react"; import { useEffect, useRef, useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { instant, reducedFade, snappy, useSafeReducedMotion } from "../lib/motion"; import { TextSwap } from "../text-swap/text-swap"; import { Spinner } from "./spinner"; const STEPS = [ { name: "Install dependencies", ms: 1400 }, { name: "Type-check", ms: 1100 }, { name: "Build 214 pages", ms: 2200 }, { name: "Upload to edge", ms: 1300 }, { name: "Warm caches", ms: 900 }, ]; export function SpinnerDemo() { const reduced = useSafeReducedMotion(); const [current, setCurrent] = useState(0); const root = useRef(null); const inView = useInView(root); const finished = current >= STEPS.length; useEffect(() => { if (!inView || finished) return; const t = window.setTimeout(() => setCurrent((c) => c + 1), STEPS[current].ms); return () => window.clearTimeout(t); }, [current, finished, inView]); return ( setCurrent(0)} disabled={!finished} swapKey={finished ? "idle" : "busy"}> {finished ? ( "Redeploy" ) : ( <> Deploying… )} } > {STEPS.map((step, i) => { const state = i < current ? "done" : i === current ? "running" : "queued"; return ( {state === "running" ? ( ) : state === "done" ? ( ) : ( )} {step.name} {state === "done" ? `${(step.ms / 1000).toFixed(1)}s` : state === "running" ? "Running" : "Queued"} {state === "done" ? "Done" : state === "running" ? "In progress" : "Queued"} ); })} Sizes ); } ``` --- # Table > A premium hairline table on TanStack Table: half-pixel row rules, a quiet sentence-case header, numbers right-aligned on one edge, one emphasised cell per row, a sticky header, and dense or comfortable rows. - Tier: Free (MIT) - Interaction: Scroll - Page: https://eased.dev/components/table - Installs: @tanstack/react-table - Registry: https://eased.dev/r/table.json ## Install ```bash npx shadcn add https://eased.dev/r/table.json ``` A premium hairline table on TanStack Table. You bring TanStack column definitions; it brings half-pixel row rules, a quiet sentence-case header, numbers right-aligned on one edge, one emphasised cell per row and two densities. Fill the cells with the Cells kit. ```tsx import { easedColumns, Table } from "@/components/eased/table/table"; import { PersonCell, StatusCell } from "@/components/eased/cells/cells"; const col = easedColumns(); const columns = col.columns([ col.accessor("customer", { header: "Customer", cell: (c) => , meta: { emphasis: true, grow: true } }), col.accessor("status", { header: "Status", cell: (c) => {c.getValue()} }), col.accessor("amount", { header: "Amount", meta: { align: "end" } }), ]);

r.id} className="min-h-0 flex-1" /> ``` ## Props | Prop | Type | Default | | |---|---|---|---| | `data` | `T[]` | | Keep it stable (state or memo). | | `columns` | `EasedColumnDef[]` | | From `easedColumns()`, at module scope or memoised. | | `getRowId` | `(row, index) => string` | index | | | `label` | `string` | | Accessible name, as a hidden caption. | | `density` | `"dense" \| "comfortable"` | `"dense"` | 36px or 48px rows. | | `stickyHeader` | `boolean` | `true` | Give the table a bounded height for it to apply. | | `empty` | `ReactNode` | `"Nothing here yet"` | | Column `meta`: `align: "end"` for numbers, `emphasis` for the one strong cell, `grow` for the column that gives way when the table is narrow, `width`, and `className` (e.g. `@max-md:hidden`). **Motion signature:** it stays still on purpose. Hover lights a row with no transition, so moving the pointer or keyboard down a column never leaves a trail, and density changes snap instead of animating height. The cells carry the motion. ## Example `components/eased/table/table-demo.tsx` ```tsx "use client"; import { useState } from "react"; import { IdCell, PersonCell, RelativeTimeCell, StatusCell } from "../cells/cells"; import { DemoFrame } from "../lib/demo-frame"; import { Segmented } from "../segmented/segmented"; import { easedColumns, Table, type TableDensity } from "./table"; type Invoice = { id: string; customer: string; status: "Paid" | "Due" | "Overdue" | "Draft"; amount: number; issued: number; }; // Fixed instant so server and client render the same relative times. const NOW = Date.UTC(2026, 9, 18, 12); const H = 3_600_000; const INVOICES: Invoice[] = [ { id: "INV-2041", customer: "Maya Okafor", status: "Paid", amount: 4280, issued: NOW - 2 * H }, { id: "INV-2040", customer: "Jonas Weber", status: "Due", amount: 1150.5, issued: NOW - 9 * H }, { id: "INV-2039", customer: "Priya Raman", status: "Overdue", amount: 12_600, issued: NOW - 26 * H }, { id: "INV-2038", customer: "Leo Martín", status: "Paid", amount: 860, issued: NOW - 50 * H }, { id: "INV-2037", customer: "Amara Diallo", status: "Draft", amount: 2340, issued: NOW - 74 * H }, { id: "INV-2036", customer: "Hana Sato", status: "Paid", amount: 18_920, issued: NOW - 98 * H }, { id: "INV-2035", customer: "Tomás Herrera", status: "Due", amount: 640.25, issued: NOW - 6 * 24 * H }, { id: "INV-2034", customer: "Ingrid Larsen", status: "Paid", amount: 3075, issued: NOW - 8 * 24 * H }, { id: "INV-2033", customer: "Kwame Mensah", status: "Overdue", amount: 5400, issued: NOW - 12 * 24 * H }, { id: "INV-2032", customer: "Sofia Rossi", status: "Paid", amount: 990, issued: NOW - 15 * 24 * H }, { id: "INV-2031", customer: "Ethan Brooks", status: "Paid", amount: 7210, issued: NOW - 21 * 24 * H }, ]; const TONE = { Paid: "success", Due: "info", Overdue: "warning", Draft: "neutral" } as const; const money = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", minimumFractionDigits: 2 }); const col = easedColumns(); const columns = col.columns([ col.accessor("id", { header: "Invoice", cell: (c) => , meta: { className: "@max-[36rem]:hidden" }, }), col.accessor("customer", { header: "Customer", cell: (c) => , meta: { emphasis: true, grow: true } }), col.accessor("status", { header: "Status", cell: (c) => {c.getValue()} }), col.accessor("amount", { header: "Amount", cell: (c) => money.format(c.getValue()), meta: { align: "end" } }), col.accessor("issued", { header: "Issued", cell: (c) => , meta: { align: "end", className: "@max-[26rem]:hidden" }, }), ]); const Rows = ({ gap }: { gap: number }) => ( ); export function TableDemo() { const [density, setDensity] = useState("dense"); return ( , "aria-label": "Dense rows" }, { value: "comfortable", icon: , "aria-label": "Comfortable rows" }, ]} /> } >

r.id} density={density} className="min-h-0 flex-1" /> ); } ``` --- # Tabs > Tabs with a gliding indicator (underline or pill) and panels that cross-fade 6px in the direction of travel while their container's height springs. Base UI Tabs behaviour. - Tier: Free (MIT) - Interaction: Slide - Page: https://eased.dev/components/tabs - Installs: motion, @base-ui/react - Registry: https://eased.dev/r/tabs.json ## Install ```bash npx shadcn add https://eased.dev/r/tabs.json ``` Tabs on Base UI's Tabs (roving focus, arrow keys, Home/End, ARIA wiring), with a gliding indicator and panels that cross-fade in the direction of travel. ## When to use - Switching between views of one thing that share a place on the page: a project's Overview, Activity and Settings. - Section navigation inside a card or panel (`underline`), or a dense view switch in a toolbar (`pill`). - Routed sections, where each tab is a link: `render={}`. ## When not to use - Picking a value for a form or a filter, where nothing else on the page changes: use [Segmented](/components/segmented). - Content people need to compare side by side, or read in sequence: put it on the page, or use an [Accordion](/components/accordion). - More than about six tabs: the list scrolls, but a sidebar or a menu reads better. ## Usage ```tsx project-tabs.tsx import { Tab, Tabs, TabsList, TabsPanel, TabsPanels } from "@/components/eased/tabs/tabs"; export function ProjectTabs() { return ( Overview Activity … … ); } ``` ## Examples ### Pill A filled highlight behind the active tab, for toolbars and filters. ```tsx Preview Code ``` ### Routed tabs Each tab is a link; the indicator and the label render inside it. Control `value` from the pathname. ```tsx }>General }>Domains ``` ## API reference ### Tabs | Prop | Type | Default | Description | |---|---|---|---| | `value` / `defaultValue` | `string` | | Controlled or uncontrolled active tab. | | `onValueChange` | `(value) => void` | | | | `variant` | `"underline" \| "pill"` | `"underline"` | A 2px bar under the active tab, or a filled highlight behind it. | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical lays the list beside the panels. | Base UI Root props pass through. ### TabsList | Prop | Type | Default | Description | |---|---|---|---| | `aria-label` | `string` | | Names the tab list. | | `activateOnFocus` | `boolean` | `false` | Select a tab as soon as an arrow key focuses it. | | `loopFocus` | `boolean` | `true` | Arrow keys wrap from the last tab to the first. | Scrolls sideways with edge fades when the tabs outgrow it, so it never widens the page. ### Tab | Prop | Type | Default | Description | |---|---|---|---| | `value` | `string` | | Matches a `TabsPanel`. | | `icon` | `ReactNode` | | A 16px icon before the label. | | `disabled` | `boolean` | `false` | | | `render` | `ReactElement` | | Render as another element, e.g. a Next ``. | ### TabsPanels and TabsPanel `TabsPanels` takes a `className`; its height springs between panels of different lengths. `TabsPanel` takes `value` and `keepMounted`, which keeps a hidden panel's state (a half-filled form, a running demo). ## Keyboard | Key | Action | |---|---| | `Tab` | Moves focus into the list (to the active tab), then on to the panel. | | `←` / `→` | Moves focus between tabs (`↑` / `↓` when vertical). | | `Home` / `End` | Moves focus to the first or last tab. | | `Enter` / `Space` | Selects the focused tab, unless `activateOnFocus` already did. | ## Accessibility - Base UI wires `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected` and `aria-controls`; name the list with `aria-label`. - One tab stop for the whole list (roving focus), so keyboard users are not walked through every tab. - The active tab's label darkens but never changes weight, so nothing shifts as you move. ## Motion The indicator glides to the new tab on the snappy spring. The new panel enters from 6px on the side of the tab you came from while the old one leaves 3px the other way, faster than it arrived, and the container's height springs between them. Reduced motion keeps only an opacity cross-fade, and the indicator jumps instead of gliding. ## Notes for AI Use Tabs when the selection swaps a region of content, and give every `Tab` a matching `TabsPanel` inside `TabsPanels`. Pick `underline` for page and card sections and `pill` for toolbars; pass `keepMounted` to panels whose state must survive switching. Do not build the indicator or the panel animation yourself, and do not use Tabs as a form control: [Segmented](/components/segmented) submits a value with a form and has radio semantics. ## Related - [Segmented](/components/segmented): a single choice that changes a value, not a view. - [Toggle Group](/components/toggle-group): several on/off options in a row. - [Accordion](/components/accordion): sections people open in place. ## Example `components/eased/tabs/tabs-demo.tsx` ```tsx "use client"; import { Avatar } from "../avatar/avatar"; import { DemoFrame } from "../lib/demo-frame"; import { rowGrid, rowGridRow } from "../lib/layout"; import { Tab, Tabs, TabsList, TabsPanel, TabsPanels } from "./tabs"; const STATS = [ { label: "Deploys this week", value: "18", note: "4 more than last week" }, { label: "Success rate", value: "97.2%", note: "1 failed on Tuesday" }, { label: "Median build", value: "1m 42s", note: "12s slower" }, { label: "Edge requests", value: "2.4M", note: "8% up on last week" }, { label: "Bandwidth", value: "86 GB", note: "62% of the monthly limit" }, ]; const ACTIVITY: { who: string; what: string; target: string; when: string; prose?: boolean }[] = [ { who: "Maya Okafor", what: "deployed", target: "main@4f2a91c", when: "4m ago" }, { who: "Jonas Berg", what: "opened", target: "Checkout copy tweaks", when: "38m ago", prose: true }, { who: "Preview bot", what: "built", target: "feat/gift-cards", when: "1h ago" }, { who: "Lena Park", what: "rolled back", target: "main@a19e03d", when: "Yesterday" }, { who: "Maya Okafor", what: "added a domain", target: "shop.acme.co", when: "Mon" }, ]; const MEMBERS = [ { name: "Maya Okafor", email: "maya@acme.co", role: "Owner" }, { name: "Jonas Berg", email: "jonas@acme.co", role: "Developer" }, { name: "Lena Park", email: "lena@acme.co", role: "Developer" }, { name: "Tomás Rivera", email: "tomas@acme.co", role: "Developer" }, { name: "Aiko Tanaka", email: "aiko@acme.co", role: "Viewer" }, ]; const SETTINGS = [ ["Framework", "Next.js"], ["Root directory", "apps/web"], ["Build command", "pnpm build"], ["Output directory", ".next"], ["Node.js", "22.x"], ["Region", "Frankfurt (fra1)"], ] as const; export function TabsDemo() { return (

Overview Activity Members Settings

{s.label}: {s.value}

{a.who} {a.what} {a.target}
{a.when}

{m.name}

{m.email}

{m.role}

{/* A fixed key track, so every value starts on one x instead of hugging the right edge. */}

{k}: {v}

); } ``` --- # Text Swap > Change a label, status or short value with y + blur, and spring the width to fit, so neighbours glide instead of jumping. Direction-aware for counts and steps. - Tier: Free (MIT) - Interaction: Press - Page: https://eased.dev/components/text-swap - Registry: https://eased.dev/r/text-swap.json ## Install ```bash npx shadcn add https://eased.dev/r/text-swap.json ``` Change a label, status or short value without a jump. ```tsx import { TextSwap } from "@/components/eased/text-swap/text-swap";

{order.status}

``` | Prop | Type | Default | | |---|---|---|---| | `children` | `ReactNode` | | Strings and numbers key themselves. | | `swapKey` | `string \| number` | `children` | Pass when `children` are elements. | | `direction` | `1 \| -1` | `1` | Use -1 for "back" or a count going down. | | `animateWidth` | `boolean` | `true` | Spring the width to fit the new text. | | `initial` | `boolean` | `false` | Animate the first render. | Reduced motion: a 100ms cross-fade, and the width changes at once. The outgoing copy is hidden from screen readers while it leaves; add `aria-live` on a parent if the change should be announced. **Motion signature:** text changes with y + blur on a tween kept apart from the spring, travels in the direction of change, and the box springs to the new width. ## Example `components/eased/text-swap/text-swap-demo.tsx` ```tsx "use client"; import { useEffect, useRef, useState } from "react"; import { Button } from "../button/button"; import { DemoFrame } from "../lib/demo-frame"; import { Segmented } from "../segmented/segmented"; import { TextSwap } from "./text-swap"; const STEPS = [ { label: "Order placed", detail: "Mon 14 Oct, 09:12" }, { label: "Packed", detail: "Mon 14 Oct, 16:40" }, { label: "Shipped from Leeds", detail: "Tue 15 Oct, 07:05" }, { label: "Out for delivery", detail: "Wed 16 Oct, 08:31" }, { label: "Delivered", detail: "Wed 16 Oct, 13:58" }, ]; const PLANS = { monthly: { price: "$12", period: "per seat / month", note: "Billed monthly" }, yearly: { price: "$120", period: "per seat / year", note: "Billed yearly, 2 months free" }, } as const; export function TextSwapDemo() { const [step, setStep] = useState(2); const [direction, setDirection] = useState<1 | -1>(1); const [plan, setPlan] = useState("monthly"); const [copied, setCopied] = useState(false); const timer = useRef(0); useEffect(() => () => clearTimeout(timer.current), []); const go = (to: number) => { setDirection(to > step ? 1 : -1); setStep(to); }; const copy = () => { void navigator.clipboard?.writeText("https://acme.co/invite/7f3k9q").catch(() => {}); setCopied(true); clearTimeout(timer.current); timer.current = window.setTimeout(() => setCopied(false), 1400); }; const p = PLANS[plan]; return (

Order #4182

{STEPS[step].label}

{STEPS[step].detail}

))}

Team plan

{p.price} {p.period}

{p.note}

Invite link

acme.co/invite/7f3k9q

{copied ? "Link copied" : ""}

); } ``` --- # Textarea > A textarea that grows with its text on a smooth height spring instead of jumping a line at a time. The character counter rolls its digits and turns warning-coloured at 90%. - Tier: Free (MIT) - Interaction: Type - Page: https://eased.dev/components/textarea - Installs: @base-ui/react, motion - Registry: https://eased.dev/r/textarea.json ## Install ```bash npx shadcn add https://eased.dev/r/textarea.json ``` A textarea that grows with its text, on Base UI's Field.Control. ```tsx import { Textarea } from "@/components/eased/textarea/textarea";

</Field>
```

| Prop | Type | Default | |
|---|---|---|---|
| `minRows` | `number` | `3` | Height when empty. |
| `maxRows` | `number` | `8` | Grows to this, then scrolls. |
| `onValueChange` | `(value: string) => void` | | Every change. |
| `maxLength` | `number` | | Native limit; turns the counter on. |
| `showCount` | `boolean` | `maxLength !== undefined` | The `count/max` counter. |
| `invalid` | `boolean` | | For use outside a Field. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Type size, radius and padding, matching Input. |
| `className`, `controlClassName` | `string` | | Shell and `<textarea>`. |

Plus every `<textarea>` prop. The counter is hidden from screen readers; a status line announces only "approaching the limit" and "limit reached".

**Motion signature:** it autosizes on a smooth height spring instead of jumping a line at a time, and the character counter rolls its digits and turns warning-coloured at 90%.

## Example

`components/eased/textarea/textarea-demo.tsx`

```tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { Avatar } from "../avatar/avatar";
import { Button } from "../button/button";
import { Field } from "../field/field";
import { DemoFrame } from "../lib/demo-frame";
import { Textarea } from "./textarea";

const MAX = 280;
const TEMPLATE =
  "Thanks for flagging this, Maya. The export fails when a sheet name contains a slash, so the fix ships in tomorrow’s release. Until then, renaming the sheet works. I’ll reply here once it’s live.";

export function TextareaDemo() {
  const [value, setValue] = useState("");
  const [state, setState] = useState<"idle" | "sending" | "sent">("idle");
  const timers = useRef<number[]>([]);
  useEffect(() => () => timers.current.forEach(clearTimeout), []);

const send = () => {
    if (!value.trim()) return;
    setState("sending");
    timers.current.push(
      window.setTimeout(() => {
        setState("sent");
        setValue("");
        timers.current.push(window.setTimeout(() => setState("idle"), 1600));
      }, 900),
    );
  };

return (
    <DemoFrame title="Reply to Maya Chen" meta="#4821">
      <div className="flex min-h-0 flex-1 flex-col gap-4 p-4">
        <div className="flex gap-3">
          <Avatar name="Maya Chen" size="md" />
          <div className="min-w-0">
            <p className="text-ui-sm text-text-muted">Maya Chen · 2h ago</p>
            <p className="text-ui text-pretty text-text-secondary">
              Exporting to CSV fails on the “Q3/Q4 forecast” sheet. Other sheets are fine.
            </p>
          </div>
        </div>

<Field label="Reply">
          <Textarea
            value={value}
            onValueChange={setValue}
            maxLength={MAX}
            minRows={2}
            maxRows={6}
            placeholder="Write a reply…"
            onKeyDown={(e) => {
              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) send();
            }}
          />
        </Field>

<div className="flex items-center gap-2">
          <Button variant="ghost" size="sm" edge="start" onClick={() => setValue(TEMPLATE)}>
            Insert template
          </Button>
          <div className="flex-1" />
          <Button
            variant="primary"
            size="sm"
            loading={state === "sending"}
            disabled={!value.trim() && state === "idle"}
            focusableWhenDisabled
            onClick={send}
          >
            {state === "sent" ? "Sent" : "Send reply"}
          </Button>
        </div>
        <span role="status" className="sr-only">
          {state === "sent" ? "Reply sent" : ""}
        </span>
      </div>
    </DemoFrame>
  );
}
```

---

# Thinking Bar

> The line above a reasoning model's answer: the label shimmers while a seconds counter rolls, then "Thinking" morphs into "Thought for 12s" and the reasoning folds away a second after the answer starts.

- Tier: Free (MIT)
- Interaction: Loading
- Page: https://eased.dev/components/thinking-bar
- Installs: motion, @base-ui/react
- Registry: https://eased.dev/r/thinking-bar.json

## Install

```bash
npx shadcn add https://eased.dev/r/thinking-bar.json
```

The line above a reasoning model's answer: "Thinking 4s" while it works, "Thought for 12s" when it's done, with the reasoning folded inside.

```tsx
import { ThinkingBar } from "@/components/eased/thinking-bar/thinking-bar";

<ThinkingBar status={isReasoning ? "thinking" : "done"} lines={["Reading your plan", "Comparing plans"]}>
  {reasoningText}
</ThinkingBar>

// A message loaded from history shows its real duration.
<ThinkingBar status="done" startedAt={msg.reasoningStartedAt} endedAt={msg.reasoningEndedAt}>{msg.reasoning}</ThinkingBar>
```

With the AI SDK, `status` is `"thinking"` while the message's last part is a streaming `reasoning` part.

## Props

| Prop | Type | Default | |
|---|---|---|---|
| `status` | `"thinking" \| "done"` | | |
| `startedAt` / `endedAt` | `number \| Date` | | Omit `startedAt` to count from when `status` turns `thinking`. |
| `label` | `string` | `"Thinking"` | |
| `lines` | `string[]` | | Status lines to rotate through after `label` (2–4s each by length; holds on the last). |
| `doneLabel` | `string` | `"Thought for"` | Under one second it reads "Thought for a moment". |
| `icon` | `ReactNode` | | Before the label, e.g. `<AgentOrb size="sm" label={false} />`. |
| `children` | `ReactNode` | | The reasoning. With it the bar is a disclosure; without it, a plain line. |
| `open` / `defaultOpen` / `onOpenChange` | | | Controlled or uncontrolled. `onOpenChange` also reports the automatic changes. |
| `autoOpen` | `boolean` | `true` | Open while thinking. |
| `autoClose` | `number \| false` | `1000` | Close this many ms after `done`. Both automatic behaviours stop once the reader toggles it, and come back on the next thinking run. |
| `className` | `string` | | |

Base UI Collapsible supplies the button, `aria-expanded` and `aria-controls`. The rolling digits are hidden from assistive tech; the button's name is "Thinking…" or "Thought for 12 seconds", and a polite status announces the result once.

**Motion signature:** the label shimmers while a seconds counter rolls beside it; on completion "Thinking" swaps to "Thought for" and the counter, the same element, glides along the springing width to read "Thought for 12s", while the reasoning folds away on Auto Height and the chevron turns on the same smooth spring.

## Example

`components/eased/thinking-bar/thinking-bar-demo.tsx`

```tsx
"use client";

import { motion } from "motion/react";
import { useEffect, useState } from "react";
import { Button } from "../button/button";
import { DemoFrame } from "../lib/demo-frame";
import { enter, useSafeReducedMotion } from "../lib/motion";
import { ThinkingBar } from "./thinking-bar";

const TRACE = [
  "The team is on monthly at $14 a seat, 18 seats, renewing 1 March.",
  "Six seats added in March prorate on either plan, so they cancel out.",
  "Yearly is $140 a seat: 24 × 140 = $3,360, against 24 × 14 × 12 = $4,032.",
  "Yearly saves $672 even with the mid-year seats. Worth saying it locks the count until renewal.",
];

const ANSWER =
  "Yes. With 24 seats, yearly comes to $3,360 against $4,032 on monthly, so you save $672. The six March seats are prorated either way. The one catch: on yearly you can add seats any time, but you can't drop below 24 until renewal.";

const THINK_MS = 6400;

export function ThinkingBarDemo() {
  const [run, setRun] = useState(0);
  const [status, setStatus] = useState<"thinking" | "done">("thinking");
  const [traced, setTraced] = useState(1);
  const [words, setWords] = useState(0);
  const reduced = useSafeReducedMotion();
  const answer = ANSWER.split(" ");

// The script: trace lines land while thinking, then the answer streams in word by word.
  useEffect(() => {
    const timers = [
      ...TRACE.slice(1).map((_, i) => window.setTimeout(() => setTraced(i + 2), ((i + 1) * THINK_MS) / TRACE.length)),
      window.setTimeout(() => setStatus("done"), THINK_MS),
    ];
    return () => timers.forEach(clearTimeout);
  }, [run]);

useEffect(() => {
    if (status !== "done" || words >= answer.length) return;
    const t = window.setTimeout(() => setWords((w) => Math.min(answer.length, w + 1 + Math.round(Math.random() * 2))), 45 + Math.random() * 70);
    return () => clearTimeout(t);
  }, [status, words, answer.length]);

const replay = () => {
    setStatus("thinking");
    setTraced(1);
    setWords(0);
    setRun((r) => r + 1);
  };

return (
    <DemoFrame
      title="Billing assistant"
      actions={
        <Button variant="ghost" size="sm" edge="end" onClick={replay}>
          Replay
        </Button>
      }
    >
      <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4 [scrollbar-width:thin]">
        {/* The turn before, so the new question lands in a conversation rather than an empty panel. */}
        <p className="ml-auto max-w-[85%] rounded-panel bg-surface-sunken px-3.5 py-2 text-ui text-text text-pretty">
          What are we paying now?
        </p>
        <p className="text-ui text-text text-pretty">$252 a month: 18 seats on monthly at $14 each, renewing 1 March.</p>
        <p className="ml-auto max-w-[85%] rounded-panel bg-surface-sunken px-3.5 py-2 text-ui text-text text-pretty">
          If we add 6 seats in March, is yearly still cheaper?
        </p>

<div className="flex flex-col gap-3">
          <ThinkingBar
            key={run}
            status={status}
            lines={["Reading your plan", "Prorating 6 seats from March", "Comparing monthly and yearly"]}
          >
            <div className="flex flex-col gap-1.5">
              {TRACE.slice(0, traced).map((line) => (
                <motion.p
                  key={line}
                  initial={reduced ? { opacity: 0 } : { opacity: 0, y: 4, filter: "blur(4px)" }}
                  animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
                  transition={enter}
                >
                  {line}
                </motion.p>
              ))}
            </div>
          </ThinkingBar>

{words > 0 && (
            <p className="text-ui text-text text-pretty" aria-live="polite">
              {answer.slice(0, words).map((w, i) => (
                <motion.span
                  key={i}
                  initial={reduced ? { opacity: 0 } : { opacity: 0, filter: "blur(4px)" }}
                  animate={{ opacity: 1, filter: "blur(0px)" }}
                  transition={enter}
                >
                  {w}{" "}
                </motion.span>
              ))}
            </p>
          )}
        </div>
      </div>
    </DemoFrame>
  );
}
```

---

# Agent Orb

> A small living orb for an assistant's state: colour fields drift inside a glassy sphere and it breathes, idle, listening, thinking or speaking, with its speed tied to the token rate so it keeps pace with the stream.

- Tier: Free (MIT)
- Interaction: Loading
- Page: https://eased.dev/components/agent-orb
- Installs: motion
- Registry: https://eased.dev/r/agent-orb.json

## Install

```bash
npx shadcn add https://eased.dev/r/agent-orb.json
```

A small living disc for an assistant's state. Colour fields drift inside a glassy sphere, a band of light sweeps through while it thinks, and it breathes. Its speed follows the token rate.

```tsx
import { AgentOrb } from "@/components/eased/agent-orb/agent-orb";
import { useTokenRate } from "@/components/eased/_primitives/thinking-core/thinking-core";

const { rate } = useTokenRate(message.text);
<AgentOrb state="speaking" rate={rate} size="lg" />

<AgentOrb state="listening" level={micLevel} />   // a 0–1 motion value from an AnalyserNode
```

## Props

| Prop | Type | Default | |
|---|---|---|---|
| `state` | `"idle" \| "listening" \| "thinking" \| "speaking"` | `"thinking"` | Each state has its own palette, speed and energy; changes crossfade over 700ms. |
| `rate` | `number \| MotionValue<number>` | | 0–1 stream rate. Speeds the swirl up to 2× and deepens the breath. A motion value updates without re-rendering. |
| `level` | `number \| MotionValue<number>` | | 0–1 input level while `listening`. |
| `variant` | `"orb" \| OrbVariant` | `"orb"` | A Pro variant component (ring, swirl, liquid, aurora, grain, shader). |
| `size` | `"sm" \| "md" \| "lg" \| number` | `"md"` | 16, 24 or 40px, or any diameter. |
| `label` | `string \| false` | the state | Accessible name (`role="img"`). `false` when visible text already says it. |
| `className` | `string` | | |

Re-theme by setting `--eased-orb-a`, `--eased-orb-b`, `--eased-orb-c` and `--eased-orb-deep` on `.eased-orb[data-state="…"]`.

**Variants.** The orb owns the clock; a variant only paints. An `OrbVariant` is a component that receives `{ size, state, phase, energy, reduced }`: `phase` is animated time already scaled by speed (derive every rotation from it so speed changes glide), and `energy` is a smoothed 0–1 amplitude.

**Motion signature:** three colour fields and a dark pocket orbit at different rates under a slow iridescent swirl, so the pattern never repeats; speed eases (0.5s, no overshoot) from a 0.4× idle drift to 1× thinking and up to 2× while speaking with the token rate, and the breath swells 1 → 1.06 with energy. It pauses off-screen and stands still under reduced motion, keeping its colours.

## Example

`components/eased/agent-orb/agent-orb-demo.tsx`

```tsx
"use client";

import { useMotionValue, useMotionValueEvent } from "motion/react";
import { useEffect, useState } from "react";
import { NumberRoll } from "../_primitives/number-roll/number-roll";
import { TextSwap } from "../_primitives/text-swap/text-swap";
import { useTokenRate } from "../_primitives/thinking-core/thinking-core";
import { DemoFrame } from "../lib/demo-frame";
import { Segmented } from "../segmented/segmented";
import { ShimmerText } from "../shimmer-text/shimmer-text";
import { AgentOrb, type OrbState } from "./agent-orb";

const REPLY =
  "Your March invoice went up because six seats were added mid-cycle. They're prorated from the 9th, so this month carries $56 extra and April goes back to the normal yearly rate. Want me to email the breakdown to finance? ";

const HINTS: Record<Exclude<OrbState, "speaking">, string> = {
  idle: "Ask about seats, invoices or plans",
  listening: "Go ahead, I’m listening",
  thinking: "Checking your March invoice…",
};

const CAPTIONS: Record<OrbState, string> = {
  idle: "Ready when you are",
  listening: "Listening",
  thinking: "Thinking",
  speaking: "Speaking",
};

/** A reply that streams in bursts: the pace changes every 1.2–2s between a trickle and a flood. */
function useFakeStream(on: boolean) {
  const [text, setText] = useState("");
  useEffect(() => {
    if (!on) return;
    let pace = 30;
    let i = 0;
    let out = "";
    const timers: number[] = [];
    const retime = window.setInterval(() => (pace = [8, 25, 45, 70][Math.floor(Math.random() * 4)]), 1600);
    const tick = () => {
      const tokens = 1 + Math.floor(Math.random() * 3);
      const chars = tokens * 4;
      out += REPLY.slice(i % REPLY.length, (i % REPLY.length) + chars);
      i += chars;
      setText(out.slice(-600));
      timers.push(window.setTimeout(tick, (tokens / pace) * 1000));
    };
    tick();
    return () => {
      clearInterval(retime);
      timers.forEach(clearTimeout);
      setText("");
    };
  }, [on]);
  return text;
}

/** A mic level: syllable-like bumps on a slow swell. */
function useFakeLevel(on: boolean) {
  const level = useMotionValue(0);
  useEffect(() => {
    if (!on) {
      level.set(0);
      return;
    }
    let raf = 0;
    const loop = (t: number) => {
      const s = t / 1000;
      const v = Math.max(0, Math.sin(s * 7.3) * 0.5 + Math.sin(s * 2.1) * 0.35 + Math.sin(s * 13.7) * 0.15);
      level.set(Math.min(1, v));
      raf = requestAnimationFrame(loop);
    };
    raf = requestAnimationFrame(loop);
    return () => cancelAnimationFrame(raf);
  }, [on, level]);
  return level;
}

export function AgentOrbDemo() {
  const [state, setState] = useState<OrbState>("thinking");
  const text = useFakeStream(state === "speaking");
  const { rate, tps } = useTokenRate(text, { max: 60 });
  const level = useFakeLevel(state === "listening");
  const [shownTps, setShownTps] = useState(0);
  useMotionValueEvent(tps, "change", (v) => {
    const r = Math.round(v);
    if (r !== shownTps) setShownTps(r);
  });

return (
    <DemoFrame title="Agent Orb" meta={state === "speaking" ? <><NumberRoll value={shownTps} /> tok/s</> : undefined}>
      <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-6 px-4">
        <AgentOrb state={state} rate={rate} level={level} size={96} label={false} />
        <div className="flex w-full min-w-0 flex-col items-center gap-1 text-center">
          <p className="text-ui-md font-medium text-text" aria-live="polite">
            <TextSwap>{CAPTIONS[state]}</TextSwap>
          </p>
          {state === "speaking" ? (
            <p
              aria-hidden
              className="flex h-5 w-full max-w-72 justify-end overflow-hidden text-ui-sm whitespace-nowrap text-text-muted [mask-image:linear-gradient(to_right,transparent,#000_30%)]"
            >
              {text}
            </p>
          ) : (
            <p className="flex h-5 items-center text-ui-sm">
              <ShimmerText active={state === "thinking"}>{HINTS[state]}</ShimmerText>
            </p>
          )}
        </div>
      </div>
      <div className="flex shrink-0 justify-center border-t border-line-subtle p-4">
        <Segmented
          aria-label="Orb state"
          size="sm"
          value={state}
          onValueChange={setState}
          options={[
            { value: "idle", label: "Idle" },
            { value: "listening", label: "Listen" },
            { value: "thinking", label: "Think" },
            { value: "speaking", label: "Speak" },
          ]}
        />
      </div>
    </DemoFrame>
  );
}
```

---

# Toggle Group

> Toggle buttons sharing one highlight: it travels between items in single mode, and pressed neighbours fuse into one shape in multiple mode. Base UI ToggleGroup behaviour.

- Tier: Free (MIT)
- Interaction: Select
- Page: https://eased.dev/components/toggle-group
- Installs: motion, @base-ui/react
- Registry: https://eased.dev/r/toggle-group.json

## Install

```bash
npx shadcn add https://eased.dev/r/toggle-group.json
```

Toggle buttons on Base UI's ToggleGroup (one tab stop, arrow keys, `aria-pressed`), sharing one highlight.

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

<ToggleGroup multiple aria-label="Text formatting" value={formats} onValueChange={setFormats}>
  <ToggleGroupItem value="bold" aria-label="Bold"><BoldIcon /></ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic"><ItalicIcon /></ToggleGroupItem>
</ToggleGroup>
```

| Prop | Type | Default | |
|---|---|---|---|
| `value` / `defaultValue` | `string[]` | `[]` | Controlled or uncontrolled. |
| `onValueChange` | `(value: string[]) => void` | | |
| `multiple` | `boolean` | `false` | Single: at most one pressed, the highlight travels. Multiple: any number. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | |
| `variant` | `"track" \| "chips"` | `"track"` | `track`: one 32px bordered track (2px padding, items stretch to 26px), the height of Segmented, Tabs and a small Button. `chips`: separate bordered 32px chips that fill when pressed, for filter rows (wrap them in a horizontal `ScrollArea` to scroll). |
| `disabled` | `boolean` | | |
| `ToggleGroupItem` | `value`, `children`, `aria-label?`, `disabled?` | | Icon-only items need `aria-label`. |

Items have no extended hit area: they sit edge to edge, and a 44px target would steal the neighbour's clicks.

**Toggle Group or Segmented:** a single choice between views or values is `Segmented` (sunken track, raised thumb). Pressing things on and off (formatting, filters, days) is `ToggleGroup` (flat track, tinted items).

To require a selection in single mode, ignore empty updates: `onValueChange={(v) => v.length && setAlign(v)}`.

**Motion signature:** in single mode one highlight travels between items (growing in from nothing, fading out when cleared); in multiple mode each pressed item's highlight grows in and pressed neighbours fuse into one continuous shape. Labels never change weight.

## Example

`components/eased/toggle-group/toggle-group-demo.tsx`

```tsx
"use client";

import { useState, type ReactNode } from "react";
import { DemoFrame } from "../lib/demo-frame";
import { ToggleGroup, ToggleGroupItem } from "./toggle-group";

function Icon({ children }: { children: ReactNode }) {
  return (
    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" aria-hidden>
      {children}
    </svg>
  );
}

const FORMATS = [
  { value: "bold", label: "Bold", icon: <path d="M4.5 3h4.25a2.5 2.5 0 0 1 0 5H4.5zM4.5 8h5a2.5 2.5 0 0 1 0 5h-5z" /> },
  { value: "italic", label: "Italic", icon: <path d="M10 3H6.5M9.5 13H6M9 3 7 13" /> },
  { value: "underline", label: "Underline", icon: <path d="M4.5 2.5v4.5a3.5 3.5 0 0 0 7 0V2.5M3.5 13.5h9" /> },
  { value: "strike", label: "Strikethrough", icon: <path d="M3 8h10M10.75 4.25C10.3 3.3 9.3 2.75 8 2.75c-1.8 0-3 .9-3 2.25 0 .9.6 1.6 1.6 2M5 11.5c.45 1.1 1.55 1.75 3 1.75 1.9 0 3.1-.95 3.1-2.4 0-.55-.15-1-.45-1.35" /> },
];

const ALIGNS = [
  { value: "left", label: "Align left", icon: <path d="M2.5 3.5h11M2.5 6.5h7M2.5 9.5h11M2.5 12.5h7" /> },
  { value: "center", label: "Align centre", icon: <path d="M2.5 3.5h11M4.5 6.5h7M2.5 9.5h11M4.5 12.5h7" /> },
  { value: "right", label: "Align right", icon: <path d="M2.5 3.5h11M6.5 6.5h7M2.5 9.5h11M6.5 12.5h7" /> },
  { value: "justify", label: "Justify", icon: <path d="M2.5 3.5h11M2.5 6.5h11M2.5 9.5h11M2.5 12.5h11" /> },
];

const ALIGN_CLASS: Record<string, string> = {
  left: "text-left",
  center: "text-center",
  right: "text-right",
  justify: "text-justify",
};

const DECORATION: Record<string, string> = {
  "false-false": "",
  "true-false": "underline",
  "false-true": "line-through",
  "true-true": "[text-decoration-line:underline_line-through]",
};

export function ToggleGroupDemo() {
  const [formats, setFormats] = useState<string[]>(["bold"]);
  const [align, setAlign] = useState<string[]>(["left"]);
  const on = (f: string) => formats.includes(f);

return (
    <DemoFrame title="Release notes" meta="Draft">
      <div className="flex flex-wrap items-center gap-2 border-b border-line-subtle px-4 py-2.5">
        <ToggleGroup multiple aria-label="Text formatting" value={formats} onValueChange={setFormats}>
          {FORMATS.map((f) => (
            <ToggleGroupItem key={f.value} value={f.value} aria-label={f.label}>
              <Icon>{f.icon}</Icon>
            </ToggleGroupItem>
          ))}
        </ToggleGroup>
        <span aria-hidden className="mx-1 h-5 w-px bg-line-subtle" />
        <ToggleGroup aria-label="Alignment" value={align} onValueChange={(v) => v.length && setAlign(v)}>
          {ALIGNS.map((a) => (
            <ToggleGroupItem key={a.value} value={a.value} aria-label={a.label}>
              <Icon>{a.icon}</Icon>
            </ToggleGroupItem>
          ))}
        </ToggleGroup>
      </div>

<div className="min-h-0 flex-1 overflow-y-auto p-4">
        <p className="mb-2 text-ui-xs text-text-muted">v2.14 · Oct 17</p>
        <p
          className={`text-ui-md text-text text-pretty ${ALIGN_CLASS[align[0] ?? "left"]} ${on("bold") ? "font-semibold" : ""} ${
            on("italic") ? "italic" : ""
          } ${DECORATION[`${on("underline")}-${on("strike")}`]} decoration-text-muted underline-offset-3`}
        >
          Checkout now remembers your shipping address between sessions.
        </p>
        <p className="mt-3 text-ui text-text-secondary text-pretty">
          Saved cards now show their expiry month, and a declined payment keeps everything you typed, so a retry is one
          tap.
        </p>
        <p className="mt-4 text-ui-xs font-medium text-text-muted uppercase tracking-caps">Fixed</p>
        <ul className="mt-1.5 flex list-disc flex-col gap-1 pl-4 text-ui text-text-secondary marker:text-text-muted">
          <li>Promo codes no longer reset when you change the quantity.</li>
          <li>Order emails show the delivery window in your time zone.</li>
        </ul>
      </div>
    </DemoFrame>
  );
}
```

---

# Tooltip

> A short label that waits 400ms for the first trigger, then follows the pointer instantly across its neighbours. Enters 3px toward its trigger, shows an optional shortcut, never appears on touch.

- Tier: Free (MIT)
- Interaction: Hover
- Page: https://eased.dev/components/tooltip
- Installs: @base-ui/react
- Registry: https://eased.dev/r/tooltip.json

## Install

```bash
npx shadcn add https://eased.dev/r/tooltip.json
```

A short visual label for mouse and keyboard users, built on Base UI Tooltip.

**Motion signature:** the first tooltip in a group waits 400ms and the rest appear instantly, with no animation, while you sweep; each enters 3px toward its trigger from the trigger's origin and never shows on touch.

## Usage

```tsx
import { Tooltip, TooltipProvider } from "@/components/eased/tooltip/tooltip";

<TooltipProvider>
  <Tooltip content="Bold" shortcut={["⌘", "B"]}>
    <button aria-label="Bold">…</button>
  </Tooltip>
</TooltipProvider>
```

Wrap a toolbar (or your app) in one `TooltipProvider` so neighbouring tooltips share a delay group. The child is the trigger: one focusable element that accepts a ref, with an `aria-label` matching `content`. Tooltips are supplementary; anything a touch or screen reader user needs belongs in the UI or a Popover.

## Props

`TooltipProvider`: `delay` (400), `closeDelay` (0), `timeout` (400, the window in which the next tooltip opens instantly).

`Tooltip`:

| Prop | Default | |
|---|---|---|
| `content` | | The label. |
| `shortcut` | | `["⌘", "B"]`, or `"Esc"` for one key: Eased `Kbd` caps after the label, hidden from screen readers. |
| `children` | | The trigger element. |
| `side` / `align` | `"top"` / `"center"` | Flips on collision; the enter direction follows. |
| `sideOffset` | 6 | Gap in px. |
| `delay` / `closeDelay` | provider's | Rest time before opening and grace after leaving, ms. |
| `closeOnClick` | true | |
| `open` / `defaultOpen` / `onOpenChange` | | Controlled or uncontrolled. |
| `zIndex` | 50 | Raise it inside a higher layer such as a dialog. |
| `disabled`, `className` | | |

## Example

`components/eased/tooltip/tooltip-demo.tsx`

```tsx
"use client";

import { Toggle } from "@base-ui/react/toggle";
import { Toolbar } from "@base-ui/react/toolbar";
import type { ReactNode } from "react";
import { Button } from "../button/button";
import { DemoFrame } from "../lib/demo-frame";
import { Tooltip, TooltipProvider } from "./tooltip";

type Tool = { label: string; keys: string[]; icon: ReactNode; toggle?: boolean; pressed?: boolean };

const MARKS: Tool[] = [
  { label: "Bold", keys: ["⌘", "B"], icon: <BoldIcon />, toggle: true, pressed: true },
  { label: "Italic", keys: ["⌘", "I"], icon: <ItalicIcon />, toggle: true },
  { label: "Strikethrough", keys: ["⇧", "⌘", "X"], icon: <StrikeIcon />, toggle: true },
  { label: "Inline code", keys: ["⌘", "E"], icon: <CodeIcon />, toggle: true },
];

const BLOCKS: Tool[] = [
  { label: "Add link", keys: ["⌘", "K"], icon: <LinkIcon /> },
  { label: "Bulleted list", keys: ["⇧", "⌘", "8"], icon: <ListIcon />, toggle: true },
];

export function TooltipDemo() {
  return (
    <DemoFrame title="Release notes" meta="Draft">
      <TooltipProvider>
        <Toolbar.Root aria-label="Formatting" className="flex h-12 shrink-0 items-center gap-0.5 border-b border-line-subtle px-2">
          {MARKS.map((t) => (
            <Tool key={t.label} tool={t} />
          ))}
          <Toolbar.Separator className="mx-1.5 h-4 w-px shrink-0 bg-line" />
          {BLOCKS.map((t) => (
            <Tool key={t.label} tool={t} />
          ))}
          <div className="flex-1" />
          <Tool tool={{ label: "Undo", keys: ["⌘", "Z"], icon: <UndoIcon /> }} />
        </Toolbar.Root>
      </TooltipProvider>

<article className="flex min-h-0 flex-1 flex-col gap-3 overflow-hidden px-4 py-5">
        <h3 className="text-ui-md font-medium text-balance text-text">Eased 2.4: background sync</h3>
        <p className="text-ui text-pretty text-text-secondary">
          Offline edits now sync in the background. When two people change the same block, the{" "}
          <strong className="font-medium text-text">newest edit wins</strong> and the other is kept in history instead of
          asking you to choose.
        </p>
        <ul className="flex flex-col gap-1.5 text-ui text-text-secondary">
          {["Sync status lives in the title bar", "Conflicts open in a side-by-side diff", "Large files upload in parallel"].map(
            (line) => (
              <li key={line} className="flex gap-2">
                <span aria-hidden className="flex h-[1lh] shrink-0 items-center">
                  <span className="size-1 rounded-pill bg-text-muted" />
                </span>
                <span className="min-w-0">{line}</span>
              </li>
            ),
          )}
        </ul>
      </article>
    </DemoFrame>
  );
}

function Tool({ tool }: { tool: Tool }) {
  // Toolbar buttons sit side by side, so no extended hit area: it would cover the neighbours.
  const button = <Button variant="ghost" size="icon-sm" hitArea={false} className="data-pressed:bg-surface-active data-pressed:text-text" />;
  return (
    <Tooltip content={tool.label} shortcut={tool.keys} side="bottom">
      <Toolbar.Button aria-label={tool.label} render={tool.toggle ? <Toggle defaultPressed={tool.pressed} render={button} /> : button}>
        {tool.icon}
      </Toolbar.Button>
    </Tooltip>
  );
}

/* ---------- Icons: 16px, 1.5px stroke ---------- */

function Icon({ children }: { children: ReactNode }) {
  return (
    <svg
      viewBox="0 0 16 16"
      className="size-4 shrink-0"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.5}
      strokeLinecap="round"
      strokeLinejoin="round"
      aria-hidden
    >
      {children}
    </svg>
  );
}

function BoldIcon() {
  return (
    <Icon>
      <path d="M4.75 3h4a2.5 2.5 0 0 1 0 5h-4zM4.75 8h4.75a2.5 2.5 0 0 1 0 5H4.75z" />
    </Icon>
  );
}

function ItalicIcon() {
  return (
    <Icon>
      <path d="M10 3h-3.5M9.5 13H6M9.75 3l-3.5 10" />
    </Icon>
  );
}

function StrikeIcon() {
  return (
    <Icon>
      <path d="M2.75 8h10.5M11 4.6C10.5 3.6 9.4 3 8 3 6.3 3 5 3.9 5 5.2c0 .9.5 1.5 1.3 1.9M5 11.4c.5 1 1.6 1.6 3 1.6 1.7 0 3-.9 3-2.3 0-.4-.1-.7-.3-1" />
    </Icon>
  );
}

function CodeIcon() {
  return (
    <Icon>
      <path d="M5.5 4.5 2 8l3.5 3.5M10.5 4.5 14 8l-3.5 3.5" />
    </Icon>
  );
}

function LinkIcon() {
  return (
    <Icon>
      <path d="M7 9a2.5 2.5 0 0 0 3.5 0l2-2A2.5 2.5 0 0 0 9 3.5l-.5.5M9 7a2.5 2.5 0 0 0-3.5 0l-2 2A2.5 2.5 0 0 0 7 12.5l.5-.5" />
    </Icon>
  );
}

function ListIcon() {
  return (
    <Icon>
      <path d="M6.5 4.5h7M6.5 8h7M6.5 11.5h7" />
      <circle cx="3" cy="4.5" r=".6" fill="currentColor" />
      <circle cx="3" cy="8" r=".6" fill="currentColor" />
      <circle cx="3" cy="11.5" r=".6" fill="currentColor" />
    </Icon>
  );
}

function UndoIcon() {
  return (
    <Icon>
      <path d="M5 3.5 2.5 6 5 8.5" />
      <path d="M2.5 6h6.75a3.75 3.75 0 0 1 0 7.5H7" />
    </Icon>
  );
}
```

---

# Sparkline

> A word-sized line chart that draws in once, rings its newest point in the surface colour and morphs to new values from the shape on screen. Optional scrub readout.

- Tier: Free (MIT)
- Interaction: Hover
- Page: https://eased.dev/components/sparkline
- Registry: https://eased.dev/r/sparkline.json

## Install

```bash
npx shadcn add https://eased.dev/r/sparkline.json
```

A word-sized line chart that fills its container's width.

```tsx
import { Sparkline } from "@/components/eased/sparkline/sparkline";

<Sparkline values={signups} label="Signups, last 30 days" />
<Sparkline values={visitors} label="Visitors" height={56} area interactive format={(v) => fmt.format(v)} formatIndex={(i) => dates[i]} />
```

## Props

| Prop | Type | Default | |
|---|---|---|---|
| `values` | `number[]` | | Oldest first, evenly spaced. |
| `label` | `string` | | Accessible name; a first/last/low/high summary is appended. |
| `color` | `string` | `var(--eased-chart-1)` | Any colour token, or `chartColor(n)`. |
| `height` | `number` | `32` | Pixels. |
| `area` | `boolean` | `false` | A soft wash under the line. |
| `dot` | `boolean` | `true` | The newest point, ringed in the surface colour (set `--chart-surface` on a different background). |
| `curve` | `"monotone" \| "linear"` | `"monotone"` | |
| `zero` | `boolean` | `false` | Include zero in the range. |
| `interactive` | `boolean` | `false` | Scrub for a readout; the sparkline becomes a keyboard slider. |
| `format` / `formatIndex` | functions | | Readout and screen-reader text. |
| `onActiveChange` | `(index \| null) => void` | | |

**Motion signature:** draws in left to right the first time it scrolls into view, then the newest point settles in as a ringed dot; new values morph the line from the shape on screen instead of redrawing it.

## Example

`components/eased/sparkline/sparkline-demo.tsx`

```tsx
"use client";

import { useMemo, useState } from "react";
import { DemoFrame } from "../lib/demo-frame";
import { NumberRoll } from "../number-roll/number-roll";
import { Segmented } from "../segmented/segmented";
import { chartColor } from "../_primitives/chart-core/tokens";
import { Sparkline } from "./sparkline";

type Range = "7d" | "30d" | "90d";
const DAYS: Record<Range, number> = { "7d": 7, "30d": 30, "90d": 90 };
const RANGES = [
  { value: "7d", label: "7D" },
  { value: "30d", label: "30D" },
  { value: "90d", label: "90D" },
] as const;

// A seeded random walk, so the demo is the same on every load.
function walk(seed: number, count: number, start: number, drift: number, noise: number) {
  let s = seed;
  const rand = () => ((s = (s * 1664525 + 1013904223) % 4294967296) / 4294967296);
  const out: number[] = [];
  let v = start;
  for (let i = 0; i < 90; i++) {
    v = Math.max(start * 0.3, v * (1 + drift + (rand() - 0.5) * noise));
    out.push(v);
  }
  return out.slice(90 - count);
}

const METRICS = [
  { name: "Signups", seed: 7, start: 410, drift: 0.006, noise: 0.16, fmt: { maximumFractionDigits: 0 } },
  { name: "Activation", seed: 21, start: 38, drift: 0.001, noise: 0.05, fmt: { maximumFractionDigits: 1 }, unit: "%" },
  { name: "Churned", seed: 5, start: 31, drift: -0.003, noise: 0.22, fmt: { maximumFractionDigits: 0 } },
  { name: "p95 latency", seed: 13, start: 182, drift: 0.002, noise: 0.08, fmt: { maximumFractionDigits: 0 }, unit: " ms" },
] as const;

const day = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric" });
const TODAY = new Date(2026, 9, 17);
const dateOf = (i: number, n: number) => day.format(new Date(TODAY.getTime() - (n - 1 - i) * 86_400_000));

export function SparklineDemo() {
  const [range, setRange] = useState<Range>("30d");
  const n = DAYS[range];
  const visitors = useMemo(() => walk(3, n, 2_400, 0.004, 0.12), [n]);
  const rows = useMemo(() => METRICS.map((m) => ({ ...m, values: walk(m.seed, n, m.start, m.drift, m.noise) })), [n]);
  const int = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });

return (
    <DemoFrame title="Product health" actions={<Segmented aria-label="Range" options={RANGES} value={range} onValueChange={setRange} />}>
      <div className="flex min-h-0 flex-1 flex-col p-4">
        <div className="flex flex-col gap-1">
          <p className="text-ui-sm text-text-muted">Daily active users</p>
          <p className="text-ui-lg font-medium text-text tabular-nums">
            <NumberRoll value={Math.round(visitors[visitors.length - 1])} locale="en-US" />
          </p>
        </div>
        <Sparkline
          className="mt-8"
          values={visitors}
          label={`Daily active users, last ${n} days`}
          height={56}
          area
          interactive
          format={(v) => int.format(v)}
          formatIndex={(i) => dateOf(i, n)}
        />
        <ul className="mt-auto grid grid-cols-[minmax(0,1fr)_minmax(0,6rem)_5rem] items-center gap-x-4 border-t border-line-subtle pt-1">
          {rows.map((m) => {
            const last = m.values[m.values.length - 1];
            const first = m.values[0];
            const lowerIsBetter = m.name === "Churned" || m.name === "p95 latency";
            const healthy = lowerIsBetter ? last <= first : last >= first;
            return (
              <li key={m.name} className="col-span-3 grid h-9 grid-cols-subgrid items-center">
                <span className="truncate text-ui-sm text-text-secondary">{m.name}</span>
                <Sparkline values={m.values} label={`${m.name}, last ${n} days`} height={20} color={healthy ? chartColor(1) : "var(--eased-warning)"} />
                <span className="text-right text-ui-sm font-medium text-text tabular-nums">
                  <NumberRoll value={last} locale="en-US" format={m.fmt} />
                  {"unit" in m ? m.unit : ""}
                </span>
              </li>
            );
          })}
        </ul>
      </div>
    </DemoFrame>
  );
}
```

---

# Code Block

> Shiki-highlighted code in warm stone and cream themes, with a file title bar and language pill, a copy button that morphs into a check while "Copied" slides out, highlighted and focused lines, and long blocks that collapse under a progressive blur with "Show 22 more lines".

- Tier: Free (MIT)
- Interaction: Press
- Page: https://eased.dev/components/code-block
- Installs: motion, shiki
- Registry: https://eased.dev/r/code-block.json

## Install

```bash
npx shadcn add https://eased.dev/r/code-block.json
```

Shiki-highlighted code in Eased's warm stone (dark) and cream (light) themes, with a file title bar, a language pill, a copy button, highlighted and focused lines, and long blocks that collapse under a progressive blur.

**Motion signature:** copying morphs the two sheets into a check that draws itself in while "Copied" slides out beside it; a long block melts into a progressive blur under "Show 22 more lines", and expanding springs the height open as the blur fades away.

## When to use

- Docs, READMEs, changelogs and AI answers: any code a reader will copy.
- One file with a name (`title`), or a bare excerpt (the copy button then floats over the code and appears on hover).

## When not to use

- Several files or one command per package manager: use [Code Tabs](/components/code-tabs).
- A single shell command: use [Snippet](/components/snippet).

## Usage

```tsx search.tsx
import { CodeBlock } from "@/components/eased/code-block/code-block";

<CodeBlock title="use-debounced-value.ts" code={source} lineNumbers highlight="7-8, 16-17" />
```

Pre-highlight on the server for a first paint that is already coloured:

```tsx page.tsx
import { highlight } from "@/components/eased/_primitives/code-core/highlighter";

const tokens = await highlight(source, "tsx");
<CodeBlock title="button.tsx" code={source} tokens={tokens} />
```

## Props

| Prop | Default | |
|---|---|---|
| `code` | | The source to show and copy. |
| `lang` | from `title` | tsx, ts, js, jsx, json, css, bash, html, md, python, diff (aliases such as `typescript`, `sh`, `py` work). Anything else renders as plain text. |
| `title` | | File name for the title bar. |
| `icon` | file glyph | Replaces the glyph before the title. |
| `showLang` | `true` | The language pill (hidden under 320px of block width). |
| `lineNumbers` | `false` | A `tabular-nums slashed-zero` gutter that is never selected or copied. |
| `startLine` | `1` | First line number, for excerpts. |
| `highlight`, `focus`, `added`, `removed` | | Line ranges: `"3-5, 9"`, `4`, or `[1, [6, 8]]`. Focused lines dim the rest until hover. |
| `collapseAfter` | `20` | Collapse longer blocks; only when 3 or more lines would hide. `0` never collapses. |
| `defaultExpanded` | `false` | Start a collapsible block open. |
| `copy` | `true` | Show the copy button. |
| `onCopy` | | `(code) => void` after a successful copy. |
| `wrap` | `false` | Soft-wrap instead of scrolling sideways. |
| `tokens` | | Lines from `highlight()`, to skip client highlighting. |

## Notes

- Grammars load on demand through one shared Shiki instance (JavaScript regex engine, no WASM).
- Token colours use CSS `light-dark()`, so a theme switch never re-highlights. The block sets `color-scheme` from `.dark` or `data-theme="dark"`.
- Keyboard: the copy and "Show more" buttons are in the tab order; a block that scrolls sideways is a focusable region.
- Reduced motion: the copy icon cross-fades, the height snaps and the blur fades in 100ms.

## Example

`components/eased/code-block/code-block-demo.tsx`

```tsx
"use client";

import { DemoFrame } from "../lib/demo-frame";
import { CodeBlock } from "./code-block";

const HOOK = `import { useEffect, useRef, useState } from "react";

/**
 * The value, but only once it has stopped changing for \`delay\` ms.
 * Use it to search as someone types without a request per keystroke.
 */
export function useDebouncedValue<T>(value: T, delay = 250): T {
  const [settled, setSettled] = useState(value);
  const first = useRef(true);

useEffect(() => {
    if (first.current) {
      first.current = false;
      return;
    }
    const id = window.setTimeout(() => setSettled(value), delay);
    return () => window.clearTimeout(id);
  }, [value, delay]);

return settled;
}

// Usage
export function SearchUsers() {
  const [query, setQuery] = useState("");
  const debounced = useDebouncedValue(query, 300);
  const { data, isLoading } = useUsers({ search: debounced });

return (
    <SearchField value={query} onValueChange={setQuery} busy={isLoading}>
      {data?.map((user) => <UserRow key={user.id} user={user} />)}
    </SearchField>
  );
}
`;

/** A docs page excerpt: a 38-line hook with its key lines highlighted, collapsed after 12. */
export function CodeBlockDemo() {
  return (
    <DemoFrame>
      <div className="min-h-0 flex-1 overflow-y-auto p-4 [scrollbar-width:thin]">
        <h3 className="text-ui font-medium text-text">Debounce a value</h3>
        <p className="mt-1 text-ui-sm text-pretty text-text-secondary">
          The search waits for a pause in typing. Lines 7–8 keep the settled value; the timer is further down.
        </p>
        <CodeBlock
          className="mt-3 rounded-control"
          title="use-debounced-value.ts"
          code={HOOK}
          lineNumbers
          highlight="7-8, 16-17"
          collapseAfter={12}
        />
      </div>
    </DemoFrame>
  );
}
```

---

# Code Tabs

> Several files, or one command per package manager, in one code block: the underline glides between tabs, the code cross-fades 6px in the direction of travel while the height springs, and with a groupId every block on the page switches together and remembers the choice.

- Tier: Free (MIT)
- Interaction: Select
- Page: https://eased.dev/components/code-tabs
- Installs: motion, @base-ui/react, shiki
- Registry: https://eased.dev/r/code-tabs.json

## Install

```bash
npx shadcn add https://eased.dev/r/code-tabs.json
```

Several files, or one command for each package manager, in one code block.

**Motion signature:** the underline glides to the new tab on the snappy spring while the code cross-fades 6px in the direction of travel, the block's height springs to the new file and the language pill swaps its label in place; with a `groupId`, every block on the page switches together.

## When to use

- A component and its demo, or a page, its component and its stylesheet.
- Install, run and dlx commands across pnpm, npm, yarn and bun.

## When not to use

- One file: use [Code Block](/components/code-block). One command with no choice: use [Snippet](/components/snippet).

## Usage

```tsx install.tsx
import { CodeTabs, packageManagerItems } from "@/components/eased/code-tabs/code-tabs";

<CodeTabs
  items={[
    { label: "page.tsx", code: page },
    { label: "counter.tsx", code: counter, highlight: "6" },
  ]}
/>
```

## Props

| Prop | Default | |
|---|---|---|
| `items` | | `{ label, value?, code, lang?, tokens?, highlight?, focus?, added?, removed? }[]`. `lang` defaults from the label's extension. |
| `groupId` | | Sync the selection with every Code Tabs (and `useChoice`) sharing this id, across the page, other tabs and visits. |
| `value`, `defaultValue`, `onValueChange` | | Controlled or uncontrolled selection by item `value` (default `label`). |
| `label` | `"Files"` | Accessible name of the tab list. |
| `showLang` | when languages differ | The language pill. |
| `lineNumbers`, `collapseAfter`, `wrap` | `false`, `20`, `false` | As Code Block. |
| `copy`, `onCopy` | `true` | The copy button copies the active tab: `(code, value) => void`. |

Helpers: `packageManagerItems({ add | dlx | run })` and `packageCommand(pm, { add | dlx | run })` (`pnpm add`, `npm install`, `npx`, `bunx --bun`, `npm run` …), `PACKAGE_MANAGERS`.

Keyboard: Base UI Tabs (arrow keys, Home/End). Reduced motion: opacity cross-fades only.

## Example

`components/eased/code-tabs/code-tabs-demo.tsx`

```tsx
"use client";

import { DemoFrame } from "../lib/demo-frame";
import { CodeTabs, packageManagerItems } from "./code-tabs";

const INSTALL = packageManagerItems({ add: "motion @base-ui/react" });

const FILES = [
  {
    label: "page.tsx",
    code: `import { Counter } from "./counter";

export default function Page() {
  return <Counter start={3} />;
}`
  },
  {
    label: "counter.tsx",
    highlight: "6",
    code: `"use client";

import { useState } from "react";
import { NumberRoll } from "@/components/eased/number-roll/number-roll";

export function Counter({ start = 0 }: { start?: number }) {
  const [count, setCount] = useState(start);
  return (
    <button onClick={() => setCount((n) => n + 1)}>
      <NumberRoll value={count} />
    </button>
  );
}`,
  },
  {
    label: "globals.css",
    code: `@import "tailwindcss";
@import "./eased.css";

body {
  background: var(--eased-bg);
}`,
  },
];

/** Install in your package manager (synced page-wide), then three files of different heights and languages. */
export function CodeTabsDemo() {
  return (
    <DemoFrame>
      <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4 [scrollbar-width:thin]">
        <section className="flex flex-col gap-2">
          <h3 className="text-ui-sm font-medium text-text">Install</h3>
          <CodeTabs items={INSTALL} groupId="package-manager" label="Package manager" className="rounded-control" />
        </section>
        <section className="flex flex-col gap-2">
          <h3 className="text-ui-sm font-medium text-text">Use it</h3>
          <CodeTabs items={FILES} className="rounded-control" />
        </section>
      </div>
    </DemoFrame>
  );
}
```

---

# Snippet

> A one-line command with a $ prompt and a copy button that morphs into a check. When the command changes (pnpm ↔ npm) the text swaps and the width springs, so the copy button glides instead of jumping.

- Tier: Free (MIT)
- Interaction: Press
- Page: https://eased.dev/components/snippet
- Installs: motion, shiki
- Registry: https://eased.dev/r/snippet.json

## Install

```bash
npx shadcn add https://eased.dev/r/snippet.json
```

A one-line command with a `$` prompt and a copy button.

**Motion signature:** when the command changes (pnpm ↔ npm) the old text lifts away and the new one rises in while the pill's width springs to fit, so the copy button glides instead of jumping; copying morphs the icon into a check.

## When to use

- Install and run commands in docs, onboarding and empty states.
- Anything a reader pastes into a terminal as one line.

## When not to use

- Multi-line code: use [Code Block](/components/code-block). A choice of package manager shown as tabs: use [Code Tabs](/components/code-tabs).

## Usage

```tsx install.tsx
import { Snippet } from "@/components/eased/snippet/snippet";
import { useChoice } from "@/components/eased/_primitives/code-core/choice";
import { PACKAGE_MANAGERS, packageCommand, type PackageManager } from "@/components/eased/code-tabs/code-tabs";

const [pm] = useChoice("package-manager", "pnpm", PACKAGE_MANAGERS);
<Snippet text={packageCommand(pm as PackageManager, { dlx: "shadcn add https://eased.dev/r/code-block.json" })} />
```

## Props

| Prop | Default | |
|---|---|---|
| `text` | | The command. Changing it swaps the text and springs the width. |
| `prefix` | `"$"` | Shown, never copied. `null` hides it. |
| `lang` | `"bash"` | Grammar for the command. |
| `label` | `"Copy command"` | Accessible name of the copy button. |
| `onCopy` | | `(text) => void`. |

A command wider than its container scrolls sideways under 20px edge fades. Reduced motion: a 100ms cross-fade and an instant width.

## Example

`components/eased/snippet/snippet-demo.tsx`

```tsx
"use client";

import { useChoice } from "../_primitives/code-core/choice";
import { PACKAGE_MANAGERS, packageCommand, type PackageManager } from "../code-tabs/code-tabs";
import { DemoFrame } from "../lib/demo-frame";
import { Segmented } from "../segmented/segmented";
import { Snippet } from "./snippet";

const OPTIONS = PACKAGE_MANAGERS.map((pm) => ({ value: pm, label: pm }));

/** An install card: pick a package manager (shared with every Code Tabs on the page) and both commands follow. */
export function SnippetDemo() {
  const [pm, setPm] = useChoice("package-manager", "pnpm", PACKAGE_MANAGERS);
  const manager = pm as PackageManager;
  return (
    <DemoFrame title="Install" actions={<Segmented options={OPTIONS} value={manager} onValueChange={setPm} aria-label="Package manager" />}>
      <ol className="flex min-h-0 flex-1 flex-col gap-6 overflow-y-auto p-4">
        <li className="flex min-w-0 flex-col gap-2">
          <div>
            <p className="text-ui font-medium text-text">Add the component</p>
            <p className="text-ui-sm text-text-secondary">Copies the source into components/eased.</p>
          </div>
          <Snippet className="self-start" text={packageCommand(manager, { dlx: "shadcn add https://eased.dev/r/code-block.json" })} />
        </li>
        <li className="flex min-w-0 flex-col gap-2">
          <div>
            <p className="text-ui font-medium text-text">Start your dev server</p>
            <p className="text-ui-sm text-text-secondary">Then open localhost:3000.</p>
          </div>
          <Snippet className="self-start" text={packageCommand(manager, { run: "dev" })} />
        </li>
        <li className="flex min-w-0 flex-col gap-2">
          <div>
            <p className="text-ui font-medium text-text">Or clone the starter</p>
            <p className="text-ui-sm text-text-secondary">A Next.js app with every free component.</p>
          </div>
          <Snippet className="self-start" text="git clone https://github.com/eased-dev/starter.git my-app" />
        </li>
      </ol>
    </DemoFrame>
  );
}
```

---

# Mac menu popover

> A macOS menu bar popover: a status item and a frosted panel whose arrow and panel are one shape, so one blur and one hairline follow the arrow. It grows from the arrow tip, reverses mid-flight, and drops its CSS blur for native Tauri or Electron vibrancy.

- Tier: Free (MIT)
- Interaction: Press
- Page: https://eased.dev/components/mac-menu-popover
- Installs: @base-ui/react
- Registry: https://eased.dev/r/mac-menu-popover.json

## Install

```bash
npx shadcn add https://eased.dev/r/mac-menu-popover.json
```

A macOS menu bar popover: a status item and a frosted panel that hangs from it on an arrow, built on Base UI Popover, the Eased floating layer and the shared `eased-mac` material.

## When to use

- A menu bar utility in a Tauri or Electron app: usage meters, timers, clipboard history, quick toggles.
- A web demo or landing page that shows a Mac app's tray panel and should look and move like the real thing.
- Anywhere a `Popover` should read as native macOS: system font, translucent material, an arrow pointing at its anchor.

## When not to use

- Ordinary web UI: use [Popover](/components/popover), which follows Eased's web material and radius.
- A list of commands with no other content: a menu is the better pattern.
- Transient feedback such as volume or brightness changes: use [Mac HUD](/components/mac-hud).

## Usage

```tsx example.tsx
import {
  MacMenuItem,
  MacMenuPopover,
  MacMenuPopoverClose,
  MacMenuPopoverContent,
  MacMenuSeparator,
  MacStatusItem,
} from "@/components/eased/mac-menu-popover/mac-menu-popover";

export function UsageMenu() {
  return (
    <MacMenuPopover>
      <MacStatusItem label="Tally: 62% of this session used">62%</MacStatusItem>
      <MacMenuPopoverContent>
        <p className="font-semibold">Tally</p>
        <p>62% of this session · resets in 1h 48m</p>
        <MacMenuSeparator />
        <MacMenuPopoverClose render={<MacMenuItem shortcut="⌘," />}>Settings…</MacMenuPopoverClose>
        <MacMenuPopoverClose render={<MacMenuItem shortcut="⌘Q" />}>Quit</MacMenuPopoverClose>
      </MacMenuPopoverContent>
    </MacMenuPopover>
  );
}
```

## Examples

### Kept inside a frame

In a mock-up, keep the panel inside the fake screen rather than the viewport.

```tsx
<MacMenuPopoverContent collisionBoundary={screenElement}>…</MacMenuPopoverContent>
```

### In a desktop tray window

On the desktop the native tray icon is the status item and a small borderless window is the panel, so render your content in `MacMenuPanel`: the same type, fills and padding, without the popover. `MacMenuItem` and `MacMenuSeparator` work inside it. In Tauri and Electron alike:

- The window draws real vibrancy and the panel uses `material="native"`, its default. A CSS blur can't see the desktop through a transparent window, so `"css"` there gives an unblurred tint; it is for web pages.
- Make the page transparent with `html, body { background: transparent; }`. shadcn's base layer paints `body` with `bg-background`, which covers the vibrancy.
- Call `useSystemAppearance()` once in the window. The vibrancy follows the system appearance and Eased's dark styles follow `.dark`; without the hook a dark Mac gets dark glass with black text.
- Size the window to the content (115px tall for the panel below) and hide it when it loses focus, as macOS does.

```tsx src/tray.tsx
import { exit } from "@tauri-apps/plugin-process";
import { useSystemAppearance } from "@/components/eased/lib/mac";
import { MacMenuItem, MacMenuPanel, MacMenuSeparator } from "@/components/eased/mac-menu-popover/mac-menu-popover";

export function TrayWindow() {
  useSystemAppearance();
  return (
    <MacMenuPanel>
      <p className="font-semibold">Tally</p>
      <p>62% of this session · resets in 1h 48m</p>
      <MacMenuSeparator />
      <MacMenuItem shortcut="⌘,">Settings…</MacMenuItem>
      {/* Electron: send an IPC message that calls app.quit() instead. */}
      <MacMenuItem shortcut="⌘Q" onClick={() => exit(0)}>Quit</MacMenuItem>
    </MacMenuPanel>
  );
}
```

`MacMenuPopover` itself is for menu bars drawn in the page: a web demo, a landing page, or an app window with its own title bar. If that window draws native vibrancy, pass `material="native"` to `MacMenuPopoverContent` too.

### In a Tauri app

Checked with Tauri 2.12, `tauri-plugin-positioner` 2.4 and `tauri-plugin-process` 2. Add the plugins with `tauri add positioner` and `tauri add process`, then turn on the tray features, which `tauri add` leaves off:

```toml src-tauri/Cargo.toml
tauri = { version = "2", features = ["tray-icon", "image-png"] }
tauri-plugin-positioner = { version = "2", features = ["tray-icon"] }
```

The window, hidden until the tray icon is clicked. `windowEffects` only works with `transparent: true`; `macOSPrivateApi` is not needed (a no-op since 2.12.1).

```json src-tauri/tauri.conf.json
{
  "app": {
    "windows": [
      {
        "label": "tray",
        "url": "/tray",
        "width": 320,
        "height": 115,
        "visible": false,
        "transparent": true,
        "decorations": false,
        "resizable": false,
        "alwaysOnTop": true,
        "skipTaskbar": true,
        "visibleOnAllWorkspaces": true,
        "windowEffects": { "effects": ["popover"], "state": "active", "radius": 12 }
      }
    ]
  }
}
```

A capability for the window. `process:default` is only for `exit`; a [Mac HUD](/components/mac-hud) window gets its own.

```json src-tauri/capabilities/tray.json
{
  "identifier": "tray",
  "platforms": ["macOS"],
  "windows": ["tray"],
  "permissions": [
    "core:default",
    "core:window:allow-show",
    "core:window:allow-hide",
    "core:window:allow-set-position",
    "positioner:default",
    "process:default"
  ]
}
```

The tray icon opens the window under itself and hides it on blur. `show_menu_on_left_click(false)` replaces the deprecated `menu_on_left_click`; the icon is a black-on-transparent PNG that macOS tints as a template.

```rust src-tauri/src/lib.rs
use tauri::{
    image::Image,
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
    Manager, WindowEvent,
};
use tauri_plugin_positioner::{Position, WindowExt};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_positioner::init())
        .plugin(tauri_plugin_process::init())
        .setup(|app| {
            // A menu bar app: no Dock icon.
            #[cfg(target_os = "macos")]
            app.set_activation_policy(tauri::ActivationPolicy::Accessory);

TrayIconBuilder::new()
                .icon(Image::from_bytes(include_bytes!("../icons/tray.png"))?)
                .icon_as_template(true)
                .show_menu_on_left_click(false)
                .on_tray_icon_event(|tray, event| {
                    tauri_plugin_positioner::on_tray_event(tray.app_handle(), &event);
                    if let TrayIconEvent::Click { button: MouseButton::Left, button_state: MouseButtonState::Up, .. } = event {
                        let Some(win) = tray.app_handle().get_webview_window("tray") else { return };
                        if win.is_visible().unwrap_or(false) {
                            let _ = win.hide();
                        } else {
                            let _ = win.move_window(Position::TrayBottomCenter);
                            let _ = win.show();
                            let _ = win.set_focus();
                        }
                    }
                })
                .build(app)?;
            Ok(())
        })
        // Hide the panel when it loses focus, as macOS does.
        .on_window_event(|window, event| {
            if window.label() == "tray" && matches!(event, WindowEvent::Focused(false)) {
                let _ = window.hide();
            }
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### In an Electron app

The main process makes the tray icon and a hidden vibrancy window, and places the window under the icon on each click. `tray.getBounds()` can fall off every screen (an icon hidden behind the notch, or a second display), so the position is clamped to the nearest display.

```js electron/main.cjs
const path = require("node:path");
const { app, BrowserWindow, Tray, nativeImage, screen } = require("electron");

let tray, panel;

app.whenReady().then(() => {
  app.dock?.hide(); // A menu bar app: no Dock icon.

panel = new BrowserWindow({
    width: 320,
    height: 115,
    show: false,
    frame: false,
    transparent: true,
    backgroundColor: "#00000000",
    resizable: false,
    skipTaskbar: true,
    alwaysOnTop: true,
    vibrancy: "popover",
    visualEffectState: "active",
  });
  panel.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
  panel.on("blur", () => panel.hide());
  panel.loadFile(path.join(__dirname, "../dist/index.html"), { query: { view: "tray" } });

macOS rounds the frameless window's corners (about 10pt) and draws its shadow; Electron can't round the vibrancy further.

## API reference

### MacMenuPopover

Base UI `Popover.Root`: `open`, `defaultOpen`, `onOpenChange`, `modal` (non-modal by default), `actionsRef`.

### MacStatusItem

Base UI `Popover.Trigger` props, plus:

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | | Required accessible name, e.g. "Usage: 62% of this session used". |
| `className` | `string` | `""` | Appended to the item's classes. |

A 22px menu bar button. Children are its icon and optional short value.

### MacMenuPopoverContent

| Prop | Type | Default | Description |
|---|---|---|---|
| `width` | `number` | `320` | Panel width, px; capped at the available width. |
| `arrow` | `boolean` | `true` | Draw the arrow. Without it the panel is a plain rounded rectangle. |
| `material` | `"css" \| "native"` | `"css"` | `native` drops the CSS blur and tint for a window that draws its own vibrancy. |
| `side` | `"bottom" \| "top"` | `"bottom"` | Flips on collision; the arrow moves to the facing edge. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | |
| `sideOffset` | `number` | `6` | Gap from the status item to the arrow tip, px. |
| `alignOffset` | `number` | `0` | |
| `collisionPadding` | `number` | `8` | Space kept from the boundary, px. |
| `collisionBoundary` | `Element \| Element[] \| Rect \| "clipping-ancestors"` | viewport | The area the panel stays inside. |
| `initialFocus` | Base UI | see description | Where focus goes on open. Default: the first control when opened from the keyboard, the panel itself when clicked, so no row lights up. |
| `finalFocus` | Base UI | the status item | Where focus returns on close. |
| `container` | `HTMLElement \| null` | `document.body` | Portal target. |
| `zIndex` | `number` | `50` | |
| `className` | `string` | `""` | Appended to the content area (a flex column with 12px padding). |

The panel exposes `--pad` (12px) and `--radius-outer` (11px) for concentric children.

### MacMenuPanel

The panel's material, type, fills and 12px padding as a plain `div`, for a native tray window. `material` (`"native"`), `className`, `children`. It fills the window, so the window draws the corners.

### MacMenuItem

A `<button>` row. All button props, plus `icon` (a 16px icon on the content line) and `shortcut` (display text such as `"⌘D"`; wire the key yourself). Wrap it in `MacMenuPopoverClose` with `render` when the action should close the panel.

### MacMenuSeparator, MacMenuPopoverClose

A divider on the content lines (`className`), and Base UI `Popover.Close`.

### useSystemAppearance

From `@/components/eased/lib/mac`. Call it once in a Tauri or Electron window: it puts `.dark` on `<html>` while `prefers-color-scheme` is dark and follows changes, so the text matches the native vibrancy. It runs in an effect, so it is safe with server rendering. Eased otherwise follows `.dark` or `data-theme="dark"`, so leave it out of a web app with its own theme toggle.

## Keyboard

| Key | Action |
|---|---|
| `Enter` / `Space` on the status item | Opens or closes the panel. |
| `Tab` / `Shift+Tab` | Moves through the panel's controls; focus stays in the page. |
| `Esc` | Closes the panel and returns focus to the status item. |

## Accessibility

- The status item is a button named by `label`, with `aria-expanded` while open. Its visible text can be just a number; the label says what the number means.
- The panel is a Base UI popover (`role="dialog"`, non-modal). A keyboard open moves focus to its first control (a click focuses the panel itself); focus returns to the status item on close; Escape and an outside click dismiss it.
- Rows are real buttons. Hover and keyboard focus draw the same highlight, so focus is never invisible. The shortcut text is display only.
- The status item is 22px tall, as in the macOS menu bar; it sits in a dense row of targets, so it isn't enlarged to 44px.

## Motion

The panel grows from the arrow tip (Base UI's `--transform-origin`, which tracks the arrow) using the floating layer's transitions: it drops 6px toward the menu bar and scales from 0.95 on the `snappy` spring while fading in over 200ms, then leaves at half the distance and scale in 150ms. Open and close are CSS transitions, so a close during the open turns around mid-flight. The shadow layer copies the panel's motion state, so it moves in step. The status item presses and stays highlighted by colour only, never by scale. Reduced motion keeps a 100ms fade.

## Notes for AI

Pick this for anything that should look like a Mac menu bar extra. In a Tauri or Electron tray window render `MacMenuPanel` (native material by default) in a window with native vibrancy, a transparent `html, body`, and `useSystemAppearance()`. Compose `MacMenuPopover` › `MacStatusItem` + `MacMenuPopoverContent`, fill the content with your own layout, and use `MacMenuItem` / `MacMenuSeparator` for action rows. Always pass `label` to `MacStatusItem`.

Don't use `material="css"` in a desktop window: the blur can't see the desktop. Don't wrap the content in another card, border, shadow or blur: the panel draws its own material, hairline and shadow as one shape. Don't put a `filter`, `opacity` or `backdrop-filter` on an ancestor of the panel; it stops the blur from seeing the page. Don't scale the status item on press, and don't add animation to the panel: it already uses the shared floating motion.

## Related

- [Popover](/components/popover): the same behaviour with Eased's web material.
- [Mac HUD](/components/mac-hud): the macOS volume and brightness overlay.

## Example

`components/eased/mac-menu-popover/mac-menu-popover-demo.tsx`

```tsx
"use client";

import { useState } from "react";
import { macTextSecondary } from "../lib/mac";
import { MacDesktop } from "../lib/mac-desktop";
import {
  MacMenuItem,
  MacMenuPopover,
  MacMenuPopoverClose,
  MacMenuPopoverContent,
  MacMenuSeparator,
  MacStatusItem,
} from "./mac-menu-popover";

/** A plan-usage tracker living in the menu bar, the kind of utility people keep open all day. */
const SESSION = 62;
const WEEK = 38;

export function MacMenuPopoverDemo() {
  // The screen is the collision boundary, so the panel stays on this little desktop.
  const [screen, setScreen] = useState<HTMLDivElement | null>(null);

return (
    <MacDesktop
      ref={setScreen}
      app="Finder"
      menus={["File", "Edit", "View", "Go"]}
      className="select-none"
      statusItems={
        <MacMenuPopover>
          <MacStatusItem label={`Tally: ${SESSION}% of this session used`}>
            <Gauge value={SESSION} />
            <span>{SESSION}%</span>
          </MacStatusItem>
          <MacMenuPopoverContent collisionBoundary={screen ?? undefined}>
            <UsagePanel />
          </MacMenuPopoverContent>
        </MacMenuPopover>
      }
    />
  );
}

/**
 * Laid out like a macOS menu bar extra (the Battery or Wi-Fi menu): 13px rows, an 11px
 * secondary line under each, slim meters, and actions as menu rows.
 */
function UsagePanel() {
  return (
    <>
      <div className="flex items-baseline justify-between gap-3">
        <p className="font-semibold">Tally</p>
        <p className={`${macTextSecondary} text-[11px]`}>Pro plan</p>
      </div>

<MacMenuPopoverClose render={<MacMenuItem icon={<ChartIcon />} shortcut="⌘D" />}>Open Dashboard</MacMenuPopoverClose>
      <MacMenuPopoverClose render={<MacMenuItem icon={<GearIcon />} shortcut="⌘," />}>Settings…</MacMenuPopoverClose>
      <MacMenuPopoverClose render={<MacMenuItem icon={<PowerIcon />} shortcut="⌘Q" />}>Quit Tally</MacMenuPopoverClose>
    </>
  );
}

/** A labelled usage row: name and percentage, a slim meter, then a secondary line. */
function Usage({ label, value, detail, className = "" }: { label: string; value: number; detail: string; className?: string }) {
  return (
    <div className={className}>
      <div className="flex items-baseline justify-between gap-3">
        <p>{label}</p>
        <p className={`${macTextSecondary} tabular-nums`}>{value}%</p>
      </div>
      <div
        role="meter"
        aria-label={label}
        aria-valuenow={value}
        aria-valuemin={0}
        aria-valuemax={100}
        className="mt-1.5 h-1 overflow-hidden rounded-full bg-(--mac-track)"
      >
        <div className={`h-full rounded-full ${ACCENT}`} style={{ width: `${value}%` }} />
      </div>
      <p className={`${macTextSecondary} mt-1.5 text-[11px] leading-[14px] tabular-nums`}>{detail}</p>
    </div>
  );
}

/** macOS system blue, light and dark. */
const ACCENT = "bg-[rgb(0_122_255)] in-[.dark]:bg-[rgb(10_132_255)] in-data-[theme=dark]:bg-[rgb(10_132_255)]";

/* ---------- Glyphs ---------- */

/** The status item's template icon: a ring filled to the session usage, in the bar's text colour. */
function Gauge({ value }: { value: number }) {
  const c = 2 * Math.PI * 5.25;
  return (
    <svg viewBox="0 0 16 16" className="size-4" aria-hidden>
      <circle cx="8" cy="8" r="5.25" fill="none" stroke="currentColor" strokeOpacity={0.3} strokeWidth={2} />
      <circle
        cx="8"
        cy="8"
        r="5.25"
        fill="none"
        stroke="currentColor"
        strokeWidth={2}
        strokeLinecap="round"
        strokeDasharray={`${(value / 100) * c} ${c}`}
        transform="rotate(-90 8 8)"
      />
    </svg>
  );
}

const stroke = { fill: "none", stroke: "currentColor", strokeWidth: 1.3, strokeLinecap: "round", strokeLinejoin: "round" } as const;

function ChartIcon() {
  return (
    <svg viewBox="0 0 16 16" aria-hidden {...stroke}>
      <path d="M2.5 13.5h11M4.5 11V8M8 11V4.5M11.5 11V6.5" />
    </svg>
  );
}

function GearIcon() {
  return (
    <svg viewBox="0 0 16 16" aria-hidden {...stroke}>
      <circle cx="8" cy="8" r="2" />
      <path d="M8 1.75v1.5M8 12.75v1.5M14.25 8h-1.5M3.25 8h-1.5M12.42 3.58l-1.06 1.06M4.64 11.36l-1.06 1.06M12.42 12.42l-1.06-1.06M4.64 4.64 3.58 3.58" />
    </svg>
  );
}

function PowerIcon() {
  return (
    <svg viewBox="0 0 16 16" aria-hidden {...stroke}>
      <path d="M8 2v5.5M4.75 4.25a5 5 0 1 0 6.5 0" />
    </svg>
  );
}
```

---

# Mac HUD

> The macOS volume and brightness overlay: a frosted, click-through HUD in the classic 200×200 square or the macOS 26 pill. Repeat changes update it in place and restart its 1.1s hold; it never replays its entrance.

- Tier: Free (MIT)
- Interaction: Press
- Page: https://eased.dev/components/mac-hud
- Installs: motion
- Registry: https://eased.dev/r/mac-hud.json

## Install

```bash
npx shadcn add https://eased.dev/r/mac-hud.json
```

The macOS volume and brightness overlay: a frosted, click-through HUD that shows a level for a moment and updates in place while it is up, in the classic square or the macOS 26 pill.

## When to use

- A Mac app (Tauri, Electron or a web app that looks native) that changes a level from a shortcut or a media key: volume, display or keyboard brightness, or your own level such as playback speed.
- Feedback for a key held down: every repeat moves the bar without the HUD flickering or re-entering.
- A desktop-style web demo where the overlay should feel like the system's own.

## When not to use

- A level people set by dragging: use a slider, which already shows its value.
- Messages and confirmations ("Copied", "Saved"): announce them in a toast or inline status.
- Anything people must act on: the HUD ignores the pointer and leaves after 1.1 seconds. For a reversible action use [Undo Pill](/components/undo-pill).

## Usage

`useMacHud` holds the state and the hold timer. Call `show(kind, value)` on every change and spread `hud` onto `<MacHud>`.

```tsx player.tsx
import { useEffect, useRef } from "react";
import { MacHud, useMacHud } from "@/components/eased/mac-hud/mac-hud";

export function Player() {
  const { hud, show } = useMacHud();
  const volume = useRef(0.5);

useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
      // One of sixteen segments per press, as on a Mac.
      const next = Math.round(volume.current * 16) + (e.key === "ArrowUp" ? 1 : -1);
      volume.current = Math.min(16, Math.max(0, next)) / 16;
      show("volume", volume.current);
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [show]);

return <MacHud {...hud} />;
}
```

`show` while the HUD is up updates it in place and restarts the 1.1-second hold, so a held key keeps it on screen until the last repeat.

## Examples

### Pill

The macOS 26 capsule, 12px in from the top-right corner. Put it under your own menu bar by rendering it in a positioned box that starts below the bar.

```tsx
<MacHud {...hud} variant="pill" />
```

### Muted

Pass `muted` with the volume: the speaker gets a slash and the bar empties, and the level comes back when you unmute.

```tsx
show("volume", volume, { muted: true });
```

### Inside a container

`position="absolute"` places it in the nearest positioned parent instead of the viewport. The classic HUD sits 140px above the bottom, or centres in a container too short for that.

```tsx
<div className="relative h-80">
  <MacHud {...hud} position="absolute" />
</div>
```

### In a desktop window

A HUD floats above every app, so in Tauri or Electron it lives in its own small window that is exactly the HUD's size. In both:

- The window draws real vibrancy, and the HUD takes `material="native"` and `position="none"`. A CSS blur can't see the desktop through a transparent window, so `"css"` there gives an unblurred tint.
- Make the page transparent with `html, body { background: transparent; }` (shadcn's `bg-background` on `body` covers the vibrancy) and call `useSystemAppearance()` from `@/components/eased/lib/mac`, so the glyphs follow the system's light or dark material.
- The window ignores the pointer, never takes focus, and sits centred 140pt above the bottom of the primary display.
- Hide the window in `onExitComplete`, or the empty vibrancy stays on screen after the HUD has left. Vibrancy belongs to the window, so it appears and disappears at once while the icon and bar animate.

For the pill, size the window 200×44 and place it 12pt below the menu bar at the right.

### In a Tauri app

Checked with Tauri 2.12. The window, in `tauri.conf.json`. `"focusable": false` matters: without it `show()` takes focus, and a tray panel that hides on blur closes. `windowEffects` only works with `transparent: true`; `macOSPrivateApi` is a no-op since 2.12.1.

```json src-tauri/tauri.conf.json
{
  "app": {
    "windows": [
      {
        "label": "hud",
        "url": "/hud",
        "width": 200,
        "height": 200,
        "visible": false,
        "transparent": true,
        "decorations": false,
        "focus": false,
        "focusable": false,
        "shadow": false,
        "resizable": false,
        "alwaysOnTop": true,
        "skipTaskbar": true,
        "visibleOnAllWorkspaces": true,
        "windowEffects": { "effects": ["hudWindow"], "state": "active", "radius": 18 }
      }
    ]
  }
}
```

A capability for the window, so its page may move, show, hide and click-through it:

```json src-tauri/capabilities/hud.json
{
  "identifier": "hud",
  "platforms": ["macOS"],
  "windows": ["hud"],
  "permissions": [
    "core:default",
    "core:window:allow-show",
    "core:window:allow-hide",
    "core:window:allow-set-position",
    "core:window:allow-set-ignore-cursor-events"
  ]
}
```

The page listens for levels, sent from Rust with `app.emit_to("hud", "hud", level)` (from a global shortcut handler, say) or from another window with `emitTo`. It places the window on the primary display each time: the hidden window's own monitor is wherever it was last shown.

```tsx src/hud.tsx
import { listen } from "@tauri-apps/api/event";
import { PhysicalPosition } from "@tauri-apps/api/dpi";
import { getCurrentWindow, primaryMonitor } from "@tauri-apps/api/window";
import { useEffect } from "react";
import { useSystemAppearance } from "@/components/eased/lib/mac";
import { MacHud, useMacHud, type MacHudKind } from "@/components/eased/mac-hud/mac-hud";

type Level = { kind: MacHudKind; value: number; muted?: boolean };

export function HudWindow() {
  useSystemAppearance();
  const { hud, show } = useMacHud();

useEffect(() => {
    const win = getCurrentWindow();
    win.setIgnoreCursorEvents(true);
    const off = listen<Level>("hud", async ({ payload }) => {
      const monitor = await primaryMonitor();
      if (monitor) {
        const size = 200 * monitor.scaleFactor;
        const x = monitor.position.x + (monitor.size.width - size) / 2;
        const y = monitor.position.y + monitor.size.height - size - 140 * monitor.scaleFactor;
        await win.setPosition(new PhysicalPosition(Math.round(x), Math.round(y)));
      }
      await win.show();
      show(payload.kind, payload.value, { muted: payload.muted });
    });
    return () => void off.then((unlisten) => unlisten());
  }, [show]);

return <MacHud {...hud} position="none" material="native" onExitComplete={() => void getCurrentWindow().hide()} />;
}
```

### In an Electron app

The main process owns the window and sends it each level; `showInactive()` shows it without taking focus. Electron can't round vibrancy, and macOS gives a frameless window about 10pt corners, so pass `radius={10}` to match (the pill becomes a rounded rectangle there).

```js electron/main.cjs
const path = require("node:path");
const { app, BrowserWindow, ipcMain, screen } = require("electron");

let hud;

app.whenReady().then(() => {
  app.dock?.hide(); // A menu bar app: no Dock icon.

hud = new BrowserWindow({
    width: 200,
    height: 200,
    show: false,
    frame: false,
    transparent: true,
    backgroundColor: "#00000000",
    focusable: false,
    hasShadow: false,
    resizable: false,
    skipTaskbar: true,
    vibrancy: "hud",
    visualEffectState: "active",
    webPreferences: { preload: path.join(__dirname, "preload.cjs") },
  });
  hud.setAlwaysOnTop(true, "screen-saver");
  hud.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
  hud.setIgnoreMouseEvents(true);
  hud.loadFile(path.join(__dirname, "../dist/index.html"), { query: { view: "hud" } });
});

// Call from a globalShortcut handler, for example.
function showHud(level) {
  const { bounds } = screen.getPrimaryDisplay();
  hud.setPosition(Math.round(bounds.x + (bounds.width - 200) / 2), bounds.y + bounds.height - 200 - 140);
  if (!hud.isVisible()) hud.showInactive();
  hud.webContents.send("hud", level);
}

ipcMain.on("hud-closed", () => hud.hide());
```

```js electron/preload.cjs
const { contextBridge, ipcRenderer } = require("electron");

contextBridge.exposeInMainWorld("hud", {
  onLevel: (callback) => {
    const listener = (_event, level) => callback(level);
    ipcRenderer.on("hud", listener);
    return () => ipcRenderer.off("hud", listener);
  },
  closed: () => ipcRenderer.send("hud-closed"),
});
```

```tsx src/hud.tsx
import { useEffect } from "react";
import { useSystemAppearance } from "@/components/eased/lib/mac";
import { MacHud, useMacHud, type MacHudKind } from "@/components/eased/mac-hud/mac-hud";

declare global {
  interface Window {
    hud: { onLevel: (callback: (level: { kind: MacHudKind; value: number; muted?: boolean }) => void) => () => void; closed: () => void };
  }
}

export function HudWindow() {
  useSystemAppearance();
  const { hud, show } = useMacHud();
  useEffect(() => window.hud.onLevel(({ kind, value, muted }) => show(kind, value, { muted })), [show]);
  return <MacHud {...hud} position="none" material="native" radius={10} onExitComplete={window.hud.closed} />;
}
```

## API reference

### MacHud

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | | Show the HUD. Keep it mounted and toggle this so the exit animates; `useMacHud` drives it. |
| `kind` | `"volume" \| "brightness" \| "keyboard"` | | Which level it shows: picks the icon and the announcement. |
| `value` | `number` | | The level, 0 to 1, drawn in quarter segments (macOS's finest step, ⌥⇧ with a media key). |
| `muted` | `boolean` | `false` | Volume only: speaker with a slash, empty bar. |
| `variant` | `"classic" \| "pill"` | `"classic"` | The 200×200 square of macOS 15 and earlier, or the 200×44 capsule of macOS 26. |
| `position` | `"fixed" \| "absolute" \| "none"` | `"fixed"` | Against the viewport, in the nearest positioned parent, or in flow for you to place (a Tauri HUD window). |
| `material` | `"css" \| "native"` | `"css"` | `native` drops the CSS blur and tint for a window that draws real vibrancy. |
| `radius` | `number` | `18`, or a capsule for `pill` | Corner radius, px. Match a native window's corner: `10` in Electron. |
| `onExitComplete` | `() => void` | | Called when the exit animation has finished (not on a variant swap): hide a native HUD window here. |
| `labels` | `{ volume?, brightness?, keyboard?, muted?: string }` | `"Volume"`, `"Brightness"`, `"Keyboard brightness"`, `"muted"` | Translate the announcement. |
| `className` | `string` | `""` | Appended to the HUD's classes; position is kept. |

### useMacHud

`useMacHud({ duration? })` returns `{ hud, show, hide }`. `show(kind, value, { muted? })` opens or updates the HUD and restarts the hold; `hide()` closes it at once. `duration` is the hold after the last `show`, in ms (default `1100`). Spread `hud` onto `<MacHud>`.

### useSystemAppearance

From `@/components/eased/lib/mac`. Call it once in a Tauri or Electron HUD window: it puts `.dark` on `<html>` while `prefers-color-scheme` is dark and follows changes, so the glyphs match the native vibrancy. It runs in an effect, so it is safe with server rendering. Eased otherwise follows `.dark` or `data-theme="dark"`, so a web app keeps its own theme toggle.

### MacHudIcon

The HUD's glyphs on their own, for media keys and menus: `<MacHudIcon kind="volume" value={1} className="size-4" />`. Takes `kind`, `value`, `muted` and `className`; colour is `currentColor`.

## Accessibility

- A `role="status"` live region, mounted before the HUD first shows, announces each change ("Volume 60%", "Volume, muted"), so screen readers hear the level without focus moving.
- The visual HUD is `aria-hidden` and ignores the pointer: it never takes focus or blocks a click on what is under it.
- It never holds the only copy of information: the level lives in your app, and the HUD only reflects it.

## Motion

The HUD fades in on the enter curve while it scales from 0.96 on the snappy spring; the pill also drops 10px. It leaves in 150ms on the ease-in curve to 0.98 (the pill rises 6px), with no overshoot. While it is up, a new value never replays the entrance: classic segments snap in 100ms, the pill's bar slides on the smooth spring, and icon changes (a wave, the mute slash, longer sun rays) fade and un-blur on the text-swap tokens; a new kind swaps the whole glyph. Changing `variant` while it is up swaps one HUD for the other, without a morph. Reduced motion keeps 100ms opacity fades only and moves the bar at once.

## Notes for AI

Use Mac HUD for transient feedback on a level changed by a shortcut or media key in a Mac-style app. Call `show` from `useMacHud` on every change, including repeats; render one HUD per window with `{...hud}` spread onto it. In Tauri or Electron, render it with `material="native"` and `position="none"` in a 200×200 vibrancy window that ignores the pointer and can't take focus, with a transparent page and `useSystemAppearance()`; hide the window in `onExitComplete`.

Do not unmount it to hide it, do not add a timer of your own (the hook owns the 1.1-second hold), and do not put controls in it: it is click-through. Do not give it a drop shadow, or a different radius except to match a native window's corner (`radius={10}` in Electron).

## Related

- [Undo Pill](/components/undo-pill): a transient pill people can act on.
- [Segmented](/components/segmented): the classic and pill switch in the demo.
- [Button](/components/button): the media keys in the demo.

## Example

`components/eased/mac-hud/mac-hud-demo.tsx`

```tsx
"use client";

import { useCallback, useEffect, useRef, useState, type KeyboardEvent, type ReactNode } from "react";
import { Button } from "../button/button";
import { MacDesktop } from "../lib/mac-desktop";
import { Segmented } from "../segmented/segmented";
import { MacHud, MacHudIcon, useMacHud, type MacHudKind, type MacHudVariant } from "./mac-hud";

type Levels = Record<MacHudKind, number> & { muted: boolean };

const VARIANTS = [
  { value: "classic", label: "Classic" },
  { value: "pill", label: "Pill" },
] as const;

// macOS moves a level one segment (1/16) per press, or a quarter segment with ⌥⇧ held.
const QUARTERS = 64;
// Close to macOS's default key repeat: a pause, then about twelve steps a second.
const DELAY = 400;
const REPEAT = 80;

/*
 * The keys sit 6px apart, so a mouse gets the 32px key alone. On touch they take the 44px
 * target: neighbours' areas meet only in the gap, never over each other's key.
 */
const TOUCH_TARGET = "pointer-coarse:hit-area";

const ARROWS: Record<string, [MacHudKind, 1 | -1]> = {
  ArrowUp: ["volume", 1],
  ArrowDown: ["volume", -1],
  ArrowRight: ["brightness", 1],
  ArrowLeft: ["brightness", -1],
};

export function MacHudDemo() {
  const [variant, setVariant] = useState<MacHudVariant>("classic");
  const { hud, show } = useMacHud();
  const levels = useRef<Levels>({ volume: 0.5, brightness: 0.75, keyboard: 0.5, muted: false });
  const hold = useHold();

const showLevel = useCallback(
    (kind: MacHudKind) => {
      const l = levels.current;
      show(kind, l[kind], { muted: kind === "volume" && l.muted });
    },
    [show],
  );

// Pressing a volume key unmutes, as on a Mac.
  const nudge = useCallback(
    (kind: MacHudKind, dir: 1 | -1, fine = false) => {
      const l = levels.current;
      l[kind] = Math.min(QUARTERS, Math.max(0, Math.round(l[kind] * QUARTERS) + dir * (fine ? 1 : 4))) / QUARTERS;
      if (kind === "volume") l.muted = false;
      showLevel(kind);
    },
    [showLevel],
  );

const mute = () => {
    levels.current.muted = !levels.current.muted;
    showLevel("volume");
  };

const key = (kind: MacHudKind, dir: 1 | -1) => (fine: boolean) => nudge(kind, dir, fine);

return (
    <MacDesktop
      app="Music"
      menus={["File", "Edit", "Song", "View"]}
      footer={
        <div className="flex shrink-0 items-center justify-between gap-3 border-t border-line-subtle px-(--pad) py-3">
          <Segmented
            aria-label="HUD style"
            // Segments are 26px tall; on touch each gets the 44px target without growing.
            className="pointer-coarse:[&>button]:hit-area"
            options={VARIANTS}
            value={variant}
            onValueChange={(v) => {
              setVariant(v);
              showLevel(hud.kind);
            }}
          />
          <div className="flex items-center gap-2" onKeyDown={onKeyDown}>
            <KeyGroup label="Display brightness">
              <MediaKey label="Brightness down" hold={hold} onPress={key("brightness", -1)}>
                <MacHudIcon kind="brightness" value={0} className="size-4" />
              </MediaKey>
              <MediaKey label="Brightness up" hold={hold} onPress={key("brightness", 1)}>
                <MacHudIcon kind="brightness" value={1} className="size-4" />
              </MediaKey>
            </KeyGroup>
            <KeyGroup label="Keyboard brightness" className="@max-sm:hidden">
              <MediaKey label="Keyboard brightness down" hold={hold} onPress={key("keyboard", -1)}>
                <MacHudIcon kind="keyboard" value={0} className="size-4" />
              </MediaKey>
              <MediaKey label="Keyboard brightness up" hold={hold} onPress={key("keyboard", 1)}>
                <MacHudIcon kind="keyboard" value={1} className="size-4" />
              </MediaKey>
            </KeyGroup>
            <KeyGroup label="Volume">
              <Button variant="secondary" size="icon-sm" hitArea={false} className={TOUCH_TARGET} aria-label="Mute" onClick={mute}>
                <MacHudIcon kind="volume" value={0} muted className="size-4" />
              </Button>
              <MediaKey label="Volume down" hold={hold} onPress={key("volume", -1)}>
                <MacHudIcon kind="volume" value={0.3} className="size-4" />
              </MediaKey>
              <MediaKey label="Volume up" hold={hold} onPress={key("volume", 1)}>
                <MacHudIcon kind="volume" value={1} className="size-4" />
              </MediaKey>
            </KeyGroup>
          </div>
        </div>
      }
    >
      {/* The desktop under the menu bar: the pill sits 12px below it, the classic HUD centres. */}
      <div
        tabIndex={0}
        role="group"
        aria-label="Desktop. Arrow keys change volume and brightness, M mutes."
        onKeyDown={onKeyDown}
        className="absolute inset-0 focus-ring [outline-offset:-2px]"
      >
        <MacHud {...hud} variant={variant} position="absolute" />
      </div>
    </MacDesktop>
  );
}

type Hold = ReturnType<typeof useHold>;

/** A media key: fires on press, then repeats while held. Enter repeats through the keyboard's own auto-repeat. */
function MediaKey({ label, hold, onPress, children }: { label: string; hold: Hold; onPress: (fine: boolean) => void; children: ReactNode }) {
  return (
    <Button
      variant="secondary"
      size="icon-sm"
      hitArea={false}
      className={TOUCH_TARGET}
      aria-label={label}
      onPointerDown={(e) => {
        if (e.button !== 0) return;
        const fine = e.altKey && e.shiftKey;
        hold.start(() => onPress(fine));
      }}
      onPointerUp={hold.stop}
      onPointerLeave={hold.stop}
      onPointerCancel={hold.stop}
      // Pointer presses already fired on pointer down; detail 0 is a keyboard click.
      onClick={(e) => {
        if (e.detail === 0) onPress(e.altKey && e.shiftKey);
      }}
      onContextMenu={(e) => e.preventDefault()}
    >
      {children}
    </Button>
  );
}

/** Fire once now, again after DELAY, then every REPEAT ms until stopped. */
function useHold() {
  const timer = useRef<number | undefined>(undefined);
  const stop = useCallback(() => {
    window.clearTimeout(timer.current);
    window.clearInterval(timer.current);
  }, []);
  const start = useCallback(
    (action: () => void) => {
      stop();
      action();
      timer.current = window.setTimeout(() => {
        timer.current = window.setInterval(action, REPEAT);
      }, DELAY);
    },
    [stop],
  );
  useEffect(() => {
    window.addEventListener("blur", stop);
    return () => {
      stop();
      window.removeEventListener("blur", stop);
    };
  }, [stop]);
  return { start, stop };
}
```