# Wingo UI

> Wingo UI is a library of animated, configurable, mobile-first React components and blocks you copy into your project, with a CLI and an MCP server for coding agents. 326 items (218 components, 72 blocks, 17 hooks, 19 helper libraries) for React 19 and Tailwind CSS v4, release 1.7.0. 75 items are free; the rest need a Pro plan.

Components are installed as source you own with the CLI (`npx wingo-ui@latest add <slug>`). Coding agents connect to the MCP server to search components, read props and design rules, and check for updates.

Every item has an HTML docs page (live preview, props, usage) and the same docs as Markdown at the page URL plus `.md`.

- MCP server (Streamable HTTP): https://wingo-ui.com/mcp (send "Authorization: Bearer wui_..." to get any source: a free account key returns free sources, a Pro key Pro sources; search, docs and props work without one)
- JSON registry (shadcn format): https://wingo-ui.com/r/registry.json, https://wingo-ui.com/r/<slug>.json (item with source; Pro items need an API key), https://wingo-ui.com/r/meta/<slug>.json (docs), https://wingo-ui.com/r/versions.json

## About

- What: a commercial React component library. Components, full-screen blocks, page templates, hooks and helpers are copied into your project as TypeScript source (shadcn style), so you own and edit the code.
- Stack: React 19, Tailwind CSS v4, Next.js (App Router) or Vite. Animations use motion; overlays use Radix primitives.
- Built for phones first (bottom sheets instead of popovers, 44px touch targets), light and dark mode, and props for every visual aspect.
- Coding agents: an MCP server, a CLI that writes rule files for Claude Code, Codex, Gemini CLI, Grok and Cursor, and this file. Details: [AI agents](https://wingo-ui.com/ai).

## Pricing

- Free: 75 of 326 items with full source, free forever. Every Pro item can still be previewed and configured on its docs page; only copying its source needs Pro.
- Pro: the source of all 326 items (251 Pro-only), updates and the Pro MCP tools. $8 a month, $80 a year (17% less than paying monthly) or $150 once for lifetime access. Prices in USD.
- License: one license per developer; use the components in unlimited end products, your own or your clients'; no reselling them as a UI kit or library. Copied components stay yours after a subscription ends.
- Refunds: within 14 days of the first purchase. [Pricing and FAQ](https://wingo-ui.com/pricing), [license](https://wingo-ui.com/legal/license), [refund policy](https://wingo-ui.com/legal/refund).

## Docs

- [Installation](https://wingo-ui.com/docs/installation): Set up a project and add components
- [MCP server](https://wingo-ui.com/docs/mcp): Connect your coding agent
- [CLI](https://wingo-ui.com/docs/cli): Every command and flag
- [Coding agents](https://wingo-ui.com/docs/agents): Claude Code, Codex, Gemini CLI, Grok, Cursor
- [Updates](https://wingo-ui.com/docs/updates): Versions, merges and the changelog
- [Theming](https://wingo-ui.com/docs/theming): Tokens, dark mode and themes
- [Components](https://wingo-ui.com/components): browse every item with live, configurable previews
- [Templates](https://wingo-ui.com/templates): whole website pages built from the marketing sections
- [Theme generator](https://wingo-ui.com/theme): brand, neutrals, status colors, radius, font and component defaults, with a live preview and export
- [Changelog](https://wingo-ui.com/changelog): every release ([RSS](https://wingo-ui.com/changelog/rss.xml), [JSON](https://wingo-ui.com/changelog/feed.json))
- [Full docs for language models](https://wingo-ui.com/llms-full.txt): install guide, design rules (tokens, sizes, motion, forms, overlays, mobile) and every item's props and usage in one large file; the same item docs per category are linked under Categories

## Categories

Each category page lists its items with live previews; the full docs of a category (props, parts, usage) are also plain text, in parts of up to 100 KB for the big categories.

- [Buttons & Actions](https://wingo-ui.com/components/category/buttons): 7 items, 3 free ([full docs](https://wingo-ui.com/llms/buttons.txt))
- [Inputs](https://wingo-ui.com/components/category/inputs): 36 items, 11 free (full docs in 4 parts: [1](https://wingo-ui.com/llms/inputs.txt), [2](https://wingo-ui.com/llms/inputs-2.txt), [3](https://wingo-ui.com/llms/inputs-3.txt), [4](https://wingo-ui.com/llms/inputs-4.txt))
- [Forms](https://wingo-ui.com/components/category/forms): 8 items, 1 free ([full docs](https://wingo-ui.com/llms/forms.txt))
- [Navigation](https://wingo-ui.com/components/category/navigation): 19 items, 7 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/navigation.txt), [2](https://wingo-ui.com/llms/navigation-2.txt))
- [Overlays](https://wingo-ui.com/components/category/overlays): 12 items, 7 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/overlays.txt), [2](https://wingo-ui.com/llms/overlays-2.txt))
- [Feedback](https://wingo-ui.com/components/category/feedback): 12 items, 8 free ([full docs](https://wingo-ui.com/llms/feedback.txt))
- [Data Display](https://wingo-ui.com/components/category/data-display): 23 items, 5 free (full docs in 3 parts: [1](https://wingo-ui.com/llms/data-display.txt), [2](https://wingo-ui.com/llms/data-display-2.txt), [3](https://wingo-ui.com/llms/data-display-3.txt))
- [Tables & Lists](https://wingo-ui.com/components/category/tables): 11 items, 1 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/tables.txt), [2](https://wingo-ui.com/llms/tables-2.txt))
- [Charts & Stats](https://wingo-ui.com/components/category/charts): 15 items, 2 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/charts.txt), [2](https://wingo-ui.com/llms/charts-2.txt))
- [Layout](https://wingo-ui.com/components/category/layout): 12 items, 3 free ([full docs](https://wingo-ui.com/llms/layout.txt))
- [Media](https://wingo-ui.com/components/category/media): 15 items, 1 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/media.txt), [2](https://wingo-ui.com/llms/media-2.txt))
- [AI Kit](https://wingo-ui.com/components/category/ai): 16 items, 3 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/ai.txt), [2](https://wingo-ui.com/llms/ai-2.txt))
- [Text & Effects](https://wingo-ui.com/components/category/effects): 1 item, 1 free ([full docs](https://wingo-ui.com/llms/effects.txt))
- [Mobile](https://wingo-ui.com/components/category/mobile): 15 items, 0 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/mobile.txt), [2](https://wingo-ui.com/llms/mobile-2.txt))
- [Commerce](https://wingo-ui.com/components/category/commerce): 16 items, 0 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/commerce.txt), [2](https://wingo-ui.com/llms/commerce-2.txt))
- [Marketing Sections](https://wingo-ui.com/components/category/marketing): 20 items, 6 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/marketing.txt), [2](https://wingo-ui.com/llms/marketing-2.txt))
- [Blocks](https://wingo-ui.com/components/category/blocks): 23 items, 0 free (full docs in 3 parts: [1](https://wingo-ui.com/llms/blocks.txt), [2](https://wingo-ui.com/llms/blocks-2.txt), [3](https://wingo-ui.com/llms/blocks-3.txt))
- [Templates](https://wingo-ui.com/templates): 29 items, 2 free (full docs in 3 parts: [1](https://wingo-ui.com/llms/templates.txt), [2](https://wingo-ui.com/llms/templates-2.txt), [3](https://wingo-ui.com/llms/templates-3.txt))
- [Hooks & Utilities](https://wingo-ui.com/components/category/utilities): 36 items, 14 free (full docs in 2 parts: [1](https://wingo-ui.com/llms/utilities.txt), [2](https://wingo-ui.com/llms/utilities-2.txt))

## Install Wingo UI (Next.js, npm)

Wingo UI components are React 19 + Tailwind CSS v4 source files you own. The CLI copies them into your project with their dependencies and records versions so you can update later.

### 1. A React 19 + Tailwind v4 project

New project:

```bash
npx create-next-app@latest my-app --ts --tailwind --eslint --app --import-alias "@/*"
```

### 2. Initialize

```bash
npx wingo-ui@latest init
```

`init` detects the framework, the `@/*` alias and your global stylesheet (app/globals.css), installs `clsx` and `tailwind-merge`, creates `lib/utils.ts` (the `cn` helper), merges the Wingo UI design tokens into app/globals.css without overwriting your values, and writes `wingo-ui.json` (commit it).

### 3. Add components

```bash
npx wingo-ui@latest add button input card
```

Registry dependencies (shared hooks like `use-controllable-state`, helpers like `lib/motion`) and npm packages come along automatically. Files land in `components/ui`, `components/blocks`, `hooks` and `lib`.

Pro components need a Pro account:

```bash
npx wingo-ui@latest login
```

(opens the browser; on a server use `npx wingo-ui@latest login --key wui_...` with a key from https://wingo-ui.com/account/ai, or set `WINGO_UI_API_KEY`).

### 4. Dark mode and app-wide defaults

Components read the `.dark` class. With Next.js use next-themes:

```bash
npm install next-themes
```

```tsx
// app/layout.tsx
import { ThemeProvider } from "next-themes"
import { UIProvider } from "@/lib/ui-config"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
          <UIProvider defaults={{ button: { radius: "full" } }}>{children}</UIProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}
```

`UIProvider` (item `ui-config`, installed with any component) sets defaults for every component (`defaults={{ input: { variant: "filled" } }}`) and the `locale` for dates and numbers. Explicit props always win.

### 5. Use it

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

export function Save() {
  return <Button tone="brand">Save changes</Button>
}
```

### Stay up to date

```bash
npx wingo-ui@latest outdated   # what changed upstream
npx wingo-ui@latest update     # 3-way merge that keeps your local edits
```

### Coding agents

Connect the MCP server (https://wingo-ui.com/mcp) so Claude Code, Codex, Gemini CLI, Grok or Cursor search components, read props and design rules, and install with the CLI:

```bash
npx wingo-ui@latest agents install
```

### Without the CLI

- shadcn: `npx shadcn@latest add https://wingo-ui.com/r/button.json` (free items). For Pro items add the `@wingo-ui` registry with an `Authorization: Bearer ${WINGO_UI_API_KEY}` header to components.json.
- Manual: copy the files from the component page, install its npm dependencies, add `lib/utils.ts` and the tokens (https://wingo-ui.com/docs/theming).


## Wingo UI design rules

Every Wingo UI component follows these rules; screens you build around them should too, so the app feels like one system.
When a component exists for the job, use it and configure it through props (size, variant, tone, radius, labels) instead of restyling it.
Use semantic tokens only (bg-background, bg-card, text-muted-foreground, border-border, bg-success-soft...) so light and dark mode both work.

### Principles

**Tactile.** Everything you can press answers within one frame: the state layer tints on hover (`hover:before:opacity-[0.08]`), the surface dips to `scale: 0.97` on a snappy spring while pressed, and the focus ring sits 2px off the edge. Nothing pressable is inert-looking.

**Fast.** Animate `transform` and `opacity` only. Entrances take 150 to 300ms, exits are quicker than entrances. No layout thrash, no `setState` per animation frame (use motion values), no JS on scroll unless passive. A component renders its final state on the server; motion is an enhancement.

**Calm.** Neutral by default: every `tone` prop defaults to `neutral` (black in light mode, white in dark mode), including switches, checkboxes, sliders, progress, tabs and selected states. Color only where it carries meaning: status tones for status, brand orange opt-in for the one hero action. One solid action per view. Springs settle without wobble except `bouncy`, which is for rare moments of delight. Copy is short and plain.

**Mobile first.** Design at 360 to 390px, then widen. Touch targets are 44px on coarse pointers. Overlays become bottom sheets below 768px. Tables become cards. Nothing depends on hover. Safe areas are respected on anything pinned to an edge.

### Tokens

Always use semantic tokens so light and dark both work. Hardcoded colors are allowed only as overridable prop defaults.

#### Surfaces (back to front)

| Token | Class | Light | Dark | Use for |
|---|---|---|---|---|
| `--background` | `bg-background` | white | black | the page |
| `--card` | `bg-card` | #EBEBEB | #121212 | flat gray tiles with no shadow, grouped rows |
| `--muted` | `bg-muted` | #F9FAFB | #171717 | large wells on the page background only: code blocks, table header bands. It is nearly invisible on white, so never use it for fields, tracks or skeletons (use the tints below) |
| `--surface` | `bg-surface` + `shadow-raised` | white | #1A1A1A | raised panels on a page: list groups, stat cards, form cards, toolbars |
| `--canvas` | `bg-canvas` | #F6F7F9 | #0E0E10 | the page of an app (dashboards, admin, settings in an `app-shell` inset panel): a cool gray canvas so white / #1A1A1A `bg-surface` cards read as cards. Marketing and docs pages stay on `bg-background` |
| `--popover` | `bg-popover` + `shadow-floating` / `shadow-modal` | white | #262626 | everything that floats: popovers, menus, selects, dialogs, sheets, toasts |
| `--primary` | `bg-primary text-primary-foreground` | black | near-white | the neutral solid fill (neutral tone), tooltips |

Each surface has its `-foreground` text token (`text-surface-foreground`, `text-popover-foreground`, `text-card-foreground`); on `bg-background` use `text-foreground`.

#### Tints

Translucent foreground over whatever is behind, so they work on every surface in both themes. Use only these steps:

| Class | Use |
|---|---|
| `bg-foreground/5` | hover on rows, items and ghost controls; the soft field fill; chips; segmented and tab tracks; skeletons; the empty-state icon tile |
| `bg-foreground/7` | hover on a soft field (one step above its fill) |
| `bg-foreground/10` | pressed and selected rows; progress and slider tracks; avatar fallbacks |
| `bg-foreground/15` | the switch track when off; sheet handles; scrollbar thumbs |
| `border-foreground/10` | hairlines on tinted surfaces and between rows |

**Legacy tokens.** `--secondary`, `--accent` (an orange tint here, not shadcn's gray), `--sidebar-*`, `--chart-*` and the `shadow-sm` ... `shadow-2xl` scale exist for the first 21 components and the showcase shell. New components never use `bg-accent`, `bg-secondary` or `bg-muted` on controls: shadcn's `focus:bg-accent` becomes `data-highlighted:bg-foreground/5`, `bg-secondary` becomes `variant="soft"`.

#### Text levels

| Level | Class | Use |
|---|---|---|
| Primary | `text-foreground` (or the surface's `-foreground`) | titles, values, labels |
| Secondary | `text-muted-foreground` | descriptions, helper text, timestamps, placeholders |
| Tertiary / disabled | `text-foreground/45` | disabled labels only; never for text people must read |
| Tone text | `text-{tone}-soft-foreground` | colored text on any surface: an error message, a +12% delta, a link |

`text-muted-foreground` passes AA on every surface in both themes. Never go lighter than it for readable text.

#### Borders and rings

- `border-border` for dividers and input outlines (the base layer sets it as the default border color, so `border` / `border-b` alone is enough).
- `border-foreground/10` for hairlines on tinted surfaces.
- `outline-ring` for the focus outline of pressables (section 7), `ring-ring/50` for fields (section 9). `--ring` is the brand orange, a touch deeper in light mode so a 2px outline keeps 3:1 on white and on `bg-card`.

#### Brand and status tones

| Tone | Tokens | Meaning |
|---|---|---|
| brand | `--brand` #D63F00 (the #FC4C01 family, deep enough for white text) | opt-in with `tone="brand"`: the one hero CTA of a marketing, pricing or checkout screen, brand moments. Never a default |
| success | `--success` | done, paid, online, positive delta |
| warning | `--warning` (amber fill, dark text) | needs attention soon, low stock, expiring |
| destructive (tone `danger`) | `--destructive` | errors, delete, failed, negative delta |
| info | `--info` | neutral news, tips, in progress |

For each tone `X`:

| Token | Class | Use |
|---|---|---|
| `--X` | `bg-X` | solid fill (buttons, solid badges, progress bars, switch on) |
| `--X-foreground` | `text-X-foreground` | text and icons on the solid fill |
| `--X-soft` | `bg-X-soft` | tinted surface (soft badges, alerts, soft buttons, selected rows) |
| `--X-soft-foreground` | `text-X-soft-foreground` | tone text on the soft surface **and on any neutral surface** |

Rules:
- Colored text is always `text-X-soft-foreground`, never `text-X`: fills are tuned for fills (`text-destructive` on a dark card is below AA).
- Borders in a tone: `border-X/40` or the `--tone-border` var (see below).
- The warning fill is light (amber), so it takes dark text. A bare warning dot on white is low contrast: pair it with text or an icon.

#### Tones in components: `lib/tones.ts`

A component with a `tone` prop never maps tokens itself. It sets five CSS vars with `toneClasses[tone]` (or `colorVars(color)` for a custom color) and paints with them:

```
--tone                  bg-(--tone)                     solid fill
--tone-foreground       text-(--tone-foreground)        text on the fill
--tone-soft             bg-(--tone-soft)                tinted surface
--tone-soft-foreground  text-(--tone-soft-foreground)   tone text
--tone-border           border-(--tone-border)          outline / divider
```

```tsx
import { colorVars, toneClasses, type Tone } from "@/lib/tones"

<span className={cn(toneClasses[tone], "bg-(--tone-soft) text-(--tone-soft-foreground)", className)} style={{ ...colorVars(color), ...style }} />
```

`tone="neutral"` maps to `--primary` (black / white). `colorVars` picks black or white text for the fill by lightness and mixes tone text toward the foreground for contrast. A caller can force any var: `className="[--tone-foreground:white]"`.

#### Elevation

| Class | Token | Use |
|---|---|---|
| `shadow-raised` | `--elevation-raised` | solid buttons, `bg-surface` panels, switch thumbs, slider thumbs, segmented thumbs, cards that lift |
| `shadow-floating` | `--elevation-floating` | popovers, menus, selects, hover cards, tooltips, toasts, dragged items |
| `shadow-modal` | `--elevation-modal` | dialogs, sheets, drawers, command palette |

Every level carries its own hairline (light: a 1px 5% black ring; dark: a 1px white ring plus a lit top edge), so elevated surfaces need no `border`. The old `shadow-sm` ... `shadow-2xl` still exist for existing components; new code uses the three levels above.

#### Stacking layers

| Class | Value | Use |
|---|---|---|
| `z-dropdown` | 1000 | in-flow floating panels that are not portaled (an inline autocomplete list) |
| `z-sticky` | 1100 | sticky headers, bottom tab bars, sticky CTA bars |
| `z-overlay` | 1200 | the dimmed backdrop behind dialogs and sheets (vaul `Drawer.Overlay` too) |
| `z-modal` | 1300 | dialog, alert dialog, sheet and drawer content (vaul `Drawer.Content` too) |
| `z-popover` | 1400 | every portaled popover, dropdown menu, context menu, select, combobox, hover card (above modals, so a select inside a dialog works) |
| `z-toast` | 1500 | toasts and snackbars |
| `z-tooltip` | 1600 | tooltips, always on top |

Never use raw `z-50` style numbers in library code.

#### Radius

**Trap:** the legacy `--radius` (6px) remaps Tailwind's `rounded-sm`, `rounded-md`, `rounded-lg` and `rounded-xl` to 2 / 4 / 6 / 10px for the ported components. New components never use those four classes. Controls take the per-size map from section 4 (copy the `RADII` map from `button.tsx` verbatim), surfaces use the table below, anything else uses an explicit `rounded-[Npx]`. `rounded-2xl` (16px), `rounded-3xl` (24px) and `rounded-full` keep Tailwind's values and are fine.

| Surface | Radius |
|---|---|
| cards, list groups, popovers, menus, selects, hover cards, toasts | `rounded-2xl` (16px) |
| dialogs, large panels, demo cards | `rounded-3xl` (24px) |
| bottom sheets | `rounded-t-[28px]` |
| tooltips, kbd, small tags inside text | `rounded-[8px]` / `rounded-[5px]` |
| anything inside a padded surface | the outer radius minus the padding: a `rounded-2xl p-1.5` menu has `rounded-[10px]` items, a `rounded-[10px] p-0.5` segmented track has a `rounded-[8px]` thumb |

A surface with a `radius` prop (card, dialog, sheet, popover) maps `none` `rounded-none`, `sm` `rounded-[12px]`, `md` `rounded-2xl`, `lg` `rounded-3xl`; `full` falls back to `lg`. Cards and popovers default to `md`, dialogs to `lg`.

#### CSS motion tokens

For CSS transitions (colors, opacity, simple transforms) that do not go through `motion/react`:

| Class | Value | Use |
|---|---|---|
| `duration-fast` | 150ms | hover, color, state layers, press release |
| `duration-normal` | 240ms | small enter / exit |
| `duration-slow` | 400ms | large surfaces |
| `ease-smooth` | cubic-bezier(0.22, 1, 0.36, 1) | the default curve for everything above |
| `ease-smooth-in-out` | cubic-bezier(0.65, 0, 0.35, 1) | moving between two on-screen states |
| `ease-sheet` | cubic-bezier(0.32, 0.72, 0, 1) | sheets and drawers |
| `ease-spring` + `duration-spring` | springs.smooth as `linear()`, 500ms | CSS-only transforms that should feel like the smooth spring |
| `ease-snappy` + `duration-snappy` | springs.snappy as `linear()`, 450ms | CSS-only press / toggle transforms |

### Typography and spacing

Font: `font-sans` (Inter), inherited. Do not hardcode a font family in a component; `font-runde` is only for display numerals and titles in demos. Numbers that change or align get `tabular-nums`.

| Role | Classes |
|---|---|
| Display (hero numbers, page titles in demos) | `text-[32px] leading-[1.05] font-bold tracking-[-0.03em]` (`md:text-5xl`) |
| Title (dialog, sheet, page header) | `text-lg font-semibold tracking-tight` (18px) |
| Heading (card, section, list group) | `text-[15px] font-semibold tracking-tight` |
| Body | `text-sm leading-relaxed` (14px); reading content `text-[15px]` |
| Label (form labels, button md, menu items) | `text-sm font-medium` (menu items `text-sm` regular) |
| Small label (button sm, chips, tabs sm) | `text-[13px] font-medium` |
| Caption (helper, meta, timestamps, field errors) | `text-xs text-muted-foreground` (12px) |
| Eyebrow | `text-[11px] font-semibold uppercase tracking-[0.12em] text-muted-foreground` |
| Mono (ids, code, keys) | `font-mono text-[12.5px]` |
| Text inputs | `text-base md:text-sm` (16px on phones so iOS never zooms) |

`cn()` is tailwind-merge: a `text-*` size removes a `leading-*` that comes before it. Put line height after the size or in the same class (`text-sm/6`).

Spacing is a 4px grid (`--spacing: 0.25rem`):

- icon to label: `gap-1.5` (sm) / `gap-2` (md, lg)
- controls in a row: `gap-2`; groups of controls: `gap-3`
- inside a panel: `p-4` on phones, `sm:p-5` or `p-6` on larger screens
- label to field: `gap-1.5`; field to field: `gap-4`
- between sections: `gap-6` to `gap-8`; page sections `py-12 md:py-16`
- phone gutters: `px-4` (16px); adjacent touch targets at least 8px apart

### Sizes

`size="sm" | "md" | "lg"`, default `md`. Every control with a height uses this table so a button, an input and a select line up: button, toggle, toggle group, segmented control, tabs (pill and segmented variants), input and every field trigger (select, combobox, date / time pickers, color picker), number stepper buttons, pagination buttons.

| | sm | md | lg |
|---|---|---|---|
| Height | 32px `h-8` | 40px `h-10` | 48px `h-12` |
| Height on coarse pointers | 32px + 44px hit area | **44px** `pointer-coarse:h-11` | 48px |
| Horizontal padding (buttons) | `px-3` | `px-4` | `px-5` |
| Horizontal padding (fields) | `px-2.5` | `px-3` | `px-3.5` |
| Font | `text-[13px]` | `text-sm` (14px) | `text-[15px]` |
| Font in text fields | `text-base md:text-[13px]` | `text-base md:text-sm` | `text-base md:text-[15px]` |
| Icon | 14px `size-3.5` | 16px `size-4` | 18px `size-[18px]` |
| Gap | `gap-1.5` | `gap-2` | `gap-2` |
| Square (icon-only) | `size-8` | `size-10` (`pointer-coarse:size-11`) | `size-12` |

Hit area without changing the look (sm on touch): `pointer-coarse:after:absolute pointer-coarse:after:inset-x-0 pointer-coarse:after:-inset-y-1.5` on a `relative` element (square: `pointer-coarse:after:-inset-1.5`). Unsized icons follow the size with `[&_svg:not([class*='size-'])]:size-4`.

Radius per size (`radius` prop, default `md`):

| radius | sm | md | lg |
|---|---|---|---|
| none | 0 | 0 | 0 |
| sm | 6px | 8px | 10px |
| md | 8px | 10px | 12px |
| lg | 10px | 14px | 16px |
| full | pill | pill | pill |

#### Selection controls

| | sm | md | lg |
|---|---|---|---|
| Checkbox / radio box | 16px `size-4` | 18px `size-[18px]` | 20px `size-5` |
| Checkbox radius | `rounded-[4px]` | `rounded-[5px]` | `rounded-[6px]` |
| Check / dot icon | 12px | 14px | 16px |
| Switch track | 32 x 18 `h-[18px] w-8` | 40 x 24 `h-6 w-10` | 48 x 28 `h-7 w-12` |
| Switch thumb (2px inset) | 14px | 20px | 24px |
| Slider track / thumb | 4px / 16px | 6px / 20px | 8px / 24px |

- Off: checkbox and radio `border-[1.5px] border-foreground/30 bg-transparent`; switch track `bg-foreground/15`; slider track `bg-foreground/10`.
- On: `bg-(--tone) text-(--tone-foreground)` (checkbox, radio, switch track, slider range), so `tone` and `color` work like the button's. The switch thumb is `bg-white shadow-raised`, and `bg-(--tone-foreground)` while checked (in dark mode the neutral track is white, so the thumb turns dark).
- The thumb and the check mark move on `springs.snappy`; the check draws with `pathLength`.
- The label sits to the right and the whole row is the target: wrap control and text in a `<label>` with `min-h-11` on coarse pointers (`pointer-coarse:min-h-11`).

#### Rows and items

| Row | Height |
|---|---|
| menu item, select option, combobox / command item, dense list row | 36px `h-9`, 44px `pointer-coarse:h-11` |
| item with a description or an avatar | `min-h-14` (56px) with `py-2` |
| menu row inside a bottom sheet | 48px `h-12` |
| list group row on a page (settings, contacts) | `min-h-14`, 44px minimum on every pointer |
| table row (desktop) | `h-12`; below 768px the table becomes cards (section 12) |

### Prop conventions

Every visual aspect is a prop with a default, and the zero-prop render looks finished. Use these names and value sets; do not invent synonyms.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | add `"icon-sm" \| "icon" \| "icon-lg"` only for square buttons |
| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "link"` | depends | only the values that make sense for the component; fields use `"soft" \| "outline" \| "ghost"` (section 9) |
| `tone` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | every component, selection controls included; through `lib/tones.ts` |
| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | controls: mapped per size (section 4); surfaces: section 2 |
| `color` / `accent` | `string` (any CSS color) | none | `color` replaces the tone (`colorVars`); `accent` for a secondary highlight (selection, indicator) |
| `leftIcon` / `rightIcon` | `ReactNode` | none | icons inside a control: button, input, select trigger, badge, tag. Unsized svgs follow the size |
| `icon` | `ReactNode` | per component | the one leading icon of an item, alert, toast, empty state or menu row |
| `prefix` / `suffix` | `ReactNode` | none | text addons inside a field: `https://`, `$`, `kg` |
| `label` / `description` / `error` | `ReactNode` | none | form controls render the field anatomy (section 9) when any is set; a truthy `error` also sets `invalid` |
| `shortcut` | `string` | none | a key combo in `mod+k` notation, shown with the Kbd look and bound where it makes sense (section 14) |
| `options` / `items` | `Option[]` / `Item[]` | none | `options` for value pickers (select, combobox, radio group, segmented, toggle group), `items` for menus, navigation and lists; shapes below |
| `classNames` | `Partial<Record<Slot, string>>` | none | one key per inner part; `className` stays for the root. Reuse these keys where the part exists: `trigger`, `content`, `overlay`, `header`, `title`, `description`, `body`, `footer`, `close`, `item`, `icon`, `label`, `input`, `error`, `indicator`, `track`, `thumb`, `spinner` |
| labels | `string` / `ReactNode` | English | every visible string is a prop: `placeholder`, `emptyText`, `loadingText`, `closeLabel`, `clearLabel`, `labels={{ next, previous }}` for groups of strings |
| `locale` | `string` | `undefined` (the user's) | numbers, dates and currency go through `Intl` with this locale; demos use `en-US` (USD, `M/d/yyyy`); a localization demo may offer other locales (`de-DE`, `ro-RO`) as options |
| `disabled`, `loading`, `invalid`, `readOnly`, `required` | `boolean` | `false` | see state conventions |
| `responsive` | `boolean` | `true` | overlays only: sheet below 768px |
| `side` / `align` / `sideOffset` | Radix values | `"bottom"` / `"start"` for menus and selects, `"center"` for popovers and tooltips / `8` (tooltips `6`) | overlays |
| durations | `number` (ms) | from `lib/motion` | only when a timing is part of the design (autoplay interval, toast duration); spring feel is not a prop |
| `asChild` | `boolean` | `false` | through `@radix-ui/react-slot` |

State props match Radix names: `value` / `defaultValue` / `onValueChange` for anything with a value, `open` / `defaultOpen` / `onOpenChange` for overlays and disclosures, `checked` / `defaultChecked` / `onCheckedChange` for checkbox and switch, `pressed` / `defaultPressed` / `onPressedChange` for toggles. New components always use `onValueChange(value)`; text inputs additionally pass the native `onChange` event through untouched (`OtpInput`'s `onChange(value)` predates this rule).

Option and item shapes (each component exports its own named type with this structure, e.g. `SelectOption`):

```ts
// value pickers: select, combobox, multi-select, radio group, segmented control, toggle group, tabs
type Option = { value: string; label: ReactNode; description?: ReactNode; icon?: ReactNode; disabled?: boolean; keywords?: string[] }
// menus: an item runs an action or navigates
type MenuItem = { label: ReactNode; icon?: ReactNode; shortcut?: string; onSelect?: () => void; href?: string; disabled?: boolean; tone?: "neutral" | "danger" }
// groups, wherever a list can be grouped
type Group<T> = { label?: ReactNode; items: T[] }
```

Values are strings (multi-value components use `string[]`); `keywords` feed filtering.

### API rules

- **Controlled and uncontrolled** through `useControllableState({ value, defaultValue, onChange })` from `@/hooks/use-controllable-state`. Never hand-roll `value === undefined ? internal : value`.
- **asChild** through `Slot` / `Slottable` from `@radix-ui/react-slot`. With motion, wrap once at module scope: `const MotionSlot = motion.create(Slot)`.
- **ref is a regular prop** (React 19). Type props as `ComponentProps<"button">` & your own; no `forwardRef`.
- **className** merges last: `cn(BASE, variantClasses, sizeClasses, className)`. Inner parts get `classNames?.part`.
- **data-slot on every part**: the root `data-slot="button"`, parts `data-slot="button-icon"`, `data-slot="dialog-content"` (kebab-case, component name first). State goes in data attributes: `data-state="open|closed|checked|unchecked|on|off|active"`, `data-disabled`, `data-loading`, `data-invalid`, `data-variant`, `data-tone`, `data-size`, `data-side`, `data-orientation`.
- **Spread the rest** onto the root (`{...props}`) so `id`, `aria-*`, `data-*` and handlers work. Destructure what you consume.
- **Defaults in the signature** (`size = "md"`), not in the body, so the audit can read them.
- **Exports:** the component by name (`export function Button`), its props type (`ButtonProps`), and the union types (`ButtonVariant`, `ButtonSize`). `export default` is optional; set `meta.defaultExport` to match.
- **Imports:** only `@/components/ui/*`, `@/hooks/*`, `@/lib/*` and npm packages. No `next/*` in library code (links via `asChild`), no relative imports. Import another `components/ui` file only when it already exists in the registry (build against what is there, not against a sibling being written in parallel).
- `"use client"` only in files that use hooks, events or motion components.
- SSR-safe: no `window` / `document` at module scope or during render. Media queries through `useMediaQuery` (it returns the server fallback during hydration).
- Guard unknown enum values from the outside (`SIZES[size] ?? SIZES.md`) so a CMS string never crashes a render.

#### Composition

Simple props API first, compound parts for advanced use, both from the same file:

```tsx
// the 90% case: one element, props for every piece
<Dialog trigger={<Button>Delete</Button>} title="Delete listing?" description="This cannot be undone." footer={...} />

// the rest: exported parts (Radix naming), each with its data-slot
<DialogRoot><DialogTrigger asChild>...</DialogTrigger><DialogContent>...</DialogContent></DialogRoot>
```

Parts are named `<Name>Root`, `<Name>Trigger`, `<Name>Content`, `<Name>Item`, `<Name>Header`, `<Name>Footer`... The simple component is built from the parts, never duplicated.

### State conventions

| State | How |
|---|---|
| Hover | a state layer: `before:absolute before:inset-0 before:rounded-[inherit] before:bg-current before:opacity-0 hover:before:opacity-[0.08]` with `before:transition-opacity before:duration-fast`. Tailwind's `hover:` only fires where hover exists, so taps never leave it stuck. Rows and items: `hover:bg-foreground/5`. |
| Press | `whileTap={{ scale: 0.97 }}` on `springs.snappy` (spread `press` from `@/lib/motion`), off under reduced motion, plus `active:before:opacity-[0.12]`. Large surfaces (cards) scale to 0.98. |
| Focus | pressables: `outline-hidden focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-ring`. The outline sits 2px off the edge, follows the radius and never fights a box-shadow. (Tailwind v4's `outline-hidden` sets the style to none, so `outline-solid` is required.) Fields use the field ring on the box (section 9). Items inside menus and listboxes show focus with the `data-highlighted` background, not an outline. |
| Disabled | `disabled` attribute on native controls, `aria-disabled` + `tabIndex={-1}` on links; style with `data-disabled:pointer-events-none data-disabled:opacity-50`. |
| Loading | `aria-busy`, `aria-disabled`, keep focus, keep the width (label and spinner share one grid cell: `grid [grid-template-areas:'stack'] *:[grid-area:stack]`, label `opacity-0`), ignore clicks in the handler. Content with a known shape shows skeletons instead of a spinner: `animate-pulse bg-foreground/5` blocks with the real content's height and radius. |
| Invalid | `aria-invalid` on the native control, `data-invalid` on the field box, the message below (section 9) linked with `aria-describedby`. |
| Selected / open / checked | a data attribute from Radix or set by hand (`data-state="checked"`), styled with `data-[state=checked]:bg-(--tone)`. |
| Empty | never a blank box: an icon in a `size-12 rounded-2xl bg-foreground/5` tile, one line of text, and an action when there is one. |

### Motion

Import from `motion/react`, presets from `@/lib/motion`.

| Preset | Use |
|---|---|
| `springs.snappy` (500 / 32) | press, toggles, switch thumbs, checkmarks, small indicators |
| `springs.smooth` (300 / 30) | the default: popovers, menus, tab indicators, `layout` changes, dialogs |
| `springs.bouncy` (400 / 18) | rare delight: a like, a badge popping in, a success tick |
| `springs.gentle` (120 / 20) | large surfaces: sheets settling, chart bars, page sections |
| `presets.overlay` | dialog / sheet backdrop fade |
| `presets.popover` | popovers, menus, selects, hover cards (set `transformOrigin` from Radix) |
| `presets.tooltip` | tooltips |
| `presets.dialog` | centered dialogs and alert dialogs |
| `presets.sheet`, `sheetFrom(side)` | sheets and drawers (on phones prefer vaul, which handles drag) |
| `presets.fade` | content swaps: tab panels, steps, empty to filled, a field error appearing |
| `presets.listItem` | rows entering / leaving (with `layout`) |
| `presets.toast` | toasts |
| `presets.collapse` | accordion, collapsible and expandable-row content (height to `auto`) |
| `press` | the shared press feedback |
| `staggerChildren(step)` + `staggerItem` | lists revealing in sequence (0.03 to 0.05s steps); `staggerDelay(i)` for items that animate on their own |
| `gestures`, `shouldComplete`, `rubberband` | drags, swipes, long presses: shared thresholds (a drag completes past 25% of the surface or on a 400px/s flick, like vaul), `dragElastic={gestures.elastic}`, long press after `gestures.longPress` ms |

Rules:
- Animate `transform` (`x`, `y`, `scale`, `rotate`) and `opacity` only. The one exception is disclosure content with `presets.collapse` on an `overflow-hidden` wrapper (padding goes on its child). Anything else that changes size animates with `layout` (`transition={{ layout: springs.smooth }}`), never `height` from JS per frame.
- Exits are quicker than entrances (presets already do this). Nothing takes longer than 400ms to become usable.
- Follow the finger with motion values (`useMotionValue`, `useTransform`, `drag`), never `setState` per frame. Decide the end of a drag with `shouldComplete(offset, velocity, size)` so every swipe in the library commits at the same point.
- `layoutId` for indicators that move between items (tabs, segmented controls); `layout="position"` on rows with text so it does not stretch.
- `will-change` only while something is animating; motion handles it.
- **Reduced motion:** `usePrefersReducedMotion()` (SSR-safe) or `useMotionPreset(name)` / `useMotionTransition(spring)`, which turn movement into a short opacity fade or an instant change. Spinners keep spinning (slower). Do not use motion's `useReducedMotion` directly: it reads the media query during the first render and breaks hydration.
- Autoplaying loops stop when `isThumbnail` (demos) and when the element is off screen (`useInView`).

#### Radix + AnimatePresence

Radix unmounts closed content, so exits need `forceMount` and a presence gate driven by your own `open` state:

```tsx
const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange })
const popover = useMotionPreset("popover")

<PopoverPrimitive.Root open={open} onOpenChange={setOpen}>
  <PopoverPrimitive.Trigger asChild>{trigger}</PopoverPrimitive.Trigger>
  <AnimatePresence>
    {open && (
      <PopoverPrimitive.Portal forceMount>
        <PopoverPrimitive.Content forceMount asChild sideOffset={8} collisionPadding={12}>
          <motion.div
            {...popover}
            data-slot="popover-content"
            style={{ transformOrigin: "var(--radix-popover-content-transform-origin)" }}
            className="z-popover w-72 max-w-[calc(100vw-24px)] rounded-2xl bg-popover p-4 text-popover-foreground shadow-floating outline-hidden"
          >
            {children}
          </motion.div>
        </PopoverPrimitive.Content>
      </PopoverPrimitive.Portal>
    )}
  </AnimatePresence>
</PopoverPrimitive.Root>
```

The same shape works for Dialog (overlay + content, `presets.overlay` / `presets.dialog`), DropdownMenu (`--radix-dropdown-menu-content-transform-origin`), Select (`position="popper"`, `--radix-select-content-transform-origin`), HoverCard and Tooltip.

### Fields

Every form control uses the same anatomy and the same box, so an input, a select and a date picker in one form are indistinguishable in height, fill, radius and focus.

#### Anatomy

Form controls (input, textarea, the number / password / search / phone / currency inputs, select, combobox, multi-select, tag input, date / time pickers, color picker, file upload, slider, rating) take `label`, `description`, `error` and `required`, and render this when any is set; without them they render the bare control. Checkbox, radio and switch put their label beside the control (section 4). Copy the classes; do not import a sibling field component that is being built in parallel.

```tsx
const generated = useId()
const id = idProp ?? generated
const describedBy = [description && !error && `${id}-description`, error && `${id}-error`].filter(Boolean).join(" ") || undefined

<div data-slot="field" className="flex w-full flex-col gap-1.5">
  <label data-slot="field-label" htmlFor={id} className="text-sm font-medium text-foreground">
    {label}
    {required && <span aria-hidden className="ms-0.5 text-destructive-soft-foreground">*</span>}
  </label>
  {/* the box below; the native control gets id, aria-describedby={describedBy}, aria-invalid={invalid || undefined}, required */}
  {error ? (
    <p data-slot="field-error" id={`${id}-error`} className="text-xs text-destructive-soft-foreground">{error}</p>
  ) : description ? (
    <p data-slot="field-description" id={`${id}-description`} className="text-xs text-muted-foreground">{description}</p>
  ) : null}
</div>
```

The error replaces the description while it shows.

#### The box

```ts
const FIELD =
  "group/field relative flex w-full min-w-0 items-center text-foreground transition-[background-color,border-color,box-shadow] duration-fast ease-smooth focus-within:ring-2 focus-within:ring-ring/50 data-invalid:ring-2 data-invalid:ring-destructive/50 data-disabled:cursor-not-allowed data-disabled:opacity-50"

// variant prop, default "soft" (the lab's own look: a filled well that works on every surface)
const FIELD_VARIANTS = {
  soft: "bg-foreground/5 hover:bg-foreground/7",
  outline: "border border-input bg-transparent focus-within:border-ring data-invalid:border-destructive",
  ghost: "bg-transparent hover:bg-foreground/5", // inline edit, table cells, toolbars
}

const FIELD_SIZES = {
  sm: "h-8 gap-1.5 px-2.5 text-base md:text-[13px]",
  md: "h-10 gap-2 px-3 text-base md:text-sm pointer-coarse:h-11",
  lg: "h-12 gap-2 px-3.5 text-base md:text-[15px]",
}
// radius: the RADII map from button.tsx, same prop, same default ("md": 8 / 10 / 12px)

// the native <input> inside the box
const FIELD_INPUT =
  "h-full min-w-0 flex-1 bg-transparent outline-hidden placeholder:text-muted-foreground disabled:cursor-not-allowed autofill:[transition:background-color_9999s]"
```

- The box, not the native element, carries `data-invalid`, `data-disabled` and the size; the native element carries `id`, `aria-*`, `disabled`, `required`, `inputMode`, `enterKeyHint`, `autoComplete`.
- Icons: `leftIcon` / `rightIcon` in `shrink-0 text-muted-foreground`, sized like the button's (`[&_svg:not([class*='size-'])]:size-4` for md). Text addons: `prefix` / `suffix` in `shrink-0 text-muted-foreground`.
- Trailing actions (clear, show password, steppers) are 28px ghost icon buttons, `<Button variant="ghost" size="icon-sm" radius="full" className="-me-1.5 size-7 pointer-coarse:after:-inset-2">` (a 44px hit area on touch) with a 16px icon and an `aria-label` from a label prop (`clearLabel="Clear"`). Clear shows only while there is a value.
- Triggers (select, combobox, date picker) are a `<button>` with the same box: value or placeholder `truncate` on the left, a `ChevronDown` (`size-4 text-muted-foreground`) on the right that turns 180 degrees while open (`group-data-[state=open]/field:rotate-180 transition-transform duration-fast`).
- Textarea: the same box with `h-auto min-h-20 items-start py-2` (sm `py-1.5`, lg `py-3`); the textarea gets `field-sizing-content resize-none` and a `maxRows`-based `max-h` so it grows with the text.
- `readOnly`: no hover tint, `cursor-default`, value still selectable.

### Lists, menus and options

#### Floating surfaces

| Surface | Classes |
|---|---|
| dropdown menu, context menu, select, combobox list | `z-popover min-w-48 max-h-(--radix-<name>-content-available-height) overflow-y-auto overscroll-contain rounded-2xl bg-popover p-1.5 text-popover-foreground shadow-floating outline-hidden`; select and combobox add `min-w-(--radix-<name>-trigger-width)` |
| popover, hover card | `z-popover w-72 max-w-[calc(100vw-24px)] rounded-2xl bg-popover p-4 text-popover-foreground shadow-floating outline-hidden` |
| tooltip | `z-tooltip max-w-64 rounded-[8px] bg-primary px-2 py-1 text-xs font-medium text-primary-foreground shadow-floating`: inverted in both themes, `sideOffset={6}`, `delayDuration={300}`, each tooltip wraps its own `TooltipProvider` so it works without setup |
| toast | `z-toast rounded-2xl bg-popover p-4 text-popover-foreground shadow-floating` |

Positioning: `sideOffset={8}` (tooltips 6), `collisionPadding={12}`, menus and selects `align="start"`, popovers and tooltips `align="center"`. Select uses `position="popper"`. Transform origin from the Radix var; motion from `presets.popover` / `presets.tooltip`.

#### Items

```ts
const ITEM =
  "relative flex h-9 w-full cursor-pointer select-none items-center gap-2.5 rounded-[10px] px-2.5 text-sm outline-hidden transition-colors duration-fast pointer-coarse:h-11 data-highlighted:bg-foreground/5 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
```

- Leading `icon`: `text-muted-foreground`.
- With a description: `h-auto min-h-9 items-start py-2`; label `text-sm`, description `text-xs text-muted-foreground`.
- Selected (select, combobox, radio items): a trailing `<Check className="ms-auto size-4" />`. Multi-select and checkbox items: a leading sm checkbox (section 4).
- `shortcut`: trailing `ms-auto ps-4 text-xs tracking-[0.08em] text-muted-foreground` in the platform's notation (section 14).
- Danger (`tone: "danger"`): `text-destructive-soft-foreground data-highlighted:bg-destructive-soft`, the icon takes the same color.
- Submenu trigger: a trailing `ChevronRight` (`ms-auto size-4 text-muted-foreground`).
- Group label: `px-2.5 pt-2 pb-1 text-xs font-medium text-muted-foreground`. Separator: `-mx-1.5 my-1.5 h-px bg-foreground/10`.
- Empty: `py-6 text-center text-sm text-muted-foreground` with an `emptyText` prop (default `"No results"`).
- A search box at the top of a list (combobox, command menu) is a `flex h-11 items-center gap-2 border-b border-foreground/10 px-3` row holding a borderless `FIELD_INPUT` and a `Search` icon; the content then drops its padding and the list below keeps `p-1.5`.
- Type-ahead, arrow keys, Home / End and Enter come from Radix (or `cmdk`); do not re-implement them. `cmdk` marks the active item with `data-selected="true"`, so its items use `data-[selected=true]:bg-foreground/5` in place of `data-highlighted:`.

#### In a bottom sheet

The same items at `h-12 rounded-[12px] px-3 text-[15px]`, 16px icons, `active:bg-foreground/5` as the pressed state (no highlight on touch), groups separated by `my-2 h-px bg-foreground/10`.

#### Lists on a page

- A list group is a `rounded-2xl bg-surface shadow-raised` panel with `divide-y divide-foreground/10` rows (the iOS inset grouped list).
- Row: `flex min-h-14 items-center gap-3 px-4 py-2.5`; title `text-[15px] font-medium`, subtitle `text-[13px] text-muted-foreground`, trailing value `text-sm text-muted-foreground tabular-nums`, navigation rows end in a `ChevronRight` (`size-4 text-muted-foreground`).
- Interactive rows: `hover:bg-foreground/5 active:bg-foreground/10`, first and last rows inherit the group's radius (`first:rounded-t-[inherit] last:rounded-b-[inherit]`).

### Overlays

- Primitives: `@radix-ui/react-*` (dialog, alert-dialog, popover, hover-card, dropdown-menu, context-menu, tooltip, select...). They bring focus management, dismiss on Escape / outside click, `aria-*` and portal handling. Do not rebuild them.
- Portaled content always gets a z-layer class (section 2) and `collisionPadding={12}`. Surface classes are in section 10.
- **Responsive rule:** below 768px (`useIsMobile()`), popover, select, dropdown menu, context menu and dialog render as a vaul bottom sheet by default. The `responsive` prop (default `true`) opts out. Tooltips never become sheets (they do not exist on touch; show the text inline or on long press instead). Hover cards open on tap as a sheet. Alert dialogs stay centered (section below).
- Sheet anatomy (vaul `Drawer`):
  - overlay: `fixed inset-0 z-overlay bg-black/40` (dark: `dark:bg-black/60`)
  - content: `fixed inset-x-0 bottom-0 z-modal flex max-h-[92dvh] flex-col rounded-t-[28px] bg-popover text-popover-foreground shadow-modal outline-hidden`
  - handle: `mx-auto mt-2.5 h-1.5 w-10 shrink-0 rounded-full bg-foreground/15`
  - title row: `px-5 pt-3 pb-2 text-[17px] font-semibold`, description under it `px-5 text-sm text-muted-foreground`; body: `min-h-0 flex-1 overflow-y-auto overscroll-contain px-5`, with `pb-[max(env(safe-area-inset-bottom),16px)]` when there is no footer
  - footer (actions): `flex flex-col gap-2 border-t border-foreground/10 px-5 pt-3 pb-[max(env(safe-area-inset-bottom),16px)]`, buttons `size="lg" fullWidth`, primary on top
  - menu rows in a sheet: section 10.
- Dialog (768px and up):
  - overlay: `fixed inset-0 z-overlay bg-black/40 dark:bg-black/60` with `presets.overlay`
  - content: `fixed left-1/2 top-1/2 z-modal flex max-h-[min(85dvh,720px)] w-[calc(100%-32px)] -translate-x-1/2 -translate-y-1/2 flex-col gap-5 rounded-3xl bg-popover p-6 text-popover-foreground shadow-modal outline-hidden` with `presets.dialog` (Tailwind v4 centers with the `translate` property, which composes with motion's transform). Width by `size`: `sm` `max-w-[400px]`, `md` (default) `max-w-[520px]`, `lg` `max-w-[720px]`.
  - header: `flex flex-col gap-1.5 pe-8`; title `text-lg font-semibold tracking-tight`; description `text-sm text-muted-foreground`
  - body: `-mx-6 min-h-0 flex-1 overflow-y-auto overscroll-contain px-6`
  - footer: `flex flex-col-reverse gap-2 sm:flex-row sm:justify-end`; the primary action is last in the DOM (right on desktop, on top when stacked); buttons `size="md"`
  - close: `<Button variant="ghost" size="icon-sm" radius="full" aria-label={closeLabel}>` with an `X`, at `absolute end-4 top-4`; `closeLabel` defaults to `"Close"`
- Alert dialog: centered at every width (short, must be answered, like an iOS alert), `max-w-[400px]`, no close button, no outside-click dismiss, Escape cancels, initial focus on Cancel (Radix default), footer buttons stacked full width below 640px, the destructive action `tone="danger"`.
- Focus: Radix traps focus in modals and returns it to the trigger on close. Set `onOpenAutoFocus` to focus the first field when a form opens; prevent it (`e.preventDefault()`) for menus opened by pointer if focus would scroll the page.
- Body scroll locks while a modal or sheet is open (Radix and vaul do it; do not add another lock).
- Every overlay closes on Escape, has a visible close affordance on phones (sheet handle, a close button in dialogs), and a real title (`Dialog.Title`, visually hidden with `@radix-ui/react-visually-hidden` if the design has none).

### Mobile rules

- Targets: 44px on coarse pointers (sizes table), 8px between adjacent targets.
- **Layout with CSS, behavior with the hook.** Phone vs desktop layout differences use breakpoints (`md:`), so the server HTML is already right on a phone and nothing jumps after hydration: a table and its cards render both with `hidden md:table` / `md:hidden`, or one grid reflows. `useIsMobile()` is for behavior only: which overlay opens (section 11), drag direction, content rendered after an interaction. It returns `false` on the server.
- Bottom sheets instead of popovers (section 11). Full-screen sheets for long forms.
- Cards instead of tables below 768px: each row becomes a card with the primary field as its title and 2 to 4 secondary fields as label / value pairs; actions move into a row menu.
- No hover-only affordances: anything revealed on hover is always visible on touch (`pointer-coarse:opacity-100`) or reachable by tap / long press. Links are underlined (the button's `link` variant is).
- Safe areas: anything fixed to an edge pads with `env(safe-area-inset-*)`, e.g. `pb-[max(env(safe-area-inset-bottom),12px)]`, `pt-[env(safe-area-inset-top)]`.
- Scroll containers: `overflow-y-auto overscroll-contain` (no scroll chaining into the page), momentum is native; horizontal rails use `snap-x snap-mandatory` and `scroll-px-4`.
- Draggable surfaces set `touch-action` (`touch-pan-y` for horizontal swipes, `touch-none` for free drag) and use `gestures` from `lib/motion`.
- Pressable controls carry `touch-manipulation select-none [-webkit-tap-highlight-color:transparent]` themselves (like the button): consumer projects do not have the lab's global stylesheet.
- Text inputs are 16px on phones; set `inputMode`, `enterKeyHint` and `autoComplete` on every field.
- Viewport units: `dvh` for full-height layouts (`min-h-dvh`), never `vh`.

### Accessibility

- Real elements: `button` for actions, `a` for navigation, `input` / `textarea` / Radix controls for input. No clickable `div`s.
- Every control has an accessible name: visible label, `aria-label` for icon-only buttons (required), `aria-labelledby` for groups.
- Keyboard: Tab reaches everything interactive, Enter / Space activate, Escape closes, arrows move within composite widgets (menus, tabs, radio groups, sliders, grids) with roving tabindex (Radix does this), Home / End jump. Shortcuts: section 14. Document the keys in `interaction`.
- Visible focus on every interactive element (section 7). Never remove an outline without a replacement.
- State to assistive tech: `aria-pressed` (toggle buttons), `aria-expanded` + `aria-controls` (disclosures), `aria-busy` (loading), `aria-invalid` + `aria-describedby` (errors), `aria-current="page"` (navigation), live regions (`aria-live="polite"`, or `role="status"`) for async results and toasts.
- Color is never the only signal: pair status colors with an icon or text; links in running text are underlined.
- Respect `prefers-reduced-motion` (section 8) and never autoplay audio.

### Keyboard shortcuts

- Notation: a `shortcut` prop takes `mod+k`, `shift+mod+p`, `alt+n`, `/`, `escape`. `mod` is Cmd on Apple devices and Ctrl elsewhere.
- Display: Apple glyphs on Apple devices (`⌘K`, `⇧⌘P`, `⌥N`), words elsewhere (`Ctrl+K`). Detect the platform with `useIsApple()` (render) or `isApple()` (handlers) from `@/hooks/use-media-query`: the server and hydration render the non-Apple form, then it swaps. Hide hints on touch (`pointer-coarse:hidden`).
- The Kbd look (import `@/components/ui/kbd` once it is in the registry): `inline-flex h-5 min-w-5 items-center justify-center gap-0.5 rounded-[5px] bg-foreground/5 px-1 font-sans text-[11px] font-medium text-muted-foreground shadow-[inset_0_-1px_0_0_color-mix(in_oklab,var(--foreground)_15%,transparent)]`. Inside menu items shortcuts are plain text (section 10).
- Binding: one `keydown` listener on `window`, added in an effect. Ignore the event when `event.defaultPrevented` or `event.isComposing`; ignore shortcuts without a modifier while focus is in an input, textarea, select or contenteditable element; `preventDefault()` only when you handle it. Match `event.key.toLowerCase()`, and fall back to `event.code` (`KeyK`) when `key` is not a Latin letter (non-Latin layouts, Option on macOS).
- Library-wide keys: Escape closes the top-most overlay; Enter activates; `mod+enter` submits multi-line inputs (textarea, comment, chat prompt); `/` focuses the page search when there is one; `mod+k` opens the command menu. Components never bind a global key without a `shortcut` prop the caller can change or clear.

## Components

### Buttons & Actions

#### Button (`button`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add button`

The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps.

Press it and it dips on a quick spring, then settles back; with a mouse the surface tints on hover. Tab to it for a focus ring that never touches the edge. Tap the playground button to see it load: the spinner takes the label's place and the width holds still. On a phone the medium size grows to 44px so it is easy to hit.

npm: @radix-ui/react-slot, motion
Wingo UI dependencies: motion, tones, ui-config

Props:
- `children?: ReactNode` = "Continue": The label. For icon sizes pass the icon itself and an aria-label.
- `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` = "solid": solid for the one main action on a screen, soft or outline for secondary actions, ghost for toolbars and dense rows, link for actions inside text (always underlined, so it reads as a link without color or hover).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color from the design tokens. neutral is black in light mode and white in dark mode; danger is for destructive actions.
- `size?: "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg"` = "md": Height 32 / 40 / 48px with matching padding, type and icon size. The icon sizes are square. On touch screens md grows to 44px and sm keeps its look with a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape. Scales with the size (md is 8 / 10 / 12px) so every size reads as the same shape; full makes a pill.
- `color?: string` = "": Any CSS color. Replaces the tone in every variant; text on a solid fill turns black or white by lightness. Leave empty to use the tone.
- `loading?: boolean` = false: Shows a spinner in place of the label, keeps the width, sets aria-busy and ignores clicks. The button stays focusable, so keyboard focus is not lost.
- `loadingText?: ReactNode` = "": Text next to the spinner while loading, like "Saving". The button reserves room for it, so it never changes width.
- `disabled?: boolean` = false: Dims the button and blocks it. With asChild the link gets aria-disabled and leaves the tab order.
- `fullWidth?: boolean` = false: Stretches to the container width. The usual choice for the main action at the bottom of a phone screen.
- `asChild?: boolean` = false: Renders your single child (an <a>, a router Link) with the button's look, press and icons, instead of a <button>. The demo swaps in a link.
- `leftIcon?: ReactNode`: An icon before the label. Unsized svgs follow the button size (14 / 16 / 18px).
- `rightIcon?: ReactNode`: An icon after the label, like an arrow or a chevron.
- `spinner?: ReactNode`: Replaces the default spinner.
- `type?: "button" | "submit" | "reset"` = "button": Defaults to "button" so a button inside a form never submits by accident. Set "submit" for the form's main action.
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Not called while loading or disabled.
- `classNames?: Partial<Record<"content" | "icon" | "spinner", string>>`: Extra classes for the inner parts: the label wrapper, each icon wrapper, the spinner.
- `className?: string`: Extra classes for the button itself, merged last. Override the tone vars here, e.g. [--tone-foreground:white].

```tsx
import { ArrowRight } from "lucide-react"
import { Button } from "@/components/ui/button"

export function CheckoutActions({ paying, onPay }: { paying: boolean; onPay: () => void }) {
  return (
    <div className="flex gap-2">
      <Button variant="ghost">Cancel</Button>
      <Button tone="brand" loading={paying} loadingText="Paying" rightIcon={<ArrowRight />} onClick={onPay}>
        Pay now
      </Button>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/button (Markdown: https://wingo-ui.com/components/button.md)

#### Button Group (`button-group`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add button-group`

Buttons joined into one control or spaced in a row, plus a split button that pairs a main action with a menu.

Each button presses on its own spring inside the shared shape, and a focused one rises above its neighbours so the ring is never cut off. Tab moves from button to button. The chevron half of a split button opens its menu with a click, Enter, Space or ArrowDown, and turns while open; on a phone the menu arrives as an action sheet. Size, variant, tone, radius and color set on the group flow into every button that did not set its own.

npm: lucide-react
Wingo UI dependencies: button, dropdown-menu, tones, ui-config

Props:
- `children?: ReactNode`: Buttons, SplitButtons, ButtonGroupText cells and ButtonGroupSeparators. Other elements (a DropdownMenu with a Button trigger) still attach, but do not inherit the group's props: set them on the trigger.
- `orientation?: "horizontal" | "vertical"` = "horizontal": A row, or a stack of full-width buttons (stacked actions on a phone).
- `attached?: boolean` = true: Joined edges: inner corners squared, borders collapsed, dividers between solid, soft and ghost buttons, one shadow for the whole group. Off, the buttons sit in a spaced row (gap-2).
- `size?: "sm" | "md" | "lg"` = "md": Passed to every child that did not set one. Icon buttons stay square and follow along (sm becomes icon-sm, lg icon-lg). md grows to 44px on touch.
- `variant?: "solid" | "soft" | "outline" | "ghost"` = "outline": Passed down. outline is the classic joined group; solid gets 1px dividers in the text color.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Passed down to every button.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Passed down; it is the outer shape of the whole group (full makes a pill).
- `color?: string` = "": Any CSS color, passed down in place of the tone. Leave empty to use the tone.
- `disabled?: boolean` = false: Disables every child that did not set disabled itself.
- `fullWidth?: boolean` = false: The group fills its container and the buttons share the width. Made for phone footers.
- `aria-label?: string` = "": The group's accessible name (role="group"). The playground falls back to a sample name when empty.
- `className?: string`: Extra classes for the group, merged last. Other props go to the root div.

Parts:
- `SplitButton` (component): A main action joined to a chevron that opens a dropdown menu. Takes the Button props for its main half (onClick, leftIcon, loading, loadingText, disabled) plus items: MenuEntry[], menuLabel (default "More options"), menuIcon (default ChevronDown), align ("end") and side ("bottom"), menuProps for the rest of the menu (title of the phone sheet, responsive, shortcut) and fullWidth. The phone sheet is named after a string label unless menuProps sets one. Inside a full-width or vertical group it stretches its main half. variant / tone / size / radius / color default to solid / neutral / md / md and style both halves; loading disables the menu too. Props: SplitButtonProps.
- `ButtonGroupText` (component): A non-interactive cell with a button's height, padding and type, for units and counters ("USD", "3 / 12"). Inherits from the group like a button. Props: ComponentProps<"div"> & { size, variant, tone, radius, color, disabled }.
- `ButtonGroupSeparator` (component): An explicit extra break (a 1px line). Pass the group's orientation. Not needed between buttons: the attached group draws its own dividers. Props: ComponentProps<"div"> & { orientation?: "horizontal" | "vertical" }.

```tsx
import { Eye, Share2 } from "lucide-react"
import { Button } from "@/components/ui/button"
import { ButtonGroup, SplitButton } from "@/components/ui/button-group"

export function PublishBar({ onPublish }: { onPublish: () => void }) {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <ButtonGroup aria-label="Preview and share">
        <Button leftIcon={<Eye />}>Preview</Button>
        <Button leftIcon={<Share2 />}>Share</Button>
      </ButtonGroup>
      <SplitButton
        tone="brand"
        onClick={onPublish}
        menuLabel="More publish options"
        menuProps={{ title: "Publish listing" }}
        items={[
          { label: "Save as draft" },
          { label: "Schedule publishing…" },
          { label: "Publish and duplicate" },
        ]}
      >
        Publish listing
      </SplitButton>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/button-group (Markdown: https://wingo-ui.com/components/button-group.md)

#### Copy Button (`copy-button`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add copy-button`

Copy an IBAN, a tax ID, a link or an API key with one tap: an icon button with a tooltip, a labelled button, and CopyText for inline values.

Click the copy icon next to the IBAN: it shrinks away, a check pops in and draws itself, and the tooltip says Copied without closing. Clicking again restarts the timer; after the timeout the copy icon comes back. With the keyboard, Tab to a button (the tooltip opens on focus) and press Enter or Space. A labelled button swaps its label to the copied text and keeps its width. CopyText makes the value itself the target: hover shows a dotted underline, a copy flashes the text once. A value read from a function that takes longer than 300ms shows the spinner; a failing or empty one shows an X and announces the error. On a phone there is no tooltip: the check, a short vibration and the screen reader announcement carry the feedback, and the small size still has a 44px hit area.

npm: motion, lucide-react
Wingo UI dependencies: button, tooltip, use-clipboard, motion, tones, ui-config

Props:
- `value: CopySource (string or () => string | Promise<string>)` = "GB29 NWBK 6016 1331 9268 19": The text to copy, or a function read at click time (the latest form value, a key fetched on demand). An empty result counts as a failure.
- `children?: ReactNode` = "": A label ("Copy IBAN") turns it into a text button whose label swaps to copiedLabel. Without one it is a square icon button labelled by copyLabel.
- `copyLabel?: string` = "Copy": The aria-label of an icon-only button and its tooltip while idle. It never switches to the copied text, so screen readers do not re-read the button. The English defaults of all three labels are exported as DEFAULT_COPY_BUTTON_LABELS.
- `copiedLabel?: string` = "Copied": Shown in the tooltip, in place of the label and announced by the status region after a copy.
- `errorLabel?: string` = "Copy failed": Tooltip and announcement when the copy fails. A labelled button keeps its label; the icon turns into an X.
- `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` = "ghost": The Button variants. ghost for rows and code headers, outline or soft for a labelled button.
- `size?: "sm" | "md" | "lg"` = "sm": 32 / 40 / 48px. Icon-only maps to the square icon-sm / icon / icon-lg sizes; sm keeps a 44px hit area on touch.
- `radius?: "auto" | "none" | "sm" | "md" | "lg" | "full"` = "auto": auto is full (a circle) for icon-only buttons and md with a label. The other values are the Button radii.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The button's color, through the tone tokens.
- `successTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": Color of the check. neutral keeps it the button's own color; on a solid fill the check always uses the fill's text color.
- `color?: string` = "": Any CSS color; replaces the tone like on Button. Leave empty to use the tone.
- `fullWidth?: boolean` = false: Stretches a labelled button to its container, for share screens on a phone.
- `loading?: boolean` = false: Forces the spinner. A value function that takes longer than 300ms shows it on its own, and clicks are ignored while it runs.
- `disabled?: boolean` = false: Dims the button and blocks copying.
- `tooltip?: boolean` = true: The desktop tooltip on icon-only buttons (a labelled button already says what it does). It opens on hover and focus and stays open to say Copied; touch screens never show it.
- `timeout?: number` = 2000: How long the check (or the X) stays, in ms. A second copy restarts it.
- `html?: string`: A rich version copied next to the plain text (pasted into mail or docs as formatted text). It changes nothing on screen, so it has no playground control.
- `icon?: ReactNode`: Replaces the Copy icon. Unsized svgs follow the button size (14 / 16 / 18px).
- `copiedIcon?: ReactNode`: Replaces the check that draws itself after a copy.
- `errorIcon?: ReactNode`: Replaces the X shown when the copy fails.
- `onCopy?: (text: string) => void`: Called after a successful copy with the copied text.
- `onError?: (error: Error) => void`: Called when the copy fails: a rejected value function, an empty value ("Nothing to copy") or a blocked clipboard.
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Runs before copying; call event.preventDefault() to cancel the copy.
- `classNames?: Partial<Record<"icon" | "label", string>>`: Extra classes for the icon stack and the label stack.
- `className?: string`: Extra classes for the button, merged last. The other Button props and native button attributes pass through.

```tsx
import { Link2 } from "lucide-react"
import { CopyButton, CopyText } from "@/components/ui/copy-button"

export function PaymentDetails() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <span className="font-mono text-sm">GB29 NWBK 6016 1331 9268 19</span>
        <CopyButton value="GB29 NWBK 6016 1331 9268 19" copyLabel="Copy IBAN" copiedLabel="Copied" />
      </div>
      <CopyButton value="https://acme.com/i/2026-0412" variant="outline" icon={<Link2 />} copiedLabel="Copied">
        Copy link
      </CopyButton>
      <p className="text-sm">
        Reference: <CopyText mono copiedLabel="Copied">#2026-0412</CopyText>
      </p>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/copy-button (Markdown: https://wingo-ui.com/components/copy-button.md)

#### Delete Button (`delete-button`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add delete-button`

A delete button that asks for confirmation in place, no dialog needed.

Click the bin to lift its lid open. A panel slides out with a check to confirm and a cross to back out. Escape, or the bin again, backs out too. Confirming draws a check where the bin was and swaps back to the bin after a moment; backing out settles the bin in place.

npm: motion
Wingo UI dependencies: ui-config

Props:
- `size?: "sm" | "md" | "lg"` = "md": Scale of the tile, the confirm panel and the icons. The tile is 40px (sm), 48px (md) or 56px (lg) square; on touch screens the sm tile and the confirm and cancel circles get a 44px tall hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the tile and the confirm panel: square, 6px tighter, the original 14 / 16 / 18px per size, 6px rounder, or a pill.
- `surface?: string` = "": Any CSS color for the tile and the two circles. Empty uses the soft gray (#F4F4F9 light, #262626 dark); hover lightens it.
- `recess?: string` = "": Any CSS color for the confirm panel behind the circles. Empty uses #E7E7EF light, #1B1B1B dark.
- `iconColor?: string` = "": Any CSS color for the bin, the cross and the focus ring. Empty uses #868593 light, #9B9AA7 dark.
- `accent?: string` = "#FF5F2E": Any CSS color for the confirm check and the check drawn after deleting.
- `label?: string` = "Delete": Accessible name of the bin button. Name the thing, e.g. "Delete invoice", when several sit on one screen.
- `confirmLabel?: string` = "Confirm delete": Accessible name of the check button in the panel.
- `cancelLabel?: string` = "Cancel": Accessible name of the cross button in the panel.
- `deletedLabel?: string` = "Deleted": Announced to screen readers after confirming.
- `keptLabel?: string` = "Kept": Announced to screen readers after backing out.
- `resetDelay?: number` = 1400: How long the check stays after confirming, in milliseconds, before the bin comes back.
- `disabled?: boolean` = false: Blocks the button and dims it. Disabling it while the panel is open backs out of the panel.
- `onConfirm?: () => void`: Called when the check is pressed.
- `onCancel?: () => void`: Called when the panel closes without deleting, from the cross, the bin, or Escape.
- `className?: string`: Extra classes merged onto the root element; other div props are spread onto it too. The root carries data-state (open or closed) and data-status (idle, deleted or kept) for styling.

```tsx
"use client"

import { DeleteButton } from "@/components/ui/delete-button"

export function Demo({ onDelete }: { onDelete: () => void }) {
  return <DeleteButton label="Delete invoice" onConfirm={onDelete} />
}
```

Docs: https://wingo-ui.com/components/delete-button (Markdown: https://wingo-ui.com/components/delete-button.md)

#### Theme Toggle (`theme-toggle`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add theme-toggle`

Switch light, dark and system on top of next-themes: an animated sun / moon button, a segmented control or a menu, with a circular reveal.

Press the icon button and the new theme grows over the page in a circle from the button, while the glyph morphs: going dark the sun's rays fold away, the disc swells and a shadow slides across it until a crescent moon is left; going light it runs backwards. The button cycles System, then the theme the device is not showing, then the device's own theme, then System again (a small monitor badge appears in the corner and the page follows the device), so from System the first press always changes what you see. With includeSystem off it flips between light and dark and never shows the badge. Hover or focus shows a tooltip with the current theme and the shortcut. The segmented variant slides its raised thumb to Light, Dark or System; the dropdown opens a menu with the three choices and a check on the current one, as a bottom sheet on phones. Keyboard: Tab to it, Enter or Space toggles the icon button; in the segmented control Left / Right (and Home / End) pick a theme; in the menu Up / Down move, Enter picks, Escape closes and focus returns to the button. A shortcut prop such as shift+t flips light and dark from anywhere. The new theme is announced to screen readers. With reduced motion the glyph crossfades and the page switches at once. On a phone every target is 44px.

npm: lucide-react, motion, next-themes
Wingo UI dependencies: button, dropdown-menu, segmented-control, tooltip, use-controllable-state, use-media-query, use-shortcut, motion, tones, ui-config

Props:
- `variant?: "icon" | "segmented" | "dropdown"` = "icon": icon: an animated sun / moon button for headers. segmented: Light / Dark / System side by side for settings pages. dropdown: a button that opens a menu (a sheet on phones).
- `includeSystem?: boolean` = true: Offers System, which follows the device. The icon button then cycles system -> the opposite of the device -> the device's theme -> system, so each press but the last visibly changes the page; without it the button flips light <-> dark, and a page on system shows as the theme it resolves to (no badge). Segmented and dropdown show a third option.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px, like the button (md is 44px on touch). The glyph is 16 / 18 / 20px; the segmented track and the menu follow.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape of the icon button, the dropdown trigger and the segmented track. Scales with the size.
- `buttonVariant?: "solid" | "soft" | "outline" | "ghost" | "link"` = "ghost": The look of the icon button and the dropdown trigger. ghost sits quietly in a header.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the icon button and the dropdown trigger, and the fill of the segmented thumb (neutral is a raised white thumb).
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `showLabels?: boolean` = false: segmented: icons with labels (icons only by default, each with a tooltip). dropdown: the current theme's name and a chevron on the trigger.
- `fullWidth?: boolean` = false: segmented: the segments share the full width of the parent, the usual layout for a settings row on a phone.
- `transition?: "none" | "fade" | "circle"` = "circle": How the new theme appears: a circle growing from the control, a crossfade, or at once. Uses the View Transitions API (Chrome, Edge, Safari 18+), falls back to switching at once, and is off under reduced motion. The file also exports switchThemeWithTransition(apply, { transition?, duration?, origin? }), which runs any theme change inside the same reveal (origin is an element or a { x, y } point) and skips it while another one runs.
- `duration?: number` = 500: Length of the reveal in ms.
- `shortcut?: string` = "": A key combo that flips light / dark from anywhere, e.g. "shift+t". Shown in the tooltip and set as aria-keyshortcuts. Empty binds nothing.
- `disabled?: boolean` = false: Dims the control and blocks it. It is also disabled on pages that force a theme (next-themes forcedTheme).
- `defaultOpen?: boolean` = false: dropdown: starts with the menu open.
- `align?: "start" | "center" | "end"` = "end": dropdown: which edge of the menu lines up with the trigger. end suits a toggle at the end of a header.
- `responsive?: boolean` = true: dropdown: the menu becomes a bottom sheet below 768px.
- `value?: "light" | "dark" | "system"`: Controlled use without next-themes: the toggle shows this theme and only calls onValueChange. Left out, it reads and writes next-themes' useTheme(). The file also exports useThemeToggle({ value?, defaultValue?, onValueChange?, transition?, duration? }), the logic on its own for user menus and settings pages: it returns { theme, resolvedTheme, setTheme(theme, origin?), toggle(origin?), mounted, forced }; theme and resolvedTheme are undefined until mounted when they come from next-themes, and setTheme / toggle run the reveal from an element or a { x, y } point.
- `defaultValue?: "light" | "dark" | "system"` = "": Uncontrolled use without next-themes: the starting theme. The toggle keeps its own state and reports picks through onValueChange. Left out (with value), it reads and writes next-themes; the playground's empty option means left out.
- `onValueChange?: (theme: ThemeValue) => void`: Fires with every pick, inside the view transition, so the new theme you apply is what the reveal shows.
- `open?: boolean`: dropdown: controls the menu.
- `onOpenChange?: (open: boolean) => void`: dropdown: fires when the menu opens or closes.
- `labels?: { light?, dark?, system?, toggle?, menu?, announceLight?, announceDark?, announceSystem? }`: Every string, merged over English defaults: "Light", "Dark", "System", "Toggle theme" (the icon button's name), "Theme" (group name, tooltip prefix, sheet title) and the screen reader announcements "Light theme", "Dark theme", "System theme".
- `classNames?: Partial<Record<"icon" | "badge" | "label" | "chevron" | "item" | "thumb" | "content", string>>`: Extra classes for inner parts: the glyph, the system badge, the trigger label and chevron, segments or menu rows, the segmented thumb, the menu surface.
- `className?: string`: Extra classes for the root: the button, the segmented track or the dropdown trigger.

```tsx
"use client"

import { ThemeProvider } from "next-themes"
import { ThemeToggle } from "@/components/ui/theme-toggle"

// next-themes needs attribute="class" so the dark: variant and the reveal see the change
export function AppHeader() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
      <header className="flex h-14 items-center justify-between px-4">
        <span className="font-semibold">Northwind CRM</span>
        <ThemeToggle
          shortcut="shift+t"
        />
      </header>
    </ThemeProvider>
  )
}
```

Docs: https://wingo-ui.com/components/theme-toggle (Markdown: https://wingo-ui.com/components/theme-toggle.md)

#### Toggle (`toggle`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add toggle`

A two-state button that stays pressed, for bold and italic in an editor, a favorite heart, mute, or a filter pill.

Click or tap it and it stays pressed: the surface takes the selected tint (soft turns into a solid fill) and it dips on a quick spring while your finger is down. Click again to release it. With a mouse it tints on hover, deeper when it is already pressed. Tab to it and press Space or Enter; screen readers hear the state through aria-pressed while the label stays the same. With pressedIcon the icon pops into its pressed form (an outline heart turns into a filled one, a bell into a muted bell), and a filter pill grows a check mark. A shortcut such as mod+b flips it from anywhere on the page. On a phone the medium size is 44px tall and the small one keeps a 44px hit area.

npm: @radix-ui/react-toggle, @radix-ui/react-slot, motion
Wingo UI dependencies: motion, tones, use-controllable-state, use-shortcut, ui-config

Props:
- `children?: ReactNode` = "Delivery only": The label. For icon sizes pass the icon itself plus an aria-label, and keep the label the same in both states and name what pressed means (Bold, Mute notifications): aria-pressed already says whether it is on.
- `variant?: "ghost" | "outline" | "soft"` = "ghost": ghost is transparent with muted text and takes the selected tint when pressed (toolbars). outline adds a hairline border that turns to the tone when pressed (filter chips). soft rests on a light fill and becomes the solid tone fill when pressed, so the on state is loud.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the pressed state. neutral is the gray selected tint (black or white fill on soft); the other tones tint the pressed state and color its text.
- `color?: string` = "": Any CSS color for the pressed state. Replaces the tone; on soft the text on the fill turns black or white by lightness. Leave empty to use the tone.
- `size?: "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg"` = "md": The button's size table: 32 / 40 / 48px tall with matching padding, type and icon size. The icon sizes are square and need an aria-label. On touch screens md grows to 44px and sm keeps its look with a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size (md is 8 / 10 / 12px). full makes a pill, the usual look for filters.
- `defaultPressed?: boolean` = false: Starting state while uncontrolled.
- `pressed?: boolean`: Controlled state. Pair it with onPressedChange; without a handler the toggle stays where you put it.
- `onPressedChange?: (pressed: boolean) => void`: Called with the next state on click, Space, Enter or the shortcut.
- `disabled?: boolean` = false: Dims the toggle, blocks clicks and the shortcut, and keeps its current state.
- `fullWidth?: boolean` = false: Stretches to the container width, e.g. a Follow toggle at the bottom of a phone screen.
- `shortcut?: string` = "": A key combo in mod+k notation ("mod+b", "shift+mod+x"; mod is ⌘ on Apple devices and Ctrl elsewhere) that flips the toggle from anywhere on the page. Also sets aria-keyshortcuts. Bare keys are ignored while typing. Pass it only while the toggle should listen, e.g. while its editor has focus.
- `asChild?: boolean` = false: Renders your single child (a router link for URL filters, your own button) with the toggle's look, state, press and icons. A child that is not a button gets role="button" and flips on Space too, so aria-pressed is announced. The demo turns the first filter into an <a>. As in Radix, calling event.preventDefault() in your onClick cancels the flip.
- `leftIcon?: ReactNode`: An icon before the label. Unsized svgs follow the size (14 / 16 / 18px).
- `pressedIcon?: ReactNode`: Replaces leftIcon (or the icon child in icon sizes) while pressed, popping in on a spring: an outline heart to a filled one, Bell to BellOff. On a text toggle without leftIcon it only shows while pressed and the width springs open, like a filter chip growing a check, with the neighbors gliding along.
- `classNames?: Partial<Record<"icon" | "label", string>>`: Extra classes for the inner parts: the icon wrapper and the label wrapper.
- `className?: string`: Extra classes for the toggle itself, merged last. Style the pressed state with data-[state=on]:, e.g. data-[state=on]:bg-background/90.

```tsx
import { Check, Heart } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function ListingActions({ saved, onSavedChange }: { saved: boolean; onSavedChange: (saved: boolean) => void }) {
  return (
    <div className="flex items-center gap-2">
      <Toggle variant="outline" radius="full" pressedIcon={<Check />}>
        Delivery only
      </Toggle>
      <Toggle
        size="icon"
        radius="full"
        tone="danger"
        pressed={saved}
        onPressedChange={onSavedChange}
        pressedIcon={<Heart className="fill-current" />}
        aria-label="Save to favorites"
      >
        <Heart />
      </Toggle>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/toggle (Markdown: https://wingo-ui.com/components/toggle.md)

#### Toggle Group (`toggle-group`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add toggle-group`

A row of toggles where one or several stay pressed, for text formatting, alignment, view switches and quick filters.

Click or tap an item and it stays pressed. In single mode the highlight slides over to the new item on a smooth spring and the old one lets go; in multiple mode each item pops its own highlight in and out. Every item dips a little while your finger is down. The group is one tab stop: arrow keys move along it (wrapping around unless loop is off), Home and End jump to the ends, Space or Enter presses. Icon-only items name themselves in a tooltip on hover or keyboard focus, with the shortcut hint next to the name; on a phone a long press shows it without pressing the item. On touch the medium size is 44px tall and the small one keeps a 44px hit area.

npm: @radix-ui/react-toggle-group, motion
Wingo UI dependencies: tooltip, motion, tones, use-controllable-state, ui-config

Props:
- `type?: "single" | "multiple"` = "single": single: one item stays pressed and the value is a string (an alignment, a view). multiple: any number stay pressed and the value is a string[] (bold, italic, filters).
- `options?: ToggleGroupOption[]`: { value: string; label: ReactNode; icon?: ReactNode; disabled?: boolean; tooltip?: ReactNode; shortcut?: string }. The shortcut is a hint shown in the tooltip and set as aria-keyshortcuts; bind it yourself with useShortcut. Values that disappear from the list are dropped from the value.
- `value?: string | string[]`: Controlled value, typed by type: a string for single (empty for none), a string[] for multiple.
- `defaultValue?: string | string[]`: Starting value while uncontrolled: "" or [] when omitted.
- `onValueChange?: (value: string | string[]) => void`: Fires with the new value, typed by type: a string for single ("" when cleared), a string[] for multiple.
- `deselectable?: boolean` = false: single only: clicking the pressed item clears the value. Off by default, since an alignment or a view always has one.
- `variant?: "ghost" | "outline" | "soft"` = "ghost": ghost: transparent items for toolbars, pressed ones get the selected tint. outline: items joined into one bordered control with hairlines between them. soft: a tinted track where the pressed item becomes a solid fill.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px with matching padding, type and icon size; icon-only items are square. On touch screens md grows to 44px and sm keeps a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size like the button's. full turns the group into a pill.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the pressed items. neutral is the gray selected tint (a black or white fill on soft); the other tones tint the highlight and color the text.
- `color?: string` = "": Any CSS color for the pressed items; replaces the tone. Leave empty to use the tone.
- `orientation?: "horizontal" | "vertical"` = "horizontal": The direction of the row and of the arrow keys. Vertical items align their labels to the start.
- `iconOnly?: boolean` = false: Shows only the icons in square items. Each label becomes the item's aria-label and its tooltip (with the shortcut hint).
- `fullWidth?: boolean` = false: Items share the width of the container, the usual layout for a view switch on a phone.
- `attached?: boolean` = true: outline only: items share their borders as one control. Off: they stand apart as separate chips with a gap; add flex-wrap through className to let them wrap.
- `loop?: boolean` = true: Arrow keys wrap from the last item to the first and back. Off: they stop at the ends.
- `disabled?: boolean` = false: Dims the whole group and blocks it. A single option can be disabled through its disabled field.
- `aria-label?: string` = "": The group's name for screen readers, like Alignment. Needed when no visible label sits next to it.
- `classNames?: Partial<Record<"item" | "highlight" | "icon" | "label", string>>`: Extra classes for every item, the pressed highlight, the icon wrapper and the label wrapper.
- `className?: string`: Extra classes for the group itself, merged last.

Parts:
- `ToggleGroupRoot` (component): The group without options, for custom layouts: the same props as ToggleGroup minus options, with ToggleGroupItem and ToggleGroupSeparator children. Props: ToggleGroupRootProps<T>.
- `ToggleGroupItem` (component): One item; children is the label. Takes every button prop too. Props: { value: string; icon?: ReactNode; tooltip?: ReactNode; shortcut?: string; disabled?: boolean; children?: ReactNode }.
- `ToggleGroupSeparator` (component): A hairline between clusters inside a group or between two groups in a toolbar; it runs across the group's direction unless you set orientation. Props: { orientation?: "horizontal" | "vertical" }.

```tsx
import { AlignCenter, AlignLeft, AlignRight, Bold, Italic, Underline } from "lucide-react"
import { ToggleGroup, ToggleGroupSeparator } from "@/components/ui/toggle-group"

export function EditorToolbar({ align, onAlignChange }: { align: string; onAlignChange: (value: string) => void }) {
  return (
    <div role="toolbar" aria-label="Editor" className="flex items-center gap-1">
      <ToggleGroup
        type="multiple"
        iconOnly
        defaultValue={["bold"]}
        aria-label="Formatting"
        options={[
          { value: "bold", label: "Bold", icon: <Bold />, shortcut: "mod+b" },
          { value: "italic", label: "Italic", icon: <Italic />, shortcut: "mod+i" },
          { value: "underline", label: "Underline", icon: <Underline />, shortcut: "mod+u" },
        ]}
      />
      <ToggleGroupSeparator />
      <ToggleGroup
        iconOnly
        value={align}
        onValueChange={onAlignChange}
        aria-label="Alignment"
        options={[
          { value: "left", label: "Left", icon: <AlignLeft /> },
          { value: "center", label: "Center", icon: <AlignCenter /> },
          { value: "right", label: "Right", icon: <AlignRight /> },
        ]}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/toggle-group (Markdown: https://wingo-ui.com/components/toggle-group.md)

### Inputs

#### Avatar Upload (`avatar-upload`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add avatar-upload`

Change a profile picture like on a phone: pick or shoot a photo, crop it in a round frame and watch a ring fill while it uploads.

Tap or click the avatar (it dips on a quick spring; with a mouse or on keyboard focus a dark scrim says Change photo) to open the source menu: Choose a photo, Take photo and Remove photo, a bottom sheet on phones. With only one entry it goes straight to the file picker. After picking, the crop step opens in a dialog (a sheet on phones) with a round frame: drag to move, pinch or scroll to zoom, the zoom and rotation sliders and a 90° turn below, then Save exports a square WebP at 512px. The new picture crossfades in at once while a ring around the avatar fills with the upload progress (it spins when the server reports none); when it finishes a green check pops over the camera badge for a moment and Photo updated is announced. If the upload fails the old picture comes back, the ring turns red, the badge becomes a retry arrow, the error shows under the avatar and Try again sits at the top of the menu. Remove runs at once (a returned promise shows the spinning ring and rolls back on rejection). Drag a photo onto the avatar or the dropzone (it grows a little and turns the tone color), or paste an image while it is focused. Take photo uses the front camera on phones; on desktops it opens a mirrored live camera with a round shutter, and a refused permission shows a message with Try again and Choose a photo. Keyboard: Tab to the avatar, Enter or Space opens the menu (arrows move, Escape closes and focus returns), Delete or Backspace removes the picture, and inside the crop step arrows nudge, + and - zoom and r rotates. The row look puts Change photo and Remove buttons with the hint beside the avatar; the dropzone look is a dashed tile with the avatar inside. Read-only shows the picture without a badge or menu.

npm: motion, lucide-react
Wingo UI dependencies: image-cropper, avatar, button, dialog, dropdown-menu, progress, field, file-upload, file-types, file-export, use-controllable-state, use-locale, use-media-query, haptics, motion, tones, ui-config

Props:
- `value?: string | null`: The controlled picture url; null shows the initials. It becomes the url your onUpload resolves, or a local object url when it resolves nothing.
- `defaultValue?: string | null` = "null": The uncontrolled starting picture.
- `onValueChange?: (value: string | null) => void`: Fires with the new url after an upload succeeds, with null on remove, and with the old url when a remove is rolled back.
- `name?: string` = "": The person's name: initials and a stable color while there is no picture, and part of the button's accessible name (Change photo, Anna Price).
- `onUpload?: (blob: Blob, context: { file: File | null; signal: AbortSignal; onProgress: (fraction: number) => void }) => Promise<string | void>`: Gets the cropped square. Call onProgress(0 to 1) to fill the ring (without calls it spins) and resolve the new url. A rejection rolls the picture back and offers Try again. The signal aborts when the component unmounts or a newer upload starts; a result that arrives after the value changed from outside is ignored. Without onUpload the blob becomes a local object url.
- `onRemove?: () => (void | Promise<unknown>)`: The Remove action, shown only when set and there is a picture. It runs at once without a confirm (offer undo in a toast); a returned promise shows the spinning ring and rolls back on rejection.
- `onError?: (error: Error) => void`: A wrong file type, a file over maxFileSize, a failed export, upload or remove.
- `variant?: "avatar" | "row" | "dropzone"` = "avatar": avatar: the picture with a camera badge, the whole avatar is the button. row: the picture with Change photo and Remove buttons and the hint beside it, for settings lists. dropzone: a dashed tile with the avatar inside, for logos and onboarding.
- `size?: "md" | "lg" | "xl"` = "lg": The avatar: 64 / 96 / 128px. The badge and the check scale with it (24 / 32 / 36px, a 44px hit area on touch).
- `shape?: "circle" | "rounded"` = "circle": The avatar and the crop frame. circle exports with transparent corners (unless JPEG); rounded suits logos and crops a plain square.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The camera badge, the progress ring, the drag-over tint and the Save button. A failed upload always turns the ring red.
- `color?: string` = "": Any CSS color; replaces the tone.
- `ringColor?: string` = "": The thin ring that separates the badge and the check from the avatar. Set it to the surface behind the avatar (the page background by default).
- `label?: ReactNode` = "": The field label above the control (W2 field anatomy).
- `description?: ReactNode` = "": Helper text under the control.
- `error?: ReactNode` = "": Replaces the description, sets aria-invalid and marks the dropzone red.
- `showHint?: boolean` = true: The hint (JPG, PNG or WebP, up to 10 MB) under the buttons in the row look and inside the dropzone.
- `required?: boolean` = false: Marks the label with an asterisk and sets aria-required.
- `invalid?: boolean` = false: Invalid without a message.
- `disabled?: boolean` = false: Dims the control; no menu, no drops.
- `readOnly?: boolean` = false: Shows the picture without a badge, a menu or drops.
- `progress?: number | null`: External progress (0 to 1) for uploads you run yourself: the ring shows at that share, null spins it, undefined hides it.
- `crop?: boolean` = true: The crop step. false uploads the largest centered square at once, without the dialog.
- `camera?: boolean` = true: The Take photo entry: the front camera through the file input on phones (capture="user"), a live camera dialog on desktops with getUserMedia, hidden where neither works.
- `accept?: string` = "image/jpeg,image/png,image/webp": Allowed types for the picker, drops and pastes; other files get labels.wrongType. Safari converts iPhone HEIC photos to JPEG on pick when JPEG is listed; other browsers reject HEIC.
- `maxFileSize?: number` = 10485760: Bytes of the chosen file (10 MB); bigger files get labels.tooLarge with the limit formatted. 0 means no limit. The export itself is small.
- `outputSize?: number` = 512: Width and height of the exported square, in px.
- `outputType?: "image/webp" | "image/jpeg" | "image/png"` = "image/webp": The exported format. JPEG has no transparency, so a round crop fills the corners white.
- `outputQuality?: number` = 0.9: 0 to 1, for WebP and JPEG.
- `responsive?: boolean` = true: The source menu, the crop step and the camera become bottom sheets below 768px.
- `locale?: string` = "": Formats the size limit in the error (10 MB). Empty uses UIProvider's locale, then the browser's.
- `inputName?: string` = "": Renders a hidden input with this name and the current url, for plain form posts. (name is the person's name here.)
- `id?: string`: The trigger's id; the label and the messages point at it.
- `cropperProps?: Partial<Omit<ImageCropperProps, "src">>`: Extra props for the crop step's ImageCropper, e.g. { labels } to translate it, { height: 360 } or { flippable: true }.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `labels?: Partial<AvatarUploadLabels>`: Every visible and announced string: change, choose, takePhoto, remove, cropTitle, cameraTitle, save, cancel, uploading, uploaded, removed, failed, removeFailed, tooLarge(max), wrongType, cameraDenied, cameraStarting, shutter, hint, retry, dropTitle, dropTitleTouch, dropHere. English defaults in DEFAULT_AVATAR_UPLOAD_LABELS.
- `classNames?: Partial<Record<"root" | "trigger" | "avatar" | "badge" | "progress" | "check" | "actions" | "hint" | "message" | "dialog" | "camera" | "field" | "label" | "description" | "error" | "counter", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root (the Field when a label, description or error is set).

```tsx
import { useState } from "react"
import { AvatarUpload } from "@/components/ui/avatar-upload"

export function ProfilePhoto() {
  const [avatar, setAvatar] = useState<string | null>("/demo/ana-pop.jpg")

  return (
    <AvatarUpload
      name="Anna Price"
      value={avatar}
      onValueChange={setAvatar}
      onUpload={async (blob, { signal, onProgress }) => {
        const body = new FormData()
        body.append("avatar", blob, "avatar.webp")
        onProgress(0.3)
        const response = await fetch("/api/profile/avatar", { method: "POST", body, signal })
        if (!response.ok) throw new Error("The upload failed")
        onProgress(1)
        const { url } = (await response.json()) as { url: string }
        return url
      }}
      onRemove={() => fetch("/api/profile/avatar", { method: "DELETE" })}
      labels={{
        change: "Update photo",
        cropTitle: "Adjust your photo",
        uploaded: "Looking good! Photo updated",
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/avatar-upload (Markdown: https://wingo-ui.com/components/avatar-upload.md)

#### Calendar (`calendar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add calendar`

A month grid for picking one day, several days or a stay, with disabled days, event dots, several months and a quick month / year jump.

Click a day to pick it; in multiple mode each click adds or removes a day, and in range mode the first click sets the start, the band follows the pointer as a preview, and the second click sets the end (a day before the start swaps them). The arrows move a month (or a page with pagedNavigation) and the grid slides the way you went. Click the caption for a months grid, click again for years, pick one to zoom back in. Keyboard: Tab lands on one day (the selected, else today); arrows move a day or a week, Home / End jump to the week's ends, PageUp / PageDown move a month and Shift+PageUp / PageDown a year, Enter or Space picks; in the months and years grids arrows move, Enter picks and Escape returns to the days. On a phone the cells grow to 44px and a swipe left or right changes the month; vertical scrolling still works.

npm: date-fns, motion, lucide-react
Wingo UI dependencies: button, date-utils, use-controllable-state, use-locale, use-media-query, motion, tones, ui-config

Props:
- `mode?: "single" | "multiple" | "range"` = "single": What a click picks: one day, a set of days (each click adds or removes one), or a range (start, then end). The value type follows the mode: Date | null, Date[] or { from, to }.
- `value?: Date | null | Date[] | DateRange`: The selection, controlled. Typed by mode: Date | null for single, Date[] for multiple, { from: Date | null; to: Date | null } for range. A value outside min / max shows as given; only clicks are limited.
- `defaultValue?: Date | null | Date[] | DateRange`: The starting selection while uncontrolled: null, [] or { from: null, to: null } by mode.
- `onValueChange?: (value: Date | null | Date[] | DateRange) => void`: Called on every pick with the next value (typed by mode). In single mode a new day keeps the time of the previous value, so a date-time picker never loses its time.
- `month?: Date`: The first visible month, controlled. Pair it with onMonthChange.
- `defaultMonth?: Date`: The first visible month on mount. Defaults to the value's month, else today's, and is clamped to min / max.
- `onMonthChange?: (month: Date) => void`: Called with the first day of the new first visible month after an arrow, a swipe, a keyboard move or a jump.
- `numberOfMonths?: number` = 1: Months side by side from 640px wide; below that they stack, each with its own caption. In a narrow container on a wide screen, stack them with classNames={{ months: "sm:flex-col" }} (or a container query).
- `pagedNavigation?: boolean` = false: The arrows and swipes move by numberOfMonths instead of one month.
- `min?: Date`: Earlier days are disabled and the previous arrow stops at this month.
- `max?: Date`: Later days are disabled and the next arrow stops at this month. min after max leaves nothing enabled (a dev warning says so).
- `disabled?: DateMatcher or DateMatcher[] (Date, Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean)`: Days that can not be picked: a Date, a list, { from, to }, { before }, { after }, { dayOfWeek: [0, 6] } for weekends, or a (date) => boolean test. Disabled days stay focusable (aria-disabled) so the keyboard can pass over them.
- `locale?: string` = "": Month and weekday names, digits and the first day of the week, all from Intl. Empty uses the nearest LocaleProvider, else the page's language. en-US starts on Sunday, de-DE on Monday.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: The first day of the week: 0 is Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Sunday in en-US, Monday in de-DE).
- `showOutsideDays?: boolean` = true: Shows the neighbour months' days that fill the first and last week, dimmed. They can be picked and move the view there.
- `fixedWeeks?: boolean` = false: Always six weeks, so the grid never changes height between months (pickers turn it on). Without it the height change animates.
- `showWeekNumbers?: boolean` = false: A column of week numbers: ISO weeks when the week starts on Monday, the locale's numbering otherwise. On touch screens md days take 40px instead of 44px to make room, so it still fits a 360px phone.
- `events?: { date: Date; tone?: Tone; color?: string; label?: string }[]`: Dots under a day (up to 3): bookings, deadlines, holidays. tone or any color; labels are read out with the day. On a selected day the dots turn the selection's text color.
- `monthYearPicker?: boolean` = true: The caption becomes a button: first a months grid, then a years grid (20 at a time), for fast jumps to a birthday or next year. Off, the caption is plain text.
- `minDays?: number` = 0: Range mode: the shortest range in days, both ends counted (a 2 night minimum stay is 3). While picking the end, closer days are unavailable; clicking the start again then clears it. 0 = no minimum.
- `maxDays?: number` = 0: Range mode: the longest range in days, both ends counted. Farther days are unavailable while picking the end. 0 = no limit.
- `excludeDisabled?: boolean` = true: Range mode: a range can not span a disabled day. While picking the end, every day past the first disabled one on each side is unavailable (booked nights in a stay).
- `maxSelected?: number` = 0: Multiple mode: how many days can be picked. At the limit the other days are unavailable until one is removed. 0 = no limit.
- `size?: "sm" | "md" | "lg"` = "md": Day cells of 32, 36 or 44px. On touch screens md grows to 44px, so seven columns still fit a 360px phone.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selection color: the day fill, the range band and the months / years highlight.
- `color?: string` = "": Any CSS color for the selection; replaces the tone. Text on the fill turns black or white by lightness and the band is a tint of it.
- `radius?: "md" | "full"` = "full": The day shape: circles (the default, like iOS) or rounded squares. The range band rounds to match.
- `strikeDisabled?: boolean` = false: Strikes through disabled days, for booked nights and sold-out dates.
- `todayButton?: boolean` = false: A Today button under the grid that jumps back to the current month (and closes the months / years view).
- `labels?: Partial<{ previousMonth; nextMonth; previousYear; nextYear; previousYears; nextYears; chooseMonth; chooseYear; today; weekNumber; selected; event: string }>`: Every visible and spoken string, merged over the English defaults ("Previous month", "Today", "selected"...). Pass translated ones in another language.
- `renderDay?: (date: Date, state: { today; selected; rangeStart; rangeMiddle; rangeEnd; outside; disabled; hoverRange; events }) => ReactNode`: The content inside a day button, in place of the number: a price under each day, a badge. Use size lg for two lines.
- `footer?: ReactNode`: Content under the grid: a range summary, a time field, actions.
- `autoFocus?: boolean` = false: Focuses the selected day (else today) on mount. Pickers pass it when they open from the keyboard.
- `name?: string` = "": Renders hidden inputs for native forms, as local ISO dates ("2026-09-23"): one for single, one per day for multiple, name.from and name.to for a range. A form reset returns to defaultValue. The demo prints what the form would submit.
- `classNames?: Partial<Record<"header" | "caption" | "nav" | "months" | "grid" | "weekday" | "day" | "today" | "selected" | "range" | "outside" | "disabled" | "events" | "view" | "footer", string>>`: Extra classes for the inner parts. range goes on the cells that carry the band, the day keys on the day buttons.
- `className?: string`: Extra classes for the root. Override the tone vars here, e.g. [--tone-soft:...] for a custom band.

```tsx
import { useState } from "react"
import { Calendar, type DateRange } from "@/components/ui/calendar"

const booked = [new Date(2026, 9, 9), new Date(2026, 9, 10), new Date(2026, 9, 11)]

export function StayPicker() {
  const [stay, setStay] = useState<DateRange>({ from: null, to: null })
  return (
    <Calendar
      mode="range"
      value={stay}
      onValueChange={setStay}
      min={new Date()}
      disabled={booked}
      minDays={3}
      strikeDisabled
      events={[{ date: new Date(2026, 9, 14), tone: "warning", label: "Request pending" }]}
      labels={{ today: "Back to today", selected: "picked" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/calendar (Markdown: https://wingo-ui.com/components/calendar.md)

#### Checkbox (`checkbox`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add checkbox`

A box that is on, off or mixed with a check that draws itself, a label row that is the whole target, cards, and groups with select all.

Click the box, its label or its description and the check draws itself on a quick spring; uncheck it and the stroke pulls back faster. While you press, the box dips a little, and with a mouse its border darkens on hover. Tab reaches every box and Space toggles it (Enter does not, as the ARIA pattern says); an indeterminate box turns checked on the next press. A link inside the label opens without toggling. Press Place order with the terms unchecked and the error slides in under the row; checking the box clears it. Cards take a ring in the tone when checked and dip slightly while pressed. In a group, Select all checks every enabled option and shows a dash while only some are checked (it turns checked once every enabled option is); with a maximum, the remaining options disable once you reach it. On a phone every row is at least 44px tall and the whole row is the target, and with reduced motion the check appears without drawing and nothing dips.

npm: @radix-ui/react-checkbox, motion
Wingo UI dependencies: field, use-controllable-state, motion, tones, ui-config

Props:
- `label?: ReactNode` = "": Text beside the box. The whole row is one <label>, so clicking the text, the description or the empty space toggles the box. A link inside it opens without toggling.
- `description?: ReactNode` = "": A second line under the label, in the muted caption style. It is kept out of the box's name and linked with aria-describedby, so screen readers read it after the label.
- `error?: ReactNode` = "": A message under the row, lined up with the label, that slides in and marks the box invalid (red border, aria-invalid). "", false and null are no error. A box without a label only turns red; wrap it in a Field to show the text.
- `required?: boolean` = false: Shows the red mark after the label, sets aria-required, and inside a native form blocks submission while unchecked (through Radix's hidden input).
- `invalid?: boolean` = false: The red border and aria-invalid without a message, for forms that show errors elsewhere. Inherits from a parent Field.
- `disabled?: boolean` = false: Dims the row to 50% and blocks it. A disabled Field or FieldGroup around it disables it too.
- `readOnly?: boolean` = false: Shows the value but ignores clicks and Space, with no hover or press feedback; the box keeps focus and sets aria-readonly.
- `defaultChecked?: boolean | "indeterminate"` = false: The starting state while uncontrolled: true, false or "indeterminate" (a dash, aria-checked="mixed").
- `checked?: boolean | "indeterminate"`: The state while controlled. Pair it with onCheckedChange.
- `onCheckedChange?: (checked: boolean | "indeterminate") => void`: Called with the next state. Clicking an indeterminate box makes it true, like Radix.
- `size?: "sm" | "md" | "lg"` = "md": Box 16 / 18 / 20px with a 12 / 14 / 16px check and a 13 / 14 / 15px label. The box centers on the label's first line at every size.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The checked fill (and the card ring and icon tile). neutral is black in light mode and white in dark mode; keep brand for the one place it means something.
- `color?: string` = "": Any CSS color. Replaces the tone; the check turns black or white by the color's lightness. Leave empty to use the tone.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Box corners, scaled with the size: md is 4 / 5 / 6px, full makes a round checkbox.
- `variant?: "default" | "card"` = "default": card turns the row into a bordered tile with the box at the top end, an optional icon tile, and a ring in the tone when checked. For rich choices like paid extras.
- `labelPosition?: "end" | "start"` = "end": start puts the label first and the box at the end of a full-width row, like a settings list. Cards ignore it.
- `icon?: ReactNode`: Cards: the leading icon in a 40px tile that takes the tone when checked. Rows: a thumbnail or avatar between the box and the text (the row then centers).
- `name?: string` = "": Form field name. Inside a <form> Radix renders a hidden input that submits value while checked and returns to its first state when the form resets. The playground sits in a real form.
- `value?: string` = "on": What the form submits while the box is checked.
- `id?: string`: The box's id. Defaults to useId(); inside a Field the Field's id wins, so its label toggles the box.
- `classNames?: Partial<Record<"field" | "box" | "indicator" | "content" | "label" | "description" | "error" | "icon", string>>`: Extra classes for the parts: field is the label row (or the card), box the button, indicator the check svg. Padding for list rows goes on field so the padding stays clickable.
- `className?: string`: Classes for the outermost element: the wrapper around the row and its message, or the box itself when there is no label. ref and every other prop (aria-*, data-*, onBlur, form) go to the box, a <button role="checkbox">, so form libraries can focus it.

Parts:
- `CheckboxGroup` (component): A list of options with one label (role="group"). options: { value, label, description?, icon?, disabled? }[]; value / defaultValue / onValueChange (string[], kept in the options' order); label, description, error, required, invalid, disabled, readOnly; orientation ("vertical" | "horizontal", rows wrap); columns (1 | 2 | 3 | 4, one on phones); variant, size, tone, color, radius, labelPosition for every box; selectAll and selectAllLabel ("Select all"); max (0 = no limit) with maxLabel (n => `Choose up to ${n}`); name (every checked box submits its value, FormData.getAll(name)); fieldProps; classNames (group, all, option, box, indicator, icon, content, optionLabel, optionDescription plus the Field parts). Props: CheckboxGroupProps.
- `CheckboxIndicator` (component): The box alone, aria-hidden, with the same look and animation but no behavior: checked, size, tone, color, radius, invalid, disabled. For listbox rows (role="option" must not hold a real checkbox) and table cells that own the state. Props: CheckboxIndicatorProps.

```tsx
import { useState } from "react"
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"

const AMENITIES = [
  { value: "parking", label: "Parking" },
  { value: "balcony", label: "Balcony" },
  { value: "elevator", label: "Elevator" },
  { value: "laundry", label: "In-unit laundry" },
]

export function OrderConsent({ showError }: { showError: boolean }) {
  const [accepted, setAccepted] = useState(false)
  const [amenities, setAmenities] = useState<string[]>(["parking"])
  return (
    <form className="flex flex-col gap-4">
      <Checkbox
        name="terms"
        required
        checked={accepted}
        onCheckedChange={(checked) => setAccepted(checked === true)}
        label="I agree to the Terms and conditions"
        error={showError && !accepted ? "You need to accept the terms." : undefined}
      />
      <CheckboxGroup
        label="Amenities"
        name="amenities"
        columns={2}
        options={AMENITIES}
        value={amenities}
        onValueChange={setAmenities}
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/checkbox (Markdown: https://wingo-ui.com/components/checkbox.md)

#### Color Picker (`color-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add color-picker`

A color field with a saturation / brightness square, hue and opacity sliders, HEX / RGB / HSL inputs, swatches and an eyedropper.

Click the field (or the round swatch button) to open a panel under it: drag in the square to set saturation (left to right) and brightness (bottom to top), drag the hue bar, and with alpha the opacity bar; the thumb grows a little while you drag and the value updates live, once per frame. Below them the HEX / RGB / HSL switch changes which fields show (the output keeps its format); typed values apply on Enter or when the field loses focus, text that is not a color turns the field red and goes back to the last good color, ArrowUp / ArrowDown in a number field step by 1 (Shift by 10), and a 3-digit hex expands ("F60" is #FF6600). Tap a preset swatch to use it: a ring slides to it. In Chrome and Edge a pipette button picks any pixel on screen. Keyboard: Enter, Space or ArrowDown on the trigger opens the panel with focus in the square; in the square ArrowLeft / ArrowRight change saturation and ArrowUp / ArrowDown brightness by 1% (Shift 10%), PageUp / PageDown step brightness by 10%, Home / End go to no or full saturation; the hue and opacity bars take the arrow keys, Home and End; the swatches are a radio group moved with the arrow keys; Escape closes the panel and returns focus to the trigger. Clicking the label focuses the trigger. On a phone the panel opens in a bottom sheet, full width, with a taller square, 28px thumbs and larger swatches; the changes are a draft until Done, and dragging the sheet away keeps the old color. Disabled and read-only pickers never open. ColorPickerPanel (the panel alone, with the same value, format, alpha, swatches and labels props) is exported for your own popovers and pages, with the helpers parseColor (hex, rgb(), hsl() and the 16 basic CSS names, no canvas), formatColor, hsvaToRgba, rgbaToHsva and COLOR_PICKER_SWATCHES.

npm: @radix-ui/react-popover, @radix-ui/react-slider, motion, lucide-react
Wingo UI dependencies: button, drawer, field, segmented-control, use-controllable-state, use-media-query, motion, ui-config

Props:
- `label?: ReactNode` = "": The field label. The trigger reads it with the value ("Primary color, #FC4C01"); plain text also titles the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid.
- `required?: boolean` = false: The red mark after the label and aria-required on the trigger.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field and never opens the panel; the hidden input is not submitted.
- `readOnly?: boolean` = false: The color stays visible and the trigger focusable, but the panel never opens (inline: nothing can change).
- `defaultValue?: string` = "": The starting color while uncontrolled, any CSS color we can read ("#FC4C01", "rgb(252 76 1)", "hsl(18 99% 50%)", "red"). A form reset returns to it.
- `value?: string`: The color, controlled, as a CSS color in format ("" is empty). A value in another format is shown as given and re-emitted in format on the next change.
- `onValueChange?: (value: string) => void`: Called with the new color in format: live while dragging (at most once per frame), after a typed value, a swatch or the eyedropper. On phones only when Done is pressed.
- `onValueCommit?: (value: string) => void`: Called when a change is final: pointer up after a drag, Enter or blur in a field, a swatch, an eyedropper pick, a key in the square, the sheet's Done. Save here.
- `format?: "hex" | "rgb" | "hsl"` = "hex": The output: "#FC4C01", "rgb(252, 76, 1)" or "hsl(18, 99%, 50%)". Also the fields the panel shows first; the panel's switch only changes the fields. The exported parseColor(text) and formatColor(hsva, format, alpha) do the same conversions for your own code.
- `alpha?: boolean` = false: An opacity slider and an opacity field. Hex becomes #RRGGBBAA below 100% opacity; rgb and hsl always become rgba() / hsla(). Off, colors are always opaque.
- `swatches?: string[]` = "[\"#0A0A0A\", \"#525252\", \"#A3A3A3\", \"#FFFFFF\", \"#EF4444\", \"#F97316\", \"#F59E0B\", \"#EAB308\", \"#84CC16\", \"#22C55E\", \"#14B8A6\", \"#0EA5E9\", \"#3B82F6\", \"#6366F1\", \"#8B5CF6\", \"#EC4899\"]": Preset colors in a grid of 8 per row. Defaults to the exported COLOR_PICKER_SWATCHES: 16 colors (neutrals, red, orange, amber, yellow, lime, green, teal, sky, blue, indigo, violet, pink), easy to extend. [] hides the row.
- `showInputs?: boolean` = true: The format switch, the text fields and the eyedropper under the sliders.
- `showFormatSwitch?: boolean` = true: The HEX / RGB / HSL segmented control above the fields.
- `showEyeDropper?: boolean` = true: The pipette button. It only renders where the browser has window.EyeDropper (Chrome and Edge on desktop), so it never appears broken.
- `inline?: boolean` = false: Renders the panel in place (settings pages): no trigger, no popover, no sheet. Changes apply at once.
- `trigger?: "field" | "swatch"` = "field": A field box with a color chip and the value, or a round swatch button sized like an icon button (toolbars, compact forms).
- `placeholder?: string` = "Pick a color": The trigger's text while empty (with a checkerboard chip).
- `labels?: Partial<{ area; saturation; brightness; hue; alpha; hex; red; green; blue; hueInput; lightness; format; eyeDropper; swatches; done; trigger: string }>`: Every spoken and visible string, merged over English defaults ("Saturation and brightness", "Hue", "Opacity", "Done"...). trigger names the trigger when there is no label ("Color, #FC4C01").
- `size?: "sm" | "md" | "lg"` = "md": Trigger heights of 32, 40 and 48px (md is 44px on touch screens); the swatch button is square at the same sizes.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box look (trigger field): a tinted fill, a border, a bottom line, or nothing until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the field, scaled per size like the button; full also makes the color chip round. Ignored by underline.
- `name?: string` = "": Renders a hidden input with this name and the color text, for native forms.
- `defaultOpen?: boolean` = false: Starts with the panel (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the panel or sheet is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the panel or sheet opens or closes.
- `responsive?: boolean` = true: Below 768px the panel opens in a bottom sheet with a Done button that commits the draft. Off, phones get the popover too.
- `sheetTitle?: string` = "Pick a color": The phone sheet's title (and the popover's accessible name) when the label is not plain text or missing.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the panel opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the panel lines up with the trigger.
- `container?: HTMLElement | null`: Portal target of the panel and the sheet; defaults to document.body.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The trigger's id (the panel's with inline); generated when left out.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "trigger" | "swatch" | "value" | "chevron" | "content" | "panel" | "area" | "thumb" | "hue" | "alpha" | "preview" | "inputs" | "format" | "input" | "eyedropper" | "swatches" | "swatchOption" | "footer", string>>`: Extra classes for the inner parts. content is the popover or the sheet, thumb the square's thumb, input every text field in the panel.
- `className?: string`: Extra classes for the outermost element: the Field when there is a label or message, else the trigger (or the inline panel).
- `ref?: Ref<HTMLButtonElement> (a useRef object or an (el) => void callback)`: The trigger button. Other props (onBlur, autoFocus, aria-*, data-*) land on it too.

```tsx
import { useState } from "react"
import { ColorPicker } from "@/components/ui/color-picker"

export function StoreColor() {
  const [color, setColor] = useState("#FC4C01")
  return (
    <ColorPicker
      label="Primary color"
      description="The store's buttons and links use this color."
      value={color}
      onValueChange={setColor}
      onValueCommit={(saved) => console.log("saved", saved)}
      name="primary_color"
      placeholder="Choose a brand color"
      sheetTitle="Brand color"
      labels={{ swatches: "Brand presets", done: "Apply" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/color-picker (Markdown: https://wingo-ui.com/components/color-picker.md)

#### Combobox (`combobox`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add combobox`

An autocomplete field: type to filter a list or search a server, with matches in bold, a create row and free text; a search sheet on phones.

Type and the list opens under the field with the matching letters in bold and the best matches first ("st louis" finds Saint Louis, diacritics never matter); with loadOptions the query goes to your server after a short pause, a spinner shows in the field while the previous results stay, and an old answer never overwrites a newer one. Click an option (or press Enter on the highlighted one) to fill the field and close the list. Backspace edits the chosen text and the value clears once the text no longer spells it. When you leave the field the text goes back to the chosen option, or empties; with allowCustomValue whatever you typed becomes the value. With creatable a "Create" row appears when nothing matches exactly. The chevron toggles the list and the x clears it. Keyboard: ArrowDown opens the list (every option when the field is empty) and moves down, ArrowUp moves up, Alt+ArrowDown opens without moving, PageUp / PageDown jump, Enter picks, Escape closes the list and a second Escape clears the field, Home / End move the caret, Tab closes and keeps the rule above. With openOnFocus the list opens as soon as the field gets focus. On a phone the field never raises the keyboard: a tap opens a full-height sheet with a search box (the keyboard comes up at once) and Cancel, big 48px rows, and a tap on a result fills the field and closes the sheet; the keyboard's search key picks the first result. name submits the value through a hidden input.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: drawer, field, listbox, spinner, text-match, use-controllable-state, use-media-query, motion, ui-config

Props:
- `label?: ReactNode` = "": The label above the field; renders the field anatomy and names the list and the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid.
- `required?: boolean` = false: A red * after the label and required on the input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field and blocks typing and opening.
- `readOnly?: boolean` = false: The text stays visible and focusable; nothing opens and nothing can be typed.
- `options?: ComboboxItems ((ComboboxOption | { label?: ReactNode; items: ComboboxOption[] })[])` = "[]": Options and groups, filtered locally as you type. An option is { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? }. With loadOptions they show while the query is shorter than minQueryLength.
- `loadOptions?: (query: string, context: { signal: AbortSignal }) => Promise<ComboboxItems>`: Server search for the debounced query. The results replace the list, the previous ones stay while loading, a newer query aborts the older request, and the last 20 answers are cached.
- `debounce?: number` = 250: Milliseconds of quiet before loadOptions runs.
- `minQueryLength?: number` = 0: loadOptions waits for this many characters.
- `filter?: boolean, or (option: ComboboxOption, query: string) => score (number, null hides)` = true: true filters with text-match on the label and keywords; false means the options are already filtered; a function scores each option (null hides it).
- `fuzzy?: boolean` = false: Letters in order may have gaps ("sfco" finds San Francisco).
- `value?: string`: The chosen option's value (or the free text with allowCustomValue), controlled. A value that is not in the current results shows the cached option text, else the value.
- `defaultValue?: string` = "": The starting value while uncontrolled. A form reset returns to it.
- `onValueChange?: (value: string) => void`: Called with the new value; "" when it clears.
- `inputValue?: string`: The text in the field, controlled.
- `defaultInputValue?: string` = "": The starting text while uncontrolled; it filters the list like typed text.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event of every keystroke, untouched (react-hook-form's register works).
- `onInputValueChange?: (text: string) => void`: Called on every keystroke and when the text snaps to an option.
- `allowCustomValue?: boolean` = false: The typed text is a valid value (a street, a free label): it becomes the value on blur or Enter. Otherwise the text snaps back to the chosen option.
- `creatable?: boolean` = false: A create row when nothing matches exactly (first and highlighted when there are no results).
- `onCreate?: (query: string) => (string | void | Promise<string | void>)`: Runs for the create row; a returned value (or a promise of one) is selected, and a promise shows a spinner on the row. Without it the typed text becomes the value.
- `createLabel?: (query: string) => ReactNode` = "(q) => `Create \"${q}\"`": The create row's text.
- `placeholder?: string` = "": Shown while the field is empty, also in the phone sheet's search box.
- `emptyText?: string` = "No results": Shown when the query matches nothing.
- `loadingText?: string` = "Loading…": The first load's status row and the spinner's accessible name.
- `errorText?: string` = "Could not load results": Shown when loadOptions fails, above a retry button.
- `retryLabel?: string` = "Try again": The retry button under errorText.
- `clearLabel?: string` = "Clear": The accessible name of the x button.
- `toggleLabel?: string` = "Show suggestions": The accessible name of the chevron button.
- `highlightMatches?: boolean` = true: The matched letters of each option in bold.
- `openOnFocus?: boolean` = false: Opens with every option (or the recent picks you pass) as soon as the field gets focus.
- `autoHighlight?: boolean` = true: The first match is highlighted, so Enter picks it. Turn it off for free text, where Enter should keep what you typed.
- `clearable?: boolean` = true: An x while there is text or a value; Escape on a closed list clears too.
- `leftIcon?: ReactNode`: An icon before the text, like a MapPin. Unsized svgs follow the size.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px like every field; md grows to 44px on touch screens.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box: a filled well, an outline, a bottom line, or nothing until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button (md is 8 / 10 / 12px); also the sheet's search box.
- `defaultOpen?: boolean` = false: Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the list is open, controlled. It shows only when there is something to show, and never while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the list opens or closes.
- `responsive?: boolean` = true: Below 768px the field opens a full-height search sheet instead of the popover.
- `sheetTitle?: string` = "Search": The phone sheet's title for screen readers (its visible header is the search box); a string label wins.
- `cancelLabel?: string` = "Cancel": The text button next to the sheet's search box.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the list opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the list lines up with the field.
- `maxHeight?: number` = 360: The list's height limit in px, capped by the room on screen.
- `virtualThreshold?: number` = 100: Above this many rows only the visible ones render.
- `renderOption?: (option, state: { selected, highlighted, disabled, ranges }) => ReactNode`: Replaces a row's content; the row element, its aria and its classes stay.
- `name?: string` = "": Submits the value through a hidden input.
- `id?: string`: The input's id; generated when left out.
- `container?: HTMLElement | null`: Portal target for the list and the sheet (default document.body).
- `fieldProps?: Partial<FieldProps>`: Anything else for the field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "input" | "leftIcon" | "spinner" | "clear" | "toggle" | "content" | "list" | "item" | "group" | "status" | "sheet" | "sheetSearch" | "cancel", string>>`: Extra classes for the inner parts. content is the popover, sheet the phone sheet.
- `className?: string`: Extra classes for the outermost element: the Field when there is a label or message, else the combobox root.
- `ref?: Ref<HTMLInputElement> (a useRef object or an (el) => void callback)`: The text input. Other props (onBlur, onKeyDown, autoFocus, aria-*, data-*) land on it too; onChange gets the native event.

```tsx
import { useState } from "react"
import { MapPin } from "lucide-react"
import { Combobox, type ComboboxItems } from "@/components/ui/combobox"

async function searchCities(query: string, { signal }: { signal: AbortSignal }): Promise<ComboboxItems> {
  const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, { signal })
  const cities: { id: string; name: string; state: string }[] = await response.json()
  return cities.map((city) => ({ value: city.id, label: city.name, description: city.state }))
}

export function CityField() {
  const [city, setCity] = useState("")
  return (
    <Combobox
      label="City"
      placeholder="Search for a city"
      leftIcon={<MapPin />}
      loadOptions={searchCities}
      minQueryLength={1}
      value={city}
      onValueChange={setCity}
      emptyText="No cities found"
      errorText="Could not load cities"
      sheetTitle="Search cities"
      name="city"
    />
  )
}
```

Docs: https://wingo-ui.com/components/combobox (Markdown: https://wingo-ui.com/components/combobox.md)

#### Cron Picker (`cron-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add cron-picker`

Build a schedule without knowing cron: frequency tabs, weekday and day chips, a time, a sentence that says it back and the next runs.

Pick how often with the frequency tabs (arrow keys move between them; on a phone they show short names). Every few minutes and every few hours are a select in a sentence (a bottom sheet on phones), hourly adds the minute in a number field (arrows step, Shift steps by 5). Weekly shows seven day chips and monthly a 7-column grid of days 1 to 31: tap or press Space to toggle a chip, arrows move between chips, and each chip pops in on a quick spring. The time opens columns on desktop and a wheel sheet on phones. Every change rewrites the expression at once: the sentence under the fields says it back ("Every weekday at 9:00 AM") and screen readers hear it half a second after you stop, the expression chip copies with one click, and the next runs slide into place with the date, the time and how far away they are. Custom takes a raw expression, validated as you type with a message per field ("Hour must be between 0 and 23"), or five small boxes with By field; Enter never submits the form around it. Weekly or monthly with nothing picked says what is missing. Read-only keeps the sentence and the expression; reduced motion turns the slides into fades.

npm: motion, lucide-react
Wingo UI dependencies: badge, copy-button, field, input, number-input, segmented-control, select, time-picker, toggle-group, use-controllable-state, use-locale, date-utils, relative-time, motion, tones, ui-config

Props:
- `value?: string`: The controlled cron expression: 5 fields (minute hour day month weekday) with *, lists, ranges, steps, JAN / MON names and @daily-style macros. It is "" while a weekly or monthly tab has nothing picked.
- `defaultValue?: string` = "0 9 * * 1-5": The uncontrolled start. The tab it opens on comes from detectFrequency; anything the tabs cannot express (or an invalid expression) opens Custom. Try "*/15 9-17 * * 1-5" or "0 25 * * *".
- `onValueChange?: (value: string) => void`: Every change from the tabs, chips, fields or the custom input, with the new expression (invalid custom text too, so a form can block saving).
- `frequencies?: CronFrequency[] ("minutes" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "custom")` = "[\"minutes\", \"hourly\", \"daily\", \"weekly\", \"monthly\", \"custom\"]": The tabs, in order. Add "yearly" for dates like 1 January; custom only shows while allowCustom is on.
- `showSummary?: boolean` = true: The sentence that says the schedule back, in Romanian or English, with correct plurals.
- `showExpression?: boolean` = true: The expression as a mono chip with a copy button (and the time zone badge when timeZone is set).
- `showNextRuns?: number` = 5: How many next runs to list, with the date, the time and a relative label ("tomorrow"). 0 hides the list.
- `allowCustom?: boolean` = true: The Custom tab: a raw expression input or five labelled boxes, validated as you type.
- `minuteIntervals?: number[]` = "[5, 10, 15, 30]": The choices for every N minutes. An incoming step outside the list (*/7) is added so it still shows.
- `hourIntervals?: number[]` = "[1, 2, 3, 4, 6, 12]": The choices for every N hours.
- `weekStartsOn?: Weekday | -1 (0 Sunday to 6 Saturday)` = -1: The weekday chip order. -1 follows the locale: Monday first in ro-RO, Sunday in en-US.
- `timeZone?: string` = "": An IANA zone ("America/New_York") the expression is read in: the next runs are computed and shown in it, and a badge names it. Empty uses the device's zone.
- `hourCycle?: "auto" | "h12" | "h23"` = "auto": 12 or 24 hours for the time field, the sentence and the next runs. auto follows the locale (24h in ro-RO).
- `layout?: "stacked" | "split"` = "stacked": split puts the fields on the left and the summary and next runs on the right once the picker is 672px wide (a container query); stacked always on phones.
- `now?: Date | number`: The moment the next runs count from. Default the current minute (useNow), with placeholder rows during server rendering.
- `label?: ReactNode` = "": The field label above the picker. Clicking it focuses the frequency tabs.
- `description?: ReactNode` = "": Helper text under the picker, replaced by the error while one shows.
- `error?: ReactNode` = "": An error from your form under the picker; it also marks the field invalid. Custom expression errors show on the input itself.
- `required?: boolean` = false: The required mark after the label and aria-required.
- `invalid?: boolean` = false: The invalid state without a message (aria-invalid on the group).
- `disabled?: boolean` = false: Dims and blocks every control inside.
- `readOnly?: boolean` = false: Shows only the sentence and the expression (with copy), for a job list or a details page.
- `size?: "sm" | "md" | "lg"` = "md": The tabs 32 / 40 / 48px, the chips 32 / 36 / 40px (44px on touch), the inline controls sm, sm and md, and the sentence text.
- `variant?: "soft" | "outline" | "ghost"` = "soft": The box of the inline select, number, time and custom inputs.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the tabs, the inputs and the chips (full makes round day chips).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected chips, the frequency thumb and the summary icon.
- `color?: string` = "": Any CSS color for the selected chips and the thumb; replaces the tone.
- `name?: string` = "": Adds a hidden input with the expression (empty while invalid), for plain form posts. The demo prints it under the picker.
- `locale?: string` = "": Sentence language (ro and en built in, others through labels), weekday and month names, dates and times. Empty uses the UIProvider locale, then the browser's. The demo defaults to en-US.
- `labels?: Partial<CronPickerLabels>`: Every string: frequencies and frequenciesShort, the sentence-row words (every, minutesUnit(n), atMinute, atTime), chip group names, custom tab strings, copy / copied, nextRuns, noRuns, invalid, pickDay, pickMonth, useFiveFields, outOfRange(field, min, max), badField(field), unknownTimeZone, increment / decrement (the minute steppers), timePicker (the time sheet: Done, Hours...), weekday and month names, and the sentence builders. A ro locale picks CRON_PICKER_LABELS_RO on its own.
- `fieldProps?: Partial<FieldProps>`: More for the field wrapper: optional, optionalLabel, labelAction, hideLabel, className.
- `id?: string`: The group's id; the label points at it.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "frequency" | "fields" | "interval" | "minute" | "weekdays" | "monthDays" | "months" | "time" | "custom" | "summary" | "expression" | "next" | "run", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the root (the field wrapper when a label, description or error is set).

Parts:
- `parseCron` (function): The five fields ({ minute, hour, dayOfMonth, month, dayOfWeek }) with macros expanded, or null for anything that is not 5-field cron (6 or 7 fields, @reboot). Signature: (expr: string) => CronParts | null.
- `isValidCron` (function): True for a valid 5-field expression. Signature: (expr: string) => boolean.
- `validateCron` (function): Why an expression is invalid: the field count, a value out of range (with the field and bounds) or a syntax error in one field. cronErrorMessage(error, labels) turns it into words. Signature: (expr: string) => { valid: true; parts: CronParts } | { valid: false; error: CronError }.
- `describeCron` (function): The sentence: "Every weekday at 9:00 AM", "Mondays, Wednesdays and Fridays at 8:30 AM", "On the 1st and 15th at 8:00 AM". Signature: (expr: string, { locale?, labels?, hourCycle? }) => string.
- `getNextRuns` (function): The next runs after from, minute-accurate, up to 4 years ahead: skips 31 February, follows cron's day-of-month OR day-of-week rule when both are set, and reads the expression in timeZone. Signature: (expr: string, { from?, count = 5, timeZone? }) => Date[].
- `detectFrequency` (function): The tab an expression opens on; "custom" for invalid ones and for what the tabs cannot express. Signature: (expr: string) => CronFrequency.
- `DEFAULT_CRON_PICKER_LABELS` (constant): The English default labels, to spread and override. Type: CronPickerLabels.
- `CRON_PICKER_LABELS_RO` (constant): The ready Romanian set (sentences with plurals and weekday articles: "lunea", "20 de minute"). Type: CronPickerLabels.

```tsx
import { useState } from "react"
import { CronPicker, describeCron } from "@/components/ui/cron-picker"

export function ReportSchedule() {
  const [cron, setCron] = useState("0 9 * * 1-5")
  return (
    <div className="flex flex-col gap-3">
      <CronPicker
        label="Send the report"
        value={cron}
        onValueChange={setCron}
        locale="en-US"
        timeZone="America/New_York"
        name="schedule"
      />
      <p className="text-sm text-muted-foreground">{describeCron(cron, { locale: "en-US" })}</p>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/cron-picker (Markdown: https://wingo-ui.com/components/cron-picker.md)

#### Currency Input (`currency-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add currency-input`

A money field formatted per locale as you type, with the symbol on the right side, an optional currency selector and quick amounts.

Type an amount the way you write it: in English 1234.5 becomes 1,234.5 as you type, in Romanian 1.234,5, and either a comma or a dot typed at the end becomes the decimal. Letters never get in, extra decimals are cut, and a currency without cents (JPY) ignores the decimal key. The symbol sits where the locale puts it ($1,234.56, 1.234,56 lei) and is not part of the text. When the field loses focus, or on Enter, the amount is padded to the currency's decimals (1,234.5 becomes 1,234.50) and clamped to min and max; out of range while typing, the field shows the red ring. Focusing the field selects the amount so the next keys replace it. ArrowUp and ArrowDown add or take away one step, Shift ten steps. With clearable, the x or Escape empties the field. With two or more currencies a compact code button (USD) sits at the end of the box: click it or press Enter, Space or the arrows on it to open the list (a bottom sheet on phones), type a letter to jump to a currency, and pick one; the symbol crossfades and the amount stays the same (it is never converted). Quick amounts sit as chips under the field; tapping one fills it in and the matching chip turns solid. Pasting 1 234,56 € or $1,234.56 over the field reads the whole amount. On a phone the decimal keypad opens (either separator is accepted), the text is 16px so iOS never zooms, the md box grows to 44px and the chips and the currency button have 44px hit areas.

npm: motion, lucide-react
Wingo UI dependencies: button, field, select, number-format, use-locale, motion, use-controllable-state, ui-config

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the box and links it to the input with htmlFor. Leave it empty for a bare field.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby (followed by a hidden "Amount in …" naming the currency). The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid (red ring, aria-invalid).
- `required?: boolean` = false: The mark after the label, and required on the input, so native form validation stops an empty submit.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message. An amount outside min and max sets it on its own until it is back in range.
- `disabled?: boolean` = false: Dims the field to 50%, blocks typing, the currency button and the chips, and leaves the hidden inputs out of the submit.
- `readOnly?: boolean` = false: The amount stays visible and selectable; typing, the arrows, the currency list and the chips stop.
- `placeholder?: string` = "": Hint text while the field is empty. Empty shows zero in the locale and the currency's decimals ("0.00" in en-US, "0" for JPY).
- `name?: string` = "": Renders a hidden input with this name and the amount as "1234.56" (dot decimal, empty when null), so FormData gets a number, not the formatted text. The visible input has no name.
- `currencyName?: string` = "": With a currency selector, a second hidden form field with the chosen code ("EUR").
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px, like a button. md grows to 44px on touch screens and the text is 16px on phones so iOS never zooms.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box: a soft fill, an outline, a bottom border that grows a bar on focus, or ghost for tables and toolbars.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button (md is 8 / 10 / 12px); the currency button follows it. Ignored by underline.
- `currencyDisplay?: "narrowSymbol" | "symbol" | "code" | "name"` = "narrowSymbol": How the currency reads next to the amount and on the chips: narrowSymbol is what people write ("$", "€", "lei"), symbol and code print "RON" for lei, name spells it out ("US dollars").
- `defaultCurrency?: string` = "USD": The starting ISO 4217 code while uncontrolled. Its decimals (USD 2, JPY 0) and symbol follow.
- `locale?: string` = "": Formats and parses with this locale: separators, and which side the symbol goes on. Empty uses the nearest LocaleProvider, then the page language. The demo passes "en-US".
- `min?: number` = -90071992547409: The lowest amount. A lower typed amount shows invalid and is clamped on blur; the arrows stop here. Without allowNegative nothing goes below 0 anyway.
- `max?: number` = 90071992547409: The highest amount, the same way. Anything above Number.MAX_SAFE_INTEGER / 100 cannot be typed at all.
- `decimals?: number` = -1: Fraction digits typed and padded to (0 to 6). The default -1 takes the currency's: USD 2, JPY 0, BHD 3.
- `allowNegative?: boolean` = false: Lets a minus in (a balance adjustment, a refund). iOS decimal keypads have no minus key: negatives come from ArrowDown or a hardware keyboard.
- `step?: number` = 1: What ArrowUp and ArrowDown add or take away; Shift moves ten steps.
- `clearable?: boolean` = false: An x at the end while there is an amount; Escape clears too. Focus stays in the field.
- `selectOnFocus?: boolean` = true: Selects the whole amount when the field takes focus (a click too), so typing replaces it.
- `responsive?: boolean` = true: The currency list becomes a bottom sheet below 768px.
- `value?: number | null`: The controlled amount in major units (1234.56); null is an empty field. An amount outside min and max shows as given and is flagged invalid.
- `defaultValue?: number | null` = "null": The starting amount while uncontrolled. A form reset returns to it.
- `onValueChange?: (value: number | null) => void`: Every change: live while typing (unclamped until blur), arrows, chips, clearing, and the rounding when a currency with fewer decimals is picked.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native input event, for keystrokes the field accepts.
- `currency?: string`: The controlled ISO 4217 code. Switching currency never converts the amount.
- `onCurrencyChange?: (currency: string) => void`: When a currency is picked from the selector.
- `currencies?: string[]`: Two or more codes show the currency selector: a compact code button at the end of the box, opening a list with the localized names ("US dollar", "Euro") and symbols. With the selector, a suffix symbol is left out (the button names the currency); a prefix one ($) stays.
- `presets?: number[]`: Quick amounts as chips under the field ("$50", "$100"), 44px hit areas on touch. The chip equal to the amount is solid and aria-pressed.
- `labels?: Partial<{ currency: string; clear: string; presets: string; amountIn: (currencyName: string) => string }>`: Accessible names, merged over English defaults: currency ("Currency", the button reads "Currency: USD" and titles the phone sheet), clear ("Clear"), presets ("Quick amounts", the chips group) and amountIn (n => `Amount in ${n}`, read with the field).
- `container?: HTMLElement | null`: Portal target for the currency list. Defaults to document.body.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional and optionalLabel, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The input's id. Defaults to useId(); inside a <Field> the Field's id wins.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native text input. Every other native prop lands there too: inputMode (decimal), enterKeyHint (done), autoComplete (transaction-amount), onBlur, onKeyDown, aria-* and data-*.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "input" | "symbol" | "currency" | "clear" | "presets" | "preset", string>>`: Extra classes for the inner parts. box targets the field box, input the native element, currency the code button, preset every chip.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description or error, else the box (or the column holding box and chips).

```tsx
import { useState } from "react"
import { CurrencyInput } from "@/components/ui/currency-input"

export function ListingPrice() {
  const [price, setPrice] = useState<number | null>(1250)
  const [currency, setCurrency] = useState("USD")

  return (
    <form className="flex flex-col gap-4">
      <CurrencyInput
        name="price"
        currencyName="currency"
        label="Price"
        description="The price includes tax"
        locale="en-US"
        currencies={["USD", "EUR", "GBP"]}
        currency={currency}
        onCurrencyChange={setCurrency}
        value={price}
        onValueChange={setPrice}
        min={1}
        error={price !== null && price < 1 ? "The minimum price is $1" : undefined}
        required
      />
      <CurrencyInput label="Donation" locale="en-US" presets={[50, 100, 200, 500]} defaultValue={100} clearable />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/currency-input (Markdown: https://wingo-ui.com/components/currency-input.md)

#### Date Picker (`date-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add date-picker`

A date field to type in your locale or pick from a calendar popover, with presets, limits and an optional time; a sheet on phones.

Type a date the way your locale writes it: "09232026" becomes "09/23/2026" as you type (separators appear after each group), "9/23" means this year, a 2 digit year picks the nearest century, ISO "2026-09-23" always works, "+3" is three days from today, and keywords like "today", "tomorrow" or "yesterday" work (other languages through parseKeywords). Clicking the field opens the calendar under it without taking focus from the text; while you type, the calendar follows and highlights the typed day, and a complete, allowed date is committed at once. On blur the text is re-written in the display format; text that does not parse shows invalidDateText, and a day outside min / max or a disabled day shows outOfRangeText. Escape in the field brings back the last good date. Clicking a day (or a preset chip: Today, Tomorrow, Next week or your own) sets it and closes the panel; with withTime a time field sits under the calendar and Done closes. The calendar button toggles the panel; the clear button empties the field. Keyboard: ArrowDown (or Alt+ArrowDown) opens the panel and moves focus to the selected day (else today); arrows move a day or a week, Home / End the week's ends, PageUp / PageDown a month (Shift: a year), Enter or Space picks and returns focus to the field, Escape closes without changing anything. With editable off the field is a button: a click, Enter, Space or ArrowDown open the calendar and a second click closes it. The calendar button opened from the keyboard moves focus to the selected day too. On a phone the field never raises the keyboard: a tap opens a bottom sheet with the title, presets as a row of chips, the calendar with 44px days you can swipe between months, and the time field when withTime (it opens its own wheel sheet); a tap on a day commits and closes, and with withTime or closeOnSelect off the sheet has Done and Clear buttons and dragging it away keeps the old date. name submits the ISO date through a hidden input.

npm: @radix-ui/react-popover, date-fns, motion, lucide-react
Wingo UI dependencies: button, calendar, drawer, field, time-picker, date-utils, use-controllable-state, use-locale, use-media-query, motion, tones, ui-config

Props:
- `label?: ReactNode` = "": The field label, linked to the input. Plain text also titles the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid. It wins over invalidDateText and outOfRangeText.
- `required?: boolean` = false: The red mark after the label and required on the input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message. A controlled value outside min / max is flagged the same way.
- `disabled?: boolean or DateMatcher or DateMatcher[] (DateMatcher: Date, Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean)` = false: true dims the field, blocks typing and never opens the calendar (the hidden input is not submitted). A DateMatcher instead disables those days: a date, a list, { from, to }, { before }, { after }, { dayOfWeek: [0, 6] } for weekends, or a test function.
- `readOnly?: boolean` = false: The date stays visible and selectable but can not change: no typing, no calendar, no clear button.
- `value?: Date | null`: The date, controlled (null is empty). With withTime the Date carries the time. A value outside min / max shows as given and is flagged invalid.
- `defaultValue?: Date | null` = "null": The starting date while uncontrolled. A form reset returns to it.
- `onValueChange?: (date: Date | null) => void`: Called with the new local Date as soon as a complete typed date is allowed, and after a day, a preset, a time, Clear or the sheet's Done. null when cleared.
- `placeholder?: string` = "": Empty uses the locale's pattern in lowercase ("dd.mm.yyyy", "mm/dd/yyyy"). Localized forms pass their own, like "zz.ll.aaaa" in Romanian. It also becomes the screen reader format hint.
- `locale?: string` = "": How dates are read and written, the month and weekday names and the first day of the week: ro-RO 23.09.2026 from Monday, en-US 09/23/2026 from Sunday. Empty uses the nearest LocaleProvider, else the page's language.
- `displayFormat?: Intl.DateTimeFormatOptions`: How the value shows while the field is not focused ({ dateStyle: "long" } gives "March 5, 1990"). Typing is always numeric. Default: 2 digit day and month, numeric year.
- `editable?: boolean` = true: Typing on desktop. Off, the field is a button that only opens the calendar (phones always work that way).
- `autoFormat?: boolean` = true: Separators appear as digits are typed: "2309" becomes "23.09.".
- `parseKeywords?: Partial<Record<"today" | "tomorrow" | "yesterday", string[]>>`: Words that mean a day, matched without case or diacritics. English by default; another language passes its own words, e.g. { today: ["hoy"], tomorrow: ["mañana"], yesterday: ["ayer"] }.
- `min?: Date`: The first day that can be picked. Earlier days are disabled, navigation stops at its month and a typed earlier date shows outOfRangeText.
- `max?: Date`: The last day that can be picked (18 years ago for a birthday).
- `presets?: boolean | { label: ReactNode; value: Date | (() => Date); key?: string }[]` = false: Chips above the calendar. true gives Today, Tomorrow and Next week; or pass your own. A preset outside the limits is disabled.
- `presetLabels?: Partial<{ today: string; tomorrow: string; nextWeek: string }>`: Names of the built-in presets ("Today", "Tomorrow", "Next week").
- `clearable?: boolean` = true: A clear button in the field while it has a date (and Clear in the panel footer and the sheet).
- `withTime?: boolean` = false: A time field under the calendar; the value keeps both and the field reads "24.09.2026, 14:30". Picking a day keeps the panel open until Done. Clearing keeps the time for the next pick.
- `timeStep?: number` = "15": Minute step of the time field.
- `hourCycle?: "auto" | "h12" | "h23"` = "auto": 12 or 24 hours for the time; auto follows the locale.
- `timeProps?: Partial<TimePickerProps>`: Anything else for the time field: labels, min, max, disabledTimes, showNow.
- `closeOnSelect?: boolean` = true: Picking a day closes the panel. Never with withTime. Off, the panel (and the sheet) get a Done button.
- `responsive?: boolean` = true: Below 768px the field opens a bottom sheet instead of the popover. Off, phones get the popover and can type.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: The first day of the week: 0 Sunday ... 6 Saturday; -1 follows the locale (Monday in ro-RO, Sunday in en-US).
- `fixedWeeks?: boolean` = true: Six weeks in every month, so the panel never changes height while you browse.
- `monthYearPicker?: boolean` = true: The calendar caption opens a months grid, then a years grid, for fast jumps (birthdays).
- `numberOfMonths?: number` = 1: Months side by side in the popover (1 to 3). The phone sheet always shows one.
- `events?: { date: Date; tone?: Tone; color?: string; label?: string }[]`: Dots under days (deliveries, deadlines); labels join the day's aria-label.
- `calendarProps?: Partial<CalendarProps>`: Anything else for the calendar: size, radius, strikeDisabled, showWeekNumbers, todayButton, renderDay, labels.
- `invalidDateText?: string` = "Enter a valid date": The error after blur while the text does not parse ("31.02.2026").
- `outOfRangeText?: string` = "This date is not available": The error after blur for a typed day outside min / max or a disabled day.
- `defaultOpen?: boolean` = false: Starts with the calendar (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the calendar is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the popover or sheet opens or closes.
- `size?: "sm" | "md" | "lg"` = "md": Field heights of 32, 40 and 48px (md is 44px on touch screens), with matching text.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box: a tinted fill, a border, a bottom line that grows on focus, or nothing until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the field, scaled per size like the button. Ignored by underline.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected day, the chosen preset and the Done button.
- `color?: string` = "": Any CSS color for the selection; replaces the tone.
- `icon?: ReactNode`: The calendar button's icon.
- `sheetTitle?: string` = "Select date": The phone sheet's title when the label is not plain text (or missing).
- `labels?: Partial<{ clear; open; done; dialog; time; presets; format: string }>`: Every other string, merged over the English defaults ("Clear", "Open calendar", "Done", "Choose date", "Time", "Quick picks", "Format: {format}"). format is the screen reader hint after the field.
- `name?: string` = "": A hidden input with this name and the local ISO date ("2026-09-23", "2026-09-23T14:30" with withTime), never shifted to UTC.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the popover opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the popover lines up with the field.
- `container?: HTMLElement | null`: Portal target of the popover and the sheet; defaults to document.body.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The input's id; generated when left out.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "input" | "trigger" | "clear" | "content" | "presets" | "preset" | "calendar" | "time" | "footer", string>>`: Extra classes for the inner parts. content is the popover (or the sheet).
- `className?: string`: Extra classes for the outermost element: the Field when there is a label or message, else the box.
- `ref?: Ref<HTMLInputElement> (a useRef object or an (el) => void callback)`: The text input. Other props (onBlur, autoFocus, aria-*, data-*) land on it too.

```tsx
import { useState } from "react"
import { addDays } from "date-fns"
import { DatePicker } from "@/components/ui/date-picker"

export function DeliveryDate() {
  const [date, setDate] = useState<Date | null>(null)
  return (
    <DatePicker
      label="Delivery date"
      description="We deliver Monday to Friday."
      value={date}
      onValueChange={setDate}
      locale="en-US"
      min={addDays(new Date(), 1)}
      disabled={{ dayOfWeek: [0, 6] }}
      presets
      presetLabels={{ nextWeek: "In a week" }}
      invalidDateText="That date does not exist"
      outOfRangeText="We do not deliver on that day"
      sheetTitle="Delivery date"
      name="delivery_date"
    />
  )
}
```

Docs: https://wingo-ui.com/components/date-picker (Markdown: https://wingo-ui.com/components/date-picker.md)

#### Date Range Picker (`date-range-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add date-range-picker`

A date range field for reports and bookings: two months with presets and Apply / Cancel on desktop, a bottom sheet with one month on phones.

Click the field to open a panel under it: presets on the left (Last 7 days, This month, Last quarter...), two months on the right and a summary with Cancel and Apply at the bottom. The first click on a day sets the start, the band follows the pointer as a preview, and the second click sets the end (a day before the start swaps them); days that would break minDays, maxDays or cross a disabled day are unavailable while you pick the end. A preset fills both ends and moves the calendar to it. The summary under the calendar updates as you go (the dates, then "· 7 days"), and Apply commits; Cancel, Escape or a click outside throw the draft away, so a half-picked range never reaches the value. With confirm={false} the range commits as soon as both ends are picked, or on a preset. The clear button in the field empties it. Keyboard: Enter, Space or ArrowDown on the field open the panel and move focus into the calendar (the start of the range, else today); arrows move a day or a week, Home / End jump to the week's ends, PageUp / PageDown move a month (Shift: a year), Enter picks the start and then the end; Tab reaches Cancel and Apply, Shift+Tab the presets (arrow keys move between presets); Ctrl+Enter (Cmd+Enter on a Mac) applies from anywhere in the panel; Escape cancels and returns focus to the field. On a phone the field opens a bottom sheet with the presets as a row of chips, two Start / End cells (the end being picked is outlined), one month you can swipe, and Apply / Cancel pinned above the home indicator; dragging the sheet down cancels.

npm: @radix-ui/react-popover, date-fns, motion, lucide-react
Wingo UI dependencies: button, calendar, drawer, field, date-utils, use-controllable-state, use-locale, use-media-query, motion, tones, ui-config

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the trigger. A string label also titles the phone sheet and names the panel. A click on the label focuses the trigger without opening it.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid (red ring, aria-invalid on the trigger).
- `required?: boolean` = false: The mark after the label and aria-required on the trigger.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean or DateMatcher or DateMatcher[] (DateMatcher: Date, Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean)` = false: true dims the field, blocks it and leaves the hidden inputs out of the submit. A DateMatcher instead disables those days in the calendar: a Date, a list, { from, to }, { before }, { after }, { dayOfWeek: [0, 6] } or a (date) => boolean test (booked nights, holidays).
- `readOnly?: boolean` = false: The value stays visible and the trigger focusable, but it never opens and the clear button hides.
- `size?: "sm" | "md" | "lg"` = "md": The field box: 32 / 40 / 48px (md is 44px on touch screens), like every other field.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box look, shared with every field.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The box corners, per size like the button (8 / 10 / 12px at md). Ignored by underline.
- `placeholder?: string` = "Select dates": The trigger text while no range is set.
- `locale?: string` = "": Month and weekday names, digits, the first day of the week and the trigger text. Empty: the nearest LocaleProvider, else the browser.
- `displayFormat?: Intl.DateTimeFormatOptions`: How the trigger and the summary write the range, through Intl formatRange: { day: "numeric", month: "short", year: "numeric" } gives "1 to 30 sept. 2026" joined by an en dash; only a start gives the start followed by a dash.
- `numberOfMonths?: 1 | 2 | 3` = 2: Months side by side on desktop. The panel drops months that do not fit the screen; phones always show one.
- `presets?: boolean | (RangePresetKey | DateRangePreset)[]` = true: true: Last 7 days, Last 30 days, This month, Last month, This quarter, Last quarter, This year. Or a list mixing built-in keys ("today", "yesterday", "last90Days", "thisWeek", "lastWeek", "lastYear", "yearToDate"...) and your own { label, value: DateRange | () => DateRange }. Presets that run past min / max are cut to them; fully outside, or longer than maxDays, they are disabled.
- `presetLabels?: Partial<Record<RangePresetKey, string>>`: Labels for the built-in presets (English by default).
- `min?: Date`: Earlier days are disabled and the calendar stops at this month.
- `max?: Date`: Later days are disabled (reports pass today) and the calendar stops at this month.
- `minDays?: number` = 0: The shortest range in days, both ends counted (a 2 night stay is 3 days). Closer ends are unavailable while picking.
- `maxDays?: number` = 0: The longest range in days, both ends counted. Further ends are unavailable while picking, longer presets are disabled.
- `excludeDisabled?: boolean` = true: A range can not span a disabled day: past the first one, the days are unavailable while picking the end (bookings).
- `confirm?: boolean` = true: Apply / Cancel buttons; the value only changes on Apply. false commits and closes as soon as both ends are picked, or on a preset.
- `clearable?: boolean` = true: A clear button in the field while a range is set.
- `showDuration?: boolean` = true: The summary shows the length ("7 days", or nights with labels.nights).
- `labels?: { apply?; cancel?; clear?; start?; end?; pickStart?; pickEnd?; presets?; duration?: (days) => string; nights?: (nights) => string }`: Every string of the panel: { apply: "Apply", cancel: "Cancel", clear: "Clear", start: "Start", end: "End", pickStart: "Pick a start date", pickEnd: "Pick an end date", presets: "Presets", duration: (d) => d + " days" }. nights switches the summary to nights (a 4 day stay is 3 nights).
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: 0 Sunday ... 6 Saturday; -1 follows the locale (Monday in ro-RO, Sunday in en-US).
- `events?: CalendarEvent[]`: Dots under days in the calendar: { date, tone?, color?, label? }.
- `calendarProps?: Partial<CalendarProps<"range">>`: Anything else for the calendar: size, radius, strikeDisabled, showWeekNumbers, renderDay, labels (Romanian month navigation), fixedWeeks (on by default so the panel never changes height).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of the picked ends, the band, the active preset check, the outline of the cell being picked and the Apply button.
- `color?: string` = "": Any CSS color; replaces the tone. Text on the fill turns black or white by lightness.
- `icon?: ReactNode`: The leading icon of the field (CalendarRange by default).
- `defaultOpen?: boolean` = false: Starts open while uncontrolled.
- `value?: DateRange`: The committed range, controlled: { from: Date | null; to: Date | null }. A value with only from shows the start followed by a dash; a backwards one is shown in order.
- `defaultValue?: DateRange`: The starting range while uncontrolled; { from: null, to: null } by default. A form reset returns to it.
- `onValueChange?: (range: DateRange) => void`: Called on Apply, on a clear, or as soon as both ends are picked with confirm={false}. Never with a half-picked draft.
- `open?: boolean`: The panel or sheet, controlled. Pair it with onOpenChange. Every opening starts from the committed value.
- `onOpenChange?: (open: boolean) => void`: Called when the panel opens or closes.
- `responsive?: boolean` = true: A bottom sheet below 768px instead of the popover.
- `sheetTitle?: string` = "Select dates": The sheet title and the panel name when the label is not plain text.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the panel opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": The panel's alignment against the field.
- `container?: HTMLElement | null`: Portal target for the panel and the sheet (document.body by default).
- `name?: string` = "": Renders hidden inputs name.from and name.to with ISO dates ("2026-09-23", local, never UTC).
- `id?: string`: The trigger's id (generated by default); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the field wrapper: optional, labelAction, orientation, labelWidth, hideLabel, className.
- `classNames?: Partial<Record<DateRangePickerSlot, string>>`: Classes for the parts: field, label, description, error, counter, box, trigger, icon, value, clear, chevron, content, presets, preset, calendar, footer, summary, cell (the phone Start / End cells), actions. className goes on the field root (or the box without a label).
- `ref?: RefObject<HTMLButtonElement | null> or (node) => void`: The trigger button; the rest of the props (onBlur, aria-*, data-*) land on it too, so react-hook-form can focus and touch it.

```tsx
import { useState } from "react"
import { DateRangePicker, type DateRange } from "@/components/ui/date-range-picker"

export function SalesReport() {
  const [range, setRange] = useState<DateRange>({ from: null, to: null })

  return (
    <DateRangePicker
      label="Period"
      name="period"
      locale="en-US"
      placeholder="Pick a period"
      max={new Date()}
      value={range}
      onValueChange={setRange}
      presetLabels={{ lastQuarter: "Previous quarter" }}
      labels={{ duration: (days) => (days === 1 ? "1 day" : `${days} days`) }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/date-range-picker (Markdown: https://wingo-ui.com/components/date-range-picker.md)

#### Date Time Picker (`date-time-picker`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add date-time-picker`

A day and a time in one field: a calendar beside a column of free time slots, presets and a time zone label; a sheet on phones.

Click the field (or press Enter, Space or ArrowDown on it) to open a panel under it: an optional row of preset chips (In 1 hour, Tomorrow 9:00, Monday 9:00 or your own), the calendar and, beside it, a column of time slots for the chosen day. Clicking a day shows its times and keeps the time you had if that slot is free that day; otherwise the first free slot is highlighted and the field shows the day with --:-- until you click a time. Clicking a time sets the value at once and the panel stays open until Done, Enter, Escape or a click outside; the selected slot's fill glides between slots of the same day. Taken slots are struck through and can not be picked, slots from getTimeSlots can carry a note ("2 locuri"), a promise shows pulsing placeholders, and a failed request shows a retry button. A preset sets day and time together and closes. The footer shows the time zone (a select when timeZones is set: switching it keeps the moment and moves the wall clock) and Done; the inline panel shows a summary of the pick there instead. Keyboard: focus lands on the selected day (else today); arrows move by day and week, PageUp / PageDown by month, Enter picks the day; Tab moves to the time list, where the arrows move one slot, Home / End jump to the ends, PageUp / PageDown move four slots, typing digits jumps ("14" to 14:00, "9" to 09:00), Space picks and Enter picks and closes; Tab reaches the zone select and Done; Escape closes and returns focus to the field. On a phone the field opens a bottom sheet instead: presets and times are horizontal chip rails with 44px chips (the chosen time scrolls to the center), the calendar is full width, and the choice is a draft that the big Done button commits; dragging the sheet away keeps the old value. Below 640px the inline panel (and a popover with responsive off) puts the times in a grid under the calendar instead of a column beside it. Clear (clearable) empties the field.

npm: @radix-ui/react-popover, date-fns, motion, lucide-react
Wingo UI dependencies: button, calendar, drawer, field, select, date-utils, relative-time, use-controllable-state, use-locale, use-media-query, motion, tones, ui-config

Props:
- `label?: ReactNode` = "": The field label. Plain text also titles the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an error and marks the field invalid.
- `required?: boolean` = false: The required mark after the label and aria-required on the trigger.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field and never opens the panel; the hidden input is not submitted.
- `readOnly?: boolean` = false: Shows the value but never opens the panel (inline: picks are ignored).
- `value?: Date | null`: The moment, controlled (an absolute Date; null is empty). A value off the step grid (16:37) shows as is and as an extra slot in the list.
- `defaultValue?: Date | null` = "null": The starting moment while uncontrolled. A form reset returns to it.
- `onValueChange?: (value: Date | null) => void`: Called when a slot or a preset is picked, when a new day keeps the chosen time, on Clear, and on the sheet's Done.
- `minuteStep?: number` = 15: Minutes between slots when getTimeSlots is not set; also rounds the In 1 hour preset.
- `startTime?: string` = "00:00": The first slot of the day, "HH:mm" ("08:00" for business hours).
- `endTime?: string` = "23:59": The last possible slot of the day, "HH:mm".
- `getTimeSlots?: (day: Date) => a list of "HH:mm" strings or DateTimeSlot objects, or a Promise of that list`: Availability per day (a local midnight Date for the wall day in the zone), replacing the step list. Items are "HH:mm" or { time, disabled?, label? }. A promise shows placeholder slots, a rejection shows noSlots with a retry. Answers are cached per function and day, so pass a stable function.
- `disabledTimes?: (slot: Date) => boolean`: Disables single slots by their absolute moment.
- `min?: Date`: Days and slots before are disabled (the day of min stays open for its later slots).
- `max?: Date`: Days and slots after are disabled. Ignored when it is before min.
- `disablePast?: boolean` = false: Shorthand for min = now: past days and today's past slots are disabled.
- `disabledDays?: DateMatcher or DateMatcher[] (DateMatcher: Date, Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean)`: Days the calendar disables: a date, a list, { from, to }, { before }, { after }, { dayOfWeek: [0, 6] } or a test.
- `presets?: boolean | DateTimePreset[]` = false: true: In 1 hour (rounded up to the step), Tomorrow 9:00 and Monday 9:00. Or your own { label, value, key? } list. A preset sets day and time and closes the panel.
- `timeZone?: string` = "": The IANA zone the wall times are picked in ("America/New_York"); the calendar and slots show its clock and DST gaps are disabled. Empty uses the device zone; an unknown zone falls back to it with a warning.
- `showTimeZone?: boolean` = true: The zone label in the footer.
- `timeZones?: string[]`: Makes the zone label a select to switch zones; the moment stays, the wall clock moves.
- `onTimeZoneChange?: (zone: string) => void`: Called when a zone is picked from the select.
- `hourCycle?: "auto" | "h12" | "h23"` = "auto": 12 or 24 hour slots and trigger text; auto follows the locale.
- `displayFormat?: Intl.DateTimeFormatOptions` = "{ weekday: \"short\", day: \"numeric\", month: \"short\", year: \"numeric\", hour: \"2-digit\", minute: \"2-digit\" }": How the trigger writes the value ("Thu, Sep 24, 2026, 4:40 PM"). While only a day is picked its date part is shown with --:--.
- `placeholder?: string` = "Pick date and time": The trigger text while empty.
- `clearable?: boolean` = false: A clear button in the field while it has a value (and Clear in the sheet).
- `inline?: boolean` = false: Renders the panel in the page without a trigger.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: The calendar's first weekday (0 Sunday to 6 Saturday); -1 uses the locale's.
- `calendarProps?: Partial<CalendarProps>`: Anything else for the calendar: size, radius, events, showWeekNumbers, labels.
- `now?: Date | number`: What now means for presets and disablePast. Default: the clock, ticking each minute (null until hydrated).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected day, slot and preset, and the Done button.
- `color?: string` = "": Any CSS color; replaces the tone.
- `icon?: ReactNode`: The trigger's leading icon. Default: CalendarClock.
- `size?: "sm" | "md" | "lg"` = "md": The field box: 32 / 40 / 48px (md grows to 44px on touch).
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box look.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The field box corners.
- `name?: string` = "": Submits value.toISOString() through a hidden input.
- `defaultOpen?: boolean` = false: Starts with the panel (or the sheet) open.
- `open?: boolean`: Whether the panel is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the panel opens or closes.
- `responsive?: boolean` = true: Below 768px the panel opens as a bottom sheet with chip rails and a draft committed by Done.
- `sheetTitle?: string` = "": The sheet title; empty uses the label's text, else labels.dialog.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the popover opens (it flips when there is no room).
- `align?: "start" | "center" | "end"` = "start": The popover's alignment to the field.
- `container?: HTMLElement | null`: Where the popover or sheet portals to.
- `locale?: string` = "": Month and weekday names, the first weekday, the hour cycle and the zone names. Empty uses the nearest LocaleProvider or UIProvider, else the page's language.
- `labels?: Partial<DateTimePickerLabels>`: The strings: time "Time", timeFor(day) "Time for {day}", noSlots "No free times on this day", pickDay, loading, retry "Try again", timeZone "Time zone", done "Done", clear "Clear", dialog "Choose date and time", presets "Quick picks", inOneHour "In 1 hour", tomorrowMorning "Tomorrow 9:00", nextMonday "Monday 9:00", selected(text), noTime "--:--". DEFAULT_DATE_TIME_PICKER_LABELS holds the defaults.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, hideLabel.
- `id?: string`: The trigger's id; generated when left out.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "trigger" | "icon" | "value" | "clear" | "chevron" | "content" | "presets" | "preset" | "body" | "calendar" | "times" | "slot" | "footer" | "zone" | "done", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the outermost element: the Field when there is a label or message, else the box.
- `ref?: Ref<HTMLButtonElement> (a useRef object or an (el) => void callback)`: The trigger button. Other button props (aria-*, data-*, tabIndex) land on it too.

Parts:
- `DateTimePickerPanel` (component): The panel alone (presets, calendar, times, footer) with the same options plus value / defaultValue / onValueChange, day / onDayChange (the day on show before a time is picked, "YYYY-MM-DD"), layout ("popover" | "sheet" | "inline"), onDone and onPresetPick. Props: DateTimePickerPanelProps.
- `DEFAULT_DATE_TIME_PICKER_LABELS` (constant): The English strings, to spread under a translation. Type: DateTimePickerLabels.
- `zonedTimeToDate` (function): A wall time in a zone to the absolute moment, DST safe: zonedTimeToDate("2026-09-24", "16:40", "America/New_York"). Repeated hours give the first occurrence. Signature: (dateISO: string, time: string, timeZone?: string) => Date.
- `getZonedParts` (function): The wall clock of a moment in a zone: { date: "2026-09-24", time: "16:40" }. Signature: (date: Date, timeZone?: string) => { date: string; time: string }.
- `formatTimeZoneLabel` (function): The zone's name and its offset at that date: "Romania Time (UTC+03:00)". Signature: (timeZone: string, date: Date, locale?: string) => string.
- `buildTimeSlots` (function): The "HH:mm" list every step minutes from start to end. Signature: ({ step?, start?, end? }) => string[].
- `isValidTimeZone` (function): Whether the runtime knows an IANA zone ("" counts as the device zone). Signature: (timeZone: string) => boolean.

```tsx
import { useState } from "react"
import { DateTimePicker, buildTimeSlots, type DateTimeSlot } from "@/components/ui/date-time-picker"

// Liam Walker's free slots: weekdays 09:00 to 17:00, 10:00 and 13:30 taken
function freeSlots(day: Date): DateTimeSlot[] {
  if (day.getDay() === 0 || day.getDay() === 6) return []
  return buildTimeSlots({ step: 30, start: "09:00", end: "17:00" }).map((time) => ({
    time,
    disabled: time === "10:00" || time === "13:30",
  }))
}

export function ScheduleDemo() {
  const [value, setValue] = useState<Date | null>(null)
  return (
    <DateTimePicker
      label="Date and time"
      placeholder="Pick a free slot"
      value={value}
      onValueChange={setValue}
      getTimeSlots={freeSlots}
      disablePast
      presets
      timeZone="America/New_York"
      locale="en-US"
      name="appointment"
      labels={{ noSlots: "No free slots that day", tomorrowMorning: "Tomorrow, 9 AM" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/date-time-picker (Markdown: https://wingo-ui.com/components/date-time-picker.md)

#### Duration Picker (`duration-picker`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add duration-picker`

A gooey, spring-animated picker for entering a duration in hours and minutes.

Click the pen to spring the segments apart and start editing; the hours field is focused for you and the pen morphs into a tick. Type your values. Anything past the ceiling (24 hr and 60 min by default) clamps to the max and shakes so you know it was corrected. Click the tick to confirm and watch the pill merge back into one piece.

npm: motion, figma-squircle, flubber, react-use-measure, @radix-ui/react-slot
Wingo UI dependencies: motion, ui-config

Props:
- `size?: "sm" | "md" | "lg"` = "md": Overall scale. The pill is 40px (sm, 44px on touch screens), 48px (md) or 56px (lg) tall, and the corner radius, the open field width, the icon and the text size scale with it.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Outer corner radius of the squircle: square, tighter, the original 10 / 12 / 14px per size, rounder, or a pill. The inner corners open up from it while editing.
- `surfaceColor?: string` = "auto": Fill of the three segments, any CSS color. Auto is a soft gray that follows the light and dark theme. A translucent tint keeps the digits readable in both themes.
- `labelColor?: string` = "auto": Color of the Hr. and Min. labels, any CSS color. Auto is a muted gray tuned per theme.
- `valueColor?: string` = "auto": Color of the typed digits, any CSS color. Auto is black on light pages and white on dark ones.
- `accentColor?: string` = "#868593": Color of the pen icon and the tick it morphs into, any CSS color.
- `gap?: number` = 8: Space in pixels the three segments spread apart to while editing.
- `maxHours?: number` = 24: Ceiling for the hours field. Typing past it clamps to this value and shakes the input.
- `maxMinutes?: number` = 60: Ceiling for the minutes field. Same clamp and shake behavior as maxHours.
- `defaultEditing?: boolean` = false: Renders the picker already open in edit mode, with the tick showing.
- `hoursLabel?: string` = "Hr.": Text rendered after the hours field. Swap it for a translation or a terser h.
- `minutesLabel?: string` = "Min.": Text rendered after the minutes field.
- `editLabel?: string` = "Edit duration": Accessible name of the pen button while the picker is closed.
- `saveLabel?: string` = "Save duration": Accessible name of the tick button while editing.
- `disabled?: boolean` = false: Dims the control to half opacity and blocks entering edit mode.
- `value?: { hours: number; minutes: number }`: Controlled value. Pair it with onChange and the picker mirrors whatever you pass in. Leave it out to let the component manage its own state.
- `defaultValue?: { hours: number; minutes: number }`: Starting value for uncontrolled usage. Ignored when value is provided. Left out, both fields start empty and show a 0 placeholder.
- `onChange?: (value: DurationValue) => void`: Fires on every keystroke with the current clamped value. Listen here to react while the user types.
- `onConfirm?: (value: DurationValue) => void`: Fires once with the final clamped value when the tick is clicked. This is usually the one you want for saving.
- `onEditingChange?: (editing: boolean) => void`: Fires when the picker enters or leaves edit mode, handy for blocking navigation or dimming surrounding UI while it is open.
- `className?: string`: Extra classes merged onto the root; other div props are spread onto it too. Every inner part carries a data-slot (duration-picker, duration-picker-segment, duration-picker-input, duration-picker-toggle) plus data-editing, data-disabled and data-size states, and the colors live in the --duration-picker-surface, --duration-picker-label and --duration-picker-value variables, so you can restyle from CSS alone.

```tsx
"use client"

import { useState } from "react"
import DurationPicker, { type DurationValue } from "@/components/ui/duration-picker"

export function Demo() {
  const [duration, setDuration] = useState<DurationValue>({ hours: 1, minutes: 30 })

  return (
    <DurationPicker
      size="md"
      value={duration}
      onChange={setDuration}
      onConfirm={(d) => console.log("saved", d)}
    />
  )
}

// zero config, fully uncontrolled
// <DurationPicker onConfirm={(d) => console.log("saved", d)} />
```

Docs: https://wingo-ui.com/components/duration-picker (Markdown: https://wingo-ui.com/components/duration-picker.md)

#### Email Input (`email-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add email-input`

An email field for one address or a list of recipients, with domain completion, typo hints, contacts and validation.

One address: type a name and after the @ a list completes the domain (emma@gm offers emma@gmail.com); Arrow Down and Up move through it, Enter or Tab takes the highlighted address, Escape closes it. Leaving the field checks the address: a malformed one shows the error, a likely typo shows "Did you mean emma@gmail.com?" with the fix as a button, and a valid one gets a green check. The error goes away as soon as the text is fixed. With multiple, every address becomes a chip with the person's initials or photo: type and press Enter, a comma, a semicolon or a space after a full address; pick a contact from the list by name or address; or paste a whole list like Emma Carter <emma@acme.com>, liam@acme.com; olivia@acme.com and every entry becomes a chip with its name, duplicates once (the existing chip pulses). A bad address stays as a red chip and the field says why; a likely typo turns its chip amber and the hint fixes it in one tap. Backspace in the empty text brings the last chip back as text to fix. Arrow Left at the start of the text moves onto the chips: Left and Right walk, Home and End jump, Delete or Backspace removes, Enter or F2 (or a double-click, or a second tap) edits, Cmd/Ctrl+C copies Name <address>, Escape returns to the text. Cmd/Ctrl+Enter adds the text and submits the form. On a phone the keyboard shows the email layout, text is 16px so iOS never zooms, the chip × buttons have a large touch area and the list stays in the page above the keyboard.

npm: motion, lucide-react
Wingo UI dependencies: avatar, badge, field, listbox, use-controllable-state, motion, text-match, tones, ui-config

Props:
- `multiple?: boolean` = false: A list of recipients as chips; value becomes string[]. Off, the field holds one address as a string.
- `label?: ReactNode` = "": Renders the field anatomy around the box: the label above it, linked to the text input.
- `description?: ReactNode` = "": Helper text under the box. A typo hint takes its place while it shows; at the limit labels.limit(max) does when you pass none.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid. Without it the field shows its own checks.
- `required?: boolean` = false: The red mark after the label and required / aria-required on the text input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, blocks typing and hides the × on chips.
- `readOnly?: boolean` = false: The value stays visible and selectable but cannot change; chips stay focusable and copyable.
- `placeholder?: string` = "name@example.com": Hint text while empty. Multiple mode defaults to Add people by name or email.
- `value?: string | string[]`: The address (single) or the addresses (multiple), controlled; pair it with onValueChange.
- `defaultValue?: string | string[]` = "\"\" / []": The starting value while uncontrolled; a form reset returns to it.
- `onValueChange?: (value: string | string[]) => void`: Fires with the new text on every keystroke (single), or with the new list after every add, remove, fix and clear (multiple).
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event of the text input, untouched.
- `contacts?: EmailContact[]` = "[]": People suggested while typing, matched by name, address or keywords (case and diacritics ignored). Chips of a known address show the name and photo.
- `domains?: string[]` = "EMAIL_DOMAINS": Completed after the @ and used for typo hints (gmail.com, outlook.com, yahoo.com, icloud.com...). [] turns both off.
- `allowedDomains?: string[]`: Only addresses at these domains are accepted (labels.domain names them); they also become the completions after the @.
- `validate?: (email: string) => (string | boolean)`: Extra rules after the format check: false marks the address invalid with the default message, a string with that message.
- `suggestTypos?: boolean` = true: Did you mean emma@gmail.com? under the field for a likely typo in the domain (gmial.com, gmail.con, gmail without .com).
- `showValidIcon?: boolean` = true: Single mode: a green check at the end once the address is valid and the field was left.
- `clearable?: boolean` = false: A clear button while there is a value: the text (Escape clears too) or every recipient.
- `max?: number` = 0: Multiple mode: the most recipients. At the limit the text hides and the description reads labels.limit(max). 0 means no limit.
- `invalidEntries?: "keep" | "reject"` = "keep": Multiple mode: keep a bad address as a red chip to fix later (like a mail app), or leave it in the text, shake and show why.
- `showAvatars?: boolean` = true: Multiple mode: the contact's photo or colored initials in each chip; the chips turn into pills.
- `leftIcon?: ReactNode` = "<Mail />": Single mode: the leading icon; null hides it.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px (md 44px on touch), 20 / 24 / 28px chips, 13 / 14 / 15px text (16px on phones). The multiple box grows as chips wrap.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box look shared with every input.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Box corners scaled with the size.
- `chipVariant?: "soft" | "outline" | "solid"` = "soft": Multiple mode: the Badge variant of the chips.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Multiple mode: the color of valid chips. Bad addresses are always danger, likely typos warning.
- `color?: string` = "": Any CSS color for valid chips; replaces the tone.
- `name?: string` = "": Single mode: the input's name. Multiple mode: one hidden input per address, so FormData.getAll(name) returns the list.
- `labels?: Partial<EmailInputLabels>`: Copy merged over the English defaults: invalid, invalidEntry(email), invalidCount(n), domain(domains), didYouMean(fix), useSuggestion(email), recipient(label, email), remove, added, removed, duplicate, limit(max), copied(email), clear, suggestions.
- `onReject?: (email: string, reason: "invalid" | "duplicate" | "limit" | "domain") => void`: Called for every address that was turned away or flagged.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The text input. Every other native prop lands there too: autoFocus, autoComplete, enterKeyHint, onBlur, onKeyDown (runs first), aria-*, data-*.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "icon" | "input" | "chip" | "valid" | "clear" | "hint" | "suggestions" | "list" | "option", string>>`: Extra classes for the parts: the field anatomy, the box, the icon, the text input, each chip, the valid check, the clear button, the typo hint and the suggestions panel.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description or error, else the email input root.

Parts:
- `isValidEmail` (function): The format check the field uses: one @, a sensible local part and a domain with a TLD of 2 or more letters, 254 characters at most.
- `normalizeEmail` (function): Trims, drops mailto: and angle brackets and lowercases the domain. The field runs it on every address it keeps.
- `suggestEmailFix` (function): The typo check behind the hint: emma@gmial.com gives emma@gmail.com, liam@acme.con gives liam@acme.com, and null when nothing looks wrong.
- `parseEmailList` (function): Splits a pasted list on commas, semicolons, tabs and new lines (quotes and <> respected) into { email, name? } entries: "Emma Carter <emma@acme.com>, liam@acme.com".
- `EMAIL_DOMAINS` (constant): The default domains completed after the @ and used for typo hints: gmail.com, outlook.com, yahoo.com, icloud.com, hotmail.com, proton.me and more.
- `EmailContact` (type): A suggested person: { email, name?, avatar?, keywords? }.
- `EmailEntry` (type): One parsed entry from parseEmailList: { email, name? }.
- `EmailInputLabels` (type): Every string the field shows or announces, for the labels prop.

```tsx
import { useState } from "react"
import { EmailInput, type EmailContact } from "@/components/ui/email-input"

const CONTACTS: EmailContact[] = [
  { name: "Emma Carter", email: "emma@acme.com" },
  { name: "Liam Brooks", email: "liam@acme.com" },
  { name: "Olivia Bennett", email: "olivia.bennett@gmail.com" },
]

export function NewMessage() {
  const [from, setFrom] = useState("")
  const [to, setTo] = useState<string[]>(["emma@acme.com"])

  return (
    <div className="flex flex-col gap-4">
      <EmailInput label="Your email" value={from} onValueChange={setFrom} name="from" required />
      <EmailInput multiple label="To" value={to} onValueChange={setTo} contacts={CONTACTS} name="to" clearable />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/email-input (Markdown: https://wingo-ui.com/components/email-input.md)

#### File Upload (`file-upload`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-upload`

Add files by dropping, browsing, pasting or taking a photo: validation, previews, per-file progress, and list, grid or avatar layouts.

Drag files from your desktop over the page and every dropzone lights up with "Drop to upload"; over the zone itself it tints, grows a touch and its icon lifts. Click the dropzone (or focus it and press Enter or Space) to open the file picker, or paste a copied file or screenshot with Ctrl+V / Cmd+V while focus is inside. Each file is checked against the accepted types, the size limit and the file limit: rejected files are listed under the dropzone with the reason and never silently dropped. Accepted images show a preview right away. With an upload function each row fills a progress bar (a ring on photos and the avatar), at most three at a time by default, and pops a green check when it finishes; X cancels a running upload, the circular arrow retries a failed or canceled one, the trash can removes a file and aborts its upload. In the photo grid the first photo is the cover: drag a tile to reorder, or focus it and press Space, move it with the arrow keys and press Space again (Escape cancels); screen readers hear every move. On a phone the dropzone reads "Tap to choose files", remove buttons on photos are always visible, a 250ms press starts reordering so the page still scrolls, every action has a 44px target, and with camera on a "Take photo" button opens the camera.

npm: @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, motion, lucide-react
Wingo UI dependencies: field, button, badge, number-format, use-locale, motion, tones, use-media-query, use-controllable-state, ui-config

Props:
- `variant?: "list" | "grid" | "avatar" | "compact"` = "list": list: a dropzone above a list of rows (documents). grid: photo tiles you can reorder, the first is the cover (listing photos). avatar: one round photo with a camera badge. compact: an attach button and small rows (chat, comments).
- `accept?: string` = "": Accepted types, like the native attribute: "image/*,.pdf". Extensions match case-insensitively, wildcards match the MIME type. Also feeds the picker and the automatic hint. The exported acceptsFile(file, accept) runs the same check.
- `maxSize?: number` = "10485760": Largest file in bytes (10 MB); 0 means no limit. Bigger files are rejected with labels.tooLarge.
- `maxFiles?: number` = 0: How many files the list may hold; 0 means no limit. Extra files are rejected, not dropped. At the limit the dropzone turns off and shows "8 / 8". The avatar always holds one.
- `multiple?: boolean` = true: Pick several files at once. Off, a new file replaces the current one.
- `upload?: (file: File, context: { signal: AbortSignal; onProgress: (fraction: number) => void }) => Promise<unknown>`: Uploads one file. Pass signal to fetch so cancel, remove and unmount abort it, call onProgress with 0..1 (throttled to one update per 100ms per file). What it resolves with lands in the file's response; a rejection keeps the file with its error and a retry button. Without it files stay idle, for forms that submit them natively.
- `autoUpload?: boolean` = true: Start uploads as files are added. Off, each row gets an upload button and the list an "Upload all" button.
- `maxConcurrent?: number` = 3: Uploads that run at once; the rest wait their turn.
- `sortable?: boolean` = true: Grid only: drag tiles to reorder (the first is the cover). A 250ms press on touch, Space and the arrow keys on a keyboard.
- `camera?: boolean` = false: On touch screens, adds a "Take photo" button that opens the back camera (capture="environment", images).
- `paste?: boolean` = true: Paste files and screenshots from the clipboard while focus is inside the component.
- `validate?: (file: File) => (string | null | undefined)`: Extra checks after type and size: return a message to reject the file with it (a duplicate, a too-small photo). formatFileSize(bytes, locale) is exported for messages.
- `onReject?: (rejections: { file: File; reason: "type" | "size" | "count" | "custom"; message: string }[]) => void`: Called with every rejected file of one add, together.
- `size?: "sm" | "md" | "lg"` = "md": Dropzone padding and icon (list), the attach button (compact) and the avatar: 64 / 96 / 128px.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the dropzone and photo tiles: 0 / 12 / 16 / 24px (full stays 24px). The avatar is always round.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the drag-over tint, the progress bars and rings and the avatar badge.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `icon?: ReactNode`: The dropzone icon, CloudUpload by default.
- `labels?: Partial<FileUploadLabels>`: Every string, English by default: title ("Drag files here or"), browse, tapTitle, dropHere, hint (else built from accept, maxSize and maxFiles), camera, add, attach, change, choose, cover, remove, retry, cancel, start, uploadAll, uploading, queued, uploaded, canceled, failed, limitReached, images / videos / audio, wrongType, tooLarge(max), tooMany(max), maxSizeHint(max, single), maxFilesHint(max), the announcements announceUploaded / announceFailed / announceRejected / announceRemoved and the reordering texts dragInstructions, dragStart, dragOver, dragEnd, dragCancel.
- `locale?: string` = "": Formats file sizes ("2,4 MB" in ro-RO, "2.4 MB" in en-US). Empty uses the nearest LocaleProvider, then the page language.
- `label?: ReactNode` = "": Renders the field anatomy around the component. A click on it focuses the dropzone without opening the picker.
- `description?: ReactNode` = "": Helper text. In the list layout it becomes the dropzone's second line (unless labels.hint is set); elsewhere it shows under the component.
- `error?: ReactNode` = "": The animated error under the component; also marks the dropzone invalid.
- `required?: boolean` = false: The red * after the label; with name, the native form refuses to submit an empty list.
- `invalid?: boolean` = false: The invalid look without a message.
- `disabled?: boolean` = false: Dims everything and blocks picking, dropping, pasting and the row actions.
- `name?: string` = "": Names the hidden file input. Its files follow the list (through DataTransfer), so a native form or FormData submits exactly the files shown.
- `value?: UploadFile[]`: The files, controlled: { id, name, size, type, file?, url?, previewUrl?, status: "idle" | "uploading" | "done" | "error" | "canceled", progress, error?, response? }. Files that already exist on a server have url and status "done". Dropping a file mid-upload aborts it.
- `defaultValue?: UploadFile[]` = "[]": The starting files when uncontrolled; a form reset returns to them.
- `onValueChange?: (files: UploadFile[]) => void`: The whole list after every add, remove, reorder, status change and throttled progress update.
- `id?: string`: The main trigger's id (dropzone, add tile, avatar or attach button), which the label points to.
- `fieldProps?: Partial<FieldProps>`: Anything else for the field wrapper: optional, labelAction, orientation, hideLabel.
- `classNames?: Partial<Record<"dropzone" | "icon" | "title" | "hint" | "camera" | "rejections" | "list" | "item" | "thumb" | "name" | "meta" | "progress" | "action" | "grid" | "tile" | "cover" | "remove" | "add" | "avatar" | "input" | "field" | "label" | "description" | "error" | "counter", string>>`: Extra classes for the inner parts and the field parts.
- `className?: string`: Extra classes for the root (the field root when a label, description or error is set).

```tsx
import { FileUpload, type UploadFile } from "@/components/ui/file-upload"

// your endpoint; signal aborts, onProgress fills the bar
function uploadFile(file: File, { signal, onProgress }: { signal: AbortSignal; onProgress: (fraction: number) => void }) {
  return new Promise<{ url: string }>((resolve, reject) => {
    const request = new XMLHttpRequest()
    request.open("POST", "/api/upload")
    request.upload.onprogress = (event) => onProgress(event.loaded / event.total)
    request.onload = () => (request.status < 300 ? resolve(JSON.parse(request.responseText)) : reject(new Error("Upload failed")))
    request.onerror = () => reject(new Error("No connection"))
    signal.addEventListener("abort", () => request.abort())
    const body = new FormData()
    body.append("file", file)
    request.send(body)
  })
}

const existing: UploadFile[] = [
  { id: "contract", name: "purchase-agreement.pdf", size: 1887437, type: "application/pdf", url: "/files/purchase-agreement.pdf", status: "done", progress: 1 },
]

export function PropertyDocuments() {
  return (
    <FileUpload
      label="Property documents"
      description="PDFs or images, up to 10 MB each"
      accept="image/*,.pdf"
      defaultValue={existing}
      upload={uploadFile}
      locale="en-US"
      labels={{ title: "Drop your documents here or", browse: "browse" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/file-upload (Markdown: https://wingo-ui.com/components/file-upload.md)

#### Filter Builder (`filter-builder`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add filter-builder`

Advanced filters for any list: condition chips, AND / OR, nested groups, saved views and a live count, with one bottom sheet on phones.

Press + Filter (or the shortcut, shift+F in the demo) for a searchable, grouped list of fields: type to narrow it, Up and Down to move, Enter to pick. The new chip appears with its editor open, the operator already chosen and focus in the value: text applies as you type (after a short pause) and on Enter, numbers and amounts through their fields, dates on an inline calendar with quick ranges, choices in a list with search, checkboxes and Select all. Close an editor (Escape, a click outside) while its condition is incomplete, or after emptying it, and the chip goes away, so no chip ever filters nothing. Click a chip to edit it; its × removes it. The chips row is a toolbar with one Tab stop: Left and Right move between chips, the and / or toggle, + Filter and Clear, Home and End jump to the ends, Enter or Space opens a chip, Delete or Backspace removes it and focus moves to the next chip. The and / or between the first two chips switches the whole filter. A nested group shows as one chip with its sentence and opens the panel, where every condition is a row (field, operator, value, remove): Add condition and Add group put focus in the new row, Enter in a text or number value applies at once (or applies the draft and closes with applyMode apply), and removing a row from the keyboard moves focus to the next one. The views menu lists saved views (pinned first) and All records, Up and Down move through them; changing a view's filter marks it modified and offers Save changes or Save as new view, with Rename and Delete in each view's ⋯ menu, and a save the app rejects keeps the name and says so. The result count updates in a polite live region. With applyMode apply, editors keep a draft until Apply. On a phone a Filters button with the count opens one bottom sheet: the conditions as rows with a ⋯ for Edit and Remove, and / or as a segmented control, + Add filter drills into the field list and then the editor with a short slide (long lists scroll under their search), the back arrow returns, focus lands on each page's title, and nothing changes until Show 24 results; closing the sheet discards the draft. The chips under it scroll sideways and their × removes at once.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, calendar, currency-input, date-picker, date-range-picker, drawer, dropdown-menu, input, listbox, number-input, popover, segmented-control, select, spinner, tooltip, filters, date-utils, number-format, use-controllable-state, use-locale, use-media-query, use-scroll-edges, use-shortcut, motion, tones, ui-config

Props:
- `fields: FilterBuilderField<T>[]`: The filterable fields: { id, label, type: text | number | currency | date | select | multi-select | boolean, accessor?, options?, operators?, currency?, placeholder?, group?, icon? }. Options carry avatars or color dots for people and statuses.
- `variant?: "chips" | "panel"` = "chips": chips: inline chips, each with its own editor popover. panel: one Filters button with a count that opens a rows editor (Airtable / Notion style).
- `size?: "sm" | "md"` = "md": Chips and bar buttons 28 / 32px with a 44px hit area on touch screens; the chip editors' fields follow (the panel keeps compact sm rows, the phone sheet full-size ones).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": The chips' and bar buttons' corners, from the button's radius map; full makes pills.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of active chips, the count badge, the calendar selection and the Apply buttons. Neutral chips use the foreground tint, other tones their soft fill.
- `maxChips?: number` = 0: Desktop: chips past this number collapse into a +3 chip that opens the panel. Phones always scroll through all of them.
- `responsive?: boolean` = true: Below 768px a Filters button opens one bottom sheet with a draft and a Show 24 results button; off, phones get the desktop chips and popovers.
- `defaultOpen?: boolean` = false: Starts with the panel (desktop) or the sheet (phones) open.
- `disabled?: boolean` = false: Dims the builder; nothing opens and chips cannot be removed.
- `loading?: boolean` = false: A request is running (server-side filtering): the count shows a spinner and dims until it settles.
- `applyMode?: "instant" | "apply"` = "instant": instant: every complete change calls onValueChange (text after a 300ms pause). apply: chip editors and the panel keep a draft with Cancel / Apply. The phone sheet always drafts.
- `allowOr?: boolean` = true: The root can switch between and / or (the toggle between the first two chips); off keeps every filter AND.
- `allowGroups?: boolean` = true: Add group in the panel and the sheet: one level of nesting, like (Balance ≥ $5,000 or Last invoice in the last 7 days).
- `shortcut?: string` = "": A key combo in mod+k notation that opens the field list (chips), the panel, or the sheet on phones. None by default; the demo uses "shift+f". Shown in the + Filter tooltip.
- `locale?: string` = "": Formats money, numbers and dates in the chips and editors; the UIProvider's or the browser's when empty. The demo uses en-US.
- `value?: FilterGroup`: The filter, controlled: { id, combinator: and | or, conditions: (FilterCondition | FilterGroup)[] }. Pair it with onValueChange.
- `defaultValue?: FilterGroup`: The starting filter while uncontrolled; an empty AND group when left out.
- `onValueChange?: (filter: FilterGroup) => void`: Every applied change. Filter rows with applyFilter from lib/filters, or send serializeFilter(filter) to the server.
- `views?: FilterView[]`: Saved views in the views menu, pinned first. Built-in views are readOnly (no Rename or Delete).
- `activeViewId?: string | null`: The active view, controlled; picking a view replaces the filter, editing it afterwards shows (modified).
- `defaultActiveViewId?: string | null` = "": The starting view while uncontrolled; none (All records) when left out. Pair it with a value that holds the view's filter, or the trigger shows (modified). The playground offers the demo's views: overdue, mine, chicago-austin.
- `onActiveViewChange?: (id: string | null) => void`: A view was picked, saved, or All records chosen (null).
- `onSaveView?: (input: { name: string; filter: FilterGroup; id?: string }) => (FilterView | Promise<FilterView>)`: Enables saving: a name field in the views menu and in the panel. id is set for Save changes on the active view. The returned view becomes active; a rejected promise keeps the name field and announces labels.saveError.
- `onRenameView?: (id: string, name: string) => (void | Promise<unknown>)`: Adds Rename to each saved view's ⋯ menu: the name turns into a field, saved on Enter; a rejection keeps it open with labels.saveError.
- `onDeleteView?: (id: string) => (void | Promise<unknown>)`: Adds Delete to each saved view's ⋯ menu. Deleting the active view keeps its filter on screen; a rejection announces labels.deleteError.
- `resultCount?: number` = 0: How many rows the filter shows: next to the chips (labels.count) in a polite live region, and in the sheet's apply button while the draft equals the filter. The code has no default: leave it out to hide the count, and 0 is a real count ("0 results"). In the playground 0 means the table's own count; drag it for a server-sized total (1 client, 24 clients).
- `previewCount?: (filter: FilterGroup) => (number | undefined)`: The rows a draft would show, so the sheet's button reads Show 3 results before anything is applied (client-side lists pass applyFilter(...).length).
- `open?: boolean`: The panel (desktop) or the sheet (phones), controlled.
- `onOpenChange?: (open: boolean) => void`: The panel or the sheet opened or closed.
- `now?: Date | number`: Today for the quick date ranges (Last 7 days) and the calendars' first month. The demo pins 24.09.2026.
- `labels?: Partial<FilterBuilderLabels>`: Every visible string, English by default (DEFAULT_FILTER_BUILDER_LABELS): add, addFilter, addCondition, addGroup, where, and, or, clear, apply, cancel, results(n, f), count(n, f), searchFields, noFields, value, from, to, days, views, allRecords, saveView, saveChanges, saveAsNew, viewName, modified, deleteView, renameView, save, saveError, deleteError, remove(text), removeGroup, removeCondition, title, group, more(n, f), switchCombinator, field, operator, back, edit, actions, search, selectAll, noResults, empty, rangePresets, operators (per operator) and describe (the lib/filters sentence labels).
- `classNames?: Partial<Record<"trigger" | "views" | "chips" | "chip" | "combinator" | "more" | "add" | "clear" | "count" | "popover" | "fieldList" | "panel" | "row" | "group" | "sheet", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last. Other props (id, aria-*, data-*, handlers) spread onto it.

Parts:
- `FilterChip` (component): One condition as a chip with its editor, for toolbars that place chips themselves: condition, fields, onConditionChange, onRemove, onEdit, open / defaultOpen / onOpenChange, isNew, applyMode, responsive (true: below 768px the editor is a bottom sheet that keeps a draft until Apply), size, radius, tone, disabled, locale, now, labels, prefix, buttonProps, classNames. Props: FilterChipProps<T>.
- `FilterConditionEditor` (component): The field / operator / value editor of one condition: layout stacked (popover, sheet) or inline (a panel row), density menu or sheet, onConditionChange, onSubmit (Enter). Props: FilterConditionEditorProps<T>.
- `DEFAULT_FILTER_BUILDER_LABELS` (constant): The English labels; spread them to translate a few. Type: FilterBuilderLabels.
- `FilterBuilderField` (type): A field of the builder. The lib/filters types it uses (FilterGroup, FilterCondition, FilterView, FilterOperator…) are re-exported. Shape: FilterField<T> & { icon?: ReactNode }.

```tsx
import { useMemo, useState } from "react"
import { FilterBuilder, type FilterBuilderField, type FilterGroup, type FilterView } from "@/components/ui/filter-builder"
import { applyFilter, createFilterCondition, createFilterGroup } from "@/lib/filters"

type Client = { name: string; city: string; balance: number }

const FIELDS: FilterBuilderField<Client>[] = [
  { id: "name", label: "Client", type: "text" },
  { id: "city", label: "City", type: "select", options: [{ value: "Chicago", label: "Chicago" }, { value: "Austin", label: "Austin" }] },
  { id: "balance", label: "Balance", type: "currency", currency: "USD" },
]

const VIEWS: FilterView[] = [
  { id: "chicago-austin", name: "Chicago and Austin", filter: createFilterGroup("and", [createFilterCondition(FIELDS[1], { value: ["Chicago", "Austin"] })]) },
]

export function ClientFilters({ clients }: { clients: Client[] }) {
  const [filter, setFilter] = useState<FilterGroup>(() => createFilterGroup("and"))
  const rows = useMemo(() => applyFilter(clients, filter, FIELDS), [clients, filter])
  return (
    <FilterBuilder
      fields={FIELDS}
      value={filter}
      onValueChange={setFilter}
      views={VIEWS}
      resultCount={rows.length}
      locale="en-US"
      shortcut="shift+f"
      labels={{ allRecords: "All clients" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/filter-builder (Markdown: https://wingo-ui.com/components/filter-builder.md)

#### Input (`input`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add input`

The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels.

Click anywhere in the box, on an icon, on the padding or on a suffix like USD, and the caret lands in the text without jumping; the whole box takes a soft ring. Type and a clear button pops in at the end: tap it or press Escape and the text is gone while focus stays in the field. While loading a small spinner spins where the trailing icon was, and the field stays editable. With a floating label the label rests inside the box like a placeholder and glides up to the top edge on focus, when filled or when the browser autofills. With a counter the numbers turn amber at 90% and red at the limit. Enter submits the form like a native field. On a phone the text is 16px so iOS never zooms, the keypad follows the type (email, url, tel, decimal for amounts), the md box grows to 44px and the clear button has a 44px hit area.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, field, spinner, motion, use-controllable-state

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the box: the label above it, linked with htmlFor. With floatingLabel it moves inside the box. Leave it empty for a bare input (then pass aria-label).
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with an alert icon and the text, slides in and marks the field invalid (red ring, aria-invalid). Empty means no error.
- `required?: boolean` = false: The red mark after the label (hidden from screen readers) and the native required attribute.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message, for forms that show the error somewhere else.
- `disabled?: boolean` = false: Dims the field to 50% and blocks input; the native input is disabled, so the form does not submit it.
- `readOnly?: boolean` = false: The value stays visible, selectable and submitted, but cannot change; the box drops its hover tint and the clear button. The demo fills in a sample value.
- `placeholder?: string` = "": Hint text while the field is empty. With a floating label it only shows while the label is floated (on focus, or always next to a prefix), never behind it.
- `defaultValue?: string` = "": The starting text while uncontrolled. Pass value and onValueChange instead to control it; a value set by a form library straight on the element shows up in the counter after the next focus.
- `prefix?: ReactNode` = "": Text before the input, like "https://" or "+40", in the muted addon look (long text truncates at 40% of the box), or an element rendered as is. A click on it lands in the input.
- `suffix?: ReactNode` = "": Text after the input, like "USD" or "@company.com", or an element such as a small Apply button. Buttons inside keep the input focused while pressed.
- `clearLabel?: string` = "Clear": The clear button's accessible name and hover title. The demo passes Clear text (the City field always shows one).
- `loadingLabel?: string` = "Loading": What screen readers hear for the spinner while loading. The demo passes Checking.
- `name?: string` = "": The form field name. It lands on the native input, so FormData, autofill and {...register('titlu')} from react-hook-form work as on a plain input.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px with 13 / 14 / 15px text (16px on phones so iOS never zooms); md grows to 44px on touch. Floating labels make the box 44 / 52 / 60px.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": soft is a filled well that works on every surface, outline a bordered box, underline a bottom line that grows a bar from the center on focus, ghost has no fill until hover (toolbars, table cells).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size like the button's (md is 8 / 10 / 12px); full makes a pill. Ignored by underline.
- `accent?: string` = "": Any CSS color for the focus ring, the outline border and underline bar on focus, and the caret. Empty uses the ring token (the brand orange).
- `floatingLabel?: boolean` = false: The label sits inside the box like a placeholder and floats up, at 80%, on focus, when filled or when autofilled (CSS only, so it is right before hydration). The box grows to 44 / 52 / 60px for the room. Needs label; a prefix keeps it floated.
- `loading?: boolean` = false: A small spinner at the end, in place of the right icon when there is one, and aria-busy. The input stays editable, e.g. while checking if a username is free.
- `type?: InputType: "text" | "email" | "url" | "tel" | "search" | "password" | "number"` = "text": The native type, which also picks the phone keypad (email, url, tel, search). number renders a text field with a decimal keypad, so maxLength works and a scroll never changes it; number-input adds steppers and locale parsing, password-input the reveal button.
- `clearable?: boolean` = false: A clear button pops in while there is a value (never when disabled or read-only). It stays out of the Tab order; Escape clears from the keyboard. Focus stays in the input.
- `showCount?: boolean` = false: The "12 / 70" counter at the end of the message row, amber from 90% and red at the limit. Needs maxLength.
- `maxLength?: number` = 0: The native character limit, also the counter's maximum. 0 means no limit.
- `selectOnFocus?: boolean` = false: Selects the whole text when the field takes focus, by click, tap or Tab, so typing replaces it. For codes and amounts.
- `value?: string`: The text, controlled. Without onValueChange typing does nothing (like React); use readOnly for a fixed value.
- `onValueChange?: (value: string) => void`: Fires with the new text on every edit, including a clear.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event, untouched. A clear fires it too, like a keystroke.
- `onClear?: () => void`: Called after the clear button or Escape emptied the field. Focus is already back in the input.
- `leftIcon?: ReactNode`: A leading icon in the muted color; unsized svgs follow the size (14 / 16 / 18px). A click on it lands in the input.
- `rightIcon?: ReactNode`: A trailing icon, e.g. a green check after a successful check. It pops in and out, and crossfades with the spinner while loading.
- `clearIcon?: ReactNode`: Replaces the clear button's icon (a 16px X by default).
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional and optionalLabel, labelAction, orientation, labelWidth, hideLabel, counterLabel, requiredIndicator.
- `id?: string`: The native input's id. Defaults to useId(); inside a <Field> the Field's id wins.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native input. Every other native prop lands there too: inputMode (defaults from the type), enterKeyHint, autoComplete, pattern, spellCheck, autoCapitalize, onBlur, onKeyDown, aria-* and data-*.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "input" | "prefix" | "suffix" | "leftIcon" | "rightIcon" | "clear" | "spinner" | "floatingLabel", string>>`: Extra classes for the inner parts. box targets the field box, input the native element.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description, error or counter, else the box.

```tsx
import { useRef, useState } from "react"
import { CircleCheck, MapPin } from "lucide-react"
import { Input } from "@/components/ui/input"

export function ListingDetails() {
  const [title, setTitle] = useState("")
  const [user, setUser] = useState("emma.carter")
  const [checking, setChecking] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)

  return (
    <form className="flex flex-col gap-4">
      <Input
        name="title"
        label="Listing title"
        placeholder="e.g. Trek FX 2 city bike"
        value={title}
        onValueChange={setTitle}
        error={title && title.length < 10 ? "The title needs at least 10 characters." : undefined}
        showCount
        maxLength={70}
        required
        enterKeyHint="next"
      />
      <Input name="price" label="Price" prefix="$" inputMode="decimal" selectOnFocus defaultValue="1,250" />
      <Input name="city" label="City" leftIcon={<MapPin />} clearable autoComplete="address-level2" />
      <Input
        label="Username"
        value={user}
        onValueChange={(next) => {
          setUser(next)
          // the check runs 1.4s after the last keystroke
          setChecking(true)
          clearTimeout(timer.current)
          timer.current = setTimeout(() => setChecking(false), 1400)
        }}
        loading={checking}
        rightIcon={<CircleCheck className="text-success-soft-foreground" />}
        autoCapitalize="none"
        enterKeyHint="done"
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/input (Markdown: https://wingo-ui.com/components/input.md)

#### Input Group (`input-group`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add input-group`

Joins a field with text addons, selects, icons and buttons into one box with one focus ring and one error state.

Several controls read as one field: the whole row takes a single soft ring when any part has focus, a single red ring when it is invalid, and dims as one when disabled. Tab walks through the controls in order. A click or tap on a text addon like https:// or kg lands the caret in the input next to it; a click on the label focuses the first control. Selects inside open their list as usual, as a bottom sheet below 768px. A solid button at the end (Apply) sits flush with the rounded corner and shows its spinner while loading without changing width. On a phone the row stays on one line down to 320px: addons never wrap, the input shrinks, text is 16px so iOS never zooms and the md row grows to 44px.

npm: @radix-ui/react-slot
Wingo UI dependencies: field, button, ui-config

Props:
- `label?: ReactNode` = "": Names the whole row (the group is aria-labelledby it); a click on it focuses the first control. The controls inside stay bare and take an aria-label each (Domeniu, Extensie).
- `description?: ReactNode` = "": Helper text under the row. It describes the group and every control inside (aria-describedby), together with the text addons.
- `error?: ReactNode` = "": Replaces the description with the animated error and turns the whole row red; every control inside gets aria-invalid.
- `required?: boolean` = false: The red mark after the label; the controls inside get required.
- `invalid?: boolean` = false: The red ring and aria-invalid on every control without a message.
- `disabled?: boolean` = false: Dims the row once to 50% and disables every control and button inside.
- `readOnly?: boolean` = false: Values stay visible and selectable but cannot change; selects do not open and the row drops its hover tint. The demo fills in a sample value.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px (md 44px on touch). Pass it to the group only: the controls, addons and buttons inside follow it.
- `variant?: "soft" | "outline"` = "soft": soft is the filled well, outline a bordered box. Ghost and underline make no sense for a joined row.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the row, scaled with the size like the button's (md is 8 / 10 / 12px); full makes a pill. Inner parts are clipped to it.
- `separators?: boolean` = true: Hairlines between segments (controls, filled addons, ghost buttons). Plain addons are text inside a segment and a solid button is its own edge, so they never get one.
- `children?: ReactNode`: InputGroupAddon, bare W2 controls (Input, Select, NumberInput, CurrencyInput... with no label of their own, an aria-label each) and InputGroupButton, in order. The row never wraps (the input shrinks instead); on a phone keep it to one or two controls plus addons, and split longer rows into separate groups.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "box" | "separator", string>>`: Extra classes for the parts: field is the wrapper with the label, box the joined row.
- `className?: string`: Classes for the outermost element: the wrapper when there is a label, description or error, else the row.

Parts:
- `InputGroupAddon` (component): Text or an icon at either end. position is inferred from the order when omitted. variant "plain" (default) is muted text that hugs the input, "filled" a tinted segment like a classic addon. A click or tap focuses the nearest input (links and buttons inside keep their own click). asChild renders a <label htmlFor>. Text addons (USD, kg) join the controls' aria-describedby; describe={false} opts out. Props: ComponentProps<"span"> & { position?: "start" | "end"; variant?: "plain" | "filled"; asChild?: boolean; describe?: boolean }.
- `InputGroupButton` (component): A Button flush with the row: variant "ghost" and radius "none" by default, full height, the group's size (an explicit sm / md / lg sets its own text size), inset focus outline, disabled with the group. size="icon" makes it square; loading keeps its width. Props: ButtonProps.
- `InputGroupSeparator` (component): A 1px hairline placed by hand, for example with separators={false}. Decorative (aria-hidden). Takes span props.

```tsx
import { useState } from "react"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon, InputGroupButton } from "@/components/ui/input-group"
import { Select } from "@/components/ui/select"

const DOMAINS = [
  { value: ".com", label: ".com" },
  { value: ".io", label: ".io" },
  { value: ".dev", label: ".dev" },
]

export function SiteAddress() {
  const [domain, setDomain] = useState(".com")
  const [pending, setPending] = useState(false)

  return (
    <div className="flex flex-col gap-4">
      <InputGroup label="Website address" description="The name without spaces.">
        <InputGroupAddon>https://</InputGroupAddon>
        <Input aria-label="Domain" placeholder="northwind" name="domain" />
        <Select aria-label="Extension" options={DOMAINS} value={domain} onValueChange={(next) => next && setDomain(next)} />
      </InputGroup>

      <InputGroup label="Discount code" error="This coupon has expired">
        <Input aria-label="Coupon code" placeholder="Coupon code" />
        <InputGroupButton
          variant="solid"
          loading={pending}
          onClick={() => {
            setPending(true)
            setTimeout(() => setPending(false), 1200)
          }}
        >
          Apply
        </InputGroupButton>
      </InputGroup>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/input-group (Markdown: https://wingo-ui.com/components/input-group.md)

#### Listbox (`listbox`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add listbox`

A searchable list of options for single or multiple choice, with groups, async loading, create-new and virtualized rows.

Click a row to pick it: in single mode a check draws itself at the end of the row, in multiple mode the leading checkbox ticks and a second click unticks it. Moving the mouse over the list highlights the row under the pointer; the highlight only shows while the list or its search has focus or the pointer is over it, so a resting list stays calm. With search on, typing filters as you go (case and accents never matter, so espanola finds Española, and state codes like OR work as keywords), matched letters turn bold, groups without matches disappear and the clear button empties the query. Keyboard: Tab reaches the list (or its search field); ArrowDown and ArrowUp move the highlight and wrap around, PageUp and PageDown jump a screen, Home and End go to the first and last row when the list itself has focus, Enter picks the highlighted row, Space toggles it in multiple mode, Ctrl+A (Cmd+A on a Mac) selects every visible option in multiple mode, and typing letters on the list jumps to the option that starts with them (the same letter again cycles). Select all toggles every visible enabled option; with a maximum, the other rows dim once you reach it. With creatable, a query that matches nothing adds a Create row that turns into the new option (with a spinner while an async create runs). Async lists keep their previous results while a new search loads, show a spinner in the search row, and offer Try again after an error. Lists above the virtual threshold only render the rows in view, so thousands of options scroll at 60fps. On a phone rows grow to 44px (48px in sheet density with a pressed state), scrolling with a finger never picks a row, the search field uses 16px text so iOS never zooms, and with reduced motion the check appears without drawing.

npm: @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: field, checkbox, spinner, button, text-match, use-debounce, use-media-query, motion, tones, use-controllable-state, ui-config

Props:
- `options: ListboxItems`: Options and groups: { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? } or { label?, items: ListboxOption[] }. Loose options between groups form their own unlabeled section. Values must be unique (a dev warning names duplicates; the first wins); a non-string label needs textValue for search and typeahead.
- `value?: string | string[]`: The selected value while controlled: a string ("" = none), or string[] with multiple. A value that is not among the options is kept and labeled from every option seen before.
- `defaultValue?: string | string[]`: The starting value while uncontrolled; "" or [] by default. A form reset returns to it.
- `onValueChange?: (value: string | string[]) => void`: Called with the next value: a string in single mode, the string[] (in pick order) with multiple.
- `multiple?: boolean` = false: Many values: rows get a leading checkbox and toggle; aria-multiselectable is set. Single mode keeps the picked value when you click it again.
- `search?: boolean` = false: The search row on top. Focus then lives in the search field (role="combobox") and drives the list with aria-activedescendant; without it the list itself is focusable.
- `searchPlaceholder?: string` = "Search…": Placeholder of the search field.
- `emptyText?: string` = "No results": Shown when nothing matches the query (or the list is empty).
- `loadingText?: string` = "Loading…": Shown with a spinner on the first load, while there are no rows yet. Later loads keep the rows and spin in the search row instead.
- `errorText?: string` = "Could not load results": Shown with a Try again button when loadOptions rejects; the last results stay. In the playground a custom text previews the error state.
- `loading?: boolean` = false: External loading, for options you fetch yourself: with no options it shows loadingText, with options the search row spins. The playground clears the options while it is on.
- `loadOptions?: (query: string, context: { signal: AbortSignal }) => Promise<ListboxItems>`: Async options for the debounced query. The previous request is aborted, the last 20 queries are cached so going back is instant, the previous results stay visible while loading, and an error keeps them and shows errorText with Try again. Results are not filtered again.
- `debounce?: number` = 250: ms to wait after typing before loadOptions runs. The first load runs at once.
- `minQueryLength?: number` = 0: loadOptions waits for this many characters; below it the static options show.
- `filter?: boolean | ((option: ListboxOption, query: string) => number | null)` = true: true: text-match on the text and keywords (every word must match, best first inside each group). false: the options are already filtered (server search). A function returns a score, higher first, or null to hide.
- `fuzzy?: boolean` = false: Letters may be spread out (orgn finds Oregon). Off by default so results stay predictable.
- `query?: string`: The search text while controlled. Pair it with onQueryChange; defaultQuery starts an uncontrolled one.
- `defaultQuery?: string` = "": The starting search text while uncontrolled. The list opens filtered (with a search row the text shows in it).
- `onQueryChange?: (query: string) => void`: Called as the search text changes.
- `creatable?: boolean` = false: When the trimmed query matches no option exactly (diacritics folded), a Create row appears last (first and highlighted when nothing else matches). Without onCreate the query itself is selected as a new value. In the playground new counties are added to the list.
- `onCreate?: (query: string) => (string | void | Promise<string | void>)`: Called from the Create row. A returned string (or a promise of one) is selected; a promise shows a spinner on the row until it settles.
- `createLabel?: (query: string) => ReactNode` = "q => `Create \"${q}\"`": The Create row's text.
- `maxSelected?: number` = 0: Multiple only: at the maximum the other rows turn aria-disabled and dim; lowering it keeps the current selection and blocks additions. 0 = no limit.
- `selectAll?: boolean` = false: Multiple only: a Select all row on top that shows a dash while some are picked. It toggles every visible enabled option, up to maxSelected (at the maximum it clears them). The playground turns multiple on with it.
- `selectAllLabel?: string` = "Select all": The Select all row's text.
- `highlightMatches?: boolean` = true: Matched letters of the label turn semibold while you search.
- `indicator?: "auto" | "check" | "checkbox" | "none"` = "auto": auto: a trailing check in single mode, a leading checkbox with multiple. none tints selected rows in the tone instead.
- `density?: "menu" | "sheet"` = "menu": menu: 36px rows (44px on touch screens). sheet: 48px rows with 15px text and a pressed state instead of a hover highlight, as pickers use in bottom sheets. Long labels truncate in menu and wrap in sheet.
- `variant?: "panel" | "plain"` = "panel": panel: a rounded-2xl surface with a raised shadow and a focus ring. plain: no surface, for a list inside your own card or sheet.
- `maxHeight?: number` = 320: px before the list scrolls; group labels stick to the top while their group scrolls. 0 grows with the content.
- `virtualThreshold?: number` = 100: Above this many visible options only the rows in view render (@tanstack/react-virtual, measured heights, aria-setsize and aria-posinset for screen readers). The playground has 42 counties, so 40 or less virtualizes it.
- `autoHighlight?: boolean` = true: Highlight the selected option (or the first match while searching) whenever the query or the options change, so Enter picks at once.
- `loop?: boolean` = true: ArrowDown on the last row wraps to the first, ArrowUp on the first to the last.
- `typeahead?: boolean` = true: Letters typed while the list itself has focus jump to the option that starts with them (500ms buffer, the same letter again cycles).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The check, the checkboxes and the tinted rows of indicator none.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `label?: ReactNode` = "": Renders the field anatomy around the list and names it (aria-labelledby). Use aria-label when there is no visible label.
- `description?: ReactNode` = "": Helper text under the list, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the list invalid (a red ring on the panel, aria-invalid).
- `required?: boolean` = false: The red mark after the label and aria-required on the list.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the list to 50% and blocks picking, searching and focus. Single options take disabled on their own.
- `name?: string`: Form field name: one hidden input per selected value (FormData.getAll(name) with multiple). A form reset returns to defaultValue.
- `aria-label?: string` = "": The list's accessible name when there is no visible label.
- `onSelect?: (option: ListboxOption) => void`: Called after every pick with the option (pickers close here in single mode).
- `renderOption?: (option, state: { selected, highlighted, disabled, ranges }) => ReactNode`: Replaces a row's content; the row element, its aria, its classes and the indicator stay.
- `labels?: Partial<{ results: (count: number) => string; clearSearch: string; retry: string }>`: The polite result count announced 500ms after the list settles ("12 results"), the clear button's name ("Clear search") and the retry button ("Try again").
- `fieldProps?: Partial<FieldProps>`: Anything else for the field wrapper: optional, labelAction, orientation, hideLabel.
- `classNames?: Partial<Record<"search" | "list" | "option" | "icon" | "label" | "description" | "badge" | "check" | "group" | "status" | "create" | "field" | "error", string>>`: Extra classes for the parts. label and description target the option's text; the field's own label keeps its recipe.

Parts:
- `useListbox` (hook): The engine behind every picker: filtering, async with abort and cache, highlight, keys, typeahead, selection, create and virtualization. Returns rows, value, selectedOptions, select / toggle / clear / selectAll, highlight / move, query / setQuery, loading / error / retry, onKeyDown (true when handled), scrollRef, and the prop getters getListProps({ focusable }), getOptionProps(row), getInputProps({ expanded }). Signature: (options: UseListboxOptions) => ListboxState.
- `ListboxProvider` (component): Shares a useListbox state with ListboxSearch, ListboxList and ListboxStatus. Props: { value: ListboxState; children: ReactNode }.
- `ListboxSearch` (component): The 44px search row with an icon, a borderless 16px-on-phones input (getInputProps), a spinner while loading and a clear button. Rest props go to the input. Props: InputProps & { placeholder?; clearLabel?; loadingLabel?; classNames? }.
- `ListboxList` (component): The rows, groups, status and announcements. scroll="parent" leaves scrolling to a DrawerBody that received scrollRef (sheets); focusable makes the list the keyboard target. Props: { density?; indicator?; highlightMatches?; maxHeight?; emptyText?; loadingText?; errorText?; retryLabel?; createLabel?; selectAllLabel?; renderOption?; focusable?; scroll?: "self" | "parent"; tone?; color?; labels?; classNames? }.
- `ListboxStatus` (component): The empty / loading / error block alone. Props: { status?: "empty" | "loading" | "error"; emptyText?; loadingText?; errorText?; retryLabel?; onRetry? }.
- `LISTBOX_ROW` (constant): The row classes per density, for custom rows that match. Type: Record<ListboxDensity, { base; description }>.
- `flattenOptions` (function): Every option of a list, with groups flattened. Signature: (items) => ListboxOption[].
- `optionText` (function): An option's plain text: label, else textValue, else value. Signature: (option) => string.

```tsx
import { useState } from "react"
import { Listbox, type ListboxItems } from "@/components/ui/listbox"

const STATES: ListboxItems = [
  { value: "CA", label: "California", keywords: ["CA", "Sacramento"] },
  { value: "NY", label: "New York", keywords: ["NY", "Albany"] },
  { value: "OR", label: "Oregon", keywords: ["OR", "Salem"] },
  { value: "TX", label: "Texas", keywords: ["TX", "Austin"] },
]

export function ShippingState() {
  const [state, setState] = useState("OR")
  return (
    <Listbox
      label="Pick a state"
      search
      searchPlaceholder="Search a state or its code…"
      emptyText="No states found"
      name="state"
      options={STATES}
      value={state}
      onValueChange={setState}
    />
  )
}
```

Docs: https://wingo-ui.com/components/listbox (Markdown: https://wingo-ui.com/components/listbox.md)

#### Masked Input (`masked-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add masked-input`

A text field that formats itself as you type or paste: card number, expiry, CVC, IBAN, CNP, postal code or a custom mask.

Type and the text shapes itself: spaces between card groups, a slash after the month, uppercase IBAN letters, and the caret always lands right after what you typed, skipping over the literals. Paste 4111-1111-1111-1111 or RO49 AAAA 1B31… with any separators and it is cleaned and re-masked; autofilled 12/2028 becomes 12/28. Backspace right after a space or slash deletes the digit before it, Delete the one after; selecting and typing replaces, and the browser's undo still works. In the expiry field a first digit from 2 to 9 is a month on its own (4 becomes 04/). With showMask the rest of the pattern shows as a faint ghost after the caret (on focus, or always). Card numbers show a card icon and the brand chip (Visa, Mastercard, Amex, Maestro, Discover) that pops in from the first digits. Once complete, a green check or a red alert icon pops in (Luhn, IBAN mod 97, CNP checksum and birth date, expiry not in the past); the red ring and aria-invalid wait until you leave the field. Enter submits the form. On a phone the keypad and autofill follow the preset (numeric for cards, CNP and postal codes, cc-number / cc-exp / cc-csc autofill), and the ghost keeps the format visible after the placeholder disappears.

npm: motion, lucide-react
Wingo UI dependencies: input, field, motion, use-controllable-state, ui-config

Props:
- `preset?: "none" | "card-number" | "card-expiry" | "card-cvc" | "iban" | "cnp" | "postal-code"` = "none": A ready mask with its validator, inputMode and autoComplete. card-number: 16 digits in groups of 4 (up to 19, Amex 4-6-5), Luhn, brand chip. card-expiry: 99/99, smart month, not in the past. card-cvc: 3 digits. iban: country length, uppercase, mod 97. cnp: 13 digits, checksum, birth date, county 01-52. postal-code: 6 digits. The playground shows the card form while none has no mask.
- `mask?: string | ((raw: string) => string)` = "": The pattern: 9 a digit, a a letter, A a letter shown uppercase, * a letter or digit, \ escapes; anything else is a literal ("AA 99 AAA"). A function picks the pattern from the raw value typed so far (Amex cards, Bucharest plates). Overrides the preset's mask; the preset's validator stays.
- `showMask?: "never" | "focus" | "always"` = "never": The rest of the mask after the caret as a faint ghost (text-muted-foreground/60), aligned with the typed text. focus shows it while the field is focused; always keeps it visible and replaces the placeholder. A resting floating label hides it.
- `maskPlaceholder?: string` = "": The ghost text for the whole mask, character by character ("mm/dd/yyyy" for 99/99/9999). Empty shows placeholderChar in each token.
- `placeholderChar?: string` = "_": The ghost character for each token when there is no maskPlaceholder.
- `showValidity?: boolean` = true: A trailing CircleCheck (success) or CircleAlert (danger) that pops in once the value is complete, with a visually hidden Valid / Invalid. Needs a validator (the preset's or validate).
- `showBrand?: boolean` = true: card-number: the leading card icon and the trailing brand chip read from the first digits.
- `submitMasked?: boolean` = false: The hidden form input (rendered when name is set) sends the masked text (4111 1111 …) instead of the raw digits. The readout under the demo shows what the form gets.
- `label?: ReactNode` = "": Renders the field anatomy around the box, linked with htmlFor. Leave it empty for a bare field (then pass aria-label).
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby; a good place for the format ("Format: LL/AA").
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid. Say why the value failed (the demo does).
- `required?: boolean` = false: The red mark after the label and the native required attribute.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message. A complete value that fails validation sets it by itself after the first blur.
- `disabled?: boolean` = false: Dims the field and blocks input; the hidden form input is disabled too, so nothing is submitted. The demo fills in the test card.
- `readOnly?: boolean` = false: The value stays visible and selectable but cannot change. The demo fills in the test card.
- `placeholder?: string` = "": Hint text while empty. Hidden while an always-visible ghost covers the field.
- `defaultValue?: string` = "": The starting raw value while uncontrolled, with or without literals ("4111111111111111").
- `name?: string` = "": Renders a hidden input with this name and the raw value (or the masked text with submitMasked), so native forms and FormData get the clean value.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px with 13 / 14 / 15px text (16px on phones so iOS never zooms); md grows to 44px on touch.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The Input's box look: a filled well, a bordered box, a bottom line or no fill until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size like the button's; full makes a pill. Ignored by underline.
- `accent?: string` = "": Any CSS color for the focus ring, the outline border on focus and the caret. Empty uses the ring token.
- `floatingLabel?: boolean` = false: The label rests inside the box and floats up on focus or when filled; the ghost waits until it has floated.
- `clearable?: boolean` = false: A clear button while there is a value; Escape clears from the keyboard.
- `prefix?: ReactNode` = "": Text before the input in the muted addon look, like "RO" or "+40", or an element rendered as is. A click on it lands in the input.
- `clearLabel?: string` = "Clear": The clear button's accessible name and title (with clearable).
- `loading?: boolean` = false: A small spinner at the end and aria-busy, e.g. while the server checks an IBAN. The field stays editable.
- `loadingLabel?: string` = "Loading": The spinner's visually hidden text.
- `selectOnFocus?: boolean` = false: Selects the whole value when the field takes focus, by click, tap or Tab, so typing replaces it.
- `enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send"` = "next": The label of the phone keyboard's Enter key. next suits a field in a form; pass done on the last one.
- `value?: string`: The raw value, controlled, without literals. A value longer than the mask shows cut but is not changed until the next edit.
- `onValueChange?: (raw: string, details: { masked: string; complete: boolean; valid: boolean | null; brand?: CardBrand | null }) => void`: Fires on every edit with the raw value and the details: the masked text, whether every token is filled, the validator's verdict once complete (null before), and the card brand for card-number.
- `validate?: (raw: string) => boolean`: Runs once the value is complete; replaces the preset's validator. Without one (and without a preset) valid stays null and no icon shows. The file also exports the engine and the checks for server code, initial state and read-only displays: applyMask(raw, mask), getMaskDetails(raw, { preset, mask, validate }), detectCardBrand(digits), isValidLuhn, isValidIban, isValidCnp, isValidExpiry.
- `labels?: Partial<{ valid: string; invalid: string; brands: Partial<Record<CardBrand, string>> }>`: The visually hidden text of the validity icon ("Valid" / "Invalid") and the brand chip names.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event, untouched. Its target value is the masked text; read the raw value from onValueChange.
- `leftIcon?: ReactNode`: A leading icon; card-number shows a card icon by default (with showBrand).
- `suffix?: ReactNode`: Text or an element after the brand chip and the validity icon.
- `rightIcon?: ReactNode`: A trailing icon after the brand chip and the validity icon; it crossfades with the spinner while loading.
- `clearIcon?: ReactNode`: Replaces the clear button's icon (a 16px X by default).
- `onClear?: () => void`: Called after the clear button or Escape emptied the field (with clearable). onValueChange fires too, with an empty raw value.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional and optionalLabel, labelAction, orientation, labelWidth, hideLabel, requiredIndicator.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native input. Every other Input prop and native prop lands on it: inputMode, autoComplete and autoCapitalize (defaults from the preset), onBlur, aria-describedby. With react-hook-form use Controller (value / onValueChange), not register, since the element holds the masked text.
- `classNames?: Partial<Record<InputSlot | "ghost" | "brand" | "validity", string>>`: Extra classes for the Input's parts plus the ghost, the brand chip and the validity icon.

```tsx
import { useState } from "react"
import { MaskedInput, type MaskedInputDetails } from "@/components/ui/masked-input"

export function CardForm() {
  const [card, setCard] = useState("")
  const [details, setDetails] = useState<MaskedInputDetails | null>(null)
  const [touched, setTouched] = useState(false)

  return (
    <form className="flex flex-col gap-4">
      <MaskedInput
        preset="card-number"
        name="card"
        label="Card number"
        placeholder="1234 5678 9012 3456"
        value={card}
        onValueChange={(raw, info) => {
          setCard(raw)
          setDetails(info)
        }}
        onBlur={() => setTouched(true)}
        error={touched && details?.valid === false ? "The card number is not valid." : undefined}
        required
      />
      <div className="grid grid-cols-2 gap-3">
        <MaskedInput preset="card-expiry" name="expiry" label="Expiry" placeholder="MM/YY" showMask="focus" maskPlaceholder="MM/YY" />
        <MaskedInput preset="card-cvc" name="cvc" label="CVC" placeholder="123" enterKeyHint="done" />
      </div>
      <MaskedInput
        label="License plate (Romania)"
        mask={(raw) => (/^B\d/i.test(raw) ? "A 999 AAA" : "AA 99 AAA")}
        placeholder="CJ 12 ABC"
        autoCapitalize="characters"
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/masked-input (Markdown: https://wingo-ui.com/components/masked-input.md)

#### Mention Input (`mention-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add mention-input`

A note field where @ mentions people, # adds tags and any trigger you define inserts chips, stored as markup that survives renames.

Type @ at the start of a word and a list of people opens at the caret; keep typing (spaces allowed, so “Daniel Re” still filters, accents and case ignored) and the matching letters turn bold. Up and Down move through the list and wrap, PageUp and PageDown jump by five, Home and End go to the ends while the list is open, Enter or Tab inserts, a click or a tap inserts without the field losing focus. The mention lands as a tinted chip followed by a space, and the caret goes after it. Type # for tags: when nothing matches exactly the last row offers “Create #…”. Escape closes the list first; a second Escape reaches the dialog or sheet around the field. A mention is one piece: Backspace right after it or Delete right before it removes all of it, Left and Right step over it in one press, a click, a tap or Up / Down that would land inside it puts the caret at its nearer edge, a double-click or a drag that starts inside it selects all of it, and typing over a selection that cuts it removes it. Undo brings a removed chip back. Copying text with chips and pasting it into another mention field keeps the chips. ⌘ Enter (Ctrl Enter elsewhere) submits; the playground’s Save note adds the note below, rendered with MentionText. With maxLength a counter sits in the box and shakes when an insert would not fit. On a phone the text is 16px, rows are at least 44px and the list attaches to the edge of the box, flipping above it when the keyboard would cover it, so the keyboard never closes. Screen readers hear the plain text (“@Daniel Reed”), the highlighted suggestion as it moves, “No matches” when nothing fits, and a short note when a mention is added or removed.

npm: motion
Wingo UI dependencies: field, listbox, avatar, spinner, text-match, use-controllable-state, use-media-query, use-keyboard-inset, use-shortcut, motion, tones, ui-config

Props:
- `defaultValue?: string` = "": The starting markup while uncontrolled. Mentions are trigger + [label](id): @[Daniel Reed](u-daniel), #[follow-up](t-follow-up); brackets and backslashes inside are escaped with \. The playground falls back to a sample note when it is empty.
- `value?: string`: The markup, to control it from outside; pair it with onValueChange. A change from outside while typing keeps the caret at the same plain-text offset.
- `onValueChange?: (value: string, context: MentionChangeContext) => void`: Called with the new markup on every change, plus a context { text; mentions: MentionRef[] }: the plain text people see and the mentions with their offsets (for notifications).
- `onChange?: (event: ChangeEvent<HTMLTextAreaElement | HTMLInputElement>) => void`: The native change event of the control, untouched. Its value is the plain text, not the markup.
- `people?: MentionItem[]`: Shorthand for the @ trigger: { id; label; avatar?; description?; icon?; keywords?; disabled? }. Rows show the avatar (initials without a photo) and the description under the name; spaces are allowed in the query.
- `tags?: MentionItem[]`: Shorthand for the # trigger. Rows show a # tile unless an item has its own icon.
- `triggers?: MentionTrigger[]`: Full control: { char; items?; onSearch?(query) => Promise<MentionItem[]>; allowCreate?; onCreate?(label); tone?; color?; title?; minChars?; maxResults? (8); allowSpaces? }. char is one symbol or punctuation character. Entries win over people / tags for the same char, field by field, so { char: "@", tone: "info" } keeps the people list. onSearch is debounced 200ms and drops stale answers.
- `allowCreateTags?: boolean` = true: The # list ends with “Create #query” when nothing matches exactly. The created tag (onCreate's result, by default { id: label, label }) is inserted and offered again later.
- `multiline?: boolean` = true: A textarea that grows with the text from minRows to maxRows; false renders a single-line input for task titles, where the text scrolls sideways and the chips follow.
- `minRows?: number` = 3: Height of the empty textarea in rows.
- `maxRows?: number` = 8: The textarea grows up to this many rows, then scrolls inside; the chips scroll with the text.
- `placeholder?: string` = "Write a note. Type @ to mention someone, # to add a tag": Shown while the field is empty; it is the best place to teach the triggers.
- `size?: "sm" | "md" | "lg"` = "md": The field sizes: text 13 / 14 / 15px (16px on phones, so iOS never zooms) and one row as tall as an input of the same size.
- `variant?: "soft" | "outline" | "ghost"` = "soft": soft is a filled well that works on every surface, outline a bordered box, ghost invisible until hovered (inline notes).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button's (md is 8 / 10 / 12px). full is a pill on one line and half a row height on a taller box.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The chip tint of every trigger without its own tone or color. Neutral is a quiet gray in both themes.
- `color?: string` = "": Any CSS color for the chips; replaces the tone. The tint is mixed at 14% so the text on it stays readable.
- `label?: ReactNode` = "": Renders the field anatomy with a label linked to the control. Leave it empty for a bare box.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description, slides in and marks the box invalid.
- `required?: boolean` = false: The required mark after the label and required on the control.
- `maxLength?: number` = 0: A limit on the plain text (a chip counts as its visible text). A counter sits in the box, turns amber at 90% and red at the limit, and shakes when a mention would not fit (the insert is refused).
- `suggestionsPlacement?: "auto" | "caret" | "below" | "above"` = "auto": auto opens the list at the caret with a mouse and attaches it to the box edge on touch, above the box when the keyboard would cover the room below. With a mouse the list is portaled above everything, so no card or dialog body ever cuts it. On touch it renders in flow against the box, so it rides every scroll with the field while the keyboard is up; when the parents that clip it (an overflow-hidden card, a sheet or dialog body) leave it too little room, it is portaled instead. A parent that isolates without clipping needs z-dropdown so the in-flow list paints over what follows it.
- `onSubmit?: (value: string, context: MentionChangeContext) => (void | Promise<unknown>)`: Runs on submitShortcut with the markup and { text, mentions }. A promise locks the field (read-only, dimmed, aria-busy) until it settles. Without it the shortcut submits the surrounding form.
- `submitShortcut?: string` = "mod+enter": A combo in mod+k notation, bound on the field only while it has focus. "enter" makes it chat style (a bare Enter still makes new lines on touch keyboards); "" turns it off.
- `disabled?: boolean` = false: Dims the field and blocks typing.
- `readOnly?: boolean` = false: The text and its chips stay visible and selectable; no suggestions open.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `autoFocus?: boolean` = false: Focuses the field on mount with the caret at the end of any starting text.
- `name?: string` = "": Adds a hidden input with the markup, so a native form posts the mentions, not just the text.
- `labels?: Partial<MentionInputLabels>`: suggestions “Suggestions”, people “People”, tags “Tags”, create (label, trigger) => “Create “#label””, empty “No matches”, loading “Searching…”, mentioned (label) => “label mentioned”, removed (label) => “label removed”, counter (count, max) => “count of max”, limitReached “Character limit reached”. Exported as DEFAULT_MENTION_INPUT_LABELS.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "box" | "control" | "highlighter" | "chip" | "suggestions" | "option" | "counter", string>>`: Extra classes for the parts: field, label, description and error style the field anatomy, the rest the box and the list. The highlighter and the control must keep the same font, padding and line height, so style both or neither.
- `className?: string`: Extra classes for the field root (the box when there is no label, description or error).
- `ref?: Ref<HTMLTextAreaElement | HTMLInputElement> (a useRef object or an (el) => void callback)`: The native control. Every other prop (id, aria-*, onKeyDown, onFocus, enterKeyHint) is spread onto it too.

Parts:
- `MentionText` (component): Renders a stored value read-only with the same chips, for comments, audit rows and approval history. Mentions of highlightIds (the current user) take highlightTone; renderMention can wrap a chip in a link. Props: { value: string; triggers?; tone?; color?; highlightIds?: string[]; highlightTone? ("brand"); renderMention?(mention, chip) }.
- `parseMentionMarkup` (function): Splits markup into { type: "text"; text } and { type: "mention"; trigger; id; label } segments. Unknown ids still parse; empty labels are dropped. Signature: (value: string) => MentionSegment[].
- `getMentions` (function): Every mention with { trigger, id, label, start, end } in plain-text offsets, e.g. to notify the people mentioned. Signature: (value: string) => MentionRef[].
- `mentionsToText` (function): The plain text people read: “Call @Daniel Reed tomorrow”. For previews, search indexes and emails. Signature: (value: string) => string.
- `createMentionMarkup` (function): The markup of one mention, escaped, to build a value on the server or prefill a reply. Signature: (trigger: string, item: { id: string; label: string }) => string.
- `serializeMentionSegments` (function): The inverse of parseMentionMarkup: segments back to markup, with text that looks like markup escaped. Signature: (segments: MentionSegment[]) => string.

```tsx
import { useState } from "react"
import { MentionInput, MentionText, getMentions, type MentionItem } from "@/components/ui/mention-input"

const team: MentionItem[] = [
  { id: "u-daniel", label: "Daniel Reed", avatar: "/demo/mihai-ionescu.jpg", description: "Sales manager" },
  { id: "u-sophia", label: "Sophia Lee", avatar: "/demo/ioana-dumitrescu.jpg", description: "Accounting" },
]
const tags: MentionItem[] = [
  { id: "t-follow-up", label: "follow-up" },
  { id: "t-quote", label: "quote" },
]

export function ClientNote() {
  const [note, setNote] = useState("Call @[Daniel Reed](u-daniel) tomorrow #[follow-up](t-follow-up)")
  const [saved, setSaved] = useState<string[]>([])
  return (
    <div className="flex flex-col gap-3">
      <MentionInput
        label="New note"
        value={note}
        onValueChange={setNote}
        people={team}
        tags={tags}
        placeholder="Write a note. @ for teammates, # for tags"
        onSubmit={(value) => {
          console.log("notify", getMentions(value).map((m) => m.id))
          setSaved((prev) => [value, ...prev])
          setNote("")
        }}
      />
      {saved.map((value, i) => (
        <MentionText key={i} value={value} className="text-sm" />
      ))}
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/mention-input (Markdown: https://wingo-ui.com/components/mention-input.md)

#### Month Picker (`month-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add month-picker`

Pick a month or a range of months from a year grid, with quarters and presets, for reports, billing periods and card expiry dates.

Click the field to open a panel under it with the year at the top and its twelve months in four rows of three; the current month carries a small dot. The arrows beside the year move one year (the grid slides that way), and the year itself opens a grid of twelve years for long jumps (its arrows move twelve years). In single mode a click on a month sets it, the fill glides to it and the panel closes. In range mode the first click sets the first month, moving the pointer previews the band, and the second click sets the last month (a month before the first swaps them); months past maxMonths or beyond a disabled month cannot be picked while the band is open. The range commits on the second click and the panel stays open until Escape, Enter or a click outside, with a summary like "Jul - Sep 2026 · 3 months" under the grid. Quarter chips (Q1 to Q4, T1 to T4 in French or Spanish) pick three months at once, or the quarter's first month in single mode, and presets (This month, Last 3 months, This year...) sit in a column on the left, clamped to min and max. The clear button empties the field. Keyboard: Enter, Space or ArrowDown on the field open the panel with focus on the selected (else the current) month; arrows move one month, Up / Down three, Home / End the row's ends, PageUp / PageDown a year, Enter or Space pick, and Enter on the last month of a range closes the panel. Escape first leaves the years grid, then drops a half-picked range, then closes and returns focus to the field. On a phone the field opens a bottom sheet with the title, the presets as a row of chips, 48px month cells and the quarters; single mode commits on tap and closes, range mode keeps a draft in the sheet until Apply, and Cancel or dragging the sheet away keeps the old value. name submits YYYY-MM, or name.from and name.to as ISO dates.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: button, drawer, field, date-utils, relative-time, use-controllable-state, use-locale, use-media-query, motion, tones, ui-config

Props:
- `mode?: "single" | "range"` = "single": single picks one month (value: its first day at 00:00); range picks a span of months (value: from the first day of the first month to the last day of the last one, ready for a query).
- `value?: Date | null (single) | DateRange (range)`: The month or range, controlled. A date in the middle of a month shows as its month and is not rewritten; a value outside min / max or on a disabled month shows as given and flags the field invalid.
- `defaultValue?: Date | null (single) | DateRange (range)` = "null / { from: null, to: null }": The starting value while uncontrolled. A form reset returns to it.
- `onValueChange?: (value: MonthPickerValue<mode>) => void`: Called with the new month (single) or the complete range (range: on the second click, a quarter or a preset; on phones on Apply). A half-picked range never reaches it. null or { from: null, to: null } when cleared.
- `label?: ReactNode` = "": The field label. Plain text also titles the phone sheet and names the panel.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with the error and marks the field invalid.
- `placeholder?: string` = "": The empty trigger text. Empty uses "Pick a month" (single) or "Pick months" (range).
- `presets?: boolean | MonthPreset[]` = false: true: This month, Last month, Last 3 / 6 / 12 months, This year and Last year in range mode (This month and Last month in single), clamped to min / max and off when they break maxMonths or touch a disabled month. Or your own list of { label, value: Date | DateRange | () => Date | DateRange, key? }. A column on the left from 640px, a chip rail on phones.
- `locale?: string` = "": Month names, the trigger text and the quarter letter (Q in English, T in Romanian, French, Spanish, Italian, Portuguese). Empty uses the nearest LocaleProvider, else the page's language.
- `sheetTitle?: string` = "": The phone sheet title when the label is not plain text. Empty uses labels.dialog ("Choose month").
- `displayFormat?: Intl.DateTimeFormatOptions` = "{ month: \"long\", year: \"numeric\" } (single), { month: \"short\", year: \"numeric\" } (range)": The trigger text through Intl: "septembrie 2026"; ranges through formatRange, the shared year folded ("iul. - sept. 2026", across years "nov. 2025 - feb. 2026").
- `formatValue?: (value: MonthPickerValue<mode>, locale: string) => string`: Your own trigger text, for formats Intl does not write, like a card expiry "09/28".
- `icon?: ReactNode` = "<CalendarDays />": The leading icon of the trigger.
- `labels?: Partial<MonthPickerLabels>` = "DEFAULT_MONTH_PICKER_LABELS": Every string: previousYear, nextYear, previousYears, nextYears, chooseYear, quarter(q), quarters, presets, the preset names (thisMonth, lastMonth, last3Months, last6Months, last12Months, thisYear, lastYear), months(count) for the summary, pickStart, pickEnd, apply, cancel, clear, dialog.
- `size?: "sm" | "md" | "lg"` = "md": The field height: 32 / 40 / 48px (44px on touch for md), matching inputs and selects.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box: a soft fill, a hairline outline, a bottom line, or nothing until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The field corners, per size like the button.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected months, the range band, the quarter chips and Apply.
- `color?: string` = "": Any CSS color for the selection; replaces the tone.
- `monthFormat?: "short" | "long"` = "short": The month cells: "Sept." or "Septembrie".
- `classNames?: Partial<Record<MonthPickerSlot, string>>`: Classes per part: field, label, description, error, box, trigger, icon, value, clear, chevron, content, panel, header, title, nav, grid, month, years, year, quarters, quarter, presets, preset, footer, summary.
- `min?: Date`: The first month that can be picked; earlier months are disabled and the year arrows stop there.
- `max?: Date`: The last month that can be picked. A max before min is ignored.
- `quarters?: boolean` = false: The Q1 to Q4 chips under the grid. Left unset they show in range mode (three months at once) and hide in single mode, where true adds them and a quarter picks its first month.
- `maxMonths?: number` = 0: The longest range in months; while you pick the end, months farther away are disabled. 0 = no limit.
- `clearable?: boolean` = false: A clear button inside the field while it has a value.
- `closeOnSelect?: boolean` = true: Single mode closes after a pick. Range mode always stays open until Escape, Enter or a click outside.
- `now?: Date | number`: What this month means: the current-month dot and the presets. Left out, the live clock (useNow); pin it for screenshots.
- `name?: string` = "": Hidden inputs for forms: single submits YYYY-MM, range submits name.from and name.to as ISO dates.
- `disabled?: boolean or (month: Date) => boolean` = false: true dims the whole field and never opens it. A test disables single months instead (closed accounting periods): it gets each month's first day.
- `readOnly?: boolean` = false: The value stays visible but the panel never opens.
- `required?: boolean` = false: The mark after the label and aria-required on the trigger.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `open?: boolean`: The panel, controlled. Pair it with onOpenChange.
- `defaultOpen?: boolean` = false: Opens the panel on mount while uncontrolled.
- `onOpenChange?: (open: boolean) => void`: Called when the panel or sheet opens or closes.
- `inline?: boolean` = false: The panel sits on the page without a trigger (a raised surface with the grid, quarters, presets and the range summary).
- `responsive?: boolean` = true: A bottom sheet below 768px instead of the popover.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the popover opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the popover lines up with the field.
- `container?: HTMLElement | null`: The portal target of the popover and the sheet (default document.body).
- `id?: string`: The trigger's id; the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, hideLabel.
- `ref?: Ref<HTMLButtonElement> (a useRef object or an (el) => void callback)`: The trigger button (a regular prop in React 19).

Parts:
- `MonthPickerPanel` (component): The grid alone on a raised panel, for inline use and composition: mode, value / defaultValue / onValueChange, min, max, disabled, quarters, presets, maxMonths, monthFormat, tone, color, now, locale, labels, classNames, autoFocus. Props: MonthPickerPanelProps<M>.
- `DEFAULT_MONTH_PICKER_LABELS` (constant): The English strings; spread them to translate a few. Type: MonthPickerLabels.
- `startOfMonthDate` (function): The first / last day of the date's month at 00:00. Signature: (date: Date) => Date.
- `endOfMonthDate` (function): The first / last day of the date's month at 00:00. Signature: (date: Date) => Date.
- `getQuarter` (function): The quarter a date falls in. Signature: (date: Date) => 1 | 2 | 3 | 4.
- `quarterRange` (function): The quarter as a range: its first day to its last day (Q3 2026: Jul 1, 2026 to Sep 30, 2026). Signature: (year: number, quarter: number) => { from: Date; to: Date }.

```tsx
import { useState } from "react";
import { MonthPicker, type DateRange } from "@/components/ui/month-picker";

export function SalesReport() {
  const [period, setPeriod] = useState<DateRange>({ from: new Date(2026, 6, 1), to: new Date(2026, 8, 30) });
  const [month, setMonth] = useState<Date | null>(new Date(2026, 8, 1));
  return (
    <div className="flex flex-col gap-4">
      <MonthPicker
        mode="range"
        label="Period"
        presets
        max={new Date()}
        value={period}
        onValueChange={setPeriod}
        name="period"
        labels={{ apply: "Done" }}
      />
      <MonthPicker label="Billing month" value={month} onValueChange={setMonth} min={new Date(2024, 0, 1)} max={new Date()} />
    </div>
  );
}
```

Docs: https://wingo-ui.com/components/month-picker (Markdown: https://wingo-ui.com/components/month-picker.md)

#### Multi Select (`multi-select`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add multi-select`

Pick several options from a list, shown as chips with a measured +N overflow, with search, select all, a maximum and async options.

Click or tap the field to open the list under it; every row has a checkbox, and clicking a row toggles it while the list stays open (closeOnSelect closes it after each pick). The chosen options show as chips in the field: as many as fit on one line, measured as the field resizes, then a "+N" chip whose number crossfades; chips slide in and out as you pick. Each chip's x removes it without opening the list, and an x at the end of the field clears everything. The footer under the list shows the count ("3 selected", or "2 of 3 selected" with a maximum) and a Clear all button; at the maximum the unselected rows turn disabled. With selectAll a row on top toggles every visible option. Above 8 options (or with loadOptions, creatable or search="always") a search row sits on top and takes focus: typing filters, case and diacritics never matter and matched letters turn bold; Backspace in the empty search removes the last chip. display="count" shows "3 selected" instead of chips, display="text" the names joined and truncated, and wrap lets chips flow onto more lines while the field grows. Keyboard: Tab reaches the field (chip x buttons stay out of the tab order) and a click on its label focuses it. While closed, Enter, Space and ArrowDown open it, ArrowUp opens on the last option, Home and End open at the ends, and Backspace removes the last chip. While open, ArrowDown and ArrowUp move and wrap, PageUp and PageDown jump, Enter or Space toggle the highlighted row and keep the list open, Cmd/Ctrl+A selects all (when the list, not the search, has focus), Escape or Alt+ArrowUp close and keep focus on the field, Tab closes and moves on. On a phone the field opens a bottom sheet titled with the label, with 48px checkbox rows and a sticky footer: "Done (3)" commits the picks and "Clear all" empties the draft; dragging the sheet down, tapping outside or Escape discards the changes. With name, one hidden input per value submits (FormData.getAll), an empty required field blocks the submit and a form reset restores the default. With reduced motion chips and the list appear without sliding or scaling.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: ui-config, listbox, field, drawer, badge, button, spinner, motion, tones, use-media-query, use-controllable-state

Props:
- `options: MultiSelectItems`: Options and groups: { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? } or { label, items }. The icon also shows inside the chip.
- `value?: string[]`: The chosen values, controlled. Values not among the options keep their chips (labels from the cache, else the value).
- `defaultValue?: string[]`: The starting values while uncontrolled (empty when omitted). A form reset returns to them.
- `onValueChange?: (value: string[]) => void`: Called with the new values after a toggle, a chip removal, select all, clear, or Done in the phone sheet.
- `label?: ReactNode` = "": The field label. A click focuses the trigger; plain text also titles the phone sheet and names the trigger with the count.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid.
- `required?: boolean` = false: The red mark after the label, aria-required on the trigger; with name an empty field blocks the form submit.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, never opens, chips are not removable and nothing is submitted.
- `readOnly?: boolean` = false: The chips stay visible and the field focusable, but it never opens and nothing can be removed or cleared.
- `placeholder?: string` = "Select options": Shown in the field while nothing is chosen.
- `display?: "chips" | "count" | "text"` = "chips": How the value shows in the field: chips; "3 selected"; or the names joined and truncated.
- `maxVisibleChips?: number` = 0: At most this many chips, then +N. 0 shows as many as fit on one line, measured on resize.
- `wrap?: boolean` = false: Chips wrap onto more lines and the field grows instead of collapsing into +N.
- `chipRemovable?: boolean` = true: Each chip has an x that removes it without opening the list; Backspace on the field removes the last one.
- `showChipIcons?: boolean` = true: The option's icon (an avatar, a flag) inside its chip.
- `maxSelected?: number` = 0: The most options that can be chosen; at the limit the other rows turn disabled. 0 means no limit.
- `selectAll?: boolean` = false: A "Select all" row on top that toggles every visible option (respecting maxSelected).
- `clearable?: boolean` = true: An x at the end of the field that clears everything while something is chosen.
- `closeOnSelect?: boolean` = false: Closes the popover after every pick. The phone sheet always waits for Done.
- `search?: "auto" | "always" | "never"` = "auto": The search row: auto shows it above 8 options, with loadOptions or with creatable.
- `searchPlaceholder?: string` = "Search…": The search row's placeholder.
- `emptyText?: string` = "No results": Shown when the search matches nothing (or there are no options).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The chips, the checkboxes and the sheet's Done button.
- `color?: string` = "": Any CSS color for the chips and checkboxes; replaces the tone. Leave empty to use the tone.
- `loading?: boolean` = false: Options are on their way: a spinner replaces the chevron and the list shows a loading row.
- `loadingText?: string` = "Loading…": The loading row's text and the spinner's accessible name.
- `highlightMatches?: boolean` = true: Bold matched letters while searching.
- `leftIcon?: ReactNode`: A leading icon in the field.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px (md grows to 44px on touch) with 20 / 24 / 28px chips, 16px text on phones.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field look, the same as every other field.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius, scaled per size like the button; full also makes the chips pills. Ignored by underline.
- `name?: string` = "": Renders one hidden input per value with this name, so FormData.getAll(name), required and form reset work.
- `id?: string`: The trigger's id (useId() by default); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `defaultOpen?: boolean` = false: Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the list is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the list opens or closes.
- `responsive?: boolean` = true: A bottom sheet with 48px checkbox rows and a Done button below 768px instead of the popover.
- `sheetTitle?: string` = "": The phone sheet's title. Empty uses the label's text, else aria-label, else the placeholder.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the list opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the list lines up with the field.
- `maxHeight?: number` = 360: The list's maximum height in px (search and footer included), capped by the room on screen.
- `virtualThreshold?: number` = 100: Above this many visible options only the rows in view render.
- `loadOptions?: (query: string, context: { signal: AbortSignal }) => Promise<MultiSelectItems>`: Async options for the debounced query; the previous request is aborted and results are cached per query.
- `debounce?: number` = 250: ms to wait after typing before loadOptions runs.
- `minQueryLength?: number` = 0: loadOptions waits for this many characters.
- `creatable?: boolean` = false: A create row when the query matches nothing exactly; pair it with onCreate.
- `onCreate?: (query: string) => (string | void | Promise<string | void>)`: Creates an option from the query; a returned value is selected.
- `createLabel?: (query: string) => ReactNode`: The create row's text (default: Create "query").
- `filter?: boolean, or (option: MultiSelectOption, query: string) => score (number, null hides)`: Default true: true filters with text-match; false means the options are already filtered; a function scores (null hides).
- `fuzzy?: boolean` = false: Fuzzy matching for the search.
- `renderOption?: (option, state: { selected, highlighted, disabled, ranges }) => ReactNode`: Replaces a row's content; the row element, its checkbox, aria and classes stay.
- `container?: HTMLElement | null`: Where the list or the sheet is portaled (document.body by default).
- `labels?: Partial<MultiSelectLabels>`: Every string: { selectAll, clearAll, done, selected(n), limit(n, max), more(n), remove(label), results(n), clearSearch, retry }. Defaults: "Select all", "Clear all", "Done", "3 selected", "2 of 3 selected", "+3", "Remove Auto", the announced result count, the search clear button and the retry button.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "trigger" | "icon" | "chips" | "chip" | "overflow" | "placeholder" | "summary" | "clear" | "chevron" | "content" | "search" | "list" | "item" | "group" | "empty" | "footer", string>>`: Extra classes for the inner parts. box is the field box, trigger the button covering it, content the popover (or the sheet).
- `className?: string`: Merged onto the Field root when there is a label, description or error, otherwise onto the box.
- `ref?: RefObject<HTMLButtonElement | null> or (node) => void`: The trigger button; other props (onBlur, aria-*, data-*, form) go there too.

```tsx
import { useState } from "react"
import { Car, Building2, Smartphone, Dumbbell } from "lucide-react"
import { MultiSelect, type MultiSelectOption } from "@/components/ui/multi-select"

const CATEGORIES: MultiSelectOption[] = [
  { value: "real-estate", label: "Real estate", icon: <Building2 /> },
  { value: "vehicles", label: "Vehicles", icon: <Car /> },
  { value: "electronics", label: "Electronics", icon: <Smartphone /> },
  { value: "sports", label: "Sports", icon: <Dumbbell /> },
]

export function FollowedCategories() {
  const [categories, setCategories] = useState<string[]>(["vehicles"])
  return (
    <MultiSelect
      label="Followed categories"
      placeholder="Pick categories"
      options={CATEGORIES}
      value={categories}
      onValueChange={setCategories}
      maxSelected={3}
      selectAll
      name="categories"
      labels={{
        selected: (n) => `${n} picked`,
        limit: (n, max) => `${n} of ${max} picked`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/multi-select (Markdown: https://wingo-ui.com/components/multi-select.md)

#### Number Input (`number-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add number-input`

A field for numbers people type or step: steppers with hold to repeat, min, max and step, and Intl formatting for money and units.

Type a number the way you write it: 1.234,5 in Romanian or 1,234.5 in English both work, a comma or a dot is taken as the decimal, and letters are simply refused (a refused key typed over a selection keeps it selected). At rest the field shows the formatted value ($125,000, 2.5 kg); focus it and it turns into the plain number, ready to edit, and Tab selects it all like any field. Press + or - to step, and hold either one: after a short pause it repeats, faster the longer you hold, and stops at min or max, where that button dims. ArrowUp and ArrowDown step, Shift or PageUp and PageDown take the large step, Home and End jump to min and max, Enter commits and still submits the form, Escape puts back the last committed value. With the field focused the mouse wheel steps too, without scrolling the page. A number typed past a bound shows the red ring until you leave the field, where it snaps back inside (or cannot be typed at all with strict clamping). On a phone the keypad is numeric (decimal when the step allows decimals), the text is 16px so iOS never zooms, the md box grows to 44px, each + and - has a 44px hit area (the stacked chevrons turn into a row of two 44px buttons), and a finger that starts scrolling on a stepper undoes its step. iOS keypads have no minus key, so negative values come from the steppers.

npm: motion, lucide-react
Wingo UI dependencies: field, number-format, use-locale, motion, use-controllable-state, ui-config

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the box and links it to the input with htmlFor. Leave it empty for a bare field.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid (red ring, aria-invalid).
- `required?: boolean` = false: The mark after the label, and required on the input, so native form validation stops an empty submit.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message. A value outside min and max (typed or controlled) sets it on its own until it is back in range.
- `disabled?: boolean` = false: Dims the field to 50%, blocks typing and the steppers, and leaves the hidden form input out of the submit.
- `readOnly?: boolean` = false: The formatted value stays visible and selectable; the steppers, keys and the wheel stop and the steppers hide.
- `placeholder?: string` = "": Hint text while the field is empty.
- `prefix?: ReactNode` = "": Text or an element before the number, like €. A click on it lands in the input.
- `suffix?: ReactNode` = "": Text or an element after the number: m², buc., %, kg. With steppers split it hugs the value in the middle.
- `incrementLabel?: string` = "Increase": The + button's accessible name and hover title. The demo passes Increase.
- `decrementLabel?: string` = "Decrease": The - button's accessible name and hover title. The demo passes Decrease.
- `name?: string` = "": Renders a hidden input with this name and the value as "1234.5" (dot decimal, empty when null), so FormData and plain form posts get a number, not the formatted text. The visible input has no name.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px, like a button. md grows to 44px on touch screens and the text is 16px on phones so iOS never zooms.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box: a soft fill, an outline, a bottom border that grows a bar on focus, or ghost for tables and toolbars.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button (md is 8 / 10 / 12px). Ignored by underline.
- `steppers?: "end" | "split" | "stacked" | "none"` = "end": end: - and + at the end. split: - at the start and + at the end with the value centered, the best layout for quantities on a phone. stacked: small chevrons in a column at the end, the desktop classic; on touch screens the column turns into a row of two 44px chevron buttons. none: keys and the wheel only.
- `min?: number` = -9007199254740991: The lowest value. Steppers and keys stop here (the - button dims), Home jumps here, typed values clamp to it on blur, and a value below it is flagged invalid. Unbounded by default (the safe integer range). min above max is swapped with a dev warning.
- `max?: number` = 9007199254740991: The highest value, the same way: + dims at max, End jumps here, typed values clamp to it on blur.
- `step?: number` = 1: What + / - and the arrows add, counted from min, so an off-grid value first lands on the next multiple. It also sets the precision (0.1 keeps one decimal) unless decimals is set, and the keypad (numeric for whole steps, decimal otherwise).
- `largeStep?: number` = 10: What Shift + arrows, PageUp and PageDown (and Shift + wheel) add.
- `decimals?: number` = -1: Fraction digits kept: typing more is refused and values round to it. The default -1 takes them from step and format (2 for a USD price, 1 for step 0.1, 0 for step 1).
- `clampBehavior?: "blur" | "strict" | "none"` = "blur": blur: out-of-range typing is allowed (the red ring shows) and clamped when the field loses focus. strict: a keystroke that can only move further out of range is refused. none: never clamped, validate it yourself.
- `holdToRepeat?: boolean` = true: Holding a stepper repeats after 400ms, speeding up from every 100ms to every 30ms, and stops at min or max.
- `wheel?: boolean` = true: The mouse wheel or trackpad steps while the field is focused and hovered (and the page does not scroll). Touch screens have no wheel.
- `selectOnFocus?: boolean` = false: Selects the whole number when the field takes focus, clicks included. Keyboard focus selects it either way, like a native field.
- `formatOnBlur?: boolean` = true: Shows the formatted value at rest ("$1,234.50") and the plain number while editing ("1234.5"). Off, the plain number always shows.
- `locale?: string` = "": Formats and parses with this locale: separators, the currency symbol and its position. Empty uses the nearest LocaleProvider, then the page language. The demo passes "en-US".
- `currency?: string` = "": An ISO code like "USD", "EUR" or "RON": shorthand for a currency format with the narrow symbol ($1,234.50, 1.234,50 €).
- `value?: number | null`: The controlled value; null is an empty field. A value outside min and max is shown as given and flagged invalid, never clamped silently.
- `defaultValue?: number | null` = "null": The starting value while uncontrolled; null is an empty field. A form reset returns to it.
- `onValueChange?: (value: number | null) => void`: Every change: live while typing (out of range until blur with clampBehavior blur), every stepper tick and key, the wheel. null when the field is empty or holds only a minus.
- `onValueCommit?: (value: number | null) => void`: Once per edit, for expensive updates: on blur, on Enter, when a held stepper is released and when a stepping key goes up. Only when the value changed.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native input event, for keystrokes the field accepts.
- `format?: Intl.NumberFormatOptions`: How the value reads at rest: { style: "unit", unit: "kilogram" } for "2,5 kg", { style: "percent" } for fractions (0.15 shows 15% and is typed as 15), { useGrouping: false } for years. Invalid options fall back to plain numbers.
- `leftIcon?: ReactNode`: An icon at the start of the box (inside the centered group with steppers split). Unsized svgs follow the size.
- `incrementIcon?: ReactNode`: Replaces the + (or the up chevron when stacked).
- `decrementIcon?: ReactNode`: Replaces the - (or the down chevron when stacked).
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional and optionalLabel, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The input's id. Defaults to useId(); inside a <Field> the Field's id wins.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native input (role spinbutton, with aria-valuenow, min, max and valuetext). Every other native prop lands there too: inputMode (decimal or numeric by precision), enterKeyHint (done), autoComplete (off), onBlur, onKeyDown, aria-* and data-*.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "input" | "icon" | "prefix" | "suffix" | "steppers" | "increment" | "decrement", string>>`: Extra classes for the inner parts. box targets the field box, input the native element, steppers the stepper group or column.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description or error, else the box.

```tsx
import { useState } from "react"
import { NumberInput } from "@/components/ui/number-input"

export function PropertyDetails() {
  const [area, setArea] = useState<number | null>(85)
  const [rooms, setRooms] = useState<number | null>(3)

  return (
    <form className="flex flex-col gap-4">
      <NumberInput
        name="area"
        label="Floor area"
        suffix="m²"
        min={10}
        max={1000}
        value={area}
        onValueChange={setArea}
        locale="en-US"
        required
      />
      <NumberInput name="rooms" label="Rooms" steppers="split" min={1} max={10} value={rooms} onValueChange={setRooms} />
      <NumberInput
        name="price"
        label="Price"
        currency="USD"
        locale="en-US"
        step={1000}
        decimals={0}
        defaultValue={485000}
        onValueCommit={(price) => console.log("Price saved:", price)}
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/number-input (Markdown: https://wingo-ui.com/components/number-input.md)

#### OTP Input (`otp-input`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add otp-input`

A one-time-code input whose characters roll into place behind a caret that slides from slot to slot.

Type to fill each slot and move to the next one. Backspace clears a slot in place, then steps back on the next press. Arrow keys move between slots, and a caret slides along with you. Pasting a code, or letting the phone autofill one from a text message, drops it straight in. Set the status to turn the slots green, or shake them red on a wrong code.

npm: motion
Wingo UI dependencies: ui-config

Props:
- `length?: number` = 6: How many boxes to render, so a 4 digit code is length={4}. Any count works.
- `size?: "sm" | "md" | "lg"` = "md": Overall scale of the boxes. Maps to 40px (sm, 44px on touch screens), 48px (md), and 56px (lg), and carries the text, caret, and gaps with it. In a container narrower than the row, the boxes shrink evenly and stay square, so 8 slots still fit a 360px phone.
- `type?: "numbers" | "letters" | "both"` = "numbers": Which characters a slot accepts. Anything else is ignored, including on paste.
- `status?: "idle" | "success" | "error"` = "idle": Drives the feedback state. Success traces a green ring around each box in turn, error rings them red and shakes the row once.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Slot corners as a share of the slot, so they shrink with it and match the success ring: square, half, the original 20 / 25 / 29% per size, rounder, or circles.
- `surface?: string` = "": Any CSS color for the slot fill. Empty uses #F4F4F9 light, #262626 dark.
- `textColor?: string` = "": Any CSS color for the characters and the caret. Empty is black on light pages, white on dark ones.
- `successColor?: string` = "#34C759": Any CSS color for the ring drawn around each slot on success.
- `errorColor?: string` = "#FF3B30": Any CSS color for the ring shown on error.
- `mask?: boolean` = false: Hides the characters, like a password field.
- `disabled?: boolean` = false: Blocks input and dims every slot.
- `autoFocus?: boolean` = false: Focuses the first slot on mount.
- `slotLabel?: string` = "": Accessible name template for each slot; {index} and {length} fill in, e.g. "Cifra {index} din {length}". Empty reads "Digit 1 of 6" (or "Character" for letters).
- `value?: string`: The current code. Pass it to control the input yourself; leave it out to let the component track its own state.
- `defaultValue?: string` = "": Starting code when the input is uncontrolled.
- `onChange?: (value: string) => void`: Fires on every edit with the full code so far.
- `onComplete?: (value: string) => void`: Fires once the last slot is filled.
- `className?: string`: Extra classes for the row that wraps the slots.
- `slotClassName?: string`: Extra classes for each slot, for sizing and colors.

```tsx
import { useState } from "react"
import OtpInput, { type OtpStatus } from "@/components/ui/otp-input"

export function Demo() {
  const [status, setStatus] = useState<OtpStatus>("idle")

  return (
    <OtpInput
      length={6}
      size="md"
      status={status}
      onChange={() => setStatus("idle")}
      onComplete={(code) => setStatus(checkCode(code) ? "success" : "error")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/otp-input (Markdown: https://wingo-ui.com/components/otp-input.md)

#### Password Input (`password-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add password-input`

A password field with a caret-safe reveal toggle, a Caps Lock warning and, for sign-up, a strength meter, rules checklist and generator.

Tap the eye and the dots turn into text with the icon turning a quarter over; the caret and any selection stay exactly where they were, and the button stays in the Tab order. With Caps Lock on, a small amber warning slides in under the box and leaves when you release it or leave the field. With strength on, four bars fill left to right as you type, red, then amber, then green, with the verdict next to them, and a checklist opens on focus with each rule drawing its check the moment it is met; it stays open while there is text, so the submit button never jumps away under your finger. The wand fills a random 16-character password, reveals it until you leave the field and scores it Strong. On a phone both buttons have 44px hit areas, iOS never zooms and the checklist scrolls into view above the keyboard.

npm: motion, lucide-react
Wingo UI dependencies: input, field, motion, use-controllable-state, use-media-query, ui-config

Props:
- `label?: ReactNode` = "": The label above the box, linked with htmlFor.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description, slides in and marks the field invalid.
- `required?: boolean` = false: The red mark after the label and the native required attribute.
- `disabled?: boolean` = false: Dims the field and blocks input and the reveal toggle; the generator hides.
- `invalid?: boolean` = false: The red ring and aria-invalid without a message, when the form shows the error elsewhere.
- `readOnly?: boolean` = false: The password stays selectable and can still be revealed, but cannot change; the generator hides. The demo fills in a sample value.
- `placeholder?: string` = "": Hint text while the field is empty.
- `defaultValue?: string` = "": The starting password while uncontrolled; value and onValueChange control it. The meter scores this first value until the field is focused, so a password manager filling the field never makes it flash.
- `showLabel?: string` = "Show password": The toggle's aria-label and hover title while the password is hidden.
- `hideLabel?: string` = "Hide password": The toggle's aria-label and hover title while the password shows.
- `capsLockLabel?: ReactNode` = "Caps Lock is on": The warning under the box.
- `strengthCaption?: string` = "Password strength": The caption under the meter, left of the verdict, and the prefix screen readers hear.
- `generateLabel?: string` = "Generate a strong password": The wand button's aria-label and hover title.
- `ruleMetLabel?: string` = "met": Read by screen readers after a met rule, visually hidden.
- `ruleUnmetLabel?: string` = "not met": Read by screen readers after a rule that is not met yet, visually hidden.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px like every field (md 44px on touch); the eye and wand buttons follow.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box look, shared with Input.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size; full makes a pill.
- `accent?: string` = "": Any CSS color for the focus ring and the caret. Empty uses the ring token.
- `floatingLabel?: boolean` = false: The label rests inside the box and floats up on focus or when filled, like Input.
- `defaultVisible?: boolean` = false: Starts with the password shown as text. Use visible and onVisibleChange to control it.
- `showToggle?: boolean` = true: The eye button at the end of the box. It is a real button in the Tab order with aria-pressed and aria-controls; switching keeps the caret and selection.
- `strength?: boolean` = false: Turns the field into a sign-up field: the four-bar meter with its verdict, the rules checklist and autoComplete new-password. The verdict is announced politely 500ms after typing stops.
- `showRules?: "focus" | "always" | "never"` = "focus": When strength is on: the checklist opens on focus and stays while there is text (so the button under it never moves on blur), always shows, or never shows.
- `capsLockWarning?: boolean` = true: Reads Caps Lock from the key and pointer events while the field is focused and shows the warning (role status). Hidden on blur; phones never report it.
- `generate?: boolean` = false: A wand button before the eye: fills a random password from crypto.getRandomValues (no 0 O l 1 I, at least one lowercase, uppercase, digit and symbol, no runs), fires onChange like typing, and reveals it until focus leaves the field.
- `generateLength?: number` = 16: Length of a generated password.
- `maxLength?: number` = 0: The native character limit, also applied to typing after a generated password. 0 means no limit.
- `visible?: boolean`: Shown as text, controlled. Without onVisibleChange the toggle does nothing.
- `onVisibleChange?: (visible: boolean) => void`: Fires when the toggle, the generator or the blur after a generated password changes the visibility.
- `rules?: PasswordRule[]`: The checklist, { id, label, test(password) }. Defaults to passwordRules(): at least 8 characters, a lowercase letter, an uppercase letter, a number, a symbol. Build localized ones with passwordRules({ minLength, labels }); the rule with id length also sets the minimum for scorePassword.
- `score?: (password: string) => PasswordScore`: Replaces the scorer, e.g. with zxcvbn loaded by the app. The default scorePassword(password, rules) returns 0 when empty, short or common (password, parola, qwerty...), adds one per met rule beyond length (max 3) and one for 12+ characters, and takes one away for repeats or runs like 1234. A guide, not a guarantee.
- `strengthLabels?: [string, string, string, string, string]` = "[\"Too weak\", \"Weak\", \"Fair\", \"Good\", \"Strong\"]": The verdict per score, default ["Too weak", "Weak", "Fair", "Good", "Strong"].
- `onGenerate?: (password: string) => void`: Called with the generated password, e.g. to offer a copy button.
- `showIcon?: ReactNode`: The toggle icon while hidden (Eye by default).
- `hideIcon?: ReactNode`: The toggle icon while shown (EyeOff by default).
- `generateIcon?: ReactNode`: The generator icon (WandSparkles by default).
- `autoComplete?: string` = "\"current-password\"": Defaults to "current-password", or "new-password" with strength or generate, so password managers save and suggest correctly. A manager's own icon may sit over the end of the box; there is room for it before the toggle.
- `enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send"` = "\"go\"": The label of the phone keyboard's return key: "go" for a login field, "next" with strength (a sign-up form usually continues).
- `value?: string`: The password, controlled, with onValueChange. Every other Input prop works too: name, onBlur, prefix, leftIcon, fieldProps... (not clearable, loading, showCount or rightIcon: the eye and wand own the end of the box).
- `onValueChange?: (value: string) => void`: Fires with the new password on every edit, including a generated one.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event, untouched. A generated password fires it too, like typing.
- `prefix?: ReactNode`: Text or an element before the input, in the muted addon look.
- `suffix?: ReactNode`: Text or an element after the input, placed before the wand and eye buttons.
- `leftIcon?: ReactNode`: A leading icon such as a lock; unsized svgs follow the size (14 / 16 / 18px).
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper, e.g. labelAction: <a href="/reset">Forgot password?</a>.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native input.
- `classNames?: Partial<Record<InputSlot | "root" | "toggle" | "generate" | "strength" | "meter" | "segment" | "strengthLabel" | "rules" | "rule" | "capsLock", string>>`: Extra classes for the inner parts: the Input keys (box, input, label...) plus the password parts.
- `className?: string`: Classes for the root wrapper around the field, the warning, the meter and the checklist.

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

const rules = passwordRules({
  minLength: 10,
  labels: { length: (n) => "At least " + n + " characters", lower: "One lowercase letter", upper: "One uppercase letter", number: "One digit", symbol: "One symbol" },
})

export function SignUp() {
  return (
    <form className="flex flex-col gap-4">
      <PasswordInput
        name="password"
        label="Password"
        strength
        rules={rules}
        strengthLabels={["Too weak", "Weak", "Okay", "Good", "Strong"]}
        generate
        required
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/password-input (Markdown: https://wingo-ui.com/components/password-input.md)

#### Phone Input (`phone-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add phone-input`

A phone number field with a searchable country picker, formatting as you type, validation and one clean E.164 value out.

Type the number and it formats itself the way the country writes it (712 345 678 for Romania, 69 123 456 for Moldova, 201 555 0123 for the US), with the caret kept after the digit you typed; Backspace on a space deletes the digit before it. A leading trunk 0 is dropped (0712 345 678 becomes 712 345 678), and digits beyond the country's longest number are refused. Type or paste a number that starts with + or 00 and the calling code picks the country: +373 69… switches the flag to Moldova, 0040 712… to Romania; browser autofill of a full number works the same way. The flag button (flag, +40 and a chevron) opens the country list: search by the localized name, the English name, the ISO code or the calling code, suggested countries first. With the keyboard: Tab reaches the flag button, then the number. On the flag button Enter, Space or ArrowDown opens the list and a letter jumps to the next country starting with it without opening; in the list the search is focused, arrows, Home / End and PageUp / PageDown move, Enter picks and puts focus back in the number, Escape closes and returns to the flag button. With showValidity a green check pops in once the number is valid. On a phone the list is a bottom sheet with search and 48px rows, the field raises the phone keypad, and the flag button keeps a 44px hit area.

npm: libphonenumber-js, motion, lucide-react
Wingo UI dependencies: select, field, use-locale, motion, use-controllable-state, ui-config

Props:
- `defaultCountry?: CountryCode` = "RO": The starting country when the value does not name one. An unknown code falls back to RO.
- `countrySelect?: boolean` = true: false fixes the country: no picker, the calling code shows as a text prefix ("+40"); a pasted "+40 712…" or "0040 712…" still fills in the national digits.
- `placeholder?: string` = "": Empty shows the country's example mobile number from libphonenumber-js (712 034 567 for RO), formatted like the field formats and without the calling code; it follows the country.
- `showValidity?: boolean` = false: A green check pops in (scale 0.8 to 1, snappy spring) while the number is valid, with a visually hidden label.
- `locale?: string` = "": The language of the country names (Intl.DisplayNames) and of the list order, e.g. "en-US" or "de-DE". Empty uses the UIProvider locale, then the nearest LocaleProvider, then the page. English names stay searchable in every locale.
- `label?: ReactNode` = "": Renders the field anatomy around the box, linked with htmlFor. Leave it empty for a bare field (then pass aria-label).
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with the animated error and sets invalid (red ring, aria-invalid on the number input).
- `required?: boolean` = false: The red * after the label and required on the number input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims to 50%, blocks typing and the country list, and keeps the hidden input out of the form.
- `readOnly?: boolean` = false: The number stays visible and selectable, the list never opens, no hover tint.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px boxes (md grows to 44px on touch screens), 16px text on phones so iOS never zooms.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box look, shared with every field.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius per size (the button's scale); the flag button follows it. Ignored by underline.
- `responsive?: boolean` = true: The country list is a bottom sheet with search below 768px; false keeps the popover.
- `defaultOpen?: boolean` = false: Opens the country list on mount. open / onOpenChange control it.
- `value?: string`: The E.164 number ("+40712345678"), controlled. A value for another country switches the country. "" while empty or incomplete.
- `defaultValue?: string` = "": The starting number, uncontrolled: E.164 ("+40712345678", which also picks the country), or national digits for the default country.
- `onValueChange?: (e164: string, details: PhoneDetails) => void`: Fires on every edit: the E.164 number once it is possible, else "" with the details, so a form can say incomplete. PhoneDetails = { country?: CountryCode; national: string; international: string; valid: boolean; possible: boolean }.
- `country?: CountryCode`: The selected country, controlled. Pair it with onCountryChange.
- `onCountryChange?: (country: CountryCode) => void`: Fires when the list, the typeahead on the flag button or a typed calling code changes the country.
- `countries?: CountryCode[]`: Limits the list (and the countries a typed calling code may pick). All 245 by default, virtualized.
- `preferredCountries?: CountryCode[]` = "[\"RO\", \"MD\"]": Shown first under the Suggested heading; an empty array drops the headings.
- `renderFlag?: (country: CountryCode) => ReactNode`: Custom flags (SVGs from your app) in the button and the list. By default the emoji flag; on Windows, which has no flag emoji, the ISO code in a small chip after mount.
- `labels?: Partial<PhoneInputLabels>`: Every visible and spoken string: the flag button's name ("Country: Romania +40") and the sheet title, the search placeholder, the empty text, the group headings, the example format read after the field and the validity text.
- `name?: string` = "": Renders a hidden input with this name and the E.164 value, so FormData gets the clean number (disabled fields are not submitted). The readout under the demo shows the pair.
- `id?: string`: The number input's id (useId() by default; the flag button gets `${id}-country`).
- `container?: HTMLElement | null`: Where the country list is portaled; document.body by default.
- `open?: boolean`: The country list's open state, controlled; with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Fires when the country list opens or closes.
- `autoComplete?: string` = "tel-national": On the number input. A full number autofilled with tel ("+40 712…") is detected like a paste.
- `inputMode?: "tel" | "numeric" | "decimal" | "text" | "email" | "url" | "search" | "none"` = "tel": The keypad on touch screens: tel has + and the digits; numeric only digits.
- `enterKeyHint?: "next" | "done" | "go" | "send" | "search" | "enter" | "previous"` = "next": The label of the on-screen Enter key; use done on the last field of a form.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "country" | "flag" | "code" | "chevron" | "input" | "validity" | "content", string>>`: Extra classes for the field parts, the box, the flag button and its parts, the number input, the check and the list.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The number input. Every other native prop lands on it too: onBlur, autoComplete ("tel-national"), inputMode ("tel"), enterKeyHint ("next"), aria-*. The input holds formatted national digits, so with react-hook-form use Controller (value / onValueChange). The default metadata is libphonenumber-js min (lengths and leading digits); import from libphonenumber-js/max in your copy for stricter number-type checks at a larger size.

```tsx
import { useState } from "react"
import { PhoneInput, type PhoneDetails } from "@/components/ui/phone-input"

export function ContactForm() {
  const [phone, setPhone] = useState("")
  const [details, setDetails] = useState<PhoneDetails | null>(null)
  const [touched, setTouched] = useState(false)

  return (
    <form className="flex flex-col gap-4">
      <PhoneInput
        name="phone"
        label="Phone"
        description="Only interested buyers will call you."
        defaultCountry="US"
        preferredCountries={["US", "CA", "GB"]}
        value={phone}
        onValueChange={(e164, info) => {
          setPhone(e164)
          setDetails(info)
        }}
        onBlur={() => setTouched(true)}
        error={touched && details?.national && !details.valid ? "The phone number is not valid" : undefined}
        showValidity
        required
      />
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/phone-input (Markdown: https://wingo-ui.com/components/phone-input.md)

#### Radio Group (`radio-group`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add radio-group`

Pick exactly one of a few visible options: rows with a dot that springs in, or cards with icons, prices and a selection ring that slides.

Click or tap anywhere on a row or card to choose it: the circle fills with the tone and the dot springs in, and on cards a ring slides from the old choice to the new one while the icon tile takes the tone. The circle dips under your finger while you press, and a card dips slightly as a whole. Tab lands on the chosen option (or the first one when nothing is chosen), the arrow keys move and choose at once (Up and Left go back, Down and Right go forward, mirrored in right-to-left layouts, wrapping at the ends unless loop is off), Space chooses the focused option, and Tab leaves the group. Clicking the group's label focuses the chosen option. On a phone every row grows to 44px so each one is a full finger target, grids drop columns once a cell would get too narrow (a phone always gets one), cards stack their icon above the text when they are narrow, and horizontal rows wrap instead of scrolling. A read-only group keeps its choice visible and focusable but ignores changes; a disabled option dims and is skipped by the arrow keys. With reduced motion the dot and the ring jump instead of springing.

npm: @radix-ui/react-radio-group, motion
Wingo UI dependencies: field, use-controllable-state, motion, tones, ui-config

Props:
- `options?: RadioOption[]` = "[]": The choices: { value, label, description?, icon?, badge?, disabled? }. badge is a trailing price or tag on the label's line. For layouts an array cannot express, compose RadioGroupRoot (every prop here except options) with RadioGroupItem children (value, label, description, icon, badge, disabled, classNames, and children rendered under the description; other props and ref go on the <label> row or card).
- `value?: string`: The chosen value when controlled. Pair it with onValueChange.
- `onValueChange?: (value: string) => void`: Called with the new value when the person picks an option, by pointer, Space or the arrow keys. Not called while readOnly.
- `label?: ReactNode` = "": The group's label, above the options. It names the radiogroup through aria-labelledby, and clicking it focuses the chosen option. Leave it empty and pass aria-label for a bare group.
- `description?: ReactNode` = "": Helper text under the options, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with an alert icon and the text, slides in and marks the group invalid: empty circles and card borders turn red.
- `required?: boolean` = false: The red mark after the label, aria-required on the group, and required on the hidden form inputs, so a native form will not submit without a choice.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message, for forms that show errors elsewhere.
- `disabled?: boolean` = false: Dims every option and blocks it; a form will not submit its value. Disable one option through its own disabled.
- `readOnly?: boolean` = false: The choice stays visible and focusable, but clicks and arrow keys do not change it (aria-readonly). No hover tint, no press dip.
- `variant?: "default" | "card"` = "default": default: compact rows with the circle beside the text. card: bordered tiles with an icon tile, a description and a trailing price, and one selection ring that slides between cards.
- `size?: "sm" | "md" | "lg"` = "md": Circle 16 / 18 / 20px with a 6 / 7 / 8px dot, label 13 / 14 / 15px, card padding 12 / 16 / 20px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The checked fill, the dot's contrast color and the card ring. neutral is black in light mode and white in dark mode; brand orange is opt-in.
- `color?: string` = "": Any CSS color. Replaces the tone; the dot turns black or white by lightness. Leave empty to use the tone.
- `indicator?: "dot" | "check"` = "dot": What appears in the filled circle: a dot that springs in, or a check mark that draws itself (nice on cards).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Cards only: corners of 0 / 12 / 16 / 24px (full falls back to 24px). The ring follows it.
- `orientation?: "vertical" | "horizontal"` = "vertical": horizontal puts rows side by side and wraps them onto the next line instead of scrolling; cards share the row until they would get narrower than 10rem. Every arrow key works in both, like native radios.
- `columns?: 1 | 2 | 3 | 4` = 1: Up to this many columns of rows or cards. The grid follows the space it has, not the viewport: it drops a column whenever cells would get narrower than 12rem (cards) or 11rem (rows), so a phone always gets one column and a narrow sidebar never squeezes the text.
- `controlPosition?: "auto" | "start" | "end"` = "auto": Where the circle sits: auto is before the text for rows and at the top end of cards. end suits settings lists; start suits cards that read like a checklist.
- `showControl?: boolean` = true: Cards only: false hides the circle and lets the ring and the tinted icon tile show the choice (plan pickers). The radio stays in the accessibility tree.
- `defaultValue?: string` = "": The option chosen on first render while uncontrolled. "" chooses nothing, and the first enabled option is then the tab stop. A value that matches no option also shows nothing chosen. The demo starts on curier while this is empty; try easybox or ridicare.
- `loop?: boolean` = true: The arrow keys wrap from the last option to the first and back. The demo's key hint says which.
- `name?: string` = "": Form field name. Inside a <form> each option renders a hidden native radio with this name, so FormData and native validation work; a form reset returns to defaultValue. The demo prints what the form would submit.
- `id?: string`: The group's id (the radiogroup element). Defaults to useId(); the label and messages derive their ids from it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `classNames?: Partial<Record<"group" | "option" | "body" | "item" | "indicator" | "icon" | "content" | "label" | "description" | "badge" | "ring" | "field" | "fieldLabel" | "fieldDescription" | "error", string>>`: Extra classes for the parts. label and description style each option's text; fieldLabel and fieldDescription the group's own label and hint; group is the radiogroup element, option each row or card, body the inner row of a card (the part that stacks when the card is narrow), item the circle.
- `className?: string`: Classes for the outermost element: the Field wrapper when there is a label, description or error, otherwise the radiogroup. Override the tone vars here, e.g. [--tone:#7C3AED].
- `ref?: RefObject<HTMLDivElement | null> or (node) => void`: The radiogroup element. Every other prop (aria-label, dir, form, data-*) lands there too.

```tsx
import { Package, Store, Truck } from "lucide-react"
import { RadioGroup, type RadioOption } from "@/components/ui/radio-group"

const delivery: RadioOption[] = [
  { value: "courier", label: "Home delivery", description: "FedEx, 1-2 days", icon: <Truck />, badge: "$9.99" },
  { value: "locker", label: "Locker", description: "Pick up any time from 3,000 lockers", icon: <Package />, badge: "$5.99" },
  { value: "pickup", label: "In-store pickup", description: "Austin, 2400 S Congress Ave", icon: <Store />, badge: "Free" },
]

export function DeliveryMethod({ value, onChange }: { value: string; onChange: (value: string) => void }) {
  return (
    <RadioGroup
      name="delivery"
      label="Delivery method"
      variant="card"
      options={delivery}
      value={value}
      onValueChange={onChange}
      required
    />
  )
}

// custom content: compose the parts
import { RadioGroupRoot, RadioGroupItem } from "@/components/ui/radio-group"

export function PlanPicker() {
  return (
    <RadioGroupRoot label="Plan" variant="card" columns={2} defaultValue="pro">
      <RadioGroupItem value="free" label="Free" badge="$0" />
      <RadioGroupItem value="pro" label="Pro" badge="$9/mo">
        <ul className="mt-2 text-[13px] text-muted-foreground">
          <li>Unlimited listings</li>
        </ul>
      </RadioGroupItem>
    </RadioGroupRoot>
  )
}
```

Docs: https://wingo-ui.com/components/radio-group (Markdown: https://wingo-ui.com/components/radio-group.md)

#### Rating (`rating`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add rating`

Rate or show a rating with stars or any icon: half values, a hover preview, a label per value and a fill that pops.

Click or tap an icon to rate; with allowHalf the left half of an icon gives a half value. With a mouse the icons preview the rating under the pointer (the part beyond the chosen value dimmed) and the label follows it. Clicking the chosen value again clears it when clearable. On a phone, drag a finger across the icons to scrub and lift it to commit; every icon is a 44px target and the drag never scrolls the page. On commit the icons fill with a small staggered pop, and lowering fades the removed fill. The group is one slider: Tab to it for a focus ring, then Right / Up adds one (a half with allowHalf), Left / Down removes one (mirrored in right-to-left pages), PageUp / PageDown move a whole icon, Home clears (or goes to the lowest value), End jumps to the top, digits 1 to 9 pick a value directly, and 0, Backspace or Delete clear. Read-only ratings are a picture with a spoken summary ("Rated 4.8 of 5"). In the playground Send rating checks that a rating was chosen, pretends to send it and thanks you.

npm: motion, lucide-react
Wingo UI dependencies: field, use-controllable-state, use-locale, motion, number-format, tones, ui-config

Props:
- `label?: ReactNode` = "": The field label, rendered as a span that names the icon group (a click on it focuses the group).
- `description?: ReactNode` = "": Helper text under the icons, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error, tints the empty icons red and sets aria-invalid.
- `required?: boolean` = false: The required mark after the label. The check itself belongs to your form (the playground blocks sending without a rating).
- `invalid?: boolean` = false: The invalid look (red-tinted empty icons) and aria-invalid without a message.
- `disabled?: boolean` = false: Dims to 50%, leaves the tab order and ignores pointer and keys. A disabled FieldGroup disables it too.
- `readOnly?: boolean` = false: Display only: role="img" with a spoken summary, no pointer or keys, and fractions like 4.3 drawn proportionally. The number keeps one decimal ("4,8").
- `max?: number` = 5: How many icons. Below 1 falls back to 5. The playground keeps its Romanian labels only at 5.
- `allowHalf?: boolean` = false: Half values: the left half of an icon (right half in RTL) gives x.5, and the arrow keys move by 0.5. Ignored with icons.
- `clearable?: boolean` = true: Choosing the current value again clears it, a scrub past the first icon clears, and 0 / Backspace / Delete clear from the keyboard. false keeps at least one step.
- `size?: "sm" | "md" | "lg"` = "md": Icons 16 / 24 / 32px with 2 / 4 / 6px between them, and the value and label type. On touch screens every icon is a 44px target.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill. neutral is black in light mode and white in dark mode; warning gives the classic amber stars.
- `color?: string` = "": Any CSS color for the fill; replaces the tone.
- `showLabel?: boolean` = false: The hovered or chosen value's label beside the icons (Very poor … Excellent). Needs labels.
- `emptyLabel?: ReactNode` = "": What the label slot says while nothing is chosen, with showLabel. Empty shows nothing.
- `showValue?: boolean` = false: The number beside the icons, through Intl: "4.5" in en-US, "4,5" in de-DE. It follows the hover preview.
- `locale?: string` = "": Locale for the number. Empty uses the UIProvider locale, then the nearest LocaleProvider, then the page's language (en-US on the server). The demo passes en-US.
- `name?: string` = "": Form field name: a hidden input submits the value ("0" when empty, "4.5" with halves), and a form reset puts defaultValue back.
- `icon?: ReactNode` = "<Star />": The icon repeated max times: any lucide icon (Heart, ThumbsUp). The fill layer paints it with fill-current.
- `icons?: ReactNode[]`: One icon per value, e.g. Frown, Meh, Smile, Laugh. Only the chosen (or hovered) icon lights up, in the tone with a soft tone fill; no halves. A list shorter than max repeats its last icon.
- `labels?: string[]`: One label per value (labels[0] is 1). Read as aria-valuetext and shown with showLabel.
- `getValueText?: (value: number, max: number) => string` = "(v, m) => `${v} of ${m}`": What screen readers hear for a value without a label (and for halves).
- `getReadOnlyLabel?: (value: number, max: number) => string` = "(v, m) => `Rated ${v} of ${m}`": The spoken name of a read-only rating; the value is rounded to one decimal.
- `value?: number`: The controlled rating; 0 = none. A value between steps (4.3) is drawn proportionally and snaps on the next interaction.
- `defaultValue?: number` = 0: The uncontrolled start; a form reset returns to it. The playground starts its rating here.
- `onValueChange?: (value: number) => void`: When a rating is committed: on release of a tap or scrub, and on every key press.
- `id?: string`: The group's id. Defaults to useId(); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `classNames?: Partial<Record<"box" | "root" | "item" | "icon" | "fill" | "empty" | "value" | "label" | "field" | "description" | "error", string>>`: Extra classes for the inner parts: box (icons, number and label), root (the slider group), item (each cell), icon (the icon box), fill and empty (the two layers), value, label and the field parts.
- `className?: string`: Classes for the outermost element: the Field root when the rating has a label, description or error, else the box.

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

const LABELS = ["Very poor", "Poor", "Okay", "Good", "Excellent"]

export function SellerReview() {
  const [rating, setRating] = useState(0)
  return (
    <div className="flex flex-col gap-6">
      <Rating
        label="How was your experience?"
        name="rating"
        value={rating}
        onValueChange={setRating}
        labels={LABELS}
        showLabel
        emptyLabel="Tap a star"
        required
      />
      <Rating readOnly value={4.8} tone="warning" size="sm" showValue />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/rating (Markdown: https://wingo-ui.com/components/rating.md)

#### Search Input (`search-input`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add search-input`

The search field for lists and pages: debounced search, a focus shortcut, a spinner, a results count, recent searches and suggestions.

Press / anywhere on the page (not while typing in another field) and the search field takes focus with its text selected; the / hint at the end of the empty box shows which key it is and hides while the field is focused. Type and the search runs once you pause (300 ms by default): the magnifier crossfades into a spinner while the page loads, and a muted count like 318 results appears at the end and is read out politely. Enter searches at once, saves the query to the recent searches and closes the dropdown. On focus a dropdown opens under the field with Recent searches (each with an × to forget it and a Clear button for all of them) and suggestions, both filtered by what you type with the matches in bold. Arrow Down moves into it while the caret stays in the field, Enter picks the highlighted row, Delete or Shift+Backspace removes a highlighted recent search, and Escape first closes the dropdown, then clears the text, then leaves the field. The × in the box clears and searches at once. With expandable the field starts as a square icon button, grows with a spring on click, tap or the shortcut and folds back when you leave it empty. On a phone the keyboard shows a Search key, the text is 16px so iOS never zooms, the dropdown stays under the field above the keyboard with 44px rows, no key hint is shown, and picking a search or pressing Search lowers the keyboard so the results show.

npm: motion, lucide-react
Wingo UI dependencies: field, input, kbd, listbox, spinner, use-controllable-state, use-debounce, use-media-query, use-shortcut, motion, text-match, ui-config

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the box: the label above it, linked with htmlFor. Without it the input is named by aria-label, else the placeholder.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid.
- `required?: boolean` = false: The red mark after the label and the native required attribute.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, blocks input and unbinds the shortcut.
- `readOnly?: boolean` = false: The query stays visible and selectable but cannot change; no clear button and no dropdown.
- `placeholder?: string` = "Search": Hint text while the field is empty; also the accessible name when there is no label or aria-label. The demo passes Search listings.
- `clearLabel?: string` = "Clear": The clear button's accessible name and hover title.
- `loadingLabel?: string` = "Searching": What screen readers hear for the spinner.
- `defaultValue?: string` = "": The starting query while uncontrolled. A form reset returns to it; pass value and onValueChange to control it instead.
- `name?: string` = "": The form field name on the native input, so a GET form submits ?q=… like a plain search box.
- `labels?: Partial<{ recent: string; suggestions: string; clearRecent: string; removeRecent: string }>`: The dropdown copy, merged over { recent: "Recent searches", suggestions: "Suggestions", clearRecent: "Clear", removeRecent: "Remove" }. suggestions heads loose suggestion options and names the list for screen readers.
- `resultLabel?: (count: number) => string` = "defaultResultLabel": Formats the count shown and announced; the default gives "1 result" / "318 results". The demo writes Romanian plurals (318 rezultate, 20 de rezultate).
- `icon?: ReactNode`: Replaces the leading magnifier; it still crossfades with the spinner while loading.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px with 13 / 14 / 15px text (16px on phones); md grows to 44px on touch. The key hint and the count scale along.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box look, shared with every input: a filled well, a bordered box, a bottom line, or no fill until hover (toolbars).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape scaled with the size like the button's; full makes the classic pill search bar.
- `accent?: string` = "": Any CSS color for the focus ring, the outline and underline focus color and the caret. Empty uses the ring token.
- `loading?: boolean` = false: The magnifier crossfades into a spinner and the input gets aria-busy; typing stays possible. Set it while your request runs.
- `resultCount?: number`: Shown muted at the end of the box (dimmed while loading) and announced in a polite live region once it settles. Leave it undefined to hide it; 0 shows "0 results". Data from your search, so it has no playground control: the demo feeds it the live count.
- `value?: string`: The query, controlled; pair it with onValueChange.
- `onValueChange?: (value: string) => void`: Fires on every keystroke, a clear and a picked suggestion.
- `onSearch?: (query: string) => void`: Fires with the trimmed query after the debounce, at once on Enter and on a picked row, and with "" at once on clear. The same query twice in a row only fires again on Enter.
- `debounce?: number` = 300: Milliseconds of quiet typing before onSearch runs. 0 searches on every keystroke.
- `minLength?: number` = 0: Shorter queries do not call onSearch (the empty query after a clear always does), so a single letter never hits the server.
- `clearable?: boolean` = true: An × pops in while there is text; it clears, searches at once and keeps focus in the field. Escape clears either way.
- `shortcut?: string` = "/": Focuses the field and selects its text from anywhere, in mod+k notation ("/", "mod+k", "shift+mod+f"). Keys without a modifier are ignored while you type in another field. Empty binds nothing. mod+k usually belongs to a command menu; give each search on a page its own key.
- `showShortcut?: boolean` = true: The key hint at the end of the box while it is empty and not focused (⌘K on Apple devices, Ctrl+K elsewhere). Never shown on touch screens.
- `selectOnFocus?: boolean` = false: Selects the whole query when the field takes focus by click, tap or Tab, so typing replaces it. The shortcut always selects it.
- `maxLength?: number` = 0: The native character limit for the query. 0 means no limit.
- `dropdown?: boolean` = true: Shows recent searches and suggestions under the field while it is focused (in the page flow, not a sheet, so it stays above a phone keyboard). With it the input is a combobox driven by arrow keys; without it a plain searchbox.
- `recentStorageKey?: string` = "": Keeps recent searches in localStorage under this key, read after mount. Blocked storage (private mode) falls back to memory. Empty keeps them in memory for the page's life. The demo uses its own key with three seeded searches.
- `maxRecent?: number` = 5: How many recent searches are kept; a repeat moves to the top instead of doubling (compared without case or diacritics).
- `recent?: string[]`: Controlled recent searches, newest first; pair it with onRecentChange (then storage is left to you).
- `onRecentChange?: (recent: string[]) => void`: Fires when a search is saved, removed, cleared, or restored from storage after mount.
- `suggestions?: ListboxItems (SearchSuggestion | SearchSuggestionGroup)[]`: Static quick picks (categories, popular searches) under the recents, filtered by the query with matches in bold. Loose options go under labels.suggestions; groups keep their label. Options take icon, description, badge (a count) and keywords.
- `onSuggestionSelect?: (option: SearchSuggestion) => void`: Called with a picked suggestion (not a recent search). Without it the option's text fills the field, searches and is saved as a recent search.
- `expandable?: boolean` = false: Starts as a square icon button the size of the box; a click, tap or the shortcut grows it to expandedWidth with a spring (the magnifier glides into place and the text fades in), and it folds back when it loses focus while empty.
- `expandedWidth?: number` = 280: Width in px once expanded, capped by the container. Only with expandable.
- `onChange?: (event: ChangeEvent<HTMLInputElement>) => void`: The native change event, untouched; a clear fires it too, like a keystroke.
- `onClear?: () => void`: Called after the × or Escape emptied the field (onSearch has already run with ""). Focus stays in the input.
- `prefix?: ReactNode`: Text or an element before the query, after the magnifier: a scope like "in Cars:" or a small select. Passed to Input.
- `rightIcon?: ReactNode`: A trailing icon after the clear button, e.g. a filter or microphone glyph. Passed to Input.
- `clearIcon?: ReactNode`: Replaces the clear button's icon (a 16px X).
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The native input's id. Defaults to useId(); inside a <Field> the Field's id wins.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The native input. Every other native prop lands there too: autoFocus, onBlur, onKeyDown (runs first; preventDefault skips the built-in keys), aria-*, data-*; onClear runs after a clear.
- `classNames?: Partial<Record<InputSlot | "root" | "icon" | "shortcut" | "count" | "dropdown" | "list" | "option" | "group" | "recentRemove" | "clearRecent" | "expand", string>>`: Extra classes for the inner parts: the Input parts (box, input, clear…), the icon stack, the key hint, the count, the dropdown and its list, rows and group labels, the recent × and Clear buttons, the expand button.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description or error, else the search root.

```tsx
import { useState } from "react"
import { Building2, Car, Laptop } from "lucide-react"
import { SearchInput } from "@/components/ui/search-input"

export function ListingsSearch() {
  const [loading, setLoading] = useState(false)
  const [total, setTotal] = useState<number>()

  return (
    <SearchInput
      placeholder="Search listings"
      recentStorageKey="recent-listings"
      suggestions={[
        {
          label: "Categories",
          items: [
            { value: "real-estate", label: "Real estate", icon: <Building2 /> },
            { value: "cars", label: "Cars", icon: <Car /> },
            { value: "electronics", label: "Electronics", icon: <Laptop /> },
          ],
        },
      ]}
      loading={loading}
      resultCount={total}
      resultLabel={(n) => (n === 1 ? "1 listing" : `${n} listings`)}
      onSearch={async (query) => {
        if (!query) return setTotal(undefined)
        setLoading(true)
        const response = await fetch(`/api/listings?q=${encodeURIComponent(query)}`)
        const { total } = (await response.json()) as { total: number }
        setTotal(total)
        setLoading(false)
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/search-input (Markdown: https://wingo-ui.com/components/search-input.md)

#### Segmented Control (`segmented-control`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add segmented-control`

The iOS segmented control: pick one of a few options on a raised thumb that slides, and on touch drags along with your finger.

Click or tap an option and the raised thumb glides over to it on a quick spring; the hairlines next to it fade away. Press the thumb and it dips a little; keep holding and slide sideways to drag it across the options, the value follows the finger and settles where you let go. A vertical swipe still scrolls the page. With the keyboard the control is one tab stop: Left and Right (Up and Down too) move and select, Home and End jump to the ends, and disabled options are skipped. Icon-only options show their name in a tooltip on hover and focus, or on a long press on touch. On a phone the medium size is 44px tall and fullWidth shares the width between options. With dir set to rtl the arrows and the drag mirror.

npm: @radix-ui/react-radio-group, motion
Wingo UI dependencies: badge, tooltip, motion, tones, use-controllable-state, ui-config

Props:
- `options: SegmentedControlOption[]`: The options: { value, label?, icon?, disabled?, badge?, tooltip? }. 2 to 5 read best; more still fit with truncated labels (use tabs then). A number badge renders a small count that hides at 0.
- `value?: string`: The selected option, when you control it. A value that is not in options shows no thumb.
- `defaultValue?: string` = "": The option selected on the first render when uncontrolled. Empty, or a value that is not in options, starts on the first enabled option.
- `onValueChange?: (value: string) => void`: Called with the new value on click, arrow keys, Home / End and while dragging the thumb.
- `size?: "sm" | "md" | "lg"` = "md": Track height 32 / 40 / 48px with matching type and icon size; options fill it inside a 2px padding. On touch screens md grows to 44px and sm keeps its look with a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the track, scaled with the size like the button's. The thumb is 2px rounder-in so the gap stays even.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The thumb's color. neutral is a raised white surface (a lifted gray in dark mode) like iOS; the other tones fill the thumb and turn its label to the tone's foreground.
- `color?: string` = "": Any CSS color for the thumb. Replaces the tone; the label on it turns black or white by lightness. Leave empty to use the tone.
- `dividers?: boolean` = true: Hairlines between unselected neighbours. The ones touching the thumb fade out, like iOS.
- `iconOnly?: boolean` = false: Shows only the icons. Each label becomes the option's aria-label and its tooltip, so the control stays readable.
- `fullWidth?: boolean` = false: Stretches the track to its container and shares the width between options. The usual layout on a phone.
- `draggable?: boolean` = true: Press the thumb and slide sideways to change the value, with touch or a mouse. Vertical swipes still scroll the page.
- `loop?: boolean` = true: Arrow keys wrap from the last option to the first and back. Off, they stop at the ends.
- `disabled?: boolean` = false: Dims the whole control and blocks it. Disable single options with option.disabled.
- `aria-label?: string` = "": The group's name for screen readers. Required when no visible label names the control.
- `name?: string` = "": Form field name. Inside a <form> the selected value is submitted like a radio group.
- `dir?: "ltr" | "rtl"` = "ltr": Reading direction; rtl mirrors the layout, the arrow keys and the drag. Left out, it follows a Radix DirectionProvider, else ltr.
- `classNames?: Partial<Record<"item" | "thumb" | "icon" | "label" | "badge" | "divider", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the track, merged last.

```tsx
import { useState } from "react"
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control"

const periods: SegmentedControlOption[] = [
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export function SalesPeriod() {
  const [period, setPeriod] = useState("week")
  return (
    <SegmentedControl
      aria-label="Period"
      options={periods}
      value={period}
      onValueChange={setPeriod}
      fullWidth
    />
  )
}
```

Docs: https://wingo-ui.com/components/segmented-control (Markdown: https://wingo-ui.com/components/segmented-control.md)

#### Select (`select`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add select`

A custom select with search, groups, icons, thousands of virtualized rows and a hidden native select for forms.

Click the field (or tap it) to open the list under it, growing out of the field; click an option to pick it, a check draws itself next to it and the list closes. Clicking the field again, clicking outside, Escape or Tab closes it without changing anything. Above 8 options (or with search="always") a search row sits on top and takes focus: typing filters as you go, case and diacritics never matter ("canon" finds Cañon City, state codes like NY work as keywords), matched letters turn bold and groups without matches disappear. Keyboard: Tab reaches the field and a click on its label only focuses it. While closed, Enter, Space, ArrowDown or ArrowUp open it on the chosen option (ArrowUp on the last one when nothing is chosen), Home and End open it on the first and last option, and typing letters picks the next option that starts with them without opening, like a native select (the same letter again cycles). While open, ArrowDown and ArrowUp move and wrap, PageUp and PageDown jump a screen, Home and End go to the ends, Enter picks and closes, Escape or Alt+ArrowUp close and keep focus on the field. With clearable an x appears while a value is set; it clears it and focus goes back to the field. With loading a spinner replaces the chevron and the list shows a loading row. Lists above the virtual threshold render only the rows in view, so thousands of cities scroll at 60fps. On a phone the field opens a bottom sheet titled with the label, with 48px rows (a tap picks and closes), the chosen row scrolled into view, and the search row under the title (it waits for a tap so the keyboard does not cover the list, unless search is always). With name, a hidden native select submits the value, blocks an empty required field and lets browser autofill fill the state. With reduced motion the list fades instead of scaling and the check appears without drawing.

npm: @radix-ui/react-popover, @radix-ui/react-slot, motion, lucide-react
Wingo UI dependencies: listbox, field, drawer, spinner, text-match, motion, use-media-query, use-controllable-state, ui-config

Props:
- `options: SelectItems`: Options and groups: { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? } or { label, items }. keywords add search terms, textValue names a non-text label.
- `value?: string`: The chosen option, controlled ("" is nothing). A value not among the options shows as text and highlights nothing.
- `defaultValue?: string` = "": The starting value while uncontrolled. A form reset returns to it.
- `onValueChange?: (value: string) => void`: Called with the new value after a pick, a typeahead jump, a clear or browser autofill.
- `label?: ReactNode` = "": The field label. A click focuses the trigger (never opens it); plain text also titles the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid.
- `required?: boolean` = false: The red mark after the label, aria-required on the trigger and required on the hidden native select.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, never opens and is not submitted.
- `readOnly?: boolean` = false: The value stays visible and the field focusable, but it never opens, typeahead does nothing and there is no clear button.
- `placeholder?: string` = "Select an option": Shown in the trigger while nothing is chosen.
- `search?: "auto" | "always" | "never"` = "auto": The search row on top of the list: auto shows it above 8 options.
- `searchPlaceholder?: string` = "Search…": The search row's placeholder.
- `emptyText?: string` = "No results": Shown when the search matches nothing (or there are no options).
- `clearable?: boolean` = false: An x in the trigger while a value is set; it clears the value and focus returns to the trigger.
- `clearLabel?: string` = "Clear": The clear button's accessible name and tooltip.
- `loading?: boolean` = false: Options are on their way: a spinner replaces the chevron and the list shows a loading row until options arrive.
- `loadingText?: string` = "Loading…": The loading row's text and the spinner's accessible name.
- `leftIcon?: ReactNode`: A leading icon, shown while the chosen option has no icon of its own (or showSelectedIcon is off).
- `showSelectedIcon?: boolean` = true: The chosen option's icon (a flag, a swatch, a plate code) in the trigger.
- `renderValue?: (option: SelectOption) => ReactNode`: Custom trigger content for the chosen option; the icon and the placeholder stay.
- `highlightMatches?: boolean` = true: Bold matched letters while searching.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px (md grows to 44px on touch), 16px text on phones.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field look, the same as every other field.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius, scaled per size like the button; ignored by underline.
- `name?: string` = "": Renders a hidden native select with this name, so FormData, required validation, form reset and autofill work.
- `autoComplete?: string` = "": For the hidden native select, so browser autofill can fill it ("address-level1" for a county).
- `id?: string`: The trigger's id (useId() by default); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `defaultOpen?: boolean` = false: Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the list is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the list opens or closes.
- `responsive?: boolean` = true: A bottom sheet with 48px rows below 768px instead of the popover.
- `sheetTitle?: string` = "": The phone sheet's title. Empty uses the label's text, else "Select an option".
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the list opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the list lines up with the field.
- `contentWidth?: "trigger" | "auto" | number` = "trigger": The list's width: the field's, its content's (at least the field's), or px.
- `maxHeight?: number` = 360: The list's maximum height in px, capped by the room on screen.
- `virtualThreshold?: number` = 100: Above this many visible options only the rows in view render.
- `renderOption?: (option, state: { selected, highlighted, disabled, ranges }) => ReactNode`: Replaces a row's content; the row element, its aria and its classes stay.
- `container?: HTMLElement | null`: Where the list or the sheet is portaled (document.body by default).
- `labels?: Partial<{ results: (count: number) => string; clearSearch: string; retry: string }>`: Screen reader and search strings: the result count announced after a search ("12 results"), the search clear button.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "trigger" | "value" | "placeholder" | "icon" | "chevron" | "clear" | "content" | "search" | "list" | "item" | "group" | "empty", string>>`: Extra classes for the inner parts. box is the field box, trigger the button inside it, content the popover (or the sheet).
- `className?: string`: Merged onto the Field root when there is a label, description or error, otherwise onto the box.
- `ref?: RefObject<HTMLButtonElement | null> or (node) => void`: The trigger button; other props (onBlur, aria-*, data-*, form) go there too.

Parts:
- `SelectRoot` (component): Owns the listbox engine and the open state and renders no DOM. Reads flags and ids from an enclosing Field. Props: { options, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, search, responsive, loading, virtualThreshold, filter, fuzzy, disabled, readOnly, required, invalid, size, id, name, autoComplete, form, children }.
- `SelectTrigger` (component): The field box with the trigger button, clear button and chevron (and the hidden native select). asChild turns your own element into the trigger (a ghost sort button, a flag button). Props: { asChild, variant, radius, size, clearable, clearLabel, leftIcon, showSelectedIcon, loadingText, classNames, ...button }.
- `SelectValue` (component): The chosen option's label (or renderValue), else the placeholder. Props: { placeholder, renderValue, placeholderClassName, ...span }.
- `SelectAnchor` (component): What the list aligns to when the trigger is small, e.g. the whole phone field around a flag button. Props: Slot props.
- `SelectContent` (component): The popover list on desktop, the bottom sheet on phones. Props: { contentWidth, maxHeight, side, align, sideOffset, container, sheetTitle, searchPlaceholder, emptyText, loadingText, highlightMatches, renderOption, labels, className, classNames }.

```tsx
import { useState } from "react"
import { MapPin } from "lucide-react"
import { Select, type SelectOption } from "@/components/ui/select"

const STATES: SelectOption[] = [
  { value: "CA", label: "California", keywords: ["CA", "Los Angeles"] },
  { value: "NY", label: "New York", keywords: ["NY", "New York City"] },
  { value: "OR", label: "Oregon", keywords: ["OR", "Portland"] },
  { value: "TX", label: "Texas", keywords: ["TX", "Austin"] },
]

export function ShippingState() {
  const [state, setState] = useState("")
  return (
    <Select
      label="State"
      placeholder="Choose the state"
      searchPlaceholder="Search a state or its code…"
      emptyText="No state found"
      options={STATES}
      value={state}
      onValueChange={setState}
      leftIcon={<MapPin />}
      clearable
      required
      name="state"
      autoComplete="address-level1"
    />
  )
}
```

Docs: https://wingo-ui.com/components/select (Markdown: https://wingo-ui.com/components/select.md)

#### Signature Pad (`signature-pad`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add signature-pad`

Sign with a finger, a pen or a mouse, with ink that thins with speed like a real pen, or type your name; exports PNG or SVG.

Draw on the dashed area with a finger, a stylus or the mouse: the ink follows the pointer at full frame rate, gets thinner when you move fast and thicker when you slow down, and a tap leaves a dot. The page still scrolls when you swipe outside the area. The placeholder fades away with the first stroke and a small frosted toolbar fades in at the top corner with Undo (removes the last stroke) and Clear (removes everything); on touch screens each is a 44px target and long press shows its name. Tab reaches the Draw / Type switch first (arrows move between the two), then the drawing area: there mod+z undoes the last stroke and Delete or Backspace clears it, and a screen reader hears Signature added and Signature cleared. Type switches to a name field: the name appears on the baseline in a handwriting font and shrinks to fit when it is long. The ink is the text color on screen (white in dark mode) and repaints when the theme changes; exports are always dark ink on a transparent background, cropped to the signature. Rotating a phone keeps the signature, scaled to fit the new size. Read-only shows the saved signature as an image without the toolbar.

npm: signature_pad, motion, lucide-react
Wingo UI dependencies: field, button, segmented-control, input, tooltip, file-export, use-controllable-state, motion, ui-config

Props:
- `value?: SignatureData | null ({ kind: "drawn"; strokes: SignatureStroke[]; width: number; height: number } | { kind: "typed"; text: string; font: string })`: The controlled signature; null when empty. Drawn strokes are in css px of a width x height box and are scaled by width when shown at another size, so a signature saved on a phone fits a desktop pad.
- `defaultValue?: SignatureData | null`: The uncontrolled start, for example a saved signature. A form reset puts it back.
- `onValueChange?: (value: SignatureData | null) => void`: Fires when a stroke ends (never per point), after undo and clear, when the mode switches and as you type.
- `onEnd?: () => void`: A stroke finished.
- `modes?: SignatureMode[] ("draw" | "type")` = "[\"draw\", \"type\"]": The ways to sign. With one entry the Draw / Type switch is hidden. Type is the keyboard and screen reader path, so keep it unless another one exists.
- `mode?: "draw" | "type"`: The controlled mode. A typed value from outside switches to type, a drawn one to draw.
- `onModeChange?: (mode: SignatureMode) => void`: The person switched between Draw and Type.
- `defaultMode?: "draw" | "type"` = "draw": The uncontrolled starting mode. Each mode keeps its own draft, so switching back restores the strokes or the name.
- `label?: ReactNode` = "": The field label. It names the drawing area (aria-labelledby) and becomes the name field's label in type mode; a click on it focuses the pad.
- `description?: ReactNode` = "": Helper text under the pad, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error, rings the surface red and sets aria-invalid.
- `placeholder?: string` = "Sign here": Centered in the empty surface above the baseline; fades out with the first stroke. Empty shows nothing.
- `variant?: "soft" | "outline"` = "outline": outline is a dashed 2px zone (a signing area reads as a place to act), soft is the filled field look for forms full of soft inputs.
- `size?: "sm" | "md" | "lg"` = "md": The label, the typed name field (32 / 40 / 48px) and the switch and toolbar buttons (lg gets 40px buttons).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The surface corners: none, 12px, 16px (md), 24px; full falls back to 24px. The name field takes the same radius.
- `height?: number` = 200: Surface height in px; the width is the container's. 200 fits a phone, 240 is roomy for couriers.
- `penColor?: string` = "currentColor": The ink on screen. currentColor reads the surface's text color (the foreground token, so white ink in dark mode) and repaints on theme changes; set classNames.surface to a text color class for a themed ink. Strokes drawn with a custom color keep it.
- `exportColor?: string` = "#111111": The ink in every export, whatever the theme: dark ink on a transparent background reads on any document. #1F3A93 is a classic blue pen.
- `minWidth?: number` = 0.8: The thinnest stroke in px, reached on fast movements (signature_pad).
- `maxWidth?: number` = 2.8: The thickest stroke in px, reached on slow movements and dots.
- `velocityFilterWeight?: number` = 0.7: How much the previous speed smooths the next width, 0 to 1 (signature_pad). Higher is calmer ink.
- `guide?: boolean` = true: A dashed baseline at 72% of the height with a × at its start, where people expect to sign.
- `typedFont?: string` = "\"Segoe Script\", \"Snell Roundhand\", \"Brush Script MT\", \"Apple Chancery\", cursive": The typed signature's font stack. System fonts only, nothing downloads; exports use the same stack. Exported as DEFAULT_SIGNATURE_FONT for rendering a typed signature elsewhere (a PDF, an email).
- `showToolbar?: boolean` = true: Undo and Clear at the top corner of the drawing area, shown once there is ink (type mode clears from the name field). Off when your own buttons do it through the api.
- `trimExport?: boolean` = true: Exports crop to the signature's bounds plus 12px of padding. Off keeps the full pad box, the signature where it was drawn.
- `fileName?: string` = "signature": The base name for api.download(), with the local date and time appended ("Signature-2026-09-24-1640.png").
- `setApi?: (api: SignaturePadApi) => void`: Called after mount and whenever the export settings change. SignaturePadApi: clear(), undo(), isEmpty(), getValue(), toBlob({ type, quality, trim, padding = 12, scale = 2, background, color }), toSVG({ trim, padding, background, color }), toDataURL(type = "image/png" | "image/svg+xml"), download({ format = "png" | "svg", ...toBlob options }) resolving with the file name.
- `required?: boolean` = false: The red mark after the label and aria-required. The check itself belongs to your form: isSignatureEmpty(value), exported by the file, is true for null, no strokes or a blank typed name.
- `invalid?: boolean` = false: The invalid look (a red ring and a red dashed border) and aria-invalid without a message.
- `disabled?: boolean` = false: Dims to 50%, the pen stops listening, no toolbar, the switch and the name field are disabled.
- `readOnly?: boolean` = false: Shows the signature as an image (role="img", named by the label and, for a typed one, the name) without the switch, the name field or the toolbar.
- `name?: string` = "": Form field name: a hidden input carries the signature as a PNG data url (export color, trimmed), updated after each stroke. A form reset puts defaultValue back.
- `id?: string`: The drawing area's id (the name field's in type mode). Defaults to useId(); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `labels?: Partial<SignaturePadLabels>`: Every visible and announced string: draw, type, modes, typePlaceholder, undo, clear, canvas, canvasHint, signature, added, undone, cleared, empty, downloaded(fileName). English defaults in DEFAULT_SIGNATURE_PAD_LABELS.
- `classNames?: Partial<Record<"root" | "modes" | "surface" | "canvas" | "typed" | "input" | "preview" | "guide" | "placeholder" | "toolbar" | "button" | "field" | "label" | "description" | "error" | "counter", string>>`: Extra classes for the inner parts. A text color on surface is the on-screen ink when penColor is currentColor.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { SignaturePad, isSignatureEmpty, type SignatureData, type SignaturePadApi } from "@/components/ui/signature-pad"

export function ConfirmDelivery() {
  const [signature, setSignature] = useState<SignatureData | null>(null)
  const [api, setApi] = useState<SignaturePadApi | null>(null)

  const confirm = async () => {
    const png = await api?.toBlob()
    if (png) console.log("Signature", png.size, "bytes")
  }

  return (
    <div className="flex max-w-md flex-col gap-4">
      <SignaturePad
        label="Recipient signature"
        description="Sign with your finger or mouse"
        required
        value={signature}
        onValueChange={setSignature}
        setApi={setApi}
        placeholder="Sign here"
        fileName="Recipient signature"
      />
      <Button size="lg" disabled={isSignatureEmpty(signature)} onClick={confirm}>
        Confirm delivery
      </Button>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/signature-pad (Markdown: https://wingo-ui.com/components/signature-pad.md)

#### Slider (`slider`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add slider`

Pick a number or a range by dragging: any number of thumbs, labelled marks, a value bubble, vertical, tones and finger-sized thumbs.

Drag a thumb or tap anywhere on the track to jump there; the thumb grows a little under the finger and a bubble with the formatted value rides above it, never under the finger. With a mouse the thumb shows a soft halo and its bubble on hover. Tab to a thumb for a focus ring and the bubble, then use the arrow keys for one step, Shift+arrow or PageUp / PageDown for ten, and Home / End for the ends; a range has one tab stop per thumb and they never cross. Tap a mark's label (New, Like new, 25 km) to send the nearest thumb there. On a phone each thumb has a 44px target, the whole row answers to a tap, and a sideways drag never scrolls the page. The playground filter counts the matching listings live and Reset puts both sliders back.

npm: @radix-ui/react-slider, motion
Wingo UI dependencies: ui-config, field, use-controllable-state, use-locale, motion, number-format, tones

Props:
- `label?: ReactNode` = "": The field label. One thumb is labelled by it directly (a click on it focuses the thumb); two or more thumbs are named as a group by it and each thumb gets its own name from thumbLabels.
- `description?: ReactNode` = "": Helper text under the slider, linked to every thumb with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with the animated error, turns the range red and sets aria-invalid on the thumbs.
- `required?: boolean` = false: The required mark after the label. A slider always holds a value, so it only marks the field.
- `invalid?: boolean` = false: The red range and aria-invalid without a message, for forms that show the error elsewhere.
- `disabled?: boolean` = false: Dims to 50%, takes the thumbs out of the tab order and ignores every drag and tap. A disabled FieldGroup disables it too.
- `readOnly?: boolean` = false: Shows the value and keeps the thumbs focusable (so the value can be read), but ignores drags, taps and keys.
- `min?: number` = 0: The lowest value. The playground shows its dollar sample (0 to 5,000, step 50) while min, max and step are all at their defaults.
- `max?: number` = 100: The highest value. A max at or below min falls back to min + step.
- `step?: number` = 1: The distance between values, for drags and arrow keys. A step that does not divide the range still reaches max: a drag past the middle of the last gap lands on it.
- `minStepsBetweenThumbs?: number` = 0: How many steps a range keeps between its thumbs. The playground names the gap under the slider.
- `size?: "sm" | "md" | "lg"` = "md": Track 4 / 6 / 8px, thumb 16 / 20 / 24px, and the value label's type. Every thumb gets a 44px hit area on touch screens.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The range fill and the hover halo. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the range; replaces the tone. Marks inside the range pick a readable dot color on their own.
- `marks?: boolean | number[] | SliderMark[]` = false: Dots on the track. true puts one on every step when there are 20 steps or fewer, else five evenly spaced; number[] places them; SliderMark[] ({ value, label }) adds a label under each. Marks outside min..max are ignored.
- `showMarkLabels?: boolean` = false: Writes the formatted value under every mark that has no label of its own. The label under a thumb's value turns to the text color.
- `showValue?: "auto" | "always" | "never"` = "auto": The value bubble above each thumb (beside it when vertical). auto shows it while dragging, on hover and on keyboard focus; always keeps it up and, under a label, makes room for it so it never covers the label row.
- `showValueLabel?: boolean` = false: The formatted value at the end of the label row: "$1,250", or both ends of a range joined by an en dash, with a shared unit written once ("500 – 2,000 km"). Without a label it gets a row of its own.
- `orientation?: "horizontal" | "vertical"` = "horizontal": vertical stands 180px tall with the mark labels beside the track and the bubble to the side. Size it with classNames.box.
- `inverted?: boolean` = false: Fills from the other end: right to left, or top to bottom when vertical. Arrow keys follow.
- `locale?: string` = "": Locale for every number shown (any BCP 47 tag). Empty uses the nearest LocaleProvider, then the page's language (en-US on the server). The demo passes en-US while it is empty.
- `prefix?: string` = "": A simple unit before the number when there is no format: "~", "$". Letters get a space ("USD 50"), symbols do not ("$50"). The demo drops its dollar format while one is set.
- `suffix?: string` = "": A simple unit after the number when there is no format: "km", "%", "m²". Letters get a non-breaking space ("50 km"), symbols do not ("50%").
- `format?: Intl.NumberFormatOptions`: Intl options for the bubble, the value label and the mark labels. Dollars: { style: "currency", currency: "USD", maximumFractionDigits: 0 }. Without it numbers keep the step's decimals.
- `formatValue?: (value: number) => ReactNode`: Replaces the formatted number everywhere it shows, e.g. a word per step (New, Like new, Good, Worn). A string result is also what screen readers hear.
- `formatValueLabel?: (values: number[]) => ReactNode`: Replaces the whole value label, e.g. "Any" when the range covers everything.
- `thumbLabels?: string[]`: Each thumb's aria-label. Two thumbs default to "Minimum" and "Maximum", one thumb to the field label (or aria-label), three or more to "Value 1 of 3"…
- `value?: number[]`: The controlled values, one per thumb. A value outside min..max is drawn at the edge and never corrected behind your back.
- `defaultValue?: number[]`: The uncontrolled start, clamped into the range once. Defaults to the middle of min..max ([50] for 0..100). Two numbers make a range.
- `onValueChange?: (value: number[]) => void`: Every change while dragging, tapping or pressing keys.
- `onValueCommit?: (value: number[]) => void`: When a drag, a tap or a key press ends: the moment to fetch results or save.
- `name?: string` = "": Form field name. Inside a <form> each thumb submits a hidden input (name[] for ranges), and a form reset puts the thumbs back.
- `id?: string`: The thumb's id (the group's for ranges). Defaults to useId(); the label points at it.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `classNames?: Partial<Record<"box" | "root" | "track" | "range" | "thumb" | "mark" | "markLabel" | "value" | "valueLabel" | "field" | "label" | "description" | "error", string>>`: Extra classes for the inner parts: box (the slider and its mark labels; size a vertical slider here), the radix root, track, range, thumbs, mark dots and labels, the bubble, the value label and the field parts.
- `className?: string`: Classes for the outermost element: the Field root when the slider has a label, description or error, else the slider's box.

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

const usd = { style: "currency", currency: "USD", maximumFractionDigits: 0 } as const

export function PriceFilter({ onApply }: { onApply: (range: number[]) => void }) {
  const [price, setPrice] = useState([500, 2000])
  return (
    <div className="flex flex-col gap-6">
      <Slider
        label="Price"
        value={price}
        onValueChange={setPrice}
        onValueCommit={onApply}
        min={0}
        max={5000}
        step={50}
        minStepsBetweenThumbs={2}
        locale="en-US"
        format={usd}
        showValueLabel
      />
      <Slider
        label="Search radius"
        defaultValue={[25]}
        min={5}
        max={100}
        step={5}
        suffix="km"
        marks={[5, 25, 50, 75, 100].map((value) => ({ value, label: `${value} km` }))}
        showValueLabel
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/slider (Markdown: https://wingo-ui.com/components/slider.md)

#### Switch (`switch`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add switch`

An on / off setting that applies at once: a spring thumb that stretches and drags like iOS, thumb icons, and async saves that roll back.

Click the track, its label or the empty space of the row and the thumb springs across while the track fills in the tone. Hold it down and the thumb stretches toward where it is going, then settles as it lands; drag the thumb sideways like on an iPhone and it follows your finger, committing past half way and snapping back otherwise. A vertical swipe on a phone still scrolls the page. Tab reaches the switch with a ring around the track; Space and Enter toggle it, and holding Space stretches the thumb until you let go. When saving is async the switch flips at once and a spinner turns in the thumb; clicks and keys are ignored until it settles, and a failed save flips it back, shakes the row and shows the error under it (press Simulate an error in the playground). Read-only switches keep their value and ignore input, disabled ones dim. Cards take a ring while on and dip slightly when pressed. On a phone every row is at least 44px tall and the whole row is the target; a switch without a label gets a 44px hit area. With reduced motion the thumb jumps, nothing stretches or shakes, and the spinner turns slower.

npm: @radix-ui/react-switch, motion
Wingo UI dependencies: ui-config, field, spinner, use-controllable-state, motion, tones

Props:
- `label?: ReactNode` = "": Text beside the track. The whole row is one <label>, so clicking the text, the description or the empty space toggles it. It names the switch through aria-labelledby. Leave it empty for a bare switch (then pass aria-label).
- `description?: ReactNode` = "": A second line under the label, in the muted caption style. It stays out of the switch's name and is linked with aria-describedby, so screen readers read it after the label and the state.
- `error?: ReactNode` = "": A message under the row, lined up with the label, that slides in and marks the switch invalid (red ring, aria-invalid). "", false and null are no error; true only marks it invalid.
- `required?: boolean` = false: A red mark after the label (hidden from screen readers) and required on the switch, so a native form will not submit while it is off.
- `invalid?: boolean` = false: The red ring and aria-invalid without a message, for forms that show errors elsewhere.
- `disabled?: boolean` = false: Dims the row to 50% and blocks every input. A disabled Field or FieldGroup around it disables it too.
- `readOnly?: boolean` = false: Shows the value but ignores clicks, keys and drags, with no hover tint and aria-readonly. It stays focusable, so it is still read out.
- `defaultChecked?: boolean` = false: The starting value while uncontrolled. Pass checked and onCheckedChange to control it.
- `loading?: boolean` = false: A spinner turns inside the thumb and clicks, keys and drags are ignored, with aria-busy. For a save you track yourself; an async onCheckedChange does the same on its own.
- `errorText?: ReactNode` = "Could not save. Try again.": Shown under the row when an async onCheckedChange rejects, and announced. It clears on the next change. Press Simulate an error in the playground to see it.
- `size?: "sm" | "md" | "lg"` = "md": Track 32x18 / 40x24 / 48x28px with a 14 / 20 / 24px thumb, label 13 / 14 / 15px. Rows grow to 44px on touch screens; the track keeps its size.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The track color while on. neutral is black in light mode and white in dark mode, where the thumb turns dark so it still stands out.
- `color?: string` = "": Any CSS color for the track while on. Replaces the tone; the thumb turns black or white by the color's lightness. Leave empty to use the tone.
- `variant?: "default" | "card"` = "default": card turns the row into a bordered tile (the checkbox card look) with the switch at the top end; it takes a ring in the tone while on and dips slightly when pressed. Pair it with icon.
- `icons?: boolean` = false: A check inside the thumb while on and an x while off, swapping with a crossfade and a small turn. They stay undistorted while the thumb stretches.
- `labelPosition?: "end" | "start"` = "end": end: the switch first, the text after it. start: the text first and the switch at the end of a full-width row, like an iOS settings list. Cards always put the switch at the end.
- `checked?: boolean`: The controlled value. With an async onCheckedChange the switch shows the value being saved until the promise settles, then follows checked again, so set checked after the save succeeds (or revert it yourself when it fails) for the rollback to show.
- `onCheckedChange?: (checked: boolean) => (void | Promise<unknown>)`: Called with the new value on every click, key or drag. Return a promise to save first: the switch flips at once, spins, ignores input until it settles, and a rejection flips it back, shakes the row and shows errorText. A late result after unmount is ignored.
- `checkedIcon?: ReactNode`: A custom icon inside the thumb while on, like a Moon. Unsized svgs follow the size (10 / 12 / 14px) and take the tone color.
- `uncheckedIcon?: ReactNode`: A custom icon inside the thumb while off, like a Sun.
- `icon?: ReactNode`: Cards: the leading icon tile, which takes the tone's soft color while on. Rows: an icon, thumbnail or avatar before the text, centered on the row.
- `name?: string` = "": Form field name. Inside a <form> Radix renders a hidden checkbox that submits value while the switch is on (nothing while off), and a form reset returns it to defaultChecked. The demo prints what the form would submit.
- `value?: string` = "on": What the form submits while the switch is on.
- `id?: string`: The switch's id. Inside a Field it reuses the Field's, so the Field's label points at it.
- `classNames?: Partial<Record<"field" | "track" | "thumb" | "icon" | "content" | "label" | "description" | "error", string>>`: Extra classes for the parts: the row or card, the track, the thumb, the icon layer, the text column, the label, the description and the error.
- `className?: string`: Classes for the outermost element: the wrapper around the row and its message, or the track itself when the switch has no text. Override the tone vars here, e.g. [--tone:var(--success)].
- `ref?: RefObject<HTMLButtonElement | null> or (node) => void`: The track: the Radix switch <button role="switch">, which also receives every other prop.

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

async function saveSetting(key: string, on: boolean) {
  const res = await fetch("/api/settings", { method: "PATCH", body: JSON.stringify({ [key]: on }) })
  if (!res.ok) throw new Error("save failed")
}

export function NotificationSettings() {
  const [messages, setMessages] = useState(true)

  return (
    <div className="flex flex-col divide-y divide-foreground/10 rounded-2xl bg-surface shadow-raised">
      <Switch
        label="New messages"
        description="When someone writes to you about a listing"
        labelPosition="start"
        checked={messages}
        onCheckedChange={setMessages}
        classNames={{ field: "min-h-14 px-4 py-3" }}
      />
      <Switch
        label="Price offers"
        labelPosition="start"
        defaultChecked
        errorText="Could not save. Try again."
        onCheckedChange={(on) => saveSetting("offers", on)}
        classNames={{ field: "min-h-14 px-4 py-3", error: "px-4 pb-3" }}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/switch (Markdown: https://wingo-ui.com/components/switch.md)

#### Tag Input (`tag-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tag-input`

A field that turns typed, pasted or suggested text into removable chips, for tags, keywords and email recipients.

Type a word and press Enter, a comma or a semicolon and it becomes a chip that slides in, with the caret moving along after it. Paste a list like emma@acme.com, michael@acme.com; olivia@acme.com and every entry becomes its own chip, duplicates once. A word that fails validation stays in the field, the text shakes and the reason shows as the field error until you change it; typing a tag that already exists makes the existing chip pulse instead of adding it again. With suggestions a list opens under the field as you type, matches in bold and diacritics ignored: Arrow Down and Up move through it, Enter picks the highlighted one, Escape closes it. Backspace in the empty field puts the last tag back as text to edit it (select mode highlights it first and a second Backspace removes it; remove mode deletes it at once). Arrow Left at the start of the text moves to the chips: Left and Right walk between them, Home and End jump, Delete or Backspace removes the focused chip and focuses its neighbour, Enter or F2 (or a double-click, or a second tap on a focused chip) edits it in place where Enter saves and Escape cancels, and Escape or Right past the last chip returns to the text. Cmd/Ctrl+Enter adds the text and submits the form. Every chip has an × to remove it and clearable adds a Clear all button; additions and removals are read out politely. At the maximum the text field hides and the description says the limit is reached. On a phone the text is 16px so iOS never zooms, the keyboard shows an Enter key (Done at the limit), commas typed on Android keyboards still split tags, the × buttons have a large touch area and the suggestions stay in the page under the field, above the keyboard.

npm: motion, lucide-react
Wingo UI dependencies: badge, field, listbox, use-controllable-state, motion, text-match, tones, ui-config

Props:
- `label?: ReactNode` = "": Renders the field anatomy around the box: the label above it, linked to the text input; the box is a group named by it.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. At the limit it is replaced by labels.limit(max) when you pass none.
- `error?: ReactNode` = "": Replaces the description with the animated error and marks the field invalid. Rejected tags show their own message here until the text changes.
- `required?: boolean` = false: The red mark after the label and aria-required on the text input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, blocks typing, hides the × on chips and disables the hidden inputs.
- `readOnly?: boolean` = false: Chips stay visible and focusable but cannot be removed, edited or added to; no suggestions.
- `placeholder?: string` = "Add a tag": Hint text while there are no tags; the input stays usable after. The demo passes Add a tag.
- `value?: string[]`: The tags, controlled; pair it with onValueChange. A tag that equals a suggestion's value shows that option's label and icon.
- `defaultValue?: string[]` = "[]": The starting tags while uncontrolled; a form reset returns to them.
- `onValueChange?: (tags: string[]) => void`: Fires with the new list after every add, remove, edit and clear.
- `suggestions?: ListboxItems (TagInputSuggestion | TagInputSuggestionGroup)[]`: Autocomplete options filtered while typing (case and diacritics ignored, groups kept). Options already added leave the list. A picked option adds its value; typing an option's label exactly adds its value too.
- `delimiters?: string[]` = "[\",\", \";\"]": Characters that add the current text as a tag, detected in the text itself so Android keyboards work. Enter always adds.
- `validate?: (tag: string, tags: string[]) => (string | boolean)`: Runs after transform. false rejects with labels.invalid(tag), a string rejects with that message; the text stays in the field and shakes. tagValidators.email, .url and .hashtag are exported; with the email one the keyboard switches to email.
- `transform?: (tag: string) => string` = "trim + collapse spaces": Normalizes typed text before validation, e.g. lowercase and a leading #. The default trims and collapses spaces, which also runs after yours.
- `labels?: Partial<TagInputLabels>`: Screen reader copy and messages, merged over the English defaults: tag(tag) the chip's name ("Tag bike, press Delete to remove"), remove(tag), added(tag), removed(tag), duplicate(tag), limit(max), invalid(tag), notInList(tag), clear ("Clear all"), suggestions ("Suggestions").
- `onReject?: (tag: string, reason: "invalid" | "duplicate" | "limit" | "notInList") => void`: Called for every tag that was turned away, e.g. to show your own message when the control sits inside a <Field>.
- `size?: "sm" | "md" | "lg"` = "md": Minimum height 32 / 40 / 48px (md 44px on touch) with 20 / 24 / 28px chips and 13 / 14 / 15px text (16px on phones). The box grows as chips wrap.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box look shared with every input.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Box corners scaled with the size; chips follow (pill chips in a full box, square chips with none, 6px otherwise).
- `chipVariant?: "soft" | "outline" | "solid"` = "soft": The Badge variant of the chips.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color of the chips.
- `color?: string` = "": Any CSS color for the chips; replaces the tone. Empty uses the tone.
- `max?: number` = 0: Maximum number of tags. At the limit the text field hides, the keyboard shows Done and the description reads labels.limit(max). 0 means no limit.
- `maxLength?: number` = 0: Characters per tag; longer text is cut as you type or paste. 0 means no limit.
- `backspace?: "edit" | "select" | "remove"` = "edit": Backspace in the empty field: edit puts the last tag back as text, select highlights it first and a second press removes it, remove deletes it at once.
- `editable?: boolean` = true: Double-click a chip, tap a focused chip, or press Enter or F2 on it to edit it in place. Emptying it removes the tag.
- `addOnBlur?: boolean` = true: Leaving the field adds what was typed (validated like Enter).
- `addOnPaste?: boolean` = true: A pasted text with delimiters, new lines or tabs becomes several tags at once; off, it is pasted as plain text.
- `allowDuplicates?: boolean` = false: Off, a tag that already exists (compared without case or diacritics) is not added and the existing chip pulses.
- `restrictToSuggestions?: boolean` = false: Only suggestions can become tags: the first match is highlighted as you type and other text is rejected with labels.notInList.
- `openOnFocus?: boolean` = false: Opens the suggestions as soon as the field is focused instead of when you type or press Arrow Down, and keeps them open after a pick.
- `clearable?: boolean` = false: A Clear all × at the end of the box while there are tags; focus returns to the text.
- `name?: string` = "": One hidden input per tag with this name, so FormData.getAll(name) returns the list. The demo uses tags while empty.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The text input's id. Defaults to useId(); inside a <Field> the Field's id wins.
- `ref?: RefObject<HTMLInputElement | null> or (node) => void`: The text input. Every other native prop lands there too: inputMode, enterKeyHint, autoFocus, onBlur, onKeyDown (runs first; preventDefault skips the built-in keys), aria-*, data-*.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "tag" | "editor" | "input" | "clear" | "suggestions" | "list" | "option", string>>`: Extra classes for the parts: the field anatomy, the box, each chip, the in-place editor, the text input, the clear button and the suggestions panel, list and rows.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description or error, else the tag input root.

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

export function ListingTags() {
  const [tags, setTags] = useState(["bike", "vintage"])

  return (
    <TagInput
      label="Listing tags"
      description="Up to 8 tags, separated by commas."
      placeholder="Type and press Enter"
      value={tags}
      onValueChange={setTags}
      max={8}
      name="tags"
      suggestions={[
        { value: "bike", label: "bike" },
        { value: "vintage", label: "vintage" },
        { value: "trek", label: "trek" },
        { value: "city", label: "city" },
        { value: "sport", label: "sport" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/tag-input (Markdown: https://wingo-ui.com/components/tag-input.md)

#### Textarea (`textarea`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add textarea`

Multi-line text that grows with what you write, with a counter, an optional resize handle, a toolbar slot and mod+enter to submit.

Type and the box grows line by line from minRows up to maxRows, then scrolls inside; growth is instant, so typing never lags, and the caret stays in view because the box grows, not a scroller. Enter makes a new line and Tab moves on, like a native textarea. Press ⌘ Enter (Ctrl Enter elsewhere) to submit: the playground's Post checks for at least 40 characters, slides the error in under the box, and sends once it is long enough; submitShortcut="enter" makes it chat style, with Shift Enter for a new line. Use an example (Example on a phone) fills a long description so you can watch it grow to maxRows and scroll; Clear clears it. With a limit and showCount the counter turns amber at 90% and red at the limit. With resizable, a grip in the corner lets a mouse drag the box taller and that height sticks as the new floor. A click anywhere in the box, even in the toolbar's empty space, lands in the text. On a phone the text is 16px so iOS never zooms, the return key makes new lines, toolbar buttons keep 44px targets and the grip hides.
Wingo UI dependencies: field, use-controllable-state, use-shortcut, ui-config

Props:
- `label?: ReactNode` = "": The label, linked with htmlFor. Leave it empty for a bare box, e.g. inside a <Field> that has its own label.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with an alert icon and the text, slides in and marks the box invalid (red ring, aria-invalid).
- `required?: boolean` = false: The required mark after the label and required on the textarea.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message, for forms that show errors elsewhere.
- `disabled?: boolean` = false: Dims the box and its label and blocks typing. Not submitted with the form, like any disabled field.
- `readOnly?: boolean` = false: The text stays visible, selectable and scrollable but cannot change; no hover tint and no resize grip. Good for terms or a sent message.
- `placeholder?: string` = "": Shown while the box is empty, in the muted text color.
- `defaultValue?: string` = "": The starting text while uncontrolled. Where the browser has CSS field-sizing the box fits it from the first paint, before any JavaScript runs.
- `value?: string`: The text, to control it from outside; pair it with onValueChange. A controlled value past maxLength shows as given (the counter turns red) and is never cut silently.
- `onValueChange?: (value: string) => void`: Called with the new text on every change, controlled or not.
- `onChange?: (event: ChangeEvent<HTMLTextAreaElement>) => void`: The native change event, untouched, so {...register("description")} from react-hook-form works as on a plain textarea.
- `size?: "sm" | "md" | "lg"` = "md": Text 13 / 14 / 15px (16px on phones, so iOS never zooms) with matching padding. One row is as tall as an input of the same size: 32 / 40 / 48px, 44px for md on touch; sm grows to 36px on phones, where its text is 16px.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": soft is a filled well that works on every surface, outline a bordered box, underline a bottom line that grows a bar from the center on focus, ghost is invisible until hovered (inline edits, toolbars).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button's (md is 8 / 10 / 12px). full is half a one-row height (16 / 20 / 24px; 18px for sm on phones, 22px for md on touch), so a one-row composer is a pill and a taller box never turns into an oval. Ignored by underline.
- `minRows?: number` = 3: The height when empty, in rows of text. 1 makes a composer that starts as tall as an input.
- `maxRows?: number` = 8: Grows up to this many rows, then scrolls inside. 0 means no limit; a value below minRows counts as minRows.
- `autosize?: boolean` = true: Grow with the text. Uses CSS field-sizing where the browser has it and measures once per change elsewhere. false keeps the box at minRows and scrolls.
- `resizable?: boolean` = false: A vertical resize grip for mouse and trackpad (hidden on touch). With autosize the dragged height becomes the new floor and the box still grows past it when the text needs more.
- `showCount?: boolean` = false: The "count / max" counter at the end of the message row, amber from 90% and red at the limit. Needs maxLength.
- `maxLength?: number` = 0: The native character limit; 0 means none. Screen readers hear how many characters are left once 10% or less remains.
- `submitShortcut?: string` = "mod+enter": The combo that submits, in mod+k notation: ⌘ Enter on Apple devices, Ctrl Enter elsewhere. It calls onSubmitShortcut, else form.requestSubmit(). "enter" makes it chat style (Shift Enter for a new line; touch keyboards keep making new lines), "" turns it off. Announced with aria-keyshortcuts; shown nowhere by default (the demo shows a Kbd hint).
- `onSubmitShortcut?: (value: string, event: KeyboardEvent<HTMLTextAreaElement>) => void`: Runs on the shortcut with the current text instead of submitting the form. The chat example sends the message with it.
- `header?: ReactNode`: A row inside the box above the text: attachment chips, a quoted reply. A click on its empty space lands in the text.
- `footer?: ReactNode`: A toolbar inside the box under the text: attach, emoji, send. Buttons keep their own 44px hit areas on touch; a click on the empty space lands in the text.
- `id?: string`: The textarea's id. Defaults to useId(); inside a <Field> the Field's id wins. ref and every other native prop (name, autoComplete, spellCheck, autoFocus, onBlur, aria-*, data-*) land on the <textarea> too; inputMode defaults to text and enterKeyHint to enter.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel, counterLabel (what screen readers hear near the limit).
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "textarea" | "header" | "footer", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the outermost element: the Field root when there is a label, description, error or counter, else the box.

```tsx
import { useState } from "react"
import { Paperclip, SendHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"

export function ListingDescription() {
  return (
    <form action="/listings" method="post">
      <Textarea
        name="description"
        label="Listing description"
        description="At least 40 characters."
        placeholder="Describe the item: condition, size, why you are selling."
        required
        minLength={40}
        showCount
        maxLength={9000}
        fieldProps={{ counterLabel: (left) => `${left} characters left` }}
      />
    </form>
  )
}

export function Composer({ onSend }: { onSend: (text: string) => void }) {
  const [text, setText] = useState("")
  const send = () => {
    if (!text.trim()) return
    onSend(text.trim())
    setText("")
  }
  return (
    <Textarea
      aria-label="Message"
      placeholder="Write a message…"
      value={text}
      onValueChange={setText}
      minRows={1}
      maxRows={6}
      onSubmitShortcut={send}
      footer={
        <>
          <Button variant="ghost" size="icon-sm" radius="full" aria-label="Attach">
            <Paperclip />
          </Button>
          <Button size="sm" radius="full" className="ms-auto" rightIcon={<SendHorizontal />} onClick={send}>
            Send
          </Button>
        </>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/textarea (Markdown: https://wingo-ui.com/components/textarea.md)

#### Time Picker (`time-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add time-picker`

A time-of-day field to type into or pick from columns, with 12 / 24 hours by locale, minute steps, limits and iOS wheels on phones.

Type a time the way you would say it: "1430", "14.30", "9", "2:30pm" or "2p" (a colon appears after the first two digits). It is read on blur and on Enter; text that does not parse turns the field red while you type and goes back to the last good time on blur, a time outside min / max moves to the nearest limit, and with strictStep the minutes snap to the step. ArrowUp / ArrowDown step the minutes by minuteStep and Shift+ArrowUp / ArrowDown step an hour, committing at once and skipping blocked times. Clicking the field or the clock button opens a panel of columns (hours, minutes, seconds, AM / PM) with the chosen time centered; clicking an option sets it at once, and a minute (or second) click closes the panel. Alt+ArrowDown (or Enter on the clock button) opens it with focus on the hour: ArrowUp / ArrowDown move and pick, PageUp / PageDown jump five, Home / End go to the ends, ArrowLeft / ArrowRight switch columns, Enter confirms and closes, Escape closes and returns to the field. On a phone the field never raises the keyboard: a tap opens a bottom sheet with wheels that snap like iOS, tick under the thumb where the phone supports vibration, and commit with Done; dragging the sheet away keeps the old time. The wheels also take arrows, PageUp / PageDown, Home and End. TimePickerWheel (the wheel of the sheet) is exported on its own (options, value, onValueChange, label, band, haptics) for durations, alarms and other pickers.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: button, drawer, field, use-controllable-state, use-locale, use-media-query, date-utils, motion, tones, ui-config

Props:
- `label?: ReactNode` = "": The field label, linked to the input. Plain text also becomes the title of the phone sheet.
- `description?: ReactNode` = "": Helper text under the field, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description with an animated error and marks the field invalid.
- `required?: boolean` = false: The red mark after the label and required on the input.
- `invalid?: boolean` = false: The invalid look and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the field, blocks typing and never opens the panel; the hidden input is not submitted.
- `readOnly?: boolean` = false: The time stays visible and selectable but can not change: no typing, no panel, no clear button.
- `defaultValue?: string` = "": The starting time while uncontrolled, as "HH:mm" in 24 hours ("HH:mm:ss" with seconds), like <input type="time">. A form reset returns to it.
- `value?: string`: The time, controlled: "HH:mm" in 24 hours whatever the display ("" is empty). A value off the step shows as given and is highlighted in no column.
- `onValueChange?: (value: string) => void`: Called with the new "HH:mm" (or "") after a typed time is read, an arrow step, a column pick, Now, Clear or the sheet's Done.
- `placeholder?: string` = "": Empty uses "--:--" for 24 hours and "--:-- --" for 12 hours (with seconds, one more group).
- `locale?: string` = "": How the time is written and which hour cycle auto picks: en-US 2:30 PM, en-GB 14:30. Empty uses the nearest LocaleProvider, else the page's language.
- `hourCycle?: "auto" | "h12" | "h23"` = "auto": 12 or 24 hours. auto follows the locale. The value is always 24 hours underneath, so switching keeps the time; midnight shows as 12:00 AM.
- `minuteStep?: number` = "5": The minutes offered in the columns and wheels and the ArrowUp / ArrowDown step. Typed minutes can be anything unless strictStep.
- `secondStep?: number` = "5": The seconds offered with withSeconds.
- `strictStep?: boolean` = false: Typed minutes (and seconds) snap to the nearest step on blur: 14:37 becomes 14:35 with a 5 minute step.
- `withSeconds?: boolean` = false: Values become "HH:mm:ss" and a seconds column (and wheel) appears.
- `min?: string` = "": The earliest time ("09:00"). Earlier options are disabled and typed times are moved up to it. A min later than max is an overnight window (22:00 to 06:00) that wraps past midnight.
- `max?: string` = "": The latest time ("18:00"). Later options are disabled and typed times are moved down to it.
- `disabledTimes?: (time: string) => boolean`: Blocks single times, called with "HH:mm" (or "HH:mm:ss"): a lunch break, booked slots. Blocked options are disabled, hours with nothing left grey out, arrow steps skip them and a typed one moves to the nearest free slot.
- `clearable?: boolean` = false: A clear button in the field while it has a time (and a Clear button in the phone sheet).
- `showNow?: boolean` = false: A Now button under the columns (and in the sheet) that sets the current time, rounded to the step and moved to the nearest allowed one.
- `closeOnSelect?: boolean` = true: Desktop: a click in the minutes column (the seconds column with withSeconds) closes the panel. Hours and AM / PM never close it. The phone sheet always waits for Done.
- `responsive?: boolean` = true: Below 768px the field opens a bottom sheet with wheels instead of the panel. Off, phones get the panel too.
- `defaultOpen?: boolean` = false: Starts with the panel (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the panel or sheet is open, controlled. It never opens while disabled or readOnly.
- `onOpenChange?: (open: boolean) => void`: Called when the panel or sheet opens or closes.
- `size?: "sm" | "md" | "lg"` = "md": Field heights of 32, 40 and 48px (md is 44px on touch screens), with matching text.
- `variant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The field box: a tinted fill, a border, a bottom line that grows on focus, or nothing until hover.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the field, scaled per size like the button. Ignored by underline.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill of the selected options and the sheet's Done button.
- `color?: string` = "": Any CSS color for the selection; replaces the tone. Text on it turns black or white by lightness.
- `showColumnLabels?: boolean` = false: Small titles above the desktop columns (Hours, Minutes...) from labels.
- `icon?: ReactNode`: The trigger button's icon; a clock by default.
- `sheetTitle?: string` = "Select time": The phone sheet's title when the label is not plain text (or missing).
- `labels?: Partial<{ now; done; clear; open; dialog; hours; minutes; seconds; period; format: string }>`: Every visible and spoken string, merged over the English defaults ("Now", "Done", "Clear", "Choose time", "Hours"...). format is the screen reader hint after the field, with {format} replaced by the pattern ("Format HH:mm").
- `name?: string` = "": Renders a hidden input with this name and the "HH:mm" value, for native forms. The visible input has no name.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the panel opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the panel lines up with the field.
- `container?: HTMLElement | null`: Portal target of the panel and the sheet; defaults to document.body.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.
- `id?: string`: The input's id; generated when left out.
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "input" | "trigger" | "clear" | "content" | "column" | "option" | "wheel" | "band" | "footer", string>>`: Extra classes for the inner parts. content is the panel (or the sheet), band the shared highlight behind the wheels.
- `className?: string`: Extra classes for the outermost element: the Field when there is a label or message, else the box.
- `ref?: Ref<HTMLInputElement> (a useRef object or an (el) => void callback)`: The text input. Other props (onBlur, autoFocus, aria-*, data-*) land on it too.

```tsx
import { useState } from "react"
import { TimePicker } from "@/components/ui/time-picker"

const lunchBreak = (time: string) => time >= "13:00" && time < "14:00"

export function PickupTime() {
  const [time, setTime] = useState("11:30")
  return (
    <TimePicker
      label="Pickup time"
      description="The store is open from 9 AM to 6 PM."
      value={time}
      onValueChange={setTime}
      locale="en-US"
      min="09:00"
      max="18:00"
      minuteStep={15}
      disabledTimes={lunchBreak}
      clearable
      showNow
      name="pickup_time"
    />
  )
}
```

Docs: https://wingo-ui.com/components/time-picker (Markdown: https://wingo-ui.com/components/time-picker.md)

### Forms

#### Address Input (`address-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add address-input`

A Romanian address form: county, locality search, street, number, block and apartment, postal code checked against the county.

Pick the county from a searchable list (type to filter, arrows and Enter; a bottom sheet on phones), then type the locality: the cities of that county show as you type, diacritics do not matter ("cluj", "iasi"), Enter picks the highlighted one, and a village that is not in the list is kept as typed through the "Use …" row, with a quiet note under the field (never an error) that it is not in the list and to check the spelling. Picking a city before the county fills the county too. Choosing București swaps the locality for a Sector select; changing the county clears the locality and a postal code from another county but keeps the street and the number. Street and number are side by side from 512px of width; "Add block, entrance, apartment" opens the bl. / sc. / et. / ap. row on a smooth collapse and moves focus into it (it is open from the start when the value has any of them). The postal code takes digits only, six at most, with the numeric keypad on phones; leaving it with a code from another county shows an amber warning with an icon under it, never an error. Enter in a part moves to the next one and submits only from the last; the phone keyboard says Next and then Done. Required parts show their message on blur (or on change, or only after the form is submitted); server errors land on their field, and a county code the list does not know (old data such as "BUC") is flagged at once. Browser autofill works on every part, and "Str. Memorandumului nr. 28, bl. A2" pasted or autofilled into the street is split into the parts; a full address ("…, sat Feleacu, jud. Cluj, 407280") also fills the county, locality, sector and postal code, but only the ones that are still empty, and never a locality from another county than the chosen one. The single-line variant is one search field: type an address, the suggestions (offline parsing and the localities list, or your searchAddress) fill every part and open the details below for a final check; leaving the field with text that was not picked (Tab or a tap outside) parses that text into the parts. Read-only shows the formatted address with a copy button; reduced motion turns the collapses into fades.

npm: motion, lucide-react
Wingo UI dependencies: button, collapsible, combobox, field, input, select, use-controllable-state, use-locale, motion, ro-locations, text-match, ui-config

Props:
- `value?: RoAddress`: The controlled address: { county (plate code "CJ", "B"), locality, localityId?, sector? (București), street, number, building?, entrance?, floor?, apartment?, postalCode?, details? }.
- `defaultValue?: RoAddress` = "EMPTY_RO_ADDRESS": The starting address when uncontrolled.
- `onValueChange?: (address: RoAddress, validation: { valid: boolean; errors: AddressErrors; warnings: AddressErrors }) => void`: Every change with the whole address and its validity, so a submit button can follow valid.
- `variant?: "form" | "single"` = "form": form: the parts. single: one autocomplete field that fills the parts, with the parts under an "Edit details" collapsible.
- `layout?: "auto" | "stacked"` = "auto": auto: one column until the component is 512px wide, then 6 columns (county and locality 3 + 3, street 4 and number 2, postal code 2 and details 4). stacked: one column always.
- `fields?: AddressField[]` = "all": Which parts render: a courier form hides details, a billing form hides the apartment row.
- `requiredFields?: AddressField[]` = "[\"county\", \"locality\", \"street\", \"number\"]": Marked with * and validated. In București the sector is required in place of the locality.
- `collapseApartment?: boolean` = true: The block / entrance / floor / apartment row waits behind a link until used; it is open when the value has any of them.
- `validateOn?: "blur" | "change" | "submit"` = "blur": When a part's error shows. A submit of the enclosing form shows them all.
- `errors?: AddressErrors`: Server errors per field, e.g. { street: "This street is not in the official street list" }. They win over the computed ones.
- `showSummary?: boolean` = false: The formatted one-line address under the form, crossfading as it changes.
- `countryLabel?: ReactNode` = "": A read-only country row at the top ("Romania"), for forms that print the country.
- `loadLocalities?: (county: string, query: string, context: { signal: AbortSignal }) => Promise<{ value: string; label: string; description?: string }[]>`: Your full nomenclature (SIRUTA). value becomes localityId. Without it the cities of the county come from ro-locations plus a built-in list of every Romanian town (Pașcani, Onești, Moinești...), and free text is accepted for villages.
- `searchAddress?: (query: string, context: { signal: AbortSignal }) => Promise<AddressSuggestion[]>`: The single variant's online suggestions ({ id, label, description?, address }), debounced 400ms. Without it the text is parsed offline.
- `label?: ReactNode` = "": The group's legend (a fieldset); every part has its own label too. The demo shows "Delivery address" while it is empty.
- `description?: ReactNode` = "": Helper text under the legend.
- `error?: ReactNode` = "": A message for the whole group, linked to the fieldset.
- `required?: boolean` = false: The * after the legend. Which parts are required is requiredFields.
- `invalid?: boolean` = false: Every part in the invalid look without a message.
- `disabled?: boolean` = false: Dims and blocks every part (a disabled fieldset).
- `readOnly?: boolean` = false: The formatted address as text on several lines with a copy button; "-" when empty.
- `size?: "sm" | "md" | "lg"` = "md": Every part 32 / 40 / 48px (md 44px on touch), with matching label and text sizes.
- `fieldVariant?: "soft" | "outline" | "underline" | "ghost"` = "soft": The box of every part (variant is the form / single choice here).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of every box, scaled per size like the button's.
- `name?: string` = "": Adds hidden inputs and names for native forms: `${name}.county`, `${name}.locality`, `${name}.localityId`, `${name}.street`… The demo lists them in the readout.
- `responsive?: boolean` = true: The county, sector and locality lists open as bottom sheets below 768px (the locality sheet has its own search box).
- `locale?: string` = "": A ro locale picks ADDRESS_INPUT_LABELS_RO on its own. Empty uses the UIProvider locale, then the browser's. The demo defaults to en-US.
- `labels?: Partial<AddressInputLabels>`: Every string: the part labels (county, locality, sector, street, number, building, entrance, floor, apartment, postalCode, details, country), more, search, editDetails, required, postalInvalid, postalMismatch(county), localityCustom(text), localityUnlisted(text), noLocalities, placeholders, countyUnknown, noResults, loading, copy, copied, filled, clear, cancel, showSuggestions. English by default; ADDRESS_INPUT_LABELS_RO is the ready Romanian set.
- `fieldProps?: Partial<FieldGroupProps>`: More for the fieldset: variant "card", classNames.
- `id?: string`: The prefix of every part's id (`${id}-street`).
- `classNames?: Partial<Record<"grid" | "country" | "county" | "locality" | "sector" | "street" | "number" | "more" | "apartmentRow" | "postal" | "details" | "warning" | "single" | "editDetails" | "summary" | "readOnly", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root inside the fieldset.

Parts:
- `formatRoAddress` (function): "Str. Memorandumului 28, bl. A2, sc. 1, et. 3, ap. 12, 400114 Cluj-Napoca, jud. Cluj"; București ends with "Sector 3, 030167 București". Signature: (address, { multiline = false, includeCounty = true, includeCountry = false }) => string.
- `validateRoAddress` (function): The component's validation, for a form's own submit handler. A postal code from another county is a warning. Signature: (address, { requiredFields?, fields?, labels? }) => { valid; errors; warnings }.
- `parseRoAddress` (function): Best effort: street type and name, nr. or a trailing number, bl. / sc. / et. / ap., a 6-digit postal code, sector, a known locality and county. Signature: (text: string) => Partial<RoAddress>.
- `postalCodeMatchesCounty` (function): false only for a complete code whose first two digits belong to another county (RO_POSTAL_PREFIXES). Signature: (code: string, county: string, sector?: string) => boolean.
- `RO_POSTAL_PREFIXES` (constant): The two-digit postal code prefixes per county (București 01 to 06), used by postalCodeMatchesCounty. Type: Record<string, string[]>.
- `RO_STREET_TYPES` (constant): The street types the street field offers and the parser recognises ("Str.", "Bd.", "Calea"…). Type: readonly string[].
- `EMPTY_RO_ADDRESS` (constant): The empty address, a starting value for a controlled form. Type: RoAddress.
- `DEFAULT_ADDRESS_INPUT_LABELS` (constant): The English default labels. Type: AddressInputLabels.
- `ADDRESS_INPUT_LABELS_RO` (constant): The ready Romanian label set (Județ, Localitate, Bloc, Scara, Etaj, Ap.). Type: AddressInputLabels.

```tsx
import { useState } from "react"
import { AddressInput, EMPTY_RO_ADDRESS, type RoAddress } from "@/components/ui/address-input"

export function ShippingAddress() {
  const [address, setAddress] = useState<RoAddress>(EMPTY_RO_ADDRESS)
  const [valid, setValid] = useState(false)
  return (
    <form action="/api/checkout" className="flex flex-col gap-4">
      <AddressInput
        label="Delivery address"
        name="shipping"
        value={address}
        onValueChange={(next, validation) => {
          setAddress(next)
          setValid(validation.valid)
        }}
        showSummary
      />
      <button type="submit" disabled={!valid}>Continue</button>
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/address-input (Markdown: https://wingo-ui.com/components/address-input.md)

#### CSV Import (`csv-import`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add csv-import`

A four step import wizard for CSV and Excel files: upload, column mapping, row review with inline fixes, and a progress run with a report.

Drop a CSV, TSV or Excel file on the zone (or click it, press Enter or Space on it, or paste a file; on a phone the native picker opens) and a card shows its size, rows, columns, separator and encoding, or its sheet; turn off "The first row is a header" for files that start with data, pick the sheet of a workbook, or download a template built from the fields. Continue to the mapping: every field already points at the column whose name or alias matches, marked Matched, and headerless files get their CUI, IBAN, CNP, email, phone and date columns recognised by their values; open a field's select (a bottom sheet on phones) to pick another column or Don't import, and picking a column another field uses moves it over. Continue stays disabled until every required field has a column, and the missing ones are named. Rows are checked while you map (big files in idle chunks, so ten thousand never freeze the page), so the review opens ready: filter All, With errors or Valid, read the red wavy underline and the tooltip on a bad cell, click it (or Tab to it, error cells are the only cells in the tab order, and press Enter) to fix it in place, where Enter saves and Escape cancels; the row number, status and skip button stay pinned while the table scrolls sideways. On a phone rows are cards and tapping a value opens a sheet with the field and its error, saved with one button. Skip single rows with the ban button, keep "Skip rows with errors" on to leave the rest out, and choose what happens to rows whose key already exists. Import opens straight on a progress bar that Cancel stops and that screen readers hear every 10%, then counts created, updated, skipped and failed rows in tiles, with a bouncing check when nothing failed, the rows that did not make it with their column and reason, a CSV of them with an Error column, and Import another file to start over; while an import runs, and after it ran, the steps stay where they are.

npm: libphonenumber-js, motion, lucide-react
Wingo UI dependencies: alert, badge, button, drawer, empty-state, file-upload, form-wizard, inline-edit, input, progress, segmented-control, select, switch, table, tooltip, use-controllable-state, use-locale, commerce, date-utils, file-types, invoicing, motion, number-format, spreadsheet, text-match, tones, ui-config

Props:
- `fields: ImportField[]`: What you import: { id, label, type?, required?, aliases?, options?, validate?, transform?, example?, description?, currency? }. type is text, number, currency, date, email, phone, cui, iban, cnp, boolean or select; aliases are other column names that mean the field; currency is the ISO code of a currency field's amounts (else the component's).
- `onImport: (rows: Record<string, unknown>[], context: { strategy; onProgress: (done: number) => void; signal: AbortSignal; rows: ImportRow[] }) => Promise<ImportResult>`: Gets the valid, non-skipped rows with typed values (numbers, ISO dates, E.164 phones, formatted CUI and IBAN). Report progress, stop on the signal, resolve with { created, updated, skipped, failed?: { index, error }[] } where index is the file row from context.rows. A server can re-run the same checks: the file also exports validateImportRows(rows, fields, mapping, options), validateImportValue(field, cell) and IMPORT_VALIDATORS (one pure parser per field type).
- `defaultStep?: "upload" | "map" | "review" | "import"` = "upload": The step it opens on. The demo loads its sample file for any step past the upload.
- `step?: "upload" | "map" | "review" | "import"`: The current step, controlled; pair it with onStepChange. A running import holds the wizard on its step.
- `onStepChange?: (step: ImportStepId) => void`: Called on every step change.
- `file?: File | null`: The picked file, controlled. Set it to start from a file you already have (a drop elsewhere on the page, a sample); pair it with onFileChange.
- `defaultFile?: File | null`: A file to start with, uncontrolled.
- `onFileChange?: (file: File | null) => void`: Called when a file is picked or removed.
- `accept?: string` = ".csv,.tsv,.txt,.xlsx": File types the drop zone takes, like the native attribute; the hint under the zone lists them. Old .xls files are refused with errors.unsupported.
- `maxFileSize?: number` = "20971520": Bytes: 20 MB (20 × 1024 × 1024, so the hint reads a round "20 MB"). Bigger files are refused with errors.tooLarge; the hint under the drop zone shows the limit. 0 means no limit.
- `maxRows?: number` = 10000: Rows read per sheet. The rest is cut and a warning says so.
- `uniqueField?: string` = "": The field that identifies a record (cui, email). Repeats inside the file become errors ("Duplicate of row 12"), rows found in existingKeys get an Exists badge, and the review shows the duplicates choice. The demo falls back to cui.
- `duplicateStrategy?: "skip" | "update" | "create"`: Controlled: what happens to rows whose unique value already exists. Pair it with onDuplicateStrategyChange; the review's select changes it.
- `defaultDuplicateStrategy?: "skip" | "update" | "create"` = "skip": What happens, while uncontrolled, to rows whose unique value already exists: left out (skip), passed on for an update, or added again (create). The review shows the choice once uniqueField is set; onImport gets it as context.strategy.
- `onDuplicateStrategyChange?: (strategy: DuplicateStrategy) => void`: Called when the review's select changes.
- `existingKeys?: string[] | Set<string>`: Values of uniqueField already in your system (compared without case and diacritics; CUIs with or without RO).
- `allowSkipInvalid?: boolean` = true: Shows the "Skip rows with errors" switch (on). Off: every error must be fixed, or its row skipped by hand, before Import unlocks.
- `inlineEdit?: boolean` = true: Fix cells in the review: click a cell to edit it in place (a sheet on phones), and it is checked again at once.
- `defaultHasHeader?: boolean` = true: The starting value of the upload step's "The first row is a header" switch. Off reads the first row as data and names the columns "Column 1"... (labels.columnLabel); CUI, IBAN, CNP, email, phone and date columns are then matched by their values.
- `templateFileName?: string` = "import-template": Name of the template CSV (the field labels and their examples, ";" separated where the locale writes decimal commas).
- `delimiter?: string` = "": Forces the CSV separator. Empty detects it among , ; tab and |.
- `dateFormat?: string` = "": A hint shown next to date fields in the mapping ("MM/DD/YYYY"). Parsing follows the locale, reads dotted dates day first, and accepts ISO and Excel dates.
- `defaultCountry?: string` = "RO": Country for phone numbers written without a + prefix (libphonenumber-js). Valid numbers are stored as E.164.
- `currency?: string` = "USD": ISO 4217 code for currency fields in the review ("$12,480.00"); a field's own currency wins. It only labels the amounts, nothing is converted.
- `stepper?: "horizontal" | "vertical" | "progress" | "dots" | "none"` = "horizontal": form-wizard's header from 768px up; phones always get the compact progress row.
- `fullScreenOnMobile?: boolean` = true: Below 768px the wizard fills its container with a sticky header and footer and 48px buttons (form-wizard's). The container needs a height.
- `size?: "sm" | "md"` = "md": Stepper markers, footer buttons, selects, switches and the filter.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active step, the drop zone's drag tint, the switches, the progress bar and the primary button.
- `locale?: string` = "": Parses and formats numbers, amounts and dates ("12,480.00" and 09/24/2026 in en-US, "12.480,00" and 24.09.2026 in ro-RO). Empty uses UIProvider's locale, then the browser's.
- `labels?: Partial<CsvImportLabels>`: Every string, English by default (DEFAULT_CSV_IMPORT_LABELS): step titles and descriptions, the drop zone (drop, browse, tapTitle, dropHere, fileHint(types, max), fileRejected(names)), template, templateHint, parsing, removeFile, sheet, hasHeader, hasHeaderDescription, columnLabel, rows, columns, delimiter(d), noFile, noFileDescription, chooseFile, the mapping (column, doNotImport, searchColumns, autoMatched, sample, required, usedBy, missingRequired, matched, dateFormat, types), the review (all, errorsFilter, withErrors, valid, skipInvalid, skipInvalidDescription, duplicates, duplicatesDescription, strategies, exists, new, skippedRow, status, errorCount, row, missing, emptyValue, yes, no, skipRow, includeRow, fix, save, cancel, validating, fixToContinue, nothingToImport, noMatches, noMatchesDescription, showMore, tableCaption, toImport), the run (importing(done, total), ready, readySkipped, cancelled, complete, completeWithErrors, completeDescription, importFailed, retry), the summary (created, updated, skipped, failed, failedRows, moreInReport, fieldError(field, error), downloadReport, importMore, reportError, reportFileName), truncated(max), form-wizard's next, back, start, progress and step(index, count), and errors { required, email, phone, cui, iban, cnp, number, date, select, boolean, duplicate(row), tooLarge, unsupported, empty, parse, tooMany }. Counted strings are (count, formatted) => string.
- `wizardClassNames?: FormWizardProps["classNames"]`: Classes for form-wizard's own parts (header, stepper, body, footer...).
- `classNames?: Partial<Record<"upload" | "dropzone" | "template" | "file" | "sheet" | "header" | "map" | "mapRow" | "mapSample" | "review" | "reviewFilter" | "reviewTable" | "reviewCard" | "duplicates" | "skip" | "run" | "progress" | "summary" | "tile" | "report" | "footer", string>>`: Extra classes for the inner parts, each also marked with data-slot="csv-import-<part>".
- `className?: string`: Classes for the wizard root (a form); other props spread onto it too.

```tsx
import { CsvImport, type ImportField } from "@/components/ui/csv-import"

const FIELDS: ImportField[] = [
  { id: "company", label: "Company", required: true, aliases: ["Company name", "Customer"] },
  { id: "cui", label: "Tax ID (CUI)", type: "cui", aliases: ["CIF", "VAT ID"] },
  { id: "email", label: "Email", type: "email" },
  { id: "phone", label: "Phone", type: "phone" },
  { id: "balance", label: "Balance", type: "currency", aliases: ["Balance (USD)"] },
]

export function ImportCustomers({ existing }: { existing: string[] }) {
  return (
    <CsvImport
      fields={FIELDS}
      uniqueField="cui"
      existingKeys={existing}
      locale="en-US"
      dateFormat="MM/DD/YYYY"
      labels={{ upload: "File", map: "Columns", review: "Check", import: "Import" }}
      onImport={async (rows, { onProgress, signal }) => {
        const response = await fetch("/api/customers/import", { method: "POST", body: JSON.stringify(rows), signal })
        onProgress(rows.length)
        return response.json()
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/csv-import (Markdown: https://wingo-ui.com/components/csv-import.md)

#### Field (`field`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add field`

The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use.

Click or tap a label and its control takes focus; a click on the box's padding, an icon or a suffix like USD also lands in the input without moving the caret. Tab moves from field to field and the whole box takes a soft ring; Enter in a field submits the form like a native one. Press Continue with a title under 10 characters and the error slides in under the field while the rest of the form glides down; type again and it slides away, and a hint swaps for the error with a crossfade instead of a jump. With a limit set, the counter turns amber at 90% and red at the limit, and screen readers hear how many characters are left. A read-only field keeps its text selectable but ignores typing, a disabled one dims with its label. Horizontal fields put the label beside the control once the field is 448px wide and stack it on top below that, so on a phone every label sits above its field and every input is 16px so iOS never zooms.

npm: @radix-ui/react-slot, motion, lucide-react
Wingo UI dependencies: button, motion, ui-config

Props:
- `label?: ReactNode` = "": The label, linked to the control with htmlFor (or aria-labelledby for groups). Leave it empty for a bare control.
- `description?: ReactNode` = "": Helper text under the control, linked with aria-describedby. The error takes its place while it shows.
- `error?: ReactNode` = "": Replaces the description with an alert icon and the text, slides in and marks the field invalid. "", false and null are no error; true marks it invalid without text (prefer invalid for that).
- `required?: boolean` = false: Shows the required mark after the label (hidden from screen readers) and tells the control to set required.
- `optional?: boolean` = false: Shows optionalLabel after the label, for forms that mark the few optional fields instead of the many required ones.
- `optionalLabel?: string` = "Optional": The word after an optional label.
- `requiredIndicator?: ReactNode` = "*": The mark after a required label.
- `labelAction?: ReactNode`: A link or small button at the end of the label row, like Forgot your password?. It sits outside the <label> and gets a 44px hit area on touch.
- `hideLabel?: boolean` = false: Keeps the label for screen readers only, e.g. a search field whose icon already says what it is.
- `invalid?: boolean` = false: The red ring and aria-invalid without a message, for forms that show errors elsewhere. Passed to the control through context.
- `disabled?: boolean` = false: Dims the label and, through context, disables the control. A disabled FieldGroup disables every field inside.
- `readOnly?: boolean` = false: The value stays visible and selectable but cannot change; the box drops its hover tint. Passed to the control through context.
- `size?: "sm" | "md" | "lg"` = "md": Label size (13 / 14 / 15px) and the box height horizontal labels align to. Controls take their own size; the demo passes the same to every box.
- `orientation?: "vertical" | "horizontal"` = "vertical": horizontal puts the label in a column beside the control once the field itself is 448px wide (a container query, not the viewport) and stacks below that. Inherits from a FieldGroup.
- `labelWidth?: number` = 160: Width of the label column in horizontal fields, in px. Inherits from a FieldGroup.
- `count?: number` = 0: The current length, for the counter. Controls with showCount pass it for you. In the playground 0 follows what you type; any other value previews a counter state.
- `maxLength?: number` = 0: Shows count / max at the end of the message row, amber from 90% and red at the limit. 0 hides the counter. The demo also sets it on the input.
- `counterLabel?: (remaining: number) => string` = "(remaining) => `${remaining} characters left`": What screen readers hear once 10% or less is left, 500ms after typing stops (negative past the limit). The visible counter is hidden from them.
- `id?: string`: The control's id (not the wrapper's). Defaults to useId(); children read it from context.
- `labelBehavior?: "native" | "focus"` = "native": focus: a label click focuses the control instead of clicking it, so a label never opens a picker. Button triggers set it through useFieldControl. The label carries it as data-behavior.
- `labelAs?: "label" | "span"` = "label": span for group controls (radio group, checkbox group, rating, a two-thumb slider), which point at it with aria-labelledby (FieldControl adds it). Clicking it focuses the group's current stop.
- `children?: ReactNode`: The control. Inside a Field, library controls read the id, flags and messages from context; do not give them their own label (the Field's wins, with a dev warning).
- `classNames?: Partial<Record<"labelRow" | "label" | "required" | "optional" | "labelAction" | "message" | "description" | "error" | "counter", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the root. The rest of the props (style, data-*, aria-*) land there too.

Parts:
- `FieldGroup` (component): A real <fieldset> with a <legend>, so screen readers announce the section before its fields. legend, description, error, columns (1 | 2 | 3 | 4: one column on phones, 2 from sm, 3 and 4 from md; span with sm:col-span-2), variant ("plain" | "card"), orientation and labelWidth (inherited by every field inside), gap ("sm" | "md" | "lg"), disabled (the native attribute plus context), required and requiredIndicator (a mark after the legend), classNames (legend, description, error, content). Props: FieldGroupProps.
- `FieldBox` (component): The box every text field and trigger uses: variant ("soft" | "outline" | "underline" | "ghost"), size (inherits the Field's), radius, multiline, invalid / disabled / readOnly (default to the Field's), state ("open" | "closed" for pickers), asChild (a trigger button or a native select), focusOnPointerDown (default true: a press on the padding or an addon focuses the input inside), data-slot. Props: FieldBoxProps.
- `FieldControl` (component): Wraps any single child (a native input or select, a range, a third-party control) and puts the Field's id, aria-describedby, aria-invalid and aria-required on it, plus disabled and readOnly while the Field has them. The child's own props win. Props: SlotProps.
- `FieldAddon` (component): Text addons like "https://" or "USD" in the muted addon look; elements render as given and bare icons turn muted. Takes span props.
- `FieldAction` (component): The 28px trailing icon button (32px in lg): label (required, its aria-label and title), icon, size (defaults to the Field's), keepFocus (default true, the input keeps focus while it is pressed), plus every Button prop. 44px hit area on touch. Props: FieldActionProps.
- `FieldLabel` (component): The label on its own: as ("label" | "span"), behavior ("native" | "focus"), size, required, optional, optionalLabel, requiredIndicator, disabled. Reads its target, size and flags from the nearest Field; every prop overrides. Props: FieldLabelProps.
- `FieldDescription` (component): Helper text in the caption style, with the Field's description id so aria-describedby finds it. Takes p props.
- `FieldError` (component): The error text with its alert icon (icon replaces it, null hides it), with the Field's error id. Props: ComponentProps<"p"> & { icon?: ReactNode }.
- `FieldCounter` (component): The visible "count / max", hidden from screen readers, with data-state="ok | near | over" (amber from 90%, red at the limit). Props: ComponentProps<"span"> & { count?: number; max: number }.
- `FieldMessage` (component): The animated row under a control: description or error (never both, crossfading) plus the counter, inside a polite live region. Opens and closes with the collapse preset and works outside a Field too, e.g. under a checkbox. Props: FieldMessageProps.
- `useFieldControl` (hook): The hook every control calls once. Merges its props with a parent Field or FieldGroup and returns id, labelId, describedBy, invalid, disabled, required, readOnly, size (the control's, else the Field's), orientation, controlProps (for a native element), ariaProps (for anything else), isWrapped and wrap(control), which renders the Field around the control when it has its own label, description, error or counter. Signature: (options: FieldControlOptions) => FieldControlState.
- `useFieldContext` (hook): The nearest Field's ids and flags (id, labelId, describedBy, invalid, disabled, required, readOnly, size, orientation), or null outside one. For custom controls. Signature: () => FieldContextValue | null.
- `useFormReset` (hook): Calls onReset after the element's form is reset, once the form has put its fields back, so uncontrolled controls return to their defaultValue. Signature: (ref: RefObject<HTMLElement | null>, onReset: () => void) => void.
- `fieldBoxClasses` (function): The box classes for any element (a trigger button, a custom wrapper). Unknown values fall back to soft / md / md. Signature: (options: { variant?, size?, radius?, multiline?, className? }) => string.
- `FIELD_BOX` (constant): The base class recipe of the field box. Import it; never retype the classes.
- `FIELD_VARIANTS` (constant): The box classes per variant (soft, outline, underline, ghost).
- `FIELD_SIZES` (constant): The box height and padding classes per size.
- `FIELD_MULTILINE_SIZES` (constant): The box padding classes per size for multiline controls (textareas).
- `FIELD_RADII` (constant): The box radius classes per size and radius.
- `FIELD_INPUT` (constant): The classes of the bare input inside the box.
- `FIELD_ADDON` (constant): The muted addon classes (text like "https://" or "USD").
- `FIELD_TRIGGER` (constant): The classes of a picker trigger button styled as a field.
- `FIELD_CHEVRON` (constant): The classes of the trailing chevron on picker triggers.
- `FIELD_HEIGHT_VAR` (constant): The CSS variable that carries the box height, for parts that line up with it.

```tsx
import type { ComponentProps } from "react"
import { FIELD_INPUT, Field, FieldAddon, FieldBox, FieldControl, useFieldControl } from "@/components/ui/field"

export function PriceField({ error }: { error?: string }) {
  return (
    <Field label="Price" description="The final price, tax included." error={error} required>
      <FieldBox>
        <FieldControl>
          <input name="price" inputMode="decimal" placeholder="0" autoComplete="off" className={FIELD_INPUT} />
        </FieldControl>
        <FieldAddon>USD</FieldAddon>
      </FieldBox>
    </Field>
  )
}

// your own control: one hook, and it works alone or inside a <Field>
export function PlainInput({ label, error, ...props }: ComponentProps<"input"> & { label?: string; error?: string }) {
  const field = useFieldControl({ label, error })
  return field.wrap(
    <FieldBox invalid={field.invalid} disabled={field.disabled}>
      <input {...props} {...field.controlProps} className={FIELD_INPUT} />
    </FieldBox>,
  )
}
```

Docs: https://wingo-ui.com/components/field (Markdown: https://wingo-ui.com/components/field.md)

#### Form Wizard (`form-wizard`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add form-wizard`

A multi-step form with a stepper, per-step sync or async validation, direction-aware slides, a summary step and a full-screen phone layout.

Fill in a step and press Continue (or Enter in any single-line field, Cmd+Enter / Ctrl+Enter in a textarea): the step's validators run, and on success the step is marked with a check and the next one slides in from the side you are heading, while the card's height follows on a spring. A failed step turns its marker into a red "!", shakes the Continue button and puts focus on the first invalid field; an async check shows a spinner on the button after a moment. Back never validates. Click a completed step in the stepper to jump back to it (with linear={false} any step), and on the summary step the Edit links do the same. Optional steps show Skip. On the last step the button submits and shows a spinner while onComplete runs, then a check. Tab order is the stepper, the fields, then Back, Skip and Continue; after a step change focus lands on the new step's heading and screen readers hear "Step 2 of 5: Details". Below 768px the stepper becomes a compact progress bar with the step title, and with fullScreenOnMobile the wizard fills the screen with a sticky header, a scrolling body and a sticky footer of 48px buttons above the safe area (in the flow, so it rides above the keyboard). Steps change only through the buttons: no swipe, so sliders and carousels inside a step keep their gestures. Under reduced motion steps crossfade and nothing shakes.

npm: motion, lucide-react
Wingo UI dependencies: button, motion, tones, use-media-query, use-controllable-state, ui-config

Props:
- `steps?: WizardStep[]`: { id, title, description?, icon?, content, optional?, validate? }. validate returns a boolean or a promise; a throw or rejection counts as failed and is logged. Alternatively pass <FormWizardStep> children with the same props (content is their children). An empty list renders nothing.
- `stepper?: "horizontal" | "vertical" | "progress" | "dots" | "none"` = "horizontal": The header from 768px up: numbered markers with connectors, a side column with descriptions, a progress bar with the step title, dots for onboardings, or nothing. Below 768px every stepper except none becomes the compact progress header.
- `linear?: boolean` = true: Only Continue moves forward; completed steps stay clickable. false makes every step clickable (going forward still validates the current step first).
- `size?: "sm" | "md"` = "md": Markers 24 / 28px, step titles 13 / 14px, footer buttons sm / md.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active marker, the connector and progress fills, completed markers' tint and the Continue button.
- `color?: string` = "": Any CSS color; replaces the tone everywhere. Text on the fill turns black or white by lightness.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the footer buttons, scaled per size like the button's.
- `showStepHeading?: boolean` = true: The step title and description above the fields. The title hides on its own wherever the header already shows it (phones, the progress stepper); false hides both but keeps the title for screen readers and as the focus target.
- `fullScreenOnMobile?: boolean` = true: Below 768px the wizard fills its container's height: a sticky blurred header, a body that scrolls on its own and a sticky footer with 48px buttons (Continue full width, Back as an icon) padded for the safe area. Give the container a height (h-dvh for a page).
- `animate?: boolean` = true: Steps slide 32px in the direction you move, the body's height follows on a spring, fills grow and a failed Continue shakes. false swaps steps instantly. Reduced motion always crossfades.
- `keepMounted?: boolean` = false: Keeps every step mounted (inactive ones hidden and inert), for forms that keep their state in the DOM. react-hook-form does not need it: it keeps the values of unmounted fields.
- `value?: string`: The current step id, controlled. Pair it with onValueChange. An unknown id shows the first step; a removed active step moves to the nearest one.
- `defaultValue?: string` = "": The starting step id; empty (or an unknown id) starts on the first step. In a linear wizard the steps before it count as completed.
- `children?: ReactNode`: <FormWizardStep> elements instead of the steps array; other children are ignored.
- `onValueChange?: (value: string) => void`: Called with the new step id on every step change.
- `onComplete?: (event: FormEvent<HTMLFormElement>) => (void | Promise<unknown>)`: The last step's submit, after its validation. A promise shows the button loading, then a check (labels.done); a rejection shakes it. After an await read the form from event.target. Without onComplete a form action (formProps.action) runs instead.
- `footer?: ReactNode`: Replaces the default footer; build one with useFormWizard() (a type="submit" button acts as Continue). null hides the footer.
- `labels?: Partial<{ back; next; submit; skip; done; step: (index, count) => string; optional; completed; error; progress }>`: Every visible and announced string, merged over the English defaults: back "Back", next "Continue", submit "Submit", skip "Skip", done "Done", step (i, n) => "Step i of n", optional "Optional", completed "Completed", error "Needs attention" (both read after a step's title), progress "Progress" (names the stepper).
- `formProps?: ComponentProps<"form">`: Extra props for the root <form> (action, id, method). Other unknown props land on the form too.
- `classNames?: Partial<Record<"header" | "stepper" | "stepItem" | "stepMarker" | "stepTitle" | "stepDescription" | "connector" | "progress" | "progressBar" | "progressText" | "main" | "body" | "panel" | "panelTitle" | "panelDescription" | "footer" | "back" | "skip" | "next", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root <form>.

Parts:
- `FormWizardStep` (component): Declares a step as a child of FormWizard instead of the steps array; its children are the content. Props: Omit<WizardStep, "content"> & { children?: ReactNode }.
- `useFormWizard` (hook): The wizard's state and actions inside FormWizard, for custom footers and summaries. next() and goTo() resolve to false when validation blocks them. Signature: () => { steps, value, index, count, isFirst, isLast, completed, errors, skipped, validating, submitting, done, next(), back(), goTo(id), skip() }.
- `useFormWizardValidation` (hook): Registers a validator for the step the calling component renders in; removed on unmount. Validators run in order after the step's own validate. With react-hook-form: useFormWizardValidation(() => form.trigger(["title", "price"])). Signature: (validate: () => boolean | Promise<boolean>) => void.
- `FormWizardSummary` (component): A review step: one list group per section (title defaults to the step's) with an Edit link that goes back to that step. Props: { sections: { step: string; title?: ReactNode; items: { label: ReactNode; value: ReactNode }[] }[]; editLabel?: string; editable?: boolean }.

```tsx
import { Controller, FormProvider, useForm, useFormContext } from "react-hook-form"
import { FormWizard, FormWizardSummary, useFormWizardValidation, type WizardStep } from "@/components/ui/form-wizard"
import { Input } from "@/components/ui/input"
import { CurrencyInput } from "@/components/ui/currency-input"

type Listing = { title: string; price: number | null }

function Details() {
  const { register, control, trigger, formState } = useFormContext<Listing>()
  useFormWizardValidation(() => trigger(["title", "price"]))
  return (
    <div className="flex flex-col gap-4">
      <Input
        label="Title"
        error={formState.errors.title?.message}
        {...register("title", { minLength: { value: 10, message: "The title needs at least 10 characters" } })}
      />
      <Controller
        name="price"
        control={control}
        rules={{ required: "Add a price" }}
        render={({ field, fieldState }) => (
          <CurrencyInput label="Price" currency="USD" locale="en-US" value={field.value} onValueChange={field.onChange} onBlur={field.onBlur} ref={field.ref} error={fieldState.error?.message} />
        )}
      />
    </div>
  )
}

function Review() {
  const { getValues } = useFormContext<Listing>()
  return <FormWizardSummary editLabel="Edit" sections={[{ step: "details", items: [{ label: "Title", value: getValues("title") }] }]} />
}

const steps: WizardStep[] = [
  { id: "details", title: "Details", content: <Details /> },
  { id: "review", title: "Review", content: <Review /> },
]

export function PostListing() {
  const form = useForm<Listing>({ defaultValues: { title: "", price: null } })
  return (
    <FormProvider {...form}>
      <FormWizard
        steps={steps}
        labels={{ submit: "Publish", step: (i, n) => `Step ${i} of ${n}` }}
        onComplete={() => fetch("/api/listings", { method: "POST", body: JSON.stringify(form.getValues()) })}
      />
    </FormProvider>
  )
}
```

Docs: https://wingo-ui.com/components/form-wizard (Markdown: https://wingo-ui.com/components/form-wizard.md)

#### Inline Edit (`inline-edit`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add inline-edit`

Edit a value where it is shown: text, long text, numbers and selects that turn into an editor in place and save optimistically.

Click or tap the value and it becomes an editor of the same size, text selected, with the text in exactly the same place. Enter saves, Escape cancels and puts focus back on the value, Tab or a click elsewhere saves (blurAction). A textarea makes new lines with Enter and saves with Cmd+Enter (Ctrl+Enter on Windows); a select opens at once and saves on the pick, as a bottom sheet on phones. From the keyboard, Tab to the value and press Enter, Space or F2. The new value shows at once with a small spinner, a check pops in when the save lands, and a failed save rolls back, shakes the value and shows the error. On touch the pencil is always visible, the save and cancel buttons get 44px hit areas and the keyboard shows Done.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, input, textarea, number-input, select, button, spinner, kbd, motion, use-controllable-state, use-locale, number-format

Props:
- `type?: "text" | "textarea" | "number" | "select"` = "text": The editor: a single-line Input, a growing Textarea, a NumberInput (value is number | null, formatted with locale and format) or a Select (needs options, saves on the pick).
- `value?: string | number | null`: Controlled value: a string, or number | null for type="number". Pair it with onValueChange, which fires when a save starts (optimistic) and again with the old value if it fails.
- `defaultValue?: string | number | null` = "": Starting value while uncontrolled: "" for text, null for numbers. The playground reads a number for type="number" and an option value (active, reserved, sold) for select.
- `onValueChange?: (value) => void`: Called with the new value when a save starts, and with the previous one when the save fails (rollback).
- `onSave?: (value) => (void | PromiseLike<unknown>)`: Persists the value. A promise keeps the saving spinner; a rejection rolls back, shakes the value and shows the error (its message, else labels.failed). Unchanged values skip it; a save made while one is pending waits and only the latest result counts.
- `validate?: (value) => (string | null | undefined)`: Return a message to keep the editor open with the error under it. It re-checks while typing once it shows.
- `options?: SelectItems`: The options of a select editor: { value, label, description?, icon? } or groups of them.
- `emptyText?: string` = "Click to add": The muted display while the value is empty.
- `placeholder?: string` = "": The editor's placeholder, shown while the draft is empty.
- `aria-label?: string` = "": Names the display button and the editor. Screen readers hear "Listing title: Trek FX 2 city bike, Edit".
- `size?: "sm" | "md" | "lg"` = "md": Text 13 / 14 / 15px (16px on phones) and the editor's field size (32 / 40 / 48px, md 44px on touch). A heading look comes from className (text-2xl font-semibold); the editor follows it.
- `variant?: "ghost" | "underline"` = "ghost": The display: ghost tints on hover like a quiet field, underline draws a dashed line under the text (for values inside a sentence).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "sm": Corner shape of the hover tint and the editor box, scaled per size like the button's (sm is 6 / 8 / 10px).
- `showIcon?: boolean` = true: The pencil after the value: on hover and keyboard focus with a mouse, always visible on touch.
- `icon?: ReactNode`: Replaces the pencil (and the icon of the edit button with activation="button").
- `fullWidth?: boolean` = true: Fills its container. false sizes it to the text, so it sits inside a sentence (wrap the sentence in a div, not a <p>: the editor holds block elements); the editor opens as wide as the text was.
- `defaultEditing?: boolean` = false: Starts in edit mode (without taking focus). Use editing / onEditingChange to control it.
- `editing?: boolean`: Controlled edit mode.
- `onEditingChange?: (editing: boolean) => void`: Called when editing starts and ends.
- `onCancel?: () => void`: Called after Escape, the cancel button, a select closed without a pick, or a blur with blurAction="cancel".
- `disabled?: boolean` = false: Dims the value and blocks editing.
- `readOnly?: boolean` = false: Shows the value only: not a button, no pencil, text selectable.
- `activation?: "click" | "doubleclick" | "button"` = "click": click: a click or tap edits. doubleclick: a double click edits (a single tap on touch, Enter from the keyboard), for headings people select often. button: only the pencil button edits, so links in the value stay clickable.
- `showActions?: boolean` = true: Save and cancel buttons after the editor (below a textarea, with the Cmd+Enter hint). Selects save on the pick and never show them.
- `blurAction?: "save" | "cancel" | "none"` = "save": What leaving the editor (Tab, a click elsewhere) does. none keeps the editor open until Enter, Escape or a button.
- `selectOnFocus?: boolean` = true: Selects the text when the editor opens, so typing replaces it. A textarea puts the caret at the end instead.
- `maxLength?: number` = 0: The editor's character limit (text and textarea); 0 = none.
- `successDuration?: number` = 1200: Milliseconds the saved check stays after a save lands; 0 = no check.
- `locale?: string` = "": Formats and parses numbers ("1,200.5" in en-US, "1.200,5" in de-DE). Defaults to the nearest LocaleProvider, then the browser.
- `format?: Intl.NumberFormatOptions`: Number display: { style: "currency", currency: "USD", currencyDisplay: "narrowSymbol" }, units, percent.
- `renderValue?: (value) => ReactNode`: Custom display, e.g. a price with a badge or a link (pair it with activation="button").
- `labels?: { edit?; save?; cancel?; saving?; saved?; failed?; saveHint? }`: Every string: { edit: "Edit", save: "Save", cancel: "Cancel", saving: "Saving", saved: "Saved", failed: "Could not save", saveHint: "to save" }. Saved and failed are announced in a polite live region.
- `editorProps?: Partial<InputProps | TextareaProps | NumberInputProps | SelectProps>`: Extra props for the editor: min / max / step / steppers for numbers, maxRows for a textarea, search for a select.
- `classNames?: Partial<Record<"display" | "value" | "empty" | "icon" | "status" | "editor" | "actions" | "save" | "cancel" | "hint" | "error", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the root, merged last. Font classes here (text-2xl font-semibold) style both the value and the editor.

```tsx
import { InlineEdit } from "@/components/ui/inline-edit"

const STATUSES = [
  { value: "active", label: "Active" },
  { value: "reserved", label: "Reserved" },
  { value: "sold", label: "Sold" },
]

export function ListingDetails({ save }: { save: (field: string, value: unknown) => Promise<void> }) {
  return (
    <dl className="grid grid-cols-[96px_1fr] items-center gap-x-4 gap-y-1">
      <dt className="text-sm text-muted-foreground">Title</dt>
      <dd>
        <InlineEdit
          aria-label="Listing title"
          defaultValue="Trek FX 2 city bike"
          emptyText="Add a title"
          maxLength={70}
          validate={(v) => (v.trim() ? null : "The title cannot be empty")}
          onSave={(v) => save("title", v)}
        />
      </dd>
      <dt className="text-sm text-muted-foreground">Price</dt>
      <dd>
        <InlineEdit
          type="number"
          aria-label="Price"
          defaultValue={280}
          locale="en-US"
          format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
          onSave={(v) => save("price", v)}
        />
      </dd>
      <dt className="text-sm text-muted-foreground">Status</dt>
      <dd>
        <InlineEdit type="select" aria-label="Status" options={STATUSES} defaultValue="active" onSave={(v) => save("status", v)} />
      </dd>
    </dl>
  )
}
```

Docs: https://wingo-ui.com/components/inline-edit (Markdown: https://wingo-ui.com/components/inline-edit.md)

#### Invoice line items (`invoice-line-items`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add invoice-line-items`

The lines of an invoice, quote or order edited like a small spreadsheet, with VAT per rate computed the way e-Factura checks it.

Type in a product cell to search the catalog by name, SKU or keyword; picking one fills its unit, price and VAT, and typing a new name adds it as free text with the price flagged until you enter one. Tab moves across the cells in reading order, Escape in a number cell puts back the value it had, and an empty cell shows its prompt only on the line you are in. Enter moves to the same cell of the next line; on the last line it walks right through the text cells and adds a line from the last one, and Cmd or Ctrl + Enter adds a line from anywhere in the table. Drag a line by its grip with the mouse, or focus the grip and press Space to lift, the arrows to move, Space to drop and Escape to cancel; Alt + Arrow Up / Down moves the line you are in, and Delete or Backspace on a focused grip removes it. The ⋯ menu duplicates, moves (⌥↑ / ⌥↓ work from any cell) and removes; a removed line leaves an undo row for five seconds, paused while you hover or focus it. The % / lei chip in a discount cell switches the discount type. Totals update on every keystroke: subtotal, discounts, the taxable base, VAT per rate and the grand total, which is announced once your edits settle. Narrower than 768px (or with layout cards) every line is a card: tap it to edit a copy in a bottom sheet (a dialog on desktop) and keep it with Save or Cmd / Ctrl + Enter, while closing the sheet discards the draft; long-press the grip to reorder, use ⋯ for Move up / Move down, and tap the Total row to open the breakdown.

npm: @dnd-kit/core, @dnd-kit/sortable, motion, lucide-react
Wingo UI dependencies: badge, button, combobox, currency-input, drawer, dropdown-menu, empty-state, input, number-input, segmented-control, select, tooltip, use-controllable-state, use-locale, commerce, invoicing, motion, number-format, ui-config

Props:
- `value?: InvoiceLine[]`: The lines (controlled). InvoiceLine is the lib/invoicing line { id, quantity, unitPrice, vatRate?, discount?, discountType? } plus product, productId, description, unit and vatCategory (tells the 0% rows apart: E exempt, AE reverse charge, K intra-community).
- `defaultValue?: InvoiceLine[]`: The starting lines while uncontrolled. Left out: one empty line (none when minLines is 0).
- `onValueChange?: (lines: InvoiceLine[], totals: InvoiceTotalsData) => void`: Every edit, with the totals from computeInvoiceTotals (net, VAT per rate, total).
- `products?: InvoiceProduct[]` = "[]": The product combobox's options: { id, name, description?, unit?, unitPrice, vatRate?, sku?, keywords? }. Name, SKU and keywords are searched; picking one fills the unit, price and VAT and keeps the quantity.
- `onSearchProducts?: (query: string) => Promise<InvoiceProduct[]>`: Async catalog search (the combobox's async mode, debounced, older answers dropped).
- `allowCustomProducts?: boolean` = true: Free text in the product cell with an “Add …” row. A new product keeps its price empty and flagged until one is entered.
- `currency?: string` = "RON": ISO 4217 code for prices and totals. Changing it never converts the amounts.
- `pricesIncludeVat?: boolean` = false: The price column is the price with VAT (B2C quotes, shops); the totals end with “of which VAT”. Math per lib/invoicing either way.
- `vatRates?: VatRateOption[]` = "RO_VAT_RATES": The VAT select's options: { value, rate, category, label, description }. Default: 21%, 11%, 0% exempt, 0% reverse charge, 0% intra-community. A line with a rate not in the list shows it as text.
- `defaultVatRate?: number` = "0.21": The VAT rate of new lines, as a fraction.
- `units?: string[]` = "[\"pcs\", \"hr\", \"day\", \"month\", \"kg\", \"m²\", \"service\"]": The unit list; any other unit can be typed.
- `showDescription?: boolean` = true: A second line under the product for a description.
- `showUnit?: boolean` = true: The unit column.
- `showVat?: boolean` = true: The VAT column.
- `showDiscount?: boolean` = true: The discount column, with a % / amount switch per line.
- `defaultDiscountType?: "percent" | "amount"` = "percent": The discount type of new lines.
- `documentDiscount?: { type: "percent" | "amount"; value: number } | null` = "null": A discount on the whole document, shared across the lines by value before VAT.
- `onDocumentDiscountChange?: (discount: InvoiceDocumentDiscount | null) => void`: Makes the totals' discount row editable.
- `showTotals?: boolean` = true: The totals block under the lines.
- `totalsPosition?: "below" | "end"` = "below": below: a full-width block; end: a narrow block at the end under the table (always full width on phones).
- `layout?: "auto" | "table" | "cards"` = "auto": auto: the spreadsheet table from 768px of the component's own width (not the screen's), cards with a sheet editor below it, so a narrow panel on a desktop gets the cards too. table and cards force one (the table scrolls inside its panel when it does not fit).
- `reorderable?: boolean` = true: Drag handles (dnd-kit: mouse, a long press on touch, the keyboard), Alt + arrows and Move up / down in the menu.
- `minLines?: number` = 1: Lines that always stay: removing one of the last ones clears it instead. 0 shows an empty state when there are none.
- `maxLines?: number` = 0: The most lines; Add and Duplicate turn off at the limit. 0 means no limit.
- `errors?: Record<string, Partial<Record<"product" | "quantity" | "unitPrice" | "vatRate" | "discount", string>>>`: Server validation per line id and field: the cell turns invalid with the message in a tooltip (desktop) or under the field (the sheet).
- `readOnly?: boolean` = false: The invoice as the customer sees it: a plain table without inputs, the same totals.
- `disabled?: boolean` = false: Every cell, handle and button is disabled.
- `size?: "sm" | "md"` = "md": Cell controls 32 / 40px (44px on touch).
- `variant?: "ghost" | "soft"` = "ghost": ghost: a spreadsheet feel with a hover tint; soft: filled fields.
- `name?: string` = "": A hidden input with the lines as JSON, for native forms.
- `locale?: string` = "": Numbers and money format with this locale; empty uses the UIProvider's, then the page's.
- `undoTimeout?: number` = 5000: Milliseconds the undo row stays after a line is removed.
- `labels?: Partial<InvoiceLineItemsLabels>` = "DEFAULT_INVOICE_LINE_ITEMS_LABELS": Every string: the order, index and actions headers, column names (product, description, quantity, unit, unitPrice, unitPriceWithVat, vat, discount, total), actions (addLine, duplicate, moveUp, moveDown, remove, undo), the add row's lineCount(count, formatted), the empty state (empty, emptyDescription), the cells (descriptionPlaceholder, untitled), the pickers (productPlaceholder, createProduct(query), noProducts, unitPlaceholder, createUnit(query), priceMissing, newProduct, discountType, percent, amount), totals (gross, lineDiscounts, documentDiscount, net, vatRow(rate, base), grandTotal, includedVat(rate), showBreakdown, hideBreakdown), the sheet (editLine, saveLine, cancel, lineTitle(n), lineTotal), accessible names (caption, cellLabel(column, n), lineActions(n), reorder(n)), announcements (removed(n, product), moved(from, to), added(n), totalAnnouncement(total)) and the drag messages (pickedUp, movedTo, dropped, dragCancelled).
- `classNames?: Partial<Record<InvoiceLineItemsSlot, string>>`: Classes for panel, table, head, row, handle, index, product, description, quantity, unit, price, vat, discount, total, actions, add, cards, card, sheet, empty, live and totals (the panel around InvoiceTotals).

```tsx
import { useState } from "react"
import {
  InvoiceLineItems,
  InvoiceTotals,
  type InvoiceDocumentDiscount,
  type InvoiceLine,
  type InvoiceProduct,
} from "@/components/ui/invoice-line-items"

const PRODUCTS: InvoiceProduct[] = [
  { id: "crm-business", name: "Northwind CRM Business license", unit: "month", unitPrice: 250, vatRate: 0.21, sku: "CRM-BUS" },
  { id: "onboarding", name: "Setup and training", unit: "hour", unitPrice: 320, vatRate: 0.21 },
  { id: "guide", name: "Printed user guide", unit: "pc", unitPrice: 64.9, vatRate: 0.11 },
]

export function InvoiceEditor() {
  const [lines, setLines] = useState<InvoiceLine[]>([
    { id: "l1", productId: "crm-business", product: "Northwind CRM Business license", quantity: 25, unit: "month", unitPrice: 250, vatRate: 0.21, discount: 10 },
  ])
  const [discount, setDiscount] = useState<InvoiceDocumentDiscount | null>(null)
  return (
    <InvoiceLineItems
      value={lines}
      onValueChange={(next, totals) => {
        setLines(next)
        console.log("Amount due", totals.total)
      }}
      products={PRODUCTS}
      units={["pc", "hour", "day", "month", "service"]}
      documentDiscount={discount}
      onDocumentDiscountChange={setDiscount}
      name="invoice[lines]"
      currency="RON"
      locale="en-US"
      labels={{ grandTotal: "Amount due" }}
    />
  )
}

// the totals block alone (an invoice preview): pass lines or precomputed totals.
// DEFAULT_INVOICE_LINE_ITEMS_LABELS holds the English strings to spread under a translation
export function InvoicePreviewTotals({ lines }: { lines: InvoiceLine[] }) {
  return <InvoiceTotals lines={lines} currency="RON" locale="en-US" />
}
```

Docs: https://wingo-ui.com/components/invoice-line-items (Markdown: https://wingo-ui.com/components/invoice-line-items.md)

#### Rich Text Editor (`rich-text-editor`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add rich-text-editor`

A Notion-like text editor on Tiptap with a toolbar, Markdown shortcuts, mentions, images and counts; outputs HTML, JSON or Markdown.

Type in the box; Markdown shortcuts format as you write (# and a space for a heading, - for a list, [] for a checklist, > for a quote, three backticks for code, **word** for bold), and pasted Markdown formats too. The toolbar has undo and redo, a text style menu (Paragraph, Heading 1 to 3), bold, italic, underline, strikethrough, inline code, link, the three lists, quote, code block, divider and image; the pressed state follows the caret and each button's tooltip shows its shortcut (⌘B on a Mac, Ctrl+B elsewhere). Below 640px the bar keeps undo, redo, style, bold, italic, link and the two lists and moves the rest into a ⋯ menu. Select text with a mouse and a small menu floats above it with bold, italic, strikethrough, code and link. Keys inside the editor: mod+b, mod+i, mod+u, mod+shift+s, mod+e, mod+alt+1 to 3 for headings, mod+alt+0 for a paragraph, mod+shift+7 / 8 / 9 for lists, mod+z and shift+mod+z, mod+k opens the link editor at the caret (Enter applies, an empty address removes the link, addresses without a scheme get https:// and javascript: is refused), Tab and Shift+Tab indent list items, alt+F10 jumps to the toolbar where Left and Right move between buttons, Home and End jump, and Escape returns to the text. Type @ to mention a colleague: the list follows the caret, arrows move, Enter or Tab picks, Escape closes, and the person becomes a chip. The image button opens a file picker (or asks for an address without an upload handler); pasted and dropped images upload with a progress bar in place and in the footer, and a failure removes the placeholder and is announced. With a character limit the counter turns amber at 90% and red at the limit, and typing stops there. On a phone the text is 16px so iOS never zooms, and while you type the toolbar docks above the keyboard as a horizontally scrolling rail of 44px buttons; the style menu, the ⋯ menu and the link editor open as bottom sheets. Read-only shows the same styles with no toolbar, links open in a new tab and checkboxes are locked.

npm: @tiptap/react, @tiptap/pm, @tiptap/core, @tiptap/starter-kit, @tiptap/extensions, @tiptap/extension-list, @tiptap/extension-image, @tiptap/extension-mention, @tiptap/suggestion, @tiptap/markdown, @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: avatar, button, dropdown-menu, field, input, popover, separator, toggle, tooltip, use-controllable-state, use-keyboard-inset, use-locale, use-media-query, motion, number-format, tones, ui-config

Props:
- `value?: string | JSONContent`: The controlled content in `format`: an HTML string, a Markdown string, or Tiptap JSON. An empty editor is "" (HTML and Markdown). A value that differs from the last one the editor emitted (a reset, a load) replaces the content; echoing the emitted value back never resets the caret.
- `defaultValue?: string | JSONContent` = "": The starting content while uncontrolled. A form reset puts it back.
- `onValueChange?: (value: string | JSONContent, editor: Editor) => void`: Fires updateDebounce ms after the last change (and at once when the editor loses focus), with the content serialized in `format`.
- `format?: "html" | "json" | "markdown"` = "html": What value, defaultValue and onValueChange speak. markdown parses and writes Markdown through @tiptap/markdown; switching at runtime carries the current document over.
- `updateDebounce?: number` = 150: Milliseconds between the last keystroke and onValueChange, so serializing a long document never slows typing. 0 fires on every change.
- `placeholder?: string` = "Write something…": Shown while the editor is empty. An empty heading shows labels.headingPlaceholder instead.
- `toolbar?: boolean | RichTextToolbarItem[]` = true: true shows DEFAULT_TOOLBAR, false hides it (keys and Markdown shortcuts still work), or pass the items in order with "|" between groups: "undo", "redo", "heading", "paragraph", "bold", "italic", "underline", "strike", "code", "bulletList", "orderedList", "taskList", "link", "blockquote", "codeBlock", "horizontalRule", "image".
- `toolbarPosition?: "top" | "bottom"` = "top": bottom puts the toolbar under the text, the comment box look.
- `stickyToolbar?: boolean` = true: The top toolbar sticks under the page's top bar (top: var(--topbar-offset, 0px)) while a long document scrolls with the page, and turns to frosted glass once stuck.
- `bubbleMenu?: boolean` = true: A small menu above selected text (bold, italic, strikethrough, code, link) on mouse and trackpad screens. Phones keep their own selection menus.
- `markdownShortcuts?: boolean` = true: Formats as you type (# , - , [] , > , ```, **bold**) and when Markdown-looking text is pasted. Off: every character stays literal.
- `headingLevels?: (1 | 2 | 3 | 4)[]` = "[1, 2, 3]": The headings the text style menu offers and the schema allows.
- `characterLimit?: number` = 0: Stops input at this many characters and drives the counter's warning colors. 0 is no limit.
- `showCount?: "none" | "characters" | "words" | "both"` = "none": The footer counter, in the locale's numbers ("1.240 caractere · 212 cuvinte"); with a limit it reads "1.240 / 2.000" and turns amber at 90% and red at 100%, and a screen reader hears it only when it crosses those two marks.
- `minHeight?: number` = 160: Minimum height of the text area in px. Before the editor mounts, the box already has this height, so nothing jumps.
- `maxHeight?: number` = 0: Past this height in px the text scrolls inside the box. 0 grows with the content and the page scrolls.
- `onImageUpload?: (file: File, options: { onProgress: (progress: number) => void; signal: AbortSignal }) => Promise<string>`: Uploads a picked, pasted or dropped image and resolves its URL. A dimmed preview with a progress bar holds the spot meanwhile; a rejection removes it and announces labels.uploadFailed. Without it the image button asks for an image address.
- `imageAccept?: string` = "image/*": Accepted image types, in the file input's accept syntax; pasted and dropped files are checked against it too.
- `maxImageSize?: number` = 10485760: Largest image in bytes (10 MB); bigger files are refused with labels.imageTooLarge. 0 accepts any size.
- `mentions?: RichTextMentions ({ items: (query: string) => MentionItem[] | Promise<MentionItem[]>; trigger?: string; onMention?: (item: MentionItem) => void })`: Turns on @mentions. items gets the text after the trigger ("@" by default); a promise is awaited with a 120ms pause between keystrokes. Rows show an Avatar, the name and a description; picked people become chips with data-id, styled by the exported MENTION classes.
- `extensions?: AnyExtension[]` = "[]": Extra Tiptap extensions, appended after the built-in ones. Read when the editor is created; a change in their names recreates it.
- `autofocus?: boolean | "start" | "end"` = false: Focuses the editor once it mounts, with the caret at the start or the end.
- `spellCheck?: boolean` = true: The browser's spell checking on the text.
- `setApi?: (api: RichTextEditorApi) => void`: Called after mount with { editor, getHTML, getJSON, getMarkdown, getText, focus(position?), clear(), insertContent(content), isEmpty() }. editor is the Tiptap instance for anything else.
- `label?: ReactNode` = "": The field label above the box; a click on it focuses the text.
- `description?: ReactNode` = "": Helper text under the box, linked with aria-describedby.
- `error?: ReactNode` = "": Replaces the description and marks the field invalid.
- `required?: boolean` = false: The asterisk after the label and aria-required on the text.
- `invalid?: boolean` = false: The invalid ring and aria-invalid without a message.
- `disabled?: boolean` = false: Dims the box; the text cannot be edited or focused.
- `readOnly?: boolean` = false: Renders the content with the same styles and no toolbar or bubble menu: links open in a new tab, checkboxes are locked, the box keeps its variant so a note still reads as a document. To show saved HTML without an editor, put the exported PROSE classes on its wrapper.
- `size?: "sm" | "md" | "lg"` = "md": Text 14 / 15 / 16px (16px on phones at every size) with matching padding and toolbar buttons (28 / 32 / 40px).
- `variant?: "soft" | "outline" | "ghost"` = "outline": outline draws a hairline (a document editor reads best framed), soft is the filled field well, ghost is borderless for a page that is the document.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the box as a surface: 0, 12, 16 or 24px; full falls back to lg.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the pressed toolbar buttons, mention chips, checked boxes, the upload bar, the selection and the caret.
- `color?: string` = "": Any CSS color; replaces the tone.
- `locale?: string` = "": Locale of the counter's numbers (1,240 in en-US). Empty uses the UIProvider's, then the browser's.
- `name?: string` = "": Adds a hidden input with the value in `format` (JSON stringified) for plain form posts.
- `id?: string`: The id of the editable element, which the label points to.
- `fieldProps?: Partial<FieldProps>`: Anything else for the Field wrapper: optional, labelAction, orientation, hideLabel.
- `labels?: Partial<RichTextEditorLabels>`: Every string, English by default (DEFAULT_RICH_TEXT_EDITOR_LABELS): button names (bold "Bold", heading "Text style", paragraph "Normal text", heading1 to heading4, …), link editor (linkPlaceholder, openLink, removeLink, apply, invalidLink, imageUrl), uploads (uploading, uploaded, uploadFailed, imageTooLarge, imageType), counts as functions (characters(count, formatted), words(count, formatted), limit(count, max, formatted, formattedMax), limitNear(remaining, formatted)), limitReached, mentions, noMentions, searching, toolbar, moreFormatting, content (the text's name without a label).
- `classNames?: Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "toolbar" | "button" | "heading" | "content" | "bubble" | "link" | "mentions" | "footer" | "count" | "docked", string>>`: Extra classes for the parts.
- `className?: string`: Extra classes for the box (the Field wrapper when a label, description or error is set).

```tsx
import { useState } from "react"
import { RichTextEditor, type RichTextValue } from "@/components/ui/rich-text-editor"

const team = [
  { id: "mihai-ionescu", label: "Michael Reed", description: "Sales" },
  { id: "ioana-dumitrescu", label: "Julia Davis", description: "Accounting" },
]

export function ClientNote() {
  const [note, setNote] = useState<RichTextValue>("<h2>Meeting, Sep 24, 2026</h2><p>The quote for <strong>Tech Solutions LLC</strong>.</p>")
  return (
    <RichTextEditor
      label="Client note"
      value={note}
      onValueChange={setNote}
      placeholder="Write a note…"
      showCount="both"
      characterLimit={2000}
      mentions={{ items: (q) => team.filter((p) => p.label.toLowerCase().includes(q.toLowerCase())) }}
      onImageUpload={async (file) => URL.createObjectURL(file)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/rich-text-editor (Markdown: https://wingo-ui.com/components/rich-text-editor.md)

#### Schema Builder (`schema-builder`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add schema-builder`

An editor for extraction schemas: named fields with unique keys, field types, JSON types, required flags, nesting and a JSON view.

Each row of the table is a field: Name (the label people read), Unique key, Type (the JSON type it stores, as a badge), a Required switch (a red asterisk marks required names) and Description. The Field type (the control a form shows: text, date, currency, select, address...) is set in Edit details and shown on phone cards. Typing a Name fills the key with its slug (Invoice number gives invoice_number, accents dropped) while the key is empty or still follows the name, marked with a link icon; edit the key and it stays yours. Keys are checked as you type, paste, import and move fields: empty, wrong format, or already used by a sibling (or anywhere, with uniqueKeys="global"), ignoring case and outer spaces. Every field involved is marked, the toolbar counts the problems, and clicking the count, or Enter / Shift+Enter in a marked input, steps through them. Picking a field type adjusts the type (Date stores a string with format date, Multi-select an array of options) and the type list offers what fits first; options typed for a select survive a switch to text and back. Groups, lists of objects and options open under their row from a Configure schema bar, each level a table of its own; the checkbox in the Required header marks a whole level required. Drag the grip on a row's left edge (it shows on hover and focus, always on touch) to reorder or to move a field into or out of a group: a line shows where it lands, in amber when the key already exists there. On touch, long press the grip. From the keyboard, Alt+↑/↓ moves a field, Alt+←/→ (on the grip, selects and the checkbox) moves it out of or into a group, and the ⋯ menu does the same plus Duplicate, Edit details and Delete (a field with children asks first). ⌘Z / ⇧⌘Z (Ctrl+Z / Ctrl+Y) undo and redo inside the builder, Escape in an input puts back what it held. Edit details opens a side panel with the format, placeholder, default value and options. The JSON tab shows the draft 2020-12 schema, highlighted, with Show changes for a diff against the schema it opened with. Import JSON reads a pasted or chosen file and points at the line of an error. Below 560px rows become cards that open the editor in a bottom sheet; menus and selects become bottom sheets on phones.

npm: @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, lucide-react, motion
Wingo UI dependencies: alert-dialog, button, checkbox, code-block, dialog, diff-viewer, dropdown-menu, empty-state, input, json-viewer, select, sheet, switch, tabs, textarea, tooltip, use-controllable-state, use-media-query, motion, tones, ui-config

Props:
- `defaultValue?: SchemaBuilderField[]` = "[]": The fields it opens with while uncontrolled. The playground uses a Northwind Outfitters invoice. Show changes in the JSON tab compares against it.
- `value?: SchemaBuilderField[]`: The fields, controlled. Pair it with onValueChange.
- `onValueChange?: (fields: SchemaBuilderField[]) => void`: Called with the new fields after every edit, move, import, undo and redo.
- `defaultTab?: "form" | "json"` = "form": The tab it opens on: the field table or the JSON Schema.
- `tab?: "form" | "json"`: The tab, controlled. Pair it with onTabChange.
- `onTabChange?: (tab: "form" | "json") => void`: Called when someone switches between Form and JSON.
- `uniqueKeys?: "siblings" | "global"` = "siblings": siblings: a key must be unique among the fields of its level (one group, one list). global: unique in the whole schema.
- `keyPattern?: string` = "^[a-z][a-z0-9_]*$": A regular expression every key must match. The default allows snake_case; the other options camelCase and kebab-case.
- `autoKey?: boolean` = true: The key follows the Name (its slug) while it is empty or unchanged; a link icon marks those keys. Off, keys are only typed by hand.
- `readOnly?: boolean` = false: Shows the schema without editing: no grips, adds, imports or undo. Copy, download and the JSON tab stay.
- `maxDepth?: number` = 5: Levels of nesting allowed, 1 is flat. Deeper fields are reported; moves and drops that would go deeper are refused.
- `defaultExpanded?: boolean` = true: Groups, lists and options open expanded. Off, only the top level shows; collapsed rows count the problems inside them.
- `showToolbar?: boolean` = true: The toolbar with the Form / JSON tabs, the problem count, add, import, copy, download, undo and redo.
- `showImport?: boolean` = true: Import JSON in the toolbar (the ⋯ menu when narrow) and in the empty state.
- `showDownload?: boolean` = true: The download button, which saves the JSON Schema as fileName.
- `fileName?: string` = "schema.json": Name of the downloaded file, also shown in the download button's label.
- `height?: number | string` = 640: Height of the builder: px as a number, any CSS length ("80dvh") to fill a pane, or "auto" to grow with the fields.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `typeColors?: Partial<Record<SchemaBuilderTypeKey, string>>`: Tints for the type badges, any CSS color per type (string, number, enum, array<object>...). Badges are neutral by default, like the rest of the library; set colors to tell types apart at a glance.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: save, publish, test on a document.
- `ref?: Ref<SchemaBuilderHandle> (a useRef object or an (handle) => void callback)`: addField(parentId?), removeField(id), focusField(id, column?), validate() (shows every problem and returns them), getSchema(), getJsonSchema(), importJson(json), reset(), undo() and redo().
- `onJsonSchemaChange?: (schema: SchemaBuilderJsonSchema) => void`: Called with the serialized JSON Schema on open and after every change.
- `onValidationChange?: (errors: SchemaBuilderError[]) => void`: Called on open and whenever the problems change: { id, path, field, code, message, otherId? } for each.
- `onFieldAdd?: (field: SchemaBuilderField, parentId: string | null) => void`: Called when a field is added, duplicated or pasted in, with the group or list it went into (null for the top level).
- `onFieldRemove?: (field: SchemaBuilderField) => void`: Called with a deleted field, children included.
- `labels?: Partial<SchemaBuilderLabels>`: Every string, English by default (DEFAULT_SCHEMA_BUILDER_LABELS): columns, field and JSON type names, menus, editor, import, JSON tab, announcements and every validation message, with functions for the ones that take a value (errorKeyDuplicate(otherName), problems(count)...).
- `classNames?: Partial<Record<"toolbar" | "viewport" | "header" | "row" | "card" | "options" | "json" | "notice" | "editor" | "state", string>>`: Extra classes for the toolbar, the scrolling form, each level header, each row and card, the options editor, the JSON tab, the import notice, the editor panel and the empty state.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `serializeSchema` (function): serializeSchema(fields, options?) returns { schema, errors }: a draft 2020-12 JSON Schema (title from Name, description, format, enum with x-enum-descriptions, items, required on the parent, default, x-placeholder, x-field-type) and the problems. strict: true throws instead when there are any.
- `parseSchema` (function): parseSchema(json, options?) reads a JSON Schema, as text or an object, into fields and never throws: { fields, errors, warnings }. A JSON syntax error comes with its line and column; $ref, allOf and other unsupported parts are reported in warnings.
- `validateSchema` (function): validateSchema(fields, options?) returns every problem in reading order: empty names and keys, key format, duplicate keys (case and outer spaces ignored), options, empty groups, a field type that cannot store the type, nesting past maxDepth.
- `slugifyKey` (function): slugifyKey(name) turns a name into a key: "Invoice number" gives invoice_number, "Preț unitar" gives pret_unitar, a leading digit gets field_.
- `typeKeyOf` (function): typeKeyOf(field) returns the type as one value: "string", "enum", or "array<object>" for an array of objects.
- `SchemaBuilderField` (type): A field: { id, name, key, fieldType, type, required, description, enumValues?, properties?, items?, format?, placeholder?, defaultValue? }. properties holds an object's children, items what an array holds ({ type, properties?, enumValues? }).
- `SchemaBuilderEnumValue` (type): An option of a select, radio or multi-select field: { id, value, description? }.
- `SchemaBuilderFieldType` (type): text, textarea, number, currency, percent, select, multi-select, radio, checkbox, switch, date, datetime, time, email, phone, url, file, signature, address, group or list.
- `SchemaBuilderType` (type): string, number, integer, boolean, null, object, array or enum: the JSON type a field stores.
- `SchemaBuilderError` (type): A problem: { id, path ("vendor.address.city", "line_items[].amount"), field ("name" | "key" | "type" | "enumValues" | "properties"), code, message, otherId? }.
- `SchemaBuilderJsonSchema` (type): What serializeSchema, getJsonSchema() and onJsonSchemaChange give you: { $schema?, type: "object", properties, required? }.
- `SchemaBuilderHandle` (type): What the ref gets: addField, removeField, focusField, validate, getSchema, getJsonSchema, importJson, reset, undo and redo.
- `SchemaBuilderLabels` (type): The shape of labels: every string the builder renders and every message it reports.
- `DEFAULT_SCHEMA_BUILDER_LABELS` (constant): The English labels. Spread it to translate a few strings.
- `SchemaBuilderTypeKey` (type): A type as one value: "string", "enum", "object", "array<object>", "array<enum>", "array<string>"...
- `DEFAULT_KEY_PATTERN` (constant): ^[a-z][a-z0-9_]*$, the key pattern used when keyPattern is not set.

```tsx
import { SchemaBuilder, serializeSchema, type SchemaBuilderField } from "@/components/ui/schema-builder"

const fields: SchemaBuilderField[] = [
  { id: "number", name: "Invoice number", key: "invoice_number", fieldType: "text", type: "string", required: true, description: "The invoice ID" },
  { id: "issued", name: "Issue date", key: "issue_date", fieldType: "date", type: "string", format: "date", required: true, description: "" },
]

export function InvoiceSchema() {
  return (
    <SchemaBuilder
      defaultValue={fields}
      height="80dvh"
      onValueChange={(next) => console.log(serializeSchema(next).schema)}
      onValidationChange={(errors) => console.log(errors.length, "problems")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/schema-builder (Markdown: https://wingo-ui.com/components/schema-builder.md)

### Navigation

#### Back To Top (`back-to-top`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add back-to-top`

A floating button that appears on long pages, rings with your reading progress and takes you, and your focus, back to the top.

Scroll past the threshold and the button pops in on a quick spring, a thin ring around it filling as you read. Click or tap it to glide back to the top; once the scroll settles, focus moves to the page title so keyboard and screen reader users land there too (scroll away mid-way and focus stays put). Tab to it for a focus ring outside the progress ring, and press Enter or Space. With showOn="scroll-up" it stays out of the way while you read down and comes back the moment you flick up. On a phone it is 48px, sits above the bottom tab bar and clears the home indicator. Under reduced motion it only fades and the jump is instant.

npm: motion, lucide-react
Wingo UI dependencies: button, use-scroll-state, motion, tones, ui-config

Props:
- `threshold?: number` = 400: Pixels scrolled before it appears. 0 shows it on any scroll. Content shorter than this never shows it.
- `showOn?: "scroll" | "scroll-up"` = "scroll": scroll: whenever you are past the threshold. scroll-up: only while scrolling up past it (and at the very end), out of the way while reading down, like Safari's toolbars. The recommendation for phones.
- `progress?: boolean` = true: A 2px ring around the button that fills with reading progress, from 12 o'clock. It follows the scroll every frame without re-rendering.
- `variant?: "surface" | "solid" | "glass"` = "surface": surface: the popover surface with a floating shadow, readable over anything. solid: filled with the tone. glass: a translucent blurred surface for photo-heavy pages.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the progress ring, and the fill of the solid variant.
- `color?: string` = "": Any CSS color. Replaces the tone for the ring and the solid fill. Leave empty to use the tone.
- `size?: "sm" | "md" | "lg"` = "md": 40 / 48 / 56px. A floating button never drops below 44px on touch screens, so sm grows to 44px there.
- `radius?: "md" | "lg" | "full"` = "full": Corner shape, scaled with the size like the button's. The progress ring follows it.
- `label?: string` = "Back to top": The accessible name, and the text of the extended pill when showLabel is on.
- `showLabel?: boolean` = false: An extended pill with the label beside the arrow, instead of an icon-only button.
- `icon?: ReactNode`: Replaces the default ArrowUp icon. It nudges up 2px on hover with a mouse.
- `position?: "fixed" | "sticky" | "absolute"` = "fixed": fixed: pinned to the viewport. sticky: render it as the last child of a scroll container and it pins to that container's bottom (panels, cards, demos). absolute: inside a positioned parent.
- `side?: "end" | "start" | "center"` = "end": Logical side, so end is on the left in right-to-left layouts.
- `offset?: number` = 16: Pixels from the edges. Added to the bottom safe area and to --bottom-bar-offset, which a bottom tab bar sets.
- `smooth?: boolean` = true: Smooth scroll back to the top. Always instant when the user prefers reduced motion. The demo's readout shows it.
- `focusTarget?: string | HTMLElement | null` = "h1": Gets focus once the scroll settles: a selector looked up inside the scroll container, or an element. Falls back to the container, then the body; elements that are not focusable get a temporary tabindex. If you scroll away before the top is reached, focus stays put. null leaves focus alone.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls. Default: the nearest ScrollContainerProvider, else (sticky and absolute) the nearest scrolling ancestor, else the window.
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Runs before scrolling. Call event.preventDefault() to cancel the scroll.
- `classNames?: Partial<Record<"button" | "ring" | "icon" | "label", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the positioned wrapper. Other props go to it too.

```tsx
import type { ReactNode } from "react"
import { BackToTop } from "@/components/ui/back-to-top"

export function GhidEFactura({ children }: { children: ReactNode }) {
  return (
    <main>
      <h1>Guide: send your first invoice in 12 steps</h1>
      {children}
      <BackToTop label="Back to the top" showOn="scroll-up" />
    </main>
  )
}
```

Docs: https://wingo-ui.com/components/back-to-top (Markdown: https://wingo-ui.com/components/back-to-top.md)

#### Bounce Sidebar (`bounce-sidebar`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add bounce-sidebar`

A vertical navigation list with a small dot that hops along an arc to the active item.

Click any item to bounce the marker over to it along a short arc. Tab moves between items and Enter or Space selects one. Heading rows are plain labels, so the dot skips past them. Drive the value from the scroll position and the marker follows the section you are reading.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `items: Array<string | { label: string; href?: string } | { label: string; heading: true }>`: Rows rendered as the vertical list. A plain string or an object with a label is a nav item, and href turns it into a link. Add heading: true to render a non-selectable group label the marker skips over.
- `dotColor?: string` = "#FC4C01": Any CSS color for the bouncing active marker (hex, rgb, hsl, var). Heading rows use it for their text too unless headingColor is set.
- `headingColor?: string` = "": Any CSS color for the heading rows. Empty follows dotColor.
- `dotSize?: number` = 6: Diameter of the marker in pixels. It is snapped to the device pixel grid so it stays crisp at any zoom.
- `size?: "sm" | "md" | "lg"` = "md": Text size and row padding: 12px (sm), 14px (md) or 16px (lg) labels. On touch screens every row is at least 44px tall whatever the size, and the dot re-centers on its row by itself.
- `activeColor?: string` = "auto": Text color of the active item, any CSS color. Auto uses the foreground color of the theme.
- `textColor?: string` = "auto": Text color of the other items, any CSS color. Auto is the foreground color at 70% opacity.
- `duration?: number` = 0.25: Seconds the dot takes to hop to a new item. Set it to 0 to jump without travel; reduced motion always jumps.
- `arc?: number` = 14: How far the dot bows out sideways on its hop, in pixels. Short hops are capped so the arc never loops; 0 slides in a straight line.
- `value?: number`: Active item index for controlled usage. When set, the component won't manage its own state. Headings count toward the index.
- `defaultValue?: number` = 0: Initial active index for uncontrolled usage. Ignored when value is provided.
- `onChange?: (index: number) => void`: Called with the new index whenever an item is selected.
- `className?: string`: Extra classes merged onto the root <ul> element. Any other <ul> attribute is passed through too.

Parts:
- `BounceSidebarItem` (type): One row of items: a plain string, { label, href? } for a nav item (href renders a link), or { label, heading: true } for a group label the dot skips.

```tsx
import { BounceSidebar } from "@/components/ui/bounce-sidebar"

const items = [
  { label: "General", heading: true },
  { label: "Home", href: "/" },
  { label: "About", href: "/about" },
]

export function Demo() {
  return <BounceSidebar items={items} defaultValue={1} dotColor="#FC4C01" />
}
```

Docs: https://wingo-ui.com/components/bounce-sidebar (Markdown: https://wingo-ui.com/components/bounce-sidebar.md)

#### Breadcrumb (`breadcrumb`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add breadcrumb`

Where you are in the hierarchy and a one-tap way up: a trail that folds its middle into “…”, sibling switchers and a back link on phones.

Click a crumb to go up a level; the current page is plain text. When the row gets too narrow the middle entries fold into a “…” button, one by one, and come back as soon as there is room; click it (or focus it and press Enter, Space or ArrowDown) for a menu of the hidden pages, walked with the arrow keys and closed with Escape. A crumb with siblings has a small chevron that opens a menu of them with the current one checked. Labels longer than maxItemWidth truncate; hover or focus them (long press on touch) to read the full text. When the trail changes, new crumbs slide in and the others glide into place. Below 640px it becomes one “‹ Parent” back link with a 44px target (or first / … / current), and every menu opens as a bottom action sheet.

npm: @radix-ui/react-slot, lucide-react, motion
Wingo UI dependencies: button, dropdown-menu, tooltip, use-overflow-items, motion, navigation, ui-config

Props:
- `items?: BreadcrumbEntry[]`: { id?: string; label: ReactNode; href?: string; icon?: ReactNode; onSelect?: (event) => void; menu?: NavItem[]; textValue?: string }. Root first; the last entry is the current page. Middle entries without href are plain text (a button with onSelect). menu adds a sibling switcher after the label. An empty label with an icon renders an icon-only crumb named by textValue (read by screen readers, shown in a tooltip). Leave items out to hand-build the trail from the parts.
- `children?: ReactNode`: A hand-built trail from the shadcn-compatible parts, rendered inside the <nav> when items is not set. BreadcrumbList: the <ol>. BreadcrumbItem: one crumb's <li>. BreadcrumbLink (NavLinkProps & { href?; asChild?; linkComponent? }): a crumb link through NavLink, asChild styles your own element, without href it is a button. BreadcrumbPage: the current page, text with aria-current="page". BreadcrumbSeparator ({ kind? }): an aria-hidden <li role="presentation"> with the Breadcrumb's glyph. BreadcrumbEllipsis ({ items?; open?; onOpenChange?; responsive? }): the “…” button with a menu of the given entries, the bare glyph without items.
- `separator?: "chevron" | "slash" | "dot" | "arrow" | ReactNode` = "chevron": The glyph between crumbs: ChevronRight, “/”, “·”, ArrowRight or any node. Chevron and arrow flip in right-to-left layouts.
- `size?: "sm" | "md"` = "md": Text 13 / 14px with 4 / 6px gaps. Icons stay 14px.
- `maxItemWidth?: number` = 200: px. Longer labels truncate with an ellipsis and show the full text in a tooltip.
- `collapse?: "auto" | "never"` = "auto": auto: while the row does not fit, entries fold into “…” from the second one onward; the first and the current page always stay. never: the trail wraps onto more lines.
- `maxItems?: number` = 0: Also fold when there are more entries than this, keeping itemsBeforeCollapse at the start and itemsAfterCollapse at the end. 0 folds only when the row does not fit. Ignored when it is smaller than itemsBeforeCollapse + itemsAfterCollapse + 1.
- `itemsBeforeCollapse?: number` = 1: Entries kept at the start when folding by maxItems.
- `itemsAfterCollapse?: number` = 2: Entries kept at the end when folding by maxItems (the parent and the current page).
- `mobileVariant?: "back" | "collapse" | "full"` = "back": What phones get, switched with CSS so the server HTML is right. back: one “‹ Parent” link to the second-to-last entry (falls back to collapse when that entry has no href). collapse: first / … / current. full: the desktop trail.
- `mobileBreakpoint?: "sm" | "md" | "always"` = "sm": Where the phone form takes over: below 640px (sm), below 768px (md), or at every width (always, for narrow side panels).
- `animate?: boolean` = true: When the trail changes, new crumbs slide in from the side and the rest glide into place; leaving ones fade. Under reduced motion it only fades.
- `responsive?: boolean` = true: The “…” and sibling menus open as bottom action sheets below 768px. false keeps the dropdown everywhere.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link every crumb renders through (next/link's Link). Default: the LinkProvider's, else a plain <a>.
- `labels?: { navigation?: string; more?: string; back?: (label: string) => string; siblings?: (label: string) => string; cancel?: string }`: Accessible names and sheet text. Defaults: navigation "Breadcrumb", more "Show hidden pages", back l => "Back to " + l, siblings l => "Switch " + l, cancel "Cancel".
- `classNames?: Partial<Record<"list" | "item" | "link" | "page" | "separator" | "ellipsis" | "back", string>>`: Extra classes for the inner parts; className styles the <nav>.

```tsx
import { Home } from "lucide-react"
import { Breadcrumb, type BreadcrumbEntry } from "@/components/ui/breadcrumb"
import type { NavItem } from "@/lib/navigation"

const clients: NavItem[] = [
  { label: "Northwind Tech Inc.", href: "/clients/42" },
  { label: "Summit Logistics", href: "/clients/57" },
  { label: "Anna Price Consulting", href: "/clients/63" },
]

export function InvoiceTrail() {
  const items: BreadcrumbEntry[] = [
    { label: "Home", href: "/", icon: <Home /> },
    { label: "Clients", href: "/clients" },
    { label: "Northwind Tech Inc.", href: "/clients/42", menu: clients },
    { label: "Invoices", href: "/clients/42/invoices" },
    { label: "#2026-0412" },
  ]

  return (
    <Breadcrumb
      items={items}
      labels={{
        more: "Show the hidden pages",
        back: (label) => `Up to ${label}`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/breadcrumb (Markdown: https://wingo-ui.com/components/breadcrumb.md)

#### Command Menu (`command-menu`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add command-menu`

The ⌘K palette: search and run anything with groups, shortcuts, nested pages, async results and recents, and a full-height sheet on phones.

Press ⌘K (Ctrl+K elsewhere) or click the search field to open it near the top of the screen. Type to filter: case and diacritics never matter and the matched letters turn bold; results from the server appear under the commands with a spinner in the input while they load. Arrow keys (and Ctrl+N / Ctrl+P) move, Home / End jump, Enter runs, and an item's own shortcut runs it while the menu is open. Items with a chevron open a page: its title appears as a chip before the input, Backspace on an empty input or Escape goes back, and Escape on the first page closes. Recently picked items come first next time (server results for the rest of the session). On a phone it opens as a full-height sheet with the keyboard already up, 48px rows and a Cancel button; swipe it down to close.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, cmdk, lucide-react, motion
Wingo UI dependencies: badge, drawer, kbd, spinner, motion, navigation, text-match, use-controllable-state, use-debounce, use-media-query, use-persisted-state, use-shortcut, ui-config

Props:
- `groups?: CommandGroup[]`: The root page: groups of { id?, label?, items }. An item is { id, label, icon?, description?, badge?, keywords?, shortcut?, href?, external?, page?, onSelect?, tone?, disabled?, closeOnSelect? }. The file also exports commandItemsFromNav(items: NavItem[], { nested?, separator? }): the app's navigation as items for a “Go to” group (href, icon, badge, keywords and shortcut; nested items read “Invoices › Overdue”).
- `pages?: CommandPage[]`: Pages pushed by items with page: { id, title, placeholder?, groups?, loadItems? }. A page's own groups and loader replace the root ones.
- `trigger?: ReactNode`: Rendered asChild as the trigger. The file also exports CommandMenuTrigger, the ready-made one (placeholder?, shortcut?, size? sm | md | lg, variant? soft | outline | ghost, radius?, icon?, responsive?, plus button props): a field-looking button (“Search or jump to…  ⌘K”) that shows the enclosing menu's shortcut and folds to an icon button below 768px. It also works next to a controlled menu.
- `loadItems?: (query: string, context: { signal: AbortSignal; page: string | null }) => Promise<CommandGroup[]>`: Async results shown after the static groups (clients, invoices). Debounced, and the previous request is aborted. On the root page it runs once the query is not empty; errors show a row with Try again.
- `debounce?: number` = 200: Milliseconds of quiet typing before loadItems runs.
- `defaultOpen?: boolean` = false: Starts open. Use open and onOpenChange to control it.
- `open?: boolean`: Controlled open state; pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Fires when the menu opens or closes.
- `page?: string | null`: The open page (null is the root), for opening straight into one. Pair it with onPageChange; defaultPage for uncontrolled.
- `defaultPage?: string | null` = "": The page it opens on while uncontrolled (a page id; empty is the root, an unknown id is ignored). It returns there every time it reopens. The demo has the tema and limba pages.
- `onPageChange?: (page: string | null) => void`: Fires when a page is pushed or popped.
- `query?: string`: Controlled search text; defaultQuery and onQueryChange complete the pair.
- `defaultQuery?: string` = "": Search text it opens with while uncontrolled; the input is back to it every time it reopens.
- `onQueryChange?: (query: string) => void`: Fires on every keystroke in the input (and when a page push or pop clears it).
- `shortcut?: string` = "mod+k": Toggles the menu from anywhere (⌘K on Apple devices, Ctrl+K elsewhere). "" binds nothing. The showcase binds ⌘K itself, so the demo uses ⌘J while this is mod+k.
- `placeholder?: string` = "Type a command or search…": The input placeholder on the root page; a page can set its own.
- `emptyText?: string` = "No results": Shown when nothing matches.
- `loadingText?: string` = "Searching…": Shown while loadItems runs and nothing else is listed yet; also the spinner's accessible name.
- `recent?: boolean` = true: A Recent group of the last picked items (by id) while the query is empty on the root page. Page pushers are not recorded.
- `recentKey?: string` = "command-menu:recent": Local storage key for the recents (use-persisted-state). "" keeps them in memory for the session.
- `maxRecent?: number` = 5: How many recent items to show.
- `footer?: boolean` = true: The key hints bar (↑↓ navigate, ↵ open, esc close) and the result count. Fine pointers only; never on the phone sheet.
- `size?: "sm" | "md" | "lg"` = "md": Width 480 / 640 / 800px (the sheet from 768px with mode sheet: 420 / 560 / 720px).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "lg": Corner radius of the panel (0 / 12 / 16 / 24px) and, scaled down, of its rows and the phone search field. full keeps the 24px panel with pill rows.
- `highlightMatches?: boolean` = true: Matched letters in bold. Matching ignores case and diacritics, so “cafe” highlights “Café”.
- `globalShortcuts?: boolean` = false: Also binds every item's shortcut on the page while mounted, even closed (a bare key only outside text fields). Off: item shortcuts work only while the menu is open.
- `loop?: boolean` = true: Arrow keys wrap from the last item to the first.
- `responsive?: boolean` = true: A full-height bottom sheet below 768px, with the keyboard raised at once.
- `mode?: "auto" | "dialog" | "sheet"` = "auto": auto: the dialog from 768px and the sheet below (with responsive). dialog or sheet: that at every width.
- `inline?: boolean` = false: Renders the palette in place instead of a dialog (a help page, a sidebar search). open and the shortcut are ignored; Escape clears.
- `filter?: (item: CommandItem, query: string) => (number | null)`: Custom ranking: higher first, null hides. Default: text-match over the label, keywords, description and the shortcut, best first inside each group.
- `onSelect?: (item: CommandItem) => void`: After every pick (not page pushes), once the item's own onSelect settled.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Router link for href items; defaults to the LinkProvider's. Clicks go through the link (cmd-click opens a new tab), Enter through useNavigate.
- `container?: HTMLElement | null`: Portal target, default document.body.
- `labels?: { title?; navigate?; select?; close?; back?; clear?; cancel?; recent?; error?; retry?; results?: (n) => string }`: Every other visible or spoken string: the hidden dialog title ("Command menu"), the footer hints (clear is the esc hint of an inline palette), the sheet's Cancel, the Recent heading, the error row and the announced result count.
- `classNames?: Partial<Record<"overlay" | "content" | "header" | "breadcrumb" | "input" | "spinner" | "esc" | "list" | "group" | "groupHeading" | "item" | "icon" | "label" | "description" | "badge" | "shortcut" | "empty" | "loading" | "error" | "footer", string>>`: Extra classes for the inner parts.

```tsx
"use client"

import { FilePlus2, Moon, Sun, UserPlus } from "lucide-react"
import { useTheme } from "next-themes"
import { CommandMenu, CommandMenuTrigger, commandItemsFromNav, type CommandGroup } from "@/components/ui/command-menu"
import type { NavItem } from "@/lib/navigation"

const nav: NavItem[] = [
  { label: "Clients", href: "/clients" },
  { label: "Invoices", href: "/invoices", items: [{ label: "Overdue", href: "/invoices/overdue" }] },
]

export function AppCommandMenu() {
  const { setTheme } = useTheme()
  const groups: CommandGroup[] = [
    { label: "Go to", items: commandItemsFromNav(nav) },
    {
      label: "Actions",
      items: [
        { id: "new-client", label: "New client", icon: <UserPlus />, href: "/clients/new" },
        { id: "new-invoice", label: "New invoice", icon: <FilePlus2 />, shortcut: "shift+mod+f", href: "/invoices/new" },
        { id: "theme", label: "Theme…", icon: <Moon />, page: "theme" },
      ],
    },
  ]
  return (
    <CommandMenu
      groups={groups}
      pages={[
        {
          id: "theme",
          title: "Theme",
          groups: [
            {
              items: [
                { id: "light", label: "Light", icon: <Sun />, onSelect: () => setTheme("light") },
                { id: "dark", label: "Dark", icon: <Moon />, onSelect: () => setTheme("dark") },
              ],
            },
          ],
        },
      ]}
      loadItems={async (query, { signal }) => {
        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal })
        const clients: { id: string; name: string; city: string }[] = await res.json()
        return [{ label: "Clients", items: clients.map((c) => ({ id: c.id, label: c.name, description: c.city, href: `/clients/${c.id}` })) }]
      }}
      placeholder="Type a command or search…"
      trigger={<CommandMenuTrigger placeholder="Search or jump to…" />}
    />
  )
}
```

Docs: https://wingo-ui.com/components/command-menu (Markdown: https://wingo-ui.com/components/command-menu.md)

#### Global Search (`global-search`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add global-search`

The search field of an app header: grouped results from every entity as you type, scopes, recents and suggestions, full-screen on phones.

Press / (or click the field) and it grows from its resting width on a smooth spring; with the query still empty the panel shows your recent searches and quick suggestions. Type and results arrive grouped (clients, contacts, offers, invoices) with the matched letters bold, a spinner in the field while the server answers and a “See all 24” row closing each long group. Arrow keys move, Enter opens the highlighted result or, with nothing highlighted, searches everywhere (the footer row does the same). Tab and Shift+Tab switch the scope chips while the panel is open; Escape closes the panel, a second Escape clears the text and a third leaves the field. Recents remember submitted queries and opened results; remove one with its × or Delete, or clear them all. On a phone the search is an icon (or a full-width field) that opens a full-screen search with the keyboard already up, 48px rows, sideways-scrolling scopes (with a keyboard, Tab reaches them and the arrow keys switch) and a Cancel button; Escape closes it.

npm: @radix-ui/react-dialog, @radix-ui/react-popover, @radix-ui/react-visually-hidden, lucide-react, motion
Wingo UI dependencies: ui-config, button, field, kbd, listbox, spinner, motion, navigation, text-match, use-controllable-state, use-debounce, use-locale, use-media-query, use-persisted-state, use-shortcut

Props:
- `results?: SearchResultGroup[]`: Static results filtered locally as you type (label, textValue, keywords and a text description; case and diacritics never matter). A group is { id?, label, items, total?, href? }; a result is a listbox option { value, label, description?, icon?, badge?, keywords? } plus href?, external? and meta? (a trailing amount or date).
- `loadResults?: (query: string, context: { signal: AbortSignal; scope: string }) => Promise<SearchResultGroup[]>`: Server search, used instead of results: debounced, the previous request aborted, the last 20 answers cached, the old results kept while the new ones load; a rejected promise shows an error with Try again. A group with href and total > items.length ends in a See all row.
- `suggestions?: SearchResult[]`: Quick links under the recents while the query is empty (“Overdue invoices”, “New clients this month”).
- `scopes?: SearchScope[]`: Chips above the results ({ value, label, icon? }): loadResults gets the scope; static results narrow to the group whose id equals it (any other value, like “all”, keeps every group).
- `placeholder?: string` = "Search": The field's placeholder and accessible name, also on the phone trigger.
- `labels?: Partial<GlobalSearchLabels>`: Every string: title, recent, suggestions, seeAll(total, label), searchFor(query, scope?), cancel, clearRecent, removeRecent, noResults(query), results(count, formatted), scopeHint, scopes, searchIn(scope), navigate, open, close, clear, loading, error, retry, minQuery(min), idle. English defaults.
- `size?: "sm" | "md" | "lg"` = "md": The field box: 32 / 40 / 48px (md is 44px on touch).
- `variant?: "soft" | "outline" | "ghost"` = "soft": The field look: a filled well, an outlined box, or bare until hovered.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the field, scaled with its size like the button's.
- `width?: number` = 320: Resting width of the desktop field in px (capped by its container).
- `expandedWidth?: number` = 480: Width while focused or open, and the minimum width of the results panel. The field grows to it on a spring.
- `mobileTrigger?: "icon" | "field"` = "icon": Phones: a 44px search icon for a bar, or a full-width field-looking button; both open the full-screen search.
- `showShortcut?: boolean` = true: The key hint at the end of the field while it is empty and not focused (never on touch).
- `highlightMatches?: boolean` = true: Matched letters of string labels in bold.
- `defaultOpen?: boolean` = false: Starts with the panel (desktop) or the full-screen search (phones) open. Use open and onOpenChange to control it.
- `open?: boolean`: Controlled open state of the panel or overlay; pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Fires when the panel or overlay opens or closes.
- `value?: string`: Controlled query; defaultValue (default "") and onValueChange complete the pair.
- `defaultValue?: string` = "": The query it starts with while uncontrolled.
- `onValueChange?: (value: string) => void`: Fires on every keystroke, and when a recent query is picked or the text is cleared.
- `scope?: string`: Controlled scope (a scope value); defaultScope (default: the first scope) and onScopeChange complete the pair.
- `defaultScope?: string` = "": The scope it starts in while uncontrolled; empty means the first scope. The demo's scopes are all (the first), clients, contacts, proposals and invoices.
- `onScopeChange?: (scope: string) => void`: Fires when a chip is picked or Tab cycles the scope.
- `disabled?: boolean` = false: Dims the field, ignores input and the shortcut.
- `onSubmit?: (query: string, scope: string) => void`: Enter with nothing highlighted, or the “Search for … everywhere” row: go to your full results page.
- `onSelect?: (result: SearchResult) => void`: A result or suggestion was picked. Default: navigate to result.href through the LinkProvider's router (external links in a new tab).
- `debounce?: number` = 250: Milliseconds of quiet typing before loadResults runs.
- `minQueryLength?: number` = 1: Characters needed before results are searched; shorter queries show a hint and the recents stay hidden.
- `shortcut?: string` = "/": Focuses the field from anywhere (opens the full-screen search on phones), never while typing in another field. "" binds nothing. The showcase binds “/” itself, so the demo uses S while this is “/”.
- `recent?: boolean` = true: Remembers submitted queries and opened results, shown while the query is empty (a repeat moves to the top).
- `recentKey?: string` = "global-search:recent": Local storage key for the recents (use-persisted-state), synced across tabs. "" keeps them in memory.
- `maxRecent?: number` = 5: How many recents to keep.
- `defaultRecent?: string[]`: Recent queries shown while nothing is stored yet (first visit, onboarding).
- `onRecentChange?: (recent: GlobalSearchRecent[]) => void`: Fires when a recent is added, removed or cleared, e.g. to sync them to the user's account.
- `responsive?: boolean` = true: Below 768px the field becomes the phone trigger and opens a full-screen search.
- `mode?: "auto" | "popover" | "overlay"` = "auto": auto follows the screen (with responsive); popover keeps the field and its panel everywhere; overlay always uses the phone trigger and the full-screen search.
- `locale?: string` = "": Formats the result counts in the footer and the announcements (“1,240 results”). Empty: the LocaleProvider's, else the browser's.
- `container?: HTMLElement | null`: Portal target of the panel and the full-screen search. Default document.body.
- `classNames?: Partial<Record<GlobalSearchSlot, string>>`: Classes per part: box, input, icon, shortcut, clear, content, scopes, scope, list, group, result, seeAll, recent, recentRemove, clearRecent, status, footer, searchFor, mobileTrigger, overlay, cancel.

```tsx
"use client"

import { Building2, FileWarning, Receipt } from "lucide-react"
import { GlobalSearch, type SearchResultGroup } from "@/components/ui/global-search"

type Hit = { id: string; name: string; city: string }

export function HeaderSearch() {
  return (
    <GlobalSearch
      placeholder="Search Acme CRM"
      scopes={[
        { value: "all", label: "All" },
        { value: "clients", label: "Clients", icon: <Building2 /> },
        { value: "invoices", label: "Invoices", icon: <Receipt /> },
      ]}
      loadResults={async (query, { signal, scope }): Promise<SearchResultGroup[]> => {
        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}&scope=${scope}`, { signal })
        const data: { clients: Hit[]; total: number } = await res.json()
        return [
          {
            id: "clients",
            label: "Clients",
            total: data.total,
            href: `/clients?q=${encodeURIComponent(query)}`,
            items: data.clients.map((c) => ({ value: c.id, label: c.name, description: c.city, href: `/clients/${c.id}` })),
          },
        ]
      }}
      suggestions={[{ value: "overdue", label: "Overdue invoices", icon: <FileWarning />, href: "/invoices/overdue" }]}
      onSubmit={(query) => console.log("search everywhere:", query)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/global-search (Markdown: https://wingo-ui.com/components/global-search.md)

#### Gooey Nav (`gooey-nav`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add gooey-nav`

A gooey navigation bar that pulls the selected item away from the rest of the group.

Click an item to lift it out of the bar. A gap opens on each side of it, a stretchy neck thins and snaps as the tiles part, and the rest close back into one piece behind it. With hrefs, the nav follows the current URL on its own. On phones the demo docks it under a page as a stacked, full width tab bar.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `items: (string | { label: string; href?: string; icon?: ReactNode })[]`: Nav entries. A string is a button, an object with href is a link, and icon renders before the label.
- `size?: "xs" | "sm" | "md" | "lg"` = "md": Scale of the bar. Sets the label padding, text size and icon size, and picks the matching separation and radius so the shape stays in proportion. Use xs on phones, where it fits a 360px screen.
- `layout?: "inline" | "stacked"` = "inline": Inline puts the icon beside the label. Stacked puts it above, like a phone tab bar, which keeps four items inside a 360px screen at sm.
- `fullWidth?: boolean` = false: Stretches the bar across its container and shares the width between the items, for a bar docked to the bottom of a screen.
- `activeColor?: string` = "#FC4C01": Fill of the selected tile. The unselected bar follows barColor.
- `activeLabelColor?: string` = "#ffffff": Label color of the selected item. Set it when a light activeColor leaves white text unreadable.
- `barColor?: string` = "": Any CSS color for the unselected tiles and the necks between them. Empty follows the theme: #F4F4F9 light, #262626 dark.
- `labelColor?: string` = "": Any CSS color for the unselected labels. Empty uses #6E6D7A light, #9B9AA7 dark.
- `separation?: number` = 20: Gap in pixels that opens on each side of the selected item, which is what pushes the rest of the bar aside. Leave it out to follow the size: 14 (xs), 16 (sm), 20 (md), 24 (lg). A value you pass overrides the size preset.
- `radius?: number` = 12: Corner radius of the tiles in pixels. Only the outer corners of the bar and the corners along an open gap use it; a closed seam sits at 0 so the tiles read as one shape. Leave it out to follow the size: 8 (xs), 10 (sm), 12 (md), 14 (lg). A value you pass overrides the size preset.
- `value?: number`: Index of the selected item. Pass it to control the nav yourself; leave it out and the nav follows the URL when the items have hrefs, and its own state otherwise.
- `defaultValue?: number` = 0: Index the nav starts on when it is uncontrolled. Ignored once value is passed, and ignored when an item href matches the current URL.
- `onChange?: (index: number) => void`: Fires with the index of the item that was clicked.
- `className?: string`: Extra classes merged onto the root element (data-slot="gooey-nav"). The bar sizes to its content and never wraps, so add an overflow container around it if it can outgrow its parent.

Parts:
- `GooeyNavItem` (type): One entry of items: a plain string (a button), or { label, href?, icon? } where href renders a link and icon sits before the label.

```tsx
"use client"

import { House } from "lucide-react"
import { GooeyNav } from "@/components/ui/gooey-nav"

export function Demo() {
  return (
    // hrefs make it track the url on its own, no value needed
    <GooeyNav
      items={[
        { label: "Home", href: "/", icon: <House /> },
        { label: "Changelog", href: "/changelog" },
        { label: "About", href: "/about" },
      ]}
    />
  )
}

// strings render buttons instead, for a segmented control:
// <GooeyNav items={["Day", "Week", "Month"]} onChange={setRange} />

// size is a single value, so step it down yourself on small screens:
// <GooeyNav items={items} size={useIsMobile() ? "xs" : "md"} />

// or dock it under a phone screen like a tab bar:
// <GooeyNav items={items} size="sm" layout="stacked" fullWidth />
```

Docs: https://wingo-ui.com/components/gooey-nav (Markdown: https://wingo-ui.com/components/gooey-nav.md)

#### Hook Sidebar (`hook-sidebar`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add hook-sidebar`

A vertical navigation list with a dashed rail that hooks into the active item.

Click an item to spring the accent rail down to it. Hovering or tabbing to another row draws a second, dimmer rail that stops where the accent one ends. When the items have hrefs, the rail follows the current route on its own.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `items: Array<string | { label: string; href?: string }>`: Rows rendered as the vertical list. A plain string or an object with a label is a nav item, and href turns it into a link.
- `label?: string` = "": Group title shown above the list, outside the rail. Leave it empty for a bare list. Also names the nav for screen readers.
- `color?: string` = "#FC4C01": Any CSS color for the active rail (hex, rgb, hsl, var). The hover rail stays neutral.
- `dashed?: boolean` = true: Draws the rail and its corner as dashes. Set false for a solid line.
- `size?: "sm" | "md" | "lg"` = "md": Row text size and padding: 12px (sm), 14px (md) or 16px (lg) labels. On touch screens every row is at least 44px tall.
- `textColor?: string` = "auto": Color of the rows that are not active, any CSS color. Auto is the foreground at 70% opacity, so it follows the light and dark theme.
- `activeTextColor?: string` = "auto": Color of the active row and of any row under the pointer, any CSS color. Auto is the foreground color.
- `hoverColor?: string` = "auto": Color of the dimmer rail drawn to the row under the pointer or focus, any CSS color. Auto is the foreground at 30% opacity.
- `gap?: number` = 2: Space between rows in pixels. The rail re-measures and springs to the new row centers.
- `cornerRadius?: number` = 6: Radius in pixels of the curve where the rail turns into the active row, and how far the rail stops short of the row's center.
- `value?: number`: Active item index for controlled usage. When set, it wins over both the URL and internal state. Pass -1 to hide the accent rail.
- `defaultValue?: number` = 0: Initial active index. Used only when no item has an href and value is not provided.
- `onChange?: (index: number) => void`: Called with the new index whenever an item is selected.
- `className?: string`: Extra classes merged onto the root <nav> element. Any other <nav> attribute is passed through too.

Parts:
- `HookSidebarItem` (type): One entry of items: a plain string (a button), or { label, href? } where href renders a link that is active on its own route.

```tsx
import { HookSidebar } from "@/components/ui/hook-sidebar"

// any item with an href makes the rail follow the current route
const display = [
  { label: "Folder", href: "/folder" },
  { label: "Code block", href: "/codeblock" },
]

const navigation = [{ label: "Gooey nav", href: "/gooeynav" }]

// one HookSidebar per group, stacked
export function Demo() {
  return (
    <div className="flex flex-col gap-5">
      <HookSidebar label="Display" items={display} />
      <HookSidebar label="Navigation" items={navigation} />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/hook-sidebar (Markdown: https://wingo-ui.com/components/hook-sidebar.md)

#### Nav Menu (`nav-menu`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add nav-menu`

A website's horizontal navigation: links and dropdown panels (lists or mega menus with a featured card) that morph through one shared panel.

Point at a menu and after a short delay its panel drops in; slide to the next one and the same panel glides under it, resizes to the new content and swaps it with a short slide in the direction you moved. A soft pill (or an underline) follows the pointer between triggers and rests on the section you are in. Click a link and the panel closes while the active item updates. With the keyboard, Tab reaches every trigger and link, ArrowLeft / ArrowRight move between triggers, Enter or Space opens a panel and Tab moves into it, ArrowDown opens it and lands on its first link, arrows move between its links and Escape closes it and returns focus. When the bar is narrower than the breakpoint (a phone) a hamburger takes the list's place: tap it and a full-screen menu slides in from the right with one accordion section per menu, 48px rows, the actions stacked full width at the bottom, and the section you are in already open. Choosing a link, tapping the close button, swiping the menu right or Escape closes it. Under reduced motion panels fade without sliding and resize at once.

npm: @radix-ui/react-navigation-menu, motion, lucide-react
Wingo UI dependencies: accordion, badge, button, sheet, use-controllable-state, motion, navigation, ui-config

Props:
- `items: NavMenuItem[]`: Top-level entries, the shared NavItem shape (id, label, href, icon, description, badge, disabled, external, match, onSelect, items) plus content (replaces the generated panel), featured ({ title, description?, image?, href, badge? }: a 16:10 card next to the links, a compact row in the phone menu) and columns (1 | 2 | 3; default 2 above 4 links, else 1). An item with items (or content) becomes a dropdown whose panel lists them; with an href as well, the panel starts with a "View all" row to it. Otherwise it is a link.
- `value?: string`: The active item's key (navItemKey: id, else href, else the label), at any depth. Controls the active state.
- `defaultValue?: string` = "": The active item's key (navItemKey: id, else href, else the label) while uncontrolled and no current path is known; clicks then move it. Empty: the first enabled item. Ignored under a router: the playground drops its pretend router's path while this is set. Try /pricing or Solutions.
- `onValueChange?: (key: string, item: NavItem) => void`: Fires on every link or row activation, in every mode (controlled, router, uncontrolled).
- `currentPath?: string` = "": The current pathname. Empty: the LinkProvider's. With a path the router decides what is active (the longest matching href) and the top-level item above it gets the active look. Try /pricing or /product/reports.
- `logo?: ReactNode`: The start slot, usually a link home. Repeated in the phone menu's header.
- `actions?: ReactNode`: The end slot ("Log in", "Try it free"). In the phone menu the same buttons stack full width at 48px, the last one on top.
- `mobileActions?: ReactNode`: Replaces actions in the phone menu's footer.
- `viewport?: boolean` = true: One shared panel that follows the open trigger and morphs between menus (the Stripe header). Off: each panel opens as its own surface under its trigger.
- `indicator?: "pill" | "underline" | "none"` = "pill": The highlight that slides between hovered and open triggers on a smooth spring and rests on the active section: a soft pill, a 2px underline, or nothing (color only).
- `size?: "sm" | "md"` = "md": Triggers 32 / 36px and the bar 56 / 64px. Triggers grow to 44px on touch screens.
- `align?: "start" | "center" | "end"` = "center": Where the list sits between logo and actions. center keeps it in the middle of the bar.
- `mobileBreakpoint?: "md" | "lg"` = "md": Below this width of the bar (768 / 1024px) the hamburger and the full-screen menu replace the list and actions, with CSS container queries, so the server HTML is already right. Use lg when the items do not fit a tablet.
- `delayDuration?: number` = 150: Milliseconds of hover before a panel opens, so a pointer passing over the bar does not flash menus.
- `skipDelayDuration?: number` = 300: Milliseconds after leaving a trigger during which the next one opens at once, without the delay.
- `defaultMobileOpen?: boolean` = false: Starts with the phone menu open (uncontrolled).
- `mobileOpen?: boolean`: The phone menu's open state, controlled. Pair with onMobileOpenChange.
- `onMobileOpenChange?: (open: boolean) => void`: Fires when the phone menu opens or closes (hamburger, close button, a chosen link, swipe, Escape).
- `modal?: boolean` = true: The phone menu traps focus, locks the page scroll and dims the page. Turn it off for inline previews of the open menu.
- `container?: HTMLElement | null`: Where the phone menu portals to, e.g. a phone frame. Default: document.body.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders every link through this component (a router Link) instead of the LinkProvider's.
- `labels?: { navigation?: string; openMenu?: string; closeMenu?: string; menu?: string; viewAll?: string }`: Every string: the nav's aria-label ("Main"), the hamburger ("Open menu" / "Close menu"), the phone menu's hidden title ("Menu") and the first row of a panel whose item has its own page ("View all").
- `classNames?: Partial<Record<"logo" | "list" | "item" | "trigger" | "link" | "chevron" | "indicator" | "viewport" | "content" | "panelLink" | "featured" | "actions" | "mobileTrigger" | "sheet" | "sheetLink" | "sheetActions", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the bar (the <nav>), merged last.

```tsx
import { Calculator, FileText, Receipt } from "lucide-react"
import { Button } from "@/components/ui/button"
import { NavMenu, type NavMenuItem } from "@/components/ui/nav-menu"
import { NavLink } from "@/lib/navigation"

const items: NavMenuItem[] = [
  {
    label: "Product",
    items: [
      { label: "Invoicing", href: "/billing", icon: <FileText />, description: "Invoices and estimates in 30 seconds" },
      { label: "E-invoicing", href: "/e-invoicing", icon: <Receipt />, description: "Sent and validated automatically" },
      { label: "Reports", href: "/reports", icon: <Calculator />, description: "Payments, sales tax and overdue" },
    ],
    featured: {
      title: "New: e-invoices sent automatically",
      description: "Every invoice reaches your client with zero extra clicks.",
      image: "/demo/laptop.jpg",
      href: "/news/e-invoicing",
    },
  },
  { label: "Pricing", href: "/pricing" },
  { label: "Contact", href: "/contact" },
]

export function SiteHeader() {
  return (
    <header className="sticky top-0 z-sticky border-b border-foreground/10 bg-background px-4 md:px-6">
      <NavMenu
        items={items}
        logo={<NavLink href="/" className="text-[15px] font-semibold">SimpleInvoice</NavLink>}
        actions={
          <>
            <Button variant="ghost" size="sm">Log in</Button>
            <Button size="sm">Try it free</Button>
          </>
        }
      />
    </header>
  )
}
```

Docs: https://wingo-ui.com/components/nav-menu (Markdown: https://wingo-ui.com/components/nav-menu.md)

#### Nav Tabs (`nav-tabs`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add nav-tabs`

Tabs that are links: the sections of a page or a record that change the URL, with the look of the tabs and the semantics of navigation.

Click a tab and the URL changes: the indicator glides to it on a smooth spring and the page below swaps. Every tab is a real link in the tab order (middle click opens it in a new tab); with focus on a tab, Left / Right move to the neighbour and Home / End jump to the first and last, Enter follows the link. Too many tabs scroll sideways with soft edge fades and the active one is kept in view, or, with overflow set to menu, the ones that do not fit fold into a More menu that becomes a bottom sheet on a phone. On touch every tab is 44px tall. Sticky tabs stay pinned under the top bar on a glass background while the page scrolls.

npm: motion, lucide-react
Wingo UI dependencies: badge, dropdown-menu, navigation, use-controllable-state, use-overflow-items, use-scroll-edges, motion, tones, ui-config

Props:
- `items?: NavTabsItem[]`: The tabs (NavItem from lib/navigation): label, href, icon, activeIcon, badge (a number renders a count), disabled, external, match, onSelect. Children are ignored. Items without href render buttons that call onSelect.
- `value?: string`: The active tab's key (id, else href, else the label). Controls the tabs; otherwise the current path decides.
- `defaultValue?: string`: The first active tab when no path is known (no LinkProvider, no currentPath). Default: the first enabled item.
- `onValueChange?: (key: string, item: NavTabsItem) => void`: Runs on every activation, in all three modes (controlled, routed, uncontrolled).
- `currentPath?: string` = "": The current pathname. Empty: the LinkProvider's. The tab whose href matches it most specifically is active and clicks store nothing. Try /setari/securitate.
- `variant?: "underline" | "pill" | "segmented"` = "underline": underline for page sections, pill for lighter filters, segmented for a compact switch. Class for class the tabs looks.
- `size?: "sm" | "md" | "lg"` = "md": 32 / 40 / 48px tabs with the matching type and icon size. On touch md grows to 44px and sm keeps its look with a 44px hit area.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The indicator color: the underline bar, the pill fill or the segmented thumb. Neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the indicator; replaces the tone. Leave empty to use the tone.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The pill and segmented shapes, scaled with the size (md is 8 / 10 / 12px). The underline bar is always round.
- `bordered?: boolean` = true: Underline only: the hairline baseline under the whole row.
- `fullWidth?: boolean` = false: Tabs share the width equally. The usual choice for two to four segments on a phone.
- `align?: "start" | "center"` = "start": Where the tabs sit when they are narrower than the row.
- `sticky?: boolean` = false: Sticks to the top of the scrolling area under the top bar (top: var(--topbar-offset, 0px), which the topbar writes) on a glass background.
- `overflow?: "scroll" | "menu"` = "scroll": What happens when the tabs do not fit. scroll: the row scrolls sideways with edge fades and keeps the active tab in view. menu: the last tabs fold into a More menu (a bottom sheet on phones); the active tab never folds.
- `moreLabel?: string` = "More": The label of the overflow trigger and the accessible title of its bottom sheet on phones.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for this instance (next/link's Link). Default: the LinkProvider's, else a plain anchor.
- `labels?: { navigation?: string }`: The nav landmark's accessible name, default "Sections". An aria-label or aria-labelledby on the component wins.
- `classNames?: Partial<Record<"list" | "link" | "indicator" | "badge" | "icon" | "more", string>>`: Extra classes for the inner parts: the list, every link, the indicator, badge and icon wrappers, the More trigger.
- `className?: string`: Extra classes for the nav root, merged last. Set --bar-bg here when sticky tabs sit on a surface other than the page.

```tsx
"use client"

import { usePathname } from "next/navigation"
import Link from "next/link"
import { NavTabs, type NavTabsItem } from "@/components/ui/nav-tabs"
import { LinkProvider } from "@/lib/navigation"

const sections: NavTabsItem[] = [
  { label: "General", href: "/settings/general" },
  { label: "Members", href: "/settings/members", badge: 8 },
  { label: "Billing", href: "/settings/billing" },
  { label: "Integrations", href: "/settings/integrations" },
  { label: "Notifications", href: "/settings/notifications" },
  { label: "Security", href: "/settings/security" },
]

export function SettingsTabs() {
  return (
    <LinkProvider component={Link} currentPath={usePathname()}>
      <NavTabs items={sections} sticky labels={{ navigation: "Company settings" }} />
    </LinkProvider>
  )
}
```

Docs: https://wingo-ui.com/components/nav-tabs (Markdown: https://wingo-ui.com/components/nav-tabs.md)

#### Pagination (`pagination`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add pagination`

Pages for tables and lists: numbers with ellipses, previous / next, page size, jump to page, a compact phone pager and load more.

Click a page number and the current-page pill slides to it on a quick spring; previous and next step one page and grey out at the ends, the optional « » buttons jump to the first and last page. With the keyboard, Tab reaches every control, and while focus is on the pages Left / Right go to the previous / next page and keep focus on the new current page, Home / End jump to the first / last. Type a number in "Go to" and press Enter to jump (it clamps to the real range). The page size select keeps the first row you were looking at on screen. The summary ("21 to 40 of 318") is announced once per change. When it is narrower than 640px (a phone, a card, a side panel) it becomes ‹ Page 5 of 16 › with the summary under the text: tap it for a list of every page (a bottom sheet on phones); buttons are 44px on touch. The load-more variant shows how many are left and a thin progress bar, and with autoLoad it loads on its own when you scroll within 200px of it.

npm: motion, lucide-react
Wingo UI dependencies: button, field, select, use-controllable-state, use-locale, use-scroll-state, motion, navigation, number-format, tones, ui-config

Props:
- `page?: number`: The current page, 1-based, controlled. A page beyond pageCount renders as given with next disabled; it is never corrected silently.
- `defaultPage?: number` = 1: The starting page while uncontrolled.
- `onPageChange?: (page: number) => void`: Fires on every page change: a click, an arrow key, the jump field, the compact page picker or a page size change.
- `pageCount?: number`: Total pages. Default: ceil(total / pageSize). 0 renders only the summary ("No results").
- `total?: number`: The item count, for the page count and the summary ("1 to 20 of 318"). Without it the summary reads "Page 5 of 16".
- `pageSize?: number`: Items per page, controlled.
- `defaultPageSize?: number` = 20: Items per page while uncontrolled; also used when total is given without pageSize.
- `onPageSizeChange?: (pageSize: number) => void`: Fires when the page size select changes. The page moves so the first visible item stays on screen: page = floor(firstIndex / newSize) + 1.
- `pageSizeOptions?: number[]` = "[10, 20, 50, 100]": The choices in the page size select.
- `variant?: "numbers" | "simple" | "compact" | "load-more"` = "numbers": numbers: ‹ 1 … 4 5 6 … 20 ›. simple: Previous / Next buttons with the summary between. compact: ‹ Page 5 of 20 › where the text opens a page picker. load-more: a full-width button for feeds with a remaining count and a progress bar.
- `mobileVariant?: "compact" | "simple" | "numbers"` = "compact": What renders while the pagination is narrower than 640px: a phone, or a card or side panel on desktop (a CSS container query). Both layouts are in the server HTML and CSS picks one, so nothing jumps after hydration. numbers drops the sibling pages there so it fits 360px.
- `siblingCount?: number` = 1: Pages shown on each side of the current one. The slots come from getPageRange(page, pageCount, siblingCount, boundaryCount), exported for custom UIs; their count stays constant while the page moves.
- `boundaryCount?: number` = 1: Pages always shown at each end.
- `showFirstLast?: boolean` = false: Adds « and » buttons that jump to the first and last page. Below 640px the numbers row drops them (its boundary pages already reach the ends) so it fits 360px.
- `showSummary?: boolean` = true: Shows "1 to 20 of 318" (a polite live region, so screen readers hear each change once).
- `showPageSize?: boolean` = false: Shows the page size select ("20 per page"); a bottom sheet on phones.
- `showJump?: boolean` = false: Shows a small "Go to" number field: Enter jumps, out-of-range numbers clamp. Hidden on phones when the compact picker is there.
- `align?: "start" | "center" | "end" | "between"` = "between": between puts the summary at the start and the pages at the end; the others keep them together.
- `size?: "sm" | "md" | "lg"` = "md": Button height 32 / 40 / 48px (md is 44px on touch). Page buttons are square and grow for long numbers.
- `activeVariant?: "soft" | "solid" | "outline"` = "soft": The current page's pill: a soft tint (like tabs), the solid tone fill, or an outline.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of every button, scaled with the size like the button's; full makes round page pills.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The current page's color (and the load-more button and bar). Neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the current page; replaces the tone. Leave empty to use the tone.
- `loading?: boolean` = false: The next page is loading: the control you pressed shows a spinner and the rest are disabled until it turns false.
- `disabled?: boolean` = false: Dims and blocks every control.
- `autoLoad?: boolean` = false: load-more only: loads the next batch on its own when the button scrolls within 200px (IntersectionObserver in the nearest scroll container).
- `locale?: string` = "": Number formatting ("1.250" in de-DE, "1,250" in en-US). Empty uses the LocaleProvider, then the page language.
- `getPageHref?: (page: number) => string`: Renders every page as a link (NavLink through the app's router link) instead of a button: crawlable, open in a new tab, router-friendly. Arrow keys, the jump field and the page picker navigate too.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The link component for this instance; default the LinkProvider's, else a plain <a>.
- `hasNextPage?: boolean`: Cursor pagination without a known count: when set and neither total nor pageCount is, only previous / next render, next disabled when false.
- `hasMore?: boolean`: load-more: whether there is more to load. Default loadedCount < total. false shows the end message.
- `onLoadMore?: (() => void | Promise<unknown>)`: load-more: called by the button (or autoLoad). Return a promise to show the loading state until it settles.
- `loadedCount?: number`: load-more: items already on screen, for "Showing 40 of 318", the remaining count and the bar.
- `labels?: Partial<PaginationLabels>`: Every string, English by default: navigation, previous, next, first, last, page(n), pageOf(page, count), summary(from, to, total), empty, pageSize, perPage(size), jump, loadMore(count), remaining(count), loading, end, showing(shown, total). Numbers arrive formatted for the locale. DEFAULT_PAGINATION_LABELS is exported to spread and override.
- `classNames?: Partial<Record<"meta" | "summary" | "controls" | "list" | "item" | "link" | "ellipsis" | "indicator" | "previous" | "next" | "first" | "last" | "size" | "jump" | "compact" | "loadMore" | "loadMoreStatus" | "loadMoreBar", string>>`: Extra classes for the inner parts.

```tsx
import { useState } from "react"
import { Pagination } from "@/components/ui/pagination"

export function InvoicesFooter({ total }: { total: number }) {
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(20)
  return (
    <Pagination
      total={total}
      page={page}
      onPageChange={setPage}
      pageSize={pageSize}
      onPageSizeChange={setPageSize}
      showPageSize
      locale="en-US"
      labels={{
        summary: (a, b, t) => `${a}\u2013${b} of ${t} invoices`,
        pageSize: "Invoices per page",
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/pagination (Markdown: https://wingo-ui.com/components/pagination.md)

#### Proximity Sidebar (`proximity-sidebar`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add proximity-sidebar`

A document minimap of thin dashes that swell near the pointer and pulse with the section you are reading.

Scroll through the content and the dash for the current section pulses wide, then settles back once you stop. Move the pointer along the rail to swell the dashes nearest to it, and click a dash to smooth-scroll to its section and update the URL hash (unless updateHash is off). On a phone, touch the rail and slide: the dash under your finger swells, and lifting your finger jumps to it. From the keyboard, Tab onto the rail, move with the arrow keys, Home and End (the focused dash swells), and press Enter to jump.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `sections: Array<{ id: string; label: string; kind?: "title" | "subtitle" | "section" | "body"; level?: 1 | 2 | 3 | 4 | 5 | 6 }>`: Ordered section map used for rendering dashes and scroll targeting. Each id must match an element id present in the page. kind (or level 1 to 3) sets the dash length and color; without either, the first heading inside the element decides.
- `side?: "left" | "right"` = "left": Pins the minimap to the chosen side and flips the dash transform origin to match.
- `activeOffset?: number` = 0.4: Viewport anchor ratio used to detect the active section while scrolling (0 = top, 1 = bottom). The section closest to that line pulses.
- `dashColor?: string` = "auto": Color of the dashes, any CSS color. Auto draws title and subtitle dashes in the foreground color and the rest in a muted gray; a custom color keeps that hierarchy by drawing the minor dashes at 40%.
- `activeColor?: string` = "auto": Color of the dash for the section you are reading, any CSS color. Auto leaves it the same color as its neighbours, so only its pulse marks it.
- `dashLength?: number` = 110: Width of the rail in pixels, which is how long a fully swollen dash gets. Every dash length scales with it.
- `gap?: number` = 8: Space between dashes in pixels. Each dash also owns the band up to its neighbours, so clicks between dashes land on the closest one.
- `thickness?: number` = 1: Height of each dash in pixels.
- `reach?: number` = 40: How far in pixels the pointer's pull reaches: dashes within this distance above or below it swell, the nearest the most.
- `inset?: number` = 32: Horizontal space in pixels between the rail and the edges of the nav.
- `updateHash?: boolean` = true: Writes #section-id to the URL (history.replaceState) when a dash is picked. Turn it off for embedded readers and modals.
- `label?: string` = "Page sections": Accessible name of the navigation landmark.
- `dashLabel?: string` = "Go to {label}": Accessible name of each dash; {label} fills in the section label, e.g. "Mergi la {label}".
- `className?: string` = "": Additional classes for the outer nav wrapper (data-slot="proximity-sidebar"), which fills its parent's height and centers the stack. Other nav attributes are passed through too.

Parts:
- `ProximitySection` (type): One entry of sections: { id, label, kind?, level? }. id is the element id to scroll to; kind (title, subtitle, section, body) or level (1 to 6) sets the dash length, and without either it is read from the section's first heading.

```tsx
import ProximitySidebar, { type ProximitySection } from "@/components/ui/proximity-sidebar"

const sections = [
  { id: "intro", label: "Introduction", level: 1 },
  { id: "setup", label: "Setup", level: 2 },
  { id: "api", label: "API", kind: "section" },
  { id: "faq", label: "FAQ", kind: "body" },
] satisfies ProximitySection[]

export function Demo() {
  return (
    <aside className="sticky top-20 h-[70vh]">
      <ProximitySidebar sections={sections} side="left" activeOffset={0.4} />
    </aside>
  )
}
```

Docs: https://wingo-ui.com/components/proximity-sidebar (Markdown: https://wingo-ui.com/components/proximity-sidebar.md)

#### Scroll Progress (`scroll-progress`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add scroll-progress`

A scroll progress pill that tracks reading position and expands into a squircle menu of sections you can jump to.

Scroll to fill the ring and watch the active section label crossfade in. Click the pill to morph it into a squircle menu, then tap any section to smooth-scroll there. From the keyboard, the menu opens with focus on the current section, the arrow keys, Home and End move between sections, and Escape closes it and hands focus back to the pill. Click outside to close it too.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `sections?: Array<{ id: string; label: string }>` = "[]": Ordered sections shown as the reader moves and listed in the menu. Each id must match an element id present in the scrolled content. Defaults to an empty list, which leaves just the ring.
- `offset?: number` = 120: Distance in pixels below the scroller's top edge that a section must cross to be marked active.
- `size?: "sm" | "md" | "lg"` = "md": Scale of the pill, the ring and the menu rows. On touch screens the pill and every row grow to at least 44px tall so they are easy to hit.
- `position?: "bottom-center" | "bottom-left" | "bottom-right" | "top-center" | "top-left" | "top-right"` = "bottom-center": Where the pill is pinned. The menu grows away from that edge, and the safe-area insets of notched phones are added on top of inset.
- `inset?: number` = 24: Distance in pixels between the pill and the edges it is pinned to.
- `showLabel?: boolean` = true: Shows the active section name next to the ring. Turn it off for a compact round button with just the ring.
- `accentColor?: string` = "auto": Color of the progress ring and the active section dot, any CSS color. Auto uses the foreground color of the theme.
- `trackColor?: string` = "auto": Color of the ring track behind the progress, any CSS color. Auto is the foreground color at 15% opacity.
- `surfaceColor?: string` = "auto": Any CSS color for the pill and the open menu. Auto is the page background at 70% over a blur.
- `textColor?: string` = "auto": Any CSS color for the labels, the dots, the row highlight and the ring (when accentColor and trackColor are auto). Auto is the foreground color.
- `radius?: number` = 26: Corner radius of the open menu in pixels. The rows follow it with a radius 12px smaller, and the closed pill is always fully round.
- `triggerLabel?: string` = "Show sections": Accessible name of the pill button. Screen readers hear it followed by the current section.
- `currentLabel?: string` = "current": The word between triggerLabel and the section name in the pill's accessible name: "Show sections, current: Pricing".
- `listLabel?: string` = "Sections": Accessible name of the open menu.
- `containerRef?: React.RefObject<HTMLElement | null>`: Scroll container to track and scroll within. Defaults to the window when omitted.
- `className?: string`: Extra classes merged onto the root wrapper, which is fixed to the viewport at the chosen position. Pass absolute to pin it inside a relative panel instead. Any other <div> attribute is passed through too.

Parts:
- `ScrollProgressSection` (type): One entry of sections: { id, label }. id is the element id the menu scrolls to and the scrollspy watches.

```tsx
"use client"

import { useRef } from "react"
import ScrollProgress from "@/components/ui/scroll-progress"

const sections = [
  { id: "intro", label: "Introduction" },
  { id: "usage", label: "Usage" },
  { id: "faq", label: "FAQ" },
]

export function Demo() {
  const scrollRef = useRef<HTMLElement>(null)

  return (
    <main ref={scrollRef} className="relative h-full overflow-auto">
      <ScrollProgress
        containerRef={scrollRef}
        sections={sections}
        className="absolute"
        position="bottom-center"
      />

      <section id="intro">{/* ... */}</section>
      <section id="usage">{/* ... */}</section>
      <section id="faq">{/* ... */}</section>
    </main>
  )
}

// tracks the window with no container ref:
// <ScrollProgress sections={sections} />
```

Docs: https://wingo-ui.com/components/scroll-progress (Markdown: https://wingo-ui.com/components/scroll-progress.md)

#### Sidebar (`sidebar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add sidebar`

The admin sidebar: grouped links with icons, nested sections, badges, a sliding active pill, an icon rail with flyouts and a filter.

Click a link and the active pill slides to it on a smooth spring; parents fold their children open with a chevron (a parent with its own page gets a separate chevron button), and collapsible group labels fold whole groups. Cmd/Ctrl+B or the footer button collapses it to a 64px icon rail: labels turn into tooltips, badges into dots, and parents open their children as a menu to the side. With the filter on, typing hides what does not match, opens the sections that do and bolds the matched letters; Escape clears it and arrow-down jumps into the list. An item's shortcut (Home has one in the demo) opens its page from anywhere. With the keyboard, Up / Down move between rows, Home / End jump, Right opens a parent (or steps into it) and Left closes it (or steps back to the parent). Rows darken while pressed and are 44px on touch screens; inside an app shell's phone drawer (mode="sheet") the rows grow and tapping a link closes the drawer. Collapsed and open sections are remembered with persistKey.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, avatar, badge, button, dropdown-menu, kbd, skeleton, tooltip, use-controllable-state, use-media-query, use-persisted-state, use-scroll-edges, use-shortcut, motion, navigation, text-match, tones

Props:
- `groups?: SidebarNavGroup[]`: The navigation: { id?, label?, items, collapsible?, defaultOpen? } per group. Items are NavItem ({ label, href, icon, activeIcon, badge, shortcut, keywords, external, disabled, match, onSelect, items }), nested one level deep.
- `items?: SidebarNavItem[]`: One unlabeled group, for small apps. Ignored when groups is set.
- `header?: ReactNode`: Above the navigation: a WorkspaceSwitcher variant="card" or a logo. It adapts to the rail through the group/sidebar CSS contract (data-collapsed="true").
- `footer?: ReactNode`: Below the navigation, before the collapse button: a UserMenu trigger="card". Replaces the user card.
- `user?: { name: string; email?: string; avatar?: string; plan?: ReactNode }`: A simple user card in the footer when there is no footer; onUserClick makes it a button.
- `onUserClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Makes the user card a button.
- `defaultCollapsed?: boolean` = false: Starts as the 64px icon rail. Use collapsed + onCollapsedChange to control it; inside an AppShell the shell owns it.
- `collapsed?: boolean`: Controlled collapsed state.
- `onCollapsedChange?: (collapsed: boolean) => void`: Fires when the rail opens or closes (button, shortcut).
- `value?: string`: The active item's key (its id, else href, else label): controlled. Without it the active item follows currentPath, else the sidebar keeps its own (defaultValue, default the first enabled item).
- `defaultValue?: string`: The first active item when neither value nor a path is known.
- `onValueChange?: (key: string, item: SidebarNavItem) => void`: Fires on every activation, in all three modes.
- `currentPath?: string` = "": The path the active item is matched against (the longest matching href wins). Default: the LinkProvider's. The playground's pretend router provides it.
- `persistKey?: string` = "": Remembers collapsed (standalone) and the open sections in local storage under `${persistKey}-collapsed` and `${persistKey}-open`. Empty keeps them in memory.
- `loading?: boolean` = false: Skeleton rows (icon + line) in place of the items, with aria-busy on the nav.
- `filter?: boolean` = false: A filter field above the navigation. Matches labels and keywords ignoring case and diacritics, opens the sections that hold a match and bolds the matched letters. On the rail it becomes a search button that expands the sidebar.
- `filterPlaceholder?: string` = "Search": The filter's placeholder.
- `filterShortcut?: string` = "": A key combo (mod+k notation) that focuses the filter from anywhere, expanding the rail first. Shown as a hint in the field.
- `defaultFilterValue?: string` = "": Starts the filter with a query (uncontrolled), e.g. a search carried over from another page.
- `onFilterValueChange?: (value: string) => void`: Fires as the filter text changes.
- `filterValue?: string`: The filter text, controlled.
- `variant?: "sidebar" | "floating" | "inset"` = "sidebar": sidebar: flush, a hairline on the end edge. floating: a raised rounded panel 8px off the edges. inset: no edge and no fill, on the app shell's tint.
- `activeStyle?: "soft" | "raised" | "bar"` = "soft": The active row: a tinted pill, a raised white pill (best on floating or tinted sidebars), or a 3px bar on the start edge over a light tint.
- `size?: "sm" | "md"` = "md": Rows 32 / 36px with 13 / 14px text; 44px on touch screens either way.
- `width?: number` = 256: Expanded width in px (160 to 480). The rail is always 64px; the width animates between the two.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the active indicator, the active row's text and its badge. Neutral is a gray pill with black / white text.
- `color?: string` = "": Any CSS color for the active indicator; replaces the tone.
- `collapsible?: "icon" | "none"` = "icon": icon: it can become the 64px rail (button and shortcut). none: always expanded, no toggle.
- `showToggle?: boolean` = true: The collapse button at the end of the footer, with a tooltip showing the shortcut.
- `shortcut?: string` = "mod+b": Toggles the rail from anywhere when the sidebar stands alone (mod is Cmd on Apple devices, Ctrl elsewhere). Inside an app shell the shell binds its own. Empty turns it off.
- `itemShortcuts?: boolean` = true: Binds each item's shortcut (mod+k notation, shown as a hint on hover and in rail tooltips) to open that page from anywhere, with aria-keyshortcuts on the row. Off leaves them as hints. Sheet mode never binds them (the desktop copy does).
- `tooltips?: boolean` = true: On the rail every row shows its label (and shortcut) in a tooltip to the side; expanded, only labels cut off by the width do.
- `flyouts?: boolean` = true: On the rail a parent opens its children as a menu to the side (a bottom sheet on phones). Off, clicking a parent expands the sidebar with that parent open.
- `mode?: "rail" | "sheet"` = "rail": rail: the desktop column, collapsible. sheet: the content of a phone drawer: never collapsed, 44px rows at 15px, no toggle, and a tap on a link closes the app shell's drawer (the app shell renders its drawer copy this way).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for this sidebar; default the LinkProvider's, else a plain <a>.
- `labels?: { sidebar?; navigation?; filter?; noResults?: (query) => string; collapse?; expand?; toggleGroup?: (label) => string; clearFilter?; loading? }`: Every string, English by default: "Sidebar", "Main", "Filter navigation", "Nothing matches “…”", "Collapse sidebar", "Expand sidebar", "Toggle …", "Clear filter", "Loading navigation".
- `classNames?: Partial<Record<"inner" | "header" | "filter" | "content" | "group" | "groupLabel" | "list" | "item" | "link" | "icon" | "label" | "badge" | "indicator" | "sublist" | "empty" | "footer" | "toggle" | "userCard", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the <aside>. Set --sidebar-bg to change its surface.
- `children?: ReactNode`: Replaces the generated groups inside the scrolling nav (SidebarGroup / SidebarItem).

Parts:
- `SidebarRoot` (component): The <aside> with the state (collapsed, active item, open sections, filter) for the parts below. Takes every Sidebar prop except header, footer, user, filter* and showToggle. Props: SidebarRootProps.
- `SidebarHeader` (component): The top area (p-3); a hairline appears under it when the list scrolls. Takes div props.
- `SidebarFooter` (component): The bottom area; a hairline appears while more of the list is below, and it stacks vertically on the rail. Takes div props.
- `SidebarContent` (component): The scrolling <nav> with fading edges and the arrow-key navigation. Renders the root's groups when it has no children. Takes nav props.
- `SidebarGroup` (component): One labelled group (a fold-away label when collapsible), for hand-built layouts. Props: { group: SidebarNavGroup; index?: number; children?: ReactNode }.
- `SidebarItem` (component): One row with its nested children. Props: { item: SidebarNavItem; index?: number; depth?: number; parentKey?: string }.
- `SidebarFilter` (component): The filter field (a search button on the rail). Props: { placeholder?: string; shortcut?: string } & input props.
- `SidebarToggle` (component): The collapse button with its tooltip; renders nothing in sheet mode or when collapsible is none. Props: ButtonProps.
- `SidebarUserCard` (component): Avatar, name, plan and email; the avatar alone on the rail. A button with onClick or interactive (a menu trigger). Props: { user: SidebarUser; trailing?: ReactNode; interactive?: boolean } & button props.
- `useSidebar` (hook): The sidebar's state for anything rendered inside it. Signature: () => { collapsed; setCollapsed; toggle; mode; activePath }.

```tsx
import { ChartColumn, FileText, Handshake, Inbox, LayoutDashboard, LifeBuoy, Package, Settings, ShoppingCart, Users } from "lucide-react"
import { Sidebar, type SidebarNavGroup } from "@/components/ui/sidebar"

const groups: SidebarNavGroup[] = [
  {
    items: [
      { label: "Home", href: "/", icon: <LayoutDashboard /> },
      { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
    ],
  },
  {
    label: "Sales",
    items: [
      { label: "Clients", href: "/clients", icon: <Users /> },
      { label: "Offers", href: "/offers", icon: <Handshake />, badge: 12 },
      {
        label: "Invoices",
        href: "/invoices",
        icon: <FileText />,
        items: [
          { label: "Issued", href: "/invoices/issued" },
          { label: "Paid", href: "/invoices/paid" },
          { label: "Overdue", href: "/invoices/overdue", badge: 3 },
        ],
      },
    ],
  },
  {
    label: "Operations",
    collapsible: true,
    items: [
      { label: "Products", href: "/products", icon: <Package /> },
      { label: "Orders", href: "/orders", icon: <ShoppingCart /> },
      { label: "Reports", href: "/reports", icon: <ChartColumn /> },
    ],
  },
  {
    label: "Account",
    items: [
      { label: "Settings", href: "/settings", icon: <Settings /> },
      { label: "Help", href: "https://example.com/help", icon: <LifeBuoy /> },
    ],
  },
]

export function AppSidebar({ pathname }: { pathname: string }) {
  return (
    <Sidebar
      groups={groups}
      currentPath={pathname}
      persistKey="crm-sidebar"
      filter
      user={{ name: "Emma Carter", email: "emma.carter@northwind.com", avatar: "/demo/ana-pop.jpg", plan: "Pro" }}
      className="h-dvh"
    />
  )
}
```

Docs: https://wingo-ui.com/components/sidebar (Markdown: https://wingo-ui.com/components/sidebar.md)

#### Steps (`steps`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add steps`

A stepper for checkouts, onboarding and KYC: circles, bars or dots, with complete, error and loading states and a compact phone header.

Move forward and the connectors fill one after another on a smooth spring, the new current marker pops and the check draws itself in. Click a completed step to go back to it (or any step with clickable="all"). With the keyboard, Tab reaches each clickable step, Left / Right (Up / Down when vertical) move between them and Home / End jump to the first and last. Below 640px a horizontal stepper turns into a compact header: "Step 2 of 4", the step title, what comes next and a progress bar. Dots variant: tap or click a dot to jump (with clickable steps). Clickable markers and dots get a 44px hit area on touch.

npm: motion
Wingo UI dependencies: spinner, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `steps: StepItem[]`: { id: string; title: ReactNode; description?: ReactNode; icon?: ReactNode; status?: StepStatus; optional?: boolean; disabled?: boolean; href?: string }. status overrides the derived one (complete before value, current at it, upcoming after); errors and loading are always explicit.
- `value?: string`: The current step id, controlled. An id that is not among the steps leaves every step upcoming.
- `defaultValue?: string` = "": The starting step id while uncontrolled. Empty starts on the first step; an id that is not among the steps leaves them all upcoming. The playground takes cart, shipping, payment or review.
- `onValueChange?: (id: string, step: StepItem) => void`: Fires when a clickable step is clicked.
- `orientation?: "horizontal" | "vertical"` = "horizontal": Vertical stacks the steps with their descriptions beside a column of markers; it works at any width.
- `variant?: "circles" | "bars" | "dots"` = "circles": circles: numbered markers joined by connectors (the form-wizard look). bars: one segment per step with the title under it (checkout). dots: small dots, the current one widened (onboarding).
- `size?: "sm" | "md" | "lg"` = "md": Markers 24 / 28 / 32px, titles 13 / 14 / 15px, descriptions 12 / 13 / 13px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Paints the current marker, the tint of completed markers and the connector fill.
- `color?: string` = "": Any CSS color. Replaces the tone; text on the current marker turns black or white by lightness.
- `labelPlacement?: "bottom" | "end"` = "bottom": Horizontal circles: titles centered under the markers (clamped to two lines), or beside them with the connector after the text.
- `clickable?: "none" | "completed" | "all"` = "completed": Which steps are buttons: none, the ones already done (plus the current one and ones marked with an error), or every enabled step. Disabled steps never are.
- `connector?: "solid" | "dashed"` = "solid": dashed draws the connectors (and bar segments) still ahead as dashes.
- `mobileVariant?: "compact" | "same"` = "compact": Below 640px a horizontal circles or bars stepper becomes the compact header ("Step 2 of 5", title, next step, progress bar). Pure CSS: both are rendered, so the server HTML is right on a phone.
- `compact?: boolean` = false: Always shows the compact header, at every width: phone screen headers, narrow cards, sheets. Horizontal circles and bars only (vertical and dots keep their layout).
- `showDescription?: boolean` = true: Descriptions under the titles. Vertical steppers always show them.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The link component for href steps (a router Link, or "a"). Default: the one set by LinkProvider, a plain <a> without one.
- `labels?: { progress?: string; step?: (position: number, count: number) => string; next?: (title: ReactNode) => ReactNode; complete?: string; current?: string; error?: string; loading?: string; optional?: string }`: Text for screen readers and the compact header. Defaults: "Progress", "Step 2 of 5", "Next: …", "Completed", "Current step", "Needs attention", "In progress", "Optional".
- `classNames?: Partial<Record<"list" | "item" | "trigger" | "marker" | "title" | "description" | "connector" | "compact", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { useState } from "react"
import { Steps, type StepItem } from "@/components/ui/steps"

const STEPS: StepItem[] = [
  { id: "cart", title: "Cart", description: "3 items" },
  { id: "shipping", title: "Shipping", description: "FedEx" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]

export function CheckoutSteps() {
  const [step, setStep] = useState("shipping")
  return (
    <Steps
      steps={STEPS}
      value={step}
      onValueChange={setStep}
    />
  )
}
```

Docs: https://wingo-ui.com/components/steps (Markdown: https://wingo-ui.com/components/steps.md)

#### Table Of Contents (`table-of-contents`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add table-of-contents`

An "On this page" list of a long page's sections that highlights the one being read and jumps to any; a pill and sheet on phones.

Scroll the page and the section you are reading lights up: on the line variant a short bar glides along the rail to it on a smooth spring, on the dots variant its dot grows and fills. Click a row to glide to that section; the highlight goes straight to it instead of running through the sections in between, the heading lands just under the top bar, receives focus and the URL hash updates (without adding history). Tab or the arrow keys (Home / End for the first and last) move through the rows, Enter jumps. Opening a page with #section in the URL lands there without animation. Below collapseBelow the list turns into a sticky pill under the top bar with a reading ring and the current section, which crossfades as you scroll; tap it to open every section in a bottom sheet (48px rows, the current one checked), tap a row and the sheet closes, then the page jumps. Under reduced motion jumps are instant and nothing slides or crossfades.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, drawer, use-controllable-state, use-media-query, use-scroll-state, motion, text-match, tones

Props:
- `items?: TocItem[]`: { id: string; label: ReactNode; level?: 2 | 3; items?: TocItem[] }. Nested items or level: 3 rows become subsections. Leave empty to collect headings from the page. Ids missing in the DOM keep their row, jumping to them does nothing.
- `headings?: string` = "h2, h3": Selector used to collect items when items is empty, after mount and again (debounced 150ms) whenever the content changes. Headings without an id get one from their text; data-toc-ignore skips one, data-toc-label renames it.
- `container?: HTMLElement | RefObject<HTMLElement | null> | null`: Where headings are collected from. Default: the scroll container, else <main>, else the body.
- `title?: ReactNode` = "On this page": The eyebrow above the list, also the nav's aria-label when it is a string. "" hides it.
- `pillLabel?: string` = "Contents": The muted word on the phone pill before the current section.
- `sheetTitle?: string` = "On this page": The title of the bottom sheet the pill opens. Also names the nav landmark when title is empty or not a string.
- `defaultSheetOpen?: boolean` = false: Opens the phone sheet on mount, uncontrolled. The sheet only opens below collapseBelow, where its pill shows.
- `sheetOpen?: boolean`: The phone sheet's open state, controlled. Pair it with onSheetOpenChange.
- `onSheetOpenChange?: (open: boolean) => void`: Called when the sheet opens or closes.
- `variant?: "line" | "dots" | "plain"` = "line": line: a rail with a segment that glides to the active row. dots: a dot per row that grows and fills. plain: text only, the active row in medium weight.
- `size?: "sm" | "md"` = "sm": Rows at 13 / 14px. Every row is 44px tall on touch screens.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the indicator, the active row, the dots and the progress ring.
- `color?: string` = "": Any CSS color. Replaces the tone. Leave empty to use the tone.
- `showProgress?: boolean` = false: A 16px reading-progress ring and a percentage next to the title. Both follow the scroll every frame without re-rendering. The phone pill always has the ring.
- `collapseBelow?: "md" | "lg" | "xl" | "never" | "always"` = "lg": Below this width the list becomes a sticky pill that opens a sheet. Pure CSS, both are rendered, so the server HTML is right on a phone. always: the pill at every width (narrow columns, phone layouts).
- `collapseOn?: "viewport" | "container"` = "viewport": What collapseBelow measures. viewport: media queries (768 / 1024 / 1280px). container: the nearest ancestor with the @container class, at the same widths, for pages that sit in a narrow pane, a card or a split view. Lay out the columns with the matching @3xl: / @5xl: / @7xl: variants.
- `sticky?: boolean` = true: Pins the list 24px and the pill 8px under the top bar (--topbar-offset) while the page scrolls. Place it as a direct child of the layout that spans the whole page (a grid column, or before the article).
- `offset?: number` = 16: Pixels below the top bar where the reading line sits and where a jumped-to heading lands. --topbar-offset, and the pill's height when it shows, are added automatically. The demo's readout shows it.
- `smooth?: boolean` = true: Smooth jumps. Always instant when the user prefers reduced motion. The demo's readout shows it.
- `updateHash?: boolean` = true: A jump writes #id into the URL with history.replaceState, so it can be shared without adding history entries. Scrolling never does. The demo's readout shows it.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls. Default: the nearest ScrollContainerProvider, else the headings' scrolling ancestor, else the window.
- `onActiveChange?: (id: string | null) => void`: Called with the id of the section being read whenever it changes.
- `classNames?: Partial<Record<"header" | "title" | "progress" | "scroll" | "list" | "item" | "link" | "rail" | "indicator" | "dot" | "pill" | "pillLabel" | "pillRing" | "sheet" | "sheetItem", string>>`: Extra classes for the inner parts. scroll is the box that scrolls a list taller than the screen.
- `className?: string`: Extra classes for the <nav> root. Other props go to it too.

Parts:
- `useActiveHeading` (hook): The scroll spy on its own, for a custom table of contents: the id of the heading being read. Signature: (ids: string[], { root?: ScrollTarget; offset?: number; disabled?: boolean }) => string | null.
- `collectHeadings` (function): The headings of a container as items, in order, assigning slug ids (duplicates suffixed -2) to headings without one. Signature: (container: ParentNode | null, selector?: string) => TocItem[].

```tsx
import { TableOfContents } from "@/components/ui/table-of-contents"

export function Contract() {
  return (
    <div className="mx-auto max-w-5xl px-5 lg:grid lg:grid-cols-[minmax(0,1fr)_220px] lg:gap-12">
      <TableOfContents
        title="On this page"
        pillLabel="Contents"
        sheetTitle="Contract contents"
        className="pt-3 lg:col-start-2 lg:row-start-1 lg:pt-8"
      />
      <article className="lg:col-start-1 lg:row-start-1">
        <h1>Lease agreement</h1>
        <h2>1. The parties</h2>
        <p>Landlord: Olivia Bennett. Tenant: Andrew Collins.</p>
        <h2>4. Rent and payment</h2>
        <p>The monthly rent is $2,500.00.</p>
        <h3>4.1 Security deposit</h3>
        <p>One month of rent, returned within 15 days.</p>
      </article>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/table-of-contents (Markdown: https://wingo-ui.com/components/table-of-contents.md)

#### Tabs (`tabs`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add tabs`

Switch between views of the same page with a sliding indicator: underline for sections, pill for filters, segmented for a compact switch.

Click or tap a tab and the indicator glides over to it on a smooth spring while the new panel slides in from the side you moved toward and the old one fades away. Tabs dip slightly under the finger. With the keyboard, Tab lands on the active tab, Left and Right (Up and Down when vertical) move between tabs, Home and End jump to the ends, and Tab again moves into the panel; in manual mode the arrows only move focus and Enter or Space opens the tab. When the tabs do not fit, the row scrolls sideways with soft fades at the edges and keeps the active tab in view. On a phone, triggers are 44px tall, and vertical tabs that get narrower than 32rem (a phone, a side panel) turn into a scrolling row above the content. Count badges roll when their number changes. With dir set to rtl the arrow keys, the edge fades and the panel slide mirror.

npm: @radix-ui/react-tabs, motion
Wingo UI dependencies: ui-config, badge, motion, tones, use-controllable-state, use-scroll-edges

Props:
- `options?: TabsOption[]`: The tabs: { value, label, icon?, badge?, disabled?, content? }. A number badge renders a small count that hides at 0; content is the panel. Leave content out to use the tabs as a filter or a switch.
- `value?: string`: The active tab, when you control it. A value that is not in options leaves no tab active.
- `defaultValue?: string` = "": The tab active on the first render when uncontrolled. Empty, or a value that is not in options (a stale link, options that load later), starts on the first enabled option.
- `onValueChange?: (value: string) => void`: Called with the new value. Also called with the first enabled tab when the active one is removed from options.
- `aria-label?: string` = "": Names the tab list for screen readers when no visible heading does, e.g. "My listings". To name it after a heading on the page, pass aria-labelledby with the heading's id instead; both land on the list.
- `variant?: "underline" | "pill" | "segmented"` = "underline": underline: a 2px bar under the active label over a hairline baseline, for page sections. pill: the active tab gets a tinted pill, for filters. segmented: a raised thumb in a tinted track, for a compact two to five way switch.
- `size?: "sm" | "md" | "lg"` = "md": Trigger height 32 / 40 / 48px with matching padding, type and icon size. On touch screens md grows to 44px and sm keeps its look with a 44px hit area.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The indicator color: the underline bar, the pill tint, the segmented thumb, and the active badge. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the indicator. Replaces the tone; text on a segmented thumb turns black or white by lightness. Leave empty to use the tone.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of pills, the segmented track and the focus ring. Scales with the size (md is 8 / 10 / 12px); the segmented thumb is 2px tighter than its track. full makes capsules.
- `orientation?: "horizontal" | "vertical"` = "horizontal": vertical puts the tabs in a column beside the content (at least 176px wide, labels start-aligned) for settings pages; the underline becomes a bar on the start edge and arrow keys go up and down.
- `responsive?: boolean` = true: Vertical tabs only: when the tabs are narrower than 32rem (a CSS container query on their own width, so a phone, a side panel or a narrow card alike) the column turns into a scrolling row above the content and the arrow keys follow. Turn it off to keep the column everywhere.
- `fullWidth?: boolean` = false: Triggers share the width equally. Segmented plus fullWidth is the usual header switch on a phone.
- `scrollable?: boolean` = true: A row that does not fit scrolls sideways with edge fades and keeps the active tab in view (the list scrolls, never the page). Off, the triggers wrap onto a new line instead.
- `animateContent?: boolean` = true: Panels slide 16px in the direction you moved and fade; the leaving panel steps out of the flow so nothing jumps. Off, panels swap instantly. Under reduced motion they only fade.
- `activationMode?: "automatic" | "manual"` = "automatic": automatic opens a tab as soon as the arrow keys focus it. manual only moves focus and opens on Enter or Space, for panels that are slow to render.
- `keepMounted?: boolean` = false: Keeps inactive panels in the DOM (hidden), so a half-filled form keeps what was typed when you switch away and back.
- `classNames?: Partial<Record<"list" | "trigger" | "indicator" | "icon" | "label" | "badge" | "content", string>>`: Extra classes for the inner parts: the scrolling list, every trigger, the indicator, icons, labels, badges and panels.
- `className?: string`: Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:var(--info)].

Parts:
- `TabsRoot` (component): The compound root: value, defaultValue, onValueChange, variant, size, tone, color, radius, orientation, responsive, fullWidth, scrollable, animateContent, activationMode, keepMounted, classNames. Wrap a TabsList and your TabsContent panels in it, and pass defaultValue (or value): unlike Tabs, the root does not pick the first tab for you. Props: TabsRootProps.
- `TabsList` (component): The scrolling tab list (role tablist). Renders the sliding indicator for you; loop (default true) lets the arrow keys wrap. Give it an aria-label when no heading names it. Props: { loop?: boolean } & ComponentProps<"div">.
- `TabsTrigger` (component): One tab. A number badge renders a count badge in the active tone; any other node renders as is. Props: { value: string; icon?: ReactNode; badge?: ReactNode | number; disabled?: boolean; children: ReactNode }.
- `TabsContent` (component): The panel for one value, focusable with a visible ring. Leaving panels are positioned against the nearest positioned parent (TabsRoot is one). Props: { value: string; children: ReactNode }.

```tsx
import { Tabs, type TabsOption } from "@/components/ui/tabs"

const options: TabsOption[] = [
  { value: "active", label: "Active", badge: 12, content: <p>12 listings live in New York.</p> },
  { value: "pending", label: "Pending", badge: 3, content: <p>3 listings waiting for review.</p> },
  { value: "sold", label: "Sold", content: <p>Last sale: Sep 2, 2026.</p> },
  { value: "expired", label: "Expired", content: <p>No expired listings.</p> },
]

export function MyListings() {
  return <Tabs options={options} aria-label="My listings" />
}
```

Docs: https://wingo-ui.com/components/tabs (Markdown: https://wingo-ui.com/components/tabs.md)

#### Topbar (`topbar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add topbar`

The app header: menu button, title or breadcrumb, a search in the middle and actions at the end, on a sticky glass bar.

Scroll the page and a hairline fades in under the glass bar. On a phone the bar slides away as you scroll down, following your finger, and comes straight back the moment you scroll up, at the top and at the end of the page; tabbing into a hidden bar springs it back, and it never hides while focus is inside it. Inside an app shell the menu button opens the drawer on phones (the two lines cross into an X) and collapses the sidebar on desktop, with a tooltip that shows the shell's shortcut (Cmd/Ctrl+B by default). Tab moves through the menu button, the title links, the search and the actions. On phones the title is centered on the screen and the search folds into an icon next to the actions.

npm: motion, lucide-react
Wingo UI dependencies: button, tooltip, use-media-query, use-scroll-state, use-shortcut, motion, navigation, ui-config

Props:
- `title?: ReactNode` = "": Text or a breadcrumb. Truncates when there is no room; with no title the bar holds start and actions only.
- `mobileTitle?: ReactNode`: A shorter title below 768px, usually the breadcrumb's last entry.
- `titleAs?: "div" | "h1" | "h2" | "span"` = "div": The title element. Use h1 only when the page has no other.
- `start?: ReactNode`: After the menu button: a logo, a back button, a workspace switcher.
- `center?: ReactNode`: The middle: a global search, a CommandMenuTrigger, a segmented switch. Below 768px it moves next to the actions, so give it a compact phone form (both do: an icon).
- `actions?: ReactNode`: The end: notifications, the user menu, buttons. Icon buttons: ghost, size icon, radius full.
- `size?: "sm" | "md" | "lg"` = "md": Bar height 48 / 56 / 64px plus the top safe area; the title grows with it.
- `background?: "blur" | "solid" | "transparent"` = "blur": blur: frosted glass over the page. solid: the page background. transparent: nothing until content scrolls under it, then glass (a header over a hero photo). The bar reads --bar-bg for the surface it sits on.
- `border?: "scrolled" | "always" | "never"` = "scrolled": The bottom hairline: fades in once content scrolls under the bar, always there, or never.
- `mobileTitleAlign?: "start" | "center"` = "center": Below 768px. center puts the title in the middle of the screen like iOS, not between uneven buttons.
- `sticky?: boolean` = true: Pins the bar to the top of its scroll container (sticky top-0). Off, it scrolls away with the page and never hides.
- `safeArea?: boolean` = true: Pads env(safe-area-inset-top) for notched phones. It is 0 in desktop browsers, so the default is harmless.
- `hideOnScroll?: "never" | "mobile" | "always"` = "mobile": Slides the bar away while scrolling down, following the finger, and brings it back on scroll up; mobile does it below 768px only. Snaps after scrolling stops; under reduced motion it flips instead of sliding.
- `menuButton?: "auto" | "always" | "never"` = "auto": auto: inside an app shell (useNavShell) the hamburger on phones and the sidebar toggle on desktop; outside one, nothing. always: also outside a shell, a hamburger that calls onMenuClick. never: no menu button. For custom headers the file also exports TopbarMenuButton (Button props + kind "auto" | "hamburger" | "sidebar", open, controls, shortcut, tooltip, labels): the same toggle alone.
- `menuShortcut?: string` = "mod+b": The sidebar shortcut shown in the toggle's tooltip and set as aria-keyshortcuts. Display only: the shell binds it. "" hides it.
- `menuOpen?: boolean` = false: Outside a shell: your drawer is open. The hamburger turns into an X and reports aria-expanded. In the playground it applies with menuButton="always", which drops the demo's app shell.
- `onMenuClick?: () => void`: Called by the menu button. Outside a shell it is the only thing the button does (open your own drawer).
- `menuControls?: string` = "": The id of the drawer or sidebar the menu button controls, set as aria-controls.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for the hairline and hide on scroll. Default: the nearest ScrollContainerProvider, else the window.
- `labels?: { openMenu?: string; closeMenu?: string; collapse?: string; expand?: string }`: The menu button's aria-labels and tooltip. Default: the shell's labels, else "Open menu", "Close menu", "Collapse sidebar", "Expand sidebar".
- `classNames?: Partial<Record<"inner" | "start" | "title" | "center" | "actions" | "menuButton", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the <header>, merged last. The bar sets data-scrolled, so text-white data-scrolled:text-foreground styles a header over a photo. Set [--bar-bg:var(--surface)] on a card.

```tsx
"use client"

import { useState } from "react"
import { Bell, Search } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Topbar } from "@/components/ui/topbar"

export function ClientsHeader() {
  const [menuOpen, setMenuOpen] = useState(false)
  return (
    <Topbar
      title="Clients"
      titleAs="h1"
      menuButton="always"
      menuOpen={menuOpen}
      onMenuClick={() => setMenuOpen((open) => !open)}
      actions={
        <>
          <Button variant="ghost" size="icon" radius="full" aria-label="Search">
            <Search />
          </Button>
          <Button variant="ghost" size="icon" radius="full" aria-label="Notifications">
            <Bell />
          </Button>
        </>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/topbar (Markdown: https://wingo-ui.com/components/topbar.md)

#### User Menu (`user-menu`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add user-menu`

The signed-in person's menu: a profile header, a theme switch, account links, other accounts and sign out, as a bottom sheet on phones.

Click the avatar (or the card in a sidebar footer, or the compact avatar and first name) and the menu grows out of it: a profile header with the plan badge and a Manage account button, a Light / Dark / System row whose raised thumb slides to the pick, your links, the other signed-in accounts and Sign out. Picking a theme keeps the menu open. Picking another account spins its row until the switch finishes, then the menu closes; Sign out spins and stays open until your promise settles (a rejection only stops the spinner). Keyboard: Enter, Space or Down on the trigger opens it on the first row, Up / Down move through every row including the three theme options, Right opens a submenu (Language), Left closes it, typing a letter jumps to a row, item shortcuts (Mod+,) run while it is open, Escape closes and focus returns to the trigger. A shortcut prop opens it from anywhere. In a collapsed sidebar the card shrinks to the avatar. On a phone the menu is a bottom sheet: a centered profile card, the theme as a full-width segmented control, 48px rows, submenus that push in from the right with a Back row, and a handle to drag it away.

npm: lucide-react, motion
Wingo UI dependencies: avatar, badge, button, drawer, dropdown-menu, segmented-control, spinner, use-controllable-state, use-media-query, use-shortcut, motion, navigation, ui-config

Props:
- `user?: UserMenuUser` = "{ name: \"Emma Carter\", email: \"emma.carter@northwind.com\" }": The signed-in person: { id?, name, email?, avatar?, status?: "online" | "offline" | "busy" | "away", plan?: ReactNode, role?: ReactNode }. Without a photo the avatar shows initials on a color from the name; long names truncate and keep the full name in a tooltip.
- `items?: MenuEntry[]` = "[]": Rows between the header and the accounts, in dropdown-menu's entry format: items ({ label, icon, description, shortcut, badge, href, onSelect, tone, disabled, keepOpen }), submenus, checkboxes, radio sets, groups, labels and separators. href items render through NavLink (the app's router link).
- `trigger?: "avatar" | "card" | "compact" | ReactNode` = "avatar": avatar: an avatar button for top bars. card: avatar, name, email and an up-down chevron filling the width, for sidebar footers; inside a collapsed sidebar (data-collapsed="true" on a group/sidebar parent) only the avatar stays. compact: avatar, first name and a chevron. Any element works too (it gets the trigger props). The built-in trigger is exported alone as UserMenuTrigger ({ user?, variant?, size?, triggerLabel?, classNames? } & button props) for custom compositions.
- `size?: "sm" | "md"` = "md": The trigger avatar: 32 / 40px (card 28 / 32px, compact 24 / 32px). Every size has a 44px hit area on touch.
- `theme?: "light" | "dark" | "system"` = "system": The current theme. Pass next-themes' theme here; left out, the row starts on system and keeps its own state.
- `onThemeChange?: (theme: UserMenuTheme) => void`: Shows the theme row (Light / Dark / System) and fires on every pick. Wire next-themes: const { theme, setTheme } = useTheme().
- `themeLabels?: { title?: string; light?: string; dark?: string; system?: string }`: The theme row's heading and option labels; each one falls back to English: { title: "Theme", light: "Light", dark: "Dark", system: "System" }.
- `accounts?: UserMenuUser[]`: Other signed-in accounts. They are listed under the current one (which gets a check), each switchable.
- `onAccountChange?: (account: UserMenuUser) => (void | Promise<unknown>)`: Picking another account. Return a promise and its row spins while the menu stays open, then the menu closes.
- `onAddAccount?: () => void`: Shows an Add account row under the accounts.
- `addAccountLabel?: string` = "Add account": The Add account row's label.
- `accountsLabel?: string` = "Accounts": The heading above the accounts.
- `manageHref?: string`: Shows a Manage account button under the profile header that links here (through the router link).
- `onManage?: () => void`: Shows the Manage account button and runs on press (with or without manageHref).
- `manageLabel?: string` = "Manage account": The Manage account button's label.
- `onSignOut?: () => (void | Promise<unknown>)`: Shows the red Sign out row. Return a promise to keep the menu open with a spinner on the row until it settles; a rejection stops the spinner and leaves the menu open.
- `signOutLabel?: string` = "Sign out": The sign-out row's label.
- `side?: "auto" | "top" | "right" | "bottom" | "left"` = "auto": Where the menu opens. auto: below the trigger, or above it for the card trigger (sidebar footers). It flips when there is no room; on phones (below 768px, with responsive off) left and right fall back to auto.
- `align?: "auto" | "start" | "center" | "end"` = "auto": Alignment against the trigger. auto: end (the avatar sits at the end of a top bar), start for the card trigger.
- `open?: boolean`: Controlled open state; pair it with onOpenChange.
- `defaultOpen?: boolean` = false: Starts open (uncontrolled).
- `onOpenChange?: (open: boolean) => void`: Fires when the menu or the sheet opens or closes.
- `responsive?: boolean` = true: Below 768px the menu becomes the account sheet. Off: the dropdown on every screen.
- `sheetTitle?: string` = "Account": The phone sheet's title, read by screen readers (it is not shown).
- `backLabel?: string` = "Back": The back row of a submenu page in the phone sheet.
- `shortcut?: string` = "": A key combo in mod+k notation that opens and closes the menu from anywhere (e.g. shift+mod+u); the trigger gets aria-keyshortcuts. Empty binds nothing.
- `triggerLabel?: (name: string) => string` = "(name) => \"Account menu, \" + name": The trigger's accessible name.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for href items and the manage link. Default: the one set with LinkProvider, else a plain <a>.
- `container?: HTMLElement | null`: Portal target for the menu and the sheet (default document.body).
- `classNames?: Partial<Record<"trigger" | "avatar" | "name" | "email" | "chevron" | "content" | "header" | "headerAvatar" | "plan" | "manage" | "theme" | "item" | "accounts" | "addAccount" | "signOut", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the built-in trigger, merged last.

```tsx
"use client"

import { CreditCard, Settings, User } from "lucide-react"
import { useTheme } from "next-themes"
import { UserMenu, type UserMenuTheme } from "@/components/ui/user-menu"

export function AccountMenu({ onSignOut }: { onSignOut: () => Promise<void> }) {
  const { theme, setTheme } = useTheme()
  return (
    <UserMenu
      user={{ name: "Emma Carter", email: "emma.carter@northwind.com", avatar: "/avatars/emma.jpg", plan: "Pro", status: "online" }}
      theme={theme as UserMenuTheme}
      onThemeChange={setTheme}
      themeLabels={{ title: "Theme" }}
      manageHref="/settings/profile"
      manageLabel="Manage account"
      items={[
        { label: "Profile", icon: <User />, href: "/settings/profile" },
        { label: "Settings", icon: <Settings />, shortcut: "mod+,", href: "/settings" },
        { label: "Billing", icon: <CreditCard />, badge: "Pro", href: "/settings/billing" },
      ]}
      signOutLabel="Sign out"
      onSignOut={onSignOut}
    />
  )
}
```

Docs: https://wingo-ui.com/components/user-menu (Markdown: https://wingo-ui.com/components/user-menu.md)

#### Workspace Switcher (`workspace-switcher`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add workspace-switcher`

Switch organizations, teams or projects: logos, plan badges, search, groups, mod+1…9 shortcuts and a create row; a sheet on phones.

Click the trigger (a card with the logo, name and plan in a sidebar header, a compact logo and name in a top bar, or the logo alone in a rail, with a tooltip) and a list of workspaces grows out of it, grouped (Personal, Teams), each row with its logo, plan badge, description and a check on the current one. Pick one and the trigger's logo and name crossfade to it; when the switch loads data (onValueChange returns a promise) the row spins and the list stays open until it finishes. Disabled workspaces are listed but cannot be picked. With more than six workspaces a search row filters by name, plan, city or keywords (diacritics do not matter) and bolds the match. Under the list sit the Create workspace row and your own actions. Keyboard: Enter, Space, Down or Up on the trigger opens it; Up / Down move, Home / End jump, Enter picks, typing filters (or jumps by first letter without search), Tab moves from the search or the list to the footer rows, leaving the footer closes, Escape closes and focus returns to the trigger. With shortcuts on, Mod+1 … Mod+9 switch to the first nine workspaces from anywhere (the hints show in the rows and the switch is announced), and a shortcut prop opens it. In a collapsed sidebar (data-collapsed="true" on a group/sidebar parent) the card shrinks to the logo. On a phone it is a bottom sheet with a title, the search under it, 48px rows and the footer rows above the safe area; drag it down or tap outside to close.

npm: @radix-ui/react-popover, lucide-react, motion
Wingo UI dependencies: avatar, badge, drawer, dropdown-menu, listbox, spinner, tooltip, use-controllable-state, use-media-query, use-shortcut, motion, navigation, text-match, ui-config

Props:
- `workspaces?: Workspace[]` = "[{ id: \"personal\", name: \"Personal\", plan: \"Free\", description: \"Just you\", group: \"Personal\" }, { id: \"acme\", name: \"Acme Inc\", plan: \"Pro\", description: \"12 members\", group: \"Teams\" }, { id: \"northwind\", name: \"Northwind\", plan: \"Business\", description: \"48 members\", group: \"Teams\" }]": The workspaces: { id, name, logo?: string (image url) | ReactNode (an icon on a color from the name), description?, plan?, group?, disabled?, keywords? }. Without a logo (or when the image fails) the initials show on a color from the name, legal forms left out (North Studio LLC reads AN). The logo alone is exported as WorkspaceLogo ({ workspace, size, radius, variant }) for your own rows.
- `value?: string`: The current workspace id (controlled). An id that is not in the list shows the placeholder.
- `defaultValue?: string` = "": The starting workspace id while uncontrolled. Empty: the first enabled workspace; an unknown id shows the placeholder.
- `onValueChange?: (id: string, workspace: Workspace) => (void | Promise<unknown>)`: Fires on a pick or a Mod+1…9 switch. Return a promise and the row shows a spinner while the list stays open; the switch commits when it resolves (a rejection keeps the current workspace).
- `variant?: "card" | "compact" | "icon"` = "card": card: logo, name, plan / description and an up-down chevron filling the width (sidebar headers; logo only in a collapsed sidebar). compact: logo, name and a chevron (top bars). icon: the logo alone with a tooltip (rails).
- `size?: "sm" | "md" | "lg"` = "md": card and icon: 40 / 48 / 56px with a 24 / 32 / 40px logo. compact: 32 / 40 / 48px, like the buttons next to it in a top bar. 44px targets on touch.
- `logoRadius?: "sm" | "md" | "full"` = "md": Logo corners, proportional to its size: organization logos are rounded squares, full makes circles.
- `logoVariant?: "solid" | "soft"` = "solid": The look of logos without an image: solid white initials on a color from the name, or a soft tint with deep initials.
- `meta?: "auto" | "plan" | "description" | "none"` = "auto": The card's second line: the plan and the description joined with a dot (auto), one of them, or nothing.
- `search?: "auto" | "always" | "never"` = "auto": The search row on top of the list. auto: above 6 workspaces. On touch screens it waits for a tap so the keyboard does not cover the list (unless always).
- `searchPlaceholder?: string` = "Find a workspace": The search row's placeholder.
- `emptyText?: string` = "No workspaces found": Shown when the search matches nothing.
- `groupBy?: boolean` = true: Groups rows under their workspace.group label, in the order the groups first appear.
- `shortcuts?: boolean` = false: Binds Mod+1 … Mod+9 to the first nine enabled workspaces while mounted (Slack, Linear), shows the hints in the rows and announces the switch.
- `onCreate?: () => void`: Shows the Create workspace row under the list.
- `createLabel?: string` = "Create workspace": The create row's label.
- `actions?: MenuItemEntry[]`: More footer rows, in dropdown-menu's item format: { label, icon, shortcut, badge, href, onSelect, tone, disabled, keepOpen }. href rows render through NavLink; shortcuts run while it is open.
- `placeholder?: string` = "Select a workspace": The trigger's text while no workspace is selected.
- `contentWidth?: number` = 288: The list's width in px; never narrower than the trigger, never wider than the screen.
- `maxHeight?: number` = 460: The list's maximum height in px, capped by the room on screen; the list scrolls and the footer stays.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the list opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": Alignment against the trigger.
- `sideOffset?: number` = 8: Gap between the trigger and the list, in px.
- `open?: boolean`: Controlled open state; pair it with onOpenChange.
- `defaultOpen?: boolean` = false: Starts open (uncontrolled).
- `onOpenChange?: (open: boolean) => void`: Fires when the list or the sheet opens or closes.
- `disabled?: boolean` = false: Dims the trigger and keeps it closed.
- `responsive?: boolean` = true: Below 768px the list becomes a bottom sheet. Off: the popover on every screen.
- `sheetTitle?: string` = "Switch workspace": The phone sheet's title, and the list's accessible name.
- `shortcut?: string` = "": A key combo in mod+k notation that opens and closes it from anywhere (e.g. mod+o); the trigger gets aria-keyshortcuts. Empty binds nothing.
- `triggerLabel?: (name: string) => string` = "(name) => \"Workspace: \" + name": The icon trigger's accessible name and tooltip.
- `switchingLabel?: string` = "Switching": What screen readers hear for the row spinner while a switch loads.
- `container?: HTMLElement | null`: Portal target for the list and the sheet (default document.body).
- `classNames?: Partial<Record<"trigger" | "logo" | "name" | "meta" | "chevron" | "content" | "search" | "list" | "option" | "optionLogo" | "optionName" | "optionDescription" | "optionPlan" | "optionShortcut" | "empty" | "footer" | "create" | "action", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the trigger, merged last. Other props (id, aria-*, data-*, handlers) are spread onto it.

```tsx
"use client"

import { Settings, UserPlus } from "lucide-react"
import { WorkspaceSwitcher, type Workspace } from "@/components/ui/workspace-switcher"

const workspaces: Workspace[] = [
  { id: "emma", name: "Emma Carter", logo: "/avatars/emma.jpg", plan: "Free", group: "Personal" },
  { id: "north-studio", name: "North Studio LLC", plan: "Pro", description: "12 members · New York", group: "Teams" },
  { id: "summit", name: "Summit Logistics", plan: "Business", description: "48 members · Boston", group: "Teams" },
]

export function SidebarHeader({ onSwitch }: { onSwitch: (id: string) => Promise<void> }) {
  return (
    <WorkspaceSwitcher
      workspaces={workspaces}
      defaultValue="north-studio"
      onValueChange={(id) => onSwitch(id)}
      shortcuts
      onCreate={() => console.log("new workspace")}
      createLabel="Create workspace"
      actions={[
        { label: "Workspace settings", icon: <Settings />, href: "/settings" },
        { label: "Invite members", icon: <UserPlus />, onSelect: () => console.log("invite") },
      ]}
      searchPlaceholder="Search workspaces"
      emptyText="No workspaces found"
      sheetTitle="Switch workspace"
    />
  )
}
```

Docs: https://wingo-ui.com/components/workspace-switcher (Markdown: https://wingo-ui.com/components/workspace-switcher.md)

### Overlays

#### Alert Dialog (`alert-dialog`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add alert-dialog`

A short modal question that must be answered, with an async confirm that loads, fails inline and shakes, plus an await confirm() API.

Press the trigger and the page dims while the card rises into the center on a smooth spring, its icon popping in a beat later. Focus lands on Cancel, the safe choice; Tab moves between the two buttons, Enter presses the focused one and Escape cancels. Clicking the dimmed page does nothing, because the question has to be answered. When the confirm returns a promise the action shows a spinner, Cancel and Escape wait, and the dialog closes once the request succeeds; if it fails the card shakes, the error slides in above the buttons and the action is ready to retry. In a type-to-confirm field Enter confirms as soon as the action is enabled. When it closes, focus goes back to the trigger, or to whatever had it before a confirm() call or a trigger-less open. On a phone it stays a centered card with the buttons stacked full width, the action on top and 44px tall. With reduced motion it only fades.

npm: @radix-ui/react-alert-dialog, motion, lucide-react
Wingo UI dependencies: button, motion, tones, use-controllable-state, ui-config

Props:
- `title?: ReactNode` = "": The question, phrased so the buttons answer it. Without one the dialog asks "Are you sure?", so a screen reader always has a title.
- `description?: ReactNode` = "": The consequence, in a sentence or two: what will be lost and whether it can be undone.
- `confirmLabel?: string` = "Continue": The action. Name what it does ("Delete listing"), not "Yes" or "OK".
- `cancelLabel?: string` = "Cancel": The safe way out. It gets the focus when the dialog opens.
- `confirmLoadingText?: string` = "": Next to the spinner while onConfirm runs, like "Deleting". The button reserves room for it, so it never changes width.
- `errorText?: ReactNode` = "": Shown above the buttons when onConfirm rejects or throws. When empty, the error's own message is used if it has one, then "Something went wrong. Try again."
- `hideTitle?: boolean` = false: Keeps the title for screen readers only, for a dialog whose description says it all.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the action and the icon tile. danger for anything destructive (with a trash icon), warning for unsaved changes, success for a positive step; neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the action and the icon tile, replacing the tone. Text on the button turns black or white by lightness.
- `size?: "sm" | "md"` = "sm": Max width 400px (sm) or 480px (md) for longer text. On a phone it is always 16px clear of both edges.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "lg": Corner shape of the card: 0, 12, 16 or 24px. The icon tile and the buttons follow along, and full turns them into a circle and pills.
- `align?: "start" | "center"` = "start": start reads like a desktop dialog with the buttons on the right; center stacks icon and text in the middle and splits the buttons evenly, like an iOS alert.
- `defaultOpen?: boolean` = false: Starts open while uncontrolled. The playground reopens it on change so every setting shows.
- `confirmDisabled?: boolean` = false: Blocks the action, e.g. until the listing's name is typed. Enter in a text field confirms once it is enabled.
- `open?: boolean`: Controlled open state; pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Called when it opens or closes, whether by the trigger, Cancel, Escape or a finished confirm.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild: a single element that takes a ref, usually a Button.
- `icon?: ReactNode`: Shown in a 40px tile above the title. Defaults to a trash can for danger, a triangle for warning and a check for success, and none for the rest; null hides it.
- `children?: ReactNode`: Extra content between the text and the buttons, like a type-to-confirm field. It scrolls when the screen is short.
- `onConfirm?: () => (void | Promise<unknown>)`: Runs on the action. Return a promise to keep the dialog open with the action loading: resolving closes it, rejecting (or throwing) shows the error and shakes the card. A late result after the dialog closed is ignored.
- `onCancel?: () => void`: Called on Cancel or Escape, not when the dialog closes after a confirm.
- `container?: HTMLElement | null`: Where the portal mounts. document.body by default.
- `classNames?: Partial<Record<"overlay" | "content" | "icon" | "header" | "title" | "description" | "body" | "error" | "footer" | "cancel" | "action", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the card, merged last. The rest of the props (id, aria-*, onOpenAutoFocus...) go to it too.

Parts:
- `confirm` (function): Asks from anywhere, even outside React: resolves true once confirmed (after onConfirm settled) and false when cancelled. Takes every AlertDialog prop except trigger and the open state. Calls made while one is open wait their turn, and focus returns to what had it when confirm() was called. Needs <AlertDialogProvider /> mounted; without it, development warns and the browser's confirm steps in. Signature: (options: ConfirmOptions) => Promise<boolean>.
- `useConfirm` (hook): The same confirm function, for code that prefers a hook. Signature: () => typeof confirm.
- `AlertDialogProvider` (component): Mount once near the root, next to the toaster. Renders confirm() calls one at a time; defaults go under every call's options (translated labels, a house tone). If the last provider unmounts, calls still waiting resolve false. Props: { defaults?: ConfirmOptions }.
- `AlertDialogRoot` (component): The parts API, for custom layouts: AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogBody, AlertDialogError, AlertDialogFooter, AlertDialogCancel and AlertDialogAction. Props: { open?; defaultOpen?; onOpenChange?; onCancel?; children }.
- `AlertDialogTrigger` (component): Opens it. Use asChild with a Button; focus returns here when the dialog closes. Props: Radix AlertDialog.Trigger props.
- `AlertDialogContent` (component): The overlay and the card. Takes size, tone, color, radius, align, container and classNames { overlay, content }, plus Radix Content props (onOpenAutoFocus, onCloseAutoFocus...). Props: AlertDialogContentProps.
- `AlertDialogHeader` (component): Title and description, with an optional icon tile above them in the content's tone. Scrolls on its own when the text outgrows a short screen. Props: { icon?: ReactNode; classNames?: { icon }; children } & ComponentProps<"div">.
- `AlertDialogIcon` (component): The 40px tile in the tone's soft color that pops in on the bouncy spring. The header renders it for you when you pass icon. Takes span props.
- `AlertDialogTitle` (component): The question, 18px semibold. Required by screen readers; hide it with the sr-only class if the design has none. Props: Radix AlertDialog.Title props.
- `AlertDialogDescription` (component): The consequence in muted text. Leave it out and pass aria-describedby={undefined} to the content. Props: Radix AlertDialog.Description props.
- `AlertDialogBody` (component): Extra content between the text and the buttons (a type-to-confirm field). Scrolls when the screen is short. Takes div props.
- `AlertDialogFooter` (component): The buttons: stacked full width below 640px with the action on top, a right-aligned row above (split evenly when align is center). Takes div props.
- `AlertDialogAction` (component): The confirm Button in the content's tone. Runs onConfirm with the loading, error and shake behavior; call event.preventDefault() in onClick to keep it from running. Props: ButtonProps & { onConfirm?; errorText? }.
- `AlertDialogCancel` (component): The soft Cancel Button. Focused on open, disabled while a confirm runs. Props: ButtonProps.
- `AlertDialogError` (component): Shows the failed confirm's message with role alert; children replace it. Takes p props.

```tsx
import type { ReactNode } from "react"
import { Trash2 } from "lucide-react"
import { AlertDialog, AlertDialogProvider, confirm } from "@/components/ui/alert-dialog"
import { Button } from "@/components/ui/button"

async function deleteListing(id: string) {
  const res = await fetch(`/api/listings/${id}`, { method: "DELETE" })
  if (!res.ok) throw new Error("Could not delete the listing. Try again.")
}

export function DeleteListing({ id }: { id: string }) {
  return (
    <AlertDialog
      trigger={
        <Button variant="soft" tone="danger" leftIcon={<Trash2 />}>
          Delete
        </Button>
      }
      tone="danger"
      title="Delete this listing?"
      description="The listing “Linus city bike” and its 12 messages will be deleted for good."
      confirmLabel="Delete"
      cancelLabel="Cancel"
      confirmLoadingText="Deleting"
      onConfirm={() => deleteListing(id)}
    />
  )
}

// the imperative api: mount the provider once, then await an answer anywhere
export function App({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <AlertDialogProvider defaults={{ cancelLabel: "Cancel" }} />
    </>
  )
}

export async function signOutEverywhere() {
  const ok = await confirm({
    title: "Sign out of every device?",
    description: "You stay signed in on this phone only.",
    confirmLabel: "Sign out",
  })
  if (ok) console.log("signed out")
}
```

Docs: https://wingo-ui.com/components/alert-dialog (Markdown: https://wingo-ui.com/components/alert-dialog.md)

#### Context Menu (`context-menu`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add context-menu`

The action menu on right-click for grids and lists, and an iOS-style action sheet on a long press on phones and touch screens.

Right-click a tile and the menu grows out of the pointer on a quick spring. Hover or use the arrow keys to move the highlight, type a letter to jump, Right opens a submenu and Left closes it, Enter or Space picks, Escape closes. The shortcuts written next to items run them while the menu is open. Keyboard users reach the same menu from a focused tile with Shift+F10 or the Menu key. On a phone or a touch screen, press and hold a tile: it dips slightly while you hold, a haptic tick fires, and an action sheet slides up with the tile's name on top, 48px rows, submenus as pages with a Back row and a Cancel button at the thumb. Scrolling never opens it, and text selection with a mouse still works. With reduced motion the tile does not dip and the menu and sheet fade.

npm: @radix-ui/react-context-menu, motion
Wingo UI dependencies: dropdown-menu, motion, use-long-press, use-media-query, use-shortcut, ui-config

Props:
- `children?: ReactNode`: The target. A single element (a card link, a row button) takes the handlers itself; anything else is wrapped in a <span>. Make it focusable so keyboard users can open the menu with Shift+F10.
- `items?: MenuEntry[]`: The same entries as the dropdown menu: items ({ label, icon, description, shortcut, badge, onSelect, href, tone: "danger", keepOpen }), { type: "checkbox" }, { type: "radio" }, { type: "submenu", items }, { type: "group" }, { type: "label" } and { type: "separator" }. With no enabled entry the browser's own menu shows.
- `title?: ReactNode` = "": The action sheet's centered header on phones, usually the name of what was pressed. Not shown on desktop. The demo uses each tile's title while this is empty.
- `description?: ReactNode` = "": A quieter line under the sheet title. The demo shows each tile's price and city while this is empty.
- `sheetTitle?: string` = "Actions": The sheet's title for screen readers when there is no visible title.
- `showCancel?: boolean` = true: The sheet's Cancel button at the bottom. The sheet still closes on a drag, a tap outside or Escape.
- `cancelLabel?: string` = "Cancel": The label of the sheet's Cancel button.
- `backLabel?: string` = "Back": The back row at the top of a submenu page in the sheet.
- `size?: "sm" | "md"` = "md": Item height 32 / 36px with 13 / 14px text. 44px on touch either way; sheet rows are always 48px.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Panel corners 0 / 12 / 16 / 24px (full falls back to lg); items keep the panel radius minus its 6px padding.
- `minWidth?: number` = 192: The panel's minimum width in px. It grows for longer labels up to 384px, then labels truncate.
- `pressFeedback?: boolean` = true: While a finger holds the target it dips to 0.97 on a snappy spring (iOS), and springs back when the sheet opens or the press is cancelled. Off under reduced motion.
- `disabled?: boolean` = false: The browser's own menu shows instead, and a long press does nothing.
- `responsive?: boolean` = true: Below 768px and on touch screens a long press (or a right-click) opens the action sheet. Off leaves Radix's own touch long press, which opens the floating menu at the finger.
- `longPressDelay?: number` = 450: How long a finger holds before the sheet opens, in ms (gestures.longPress). Moving more than 8px cancels, so scrolling never opens it.
- `loop?: boolean` = true: Arrow keys wrap from the last item to the first (menu and sheet).
- `modal?: boolean` = true: While the floating menu is open, the page behind ignores the pointer and does not scroll (Radix). The sheet is always modal.
- `onOpenChange?: (open: boolean) => void`: Called when the menu or the sheet opens or closes.
- `container?: HTMLElement | null`: Portal target for the menu and the sheet (default document.body).
- `classNames?: Partial<Record<"content" | "item" | "icon" | "label" | "description" | "shortcut" | "separator" | "sheet", string>>`: Extra classes for the parts: the panel (and sub panels), every row, row icons, labels, descriptions, shortcuts, separators and the sheet.
- `className?: string`: Extra classes for the target; any other prop (aria-*, data-*, handlers) is passed to it too. It carries data-state (open / closed) and, in sheet mode, data-pressing while a long press is held. To keep the browser menu on a link inside the target, stop it there: onContextMenu={(e) => e.stopPropagation()}.

Parts:
- `ContextMenuRoot` (component): Compound API: decides the mode once (the floating Radix menu, or the action sheet on phones and touch screens) and every part follows it. There is no open prop: a context menu opens at a pointer. Props: { onOpenChange, modal, responsive, disabled, longPressDelay, pressFeedback, container, dir, children }.
- `ContextMenuTrigger` (component): The target area (context-menu-trigger). One element child is used as the target (asChild by default); otherwise a <span>. Props: { asChild, disabled } & ComponentProps<"span">.
- `ContextMenuContent` (component): The panel (context-menu-content) with the popover spring from the pointer, or the action sheet. JSX children (the parts below) are desktop-only Radix rows, so a content with children keeps the floating menu everywhere, as if responsive were false. Props: { items, size, radius, minWidth, loop, title, description, sheetTitle, showCancel, cancelLabel, backLabel, container, classNames } & Radix ContextMenu.Content props.
- `ContextMenuItem` (component): A row. href renders an <a>; asChild takes a router Link and keeps the row layout. Its shortcut runs it while the menu is open. Props: { icon, description, shortcut, badge, tone: "neutral" | "danger", keepOpen, href, target, rel, asChild, disabled, onSelect }.
- `ContextMenuCheckboxItem` (component): A row with a leading checkbox whose check draws itself; it stays open while toggling. Props: { checked, defaultChecked, onCheckedChange, icon, description, shortcut, keepOpen = true, disabled }.
- `ContextMenuRadioGroup` (component): Holds one choice from a set of radio items. Props: { value, defaultValue, onValueChange }.
- `ContextMenuRadioItem` (component): One choice in a radio group, marked with a trailing check. Props: { value, icon, description, keepOpen = true, disabled }.
- `ContextMenuSub` (component): A nested menu: holds the open state of a side panel. Props: { open, defaultOpen, onOpenChange }.
- `ContextMenuSubTrigger` (component): The row with a chevron that opens the nested menu. Props: { icon, description, badge, disabled }.
- `ContextMenuSubContent` (component): The side panel of a nested menu. Props: { items, sideOffset, alignOffset, container }.
- `ContextMenuGroup` (component): Groups related items into a section. Takes Radix Group props.
- `ContextMenuLabel` (component): The small muted label of a section. Takes Radix Label props.
- `ContextMenuSeparator` (component): A hairline between sections. Takes Radix Separator props.

```tsx
import { Copy, ExternalLink, Heart, Trash2 } from "lucide-react"
import { ContextMenu, type ContextMenuEntry } from "@/components/ui/context-menu"

export function SavedListing({ favorite, onFavorite, onDelete }: { favorite: boolean; onFavorite: (next: boolean) => void; onDelete: () => void }) {
  const items: ContextMenuEntry[] = [
    { label: "Open", icon: <ExternalLink />, href: "/listings/park-slope-apartment" },
    { label: "Copy link", icon: <Copy />, shortcut: "mod+c", onSelect: () => navigator.clipboard.writeText("https://listings.example.com/a/123") },
    { type: "checkbox", label: "Favorite", icon: <Heart />, checked: favorite, onCheckedChange: onFavorite },
    { type: "separator" },
    { label: "Delete", icon: <Trash2 />, tone: "danger", onSelect: onDelete },
  ]

  return (
    <ContextMenu items={items} title="2-bedroom apartment, Park Slope" description="$489,000 · New York" cancelLabel="Cancel" backLabel="Back">
      {/* focusable, so Shift+F10 opens the menu from the keyboard */}
      <a href="/listings/park-slope-apartment" className="block rounded-2xl bg-surface p-3 shadow-raised">
        2-bedroom apartment, Park Slope
      </a>
    </ContextMenu>
  )
}
```

Docs: https://wingo-ui.com/components/context-menu (Markdown: https://wingo-ui.com/components/context-menu.md)

#### Dialog (`dialog`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add dialog`

The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body.

Click the trigger and the page dims while the card scales up from 96% on a smooth spring; the icon tile pops in a beat later. Focus moves to the first field, Tab stays inside, and Escape, a click on the dim page or the round × close it, handing focus back to the trigger. A long body scrolls between the pinned header and footer, and a hairline fades in under the header once it scrolls and above the footer while there is more below; with scrollBehavior outside the whole card scrolls with the page instead. A dialog opened from inside another one stacks on top while the first steps back and up, and closing it brings the first forward again. When it is not dismissible, a click outside or Escape only gives the card a small bump: an action has to answer it. A shortcut, when set, toggles it from anywhere. Below 768px it opens as a bottom sheet you can drag down to close, with the actions stacked full width, 48px tall and the primary on top. With reduced motion it only fades.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, lucide-react, motion
Wingo UI dependencies: button, drawer, motion, tones, use-controllable-state, use-media-query, use-scroll-edges, use-shortcut, ui-config

Props:
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state. The root keeps it across the 768px breakpoint, so resizing swaps the card for the sheet and keeps it open.
- `onOpenChange?: (open: boolean) => void`: Called when it opens or closes: the trigger, Escape, an outside click, a drag on the sheet, a close button, the shortcut.
- `title?: ReactNode` = "": The title, also the dialog's accessible name. Always pass one: without it a visually hidden “Dialog” stands in so screen readers still get a name. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A quieter line under the title, linked with aria-describedby. Without one the dialog opts out of the description (Radix's aria-describedby={undefined}).
- `hideTitle?: boolean` = false: Keeps the title for screen readers only, for dialogs whose content speaks for itself (a photo, a video).
- `closeLabel?: string` = "Close": aria-label of the × button, e.g. “Close dialog”. The demo spells it out under the page.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-keyshortcuts when a shortcut is set. Leave it out and control open yourself.
- `icon?: ReactNode`: An icon in a 40px tile before the title (above it when the header is centered), painted in the tone's soft color. It pops in on a bouncy spring as the card lands.
- `children?: ReactNode`: The body. It scrolls on its own between the pinned header and footer (overscroll contained) and drives the hairlines. Forms inside get the first field focused on open.
- `footer?: ReactNode`: The actions, primary last in the DOM: on the right in a row on desktop, on top when stacked. On the phone sheet they stack full width at 48px whatever size you passed. Wrap Cancel in DialogClose.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The icon tile's color: success for a confirmation, danger for a warning about data loss. Needs an icon.
- `color?: string` = "": Any CSS color for the icon tile. Replaces the tone; the icon is mixed toward the text color so it stays readable. Leave empty to use the tone.
- `size?: "sm" | "md" | "lg" | "xl" | "full"` = "md": Max width 400 / 520 / 720 / 960px, always 16px clear of the screen edges. full fills the screen minus 16px on desktop (a lightbox, a long editor) and becomes a full-height sheet on phones.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "lg": Corners 0 / 12 / 16 / 24px (full stays 24px); the icon tile follows. Dialogs default to lg like every large surface. The phone sheet takes 0 / 16 / 24 / 28px.
- `headerAlign?: "start" | "center"` = "start": start reads like a form: the icon beside the title. center reads like an announcement: the icon above a centered title, and the actions centered too.
- `showClose?: boolean` = true: The round × in the top corner (ghost, 32px with a 44px hit area on touch). It closes even a dialog that is not dismissible.
- `scrollBehavior?: "inside" | "outside"` = "inside": inside: the card stops at 85% of the screen (720px at most), the header and footer stay and the body scrolls. outside: the card grows with its content and the dimmed page scrolls instead, for long reading. The phone sheet and size full always scroll inside.
- `dismissible?: boolean` = true: false: outside clicks, Escape, the shortcut and the sheet drag do not close it; the card gives a small bump instead and the sheet loses its handle. The × and actions (DialogClose, or setting open) still close it, e.g. a consent that must be answered.
- `responsive?: boolean` = true: Below 768px it opens as the drawer's bottom sheet: drag to dismiss, safe-area padding, a 92% height for size full. Off, it stays a centered card on phones too.
- `shortcut?: string` = "": A key combo in mod+k notation (⌘ on Apple devices, Ctrl elsewhere) that toggles the dialog from anywhere on the page; the trigger gets aria-keyshortcuts. Empty binds nothing.
- `modal?: boolean` = true: false: no backdrop, no focus trap and no scroll lock; the page behind stays usable (Radix's modal), and on desktop a click on the page closes it. scrollBehavior outside needs the backdrop, so it scrolls inside then.
- `onOpenAutoFocus?: (event: Event) => void`: Runs when it opens, before focus moves. Desktop focuses the first focusable element (put the close button last, as the dialog does); the phone sheet focuses itself so no keyboard pops up. Call event.preventDefault() and focus something yourself.
- `onCloseAutoFocus?: (event: Event) => void`: Runs when it closes, before focus returns to the trigger. Prevent it to send focus elsewhere.
- `container?: HTMLElement | null`: Portal target, document.body by default.
- `classNames?: Partial<Record<"overlay" | "content" | "header" | "icon" | "title" | "description" | "body" | "footer" | "close", string>>`: Extra classes for the inner parts, in both modes: on phones they land on the sheet's parts, which carry the same data-slot="dialog-*" names (the backdrop and the handle keep drawer-overlay / drawer-handle).
- `className?: string`: Extra classes for the card (dialog-content), merged last.

Parts:
- `DialogRoot` (component): Compound API: holds the state and picks the mode (a Radix dialog, or the drawer's sheet below 768px). No DOM. Rendered inside another dialog's content it nests: the parent steps back while it is open. Props: { open, defaultOpen, onOpenChange, dismissible, responsive, modal, shortcut, container }.
- `DialogContent` (component): The portal, the backdrop (dialog-overlay), the card (dialog-content with data-size, data-scroll-behavior, data-nested, data-child-open) and the ×. Needs a DialogTitle inside (visuallyHidden if the design has none); pass aria-describedby={undefined} when there is no description. Props: { size, radius, scrollBehavior, showClose, closeLabel, container, classNames } & Radix Dialog.Content props.
- `DialogHeader` (component): The icon tile, title and description; keeps clear of the ×. Its bottom hairline fades in once the body scrolls. Without a title (and no children of its own) it renders a hidden “Dialog” title. Props: { title?, description?, hideTitle?, icon?, tone?, color?, align?: "start" | "center" }.
- `DialogTitle` (component): 18px semibold title (17px on the sheet), wired to aria-labelledby. Props: { visuallyHidden?: boolean } & Radix Dialog.Title props.
- `DialogDescription` (component): A muted 14px description, wired to aria-describedby. Takes Radix Dialog.Description props.
- `DialogIcon` (component): The 40px tone tile on its own, for custom headers. Props: { tone?, color? } & ComponentProps<"span">.
- `DialogBody` (component): The scroll region between header and footer. Reports its scroll edges for the hairlines; on the sheet it scrolls first and only then lets the sheet drag. A long text with nothing focusable inside joins the Tab order (with a ring) so the arrow and Page keys scroll it. Takes div props.
- `DialogFooter` (component): The actions, primary last: a right-aligned row from 640px, stacked with the primary on top below that, and 48px full-width buttons on the phone sheet. Its top hairline shows while the body has more below. Takes div props.
- `DialogTrigger` (component): Opens the dialog from any element. Takes Radix Dialog.Trigger props (asChild).
- `DialogClose` (component): Closes the dialog from any element, also one that is not dismissible. Takes Radix Dialog.Close props (asChild).
- `useDialog` (hook): The nearest dialog's state, e.g. to close it after a form saves, or to lay out differently on the phone sheet. Signature: () => { open: boolean, setOpen: (open: boolean) => void, sheet: boolean }.

```tsx
import { Pencil } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Dialog, DialogClose } from "@/components/ui/dialog"

export function EditListing({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <Dialog
      trigger={
        <Button variant="soft" leftIcon={<Pencil />}>
          Edit
        </Button>
      }
      title="Edit listing"
      description="Changes show up for buyers right away."
      icon={<Pencil />}
      closeLabel="Close dialog"
      shortcut="mod+e"
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Cancel</Button>
          </DialogClose>
          <Button loading={saving} loadingText="Saving" onClick={onSave}>
            Save
          </Button>
        </>
      }
    >
      <p className="text-sm text-muted-foreground">Title, price, city and description</p>
    </Dialog>
  )
}
```

Docs: https://wingo-ui.com/components/dialog (Markdown: https://wingo-ui.com/components/dialog.md)

#### Drawer (`drawer`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add drawer`

The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop.

Tap the trigger and the sheet slides up from the bottom on the iOS sheet curve while the page dims. Drag it down by the handle or anywhere on it and it follows your finger; let go past a quarter of its height, or flick it, and it closes, otherwise it settles back. A long list inside scrolls first and only drags the sheet once it is back at the top; the header hairline appears as soon as the list scrolls and the footer hairline while there is more below. Snap points stop it half open and a tap on the handle steps to the next point. A drawer opened from inside another one pushes the first one back, like iOS. Escape, a tap on the dim page or the close button close it, unless it is not dismissible. Opening moves focus to the sheet itself (no field pops the phone keyboard, Tab goes on to the first control; the desktop dialog focuses its first text field, or itself when there is none), keeps it inside while open and returns it to the trigger after. A shortcut, when set, toggles it from anywhere. From 768px it stays a centered sheet, or becomes a side panel from the right or a centered dialog, whichever desktop asks for. With reduced motion the sheet's slide ends in 200ms and the dialog only fades.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, lucide-react, motion, vaul
Wingo UI dependencies: button, motion, use-controllable-state, use-media-query, use-scroll-edges, use-shortcut, ui-config

Props:
- `defaultOpen?: boolean` = false: Starts open (uncontrolled) and skips the entrance animation. Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state. The root keeps it across the 768px breakpoint, so a resize never closes the drawer.
- `onOpenChange?: (open: boolean) => void`: Called when the drawer opens or closes, by the trigger, a drag, Escape, an outside tap or a close button.
- `title?: ReactNode` = "": The title under the handle, also the dialog's accessible name. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A quieter line under the title, linked with aria-describedby. Without one the drawer opts out of the description (Radix's aria-describedby={undefined}).
- `hideTitle?: boolean` = false: Keeps the title for screen readers only, for sheets whose content speaks for itself (a share sheet, a photo).
- `closeLabel?: string` = "Close": aria-label of the close button, e.g. “Close filters”. The demo spells it out under the page.
- `trigger?: ReactNode`: The element that opens the drawer, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-keyshortcuts when a shortcut is set.
- `children?: ReactNode`: The body. It scrolls on its own (overscroll contained), pads the home indicator when it is the last part, and drives the header and footer hairlines.
- `footer?: ReactNode`: Actions pinned under the body, primary first: stacked full width in sheets (primary on top), a row with the primary on the right in side and dialog modes. Give sheet buttons size="lg" fullWidth.
- `direction?: "bottom" | "top" | "left" | "right"` = "bottom": The edge it slides in from. Bottom and top sheets get the handle; left and right panels are 320 to 540px wide, always show the close button, and leave a tappable sliver of the page on phones.
- `desktop?: "sheet" | "side" | "dialog"` = "sheet": What it becomes at 768px and up. sheet: the same drawer, capped and centered. side: a panel floating 8px off the right edge. dialog: a centered dialog with a spring (no drag). Phones always get the sheet.
- `size?: "sm" | "md" | "lg" | "full"` = "md": Bottom and top sheets on desktop: max width 420 / 560 / 720px or the whole screen. Left, right and side panels: 320 / 400 / 540px or the whole screen. Dialog: 400 / 520 / 720px or 16px from every edge.
- `height?: "auto" | "full"` = "auto": auto grows with the content up to 92% of the screen; full always takes 92%. Sheets with snap points are full.
- `variant?: "attached" | "floating"` = "attached": attached sits on the screen edge with the outer corners square; floating keeps 8px off every edge and the safe area, with every corner rounded (the iOS 26 look). The desktop side panel always floats.
- `radius?: "none" | "sm" | "md" | "lg"` = "lg": Sheet corners 0 / 16 / 24 / 28px (28px is the design system's sheet radius). In dialog mode 0 / 12 / 16 / 24px. Any value through className="[--drawer-radius:20px]".
- `showHandle?: boolean` = true: The drag handle of bottom and top sheets. A tap on it steps through the snap points. A sheet that is not dismissible and has no snap points hides it, since there is nothing to drag (like iOS).
- `showClose?: boolean` = false: Adds the round close button to the corner of bottom and top sheets. Panels and dialogs always have one, since they have no handle.
- `overlay?: boolean` = true: The dim backdrop. Turned off, the invisible layer stays, so the page still does not scroll and a tap outside still closes. There is never one with modal={false}.
- `headerAlign?: "start" | "center"` = "start": Title and description alignment. center reads like an iOS sheet; the close button keeps both sides even.
- `dismissible?: boolean` = true: false: no drag to close, no outside tap, no Escape and no shortcut close, and no handle unless there are snap points. Only a close button or an action inside (DrawerClose, or setting open) closes it, e.g. terms that must be accepted.
- `modal?: boolean` = true: false: no overlay, no focus trap and no scroll lock; the page behind stays usable and readable, like a results sheet over a map. Focus is not moved into it on open.
- `handleOnly?: boolean` = false: Drags only from the handle, for content with its own horizontal gestures (a carousel, a map, a slider).
- `scaleBackground?: boolean` = false: Scales the page back behind the sheet like iOS. Needs vaul-drawer-wrapper="" (or data-vaul-drawer-wrapper="") on the element that wraps your app, e.g. <div vaul-drawer-wrapper="" className="min-h-dvh bg-background">. The demo marks its listings page.
- `repositionInputs?: boolean` = true: Moves the sheet up when the on-screen keyboard opens so the focused field stays visible. Turn it off for sheets that handle the keyboard themselves.
- `shortcut?: string` = "": A key combo in mod+k notation (⌘ on Apple devices, Ctrl elsewhere) that toggles the drawer from anywhere on the page; the trigger gets aria-keyshortcuts. Empty binds nothing.
- `snapPoints?: (number | string)[]`: Stops on the way up: fractions of the screen ([0.45, 1]) or px strings (["320px", 1]). The sheet becomes full height, starts at the first point, the body only scrolls at the last one, and a tap on the handle steps to the next. Ignored in desktop dialog mode.
- `activeSnapPoint?: number | string | null`: The current snap point, controlled. Uncontrolled it starts at the first point and returns there after a close.
- `onActiveSnapPointChange?: (point: number | string | null) => void`: Called when a drag or a handle tap settles on another snap point.
- `fadeFromIndex?: number`: The snap point index from which the overlay dims. Defaults to the last point, so a half open sheet leaves the page bright.
- `container?: HTMLElement | null`: Portal target, document.body by default. Inside a transformed or contain:layout element the sheet, its snap points and its 92% height stay within that element (the map example).
- `onAnimationEnd?: (open: boolean) => void`: Runs after the open or close animation with the state it ended in, e.g. to reset a form once the sheet is gone.
- `classNames?: Partial<Record<"overlay" | "content" | "handle" | "close" | "header" | "title" | "description" | "body" | "footer", string>>`: Extra classes for the inner parts: the backdrop, the sheet, the handle, the close button, and the header, title, description, body and footer the simple API renders (the same keys as the sheet).
- `className?: string`: Extra classes for the sheet (drawer-content), merged last. Set [--drawer-radius:20px] here for a custom corner.

Parts:
- `DrawerRoot` (component): Compound API: holds the state and picks the mode (vaul sheet on phones; sheet, side panel or Radix dialog from 768px). No DOM. Rendered inside another drawer's content it nests on its own. The popover, dialog, dropdown and context menu sheets are built from these parts. Props: { open, defaultOpen, onOpenChange, direction, desktop, snapPoints, activeSnapPoint, onActiveSnapPointChange, fadeFromIndex, dismissible, modal, handleOnly, scaleBackground, repositionInputs, shortcut, container, onAnimationEnd }.
- `DrawerContent` (component): The portal, the overlay (drawer-overlay), the sheet (drawer-content with data-mode, data-direction, data-variant, data-size), the handle and the close button. Needs a DrawerTitle inside (visuallyHidden if the design has none). Props: { size, height, variant, radius, showHandle, showClose, closeLabel, overlay, container, classNames } & Radix Dialog.Content props.
- `DrawerHeader` (component): The title row and description. Its bottom hairline fades in once the body scrolls. Props: { title?, description?, hideTitle?, align?: "start" | "center" }.
- `DrawerTitle` (component): 17px semibold in sheets, 18px in panels and dialogs. visuallyHidden keeps it for screen readers only. Props: { visuallyHidden?: boolean } & Radix Dialog.Title props.
- `DrawerDescription` (component): Muted 14px text, wired to aria-describedby. Props: Radix Dialog.Description props.
- `DrawerBody` (component): The scroll region. Reports its scroll edges to the header and footer, pads the safe area when it is the last part, and stays still below the last snap point so the sheet drags instead. Takes div props.
- `DrawerFooter` (component): Pinned actions, primary first. Stacked in sheets, a row in side and dialog modes; its top hairline shows while the body has more below. Takes div props.
- `DrawerTrigger` (component): Opens the drawer from any element. Takes Radix Dialog.Trigger props (asChild).
- `DrawerClose` (component): Closes the drawer from any element, also one that is not dismissible. Takes Radix Dialog.Close props (asChild).
- `useDrawer` (hook): The nearest drawer's state, e.g. to close it after a form saves or to lay out differently in dialog mode. Signature: () => { open: boolean, setOpen: (open: boolean) => void, mode: "sheet" | "side" | "dialog", direction }.

```tsx
import { SlidersHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Drawer, DrawerClose } from "@/components/ui/drawer"

export function ListingFilters({ results, onReset }: { results: number; onReset: () => void }) {
  return (
    <Drawer
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
      title="Filters"
      description="New York · 1,240 listings"
      desktop="side"
      closeLabel="Close filters"
      shortcut="mod+j"
      footer={
        <>
          <DrawerClose asChild>
            <Button size="lg" fullWidth>
              Show {results} results
            </Button>
          </DrawerClose>
          <Button size="lg" variant="ghost" fullWidth onClick={onReset}>
            Reset
          </Button>
        </>
      }
    >
      <p className="text-sm text-muted-foreground">Price, condition and categories</p>
    </Drawer>
  )
}
```

Docs: https://wingo-ui.com/components/drawer (Markdown: https://wingo-ui.com/components/drawer.md)

#### Dropdown Menu (`dropdown-menu`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add dropdown-menu`

The action menu: icons, descriptions, shortcuts, badges, checkbox and radio items, submenus, and an iOS action sheet on phones.

Click the trigger and the menu grows out of it on a quick spring. Hover or use the arrow keys to move the highlight (it wraps around), type a letter to jump to an item, Right opens a submenu and Left closes it, Enter or Space picks, Escape closes and focus returns to the trigger. The shortcuts written next to items run them while the menu is open, and an optional shortcut opens the menu from anywhere. Checkbox and radio items tick in place (the check draws itself) and keep the menu open; danger items turn red. On a phone the same menu slides up as an action sheet: 48px rows, the title centered on top, a Cancel button where the thumb is, and drag down to dismiss. A submenu row slides a new page in from the right with a Back row while the sheet resizes to fit. Opened from the keyboard, the sheet focuses its first row; the arrow keys move between rows, Right opens a submenu page and Left goes back. With reduced motion the menu and the pages fade instead of moving.

npm: @radix-ui/react-dropdown-menu, lucide-react, motion
Wingo UI dependencies: button, drawer, motion, use-controllable-state, use-media-query, use-shortcut, ui-config

Props:
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state. The root keeps it across the 768px breakpoint, so resizing never closes the menu.
- `onOpenChange?: (open: boolean) => void`: Called when the menu opens or closes: the trigger, an item, Escape, an outside click, the sheet's Cancel or a drag.
- `items?: MenuEntry[]`: The entries: items ({ label, icon, description, shortcut, badge, onSelect, href, tone: "danger", keepOpen }), { type: "checkbox", checked, onCheckedChange }, { type: "radio", value, onValueChange, options }, { type: "submenu", items }, { type: "group", label, items }, { type: "label" } and { type: "separator" }. Groups and radio sets get separators around them on their own. An onSelect that opens a dialog should wait a frame (requestAnimationFrame) so focus returns to the trigger first. With no enabled entry the trigger is disabled.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild: a single element that takes a ref (a Button, an Avatar wrapped in a button). It gets aria-keyshortcuts when a shortcut is set.
- `children?: ReactNode`: Extra rows after the items, built from the parts (DropdownMenuItem and friends). They render in the sheet too.
- `title?: ReactNode` = "": The action sheet's header on phones, centered and small like iOS (usually what the actions apply to). Not shown on desktop. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A quieter line under the sheet title, linked with aria-describedby. The demo shows its sample while this is empty.
- `sheetTitle?: string` = "Actions": The sheet's title for screen readers when there is no visible title.
- `showCancel?: boolean` = true: The sheet's Cancel button at the bottom, where the thumb is. The sheet still closes on a drag, a tap outside or Escape without it.
- `cancelLabel?: string` = "Cancel": The label of the sheet's Cancel button.
- `backLabel?: string` = "Back": The back row at the top of a submenu page in the sheet.
- `size?: "sm" | "md"` = "md": Item height 32 / 36px with 13 / 14px text and 14 / 16px icons. 44px on touch either way; sheet rows are always 48px.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Panel corners 0 / 12 / 16 / 24px (full falls back to lg). Items keep the panel radius minus its 6px padding, so lg rows are pills.
- `minWidth?: number` = 192: The panel's minimum width in px. It grows for longer labels up to 384px (and never past the screen), then labels truncate.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": The side of the trigger it opens on. It flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How it lines up with the trigger. end suits a ⋯ button at the right edge of a row.
- `sideOffset?: number` = 8: The gap between the trigger and the panel, in px.
- `loop?: boolean` = true: Arrow keys wrap from the last item to the first (desktop and sheet). The demo says which it does.
- `modal?: boolean` = true: While open, the page behind ignores the pointer and does not scroll (Radix). The sheet on phones is always modal.
- `responsive?: boolean` = true: Below 768px the menu becomes an action sheet with large rows and submenu pages. Turn it off to keep the floating menu.
- `shortcut?: string` = "": A key combo in mod+k notation (⌘ on Apple, Ctrl elsewhere) that opens and closes the menu from anywhere on the page. Empty binds nothing.
- `onOpenAutoFocus?: (event: Event) => void`: Sheet only: runs when the action sheet takes focus. Opened with the keyboard it focuses the first row, opened by a tap the sheet itself; preventDefault to focus something else. The desktop menu focuses its first item on a key open (Radix).
- `container?: HTMLElement | null`: Portal target for the menu and the sheet (default document.body).
- `classNames?: Partial<Record<"content" | "item" | "icon" | "label" | "description" | "shortcut" | "separator" | "sheet", string>>`: Extra classes for the parts: the panel (and sub panels), every row, row icons, labels, descriptions, shortcuts, separators, and the sheet.
- `className?: string`: Extra classes for the panel (or the sheet), merged last. Other Radix content props (onCloseAutoFocus, alignOffset, avoidCollisions…) pass through.

Parts:
- `DropdownMenuRoot` (component): Compound API: holds the state and decides the mode once (the floating Radix menu, or the action sheet below 768px). Every part below reads it and renders for that mode, so one tree works on desktop and on phones. Props: { open, defaultOpen, onOpenChange, modal, responsive, shortcut, container, dir, children }.
- `DropdownMenuTrigger` (component): Opens the menu; with asChild any element that takes a ref. It carries aria-keyshortcuts when the root has a shortcut. Props: Radix DropdownMenu.Trigger props (asChild).
- `DropdownMenuContent` (component): The panel (dropdown-menu-content with data-size, data-radius, data-side) with the popover spring, or the sheet on phones. Renders items first, then JSX children, and runs item shortcuts while open. Props: { items, size, radius, minWidth, title, description, sheetTitle, showCancel, cancelLabel, backLabel, container, classNames } & Radix DropdownMenu.Content props.
- `DropdownMenuItem` (component): A row. href renders an <a>; asChild takes your router Link and keeps the row layout around its text (a Link that prevents the click still closes the menu). In the sheet it is a 48px button. Props: { icon, description, shortcut, badge, tone: "neutral" | "danger", keepOpen, href, target, rel, asChild, disabled, onSelect }.
- `DropdownMenuCheckboxItem` (component): A row with a leading checkbox whose check draws itself; it stays open while toggling unless keepOpen is false. Props: { checked, defaultChecked, onCheckedChange, icon, description, shortcut, keepOpen = true, disabled } ("indeterminate" allowed).
- `DropdownMenuRadioGroup` (component): Holds one choice from a set of radio items. Props: { value, defaultValue, onValueChange }.
- `DropdownMenuRadioItem` (component): One choice in a radio group, marked with a trailing check. Pass keepOpen={false} for a sort menu that closes on pick. Props: { value, icon, description, keepOpen = true, disabled }.
- `DropdownMenuSub` (component): A nested menu: holds the open state of the side panel on desktop, a pushed page with a Back row in the sheet. Props: { open, defaultOpen, onOpenChange }.
- `DropdownMenuSubTrigger` (component): The row with a chevron that opens the nested menu. Props: { icon, description, badge, disabled }.
- `DropdownMenuSubContent` (component): The side panel (or sheet page) of a nested menu. Props: { items, sideOffset, alignOffset, container }.
- `DropdownMenuGroup` (component): Groups related items into a section. Takes Radix Group props.
- `DropdownMenuLabel` (component): The small muted label of a section. Takes Radix Label props.
- `DropdownMenuSeparator` (component): A hairline between sections. Takes Radix Separator props.
- `MenuSheet` (component): The action sheet on its own, with its own drawer root: open it from a long press or a split button (context-menu and button-group use it on phones). Props: { open, defaultOpen, onOpenChange, items, title, description, sheetTitle, showCancel, cancelLabel, backLabel, loop, container, classNames, className, children, onCloseAutoFocus }.
- `MenuItemContent` (component): The inside of a row (checkbox, icon, label and description, badge, shortcut, chevron or radio check) for any Radix menu item; slot sets the data-slot prefix, e.g. context-menu. Props: { label, icon, description, badge, shortcut, submenu, indicator: "checkbox" | "radio", checked, size, sheet, tone, slot, classNames }.
- `MENU_CLASSES` (constant): The shared class recipe (content, item, itemWithDescription, icon, label, description, shortcut, badge, groupLabel, separator, subChevron, check, sheetItem, sheetSeparator...), so context menus and split buttons match.
- `menuItemClass` (function): The menu row class for a size, radius and tone.
- `menuSheetItemClass` (function): The bottom sheet row class for a size, radius and tone.

```tsx
import { Copy, Ellipsis, Pencil, Share2, Trash2 } from "lucide-react"
import { Button } from "@/components/ui/button"
import { DropdownMenu, type MenuEntry } from "@/components/ui/dropdown-menu"

export function ListingActions({ onEdit, onDelete }: { onEdit: () => void; onDelete: () => void }) {
  const items: MenuEntry[] = [
    { label: "Edit", icon: <Pencil />, shortcut: "mod+e", onSelect: onEdit },
    { label: "Duplicate", icon: <Copy />, shortcut: "mod+d" },
    {
      type: "submenu",
      label: "Share",
      icon: <Share2 />,
      items: [{ label: "WhatsApp" }, { label: "Copy link", shortcut: "mod+c" }],
    },
    { type: "separator" },
    // a confirm dialog waits a frame, so focus is back on the trigger when it opens
    { label: "Delete", icon: <Trash2 />, tone: "danger", onSelect: () => requestAnimationFrame(onDelete) },
  ]

  return (
    <DropdownMenu
      align="end"
      items={items}
      title="Pegas city bike"
      description="$420 · Brooklyn"
      trigger={
        <Button variant="ghost" size="icon" radius="full" aria-label="Listing actions">
          <Ellipsis />
        </Button>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/dropdown-menu (Markdown: https://wingo-ui.com/components/dropdown-menu.md)

#### Family Drawer (`family-drawer`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add family-drawer`

A floating bottom drawer that morphs smoothly between stacked views, inspired by the Family app.

Press the trigger to open a floating bottom drawer with an Options menu. Pick an option and the drawer morphs into that view: its height eases to fit the new content while the old view fades and shrinks away and the new one scales in, with the crossfade timed to how far the height has to travel. Cancel, Reveal or Continue step back to the menu. Drag the drawer down, tap the backdrop, press Escape or use the close button to dismiss it. Buttons press in on tap.

npm: clsx, motion, react-use-measure, vaul
Wingo UI dependencies: ui-config

Props:
- `triggerLabel?: string` = "Try it out": Text on the built-in trigger button. Ignored when you pass your own trigger.
- `title?: string` = "Options": Heading of the built-in menu view, also the drawer's accessible name.
- `closeLabel?: string` = "Close": Accessible name of the round close button.
- `defaultView?: string` = "default": The view shown first. The built-in views are default, key, phrase and remove; with your own views, any key of views.
- `size?: "sm" | "md" | "lg"` = "md": Maximum width of the drawer: 320px (sm), 361px (md) or 420px (lg). It always keeps a 16px margin on phones.
- `radius?: number` = 36: Corner radius of the drawer in pixels.
- `accent?: string` = "#4DAFFF": Fill of the primary action in the built-in views (Reveal).
- `danger?: string` = "#FF3F40": Any CSS color for the destructive action in the built-in views: the Remove Wallet row (tinted to 12%) and the Continue button.
- `surface?: string` = "": Any CSS color for the drawer panel. Empty uses #FEFFFE light and the popover token dark. The built-in views keep the theme's text and button colors, so pick a surface that suits the theme (or restyle your own views).
- `showCloseButton?: boolean` = true: Shows the round close button in the top right corner (32px, with a 44px hit area on touch screens).
- `dismissible?: boolean` = true: Lets a downward drag, a backdrop tap or Escape close the drawer. Turn it off to require the close button or an action inside a view.
- `defaultOpen?: boolean` = false: Starts open when uncontrolled. Ignored when open is set.
- `open?: boolean`: Controlled open state. Pass it with onOpenChange to drive the drawer yourself.
- `onOpenChange?: (open: boolean) => void`: Called with the next open state from the trigger, the close button, a drag, the backdrop or Escape.
- `trigger?: ReactNode`: Your own trigger element, rendered as the drawer trigger through asChild. Replaces the built-in button.
- `views?: Record<string, ReactNode | ((api: { view, setView, close }) => ReactNode)>`: Your own views keyed by name, replacing the built-in wallet views. A function receives setView to morph to another view and close to dismiss the drawer.
- `onViewChange?: (view: string) => void`: Called with the name of the view the drawer morphs to.
- `className?: string`: Extra classes merged onto the drawer panel, for example a different surface color.

Parts:
- `DefaultView` (component): The built-in Options menu: a title row and three option buttons that switch to the key, phrase and remove views.
- `Key` (component): The built-in Private Key view: header, three safety notes, Cancel and Reveal.
- `Phrase` (component): The built-in Secret Recovery Phrase view, laid out like Key.
- `RemoveWallet` (component): The built-in confirmation view: a warning header with Cancel and Continue.
- `Header` (component): The icon, title and description block at the top of a detail view. Use it in your own views to match.
- `Button` (component): A 48px gray menu row with an icon and a label, as in the Options view.
- `SecondaryButton` (component): A 48px pill button for the actions at the bottom of a view; color it with className or style.
- `LockIcon` (component): 24px lock glyph of the View Private Key row. The other stock glyphs follow the same pattern: PhraseIcon, WarningIcon, CloseIcon, CrossIcon, ShieldIcon, PassIcon, BannedIcon, FaceIDIcon, and the 48px RecoveryPhraseIcon and DangerIcon headers.
- `FamilyDrawerApi` (type): What a view function receives: { view, setView, close }.
- `FamilyDrawerView` (type): A view: plain content, or (api: FamilyDrawerApi) => ReactNode to switch views or close the drawer.

```tsx
import FamilyDrawer from "@/components/ui/family-drawer"

export function Demo() {
  return <FamilyDrawer triggerLabel="Wallet options" />
}

// your own views: each one can morph to another view or close the drawer
// <FamilyDrawer
//   triggerLabel="Delete project"
//   views={{
//     default: ({ setView }) => <button onClick={() => setView("confirm")}>Delete</button>,
//     confirm: ({ close }) => <button onClick={close}>Yes, delete it</button>,
//   }}
// />
```

Docs: https://wingo-ui.com/components/family-drawer (Markdown: https://wingo-ui.com/components/family-drawer.md)

#### Hover Card (`hover-card`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add hover-card`

A rich preview of a person, listing or link that floats in on hover or focus, and opens as a bottom sheet with a tap on touch screens.

Rest the pointer on a link or a name and after half a second the preview grows out of it on a quick spring. Move onto the card and it stays open, so its buttons and links work; leave both and it fades out 200ms later. Tab to the trigger and it opens the same way; Escape or moving focus on closes it. The card is a supplement: its content is skipped by Tab and every action in it is reachable elsewhere. On phones and tablets there is no hover, so the first tap opens the preview as a bottom sheet instead of following the link: drag it down, tap the dim page or press Escape to close it, and the sheet's own link leads on. With reduced motion it only fades.

npm: @radix-ui/react-hover-card, @radix-ui/react-slot, motion
Wingo UI dependencies: ui-config, drawer, motion, use-controllable-state, use-media-query

Props:
- `trigger?: ReactNode`: What you hover, rendered asChild: an <a>, a router Link, a Button or an avatar wrapped in a button. It must pass a ref to its element. Plain text gets a focusable button with a dotted underline, for a name or a term inside a sentence.
- `children?: ReactNode`: The preview: an avatar row and stats, a listing with its photo, an article with its image. Round inner parts with rounded-(--hover-card-inner-radius), which follows radius and padding (and is 16px in the sheet). Put a real link to the destination in it for touch screens.
- `sheetTitle?: string` = "Preview": The bottom sheet's title for screen readers. The sheet shows no header, but a dialog needs a name: say what it previews, like "Profilul Anei Pop".
- `size?: "sm" | "md" | "lg" | "auto"` = "md": Width of the floating card: 256, 288 or 384px, or auto to fit the content (192px at least). Never wider than the screen minus 12px a side. The sheet always spans the phone.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the card: 0, 12, 16 or 24px; full falls back to lg. The sheet keeps its own 28px top corners.
- `padding?: "none" | "sm" | "md" | "lg"` = "md": Inner padding of the card: 0, 8, 16 or 20px. none lets a photo run to the edges (the card clips it to its corners), sm gives an inset photo with a matching smaller radius. The sheet always pads 20px.
- `arrow?: boolean` = false: A small arrow with a rounded tip in the card's color, pointing at the trigger. Its sides carry on the card's hairline and it keeps clear of the corners.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the card opens. It flips to the opposite side and slides along the edge when there is no room.
- `align?: "start" | "center" | "end"` = "center": Alignment along the trigger's edge.
- `sideOffset?: number` = 8: Distance from the trigger in px. The arrow adds its own 8px on top.
- `openDelay?: number` = 500: Hover (or keyboard focus) time in ms before it opens, so the pointer can cross a page full of links without cards popping up. 0 opens at once.
- `closeDelay?: number` = 200: Time in ms before it closes after the pointer leaves the trigger and the card. It is the grace period for travelling onto the card; at 0 it closes before you get there.
- `responsive?: boolean` = true: On phones (below 768px) and touch screens (a coarse pointer, like an iPad at 1024px) the first tap on the trigger opens the preview as a bottom sheet instead of following the link. Off: the floating card everywhere, and a tap follows the link.
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Leaving the trigger and the card, Escape or a click outside closes it.
- `disabled?: boolean` = false: Never opens and closes if it is open, e.g. for your own name in a list. The trigger keeps working: a link navigates on click and on tap.
- `open?: boolean`: Controls it from outside, with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Called on hover, focus, a tap on touch screens, Escape and outside clicks. Not called for opens refused while disabled.
- `container?: HTMLElement | null`: Where the card (or the sheet) mounts. document.body by default.
- `classNames?: Partial<Record<"content" | "body" | "arrow", string>>`: Extra classes for the card (hover-card-content, also the sheet), its padded scroll region (hover-card-body) and the arrow svg (set a fill-* to recolor it).
- `className?: string`: Extra classes for the card, merged last. Other Radix content props pass through: alignOffset, collisionPadding (12), avoidCollisions, sticky, hideWhenDetached, onEscapeKeyDown, onPointerDownOutside.

Parts:
- `HoverCardRoot` (component): Compound API: holds the state and picks the mode once (the Radix hover card, or the drawer's bottom sheet on phones and touch screens). No DOM. Props: { open, defaultOpen, onOpenChange, openDelay, closeDelay, responsive, disabled }.
- `HoverCardTrigger` (component): An <a> (or your child with asChild) that opens the card on hover and focus, or the sheet on a tap, where it keeps the link from navigating. A plain element gets data-slot="hover-card-trigger" and data-state; a component child keeps its own and gets data-hover-card-state. Props: ComponentProps<"a"> & { asChild?: boolean }.
- `HoverCardContent` (component): The portaled, animated card (hover-card-content with data-side, data-align, data-size, data-state) and its body (hover-card-body); in sheet mode the drawer's sheet with the same slots and a hidden title. Props: { side, align, sideOffset, size, radius, padding, arrow, sheetTitle, container, classNames } & Radix HoverCard.Content props.
- `useHoverCard` (hook): The nearest hover card's state, for content that lays out bigger in the sheet (44px buttons, a larger avatar) or closes the card after an action. Signature: () => { open: boolean, setOpen: (open: boolean) => void, sheet: boolean }.

```tsx
import { HoverCard } from "@/components/ui/hover-card"
import { Avatar } from "@/components/ui/avatar"

export function Mention() {
  return (
    <p className="text-sm">
      Ask{" "}
      <HoverCard
        trigger={
          <a href="/profile/emma.carter" className="font-semibold underline decoration-foreground/25 underline-offset-4">
            @emma.carter
          </a>
        }
        sheetTitle="Emma Carter's profile"
      >
        <div className="flex items-center gap-3">
          <Avatar src="/demo/ana-pop.jpg" name="Emma Carter" size="lg" status="online" className="[--avatar-ring:var(--popover)]" />
          <div className="min-w-0">
            <p className="text-[15px] font-semibold">Emma Carter</p>
            <p className="text-[13px] text-muted-foreground">Portland · member since 2019</p>
          </div>
        </div>
        <p className="mt-3 text-[13px] text-muted-foreground">48 listings · 4.9 ★ · replies in 1 h</p>
        <a href="/profile/emma.carter" className="mt-3 inline-block font-medium underline underline-offset-4">
          View profile
        </a>
      </HoverCard>{" "}
      about the bike.
    </p>
  )
}
```

Docs: https://wingo-ui.com/components/hover-card (Markdown: https://wingo-ui.com/components/hover-card.md)

#### Popover (`popover`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add popover`

Rich floating content anchored to a trigger, like a quick filter, form or share panel, that becomes a bottom sheet on phones.

Click the trigger and the panel grows out of it on a quick spring, pointing at the trigger when it has an arrow. It flips to the other side and slides along the edge when there is no room, and stays anchored while the page scrolls. Focus moves to the first field so you can type at once (on a touch screen the panel itself takes focus, so no keyboard pops up); Escape or a click outside closes it and focus returns to the trigger; Tab past the last control (or Shift+Tab past the first) leaves it in reading order and closes it. A modal popover keeps focus inside and blocks the page until it closes. A shortcut, when set, toggles it from anywhere. Below 768px the same content opens as a bottom sheet you can drag down: the header and footer stay pinned, the body scrolls, and the footer stacks full-width 48px buttons with the primary action on top. With reduced motion it only fades.

npm: @radix-ui/react-popover, @radix-ui/react-slot, lucide-react, motion
Wingo UI dependencies: button, drawer, motion, use-controllable-state, use-media-query, use-shortcut, ui-config

Props:
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state. The root keeps it across the 768px breakpoint, so turning a tablet never closes the popover.
- `onOpenChange?: (open: boolean) => void`: Called when it opens or closes: the trigger, Escape, a click outside, focus leaving it, the shortcut or a close button.
- `title?: ReactNode` = "": An optional heading at the top, 15px semibold; it names the panel for screen readers. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A quieter line under the title, wired to aria-describedby.
- `closeLabel?: string` = "Close": aria-label of the close button, e.g. a translated “Close” for another language.
- `sheetTitle?: string` = "Details": The name screen readers hear while there is no title: the bottom sheet's hidden title on phones and the panel's aria-label on desktop.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-expanded, aria-controls, data-state and, with a shortcut, aria-keyshortcuts.
- `children?: ReactNode`: The body, 14px text. It scrolls when the panel would be taller than the space on screen.
- `footer?: ReactNode`: Actions under the body, primary last: a right-aligned row of size="sm" buttons in the panel, stacked full width with the primary on top in the sheet (buttons grow to 48px there on their own).
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": The side of the trigger it opens on. It flips to the opposite side when there is no room.
- `align?: "start" | "center" | "end"` = "center": How it lines up with the trigger along that side: its start edge, its center or its end edge.
- `sideOffset?: number` = 8: Gap in px between the trigger and the panel (the arrow adds its own 8px).
- `alignOffset?: number` = 0: Shifts the panel along the trigger's edge, in px, from where align puts it.
- `size?: "sm" | "md" | "lg" | "auto"` = "md": Width 256 / 288 / 384px, or auto to fit the content (at least 192px). Always at most the screen width minus 24px.
- `padding?: "none" | "sm" | "md" | "lg"` = "md": Space inside the panel: 0 / 12 / 16 / 20px. none is for full-bleed lists and media. The sheet on phones keeps its own 20px sides (check usePopover().sheet to lay out rows for it).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius 0 / 12 / 16 / 24px (full is 24px, like every floating surface). The sheet keeps its 28px top corners.
- `arrow?: boolean` = false: A 16 x 8 arrow with a rounded tip pointing at the trigger, in the panel's color with the same hairline. It keeps clear of the rounded corners and hides when it cannot point at the trigger.
- `showClose?: boolean` = false: A round X in the top corner, centered on the title's line. Escape and a click outside always close it too.
- `modal?: boolean` = false: Traps focus inside, blocks clicks on the page and locks its scroll until the popover closes. For a confirm or a form that must be finished or cancelled.
- `responsive?: boolean` = true: Below 768px it opens as the drawer's bottom sheet: handle, drag to dismiss, pinned header and footer, safe-area padding. false keeps the floating panel on phones (an autocomplete under a field).
- `shortcut?: string` = "": A key combo in mod+k notation (⌘ on Apple devices, Ctrl elsewhere) that toggles it from anywhere on the page; the trigger gets aria-keyshortcuts. Empty binds nothing.
- `onOpenAutoFocus?: (event: Event) => void`: Runs when it opens, before focus moves in. Call event.preventDefault() to keep focus where it is (an anchored suggestion list under a field).
- `container?: HTMLElement | null`: Portal target, document.body by default. The sheet renders there too.
- `classNames?: Partial<Record<"content" | "viewport" | "header" | "title" | "description" | "body" | "footer" | "close" | "arrow", string>>`: Extra classes for the inner parts: the panel, its scrolling viewport (which holds the padding), the header, title, description, body, footer, the close button and the arrow. The same keys style the sheet's parts on phones.
- `className?: string`: Extra classes for the panel (popover-content), merged last, e.g. w-(--radix-popover-trigger-width) to match an anchor. A width here never narrows the sheet.

Parts:
- `PopoverRoot` (component): Compound API: holds the state, binds the shortcut and picks the mode (a Radix popover, or the drawer below 768px). No DOM. Props: { open, defaultOpen, onOpenChange, modal, responsive, shortcut, container }.
- `PopoverTrigger` (component): Opens and closes it; gets aria-expanded, aria-controls and aria-keyshortcuts when a shortcut is set. In the sheet it is the drawer trigger. Props: Radix Popover.Trigger props (asChild).
- `PopoverAnchor` (component): Positions the panel against another element, such as a field, while the trigger stays elsewhere (or is left out); in the sheet it is a plain wrapper. Props: Radix Popover.Anchor props (asChild).
- `PopoverContent` (component): The portal and the panel (popover-content with data-side, data-align, data-size) around a scrolling viewport, plus the close button and the arrow. In the sheet, loose children become the body on their own; keep the header, body and footer as direct children (fragments are fine) so the sheet can pin them. Props: { side, align, sideOffset, alignOffset, size, radius, padding, arrow, showClose, closeLabel, sheetTitle, container, classNames } & Radix Popover.Content props.
- `PopoverHeader` (component): The heading block (title and description stacked, gap 4px). Renders nothing when empty; in the sheet it is the drawer header. Props: { title?, description? } & div props.
- `PopoverTitle` (component): 15px semibold title that labels the panel (aria-labelledby). In the sheet it is the drawer title. Props: h2 props.
- `PopoverDescription` (component): 13px muted line that describes the panel (aria-describedby). In the sheet it is the drawer description. Props: p props.
- `PopoverBody` (component): The body, 14px text; the scroll region in the sheet. Takes div props.
- `PopoverFooter` (component): The actions row, primary last on the right; stacked full width with the primary on top in the sheet. Takes div props.
- `PopoverClose` (component): Closes it from any element, such as an Apply button. Props: Radix Popover.Close props (asChild).
- `PopoverArrow` (component): The 16 x 8 arrow that arrow={true} renders, in the popover color; nothing in the sheet. Props: Radix Popover.Arrow props.
- `usePopover` (hook): The nearest popover's state, e.g. to close it after a save or to size footer buttons for the sheet. Signature: () => { open, setOpen, sheet }.

```tsx
import { ChevronDown } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Popover, PopoverClose } from "@/components/ui/popover"

export function PriceFilter({ onApply, onReset }: { onApply: () => void; onReset: () => void }) {
  return (
    <Popover
      trigger={
        <Button variant="soft" rightIcon={<ChevronDown />}>
          Price
        </Button>
      }
      title="Price"
      description="Pick a range or type your own."
      align="start"
      arrow
      sheetTitle="Price filter"
      footer={
        <>
          <Button variant="ghost" size="sm" onClick={onReset}>
            Reset
          </Button>
          <PopoverClose asChild>
            <Button size="sm" onClick={onApply}>
              Apply
            </Button>
          </PopoverClose>
        </>
      }
    >
      <p className="text-muted-foreground">Between $500 and $1,500</p>
    </Popover>
  )
}
```

Docs: https://wingo-ui.com/components/popover (Markdown: https://wingo-ui.com/components/popover.md)

#### Sheet (`sheet`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add sheet`

A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch.

Click the trigger and the panel glides in from its edge on a spring while the page dims in step with it; it leaves the same way, a little faster. On a touch screen drag a side panel toward its edge, or a top or bottom sheet by its handle or header: it follows your finger, the dim lightens as it goes, and letting go past a quarter of its size (or a quick flick) closes it from right there, while a shorter drag springs back. Vertical scrolling inside a side panel stays native, and sideways scrollers and fields keep their own gestures. Escape, a click on the dimmed page or the X close it unless it is not dismissible; focus stays inside while it is open and goes back to the trigger after. A shortcut such as mod+j toggles it from anywhere. The header hairline appears once the body scrolls and the footer hairline while more is below. Non-modal sheets leave the page clickable and stay open while you work next to them. With reduced motion it fades instead of sliding.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, lucide-react, motion
Wingo UI dependencies: ui-config, button, motion, use-controllable-state, use-media-query, use-scroll-edges, use-shortcut

Props:
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state. It lives in the root, so crossing 768px with mobileSide keeps the sheet open.
- `onOpenChange?: (open: boolean) => void`: Called when the sheet opens or closes: the trigger, a swipe, Escape, an outside click, the X or the shortcut.
- `title?: ReactNode` = "": The header title, also the sheet's accessible name. Without one, screen readers hear a hidden “Panel”; always pass a real one. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A quieter line under the title, linked with aria-describedby. Without one the sheet opts out of the description (Radix's aria-describedby={undefined}).
- `hideTitle?: boolean` = false: Keeps the title for screen readers only, for sheets that carry their own header (a menu with a logo). The body then starts at the top, so leave room for the X in its first row.
- `closeLabel?: string` = "Close": aria-label of the X button. Translate it together with the rest of your copy.
- `trigger?: ReactNode`: The element that opens the sheet, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-keyshortcuts when a shortcut is set.
- `children?: ReactNode`: The body. It scrolls on its own (overscroll contained), pads the home indicator when it is the last part, and drives the header and footer hairlines.
- `footer?: ReactNode`: Actions pinned under the body. Put the primary action last: it lands on the right from 640px and on top when the buttons stack full width on a phone.
- `side?: "right" | "left" | "top" | "bottom"` = "right": The edge it slides in from. Left and right are logical, so an rtl page mirrors them (the swipe too). Top and bottom sheets get a grab handle on touch screens.
- `mobileSide?: "auto" | "right" | "left" | "top" | "bottom"` = "auto": The side below 768px. auto keeps side (a nav menu from the left stays on the left); bottom turns a right filter panel into a bottom sheet on phones.
- `size?: "sm" | "md" | "lg" | "xl" | "full"` = "md": Left and right: 320 / 400 / 540 / 720px wide, capped so a 48px sliver of the page stays tappable on a phone, or the whole screen. Top and bottom: as tall as the content up to 50 / 70 / 85 / 92% of the screen, or all of it. full always shows the X.
- `variant?: "attached" | "floating"` = "attached": attached sits flush on its edge and rounds only the inner corners. floating hovers 8px off the screen edges and the safe areas with every corner rounded.
- `radius?: "none" | "sm" | "md" | "lg"` = "lg": Corner size: 0 / 12 / 16 / 24px. Attached top and bottom sheets take the bottom-sheet corner, 28px, at lg. Any other value falls back to lg.
- `overlay?: boolean` = true: The dim backdrop. Turned off, a modal sheet still locks the page and closes on an outside click; it just does not darken it.
- `showClose?: boolean` = true: The X in the top corner (a 44px target on touch). Always shown at size full, where no page is left to tap.
- `showHandle?: boolean` = true: The grab handle of top and bottom sheets. It only appears on touch screens while the sheet can be swiped.
- `modal?: boolean` = true: false: no overlay, no focus trap, no scroll lock. The page stays usable and clicks on it never close the sheet, like an inspector next to a list.
- `dismissible?: boolean` = true: Outside clicks, Escape, swipes and the shortcut close it. false leaves only the X and your own actions (a SheetClose or setting open).
- `swipeToClose?: boolean` = true: On touch screens, drag it toward its edge to close: side panels from anywhere on them, top and bottom sheets from the handle or header. Past a quarter of its size or a flick closes, less springs back. Mark a child data-sheet-no-drag to keep its own gestures.
- `shortcut?: string` = "": A key combo in mod+k notation (⌘ on Apple, Ctrl elsewhere) that toggles the sheet from anywhere. The trigger gets aria-keyshortcuts. Empty binds nothing.
- `container?: HTMLElement | null`: Portal target. Defaults to document.body.
- `classNames?: Partial<Record<"overlay" | "content" | "header" | "title" | "description" | "body" | "footer" | "close" | "handle", string>>`: Extra classes for the parts. The header, title, description, body and footer parts read theirs from the content, so this works with the parts API too.
- `className?: string`: Extra classes for the panel (sheet-content). Set any corner with [--sheet-radius:20px].

Parts:
- `SheetRoot` (component): The state and the Radix Dialog root, without DOM. Build custom sheets from the parts inside it. Props: { open, defaultOpen, onOpenChange, modal, dismissible, shortcut, container, children }.
- `SheetTrigger` (component): Opens the sheet. Use asChild with your own button; it carries aria-keyshortcuts for the root's shortcut. Props: ComponentProps<typeof Dialog.Trigger>.
- `SheetContent` (component): The portal, the overlay and the animated panel with its handle and X. Radix Content props (onOpenAutoFocus, onEscapeKeyDown, aria-describedby...) pass through. It focuses the panel itself on open; pass onOpenAutoFocus to focus a field. Props: { side, mobileSide, size, variant, radius, overlay, swipeToClose, showClose, showHandle, closeLabel, container, classNames } & Dialog.Content props.
- `SheetHeader` (component): The title row (room left for the X); a hairline fades in under it once the body scrolls. On top and bottom sheets it is also a drag area. Props: { title?, description?, hideTitle?, children? }.
- `SheetTitle` (component): The accessible name and description. visuallyHidden keeps the title for screen readers only. Props: ComponentProps<typeof Dialog.Title> & { visuallyHidden? }.
- `SheetDescription` (component): The accessible name and description. visuallyHidden keeps the title for screen readers only. Props: ComponentProps<typeof Dialog.Description>.
- `SheetBody` (component): The scroll region between header and footer. It reports its scroll edges for the hairlines. Takes div props.
- `SheetFooter` (component): Pinned actions: stacked full width below 640px (last child on top), a right-aligned row above that wraps in a narrow panel. Takes div props.
- `SheetClose` (component): Closes the sheet, also when it is not dismissible. Use asChild on a footer button. Props: ComponentProps<typeof Dialog.Close>.
- `useSheet` (hook): The nearest sheet's state, e.g. to close it once a form has saved. Signature: () => { open: boolean; setOpen: (open: boolean) => void; side: SheetSide | undefined }.

```tsx
import { SlidersHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Sheet, SheetClose } from "@/components/ui/sheet"

export function ListingFilters({ results, onReset }: { results: number; onReset: () => void }) {
  return (
    <Sheet
      side="right"
      mobileSide="bottom"
      title="Filters"
      description="Biciclete · Cluj-Napoca"
      shortcut="mod+j"
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
      footer={
        <>
          <Button variant="ghost" onClick={onReset}>
            Reset
          </Button>
          <SheetClose asChild>
            <Button>Show {results} results</Button>
          </SheetClose>
        </>
      }
    >
      <p className="text-sm text-muted-foreground">Price, condition and delivery.</p>
    </Sheet>
  )
}
```

Docs: https://wingo-ui.com/components/sheet (Markdown: https://wingo-ui.com/components/sheet.md)

#### Shortcuts Dialog (`shortcuts-dialog`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add shortcuts-dialog`

The "?" overlay every keyboard-friendly app has: all shortcuts grouped and searchable, in the notation of the device.

Press ? anywhere (not while typing) and the dialog springs in with every shortcut grouped in two columns; press it again to close. Keys show as ⌘ ⇧ glyphs on a Mac and Ctrl / Shift words elsewhere, alternatives read "⌘ K or /" and sequences "G then I". With a mouse or trackpad the search takes focus at once: type a word, a key ("ctrl", "shift", "⌘") or a group name and the rows narrow instantly with the matching letters underlined, groups without matches disappear and an empty state fades in when nothing is left; the card keeps its height while you search, so nothing jumps. Esc clears the search first, then closes; Tab moves between the search, the clear button and the close button. On a phone it is a tall bottom sheet in one column with the search pinned under the title (it keeps its height while you filter), opened from a trigger such as a help menu entry; swipe it down or tap outside to close, and the keyboard only appears when you tap the search.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, dialog, input, kbd, use-controllable-state, use-media-query, use-shortcut, motion, text-match

Props:
- `groups?: ShortcutGroup[]` = "[]": { id?, label?: ReactNode, textValue?, items: ShortcutEntry[] }. An entry is { id?, label: ReactNode, shortcut: string | string[], description?: ReactNode, sequence?: boolean, keywords?: string[], textValue?: string }. Shortcuts use mod+k notation; an array is alternatives ("mod+k" or "/"), or the keys of a sequence when sequence is true (["g", "i"]). An unparseable shortcut shows its raw text in one cap. Empty groups are hidden.
- `title?: ReactNode` = "Keyboard shortcuts": The dialog title. "" keeps it for screen readers only.
- `description?: ReactNode` = "": A muted line under the title.
- `searchPlaceholder?: string` = "Search shortcuts": The search field's placeholder and accessible name.
- `emptyText?: ReactNode` = "No shortcuts found": Shown when nothing matches the search.
- `thenLabel?: string` = "then": Between the keys of a sequence ("G then I"). Screen readers read it too.
- `orLabel?: string` = "or": Between alternatives ("⌘ K or /").
- `closeLabel?: string` = "Close": aria-label of the close button.
- `clearLabel?: string` = "Clear": aria-label of the search's clear button.
- `hint?: ReactNode`: The footer line. Default: "Press ? anytime to see this list" with the bound key as a cap, hidden on touch screens; null hides it. Pass a translated node for localized apps.
- `size?: "md" | "lg" | "xl"` = "lg": The dialog's max width: 520 / 720 / 960px. On phones the sheet with a search is 92% tall, so filtering never resizes it; without a search it fits its content.
- `radius?: "none" | "sm" | "md" | "lg"` = "lg": Corner shape of the card (sm 12px, md 16px, lg 24px) and of the phone sheet's top corners.
- `platform?: "auto" | "apple" | "other"` = "auto": The key notation: apple shows ⌘ ⇧ ⌥ glyphs, other Ctrl / Shift / Alt words. auto renders the other form on the server, then the device's.
- `kbdVariant?: "soft" | "outline" | "solid"` = "soft": The key cap look: the quiet gray key, a bordered key or a raised physical key.
- `kbdSize?: "sm" | "md"` = "sm": Key cap height, 16 or 20px.
- `columns?: 1 | 2` = 2: Groups side by side from 768px. Phones always get one column.
- `defaultOpen?: boolean` = false: Starts open while uncontrolled.
- `open?: boolean`: Controlled open state; pair it with onOpenChange (e.g. to open it from a help menu entry).
- `onOpenChange?: (open: boolean) => void`: Called when it opens or closes (trigger, shortcut, Esc, outside click, swipe).
- `shortcut?: string` = "?": Opens and closes it from anywhere, in mod+k notation. Keys without a modifier never fire while typing, so "?" in the search types a "?". "" binds nothing. The showcase itself listens for ?, so the demo binds ⌘/ in its place.
- `search?: boolean` = true: A filter field above the groups. It matches labels, keywords, descriptions and the shortcut in both notations, ignoring case and diacritics; it takes focus on open only with a mouse or trackpad.
- `responsive?: boolean` = true: A bottom sheet below 768px (one column, search pinned). false keeps the centered card on phones.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild (a single element that takes a ref); it gets aria-keyshortcuts.
- `container?: HTMLElement | null`: Portal target, document.body by default.
- `classNames?: Partial<Record<"content" | "header" | "search" | "groups" | "group" | "groupLabel" | "row" | "label" | "description" | "keys" | "then" | "or" | "mark" | "empty" | "hint", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the dialog card (or the sheet), merged last. Other props (aria-*, data-*, style, onOpenAutoFocus, onEscapeKeyDown, ref) go to the same element.

```tsx
import { Keyboard } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Kbd } from "@/components/ui/kbd"
import { ShortcutsDialog, type ShortcutGroup } from "@/components/ui/shortcuts-dialog"

const groups: ShortcutGroup[] = [
  {
    label: "General",
    items: [
      { label: "Search", shortcut: ["mod+k", "/"] },
      { label: "Shortcuts", shortcut: "?" },
      { label: "Toggle sidebar", shortcut: "mod+b" },
    ],
  },
  {
    label: "Navigation",
    items: [
      { label: "Go to Inbox", shortcut: ["g", "i"], sequence: true },
      { label: "Go to Clients", shortcut: ["g", "c"], sequence: true },
    ],
  },
  {
    label: "Invoices",
    items: [
      { label: "New invoice", shortcut: "f", keywords: ["issue"] },
      { label: "Send by email", shortcut: "mod+enter" },
      { label: "Download PDF", shortcut: "shift+mod+d" },
    ],
  },
]

export function HelpShortcuts() {
  return (
    <ShortcutsDialog
      groups={groups}
      title="Keyboard shortcuts"
      hint={
        <span className="inline-flex items-center gap-1.5">
          Press <Kbd shortcut="?" size="sm" /> any time to open the list
        </span>
      }
      trigger={
        <Button variant="soft" size="sm" leftIcon={<Keyboard />}>
          Shortcuts
        </Button>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/shortcuts-dialog (Markdown: https://wingo-ui.com/components/shortcuts-dialog.md)

#### Tooltip (`tooltip`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add tooltip`

A short inverted label for icon buttons and cut-off values: shortcut hints, toolbar groups that skip the delay, long press on touch.

Rest the pointer on a trigger and after 300ms the label fades in, growing a touch out of the trigger. Inside a TooltipGroup only the first one waits: glide along a toolbar and each next label swaps in at once. Tab to a trigger and its tooltip opens straight away; Escape, a click, a scroll or moving away closes it. The pointer can travel onto the tooltip without closing it. A shortcut shows after the text in the notation of your device (⌘C on a Mac, Ctrl+C elsewhere) and is announced as aria-keyshortcuts. Phones have no hover, so a long press shows the label instead: the button does not fire, the tooltip stays while your finger is down and for 1.5 seconds after, and the next touch dismisses it. Shortcut hints hide on touch screens. With reduced motion it only fades.

npm: @radix-ui/react-tooltip, @radix-ui/react-slot, motion
Wingo UI dependencies: kbd, use-controllable-state, use-long-press, use-shortcut, motion, tones, ui-config

Props:
- `content?: ReactNode` = "": The label: a few words for an icon button, or a sentence with size md. Empty renders the trigger alone, so a tooltip can come and go without re-mounting the button.
- `shortcut?: string` = "": A combo in mod+k notation ("s", "mod+c", "alt+n", "shift+mod+p"), shown after the text at 60% of its color and set as aria-keyshortcuts on the trigger. Display only: bind the key yourself with useShortcut. Hidden on touch screens.
- `children?: ReactNode`: The trigger, rendered asChild: a Button, an <a>, or a span with tabIndex={0}. It must pass a ref to its element. A disabled <button> gets no pointer events, so wrap it in a focusable span. A plain string gets a focusable span of its own. It keeps its own data-slot and data-state; the tooltip's state is in data-tooltip-state.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": neutral is the inverted tooltip: black on a light page, near-white on a dark one. Other tones fill with their color, for a label that carries meaning (out of stock, verified).
- `color?: string` = "": Any CSS color. Replaces the tone; the text turns black or white by lightness. Leave empty to use the tone.
- `size?: "sm" | "md"` = "sm": sm is one short centered line in 12px medium type, up to 256px wide. md is for a sentence: 13px, more padding, left aligned, up to 288px wide. Both shrink to the room left on screen, so a flipped tooltip wraps on a phone instead of running off the edge.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled with the size: md is 8px on sm and 10px on md. full is a pill on one line and a soft capsule on a wrapped sentence.
- `arrow?: boolean` = false: A small arrow with a rounded tip in the tooltip's color, pointing at the center of the trigger and kept clear of the corners.
- `side?: "top" | "right" | "bottom" | "left"` = "top": Where it opens. It flips to the opposite side and slides along the edge when there is no room.
- `align?: "start" | "center" | "end"` = "center": Alignment along the trigger's edge.
- `sideOffset?: number` = 6: Distance from the trigger in px. The arrow adds its own height on top.
- `delayDuration?: number` = 300: Hover time in ms before it opens. Keyboard focus opens it at once. Inside a TooltipGroup the group's delay wins (the playground feeds this value to the group).
- `longPress?: boolean` = true: On touch screens a long press on the trigger shows the tooltip, with a light vibration where supported. The click that would follow is swallowed, so the button does not fire. Off: touch never shows it.
- `touchDuration?: number` = 1500: How long in ms it stays after the finger lifts from a long press. The next touch anywhere closes it sooner.
- `overflowOnly?: boolean` = false: Opens only while the trigger's text is cut off (truncate or line-clamp on the trigger or inside it), so a cell shows its full value only when it needs to. The playground's heart never overflows, so it stays quiet.
- `defaultOpen?: boolean` = false: Starts open. The next hover elsewhere, click or scroll closes it.
- `disabled?: boolean` = false: Never opens and closes if it is open. The trigger itself keeps working.
- `open?: boolean`: Controls it from outside, with onOpenChange. Handy for a confirmation like "Link copied" after a click.
- `onOpenChange?: (open: boolean) => void`: Called on hover, focus, long press, Escape, click and scroll. Not called for opens that are refused (disabled, overflowOnly with nothing cut off, a tap on a touch screen).
- `container?: HTMLElement | null`: Where the portal mounts. document.body by default.
- `classNames?: Partial<Record<"content" | "arrow" | "shortcut", string>>`: Extra classes for the tooltip body, the arrow svg and the shortcut Kbd.
- `className?: string`: Extra classes for the tooltip body (the trigger is your child), merged last. Other Radix content props (alignOffset, collisionPadding, avoidCollisions, onEscapeKeyDown, aria-label) pass through.

Parts:
- `TooltipGroup` (component): Wrap a toolbar: the first tooltip waits delayDuration (300), then moving to the next within skipDelayDuration (300) opens it at once with a quick fade. Tooltips outside a group bring their own provider, so no setup is needed. Props: { delayDuration?: number; skipDelayDuration?: number; disableHoverableContent?: boolean; children }.
- `TooltipRoot` (component): State and behavior for the parts: open, defaultOpen, onOpenChange, delayDuration, disabled, longPress, touchDuration, overflowOnly, shortcut, disableHoverableContent. Props: TooltipRootProps.
- `TooltipTrigger` (component): Wires hover, focus and long press onto its child (asChild) or its own <button>, and sets aria-keyshortcuts. Props: ComponentProps<"button"> & { asChild?: boolean }.
- `TooltipContent` (component): The portaled, animated body: side, align, sideOffset, arrow, tone, color, size, radius, container, classNames and the Radix content props. Renders the Root's shortcut after its children. Props: TooltipContentProps.

```tsx
import { Copy, Heart, Share2 } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipGroup } from "@/components/ui/tooltip"

export function ListingActions({ onSave, onCopy }: { onSave: () => void; onCopy: () => void }) {
  return (
    <TooltipGroup>
      <div className="flex items-center gap-1">
        <Tooltip content="Save to favorites" shortcut="s">
          <Button variant="ghost" size="icon" radius="full" aria-label="Save to favorites" onClick={onSave}>
            <Heart />
          </Button>
        </Tooltip>
        <Tooltip content="Share">
          <Button variant="ghost" size="icon" radius="full" aria-label="Share">
            <Share2 />
          </Button>
        </Tooltip>
        <Tooltip content="Copy link" shortcut="mod+c" side="bottom" arrow>
          <Button variant="ghost" size="icon" radius="full" aria-label="Copy link" onClick={onCopy}>
            <Copy />
          </Button>
        </Tooltip>
      </div>
    </TooltipGroup>
  )
}

// a value that only shows its tooltip when it is cut off
export function Address({ value }: { value: string }) {
  return (
    <Tooltip content={value} overflowOnly>
      <span tabIndex={0} className="block max-w-40 truncate">
        {value}
      </span>
    </Tooltip>
  )
}
```

Docs: https://wingo-ui.com/components/tooltip (Markdown: https://wingo-ui.com/components/tooltip.md)

#### Tour (`tour`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tour`

A product tour that dims the page around the real UI, explains each step in a card and docks at the bottom on phones, plus hotspots.

Start the tour with its button or the shortcut and the page dims around the first target: a rounded spotlight hugs the element and a card beside it explains the step. Next, Back and Skip sit in the card; the progress dots can be clicked to jump. Each step scrolls its target into view first, then the spotlight glides there on a spring and the card fades in beside it; steps without a target show a centered card. Keys: Right arrow or Enter goes next, Left goes back, Escape skips (announced), Tab stays inside the card, and focus returns to where it was when the tour ends. Interactive steps let clicks and typing reach the highlighted element, and advanceOn click moves on when you press the real button. On a phone the card docks at the bottom above the safe area and the keyboard, its target is scrolled into the top half, and a swipe left or right pages the steps. With persistKey a finished or skipped tour is remembered and autoStart leaves it alone. TourHotspot is a pulsing dot on a new feature: tap or click it for a hint (a bottom card on phones); once seen it stays away. Reduced motion makes the spotlight jump and the cards fade.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: button, kbd, progress, use-controllable-state, use-keyboard-inset, use-media-query, use-persisted-state, use-shortcut, haptics, motion, tones, ui-config

Props:
- `steps: TourStep[]`: The steps: { id, target? (selector, function or ref), title, content?, media?, side? (top / right / bottom / left / auto), align?, spotlightPadding?, spotlightRadius?, interactive?, advanceOn?: "click", beforeEnter?, nextLabel? }. A step without a target, or whose target is not found within 1s, shows a centered card.
- `defaultOpen?: boolean` = false: Starts open. Use open / onOpenChange to control it, or start() from useTour / setApi.
- `open?: boolean`: Controlled open state. Only one tour shows at a time; a second one waits for the first to close.
- `onOpenChange?: (open: boolean) => void`: Called when the tour opens or closes.
- `defaultStep?: number` = 0: The step index it starts at.
- `step?: number`: Controlled step index.
- `onStepChange?: (step: number) => void`: Called with the new index on Next, Back, a dot, a swipe or goTo.
- `onComplete?: () => void`: Called when the last step's Done is pressed (or finish()).
- `onSkip?: () => void`: Called on Skip, the close button, Escape, an overlay click with closeOnOverlayClick, or skip().
- `persistKey?: string` = "": Local storage key that remembers the tour was completed or skipped. autoStart does not start a finished tour; start() still does, and reset() forgets it.
- `autoStart?: boolean` = false: Opens once after hydration and a 600ms settle, unless persistKey says it was already finished.
- `shortcut?: string` = "": A global key that starts the tour, in mod+k notation. Empty binds nothing; the demo passes "shift+h" (the showcase owns ?).
- `spotlight?: boolean` = true: Dims the page with a rounded cutout around the target and blocks clicks elsewhere. false shows only the cards, with an arrow (a ring alone marks the target when the card is docked), and leaves the page usable (coachmarks).
- `overlayOpacity?: number` = 0.55: Strength of the dim. Dark mode adds 0.1 so the page still recedes behind the card.
- `spotlightPadding?: number` = 8: Room in px between the target and the edge of the cutout. Steps can override it.
- `spotlightRadius?: number` = 14: Corner radius of the cutout in px, capped at half the smaller side. Steps can override it.
- `showProgress?: "dots" | "fraction" | "bar" | "none"` = "dots": How the card shows where you are: dots (clickable), 2 / 5, a thin bar, or nothing (screen readers still hear it).
- `size?: "sm" | "md"` = "md": Card width 288 / 340px (never wider than the screen minus 24px), with matching padding and type.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "lg": Card corners: 0, 12, 16 or 24px; full falls back to lg. The docked phone card keeps its 28px sheet top.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the Next button and the progress.
- `color?: string` = "": Any CSS color for the Next button and the progress; replaces the tone.
- `showSkip?: boolean` = true: A Skip button in the card on every step but the last.
- `showClose?: boolean` = true: The × in the card's corner (on phones it shows only when Skip is hidden). It skips the tour.
- `keyHints?: boolean` = true: Shows the → key on the Next button on desktops. Hidden on touch screens.
- `closeOnOverlayClick?: boolean` = false: A click on the dimmed area skips the tour. Off by default so a stray tap does not end it.
- `scrollBehavior?: "smooth" | "instant"` = "smooth": How targets scroll into view (instant under reduced motion). Nested scrollers scroll too.
- `mobileLayout?: "docked" | "popover"` = "docked": Below 768px the card docks at the bottom where the thumb is, with a 44px Next and swipe paging, and targets scroll into the top half. popover keeps the desktop card.
- `docked?: boolean` = false: Docks the card at every width, e.g. inside a phone mockup.
- `container?: Element | null`: Where the overlay renders (default document.body). A transformed element becomes the frame: the dim, the spotlight and the docked card stay inside it.
- `setApi?: (api: TourApi) => void`: Receives { start(stepId?), next(), previous(), goTo(index | id), skip(), finish(), reset() } once mounted.
- `labels?: Partial<TourLabels>`: Every string: next "Next", back "Back", skip "Skip tour", done "Done", close "Close tour", progress(i, n) "Step i of n", stepAnnounce(i, n, title), skipped "Tour closed", completed "Tour completed". DEFAULT_TOUR_LABELS has the English set.
- `classNames?: Partial<Record<"overlay" | "spotlight" | "card" | "media" | "title" | "content" | "progress" | "actions" | "close" | "handle", string>>`: Extra classes for the inner parts.
- `children?: ReactNode`: Rendered in place; anything inside can read the tour with useTour().

Parts:
- `TourHotspot` (component): A pulsing dot on a corner of its children (or of target) that opens a hint: title, content, placement ("top-end" | "top-start" | "bottom-end" | "bottom-start"), offset, side, align, persistKey (gone once seen), tone, color, pulse, open / defaultOpen / onOpenChange, onDismiss, responsive (a bottom card below 768px), labels { open, dismiss "Got it" }, classNames. Props: TourHotspotProps.
- `useTour` (hook): The nearest tour's API plus { open, step, count, status }; null outside a Tour. Signature: () => TourState | null.

```tsx
import { useRef } from "react"
import { Button } from "@/components/ui/button"
import { Tour, type TourStep } from "@/components/ui/tour"

export function ClientsTour() {
  const search = useRef<HTMLInputElement>(null)
  const invoice = useRef<HTMLButtonElement>(null)
  const steps: TourStep[] = [
    { id: "welcome", title: "Welcome to Northwind CRM", content: "We show you where everything is in 30 seconds." },
    { id: "search", target: search, title: "Find any client", content: "A name, an EIN or a city." },
    { id: "invoice", target: invoice, title: "Issue an invoice", content: "Press New invoice.", advanceOn: "click" },
  ]
  return (
    <Tour
      steps={steps}
      persistKey="northwind-crm:tour"
      autoStart
      shortcut="shift+h"
      labels={{ next: "Continue" }}
    >
      <input ref={search} placeholder="Search clients" />
      <Button ref={invoice}>New invoice</Button>
    </Tour>
  )
}
```

Docs: https://wingo-ui.com/components/tour (Markdown: https://wingo-ui.com/components/tour.md)

### Feedback

#### Alert (`alert`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add alert`

An inline message about a page or a section, from a failed payment to a maintenance banner, in three variants and six tones.

The alert sits in the page and never blocks it: server-rendered alerts show up as they are, and one that appears later (after a failed submit) fades in without pushing the page around. Its actions are real buttons that match the tone, and on a solid fill they flip to the fill's text color. With dismissible on, the close button (or Tab to it, then Enter or Space) fades the alert out while its space collapses and the content below slides up; open it again and it springs back in. With reduced motion it only fades. Closing it with focus inside moves focus to the next control instead of dropping it on the page (after a tap a text field is skipped, so the phone keyboard never pops up). Errors and warnings are announced by screen readers right away, other tones politely. On a phone two or more actions stretch into a full-width button bar under the text, and the close button keeps a 44px hit area. As a banner it spans the page: one line with the actions at the end once it is wide enough, stacked on a phone or in a narrow panel.

npm: motion, lucide-react
Wingo UI dependencies: button, motion, tones, use-controllable-state, ui-config

Props:
- `title?: ReactNode` = "": The headline, in the tone's text color. Without it the description lines up with the icon.
- `description?: ReactNode` = "": The message under the title. Long words wrap instead of overflowing, and links inside stay underlined.
- `closeLabel?: string` = "Dismiss": Accessible name of the close button, read by screen readers. Translate it with the rest of the page.
- `variant?: "soft" | "outline" | "solid"` = "soft": soft is a tinted surface for most messages, outline a hairline on the page for quieter ones, solid a full fill for urgent banners.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": danger for errors, warning for things that need attention, success for done, info for tips. Also picks the default icon and the screen reader role.
- `color?: string` = "": Any CSS color. Replaces the tone for the tint, the border, the fill, the icon and the actions; text on a solid fill turns black or white by lightness.
- `size?: "sm" | "md"` = "md": md for page and section messages (16px padding, 20px icon). sm for inline form messages (12px padding, 13px text, 16px icon).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape: 0, 12, 16 or 24px; full falls back to 24px. A banner is always square.
- `banner?: boolean` = false: A full-bleed page banner: no radius, a bottom border, the content centered in max-w-5xl. It lays out by its own width: one line with the actions at the end from 672px, stacked below that. At the very top of a phone screen, add pt-[env(safe-area-inset-top)].
- `dismissible?: boolean` = false: Shows a close button. Pressing it sets open to false and the alert collapses out.
- `defaultOpen?: boolean` = true: Starts visible. A server-rendered alert shows up at once and one mounted later fades in; keep it mounted and flip open to collapse it out and expand it back.
- `open?: boolean`: Controlled visibility. When set, the parent decides whether a dismiss really closes it.
- `onOpenChange?: (open: boolean) => void`: Called with false when the close button is pressed, controlled or not.
- `icon?: ReactNode`: The leading icon. Defaults per tone: Info for neutral and info, Sparkles for brand, CircleCheck for success, TriangleAlert for warning, CircleAlert for danger. Pass null to hide it; the text then starts at the edge.
- `actions?: ReactNode`: Buttons under the text, usually AlertAction: a small Button (ButtonProps) in the alert's tone and color, solid by default (pass variant for secondary actions) and inverted on a solid alert so it always reads. On a phone two or more share the alert's full width like a native button bar; in a wide banner they sit at the end of the line.
- `children?: ReactNode`: Extra content under the description, or the parts for full control: AlertTitle (the headline, sized and colored by the alert), AlertDescription (the message; takes paragraphs, lists and links) and AlertActions (the row of actions, wrapping on phones and at the end of the line in a wide banner).
- `role?: "alert" | "status" | "none"`: The live region. Unset, it follows the tone: "alert" for danger and warning (announced at once), "status" for the rest (announced politely). "none" adds no role, for alerts that are part of the page from the start.
- `classNames?: Partial<Record<"wrapper" | "container" | "icon" | "content" | "title" | "description" | "actions" | "close", string>>`: Extra classes for the inner parts. wrapper is the full-width collapsing element around the alert (put grid or flex placement there); container is the centered row of a banner.
- `className?: string`: Extra classes for the alert surface, merged last. Override the tone vars here, e.g. [--tone-soft:...]. In a flex column or grid the collapse also takes the parent's gap along, so nothing snaps when it closes.

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

export function PaymentError({ onRetry }: { onRetry: () => void }) {
  return (
    <Alert
      tone="danger"
      title="We could not process the payment"
      description="Your bank declined the card. Try another card or pay on delivery."
      actions={
        <>
          <AlertAction onClick={onRetry}>Try again</AlertAction>
          <AlertAction variant="ghost">Pay on delivery</AlertAction>
        </>
      }
      dismissible
      closeLabel="Close"
    />
  )
}

// the parts, for lists and custom layouts
export function ListingChecklist() {
  return (
    <Alert tone="warning">
      <AlertTitle>The listing cannot be published yet</AlertTitle>
      <AlertDescription>
        <ul className="list-disc ps-4">
          <li>Add at least 3 photos</li>
          <li>Fill in the floor area</li>
        </ul>
      </AlertDescription>
      <AlertActions>
        <AlertAction>Complete it</AlertAction>
      </AlertActions>
    </Alert>
  )
}
```

Docs: https://wingo-ui.com/components/alert (Markdown: https://wingo-ui.com/components/alert.md)

#### Banner (`banner`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add banner`

A full-width announcement strip for the top of an app, a page or a panel, with tones, one action and a dismissal it remembers.

The strip says one thing to everyone: an icon, a bold title and the rest of the sentence on the same line, with one action at the end. Press the action and it shows a spinner while its promise runs; with only a link it is an underlined link with an arrow. The close button (Tab to it, then Enter or Space) collapses the strip, the page below slides up, and focus moves to the next control instead of getting lost; with persistKey the dismissal is remembered in local storage and the banner stays away, forever or for dismissDays days. Sticky banners stay pinned at the top of their scroller and fixed ones at the top of the viewport, below the notch, writing their height to --banner-offset so a topbar can move down. Banners that appear after the page loaded slide down from the top edge; with reduced motion they only fade. On a phone (below 640px) the banner turns compact: the description hides, the text keeps to two lines, the action becomes a chevron and the whole 44px row is the tap target, while the close button keeps its own 44px hit area. With announce on, screen readers hear the title politely when it appears, which suits offline notices.

npm: motion, lucide-react
Wingo UI dependencies: button, use-controllable-state, use-persisted-state, motion, tones, ui-config

Props:
- `title?: ReactNode` = "": The bold lead of the sentence. The playground shows a sample when it is empty.
- `description?: ReactNode` = "": The rest of the sentence, on the same line after a middot. Hidden in compact mode, so keep the title self-sufficient.
- `actionLabel?: string` = "": Shortcut for action.label: a small button at the end. The playground wires it to a fake 1.2s request.
- `action?: { label: ReactNode; onClick?: () => void | Promise<unknown>; href?: string; target?: string }`: The one action. A promise from onClick shows the loading state until it settles. With only href it renders as an underlined link with an arrow. In compact mode the whole row presses it.
- `children?: ReactNode`: Free content instead of (or after) the title and description: a countdown, a progress bar.
- `icon?: ReactNode | false`: The leading icon. Defaults per tone: neutral Megaphone, info Info, success CircleCheck, warning TriangleAlert, danger CircleAlert, brand Sparkles. false hides it.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color. Neutral solid is a black strip in light mode and a white one in dark mode.
- `color?: string` = "": Any CSS color. Replaces the tone; text on a solid strip turns black or white by lightness.
- `variant?: "solid" | "soft" | "outline"` = "solid": solid for app-wide news, soft for a tinted strip (warnings, trials), outline for a hairline strip inside cards and panels.
- `size?: "sm" | "md"` = "md": sm is at least 36px tall with 13px text, md 44px with 14px text.
- `defaultOpen?: boolean` = true: Starts visible. Use open and onOpenChange to control it; open wins over persistKey and nothing is stored then.
- `open?: boolean`: Controlled visibility. onOpenChange(false) fires on dismiss.
- `onOpenChange?: (open: boolean) => void`: Fires when the close button is pressed (also with persistKey).
- `onDismiss?: () => void`: Fires after the collapse animation finished.
- `dismissible?: boolean` = true: Shows the close button, with a 44px hit area on touch screens.
- `persistKey?: string` = "": Remembers the dismissal ({ at: ISO date }) in local storage under this key. Nothing renders until storage is read, so a dismissed banner never flashes.
- `dismissDays?: number` = 0: With persistKey: 0 keeps the banner dismissed forever, otherwise it returns after this many days.
- `position?: "static" | "sticky" | "fixed"` = "static": sticky pins it to the top of the nearest scroller, below var(--topbar-offset). fixed pins it to the viewport top with the safe area and writes its height to --banner-offset on <html> (0 while hidden). One fixed banner at a time; stack several as static banners in one fixed wrapper.
- `align?: "center" | "start"` = "center": Where the content row sits. Centered text stays centered even with a close button at the end.
- `contentWidth?: "full" | "page"` = "page": page caps the content row at max-w-6xl like a page; full uses the whole width (panels, cards).
- `compact?: "auto" | "always" | "never"` = "auto": auto goes compact below 640px: the description hides, the text keeps to two lines, the action becomes a chevron and the whole row is its tap target.
- `href?: string` = "": Makes the whole banner a link. The close button and the action stay separate.
- `announce?: boolean` = false: Reads the title in a polite live region when the banner appears after mount. For offline style notices.
- `safeArea?: boolean` = true: A fixed banner pads env(safe-area-inset-top), so it clears the notch.
- `labels?: Partial<{ region: string; dismiss: string }>`: The region's aria-label ("Announcement") and the close button's aria-label ("Dismiss"). DEFAULT_BANNER_LABELS has the English set.
- `classNames?: Partial<Record<"inner" | "body" | "icon" | "content" | "title" | "description" | "action" | "close", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the strip itself, merged last.

```tsx
import { Banner } from "@/components/ui/banner"

export function ReleaseBanner() {
  return (
    <Banner
      title="Version 3.2 is here"
      description="New invoicing reports and Excel export."
      action={{ label: "See what's new", href: "/whats-new" }}
      persistKey="banner-v32"
    />
  )
}
```

Docs: https://wingo-ui.com/components/banner (Markdown: https://wingo-ui.com/components/banner.md)

#### Cookie Consent (`cookie-consent`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add cookie-consent`

GDPR cookie consent: a bottom bar or card with Accept, Reject and Settings, per-category switches, and a gate for embeds.

The bar rises from the bottom edge once the page has painted, only for visitors who have not chosen yet. Accept all, Reject all and Settings are equal buttons (on a phone three full-width 48px buttons with Accept on top); any choice slides the bar away, saves the record for 180 days and is announced to screen readers. Settings opens a dialog on desktop and a full-height bottom sheet on phones: flip a switch per category (Strictly necessary is locked on), tap Show cookies for the list behind it, then Save choices or Accept all; closing it any other way discards the draft. Keyboard: Tab reaches the buttons and the policy link, Enter or Space activates, Escape closes the settings without saving. With blocking the page dims, focus starts on Reject all, Tab stays inside and Escape does nothing until a choice; afterwards focus returns to what had it before the bar. A footer link (CookieSettingsLink) reopens the settings from anywhere; raising version brings the bar back.

npm: motion, lucide-react
Wingo UI dependencies: use-consent, button, switch, dialog, collapsible, badge, use-media-query, use-controllable-state, motion, tones, ui-config

Props:
- `title?: ReactNode` = "": The heading. Empty uses labels.title ("We use cookies" by default).
- `description?: ReactNode` = "": The text under the heading. Empty uses labels.description; the policy link follows it.
- `policyHref?: string` = "": The cookie policy URL, shown as an underlined link after the description. Empty hides the link.
- `icon?: ReactNode | false`: A cookie in a 40px tinted tile by default; pass your own icon, or false to hide it.
- `categories?: ConsentCategoryConfig[]`: { id, label, description?, required?, cookies?: { name, provider?, duration?, purpose? }[] }[]. Display order; necessary (or any required) is locked on. Default DEFAULT_CONSENT_CATEGORY_CONFIG (English), or CONSENT_CATEGORY_CONFIG_RO.
- `labels?: Partial<CookieConsentLabels>`: Every string: region, title, description, policy, acceptAll, rejectAll, settings, settingsTitle, settingsDescription, save, alwaysOn, showCookies(count), hideCookies, cookieName, provider, duration, purpose, saved, gateTitle(category), gateDescription, gateAllow, close. English by default; pass COOKIE_CONSENT_LABELS_RO for the ready Romanian copy.
- `variant?: "bar" | "card"` = "bar": bar: a full-width glass bar at the bottom (a card-like sheet on phones). card: a 400px floating card.
- `position?: "bottom" | "bottom-start" | "bottom-end"` = "bottom": Where the card floats (centered, start or end corner); for the bar, where its content column sits on wide screens. Unset, the bar uses bottom and the card bottom-start.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Accept button, the switches and the icon tile. Reject keeps the neutral soft look at the same size, so both choices weigh the same.
- `color?: string` = "": Any CSS color; replaces the tone on the Accept button, the switches and the icon tile.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the buttons, scaled per size like the button's (the 48px phone buttons take the lg step).
- `showReject?: boolean` = true: Reject all next to Accept all, as easy as accepting. Keep it on in the EU.
- `showSettings?: boolean` = true: The Settings button that opens the per-category panel.
- `defaultOpen?: boolean` = false: Shows the bar on mount even when the visitor already chose. Unset, the bar shows exactly while the visitor has not decided. Controlled with open / onOpenChange.
- `open?: boolean`: Controls the bar's visibility (previews, a consent page). onOpenChange(false) fires when a choice hides it.
- `onOpenChange?: (open: boolean) => void`: Called when a choice hides the bar.
- `defaultSettingsOpen?: boolean` = false: Opens the settings panel on mount. Controlled with settingsOpen / onSettingsOpenChange; openConsentSettings() opens it from anywhere.
- `settingsOpen?: boolean`: Controls the settings panel.
- `onSettingsOpenChange?: (open: boolean) => void`: Called when the settings panel opens or closes.
- `blocking?: boolean` = false: Dims the page and traps focus until a choice (role dialog, focus on Reject all, Escape does nothing). Non-blocking is the default and the usual advice; use this only where legally advised.
- `delay?: number` = 0: Milliseconds after hydration before the bar shows, so the page paints first. The bar is fixed, so it never shifts the layout.
- `storageKey?: string` = "ui-consent": Cookie / storage key of the record, passed to useConsent. Every consent hook, gate and link with the same key shares it.
- `version?: number` = 1: The policy version. Bump it when the policy or the categories change: older choices count as undecided and the bar returns.
- `storage?: "cookie" | "local" | "session"` = "cookie": Where the record lives. A cookie can be read on the server too. When storage is blocked the choice lives in memory for the session.
- `maxAgeDays?: number` = 180: How long a cookie choice is kept before the visitor is asked again.
- `responsive?: boolean` = true: Settings as a full-height bottom sheet below 768px (a dialog otherwise).
- `portal?: boolean` = true: Renders the region as the first child of document.body (or container), so keyboard and screen reader users reach it before the page. false renders it in place with absolute instead of fixed (previews, a phone frame, docs).
- `container?: HTMLElement | null`: The portal target instead of document.body. A container with contain: layout or a transform keeps the fixed bar inside it.
- `onDecide?: (record: ConsentRecord) => void`: After every decision (accept, reject, save): { version, choices, decidedAt, method }. Load scripts here, or use onConsentChange from use-consent.
- `classNames?: Partial<Record<"overlay" | "inner" | "icon" | "content" | "title" | "description" | "policy" | "actions" | "button" | "settings" | "category" | "cookies" | "cookie", string>>`: Extra classes for the inner parts; settings is the dialog / sheet content (the data-slot cookie-consent-settings marks the category list inside it).
- `className?: string`: Extra classes for the bar or card itself, merged last.

Parts:
- `ConsentGate` (component): Renders children only when the category is allowed, nothing during hydration, and otherwise a placeholder tile with labels.gateTitle and an Allow and load button that turns that category on. Props: { category; children; fallback?; storageKey?; version?; storage?; maxAgeDays?; categories?; icon?; tone?; color?; radius?; labels? }.
- `CookieSettingsLink` (component): A link-styled button for the footer that calls openConsentSettings(storageKey). Children default to labels.settingsTitle. Props: ButtonProps & { storageKey?; labels? }.
- `COOKIE_CONSENT_LABELS_RO` (constant): Ready Romanian copy. Type: CookieConsentLabels.
- `CONSENT_CATEGORY_CONFIG_RO` (constant): Ready Romanian categories (necessary, preferences, analytics, marketing). Type: ConsentCategoryConfig[].
- `DEFAULT_COOKIE_CONSENT_LABELS` (constant): The English default copy, to extend. Type: CookieConsentLabels.
- `DEFAULT_CONSENT_CATEGORY_CONFIG` (constant): The English default categories, to extend or reorder. Type: ConsentCategoryConfig[].

```tsx
import type { ReactNode } from "react"
import { ConsentGate, CookieConsent, CookieSettingsLink } from "@/components/ui/cookie-consent"

export function SiteShell({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <ConsentGate category="marketing" className="aspect-video">
        <iframe title="Acme CRM overview" src="https://www.youtube-nocookie.com/embed/abc123" className="aspect-video w-full rounded-2xl" />
      </ConsentGate>
      <footer>
        <CookieSettingsLink />
      </footer>
      <CookieConsent
        policyHref="/cookie-policy"
        delay={500}
        onDecide={(record) => {
          if (record.choices.analytics) console.log("load analytics")
        }}
      />
    </>
  )
}
```

Docs: https://wingo-ui.com/components/cookie-consent (Markdown: https://wingo-ui.com/components/cookie-consent.md)

#### Emoji Reaction (`emoji-reaction`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add emoji-reaction`

A tapback-style reaction button that opens a bar of Apple emoji and sends copies of your pick floating up out of it.

Click the button to pop the emoji bar open, or press and drag straight onto an emoji to pick it in one gesture. Hover an emoji to lift it. Pick one and 5 copies stream up off it, drifting apart, shrinking, and blurring out of focus as they climb. Hold the emoji down to keep them coming. The bar flips below the button when there is no room above, and the arrow keys, Home and End move along it. While it is open the button turns into a cross; click that, click outside, or press Escape to close. The button then shows your last pick.

npm: motion, react-apple-emojis, lucide-react, @radix-ui/react-slot
Wingo UI dependencies: ui-config

Props:
- `size?: "sm" | "md" | "lg"` = "md": Scale of the button, the bar, and the emoji that fly up. The trigger is 32px (sm), 40px (md) or 48px (lg).
- `align?: "left" | "center" | "right"` = "center": Which edge of the bar lines up with the trigger. It still shifts inward when it would run off screen.
- `asChild?: boolean` = false: Uses your own child as the trigger instead of the built-in button, so the bar can hang off a message, card, or image.
- `surfaceColor?: string` = "auto": Fill of the trigger, the bar and its tail, any CSS color. Auto is #F4F4F9 on light pages and #262626 on dark ones.
- `burstCount?: number` = 5: How many copies of the emoji fly up per reaction. Holding an emoji repeats the burst, and at most 60 copies are in the air at once.
- `rise?: number` = 450: How far the copies climb before they fade out, in pixels. Each copy varies it a little.
- `holdInterval?: number` = 550: While an emoji is held down, a new burst fires this often, in milliseconds.
- `defaultOpen?: boolean` = false: Starts with the bar open, for a first-run hint or a screenshot. It does not take focus until the user opens it themselves.
- `openLabel?: string` = "Add a reaction": Accessible name of the trigger before any reaction.
- `closeLabel?: string` = "Close reactions": Accessible name of the trigger while the bar is open.
- `reactedLabel?: string` = "Reacted {emoji}": Accessible name of the trigger after a reaction; {emoji} fills in its name.
- `menuLabel?: string` = "Pick a reaction": Accessible name of the emoji bar.
- `emojiBaseUrl?: string` = "https://em-content.zobj.net/source/apple/419/": Where the built-in five faces load from; point it at your own mirror of the same file names. Ignored when emojiData is passed.
- `emojis?: string[]` = "[\"smiling-face-with-hearts\", \"star-struck\", \"confused-face\", \"pleading-face\", \"grinning-face-with-smiling-eyes\"]": Apple emoji names shown in the bar, hyphenated as on Emojipedia. Anything beyond the five defaults needs emojiData too.
- `emojiData?: EmojiData` = "built-in Apple emoji set (the five defaults)": Emoji name to image map passed to EmojiProvider. Defaults to the five bundled faces served from the emojipedia CDN; pass react-apple-emojis/src/data.json for the full set.
- `onReact?: (name: string) => void`: Called with the emoji name every time one is picked, including each repeat while it is held down.
- `children?: ReactNode`: The custom trigger when asChild is set. Ignored otherwise.
- `className?: string`: Extra classes merged onto the root element; other div props are spread onto it too.

```tsx
import { EmojiReaction } from "@/components/ui/emoji-reaction"

export function Demo() {
  return <EmojiReaction onReact={(name) => console.log(name)} />
}

// or hang the bar off your own element:
// <EmojiReaction asChild>
//   <button className="rounded-2xl bg-card p-4">Nice work</button>
// </EmojiReaction>
```

Docs: https://wingo-ui.com/components/emoji-reaction (Markdown: https://wingo-ui.com/components/emoji-reaction.md)

#### Empty State (`empty-state`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add empty-state`

What a list, table, search or page shows when there is nothing to show: an icon tile, a title, a description and actions.

It appears with the tile scaling up and the text and buttons rising in one after another; under reduced motion it only fades. Pick a preset to swap icon, tone and copy at once. Press the retry button on the error preset and it spins until the returned promise settles. Tab moves through the actions in reading order, Enter or Space presses them. With live on, a screen reader announces the title and description once when the state appears. On a phone, or anywhere narrower than 400px, two or more actions stack full width with the primary one on top, and lg pages drop to the md spacing below 640px.

npm: @radix-ui/react-slot, motion, lucide-react
Wingo UI dependencies: button, motion, tones, ui-config

Props:
- `preset?: "empty" | "no-results" | "error" | "first-run" | "no-permission" | "offline"` = "empty": Picks the default icon, tone and copy for the usual reasons: empty (Inbox, neutral), no-results (SearchX, neutral), error (CircleAlert, danger), first-run (Sparkles, brand, with a plus badge), no-permission (Lock, warning), offline (WifiOff, neutral). Every piece stays overridable.
- `title?: ReactNode` = "": The heading. Leave empty for the preset's; null hides it.
- `description?: ReactNode` = "": One or two sentences under the title; wraps at 36ch (44ch at lg). Leave empty for the preset's; null hides it.
- `icon?: ReactNode`: The glyph inside the tile, sized by the empty state. Defaults to the preset's icon; null hides the tile.
- `illustration?: ReactNode`: Replaces the tile with an image or an svg, at most 112 / 160 / 192px tall by size. Decorative (aria-hidden).
- `badge?: ReactNode`: A small round badge on the tile's corner in the tone's fill. first-run shows a plus; null hides it.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "": The tile tint. Empty uses the preset's tone. neutral is a quiet gray tile; the others use the tone's soft fill and text.
- `color?: string` = "": Any CSS color for the tile (and the badge); replaces the tone.
- `size?: "sm" | "md" | "lg"` = "md": sm inside a table, list or popover (40px tile, 14px title, 24px padding); md in a panel (48px tile, 15px title, 40px padding); lg for a whole page (64px tile, 18px title, 64px padding, 40px below 640px).
- `variant?: "plain" | "dashed" | "surface"` = "plain": plain sits on whatever is behind it; dashed draws a dashed frame (first-run areas, drop zones); surface is a raised panel.
- `align?: "center" | "start"` = "center": start aligns text and actions to the start edge, for cards and sidebars.
- `actions?: ReactNode`: Buttons. Put the primary action last in the DOM: it sits at the end of the row and on top when the row stacks.
- `onRetry?: () => (void | Promise<unknown>)`: Adds an outline retry button after the actions (meant for the error and offline presets). A returned promise keeps it loading until it settles.
- `retryLabel?: string` = "Try again": The retry button's label.
- `titleAs?: "h2" | "h3" | "h4" | "p"` = "h3": The title's element, to fit the page's heading outline.
- `live?: boolean` = false: role="status" with a polite live region, so a screen reader announces the state when it appears. Use it for results that change, like no-results under a search.
- `animated?: boolean` = true: Tile, text and actions rise in with a short stagger when the state mounts. Server-rendered markup shows the final state; reduced motion fades only. The demo's replay button remounts it.
- `presets?: Partial<Record<EmptyStatePreset, Partial<EmptyStatePresetConfig>>>`: Overrides merged over DEFAULT_EMPTY_STATE_PRESETS ({ icon, tone, title, description, badge } per preset). Translate once for the whole app with <UIProvider defaults={{ "empty-state": { presets } }}>.
- `children?: ReactNode`: Extra content between the description and the actions: suggestions, a search field, a list of shortcuts.
- `classNames?: Partial<Record<"media" | "icon" | "badge" | "title" | "description" | "content" | "actions", string>>`: Extra classes for the inner parts: the tile or illustration, the glyph, the corner badge, the title, the description, the children wrapper, the actions row.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `EmptyStateIcon` (component): The decorative icon tile on its own (data-slot empty-state-media). Inside an EmptyState it follows its size and entrance. Props: { tone?, color?, badge?, size?, classNames?: { icon, badge } } & div props.
- `EmptyStateTitle` (component): The title part, sized by the surrounding EmptyState. Props: { as?: "h2" | "h3" | "h4" | "p" } & heading props.
- `EmptyStateDescription` (component): The description part, sized by the surrounding EmptyState. Takes p props.
- `EmptyStateActions` (component): The actions row (wraps, stacks full width below 400px). asChild renders your own element as the row. Props: { asChild?: boolean } & div props.
- `DEFAULT_EMPTY_STATE_PRESETS` (constant): The English preset copy, icons and tones, to spread and translate. Type: Record<EmptyStatePreset, EmptyStatePresetConfig>.

```tsx
import { FileUp, UserPlus } from "lucide-react"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"

export function ClientsEmpty({ onReload }: { onReload: () => Promise<void> }) {
  return (
    <div className="flex flex-col gap-4">
      <EmptyState
        variant="surface"
        title="No clients yet"
        description="Add your first client or import the list from a CSV to get started."
        actions={
          <>
            <Button variant="outline" leftIcon={<FileUp />}>Import CSV</Button>
            <Button leftIcon={<UserPlus />}>Add client</Button>
          </>
        }
      />
      <EmptyState
        preset="error"
        size="sm"
        title="We could not load the invoices"
        description="Check your connection and try again."
        onRetry={onReload}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/empty-state (Markdown: https://wingo-ui.com/components/empty-state.md)

#### Notification Bell (`notification-bell`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add notification-bell`

An iOS-style notification bell with an unread count badge.

Press plus to add a notification, minus to clear one. The bell swings when one lands, its clapper lagging behind, and the count rolls to the new number digit by digit. Add a few fast and it swings harder. Past the max the badge reads 99+, and it shrinks away at zero.

npm: motion, @radix-ui/react-slot
Wingo UI dependencies: motion, ui-config

Props:
- `count?: number` = 0: Unread total on the badge. The badge is hidden at 0, and fractional or negative values are floored to it.
- `max?: number` = 99: Highest number shown. Anything above it displays as the max followed by a plus.
- `variant?: "count" | "dot"` = "count": Whether the badge shows the number or a plain dot. The dot appears and leaves on the same counts.
- `size?: number` = 48: Diameter of the button in pixels. The bell, badge, and digits are all fractions of it. Below 44px the button keeps a 44px hit area on touch screens.
- `color?: "red" | "orange" | "green" | "blue" | "violet" | string` = "red": Badge color: a name from the Apple system palette (each swaps to its dark mode variant with the theme) or any CSS color.
- `badgeTextColor?: string` = "#ffffff": Any CSS color for the digits in the badge.
- `surfaceColor?: string` = "": Any CSS color for the round button. Empty uses #F4F4F9 light, #262626 dark.
- `iconColor?: string` = "": Any CSS color for the bell glyph. Empty uses #868593 light, #9B9AA7 dark.
- `ringStrength?: number` = 1: How hard the bell swings when the count goes up: 0 keeps it still, 1 is the original swing, 2 twice the kick.
- `label?: string` = "Notifications": What screen readers hear with no unread notifications; also the button's name.
- `unreadLabel?: string` = "Notifications, {count} unread": What screen readers hear with unread notifications; {count} fills in, e.g. "{count} unread notifications".
- `asChild?: boolean` = false: Uses your own child as the trigger instead of the built-in button, so the badge can sit on an avatar or a nav item. Your element should be round for the badge to line up, and the bell swing only runs on the built-in button.
- `children?: ReactNode`: The custom trigger when asChild is set. Ignored otherwise.
- `className?: string`: Extra classes merged onto the root element; other button props are spread onto it too. Sizing is set inline from the size prop, so a width or height class here will not take effect.

Parts:
- `NotificationBellColor` (type): The named badge colors: "red" | "orange" | "green" | "blue" | "violet". color also takes any CSS color.

```tsx
import { NotificationBell } from "@/components/ui/notification-bell"

export function Demo() {
  return <NotificationBell count={8} />
}

// or wrap it in your own menu trigger (shadcn dropdown-menu):
// <DropdownMenuTrigger asChild>
//   <NotificationBell count={unread} />
// </DropdownMenuTrigger>
```

Docs: https://wingo-ui.com/components/notification-bell (Markdown: https://wingo-ui.com/components/notification-bell.md)

#### Notification Center (`notification-center`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add notification-center`

The app's notification inbox: a bell with the unread count and a panel with filter tabs, day groups, inline actions and swipe to dismiss.

Click the bell (or press its shortcut) and the panel grows out of it with All / Unread / Mentions tabs, the Unread tab counting live. Notifications sit under sticky day labels (Today, Yesterday, weekdays, then dates) with relative times that refresh every minute. Click a row to open it: it turns read, follows its link and the panel closes. Inline buttons (accept an invite, retry a payment) spin while their promise runs. The ⋯ menu on each row (on hover or focus with a mouse, always visible on touch) marks it read or unread or dismisses it, and the row collapses out. "Mark all as read" clears every dot at once and the red count on the bell scales away; when a new notification arrives the bell swings and the row slides in, and screen readers hear it through a polite live region. Keyboard: Tab into the panel, Down or Home jumps to the first row, Up / Down move between rows, Home / End jump, Enter opens, Escape closes and focus returns to the bell. The last row loads more by itself when it scrolls into view. On a phone the panel is a full-height bottom sheet: swipe a row left to dismiss it (a red Dismiss layer follows your finger) or right to toggle read, with a haptic tick where supported; drag the handle down to close. NotificationList (same file) is the panel without the bell, for a full inbox page or a sidebar panel.

npm: @radix-ui/react-popover, lucide-react, motion
Wingo UI dependencies: avatar, badge, button, drawer, dropdown-menu, skeleton, spinner, tabs, use-controllable-state, use-locale, use-media-query, use-shortcut, date-utils, motion, navigation, tones, ui-config

Props:
- `notifications?: NotificationItem[]` = "[]": Newest first. { id, title: ReactNode, body?, createdAt: Date | string | number, read?, type?, avatar?, name?, icon?, tone?, href?, actions?: NotificationAction[] }. NotificationAction is { label, onSelect: () => void | Promise<unknown>, variant?: "solid" | "soft" | "ghost", tone? }. String dates are parsed; invalid ones go last without a time. type "mention" feeds the Mentions tab, and @Name inside string titles and bodies is highlighted.
- `onRead?: (ids: string[]) => void`: Rows turned read: from the row menu, a swipe right, opening a row or Mark all (when onReadAll is not set). The panel updates at once and keeps the change until your data agrees.
- `onUnread?: (ids: string[]) => void`: Rows turned unread from the row menu or a swipe right on a read row.
- `onReadAll?: () => void`: "Mark all as read" in the header (shown while anything is unread). Without it onRead gets every unread id.
- `onDismiss?: (id: string) => void`: A row was dismissed (row menu or swipe left). Runs after the row has collapsed out, so remove it from your data here.
- `onSelect?: (item: NotificationItem) => void`: A row was opened: it turns read, navigates to its href through NavLink and the panel closes.
- `filters?: NotificationFilter[]`: The tabs, All / Unread / Mentions by default: { value, label, filter?: (item) => boolean, badge?, emptyTitle?, emptyText? }. A tab whose value is "unread" shows the unread count; each tab can have its own empty state. Fewer than two filters hide the tabs.
- `filter?: string`: The active tab, controlled. Pair it with onFilterChange.
- `defaultFilter?: string` = "all": The tab it starts on while uncontrolled (a filter value).
- `onFilterChange?: (filter: string) => void`: Fires when another tab is picked.
- `title?: ReactNode` = "Notifications": The panel title; it also names the dialog.
- `markAllLabel?: string` = "Mark all as read": The header button that clears every unread dot.
- `emptyTitle?: string` = "You're all caught up": The empty state of a tab with nothing in it. A filter's own emptyTitle wins.
- `emptyText?: string` = "": A second, muted line under the empty title.
- `emptyIcon?: ReactNode`: Replaces the BellOff icon of the empty state.
- `groupByDay?: boolean` = true: Sticky day labels: Today, Yesterday, weekday names this week, then dates in the locale. Off, rows show the date with the time.
- `timeFormat?: "relative" | "time"` = "relative": "5 min ago" through Intl.RelativeTimeFormat, refreshed every minute while open, or the clock time ("14:20"). Under an older day label rows show the clock time, so "Yesterday" is never said twice. Relative times are computed after mount: the server and hydration render print the clock time, so there is no mismatch.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The unread dots and the tab indicator.
- `badgeTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "danger": The count badge on the bell. Red by default on purpose: people read a red count as unread.
- `max?: number` = 99: Counts above it read "99+".
- `width?: number` = 400: The desktop panel width in px (never wider than the screen minus 24px).
- `badgeRingColor?: string` = "var(--bar-bg, var(--background))": The 2px ring that cuts the badge out of the bell: the surface the bell sits on.
- `count?: number` = "": Overrides the badge number (default: the unread count). 0 hides the badge. The playground's empty control means left out.
- `loading?: boolean` = false: Skeleton rows while the list is empty, a spinner row after the last one otherwise.
- `hasMore?: boolean` = false: Shows the "Load more" row at the end, which also loads by itself when it scrolls into view.
- `onLoadMore?: () => (void | Promise<unknown>)`: Loads the next page. A returned promise keeps a spinner in the row until it settles.
- `defaultOpen?: boolean` = false: Starts open (uncontrolled).
- `open?: boolean`: Controlled open state. Pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Fires when the panel opens or closes.
- `ringOnNew?: boolean` = true: The bell swings from its top when the unread count goes up (never under reduced motion).
- `swipeActions?: boolean` = true: Swipe a row left to dismiss it, right to toggle read. Follows the finger and commits past a quarter of the row or on a flick.
- `responsive?: boolean` = true: Below 768px the panel is a full-height bottom sheet with full-width tabs.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Where the desktop panel opens; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "end": The panel's alignment against the bell. end suits a bell at the right of a top bar.
- `shortcut?: string` = "": A key combo in mod+k notation that opens and closes the panel from anywhere (none by default).
- `locale?: string` = "": Dates, weekdays and relative times. Empty uses the LocaleProvider or the browser.
- `settingsHref?: string` = "": Adds a gear link in the header (a NavLink), e.g. to notification settings.
- `onSettings?: () => void`: Adds a gear button in the header, or runs before the settingsHref link.
- `trigger?: ReactNode`: A custom trigger instead of the bell, rendered with asChild (one element that takes a ref).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for rows with href and the settings link; default from LinkProvider.
- `container?: HTMLElement | null`: Portal target for the panel and the sheet (default document.body).
- `labels?: { trigger?: (unread) => string; markRead?; markUnread?; dismiss?; more?; loadMore?; loading?; settings?; filters?; unread?; earlier?; newNotification?: (title) => string }`: Every other string, English by default: the bell's label ("Notifications, 3 unread"), the row menu, the swipe layers, load more, the live announcement for new notifications.
- `classNames?: Partial<Record<"trigger" | "badge" | "content" | "header" | "title" | "markAll" | "settings" | "tabs" | "list" | "group" | "groupLabel" | "item" | "media" | "body" | "time" | "actions" | "empty" | "footer", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the bell button. Other props (aria-*, data-*, handlers) go to the bell too.

```tsx
import { CreditCard } from "lucide-react"
import { NotificationCenter, NotificationList, type NotificationItem } from "@/components/ui/notification-center"

const notifications: NotificationItem[] = [
  {
    id: "n1",
    type: "mention",
    name: "Sophia Lee",
    avatar: "/demo/ioana-dumitrescu.jpg",
    title: "Sophia Lee mentioned you in “Acme Corp quote”",
    body: "@Emma Carter can you check the discount before we send it?",
    createdAt: "2026-09-23T10:42:00",
    href: "/quotes/Q-2026-118",
  },
  {
    id: "n2",
    icon: <CreditCard />,
    tone: "danger",
    title: "Your Pro plan payment failed",
    body: "The card ending in 4821 was declined.",
    createdAt: "2026-09-23T08:15:00",
    actions: [{ label: "Retry", onSelect: () => fetch("/api/billing/retry", { method: "POST" }) }],
  },
]

export function TopbarNotifications() {
  return (
    <NotificationCenter
      notifications={notifications}
      onRead={(ids) => console.log("read", ids)}
      onDismiss={(id) => console.log("dismiss", id)}
    />
  )
}

// the panel without the bell (full inbox page, sidebar panel): same content props, a header when title is set.
// it paints on var(--background); on a raised panel set [--nc-surface:var(--surface)] in className
export function InboxPage() {
  return <NotificationList title="Notifications" notifications={notifications} className="rounded-3xl border border-border" />
}
```

Docs: https://wingo-ui.com/components/notification-center (Markdown: https://wingo-ui.com/components/notification-center.md)

#### Progress (`progress`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add progress`

How far something has come: a bar, a bar in steps or a ring, determinate or indeterminate, with a label, value, tones and thresholds.

It is read, not operated: it never takes focus. Every value change glides on a spring from where the bar was, with no re-render per frame; the first paint already shows the final value. Without a value the bar slides endlessly (the ring spins), and a value arriving later glides on from there. With thresholds a quota bar turns amber, then red, as it fills. Screen readers hear a progressbar named by the label, described by the description, with the value as a percent. Under reduced motion values jump, stripes stop and the indeterminate bar pulses in place. In the playground, press Simulate to run an import from 0 to 100% in uneven steps. The same markup works on a phone; the header wraps under 240px. ProgressRing is the bare ring for other components (a stat card, an avatar, a file row): the same value props, a size that also takes a px number, a thickness, children in the center (the centered text shrinks to fit), classNames ring and content, and its own global defaults under progress-ring. Pass it an aria-label.

npm: @radix-ui/react-progress, motion
Wingo UI dependencies: use-locale, motion, number-format, tones, ui-config

Props:
- `value?: number | null` = 64: The current value, from 0 to max. Omit it (or pass null, NaN) for the indeterminate state: a sliding bar or a spinning arc. Values outside 0..max are clamped for drawing. The playground starts at a sample 64; the component's default is null.
- `max?: number` = 100: The value that means done. 0 or less renders the indeterminate state.
- `variant?: "linear" | "segmented" | "ring"` = "linear": linear: one bar. segmented: equal steps (onboarding, password strength, stories); a fractional value fills a segment partly. ring: a circle for KPIs and compact rows.
- `segments?: number` = 5: Segmented only: how many equal steps. 2,5 of 5 shows two full segments and one half.
- `size?: "xs" | "sm" | "md" | "lg"` = "md": Linear track 2 / 4 / 6 / 8px (xs is the hairline for a refreshing list); ring 24 / 32 / 48 / 64px with a 3 / 3 / 4 / 6px stroke. The xs ring shows its value beside it.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill color. The track stays a neutral tint. A finished upload does not turn green on its own: pass success when it should.
- `color?: string` = "": Any CSS color for the fill; replaces the tone. Empty uses the tone.
- `radius?: "none" | "sm" | "full"` = "full": Ends of the linear and segmented bars: square, 2px or a pill.
- `label?: ReactNode` = "": Above the bar, or beside the ring with labelPosition side. Names the progressbar for screen readers (else pass aria-label).
- `description?: ReactNode` = "": Under the bar in small muted text, e.g. "2.4 MB of 12 MB". Linked with aria-describedby.
- `showValue?: boolean` = false: Shows the formatted value at the end of the header row (linear) or in the center of the ring.
- `valueFormat?: "percent" | "fraction" | "value"` = "percent": How the value reads: "64%", "32 / 50" or "32", in the locale ("64 %" in de-DE).
- `labelPosition?: "top" | "side"` = "top": Ring only: top stacks label, ring and description; side puts the text to the right of the ring (KPI rows).
- `striped?: boolean` = false: Linear only: moving diagonal stripes on the fill while it is below max. They stop under reduced motion.
- `animated?: boolean` = true: Value changes glide on a spring. Off, the bar jumps straight to the new value.
- `locale?: string` = "": Intl locale for the value. Empty uses the UIProvider locale, then the page language.
- `thresholds?: { warning?: number; danger?: number }`: Quotas: at or above warning % the fill turns warning, at danger % danger. Compares percentages, not raw values. Wins over tone and color.
- `buffer?: number` = 0: Linear only: a lighter second bar behind the fill, in the same units as value (media buffering, uploaded vs processed). Glides on the same spring. Omitted (0 in the playground) draws none.
- `thickness?: number` = 0: Ring only: the stroke width in px. 0 uses 3 / 3 / 4 / 6px by size.
- `formatValue?: (value: number, max: number) => ReactNode`: Replaces valueFormat, e.g. "7.2 GB of 10 GB".
- `getValueLabel?: (value: number, max: number) => string`: The aria-valuetext. Defaults to the percent in the locale.
- `children?: ReactNode`: Ring only: replaces the centered value (an icon, a figure in your own style).
- `classNames?: Partial<Record<"header" | "label" | "value" | "track" | "indicator" | "segment" | "ring" | "description", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last. Other props (aria-label, aria-labelledby, aria-describedby) reach the progressbar.

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

export function ClientImport({ done, total }: { done: number; total: number }) {
  return (
    <div className="flex flex-col gap-4">
      <Progress
        label="Importing clients"
        description={`${done} of ${total} rows`}
        value={done}
        max={total}
        showValue
      />
      <Progress
        label="Storage"
        value={7.2}
        max={10}
        thresholds={{ warning: 80, danger: 95 }}
        showValue
        formatValue={(value, max) => `${value} GB of ${max} GB`}
      />
      <ProgressRing value={68} tone="brand" showValue aria-label="Monthly goal" />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/progress (Markdown: https://wingo-ui.com/components/progress.md)

#### Route Progress (`route-progress`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add route-progress`

The thin bar at the very top of the app while a page loads, started by in-app links and by hand for any async work.

Click a link inside the LinkProvider and the bar slides in from the start edge after a short delay, creeps toward 90% while the next page loads, then fills to the end, holds for a beat and fades out once the path changes. Navigations faster than the delay never show it, a click on the page you are already on does nothing, and browser back / forward shows nothing either. Call routeProgress.start() and routeProgress.done() from anywhere (saving, exporting) to drive it by hand, or pass loading. It is never focusable and has nothing to tap; on a phone it sits under the status bar through the safe-area inset. Screen readers get a labelled progressbar with its value while it is visible and nothing while idle. Under reduced motion the bar jumps between values without springs or glow.

npm: motion
Wingo UI dependencies: navigation, motion, tones, ui-config

Props:
- `auto?: boolean` = true: Starts on in-app navigations (a NavLink click, useNavigate) and finishes when the current path changes. A click on the current page, a hash or a query change does not count.
- `loading?: boolean`: Controlled mode: true starts, false finishes. It overrides auto. Leave it undefined to use auto and the imperative routeProgress API.
- `currentPath?: string`: The path whose change finishes a navigation. Defaults to the LinkProvider's currentPath.
- `delay?: number` = 120: Milliseconds before the bar appears. Anything that finishes sooner never shows it, so fast pages do not flash.
- `minimum?: number` = 0.08: Where the bar starts, as a fraction of the width.
- `trickle?: boolean` = true: Creeps toward 90% while waiting; each step covers 5 to 15% of the distance left.
- `trickleSpeed?: number` = 250: Milliseconds between trickle steps.
- `timeout?: number` = 10000: Milliseconds after which a navigation that never finished completes anyway (a cancelled route, a redirect back to the same page). 0 turns the safety net off.
- `size?: "sm" | "md" | "lg"` = "md": Bar height: 2 / 3 / 4px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The bar's color from the design tokens. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color. Replaces the tone for the bar, the glow and the spinner. Leave empty to use the tone.
- `glow?: boolean` = true: A soft glow on the last 96px of the bar, at 60% opacity. Dropped under reduced motion.
- `spinner?: boolean` = false: A 14px ring spinner in a small floating chip under the top end of the bar while loading.
- `position?: "fixed" | "absolute"` = "fixed": fixed pins it to the top of the viewport; absolute pins it to the nearest positioned ancestor (a card, a panel, a demo frame).
- `offset?: number` = 0: Pixels from the top, e.g. 56 to sit under a fixed header.
- `safeArea?: boolean` = true: Adds env(safe-area-inset-top) to the offset, so an installed web app draws the bar under the status bar. It is 0 in desktop browsers.
- `label?: string` = "Loading page": The progressbar's aria-label.
- `store?: RouteProgressStore` = "routeProgress": The store this bar shows. Defaults to the shared routeProgress; pass createRouteProgress() when two bars must not share state.
- `classNames?: Partial<Record<"track" | "bar" | "glow" | "spinner", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:var(--info)].

Parts:
- `routeProgress` (constant): The shared imperative store. start() shows the bar after the delay (ignored while running), done() finishes it (silently while still pending), set() jumps to a fraction, inc() moves it forward, reset() hides it at once. Type: { start(); done(); set(fraction: number); inc(amount?: number); reset() }.
- `useRouteProgress` (hook): The store's state and value, for a custom progress UI (a spinner in the tab title, a disabled form). Signature: (store?: RouteProgressStore) => { state: "idle" | "pending" | "loading" | "done"; value: number }.
- `createRouteProgress` (function): Makes an independent store with the same API as routeProgress. Signature: (config?: Partial<RouteProgressConfig>) => RouteProgressStore.

```tsx
"use client"

import type { ReactNode } from "react"
import Link from "next/link"
import { usePathname, useRouter } from "next/navigation"
import { Button } from "@/components/ui/button"
import { RouteProgress, routeProgress } from "@/components/ui/route-progress"
import { LinkProvider } from "@/lib/navigation"

// once, in the root layout's client providers: every NavLink click starts the bar, the new path finishes it
export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter()
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      <RouteProgress />
      {children}
    </LinkProvider>
  )
}

// by hand, for any async work
export function SaveInvoice({ save }: { save: () => Promise<void> }) {
  return (
    <Button
      onClick={async () => {
        routeProgress.start()
        try {
          await save()
        } finally {
          routeProgress.done()
        }
      }}
    >
      Save invoice
    </Button>
  )
}
```

Docs: https://wingo-ui.com/components/route-progress (Markdown: https://wingo-ui.com/components/route-progress.md)

#### Skeleton (`skeleton`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add skeleton`

Placeholders shaped like the content on its way: a shimmering block, text lines, and presets for cards, lists, tables and profiles.

Nothing to press: blocks shimmer or pulse while data loads, and the real content fades in the moment loading turns off. Tap Reload in the playground to replay a 1.4s request and watch the cards swap without the layout moving. Wrap real content in a Skeleton and the block takes its exact size and corners; the wrapped content is inert while loading, so Tab skips it until it arrives. On a phone the table preset turns into one card per row. Screen readers hear each preset's label once, never every block, and reduced motion keeps every block still.

npm: motion
Wingo UI dependencies: ui-config, motion

Props:
- `shape?: "rect" | "circle" | "line"` = "rect": rect: a block with radius (full width, 96px tall until you size it). circle: a round block, 40px unless width says otherwise. line: a 14px text line.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of a rect: 0 / 6 / 10 / 16px or a pill. Circles and lines are always round. A rect wrapping real content copies the corners of what it wraps when that has any (a button, a rounded photo).
- `animation?: "shimmer" | "pulse" | "none"` = "shimmer": shimmer: a soft highlight sweeps across. pulse: the block fades in and out. none: static. Under reduced motion every block stays still.
- `color?: string` = "": Any CSS color for the block. Leave empty for the 5% foreground tint, which works on every surface in both themes. Set it on colored surfaces, e.g. a white tint on a brand banner.
- `highlight?: string` = "": Any CSS color for the shimmer band. Leave empty for a 7% foreground tint.
- `speed?: number` = 1: Playback multiplier for shimmer and pulse: 0.5 is half speed, 2 twice as fast. One shimmer sweep takes 1.6s at 1, a pulse 2s. Clamped to 0.25..4.
- `loading?: boolean` = true: false renders the children instead, fading them in. Content that is already there on the first render (the server's too) shows without a fade.
- `children?: ReactNode`: The real content. While loading it sits invisible and inert inside the block, so the block takes its exact size (a rect its corners too, a line draws a bar 70% as tall as the text box, like the presets); once loaded it shows in a wrapper that fades in. className lands on both, so pass layout classes like w-full or flex-1 once.
- `width?: number | string`: px as a number (or a number-like string such as "120"), any other CSS length as a string. rect and line fill the row by default; a circle takes its size from width, or from height when width is missing.
- `height?: number | string`: px as a number (or a number-like string), any other CSS length as a string. A rect is 96px tall by default, or follows an aspect-* class. Ignored by circles, which stay round.
- `className?: string`: Extra classes for the block, merged last: size it with h-4 w-32, size-12, aspect-video.

Parts:
- `SkeletonText` (component): A column of lines: 3 by default, the last at 60%. size sm / md / lg makes 10 / 14 / 18px lines (text-xs, text-sm, text-[15px]). lines={0} renders nothing. Props: { lines?: number; lastLineWidth?: number | string; size?: "sm" | "md" | "lg"; animation; speed; color; highlight; classNames?: { line } }.
- `SkeletonCard` (component): A media card: a 16:10 block on top (media, true; mediaAspect takes any CSS aspect ratio, "1" for square thumbnails), a title and meta lines (lines, 2), a price line and a round action (footer, true). role="status" with a hidden label ("Loading"). Every preset also takes animation, speed, color and highlight. Props: { media?: boolean; mediaAspect?: string; lines?: number; footer?: boolean; radius?; label?: string; classNames?: { media, body, footer } }.
- `SkeletonList` (component): List group rows (56px, px-4): a 40px avatar, a title and a subtitle, a button-sized action, hairlines between rows. 4 rows by default. classNames.avatar="rounded-[10px]" makes square thumbnails. Props: { rows?: number; avatar?: boolean; action?: boolean; dividers?: boolean; label?: string; classNames?: { row, avatar, action } }.
- `SkeletonTable` (component): A table-shaped grid from 768px up (a header and 48px rows, the first column wider), one card per row below: a title line and two label / value pairs. Pure CSS, right on the first paint. 5 rows, 4 columns. Props: { rows?: number; columns?: number; header?: boolean; label?: string; classNames?: { header, row, card } }.
- `SkeletonProfile` (component): A profile header: a cover the avatar overlaps through a round cut-out, name and meta lines, and a row of stats (3). avatarSize is in px (80). Props: { cover?: boolean; stats?: number; avatarSize?: number; radius?; label?: string; classNames?: { cover, avatar, stats } }.

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

type Listing = { title: string; city: string; photo: string }

export function ListingCard({ listing }: { listing?: Listing }) {
  if (!listing) return <SkeletonCard label="Loading the listing" />
  return (
    <article className="flex flex-col gap-3">
      <img src={listing.photo} alt="" className="aspect-[16/10] w-full rounded-[10px] object-cover" />
      <h3 className="text-[15px] font-semibold">{listing.title}</h3>
      <p className="text-[13px] text-muted-foreground">{listing.city}</p>
    </article>
  )
}

export function Seller({ loading }: { loading: boolean }) {
  return (
    <div className="flex items-center gap-3">
      <Skeleton shape="circle" loading={loading}>
        <img src="/ana-pop.jpg" alt="Emma Carter" className="size-10 rounded-full" />
      </Skeleton>
      <Skeleton shape="line" loading={loading}>
        <p className="text-sm font-medium">Emma Carter</p>
      </Skeleton>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/skeleton (Markdown: https://wingo-ui.com/components/skeleton.md)

#### Spinner (`spinner`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add spinner`

The loading indicator for anything without a known shape: six styles, from a quiet ring to the iOS spokes, in any size, tone or speed.

It turns on its own and never takes focus. Screen readers hear its label once, as a polite status, and nothing else; inside a parent that already announces the wait (a loading button) pass aria-hidden and it stays silent. With a delay it stays invisible for fast loads and fades in only when the wait gets long enough to notice. Under reduced motion it keeps turning at half speed, so the page still reads as busy. Every style animates only transform and opacity on the compositor, so it keeps moving while the page is busy.
Wingo UI dependencies: ui-config, tones

Props:
- `variant?: "ring" | "dots" | "bars" | "pulse" | "orbit" | "spokes"` = "ring": ring: a quarter arc over a faint track. dots: three dots in a wave. bars: three bars like an equalizer. pulse: a dot with an expanding ring. orbit: two dots circling. spokes: the iOS activity indicator, 8 spokes (12 from 40px) with the light traveling clockwise.
- `size?: "sm" | "md" | "lg" | number` = "md": 16 / 24 / 40px, or any px number (12 at least). sm for inline text and buttons, md for cards and panels, lg for a whole page. The ring stroke and the label grow with it.
- `tone?: "current" | "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "current": current follows the text color, so it works inside any colored parent (a solid button, a colored chip). A tone paints the indicator with the design tokens and the visible label with the readable tone text.
- `color?: string` = "": Any CSS color. Replaces the tone; faded parts use the same color at lower opacity. Leave empty to use the tone.
- `speed?: number` = 1: Playback multiplier: 0.5 is half speed, 2 twice as fast. Clamped to 0.25 to 4. Every style keeps its own rhythm (ring 0.75s, spokes 0.8s, dots 1s per loop).
- `label?: string` = "Loading": The accessible name, announced once as a polite status. Shown next to the indicator with showLabel. Pass aria-hidden when a parent already announces the loading (a loading button): the spinner then drops its status role and this label.
- `showLabel?: boolean` = false: Shows the label next to (or under) the indicator. Without it the label is only for screen readers.
- `labelPosition?: "end" | "bottom"` = "end": end sits beside the indicator for inline use; bottom stacks it, for page and panel loaders.
- `track?: boolean` = true: Ring only: the faint full circle under the arc. Turn it off for a lighter look on busy backgrounds.
- `delay?: number` = 0: Milliseconds before anything renders, label included, counted from mount. 300 hides the spinner entirely for fast loads, so it never flashes; after the wait it fades in. A spinner that is already showing never hides again when delay changes (remount it with a key to replay the wait).
- `paused?: boolean` = false: Holds the current frame. Useful while a pull-to-refresh is still being dragged, or for a still in a gallery.
- `classNames?: Partial<Record<"indicator" | "label", string>>`: Extra classes for the drawing (svg or span) and the label.
- `className?: string`: Extra classes for the root span, merged last. Override the color with [--spinner-color:...].
- `style?: CSSProperties`: Inline styles for the root span.

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

export function ListingsLoading() {
  return (
    <div className="flex flex-col items-center gap-3 py-12 text-muted-foreground">
      <Spinner variant="spokes" size="lg" delay={300} label="Loading listings" />
      <p className="text-sm">Searching apartments in New York…</p>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/spinner (Markdown: https://wingo-ui.com/components/spinner.md)

#### Toast (`toast`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add toast`

Toast notifications: a Toaster mounted once and a toast() you call from anywhere, stacked, swipeable and paused while you read.

New toasts rise from the edge and stack, the older ones peeking behind the newest. On desktop, hovering the stack fans it out into a list; on a phone, tap it. Swipe a toast toward the edge (down for a bottom stack) or toward its side to dismiss it; a short drag springs back, and a mouse drag works too. Timers pause while you hover, while keyboard focus is inside, while you drag and while the tab is in the background, then resume with the time that was left. Alt+T (⌥T on a Mac) jumps to the newest toast, Tab walks through its buttons, Escape dismisses the focused one. A promise toast turns from loading into success or error in place. Action buttons sit beside the text when the toast has room and move under it when it does not (two buttons, a close button, a narrow phone). On phones toasts span the width with 16px gutters and respect the safe area; under reduced motion they fade instead of moving.

npm: motion, lucide-react
Wingo UI dependencies: button, spinner, motion, tones, use-shortcut, use-media-query, ui-config

Props:
- `position?: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"` = "bottom-right": Where the stack sits on desktop. A bottom stack grows upward and is swiped down; a top one grows downward and is swiped up. Side stacks also swipe toward their side, centered ones either way.
- `mobilePosition?: "top" | "bottom"` = "bottom": Below 768px toasts span the width, pinned to the top or the bottom of the screen, above the safe area (home indicator, notch).
- `expand?: boolean` = false: Always shows the toasts as a list instead of a stack. Timers keep running; hovering or tapping still pauses them.
- `visibleToasts?: number` = 3: How many toasts show at once. Older ones wait in line with their timers stopped and slide in as newer ones leave.
- `duration?: number` = 4000: Default time on screen in ms. A toast can set its own (Infinity keeps it until dismissed); loading toasts wait for their update.
- `gap?: number` = 12: Space between toasts in px while the list is expanded.
- `offset?: number` = 24: Distance from the viewport edges in px on desktop (never less than the safe area).
- `mobileOffset?: number` = 16: Side gutters and edge distance in px on phones. Where the safe area (home indicator, notch) is larger, it wins.
- `width?: number` = 356: Toast width in px on desktop. Never wider than the viewport minus the offsets; phones always use the full width.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of every toast: 0 / 12 / 16 / 24px (full falls back to lg).
- `richColors?: boolean` = false: Tints success, error, warning and info toasts with their tone (an opaque mix over the popover, text and icon in the readable tone color) instead of the neutral surface with a colored icon.
- `closeButton?: boolean` = false: An X at the top end of every toast. A toast can override it with its own closeButton option.
- `hotkey?: string` = "alt+t": Moves focus to the newest toast, in mod+k notation. It is appended to the region label ("Notifications Alt+T"). Empty turns it off.
- `pauseWhenPageIsHidden?: boolean` = true: Stops every timer while the tab is in the background, so nothing expires unseen.
- `toasterId?: string` = "": Makes this toaster show only toasts sent with the same toasterId option, for independent toasters on one page (a canvas, a side panel). Without it, it shows every toast sent without one.
- `icons?: Partial<Record<ToastType, ReactNode>>`: Replaces the icon per type (success, error, warning, info, loading, default).
- `labels?: { region?: string; close?: string }`: The region's aria-label (default "Notifications", the hotkey is appended) and the close buttons' label (default "Close").
- `classNames?: Partial<Record<"toaster" | "list" | "toast" | "icon" | "content" | "title" | "description" | "actions" | "action" | "cancel" | "close", string>>`: Extra classes for the parts. toast is the visible card; toaster and list the fixed region and the stack.
- `className?: string`: Extra classes for the fixed region, merged last. It is rendered in place (not portaled): mount it once in the root layout. className="absolute" pins it inside a relative container.

Parts:
- `toast` (function): Shows a toast and returns its id. Also toast.success / error / warning / info / loading(message, options), toast.promise(promise, { loading, success, error }, options) which returns the original promise, toast.custom((id) => node, options) and toast.dismiss(id?) (all when no id). Call it again with the same { id } to update a toast in place: with the same type only the options you pass change (progress text), with a new type (loading to success) it starts over from the new options, so a loading toast's Infinity duration or description never sticks to the result. Works outside React and before the Toaster mounts. Signature: (message: ReactNode, options?: ToastOptions) => string.
- `ToastOptions` (type): Per toast: icon null hides the type icon, tone or color override the type's color, action { label, onClick, keepOpen } closes the toast unless keepOpen or preventDefault, cancel { label, onClick }, dismissible false blocks swipe, close and Escape, closeButton and richColors override the Toaster's, important makes it assertive (errors already are), onDismiss fires when the user closes it, onAutoClose when it times out. Type: { id, toasterId, description, icon, tone, color, duration, action, cancel, dismissible, closeButton, richColors, important, className, onDismiss, onAutoClose }.
- `Toast` (component): One toast as a static card (type, title, description, icon, tone, color, action, cancel, closeButton, richColors, radius): what the Toaster renders, usable on its own for mockups and inline confirmations. Props: ToastProps.
- `useToasts` (hook): The toasts on screen, newest first, for a counter or a clear-all button. Signature: (toasterId?: string) => ToastData[].

```tsx
import type { ReactNode } from "react"
import { Button } from "@/components/ui/button"
import { Toaster, toast } from "@/components/ui/toast"

// once, next to the app in the root layout
export function Providers({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <Toaster richColors />
    </>
  )
}

// anywhere else
export function PublishButton({ publish }: { publish: () => Promise<{ price: string }> }) {
  return (
    <Button
      onClick={() =>
        toast.promise(publish, {
          loading: "Publishing the listing…",
          success: (data) => `Published for ${data.price}`,
          error: "Could not publish the listing",
        })
      }
    >
      Publish
    </Button>
  )
}
```

Docs: https://wingo-ui.com/components/toast (Markdown: https://wingo-ui.com/components/toast.md)

### Data Display

#### Approval Flow (`approval-flow`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add approval-flow`

A request's sign-off chain: who approved, who is next and who can still reject, with comments, reminders, history and a compact summary.

Read the chain top to bottom: a green check per approved step, a ring with a clock on the step that waits, numbers on the ones after it, and every approver with a status ring, a decision badge, the time and their comment. When it is your turn a tinted bar asks for your decision: write an optional comment (type @ to mention a colleague, arrows and Enter pick one), then press Approve, Request changes or Reject. Reject opens a dialog (a bottom sheet on phones) that focuses the reason field and will not go on without a reason; Cmd or Ctrl + Enter there confirms, Escape cancels and returns focus. Approve never fires from the keyboard shortcut: decisions are explicit clicks. While a decision saves the pressed button spins and the others wait; an error from the server shows under the buttons. Once it saves, the bar folds away and keyboard focus moves to the flow instead of getting lost. Late approvers get a Send a reminder button, amber once the step is overdue. The last approval pops the final marker with a small bounce. The History row folds the timeline open and closed. In the compact variant the summary (stacked avatars with rings, 2 of 3 approvals, the status) is a button that opens the whole flow in a popover, a sheet on phones. Wider than 512px a horizontal flow lays its steps in a row; narrower it stacks. Everything is announced to screen readers and reduced motion turns the springs into instant changes.

npm: motion, lucide-react
Wingo UI dependencies: mention-input, timeline, avatar, badge, button, dialog, textarea, tooltip, popover, relative-time, commerce, use-locale, use-controllable-state, motion, tones, ui-config

Props:
- `steps: ApprovalStep[]`: The chain in order: { id, name, description?, rule?: "any" | "all", approvers, dueAt?, skipped? }. Each approver is { id, name, avatar?, role?, decision?, decidedAt?, comment? (mention markup), delegatedFrom? }. The status of each step and of the request is derived from the decisions.
- `title?: ReactNode` = "": The request, e.g. "15% discount · Keystone Construction". Without it the section is named by labels.title for screen readers. The demo shows a sample while the field is empty.
- `requester?: { name: string; avatar?: string }`: Who asked, shown with a small avatar in the meta line under the title.
- `submittedAt?: TimeInput`: When it was submitted: a relative time in the meta line, the full date on hover.
- `amount?: number` = 0: The money the request is about, in major units, formatted with formatPrice in the meta line. 0 hides it (the demo then shows its sample amount).
- `currency?: string` = "USD": ISO 4217 code for the amount.
- `status?: "draft" | "pending" | "approved" | "rejected" | "changes-requested" | "cancelled" | ""` = "": Overrides the status derived from the steps. Draft and cancelled only exist this way; any status other than pending hides the action bar and the active step ring.
- `currentUserId?: string` = "": The person looking. When they are a pending approver of the active step the action bar shows and their row gets a You badge; anyone else sees who the request waits for. The demo's "View as" switch sets it while this field is empty.
- `onDecision?: (input: ApprovalDecisionInput) => (void | Promise<unknown>)`: Runs on Approve, Reject and Request changes with { stepId, decision: "approved" | "rejected" | "changes-requested", comment (markup), mentions (ids) }. A promise keeps the pressed button busy; a rejection shows its message under the buttons (or in the reject dialog).
- `requireRejectComment?: boolean` = true: Reject opens a dialog (a sheet on phones) that needs a reason. false rejects at once with the comment as it is.
- `allowRequestChanges?: boolean` = true: Shows the third action, Request changes, which sends the request back without rejecting it.
- `onRemind?: (approver: ApprovalApprover, step: ApprovalStep) => (void | Promise<unknown>)`: Adds a Send a reminder button to the pending approvers of the active step (amber once the step is overdue). A promise spins it; success turns it into Reminder sent and announces it.
- `people?: MentionItem[]`: The colleagues @ can mention in the comment box (MentionInput). Without it the comment box is a plain Textarea.
- `history?: ApprovalHistoryEntry[]`: The events: { id, at, actor: { name, avatar? }, type: submitted | approved | rejected | changes-requested | comment | reminder | resubmitted | cancelled, comment?, stepId? }, shown as a feed timeline under a History (n) toggle.
- `showHistory?: boolean` = true: Shows the History toggle when there is history.
- `historyDefaultOpen?: boolean` = false: Starts with the history open.
- `defaultOpen?: boolean` = false: Starts with the overlay open: the reject dialog in the full variant (when the viewer can decide), the details popover in compact. Control it with open and onOpenChange.
- `open?: boolean`: Controlled overlay state (reject dialog or compact popover); pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Runs when the reject dialog or the compact popover opens or closes.
- `orientation?: "vertical" | "horizontal"` = "vertical": horizontal lays the steps in a row with an avatar group under each, for page and invoice headers. Below 512px of width it stacks vertically anyway.
- `variant?: "full" | "compact"` = "full": compact renders only the summary (stacked avatars with status rings, 2 of 3 approvals, the status badge) as a button that opens the full flow in a popover, a bottom sheet on phones. For table rows and cards.
- `size?: "sm" | "md"` = "md": sm tightens the panel, the markers (24px), the avatars and the text for side panels.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active step's ring, the your-turn bar and the Approve button. Decisions keep their status colors: green approved, red rejected, blue changes requested, amber waiting.
- `color?: string` = "": Any CSS color; replaces the tone for the active ring, the bar and the Approve button.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner of the panel: 0, 12, 16 or 24px.
- `surface?: boolean` = true: The raised panel look. false drops the background, shadow and padding for a flow inside a card of your own.
- `maxAvatars?: number` = 4: Compact: avatars before the +N chip.
- `now?: Date | number`: The moment relative times and overdue checks count from. Defaults to the live clock (useNow); demos pin 24.09.2026 16:40.
- `locale?: string` = "": Locale for money, dates and relative times. Empty uses the UIProvider locale, then the browser's.
- `labels?: ApprovalFlowLabelsInput (a deep Partial<ApprovalFlowLabels>)`: Every string, English by default (DEFAULT_APPROVAL_FLOW_LABELS): title, statuses, decisions, stepStatuses, events, any, all, due(date), overdue(date), approve, reject, requestChanges, comment, cancel, rejectTitle, rejectDescription, rejectReason, rejectReasonPlaceholder, rejectReasonRequired, mentionPeople, mentionEmpty, remind, reminderSent, reminded(name), remindError, yourTurn, waitingFor(names), progress(approved, required), history(count, formatted), submitted, skipped, delegated(from), you, decided(decision), decisionError.
- `classNames?: Partial<Record<"header" | "title" | "meta" | "status" | "steps" | "step" | "marker" | "connector" | "stepName" | "rule" | "due" | "approver" | "comment" | "remind" | "actions" | "history" | "summary", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root section (the summary button in compact), merged last.

Parts:
- `ApprovalSummary` (component): The compact form alone for table cells: avatars with status rings, the progress and the status badge. A button when it gets onClick, with an aria-label like "2 of 3 approvals, Pending, Waiting for Ioana Dumitrescu". Props: { steps; status?; size?; max?; showCount?; showStatus?; locale?; labels?; classNames?; onClick? }.
- `getApprovalStatus` (function): The derived overall status: approved when every step is approved or skipped, the active step's rejected or changes-requested, otherwise pending; draft without steps. Pure, for servers and lists. Signature: (steps: ApprovalStep[]) => ApprovalStatus.
- `getActiveStep` (function): The first step that is neither approved nor skipped. Signature: (steps: ApprovalStep[]) => ApprovalStep | null.
- `getStepStatus` (function): One step's outcome: any needs one approval, all needs every approver; a step without approvers counts as skipped. Signature: (step: ApprovalStep) => "approved" | "rejected" | "changes-requested" | "pending" | "skipped".
- `getApprovalProgress` (function): Approvals given and needed across the chain (the 2 of 3 in the summary). Signature: (steps: ApprovalStep[]) => { approved: number; required: number }.

```tsx
import { useState } from "react"
import { ApprovalFlow, type ApprovalStep } from "@/components/ui/approval-flow"

const initialSteps: ApprovalStep[] = [
  {
    id: "sales",
    name: "Sales manager",
    approvers: [{ id: "u-ryan", name: "Ryan Martin", role: "Sales", decision: "approved", decidedAt: "2026-09-22T14:05:00" }],
  },
  {
    id: "finance",
    name: "Finance director",
    description: "required over $10,000",
    dueAt: "2026-09-24T12:00:00",
    approvers: [{ id: "u-jessica", name: "Jessica Dunn", role: "Accounting" }],
  },
  { id: "ceo", name: "CEO", approvers: [{ id: "u-liam", name: "Liam Brooks", role: "Owner" }] },
]

export function DiscountApproval() {
  const [steps, setSteps] = useState(initialSteps)
  return (
    <ApprovalFlow
      title="15% discount · Keystone Construction"
      requester={{ name: "Michael Hayes" }}
      submittedAt="2026-09-22T11:20:00"
      amount={103400}
      currency="USD"
      currentUserId="u-jessica"
      steps={steps}
      labels={{ approve: "Approve", reject: "Decline", requestChanges: "Ask for changes" }}
      onDecision={async ({ stepId, decision, comment }) => {
        await fetch("/api/approvals", { method: "POST", body: JSON.stringify({ stepId, decision, comment }) })
        setSteps((prev) =>
          prev.map((step) =>
            step.id !== stepId
              ? step
              : {
                  ...step,
                  approvers: step.approvers.map((a) =>
                    a.id === "u-jessica" ? { ...a, decision, comment, decidedAt: new Date() } : a,
                  ),
                },
          ),
        )
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/approval-flow (Markdown: https://wingo-ui.com/components/approval-flow.md)

#### Avatar (`avatar`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add avatar`

A person or organization as a photo that falls back to colored initials, with a status dot, five sizes, any shape and a stacking group.

Photos fade in once they load; a slow photo shows its color first and the initials only after a short wait, and a broken one settles on the initials without a flash. A status dot pops in when the status changes. Hover a group, or Tab into it, and the stack fans out on a spring; the avatar under the pointer lifts. On a phone the first tap fans the group out, the next tap on an avatar or on +N opens it, and a tap outside folds it back. With avatar buttons, Tab walks the stack with a focus ring, and when +N reveals the rest in place, focus moves to the first new avatar. Screen readers hear the name and the status, and +N reads as a count.

npm: @radix-ui/react-avatar, motion, lucide-react
Wingo UI dependencies: motion, tones, ui-config

Props:
- `src?: string` = "": Image URL. While it loads the avatar shows its fallback color, and if it fails the initials take over. The demo uses /demo/ana-pop.jpg while this is empty; type a broken URL to see the fallback.
- `name?: string` = "": The person or organization. It is the spoken label, gives the initials ("Steven Grant" becomes SG) and picks the fallback color. The demo shows Anna Price while this is empty.
- `alt?: string` = "": The spoken label when it should differ from name, e.g. "Anna Price, administrator". Empty uses name. The avatar is one image to screen readers: this label plus the status.
- `size?: "xs" | "sm" | "md" | "lg" | "xl" | number` = "md": 24 / 32 / 40 / 48 / 64px with initials at 10 / 12 / 14 / 16 / 22px, or any number of px (initials and the status dot scale along). Five sizes on purpose: avatars live in dense lists and on profile headers.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": full is a circle; sm, md and lg round 16 / 24 / 32% of the size, so every size keeps its shape. Squares suit companies and workspaces.
- `status?: "none" | "online" | "offline" | "busy" | "away"` = "none": A dot on the bottom end edge: green online, gray offline, red with a bar for busy, amber away. It pops in when it changes and is spoken after the name.
- `statusLabels?: Partial<Record<"online" | "offline" | "busy" | "away", string>>`: The spoken status. Defaults to { online: "Online", offline: "Offline", busy: "Busy", away: "Away" }.
- `variant?: "soft" | "solid"` = "soft": How the fallback is painted: soft is a light tint with deep initials, solid a filled disc with white initials (black on a light custom color). Photos cover either.
- `colorful?: boolean` = true: Initials on a color picked from the name: a stable hash into 12 hues, so a person keeps the same color everywhere. The initials are derived from the hue so they keep 4.5:1 in both themes. Off keeps every fallback neutral.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": A fixed fallback color instead of the name hash. Any tone but neutral wins over colorful; neutral leaves the choice to colorful.
- `color?: string` = "": Any CSS color for the fallback, a company or team color. Soft tints with it and derives readable initials; solid fills with it as is. Wins over tone and colorful. Leave empty to use them.
- `ring?: boolean` = false: A 2px ring in ringColor that cuts the avatar out of whatever it overlaps. Groups turn it on; the demo shows it where the avatar overlaps the cover.
- `ringColor?: string` = "": The surface behind the avatar, used for the ring and the status dot outline. Empty inherits a --avatar-ring set by a parent, else var(--background). Pass var(--surface) on panels, or set [--avatar-ring:var(--surface)] once on the panel.
- `fallbackDelay?: number` = 250: Milliseconds before the fallback shows while a photo loads, so fast photos never flash initials. Only applies with src: a list without photos shows its initials at once.
- `fallback?: ReactNode`: Replaces the initials and the user icon: a company logo, an icon, an emoji.
- `onLoadingStatusChange?: (status: "idle" | "loading" | "loaded" | "error") => void`: Fires as the photo loads or fails. The root also carries it as data-state.
- `classNames?: Partial<Record<"image" | "fallback" | "status", string>>`: Extra classes for the photo, the fallback and the status dot.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `AvatarGroup` (component): A stack with a +N chip. items (AvatarProps[]) or Avatar children; max = 4 before +N; total for the real count (+N = total - shown); size = "md" and radius = "full" for every avatar; overlap "sm" | "md" | "lg" (20 / 28 / 36%, default "md"); spread "hover" (default: fans out on hover, keyboard focus or a first tap; the box keeps its size and the fan overflows to the end, so leave room after it) | "always" | "never"; ringColor; onAvatarClick(index) makes avatars buttons; onOverflowClick makes +N a button; overflowLabel = n => `${n} more`; label = "People" (the group's aria-label); classNames { item, overflow }. Props: AvatarGroupProps.
- `getInitials` (function): The first letter of the first and last word, Unicode-aware, upper-cased with the ro-RO rules by default: "émile zola" gives ÉZ, one word gives one letter, emoji and punctuation are skipped. Signature: (name: string, locale?: string) => string.
- `avatarColor` (function): The fallback color for a name, one of 12 hues (AVATAR_COLORS). Use it to color the same person the same way in lists and charts. Signature: (name: string) => string.

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

const team = [
  { name: "Michael Hayes", src: "/demo/mihai-ionescu.jpg" },
  { name: "Steven Grant" },
  { name: "Jessica Dunn", src: "/demo/ioana-dumitrescu.jpg" },
  { name: "Bianca Ross" },
  { name: "Andrew Porter", src: "/demo/andrei-popescu.jpg" },
]

export function ProfileHeader({ onOpenTeam }: { onOpenTeam: () => void }) {
  return (
    <div className="flex items-center gap-3 rounded-3xl bg-surface p-4 shadow-raised [--avatar-ring:var(--surface)]">
      <Avatar src="/demo/ana-pop.jpg" name="Anna Price" size="lg" status="online" statusLabels={{ online: "Available" }} />
      <div className="min-w-0 flex-1">
        <p className="text-[15px] font-semibold">Anna Price</p>
        <p className="text-[13px] text-muted-foreground">Member since 2019 · San Francisco</p>
      </div>
      <AvatarGroup items={team} max={3} size="sm" label="Team" overflowLabel={(n) => `${n} more`} onOverflowClick={onOpenTeam} />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/avatar (Markdown: https://wingo-ui.com/components/avatar.md)

#### Badge (`badge`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add badge`

Status chips, removable filters and animated counts in three variants and six tones, plus an anchor that pins a count or dot to any corner.

A status badge is plain text in a tinted pill; with pulse its dot pings like a live light. A count rolls to the new number, up when it grows and down when it shrinks, the pill widens on a smooth spring and gives a small bounce on every new item; at 0 it scales away. Removable chips show a round x: click or tap it (a 36px target on touch), or focus it with Tab and press Enter, Backspace or Delete. With asChild the badge is a real link or button with a hover tint, a press dip, a focus ring and a 44px tall touch target. BadgeAnchor pins a badge to a corner of an icon button or avatar, cut out by a thin ring, and pops it in and out.

npm: @radix-ui/react-slot, lucide-react, motion
Wingo UI dependencies: motion, tones, ui-config

Props:
- `children?: ReactNode` = "Nou": The label. Long labels truncate with an ellipsis. Leave it empty (with no icons or count) and the badge becomes a status dot.
- `variant?: "solid" | "soft" | "outline"` = "soft": soft (a tinted pill) for statuses, solid for counts and the one label that must stand out, outline for filters and quiet tags.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color from the design tokens: success for paid or online, warning for low stock, danger for cancelled or failed, info for in progress. Pair color with the text, never color alone.
- `color?: string` = "": Any CSS color. Replaces the tone in every variant; text on a solid fill turns black or white by lightness. Leave empty to use the tone.
- `size?: "sm" | "md" | "lg"` = "md": Height 20 / 24 / 28px with 11 / 12 / 13px text and 12 / 12 / 14px icons.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape: 0 / 4 / 6 / 8px or a pill. Badges default to pills (a deliberate difference from controls); the square steps suit tag-like labels.
- `dot?: boolean` = false: A leading status dot in the tone (in the text color on a solid badge).
- `pulse?: boolean` = false: The dot pings, for live, recording or online. Implies dot. Decorative (hidden from screen readers); under reduced motion the dot stays still.
- `max?: number` = 99: Counts above it read "99+". Values below 1 fall back to 99. Only used with count.
- `showZero?: boolean` = false: A count of 0 scales the badge away unless this is set. Try it on the bell: tap it to mark all as read.
- `locale?: string` = "": Formats the count through Intl, e.g. "en-US" turns 1250 into 1,250 and "de-DE" into 1.250. Empty uses the reader's locale; pass one for server-rendered counts of 1000 or more so the grouping matches after hydration.
- `removeLabel?: string` = "Remove": aria-label of the remove button, e.g. "Remove the Brooklyn filter". Only used with onRemove.
- `disabled?: boolean` = false: Dims the badge (a count too) and hides the remove button. With asChild the link gets aria-disabled, leaves the tab order and ignores clicks.
- `asChild?: boolean` = false: Renders your single child (an <a>, a router Link, a button) as the badge, with a hover tint, a press dip and a focus ring. asChild badges have no remove button, since a button inside a link is invalid. The demo swaps in a link.
- `count?: number`: Shows this number instead of children and animates every change: the digits slide, the width follows on a spring and the badge bumps when it grows. Negative values clamp to 0, fractions round. The demo's bell drives it with the + and - buttons.
- `leftIcon?: ReactNode`: An icon before the label. Unsized svgs follow the size (12 / 12 / 14px).
- `rightIcon?: ReactNode`: An icon after the label, like an arrow on a link badge.
- `onRemove?: () => void`: Shows a round x button that calls it on click, tap, Enter, Backspace or Delete. The click does not bubble, so a chip inside a clickable row removes itself without opening the row.
- `classNames?: Partial<Record<"dot" | "icon" | "label" | "count" | "remove", string>>`: Extra classes for the inner parts: the status dot, each icon wrapper, the label, the count and the remove button.
- `className?: string`: Extra classes for the badge itself, merged last. Override the tone vars here, e.g. [--tone-foreground:white].

Parts:
- `BadgeAnchor` (component): Pins a badge to a corner of its child (an icon button, an avatar). badge: the Badge to place (a count, or an empty Badge for a dot). placement: "top-end" (default) | "top-start" | "bottom-end" | "bottom-start", logical so it flips in RTL. offset: px, default 0; positive moves the badge inward, about 5 to 6px puts it on the edge of a round 40px host. invisible: scales it out and back in. ringColor: default var(--background), the 2px ring that cuts the badge out of its host (pass var(--surface) on panels). classNames.badge: the placed wrapper, which lets clicks through to the host. Props: BadgeAnchorProps.

```tsx
import { Bell } from "lucide-react"
import { Badge, BadgeAnchor } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

export function OrderHeader({ unread, onOpenInbox }: { unread: number; onOpenInbox: () => void }) {
  return (
    <div className="flex items-center gap-3">
      <Badge tone="success" dot>Paid</Badge>
      <Badge tone="warning">Low stock</Badge>
      <BadgeAnchor offset={5} badge={<Badge variant="solid" tone="danger" size="sm" count={unread} aria-hidden />}>
        <Button variant="soft" size="icon" radius="full" aria-label={`Notifications, ${unread} unread`} onClick={onOpenInbox}>
          <Bell />
        </Button>
      </BadgeAnchor>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/badge (Markdown: https://wingo-ui.com/components/badge.md)

#### Calendar View (`calendar-view`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add calendar-view`

A scheduler for appointments and meetings: month, week, day and agenda views with a now line, event details and drag to reschedule.

Switch between Month, Week, Day and Agenda in the toolbar; the arrows move a period back or forward and Today jumps home, while the body slides in the direction you went and the title announces the new range. Click or tap an event to open its details (time, location, attendees) in a popover next to it; on a phone they rise as a bottom sheet. A month cell that has more events than fit shows "+2 more", which lists the whole day. With editable on and a mouse or pen, drag an event to another time or day (it snaps to the slot and springs into place while the original stays as a faint ghost) and drag its bottom edge to change the length; the change is applied at once and undone if onEventChange returns false. With onSlotSelect, click an empty slot to pick an hour or drag down the grid (or across days in the month) to select a range. Click a day number or a week column heading to open that day. Keyboard: the month is one Tab stop; arrows move by day and week, Home / End go to the start and end of the week, PageUp / PageDown change the month (Shift for a year), Enter opens the day's events, and Tab moves on to the events inside the day. In week, day and agenda PageUp / PageDown change the period while focus is inside, and events are buttons in time order read as the title and the time range. Escape closes the details and returns focus to the event. On a phone (or whenever the calendar is narrower than 576px) month and week turn into the agenda (or the compact month with dots and the day's list below, or the day view), agenda days have sticky headings and open at today, rows are 56px tall, and you swipe left or right on the day view and the compact month to change the period. Dragging events is off on touch so the page still scrolls. Reduced motion replaces the slides with fades.

npm: @dnd-kit/core, date-fns, lucide-react, motion
Wingo UI dependencies: avatar, button, empty-state, popover, progress, segmented-control, use-controllable-state, use-locale, use-media-query, date-utils, motion, relative-time, tones, ui-config

Props:
- `events?: CalendarEvent[]` = "[]": The events: { id, title, start: Date, end: Date, allDay?, tone?, color?, location?, description?, attendees?: { name, avatar? }[], editable?, meta? }. An all-day event ending at local midnight ends the day before; an end at or before the start reads as 30 minutes (with a dev warning). Events crossing midnight show a block per day; multi-day events span the month cells as one bar per week.
- `defaultView?: "month" | "week" | "day" | "agenda"` = "month": The view it opens in. Control it with view and onViewChange.
- `view?: "month" | "week" | "day" | "agenda"`: The current view (controlled); pair it with onViewChange.
- `onViewChange?: (view: CalendarViewMode) => void`: Fires when the switch, a day number or a week column heading changes the view.
- `views?: CalendarViewMode[]` = "[\"month\", \"week\", \"day\", \"agenda\"]": The views in the switch, in this order. A single view hides the switch.
- `defaultDate?: Date`: The focused date it opens on. Without it the server renders the first event's day and the browser moves to today after mount (no hydration mismatch).
- `date?: Date`: The focused date (controlled); pair it with onDateChange.
- `onDateChange?: (date: Date) => void`: Fires on prev / next / Today, on arrow keys in the month and when a day is picked.
- `mobileView?: "agenda" | "day" | "month"` = "agenda": What phones get instead of month and week (a container query: whenever the calendar is narrower than 576px, so a narrow side panel gets it too; both layouts are in the server HTML): the agenda of that month or week, the focused day, or a compact month with dots and the chosen day's events listed underneath. The phone switch only offers views that make sense there.
- `layout?: "responsive" | "desktop" | "mobile"` = "responsive": responsive switches to the phone layout when the calendar itself is narrower than 576px; desktop and mobile force one layout, e.g. a phone frame on a wide screen.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface: a raised panel. outline: a hairline border on the page. plain: no container, for a page that is only the calendar.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The tone of events without their own tone or color: chips, blocks, agenda bars and dots.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: The first day of the week: 0 is Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Sunday in en-US, Monday in de-DE).
- `dayStartHour?: number` = 0: The first hour of the week and day grids.
- `dayEndHour?: number` = 24: The hour the week and day grids end at (at least one hour after dayStartHour).
- `scrollToHour?: number` = 8: Where the week and day grids open. Moving to another week keeps the scroll position you left.
- `slotMinutes?: 15 | 30 | 60` = "30": The snap for creating, moving and resizing events. Half-hour lines are dashed whenever the slot is under an hour.
- `hourHeight?: number` = 48: Pixels per hour in the week and day grids. Touch screens get at least 56px so short events stay tappable.
- `height?: number` = 600: Height of the scrolling week / day grid and the most the agenda grows to before it scrolls, in px.
- `maxEventsPerDay?: number` = 3: Chips per month cell before the last line turns into "+N more", which lists the day in a popover (a sheet on phones).
- `showWeekNumbers?: boolean` = false: ISO week numbers in a narrow column at the start of each month row.
- `showNowIndicator?: boolean` = true: A red line with a dot at the current time in today's column of the week and day grids; it moves once a minute.
- `hideWeekends?: boolean` = false: The week view shows the five working days of the locale.
- `editable?: boolean` = false: Drag events to move them and drag their bottom edge to resize, with a mouse or pen, snapped to slotMinutes. Events can opt out with editable: false. Off on touch screens, where dragging would fight scrolling.
- `onEventChange?: (event: CalendarEvent, change: CalendarEventChange) => (false | void)`: After a move or resize. The change shows at once; return false to put the event back. Update your events with the new times.
- `onEventClick?: (event: CalendarEvent, domEvent: MouseEvent<HTMLElement>) => void`: Every click on an event. Call domEvent.preventDefault() to skip the built-in details (open your own drawer instead).
- `showEventDetails?: boolean` = true: The built-in details on click: a popover next to the event, a bottom sheet on phones.
- `renderEventDetails?: (event: CalendarEvent) => ReactNode`: Replaces the default details (title, time, location, description, attendees, meta) inside the popover or sheet.
- `openEventId?: string | null`: The event whose details are open (controlled), e.g. to open a new event right after onSlotSelect adds it.
- `defaultOpenEventId?: string | null` = "": The event whose details are open at first. In the playground try c26 (Implant follow-up on the 24th).
- `onOpenEventIdChange?: (id: string | null) => void`: Fires when details open or close.
- `onSlotSelect?: (slot: { start: Date; end: Date; allDay: boolean }) => void`: Makes empty time selectable: click a slot for an hour, or drag down the grid (desktop) with a ghost "New event" showing the range; in the month click a day or drag across days for all-day ranges. Tap on touch.
- `renderEvent?: (event: CalendarEvent, info: { view: CalendarViewMode }) => ReactNode`: Replaces the content of chips and blocks; the button, position, tone and drag stay.
- `toolbar?: boolean` = true: The title, prev / Today / next and the view switch.
- `toolbarActions?: ReactNode`: Buttons at the end of the toolbar, like "New appointment".
- `loading?: boolean` = false: A thin indeterminate bar under the toolbar while events refresh; the current events stay.
- `emptyAgenda?: ReactNode`: Shown when the agenda range has no events. Defaults to a small EmptyState with labels.noEvents.
- `agendaDays?: number` = 14: How many days the agenda view lists from the focused date; prev / next move by that many.
- `locale?: string` = "": Month and weekday names, times (09:30 or 9:30 AM) and the first day of the week. Empty uses UIProvider, then the page language.
- `labels?: Partial<CalendarViewLabels>`: Every string, English by default: today, previous, next, month, week, day, agenda, allDay, more(n), noEvents, newEvent, weekNumber, eventTime(start, end), eventCount(n), views, loading, drag { start, end, cancel }, details { location, attendees, close, title }. DEFAULT_CALENDAR_VIEW_LABELS has them all.
- `classNames?: Partial<Record<"toolbar" | "title" | "nav" | "switch" | "actions" | "body" | "month" | "weekdays" | "day" | "week" | "event" | "more" | "weekHeader" | "allDay" | "scroll" | "gutter" | "grid" | "now" | "agenda" | "agendaDay" | "agendaEvent" | "details", string>>`: Extra classes for the inner parts.
- `children?: ReactNode`: Custom composition: the parts below in place of the built-in toolbar and body, sharing the calendar's state.

Parts:
- `CalendarViewToolbar` (component): The toolbar: live-region title, prev / Today / next, the view switch (a phone switch below 576px) and actions. Props: { actions?: ReactNode } & ComponentProps<"div">.
- `CalendarMonth` (component): The month grid (role="grid") with lanes for chips and multi-day bars, "+N more" and keyboard roving. Takes div props.
- `CalendarMonthCompact` (component): The phone month: day buttons with up to three tone dots and the chosen day's events underneath. Takes div props.
- `CalendarWeek` (component): The time grid: day headings, the all-day row, the hour gutter, overlapping blocks, the now line and the selection ghost. Props: { mode?: "week" | "day" } & ComponentProps<"div">.
- `CalendarAgenda` (component): Days with events as sticky headings over 56px rows (time, tone bar, title, location); scrolls to today on mount. Props: { range?: { start: Date; end: Date } } & ComponentProps<"div">.
- `CalendarEventChip` (component): The month chip on its own: a tinted button with a 3px start bar in the event's tone. Props: { event: CalendarEvent; time?: ReactNode; tone?: Tone } & ComponentProps<"button">.
- `layoutDayEvents` (function): The overlap layout of one day: segments with start / end minutes and column, columns and span (greedy columns, each event stretching over the free columns to its right). Signature: (events: CalendarEvent[], day: Date) => CalendarDayLayout[].
- `getVisibleRange` (function): The first and last visible day of a view, both inclusive local midnights. Use it to fetch events for the screen. Signature: (view, date, weekStartsOn?, agendaDays?) => { start: Date; end: Date }.
- `DEFAULT_CALENDAR_VIEW_LABELS` (constant): The English strings, to spread under your own or translate once in UIProvider defaults. Type: CalendarViewLabels.

```tsx
import { useState } from "react"
import { Plus } from "lucide-react"
import { Button } from "@/components/ui/button"
import { CalendarView, type CalendarEvent } from "@/components/ui/calendar-view"

const appointments: CalendarEvent[] = [
  { id: "p1", title: "Consultation: Emma Carter", start: new Date(2026, 8, 24, 9, 0), end: new Date(2026, 8, 24, 10, 0), tone: "info", location: "Room 1" },
  { id: "p2", title: "Cleaning: Irene Vance", start: new Date(2026, 8, 24, 11, 30), end: new Date(2026, 8, 24, 12, 30), tone: "success" },
  { id: "p3", title: "Supplies delivery (UPS)", start: new Date(2026, 8, 24), end: new Date(2026, 8, 24), allDay: true },
]

export function Appointments() {
  const [events, setEvents] = useState(appointments)
  return (
    <CalendarView
      events={events}
      defaultDate={new Date(2026, 8, 24)}
      editable
      onEventChange={(event, change) =>
        setEvents((list) => list.map((e) => (e.id === event.id ? { ...e, ...change } : e)))
      }
      toolbarActions={<Button size="sm" leftIcon={<Plus />}>New appointment</Button>}
      labels={{
        more: (n) => `${n} more`,
        noEvents: "No appointments",
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/calendar-view (Markdown: https://wingo-ui.com/components/calendar-view.md)

#### Code Block (`code-block`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add code-block`

A syntax-highlighted code block that builds its entire theme from a single accent color.

Pick an accent to re-shade the whole block from that one color: keywords, strings, comments, selection and the highlighted-line wash are all tints of it. Hit the copy button to put the code on the clipboard and watch the icon spring into a check. Long lines scroll sideways inside the block, and the code area is focusable so arrow keys scroll it too.

npm: lucide-react, motion, prism-react-renderer
Wingo UI dependencies: ui-config

Props:
- `code: string`: The source code to render. Leading blank lines and trailing whitespace are trimmed.
- `language?: string` = "tsx": Prism language id, e.g. "tsx", "css", "json", "python". Also shown in the header when there is no filename. Bundled: markup, jsx, tsx, js, ts, css, json, python, go, rust, sql, yaml, graphql, swift, kotlin, cpp, markdown.
- `accent?: string` = "#F75001": Any hex color. The whole theme is shades of it: keywords take the accent itself, strings, numbers and functions are lighter or darker tints, and selection and highlighted lines get a soft wash of it.
- `mode?: "auto" | "dark" | "light"` = "auto": Color scheme. Auto follows the page theme (html dark/light class, data-theme, or OS preference). Pass dark or light to pin a palette: dark puts light tints of the accent on a dark surface, light flips the ramp.
- `filename?: string` = "": Filename or path shown on the left of the header. Falls back to the language id when empty or omitted.
- `size?: "sm" | "md" | "lg"` = "md": Code at 12 / 13 / 14px on 20 / 24 / 28px lines, with a 36 / 40 / 44px header.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the frame: 0, 12, 16 or 24px; full falls back to 24px.
- `background?: string` = "": Any CSS color for the framed surface. Empty uses the neutral surface of the mode (near black or near white). Token colors are tuned for 4.5:1 on those defaults, so pair a dark background with mode dark and a light one with mode light.
- `showFrame?: boolean` = true: Toggles the outer frame: background, border, rounded corners, and header. Turn off to render nothing but the highlighted code.
- `showHeader?: boolean` = true: Toggles the header bar. When hidden, the copy button floats over the top-right corner instead. Ignored when showFrame is off.
- `showLineNumbers?: boolean` = true: Toggles the line-number gutter.
- `showCopyButton?: boolean` = true: Toggles the copy-to-clipboard button.
- `wrap?: boolean` = false: Wraps long lines inside the block instead of scrolling sideways; line numbers stay on the first row of each line.
- `maxHeight?: number` = 0: Caps the block's height in pixels and scrolls the code inside it. 0 means no limit.
- `copyLabel?: string` = "Copy code": Accessible name of the copy button.
- `copiedLabel?: string` = "Copied": Accessible name of the copy button right after copying.
- `copyResetMs?: number` = 1800: How long the check stays on the copy button, in milliseconds.
- `highlightLines?: number[]`: Optional 1-based line numbers to highlight with a soft accent wash. Off when omitted.
- `className?: string`: Extra classes merged onto the root element (data-slot="code-block"). Use it for width and max-height; the code area scrolls inside.

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

export function Demo() {
  return (
    <CodeBlock
      code={`const greet = (name: string) => \`Hello, \${name}!\``}
      language="ts"
      accent="#F75001"
      filename="greet.ts"
      highlightLines={[1]}
      className="max-h-96 w-full max-w-xl"
    />
  )
}
```

Docs: https://wingo-ui.com/components/code-block (Markdown: https://wingo-ui.com/components/code-block.md)

#### Comment Thread (`comment-thread`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add comment-thread`

Discussions on a record: comments with replies, reactions, edit and delete, @mentions and a composer that sends optimistically with retry.

Write in the composer at the bottom and send with the arrow or Cmd/Ctrl+Enter (Enter adds a line; with sendOnEnter, Enter sends and Shift+Enter adds a line). The comment appears at once at 60% opacity with "Sending…", then fades to its time; if the request fails it shakes once and offers Retry and Discard. Type @ and a few letters for the people list: Up and Down move, Enter or Tab insert "@Anna Price ", Escape closes it. Press Up in the empty composer to edit your last comment. Reply opens an inline composer under the thread (Escape cancels, replying to a reply prefills the @name); Edit turns the text into a box with Save and Cancel (Cmd/Ctrl+Enter saves, Escape cancels, an empty text cannot be saved). Tap a reaction pill to toggle yours; the smiley opens the emoji row. The ⋯ menu has Edit, Copy text, Copy link and Delete, which asks first. "Show N more replies" unfolds older replies, the sort button flips oldest and newest first. On a phone every action is visible with a 44px target, the menu and the emoji row open as bottom sheets, and a long press on a comment opens its actions sheet.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, avatar, badge, button, dropdown-menu, empty-state, kbd, listbox, popover, skeleton, textarea, use-clipboard, use-controllable-state, use-locale, use-long-press, motion, relative-time, text-match, tones, ui-config

Props:
- `comments?: CommentData[]` = "": { id, author: { id, name, avatar?, badge? }, body, createdAt, editedAt?, replies?, reactions?: { emoji, count, reacted, users? }[], attachments?, pending?, failed?, deleted? }. Bodies are plain text; replies nest one level (deeper ones are flattened with the @name in front).
- `currentUser?: CommentAuthor`: You. Turns on the composer, Reply, reactions and the actions on your own comments. Without it the thread is read-only.
- `people?: CommentAuthor[]` = "": Who can be mentioned: @Name in bodies becomes a chip (yours is highlighted) and the composer suggests them after @.
- `reactions?: string[]` = "": The emoji row of the reaction picker. Default ["👍", "❤️", "😂", "🎉", "😮", "🙏"].
- `placeholder?: string` = "Write a comment…": The empty composer's hint. Replies use labels.replyPlaceholder(name).
- `variant?: "plain" | "bubble"` = "plain": plain: flat comments with a thread line to the replies, like GitHub. bubble: the name and text in a bubble, your own bubbles tinted with the tone, time and actions underneath.
- `size?: "sm" | "md"` = "md": Avatars 28 / 36px (replies 24 / 28px), text 13 / 14px. sm fits side panels.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Your own bubbles, your reactions, the send and save buttons.
- `color?: string` = "": Any CSS color; replaces the tone.
- `timeFormat?: "relative" | "time" | "date" | "datetime"` = "relative": "5 min. ago", "4:40 PM", "9/24/2026" or both. The full date is always in the tooltip.
- `showHeader?: boolean` = true: The title row with the count and the sort button.
- `composer?: "bottom" | "top" | "none"` = "bottom": Where the composer sits; top suits newest-first feeds. Needs currentUser and onSubmit.
- `stickyComposer?: boolean` = false: The composer sticks to the edge of the scroll container on a glass background and pads the safe area, for chat-like pages on phones. Set --comment-thread-surface to the background behind it and --comment-thread-bleed to reach the container's edges.
- `sort?: "oldest" | "newest"` = "oldest": Order of the top-level comments; replies are always oldest first. The header button flips it (onSortChange).
- `collapseRepliesAfter?: number` = 2: Shows the newest N replies and folds the older ones behind "Show N more replies".
- `loading?: boolean` = false: Skeleton comments with the real shape.
- `skeletonCount?: number` = 3: How many skeleton comments show while loading.
- `confirmDelete?: boolean` = true: Delete asks first in an alert dialog (a returned promise keeps it loading).
- `sendOnEnter?: boolean` = false: Chat style: Enter sends and Shift+Enter adds a line (touch keyboards keep Enter for new lines and show a Send key). By default Enter adds a line and Cmd/Ctrl+Enter sends.
- `locale?: string` = "": Locale for the times. Empty uses the UIProvider locale, then the browser's.
- `onSubmit?: (body: string, context: { parentId?: string; mentions: string[] }) => (void | Promise<unknown>)`: A new comment or reply. The optimistic row shows at once; a promise keeps it "Sending…" and a rejection marks it failed with Retry. Resolve with the saved comment's id so the row stays in place when it arrives in comments.
- `onEdit?: (id: string, body: string) => (void | Promise<unknown>)`: Saves an edit. A promise keeps Save loading; a rejection keeps the editor open with an error.
- `onDelete?: (id: string) => (void | Promise<unknown>)`: Deletes a comment after the confirmation. Mark it deleted to keep the placeholder above its replies.
- `onReact?: (id: string, emoji: string) => void`: Toggles the current user's reaction.
- `onRetry?: (id: string) => void`: Retry on a comment you marked failed yourself. Optimistic comments from onSubmit retry on their own.
- `onSortChange?: (sort: CommentThreadSort) => void`: The header sort button was pressed.
- `canEdit?: (comment: CommentData) => boolean`: Default: your own comments (needs onEdit).
- `canDelete?: (comment: CommentData) => boolean`: Default: your own comments (needs onDelete). Return true for moderators.
- `getLink?: (comment: CommentData) => string`: What Copy link copies. Default: the page URL with #comment-<id> (every comment has that id).
- `emptyState?: ReactNode`: Replaces the default <EmptyState size="sm" icon={<MessageSquare />} title={labels.empty} />.
- `composerProps?: Partial<CommentComposerProps>`: Extra props for the main composer: attachments, maxLength, autoFocus, submitLabel.
- `labels?: Partial<CommentThreadLabels>`: Every string, English by default (DEFAULT_COMMENT_THREAD_LABELS): title, reply, edit, delete, edited, save, cancel, send, sending, retry, discard, failed, deleted, showReplies(n), hideReplies, react, reactedBy(names, count), empty, deleteTitle, deleteConfirm, sortOldest, sortNewest, mention, actions, copyText, copyLink, newComment(name), replyPlaceholder(name)…
- `classNames?: Partial<Record<CommentThreadSlot, string>>`: header, title, count, sort, list, comment, avatar, main, author, time, body, bubble, attachments, reactions, footer, replies, composer.

Parts:
- `CommentItem` (component): One comment with its replies. Inside a CommentThread it gets the thread's actions; on its own it renders read-only. Props: { comment: CommentData; parentId?: string } & ComponentProps<"li">.
- `CommentComposer` (component): The composer on its own (a chat input, a review box): auto-growing box, @mention suggestions, Cmd/Ctrl+Enter or Enter to send, a counter with maxLength. A returned promise keeps the send button busy and the text until it resolves. The mention list opens above the box (suggestionsSide="bottom" for a composer at the top; the thread sets it for composer="top"). Props: { value?, defaultValue?, onValueChange?, onSubmit?(body, { mentions }), people?, user?, placeholder?, submitLabel?, autoFocus?, maxLength?, sendOnEnter?, attachments?, disabled?, size?, tone?, color?, onCancel?, onEditLast?, suggestionsSide?: "top" | "bottom", labels?, classNames? }.
- `CommentBody` (component): The plain-text renderer: line breaks kept, @mentions as chips, URLs as links (new tab, noopener). Never renders HTML. Props: { body: string; people?: CommentAuthor[]; currentUserId?: string }.
- `parseMentions` (function): Splits text into text, mention and link segments. getMentionIds(text, people) returns the mentioned ids. Signature: (text: string, people: CommentAuthor[]) => CommentSegment[].

```tsx
"use client"

import { useState } from "react"
import { CommentThread, type CommentAuthor, type CommentData } from "@/components/ui/comment-thread"

const anna: CommentAuthor = { id: "anna", name: "Anna Price", avatar: "/demo/ana-pop.jpg" }
const michael: CommentAuthor = { id: "michael", name: "Michael Hayes", avatar: "/demo/mihai-ionescu.jpg", badge: "Author" }

export function QuoteDiscussion() {
  const [comments, setComments] = useState<CommentData[]>([
    {
      id: "c1",
      author: michael,
      body: "Sent the revised quote with 5% off the annual plan. @Anna Price can you take a look?",
      createdAt: "2026-09-24T14:05:00",
      reactions: [{ emoji: "👍", count: 3, reacted: false, users: ["Jessica Dunn", "Ryan Martin", "Liam Brooks"] }],
    },
  ])

  const send = async (body: string, { parentId }: { parentId?: string }) => {
    // await api.post("/quotes/Q-2026-118/comments", { body, parentId })
    const saved: CommentData = { id: crypto.randomUUID(), author: anna, body, createdAt: new Date() }
    setComments((list) =>
      parentId
        ? list.map((c) => (c.id === parentId ? { ...c, replies: [...(c.replies ?? []), saved] } : c))
        : [...list, saved],
    )
    return saved.id
  }

  return (
    <CommentThread
      comments={comments}
      currentUser={anna}
      people={[anna, michael]}
      onSubmit={send}
      onEdit={(id, body) => setComments((list) => list.map((c) => (c.id === id ? { ...c, body, editedAt: new Date() } : c)))}
      onDelete={(id) => setComments((list) => list.map((c) => (c.id === id ? { ...c, deleted: true } : c)))}
      labels={{ title: "Discussion", empty: "No comments yet" }}
      placeholder="Write a comment…"
    />
  )
}
```

Docs: https://wingo-ui.com/components/comment-thread (Markdown: https://wingo-ui.com/components/comment-thread.md)

#### Contact card (`contact-card`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add contact-card`

A person or a company at a glance: avatar, role, status, call / email / WhatsApp buttons, tags, owner and last activity, in three layouts.

Tap Call, Email or WhatsApp to open the phone, the mail app or a WhatsApp chat (wa.me with the Romanian 40 prefix added to 07… numbers); an onCall / onEmail / onMessage handler replaces the link, for a softphone or an in-app composer, and the email and phone in the full card go through the same handlers. Tap the name (or anywhere on a linked card) to open the record: the card tints on hover and dips slightly while pressed (a row only tints), but neither dips nor darkens when the press lands on a button or link inside. The company, email, phone and website are underlined links of their own. The star saves the contact optimistically and rolls back, with a spoken error, when the request fails. The copy buttons next to email, phone and CUI copy the value and confirm with a check; they show on hover or keyboard focus of their row with a mouse and are always visible on touch. The ⋯ button opens the actions menu, a bottom sheet with the contact's name on phones. On narrow cards the buttons stack their icon over the label; in the row layout they appear on hover (always on touch), rows narrower than 30rem keep only the first one (Call), below 18rem none, and the row's ⋯ menu always lists every channel on top. Tab reaches the name link, the company link, the star, the menu, each contact button, then each field link and copy button, in reading order, with the focus ring drawn around the whole card for the name; Enter or Space activates; in the menu the arrows move and Escape closes it and returns focus to ⋯. Hover a round button for its label; long-press it on touch.

npm: lucide-react, motion
Wingo UI dependencies: avatar, badge, button, copy-button, dropdown-menu, favorite-button, skeleton, tag, tooltip, use-locale, motion, navigation, relative-time, tones, ui-config

Props:
- `contact: ContactData`: { id; kind?: "person" | "company"; name; avatar?; title?; company?: { name; href?; logo? }; email?; phone?; whatsapp?: string | boolean (true uses phone); website?; location?; cui?; status?: { label; tone?; icon? }; tags?: { label; tone?; color? }[]; owner?: { name; avatar? }; lastActivity?: { label; at; icon? }; fields?: ContactFact[]; href? }. Anything missing simply does not render.
- `layout?: "full" | "compact" | "row"` = "full": full: every part, for a record's side panel. compact: centered avatar, name, role, status and round buttons, for grids. row: one 56px line with icon buttons, for lists.
- `variant?: "elevated" | "outline" | "soft" | "ghost"` = "elevated": The card surface: a raised panel, a hairline frame, the flat gray tile or nothing (ghost, for rows inside a list group).
- `size?: "sm" | "md"` = "md": md: a 48px avatar and a 17px name in the full layout (64px in compact); sm one step smaller.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Card corners: none, 12px, 16px or 24px. Rows inside a list group use none.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the selected ring and the star when it is on.
- `color?: string` = "": Any CSS color for the selected ring and the star. Replaces the tone.
- `defaultFavorite?: boolean` = false: The star's starting state when uncontrolled. Setting it (or favorite, onFavoriteChange) shows the star.
- `favorite?: boolean`: Controlled star.
- `onFavoriteChange?: ((favorite: boolean, contact: ContactData) => void | Promise<unknown>)`: Called when the star is toggled. Return a promise to keep it optimistic while pending; a rejection rolls it back and announces labels.favoriteError.
- `showFavorite?: boolean` = false: Shows the star even without favorite props (an uncontrolled star that starts off).
- `selected?: boolean` = false: A 2px ring in the tone and data-selected, for the picked contact in a grid (drawn inside the edge on rows, so a list group never clips it).
- `loading?: boolean` = false: Skeletons in the layout's shape (aria-busy); the content fades in when it turns false.
- `showFields?: boolean` = true: Full layout: the rows for email, phone, website, location and CUI, then contact.fields.
- `showTags?: boolean` = true: Full layout: the tag row.
- `showActivity?: boolean` = true: Full layout: the footer with the owner and the last activity (a <time>, relative to now).
- `copyable?: boolean` = true: Copy buttons on email, phone, CUI and facts with copyValue: on hover or focus with a mouse, always on touch.
- `channels?: ("call" | "email" | "whatsapp" | "sms" | "website")[]` = "[\"call\", \"email\", \"whatsapp\"]": Which contact buttons show, in order. A channel without data (no phone, no email) is hidden; with none left the row disappears.
- `onCall?: (contact: ContactData) => void`: Replaces the tel: links of the Call button and the phone field (a softphone).
- `onEmail?: (contact: ContactData) => void`: Replaces the mailto: links of the Email button and the email field (an in-app composer).
- `onMessage?: (contact: ContactData) => void`: Replaces the wa.me and sms: links.
- `onChannelSelect?: (channel: ContactChannel, contact: ContactData, event: ContactChannelEvent) => void`: Runs first for every contact button, every channel picked in the row menu and the email / phone / website links of the fields. event.preventDefault() stops the link and the handler (tracking, a confirmation).
- `actions?: MenuEntry[]`: The ⋯ menu (Edit, Add note, Merge, Delete with tone "danger"), a bottom sheet on phones. Rows put the channels on top.
- `locale?: string` = "": Formats the last activity time ("45 min. ago"). Empty uses the UIProvider locale, then the browser's.
- `now?: Date | number`: The reference time for the relative activity time. Defaults to a live clock that ticks every minute.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders the name, company and fact links through your router's Link. Defaults to the LinkProvider's, else <a>.
- `labels?: Partial<ContactCardLabels>` = "DEFAULT_CONTACT_CARD_LABELS": call, email, whatsapp, sms, website, phone, location, copy, copied, favorite, favoriteAdd, favoriteRemove, favoriteError, actions, cancel, owner, lastActivity, cui, noActivity, tags (the tag list's name), actionLabel(action, name) ("Call Emma Carter"), copyField(field) ("Copy Email").
- `classNames?: Partial<Record<"media" | "heading" | "name" | "title" | "company" | "status" | "favorite" | "menu" | "actions" | "action" | "fields" | "field" | "tags" | "footer" | "owner" | "activity", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the <article>, merged last.

Parts:
- `ContactActions` (component): The contact buttons alone, for other layouts: contact, channels, layout ("tiles" labelled buttons in equal columns, "icons" round buttons with tooltips), variant (soft), tone, radius, onCall / onEmail / onMessage / onChannelSelect, labels. Props: ContactActionsProps.
- `whatsappHref` (function): https://wa.me/40745123456 from "0745 123 456"; international numbers are kept as given, text becomes ?text=. Signature: (phone: string, text?: string) => string.
- `DEFAULT_CONTACT_CARD_LABELS` (constant): The English strings. Spread it and override a few keys, or pass a full translated set through labels. Type: ContactCardLabels.
- `telHref` (function): tel:0745123456 from "0745 123 456", tel:+40745123456 from "+40 745 123 456": spaces and punctuation dropped, a leading + kept. Signature: (phone: string) => string.

```tsx
import { Pencil, PhoneCall, Trash2 } from "lucide-react"
import { ContactCard, type ContactData } from "@/components/ui/contact-card"

const emma: ContactData = {
  id: "c-emma",
  name: "Emma Carter",
  title: "Head of Procurement",
  company: { name: "Northwind Tech Inc.", href: "/clients/c01" },
  email: "emma.carter@northwindtech.com",
  phone: "+1 415 555 0132",
  whatsapp: true,
  location: "San Francisco, CA",
  status: { label: "Active client", tone: "success" },
  tags: [{ label: "Decision maker" }, { label: "2027 budget", tone: "info" }],
  owner: { name: "Anna Price", avatar: "/demo/ana-pop.jpg" },
  lastActivity: { label: "Call", at: new Date(2026, 8, 24, 15, 55), icon: <PhoneCall /> },
  href: "/contacts/emma-carter",
}

export function ContactPanel({ onFavorite }: { onFavorite: (favorite: boolean) => Promise<unknown> }) {
  return (
    <ContactCard
      contact={emma}
      defaultFavorite={false}
      onFavoriteChange={(favorite) => onFavorite(favorite)}
      actions={[
        { label: "Edit", icon: <Pencil /> },
        { type: "separator" },
        { label: "Delete contact", icon: <Trash2 />, tone: "danger" },
      ]}
      locale="en-US"
      labels={{ owner: "Account owner" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/contact-card (Markdown: https://wingo-ui.com/components/contact-card.md)

#### Countdown (`countdown`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add countdown`

Time left until a moment, as rolling digit blocks, inline in a sentence or in words, with a finish callback and done content.

Nothing to press: it counts down on its own and each changed digit rolls into place on a spring (or crossfades, or simply swaps with reduced motion). Leading zero units drop out as time passes, so a launch two days away shows days while the last hour shows only minutes and seconds. At zero onComplete fires once, the done content springs in and screen readers hear the finish once; the ticking itself is never announced, a sentence updated once a minute is read instead. A tab that slept jumps straight to the right value. In the playground pick when the launch is (in 10 s, in 2 days, in 45 days or already past) to watch it tick, finish, or render done.

npm: motion
Wingo UI dependencies: animated-counter, relative-time, use-locale, motion, number-format, tones, ui-config

Props:
- `to: Date | number | string`: The moment to count down to: a Date, ms since epoch or an ISO string. An invalid value renders the done state and logs nothing. Changing it recomputes at once and re-arms onComplete. The playground sets it through the buttons under the card.
- `now?: Date | number`: Pins the clock (demos, screenshots, server rendering). Left out, the live clock ticks exactly on the unit boundaries of `to` (and re-syncs when the tab wakes); until it is known after hydration the digits render as -- at their final width.
- `units?: CountdownUnit[] | "auto"` = "auto": auto shows days, hours, minutes and seconds and drops leading zero units (never "0 days"), always keeping the last two. An explicit list like ["hours", "minutes"] folds the rest into the largest unit (52 hours).
- `variant?: "blocks" | "inline" | "text"` = "blocks": blocks: a tile per unit with its label under it. inline: 2d 04:12:09 in the flow of a sentence. text: words, "in 2 days and 4 hours", built from labels.
- `size?: "sm" | "md" | "lg"` = "md": blocks: 40 / 56 / 80px tiles with 20 / 28 / 44px numerals (lg shrinks to 36px numerals below 400px so four units fit a 360px phone). inline 13 / 15 / 20px, text 13 / 14 / 16px.
- `animation?: "roll" | "fade" | "none"` = "roll": roll: odometer wheels from AnimatedCounter. fade: each changed digit crossfades in place. none: plain text. Reduced motion always behaves as none.
- `tileVariant?: "soft" | "solid" | "outline" | "elevated"` = "soft": The look of the tiles in blocks: a tint, a solid fill, a hairline outline, or a raised card surface.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color of the tiles and digits. neutral is a quiet foreground tint. It never changes on its own near the end; style [data-urgent] if you want that.
- `color?: string` = "": Any CSS color. Replaces the tone; text on a solid tile turns black or white by lightness.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the tiles and the done box, scaled with the size (md is 12 / 16 / 24px).
- `showLabels?: boolean` = true: Unit names under the blocks; in inline the letter after the days (2d). Without labels, blocks show the separator between tiles.
- `showSeconds?: boolean` = true: false hides seconds and ticks once a minute: calmer, and cheaper on long lists of cards.
- `padStart?: boolean` = true: 04 instead of 4 for hours, minutes and seconds. Days are never padded and grow past 99 without a cap.
- `separator?: string` = ":": Between units in inline, and between tiles in blocks when showLabels is off. An empty string in inline gives every unit its letter: 2d 4h 12m 09s.
- `precision?: number` = 2: text variant: how many units the phrase names, largest first ("in 3 days and 4 hours").
- `align?: "start" | "center" | "end"` = "center": blocks: where the row sits in its container (the blocks root is full width).
- `completedContent?: ReactNode` = "": Replaces the digits when time is up, like "The offer has ended", springing in on a bouncy scale. Without it the digits stay at zero. Try it with "in 10 s".
- `locale?: string` = "": Locale for the digits and the plural rules your labels use. Empty follows UIProvider, then the page.
- `onComplete?: () => void`: Fires once on the transition to zero while mounted, on time even when seconds are hidden. A to already past at mount renders done without calling it.
- `interval?: number` = 1000: ms between ticks (at least 1000), aligned to the target so the last tick lands exactly at zero. With showSeconds off the default is 60000.
- `labels?: Partial<CountdownLabels>`: Every string, English by default (DEFAULT_COUNTDOWN_LABELS): days / hours / minutes / seconds (count, formatted) => "3 days", names { days: (count) => "days" } under the blocks, short { days: "d", ... }, sentence(text, parts) => "3 days and 4 hours left", done "Time's up", and "and", in "in".
- `classNames?: Partial<Record<"units" | "unit" | "value" | "label" | "separator" | "done", string>>`: Extra classes for the inner parts: the row, each unit, the tile or digits, the label, the separator, the done content.
- `className?: string`: Extra classes for the root, merged last. The root carries data-state (idle, running, done) and data-urgent in the last minute.

Parts:
- `useCountdown` (hook): The clock behind the component for custom layouts: { days, hours, minutes, seconds, totalMs, done }, recomputed from the absolute time on every tick and on waking, with ticks aligned to the target. totalMs (rounded up to the interval) is null until the clock is known. Signature: (to: Date | number | string, options?: { now?; interval? = 1000; onComplete?; units? }) => CountdownParts.
- `getCountdownParts` (function): The pure split of the time left into units: the largest unit carries the overflow, the smallest rounds up. Signature: (to, now, units?) => CountdownParts.
- `DEFAULT_COUNTDOWN_LABELS` (constant): The English strings, to spread under a translation. Type: CountdownLabels.

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

export function LaunchCountdown() {
  return (
    <Countdown
      to="2026-09-26T20:52:09+03:00"
      size="lg"
      completedContent="Acme CRM 4.0 is live"
      onComplete={() => toast.success("The launch has started")}
      // labels: plural functions per unit, e.g. days: (count, formatted) => `${formatted} ${count === 1 ? "day" : "days"}`
    />
  )
}
```

Docs: https://wingo-ui.com/components/countdown (Markdown: https://wingo-ui.com/components/countdown.md)

#### Description List (`description-list`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add description-list`

The key-value grid of every detail page: client details, invoice summaries and profiles, with copy buttons, skeletons and iOS rows.

Read the details in document order: label above value on phones and in narrow cards, one to three columns once the container is wide enough (it follows its container, not the window). Hover a row with a mouse or Tab into it and a copy button appears next to a copyable value; click it or press Enter and the icon turns into a check while the tooltip says Copied. On a phone the copy buttons are always visible and have a 44px hit area. Tab only stops on real controls (copy buttons, actions, inline edits). While loading, values are skeleton bars that crossfade into the real text. The grouped variant reads like iOS settings: label left, value right, long values move under the label on narrow screens.

npm: motion
Wingo UI dependencies: copy-button, skeleton, motion, ui-config

Props:
- `items?: DescriptionListItem[]`: { id?, label, value, description?, icon?, copy?: boolean | string, span?: 1 | 2 | 3 | "full", mono?, action?, hidden? }. copy: true copies a string or number value, a string copies that string, false opts out of copyable. span clamps to columns; hidden items are skipped.
- `columns?: 1 | 2 | 3` = 2: Columns once the container is at least 32rem (2) or 48rem (3) wide. Always one column below 32rem, so it stacks on phones and in narrow cards.
- `layout?: "auto" | "stacked" | "inline"` = "auto": stacked: label above value. inline: a label column and a value column (from 24rem of container width, so phones stack). auto: inline when there is one column and the container is at least 40rem wide, stacked otherwise.
- `labelWidth?: number` = 160: Width of the label column in px for the inline layout. Never more than 35% of the row.
- `variant?: "plain" | "divided" | "surface" | "grouped"` = "divided": plain: no lines. divided: hairlines between rows, per column. surface: the whole list, header included, on a raised panel. grouped: iOS inset rows on a panel, label left and value right, 44px rows (ignores columns and layout).
- `size?: "sm" | "md" | "lg"` = "md": Label 12 / 13 / 14px, value 13 / 14 / 15px, row padding 8 / 12 / 16px.
- `copyable?: boolean` = false: Every item with a string or number value gets a copy button. Items opt out with copy: false; React element values need copy set to a string.
- `copyLabel?: string` = "Copy": The copy button's tooltip and aria-label, followed by the item label: "Copy CUI".
- `copiedLabel?: string` = "Copied": Tooltip and screen reader announcement after a copy.
- `emptyValue?: ReactNode` = "–": Shown, muted, for null, undefined, false and "" values. Empty values are never copyable.
- `loading?: boolean` = false: Values become skeleton bars (widths vary by row, the same on the server and in the browser) and the <dl> gets aria-busy. With no items, skeletonCount fake rows show. Skeletons crossfade into the values.
- `skeletonCount?: number` = 6: Rows to fake while loading before any items exist.
- `title?: ReactNode` = "": The header title. With a title the root becomes a <section> labelled by it.
- `description?: ReactNode` = "": A muted line under the title.
- `titleAs?: "h2" | "h3" | "h4"` = "h3": Heading level of the title, to fit the page outline.
- `actions?: ReactNode`: Buttons at the end of the header, like an Edit button.
- `children?: ReactNode`: Parts instead of items. DescriptionItem is one row: label, value (or children), description, icon, copy, span, mono, action, hidden; it reads size, variant and copy labels from the list, and without a label its children render as they are. Inside it, DescriptionTerm is the <dt> with the label look and an optional icon, and DescriptionDetails the <dd> with the value look (muted, end-aligned and tabular in grouped rows).
- `classNames?: Partial<Record<"header" | "title" | "description" | "actions" | "body" | "grid" | "item" | "term" | "icon" | "details" | "value" | "hint" | "copy" | "action" | "skeleton", string>>`: Extra classes for the inner parts. grid is the <dl>, item the row <div>, term the <dt>, details the <dd>, copy the copy button.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { Pencil } from "lucide-react"
import { Button } from "@/components/ui/button"
import { DescriptionList, type DescriptionListItem } from "@/components/ui/description-list"

const CLIENT: DescriptionListItem[] = [
  { label: "Company", value: "Tech Solutions Inc." },
  { label: "Tax ID", value: "12-3456789", copy: true, mono: true },
  { label: "Registration no.", value: "DE-5512345", mono: true },
  { label: "Address", value: "233 S Wacker Dr, Chicago, IL 60606", span: 2 },
  { label: "IBAN", value: "GB29 NWBK 6016 1331 9268 19", copy: "GB29NWBK60161331926819", mono: true },
  { label: "Balance", value: "$12,480.00" },
]

export function ClientDetails({ loading }: { loading: boolean }) {
  return (
    <DescriptionList
      title="Client details"
      description="Billing details"
      actions={<Button variant="soft" size="sm" leftIcon={<Pencil />}>Edit</Button>}
      items={CLIENT}
      loading={loading}
    />
  )
}
```

Docs: https://wingo-ui.com/components/description-list (Markdown: https://wingo-ui.com/components/description-list.md)

#### Diff Viewer (`diff-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add diff-viewer`

Shows what changed between two texts: split or unified, word highlights, collapsed context, syntax colors and jumps between changes.

Read the change at a glance: removed lines are tinted red with a minus, added lines green with a plus, and the words that changed inside a line are marked. Wide screens show the two versions side by side; phones (and the server render) show one unified column, and the switch in the toolbar, or the ⋯ menu on a phone (a bottom sheet), flips between them with a short crossfade. Long runs of unchanged lines fold into a row that says how many lines hide there: tap it to show them all, or use the arrows beside it to reveal 20 at a time; the new rows fade in. The chevron buttons, or Alt+Down and Alt+Up while focus is anywhere inside the viewer, scroll to the next or previous change, focus it and flash it briefly (no flash with reduced motion), wrapping around at the ends; a screen reader hears Change 2 of 5. The ⋯ menu copies either version and toggles line wrapping, ignoring whitespace and ignoring case; the copy buttons in the column headers do the same per side. Lines scroll sideways inside the viewer with the line numbers pinned, the body scrolls with the keyboard once focused, and every changed line carries a spoken added or removed label.

npm: diff, prism-react-renderer, motion, lucide-react
Wingo UI dependencies: badge, button, copy-button, dropdown-menu, segmented-control, tooltip, use-clipboard, use-controllable-state, use-media-query, motion, ui-config

Props:
- `oldValue: string` = "# Services agreement no. 118/2026\nThe parties: Acme Software Inc., Chicago, Tax ID 40-1122334, as the Provider,\nand Tech Solutions Inc., Tax ID 12-3456789, as the Client.\n\n## Art. 4. Scope of the agreement\nThe Provider licenses, sets up and maintains the Acme CRM platform\nfor 25 users, as listed in Appendix 1.\nServices are delivered remotely, on business days, between 9:00 AM and 6:00 PM.\n\n## Art. 5. Payment\nMonthly fee: $4,990 plus sales tax\nThe Client pays each invoice within 15 days of receiving it.\nPayment is made by bank transfer or in cash at the Provider's office.\nLate payment accrues a penalty of 0.1% per day of the amount due, capped at the value of the overdue invoice.\n\n## Art. 6. Term\nThe agreement runs for 12 months, starting on the date it is signed.\nThe agreement renews automatically for further 12-month periods unless either party terminates it in writing.\nNotice of termination is given at least 30 days before expiry.\n\n## Art. 7. Confidentiality\nThe parties keep confidential the information received while performing the agreement.\nThe obligation stays in force for 2 years after the agreement ends.\nPublic information and information required by a competent authority are not confidential.\n\n## Art. 8.  Force majeure\nForce majeure releases the party that invokes it from liability, as provided by law.\nThe affected party notifies the other party within 5 days of the event.\n\n## Art. 9. Disputes\nDISPUTES are settled amicably or, failing that, by the courts of Cook County, Illinois.\n\n## Art. 10. Final provisions\nThis agreement was signed in two copies, one for each party.\n": The original text. Line endings are normalized (CRLF, LF), text with NUL bytes shows a binary notice, and inputs above 2,000 lines compare in idle time behind a skeleton.
- `newValue: string` = "# Services agreement no. 118/2026\nThe parties: Acme Software Inc., Chicago, Tax ID 40-1122334, as the Provider,\nand Tech Solutions Inc., Tax ID 12-3456789, as the Client.\n\n## Art. 4. Scope of the agreement\nThe Provider licenses, sets up and maintains the Acme CRM platform\nfor 40 users, as listed in Appendix 1.\nServices are delivered remotely, on business days, between 9:00 AM and 6:00 PM.\n\n## Art. 5. Payment\nMonthly fee: $6,490 plus sales tax\nThe Client pays each invoice within 30 calendar days of the issue date,\nby bank transfer to account 4839 2017 5 (routing 021000021) at Chase.\nLate payment accrues a penalty of 0.1% per day of the amount due, capped at the value of the overdue invoice.\n\n## Art. 6. Term\nThe agreement runs for 12 months, starting on the date it is signed.\nThe agreement renews automatically for further 12-month periods unless either party terminates it in writing.\nNotice of termination is given at least 30 days before expiry.\n\n## Art. 7. Confidentiality\nThe parties keep confidential the information received while performing the agreement.\nThe obligation stays in force for 2 years after the agreement ends.\nPublic information and information required by a competent authority are not confidential.\n\n## Art. 8. Force majeure\nForce majeure releases the party that invokes it from liability, as provided by law.\nThe affected party notifies the other party within 5 days of the event.\n\n## Art. 9. Disputes\nDisputes are settled amicably or, failing that, by the courts of Cook County, Illinois.\n\n## Art. 10. Final provisions\nThis agreement was signed in two copies, one for each party.\nAppendices 1 and 2 are an integral part of the agreement.\n": The changed text.
- `oldTitle?: ReactNode` = "Agreement v3 · Sep 12, 2026": The original's name above its column (split) or first in the header (unified). Empty shows labels.original ("Original").
- `newTitle?: ReactNode` = "Agreement v4 · Sep 24, 2026": The changed version's name. Empty shows labels.modified ("Changed").
- `defaultView?: "auto" | "split" | "unified"` = "auto": The starting view. auto is unified below 768px and on the server, split from 768px. Use view and onViewChange to control it.
- `view?: "auto" | "split" | "unified"`: Controlled view.
- `onViewChange?: (view: "split" | "unified") => void`: Called when the person switches the view in the toolbar or the ⋯ menu.
- `granularity?: "word" | "char" | "none"` = "word": Highlights inside a changed line pair: whole words, single characters, or none. Pairs that share 40% of their text or less get the line tint only.
- `contextLines?: number` = 3: Unchanged lines kept around each change; longer unchanged runs fold into an expander row. -1 shows every line.
- `lineNumbers?: boolean` = true: The old and new line number gutters. They stay pinned while long lines scroll sideways.
- `wrap?: boolean` = false: Long lines wrap instead of scrolling sideways. The ⋯ menu toggles it too; a new prop value resets it.
- `ignoreWhitespace?: boolean` = false: Lines that differ only in spaces or tabs count as unchanged (and a missing final newline is ignored). Also in the ⋯ menu.
- `ignoreCase?: boolean` = false: Lines that differ only in upper and lower case count as unchanged. Also in the ⋯ menu.
- `language?: string` = "": A Prism language for syntax colors (tsx, jsx, ts, js, json, yaml, markdown, css, sql, python, go...). Colors come from the tone tokens, so both themes read well. Empty keeps plain text.
- `showStats?: boolean` = true: The +12 −3 badges in the toolbar (spoken as 12 additions, 3 deletions).
- `toolbar?: boolean` = true: The toolbar with the stats, the view switch, previous / next change and the ⋯ menu. Alt+Up / Alt+Down keep working without it.
- `size?: "sm" | "md"` = "md": Mono text 12px on 20px lines, or 13px on 22px lines.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the panel: 0, 12, 16 or 24px (full falls back to lg).
- `maxHeight?: number` = 560: Height cap in px; the body scrolls inside it with a sticky header. 0 lets the viewer grow with its content.
- `onLineClick?: (line: DiffLine, side: "old" | "new") => void`: Turns the line numbers into buttons, e.g. to comment on a line. DiffLine is { type: "added" | "removed" | "unchanged" | "collapsed"; oldNumber?; newNumber?; content; parts?; hidden?; noNewline? }. Unified rows with both numbers report the side clicked.
- `renderGutter?: (line: DiffLine, side: "old" | "new") => ReactNode`: An extra cell in each gutter, after the numbers: comment counts, blame avatars, coverage marks.
- `setApi?: (api: DiffViewerApi) => void`: Receives { nextChange(), previousChange(), expandAll(), collapseUnchanged() } once after mount; the object keeps its identity.
- `labels?: Partial<DiffViewerLabels>`: Every visible and spoken string, English by default (DEFAULT_DIFF_VIEWER_LABELS): split, unified, view, nextChange, previousChange, more, cancel, expand(count), expandUp(count), expandDown(count), added, removed, noChanges, copyOld, copyNew, copied, copyFailed, wrap, ignoreWhitespace, ignoreCase, stats(stats), changes(count), changeOf(index, total), caption(old, new, stats), original, modified, computing, noNewline, lineEndingsOnly, binary, line(n).
- `classNames?: Partial<Record<"toolbar" | "header" | "title" | "body" | "table" | "row" | "number" | "sign" | "content" | "word" | "collapsed" | "empty", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the panel, merged last.

Parts:
- `computeDiff` (function): The framework-free diff the viewer uses: { rows: DiffRow[], stats: { added, removed, changed }, blocks, lineEndingsOnly, binary }. Rows are unchanged pairs, change pairs (removed left, added right, with word parts) and collapsed runs. Signature: (oldValue: string, newValue: string, options?: { granularity?, ignoreWhitespace?, ignoreCase?, contextLines? }) => DiffResult.

```tsx
import { DiffViewer } from "@/components/ui/diff-viewer"

const v3 = `Art. 5. Payment
The Client pays each invoice within 15 days of receiving it.
Payment is made by bank transfer.`

const v4 = `Art. 5. Payment
The Client pays each invoice within 30 calendar days of the issue date,
by bank transfer to account 4839 2017 5 at Chase.`

export function ContractChanges() {
  return (
    <DiffViewer
      oldValue={v3}
      newValue={v4}
      oldTitle="Agreement v3 · Sep 12, 2026"
      newTitle="Agreement v4 · Sep 24, 2026"
      labels={{ split: "Side by side", noChanges: "The versions match" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/diff-viewer (Markdown: https://wingo-ui.com/components/diff-viewer.md)

#### File List (`file-list`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-list`

Attachments and documents as rows, preview tiles or chips, with type icons, photo thumbnails, upload progress, selection and file actions.

Click or tap a file to preview it (photos open in place in the demo, documents open their url in a new tab by default); the row tints on hover and press. Photos fade in as they load, and a picture that fails falls back to its type tile. On desktop the download button sits at the end of each row and the ⋯ menu (shown on hover or focus, always on touch) holds the extra actions and Delete, which asks first in an alert dialog and fades the row while it runs; right click opens the same menu. When the list is narrower than 448px (a phone, a sidebar card) download moves into the ⋯ menu and uploaders show as a face only; on a phone the menu opens as a bottom sheet, and a long press opens it too. Uploading files show a thin progress bar with "64% · 2,4 of 3,8 MB" and a cancel ×; processing shows a moving bar; a failed upload shows its reason in red with Retry and remove; when an upload finishes its progress crossfades into the size and time with a quick check mark. With selectionMode="multiple" each file gets a checkbox: click it, Shift + click for a range, or long press on touch; while something is selected a click on a file toggles it. Keyboard: Tab reaches each file and its buttons, Up / Down (and Left / Right in the grid and chips) move between files, Home / End jump, Page Up / Page Down move by 10, Enter previews, Space toggles selection, Shift + Space or Shift + arrows extend it, Ctrl / Cmd + A selects all, Escape clears, Delete or Backspace deletes the focused file (with the confirm), Shift + F10 or the Menu key opens its menu (from the file or any of its buttons). Files enter and leave on a soft spring; reduced motion turns movement into fades.

npm: lucide-react, motion
Wingo UI dependencies: alert-dialog, avatar, button, checkbox, dropdown-menu, empty-state, file-types, motion, progress, relative-time, skeleton, tones, ui-config, use-locale, use-long-press, use-selection

Props:
- `files?: FileItem[]`: { id, name, size?, type?, url?, thumbnailUrl?, previewUrl?, uploadedAt?, uploadedBy?: { name, avatar? }, status?: "done" | "uploading" | "processing" | "error" | "idle" | "canceled", progress? (0..1), error?, description?, disabled? }. W2 FileUpload's UploadFile[] fits as it is. FileListItem ({ file, index? } & div props) renders one file on its own, as a plain row that opens its url. Unknown sizes are left out of the meta line; heic and tiff never try to render.
- `layout?: "list" | "grid" | "compact"` = "list": list: rows with a thumb, name, meta and actions. grid: preview tiles (4:3 photos or a big type tile) in auto-fill columns of at least 10rem, 2 columns on a phone. compact: 40px chips that wrap, for email attachments.
- `size?: "sm" | "md"` = "md": List rows 44 / 56px with 32 / 40px thumbs and a 13 / 14px name.
- `variant?: "plain" | "surface" | "separated"` = "surface": surface: one raised panel with hairlines (raised tiles and chips in the other layouts); plain: rows with hairlines and no container (flat gray tiles, tinted chips); separated: a panel per file (outlined tiles and chips).
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Panel and tile corners: 0 / 12 / 16 / 24px; previews inside a tile follow at the radius minus the padding. Chips are pills from md up.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selection checkbox, the selected ring on tiles and chips, and the upload progress fill.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `showThumbnails?: boolean` = true: Photo previews for images (thumbnailUrl, then previewUrl, then url). Off shows the colored type tile for every file.
- `showMeta?: boolean` = true: The size · time · uploader line under the name. Upload progress and errors show either way.
- `timeFormat?: "relative" | "time" | "date" | "datetime"` = "relative": How uploadedAt reads: "2 days ago", "4:40 PM", "9/22/2026" or both. Relative text waits for the browser, so the server prints the date and time.
- `actionsVisibility?: "hover" | "always"` = "hover": The ⋯ button: shown on hover and focus (always on touch screens), or always.
- `confirmDelete?: boolean` = true: Delete asks first in an alert dialog. Off deletes right away (email attachments).
- `selectionMode?: "none" | "multiple"` = "none": multiple adds a checkbox per finished file, Shift ranges, Ctrl / Cmd + A and Escape, and long press to select on touch. Uploading and failed files cannot be selected.
- `loading?: boolean` = false: Skeletons in the shape of the layout (rows, tiles or chips) instead of the files, with aria-busy.
- `skeletonCount?: number` = 3: How many skeletons show while loading.
- `locale?: string` = "": Sizes ("2.4 MB") and times ("2 days ago"). Empty uses the UIProvider locale, then the browser's. The demo falls back to en-US.
- `onPreview?: (file: FileItem, index: number) => void`: Clicking a file or pressing Enter on it. Without it a file with a url opens in a new tab.
- `onDownload?: (file: FileItem) => void`: The download action. Without it the download button is a link to the url with the download attribute.
- `onDelete?: (file: FileItem) => (void | Promise<unknown>)`: Shows Delete in the ⋯ menu (and the Delete key). A returned promise fades the row to 50% until it settles; afterwards focus moves to the next file. Also removes a failed upload (without asking).
- `onCancel?: (file: FileItem) => void`: The × on uploading, waiting and processing files; also removes a failed upload when there is no onDelete.
- `onRetry?: (file: FileItem) => void`: Retry on failed uploads.
- `getActions?: (file: FileItem) => MenuEntry[]`: Extra ⋯ entries in the W1 MenuEntry shape (Rename, Move, Copy link), above Delete. In compact chips it turns the trailing button into a ⋯.
- `selectedKeys?: string[]`: The selected file ids (controlled). Pair with onSelectedKeysChange.
- `defaultSelectedKeys?: string[]` = "[]": The initial selection when uncontrolled.
- `onSelectedKeysChange?: (keys: string[]) => void`: Every selection change, in display order.
- `emptyState?: ReactNode`: Shown when files is empty. Defaults to <EmptyState size="sm" preset="empty" icon={<Paperclip />} /> with labels.empty.
- `labels?: Partial<FileListLabels>`: Every string, merged over DEFAULT_FILE_LIST_LABELS: preview, download, delete, cancel, retry, remove, actions and select ({name}), uploading ({ percent, loaded, total }) => string, processing, queued, canceled, failed, uploaded, deleteTitle (name) => string, deleteDescription, deleteConfirm, deleteCancel, sheetTitle, sheetCancel, empty, emptyDescription, loading, kinds (screen reader names per file kind).
- `classNames?: Partial<Record<"item" | "main" | "select" | "thumb" | "body" | "name" | "meta" | "description" | "progress" | "error" | "actions" | "empty" | "skeleton", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root (the panel, grid or chip row).

```tsx
import { useState } from "react"
import { FileList, type FileItem } from "@/components/ui/file-list"

const initial: FileItem[] = [
  { id: "f1", name: "Invoice 2026-0412.pdf", size: 253952, url: "/files/invoice-2026-0412.pdf", uploadedAt: "2026-09-22T11:20:00", uploadedBy: { name: "Olivia Bennett" } },
  { id: "f2", name: "Sales report Q3 2026.xlsx", size: 1258291, url: "/files/report-q3.xlsx", uploadedAt: "2026-09-24T10:12:00", uploadedBy: { name: "Liam Walker" } },
  { id: "f3", name: "Admin ID scan.pdf", size: 3984589, status: "uploading", progress: 0.64 },
]

export function ClientDocuments() {
  const [files, setFiles] = useState(initial)
  const remove = (file: FileItem) => setFiles((prev) => prev.filter((f) => f.id !== file.id))
  return (
    <FileList
      files={files}
      locale="en-US"
      onDelete={async (file) => {
        await fetch(`/api/files/${file.id}`, { method: "DELETE" })
        remove(file)
      }}
      onCancel={remove}
      getActions={(file) => [{ label: "Copy link", onSelect: () => navigator.clipboard.writeText(file.url ?? "") }]}
      labels={{ deleteTitle: (name) => `Delete “${name}” for everyone?` }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/file-list (Markdown: https://wingo-ui.com/components/file-list.md)

#### File manager (`file-manager`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-manager`

The documents of a company or a record: folders and files in a grid or a list, with a folder tree, uploads, moves, renames and bulk actions.

Click a file or a folder to select it, Cmd or Ctrl + click to add or remove one, Shift + click for a range, tick the checkbox that appears on hover, or click empty space to clear the selection; with anything selected the toolbar turns into the bulk bar (Move, Download, Delete, Select all). Double-click (or Enter) opens: a folder slides in, an image opens in the lightbox with the folder's other images, any other file goes to onOpen or its url in a new tab. Right-click or the ⋯ button opens the menu (Open, Rename, Move to, Download, your own entries, Delete); right-click on empty space offers New folder, Upload and Select all. Rename with F2, the menu or a slow second click on the name: the base name is selected, Enter saves, Escape cancels, and a rejected promise shows its message under the field. Drag files (the whole selection comes along) onto a folder, a crumb or a folder in the tree to move them; a folder never drops into itself, and the drag card shows a stop sign over a refused target. Drop files from the desktop anywhere on it to upload into the open folder, or onto a folder tile to upload there; pasting files uploads too, and the uploads panel in the bottom corner shows progress and rejected files, folds away and closes once nothing runs. Search looks through every folder, lists the results with their path and marks the matched letters. With the keyboard the files are one Tab stop: arrows move (Up and Down by a row of tiles), Home, End, Page Up and Page Down jump, letters jump to a name, Space toggles, Shift + arrows extend, Cmd or Ctrl + A selects all, Escape clears, Delete asks and removes, Backspace or Alt + Up goes to the parent folder, Shift + F10 opens the menu, and Cmd or Ctrl + Shift + N makes a folder from anywhere inside. On a phone it starts as a list under the folder's name as a large title with a back link: a tap opens, a long press starts selecting (checkboxes appear, taps add or remove, a floating bar offers Move, Download and Delete), hold and drag a selected file onto a folder to move it, and every menu, the Move dialog and the new folder dialog are bottom sheets. The layout follows the manager's own width, so in a narrow side panel it shows the compact list and two-column tiles even on a wide screen.

npm: @dnd-kit/core, motion, lucide-react
Wingo UI dependencies: alert-dialog, avatar, breadcrumb, button, checkbox, context-menu, dialog, dropdown-menu, empty-state, file-upload, image-lightbox, input, progress, segmented-control, skeleton, toolbar, tooltip, tree-view, use-controllable-state, use-locale, use-long-press, use-media-query, use-persisted-state, use-selection, use-shortcut, file-types, motion, number-format, relative-time, text-match, tones, ui-config

Props:
- `items: FileManagerItem[]` = "[]": The whole tree, flat: { id, kind: "folder" | "file", name, parentId (null at the root), size? (bytes), type? (mime), url?, thumbnailUrl?, modifiedAt?, modifiedBy?: { name, avatar? }, itemCount?, shared?, starred?, locked? }. The component filters by parentId; a parentId loop never hangs. Locked items cannot be renamed, moved or deleted; Move and Delete on a selection that holds some skip them. Tiles use content-visibility past 60 items; page from the server beyond about 2.000 files in one folder.
- `rootLabel?: string` = "": The root's name in the breadcrumb, the folder tree and search paths. Empty uses labels.root ("All files").
- `quota?: { used: number; total: number }`: Bytes used and available: a thin bar with "2,4 GB of 10 GB" next to the breadcrumb, amber past 80% and red past 95%.
- `uploads?: FileManagerUpload[]` = "[]": The uploads you are running: { id, name, size, progress (0 to 1), status: "uploading" | "done" | "error", error?, folderId }. They show in a floating panel at the bottom corner (collapsible, dismissible once nothing is running), next to the files the picker or a drop rejected.
- `emptyState?: ReactNode`: Replaces the empty folder state (by default an icon, a line of text and New folder / Upload when those handlers exist).
- `labels?: Partial<FileManagerLabels>`: Every string, English by default (DEFAULT_FILE_MANAGER_LABELS): root, region, folders, search, newFolder, folderName, create, cancel, upload, dropHere(folder), move, moveTo, moveHere, moveDescription(count, name), rename, download, delete, deleteTitle(count, name), deleteDescription, open, preview, select(name), selectAll, clearSelection, selected(count, formatted), items(count, formatted), results(count, formatted), name, modified, size, owner, type, sort, ascending, descending, view, grid, list, actions(name), sheetTitle, uploads, uploading(count, formatted), uploadsDone(count, formatted), uploadsFailed(count, formatted), uploadDone, uploadFailed, rejectedType, rejectedSize(max), collapse, expand, dismiss, storage, quota(used, total), empty, emptyDescription, noResults, noResultsDescription(query), clearSearch, loading, errorTitle, retry, moved(count, folder), renamed(name), deleted(count), created(name), failed, locked, shared, starred, folder, modifiedOn(when), dragging(count, name), pickedUp(count, name), dropped, dragCancelled, kinds (names per file kind).
- `defaultView?: "grid" | "list"` = "grid": The first layout while uncontrolled: tiles with previews, or rows with Modified, Size and Owner columns. Phones start with the list until someone picks a view; search results are always a list.
- `view?: "grid" | "list"`: The layout, controlled. Pair it with onViewChange.
- `onViewChange?: (view: "grid" | "list") => void`: Called when the view switch in the toolbar changes.
- `tileSize?: "sm" | "md" | "lg"` = "md": The smallest tile width in the grid, 120 / 160 / 200px; the grid fits as many columns as it can. Below 512px of width (phones, side panels) it shows two columns.
- `variant?: "surface" | "plain"` = "surface": surface sits the manager in a raised panel; plain drops the panel, for a section card that already has one.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Selected tiles and rows, drop targets, checkboxes, the tree's current folder, progress bars and the Upload button of the empty state.
- `color?: string` = "": Any CSS color in place of the tone.
- `showTree?: boolean` = true: The folder tree beside the files once the manager itself is 768px wide (a container query, so it also hides in a narrow panel on a wide screen). Its folders are drop targets too.
- `showBreadcrumb?: boolean` = true: The path from the root to the open folder; every crumb is a drop target. Phones show a back link to the parent.
- `loading?: boolean` = false: Skeleton tiles or rows with the real shape while the first page loads.
- `skeletonCount?: number` = 12: How many skeletons show while loading.
- `error?: ReactNode` = "": Replaces the files with an error state and its message; add onRetry for a Try again button.
- `onRetry?: () => (void | Promise<unknown>)`: The error state's Try again button.
- `defaultSearch?: string` = "": A search to start with. Search looks through every folder, ignoring case and diacritics, and lists the results with their folder path.
- `search?: string`: The search, controlled. Pair it with onSearchChange.
- `onSearchChange?: (search: string) => void`: Called with the debounced query, and with "" when a folder is opened from the results.
- `folderId?: string | null`: The open folder, controlled (null is the root). If it disappears from items, the nearest folder that still exists opens.
- `defaultFolderId?: string | null` = "null": The folder that opens first while uncontrolled (null is the root). The playground offers folders of the demo.
- `onFolderChange?: (folderId: string | null) => void`: Called when a folder opens: a double-click, a crumb, the tree, Backspace.
- `sort?: FileManagerSort`: The sort, controlled: { by: "name" | "modified" | "size" | "type", direction: "asc" | "desc" }. Folders always come first.
- `defaultSort?: FileManagerSort` = "DEFAULT_FILE_MANAGER_SORT": The first sort while uncontrolled: { by: "name", direction: "asc" }. Picking Modified or Size in the menu starts with the newest or largest.
- `onSortChange?: (sort: FileManagerSort) => void`: Called from the sort menu and from the column headers of the list.
- `selectedKeys?: string[]`: The selected ids, controlled. Pair it with onSelectedKeysChange.
- `defaultSelectedKeys?: string[]` = "[]": The ids selected at first while uncontrolled; with any selected the toolbar is the bulk bar.
- `onSelectedKeysChange?: (keys: string[]) => void`: Called when the selection changes. Opening another folder clears it.
- `persistKey?: string` = "": Remembers the view and the sort in localStorage under this key ("<key>:view", "<key>:sort"). Empty remembers nothing.
- `confirmDelete?: boolean` = true: Ask before deleting, in an alert dialog that names the file or the count. Off, Delete runs at once.
- `previewImages?: boolean` = true: Images open in the built-in lightbox with the folder's other images. Off, they go to onOpen like any other file.
- `accept?: string` = "": What the upload picker offers, like the input's accept ("image/*,.pdf"). Dropped or pasted files outside it are listed as rejected in the uploads panel instead of reaching onUpload.
- `maxFileSize?: number` = 0: The largest file in bytes; bigger ones are listed as rejected with the limit. 0 means no limit.
- `uploadShortcut?: string` = "": A key combo that opens the upload picker from anywhere on the page ("mod+u" notation). Empty binds nothing.
- `locale?: string` = "": Formats sizes ("2,4 MB"), dates, counts and the sort order. Empty uses the UIProvider locale, then the browser's.
- `now?: Date | number`: The reference time for "modified 5 min ago". Defaults to a live clock that ticks every minute; demos pin 24.09.2026 16:40.
- `onOpen?: (item: FileManagerItem) => void`: Opens a file. Folders always open in place and images in the lightbox (while previewImages is on). Without it a file with a url opens in a new tab.
- `onUpload?: (files: File[], folderId: string | null) => (void | Promise<unknown>)`: Turns on the Upload button, dropping files from the desktop and pasting them. folderId is the open folder, or the folder tile the files were dropped on. Report progress back through uploads.
- `onCreateFolder?: (name: string, parentId: string | null) => (void | Promise<unknown>)`: Turns on New folder (a dialog, a sheet on phones). A rejected promise keeps the dialog open with its message, so you decide about duplicate names.
- `onRename?: (item: FileManagerItem, name: string) => (void | Promise<unknown>)`: Turns on renaming in place. The field stays busy while the promise runs; a rejection shows its message under it and keeps it open.
- `onMove?: (ids: string[], targetFolderId: string | null) => (void | Promise<unknown>)`: Turns on dragging onto folders, crumbs and tree nodes, and Move to (a dialog with the folder tree, a sheet on phones). Moves into the current folder, into itself or into a subfolder are refused before it runs.
- `onDelete?: (ids: string[]) => (void | Promise<unknown>)`: Turns on Delete in the menus, the bulk bar and the Delete key. The confirmation stays loading while the promise runs.
- `onDownload?: (items: FileManagerItem[]) => void`: Download for files and selections. Without it Download appears when every file has a url and saves them through links.
- `getActions?: (item: FileManagerItem) => MenuEntry[]`: Extra menu entries per item (Share, Copy link, Star), between Download and Delete, in the W1 MenuEntry shape.
- `classNames?: Partial<Record<"toolbar" | "breadcrumb" | "title" | "quota" | "body" | "tree" | "content" | "header" | "tile" | "row" | "select" | "icon" | "name" | "meta" | "actions" | "drop" | "uploads" | "empty" | "move" | "newFolder", string>>`: Extra classes for the parts. title is the phone's folder title, move and newFolder go on the dialogs' bodies, uploads on the floating panel.
- `className?: string`: Extra classes for the root, merged last. Other props (id, aria-*, data-*, handlers) spread onto it.

Parts:
- `buildFolderTree` (function): The folders as nested tree-view nodes with folder icons, sorted by name; a parentId loop is broken (a folder is never listed twice). Pure, so a server can call it. Signature: (items: FileManagerItem[], options?: { locale?: string }) => TreeNode[].
- `getFolderPath` (function): The trail from the root to a folder as breadcrumb entries (the root's id is "file-manager-root"). Pure and cycle-safe. Signature: (items: FileManagerItem[], folderId: string | null, options?: { rootLabel?: string }) => BreadcrumbEntry[].
- `DEFAULT_FILE_MANAGER_LABELS` (constant): The English strings, to spread under a translation. Type: FileManagerLabels.
- `DEFAULT_FILE_MANAGER_SORT` (constant): { by: "name", direction: "asc" }, the default sort. Type: FileManagerSort.

```tsx
import { useState } from "react"
import { FileManager, type FileManagerItem, type FileManagerUpload } from "@/components/ui/file-manager"

export function Documents({ initial }: { initial: FileManagerItem[] }) {
  const [items, setItems] = useState(initial)
  const [uploads, setUploads] = useState<FileManagerUpload[]>([])

  return (
    <FileManager
      items={items}
      uploads={uploads}
      quota={{ used: 2.4 * 1024 ** 3, total: 10 * 1024 ** 3 }}
      locale="en-US"
      persistKey="crm:documents"
      labels={{ root: "Company files", search: "Search company files" }}
      onUpload={async (files, folderId) => {
        setUploads(files.map((file) => ({ id: file.name, name: file.name, size: file.size, progress: 0, status: "uploading", folderId })))
        const body = new FormData()
        files.forEach((file) => body.append("files", file))
        const saved: FileManagerItem[] = await (await fetch(`/api/files?folder=${folderId ?? ""}`, { method: "POST", body })).json()
        setItems((list) => [...list, ...saved])
        setUploads((list) => list.map((upload) => ({ ...upload, progress: 1, status: "done" })))
      }}
      onCreateFolder={async (name, parentId) => {
        const folder: FileManagerItem = await (await fetch("/api/folders", { method: "POST", body: JSON.stringify({ name, parentId }) })).json()
        setItems((list) => [...list, folder])
      }}
      onRename={async (item, name) => {
        await fetch(`/api/files/${item.id}`, { method: "PATCH", body: JSON.stringify({ name }) })
        setItems((list) => list.map((i) => (i.id === item.id ? { ...i, name } : i)))
      }}
      onMove={async (ids, parentId) => {
        await fetch("/api/files/move", { method: "POST", body: JSON.stringify({ ids, parentId }) })
        setItems((list) => list.map((i) => (ids.includes(i.id) ? { ...i, parentId } : i)))
      }}
      onDelete={async (ids) => {
        await fetch("/api/files", { method: "DELETE", body: JSON.stringify({ ids }) })
        setItems((list) => list.filter((i) => !ids.includes(i.id)))
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/file-manager (Markdown: https://wingo-ui.com/components/file-manager.md)

#### Folder (`folder-component`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add folder-component`

An animated folder whose cards fan out on hover and lift open on click, behind a 3D-tilted glass flap.

Hover (or tab to it) to fan the three cards out of the folder while the flap tips back, then click, tap, Enter or Space to lift the folder open and send the cards up in a spread. Click again, press Escape, or move the pointer away to drop everything back in.

npm: motion
Wingo UI dependencies: ui-config

Props:
- `color?: "auto" | "black" | "white" | "blue"` = "auto": Color theme of the folder, flap, and cards. Auto is white on light pages and black on dark ones, switched in CSS with the dark class so it never flashes; the others stay fixed in both themes.
- `backColor?: string` = "": Any CSS color for the back panel, over the chosen color theme.
- `flapColor?: string` = "": Any CSS color for the frosted front flap (it keeps the theme's glass opacity); its outline follows as a lighter shade.
- `cardColor?: string` = "": Any CSS color for the three cards; their outline follows as a darker shade.
- `size?: "sm" | "md" | "lg"` = "md": Overall scale of the folder. Maps to 0.65x (sm), 1x (md), and 1.35x (lg) of the 321 x 270 px base, and carries the cards and flap with it.
- `spread?: number` = 1: How wide the cards fan out: 1 is the original, 0 stacks them straight, 1.5 fans them further. Scales the sideways offsets and tilts, not the lift.
- `label?: string` = "Folder": Accessible name of the folder button, e.g. the name of the folder.
- `closeOnLeave?: boolean` = true: Drops the cards back in when the pointer leaves or focus moves away. Turn it off to keep the folder open until it is clicked again.
- `defaultOpen?: boolean` = false: Starts open when uncontrolled. Ignored when open is set.
- `open?: boolean`: Controlled open state. Pass it with onOpenChange to drive the folder yourself.
- `onOpenChange?: (open: boolean) => void`: Called with the next open state on click, Escape, pointer leave or blur.
- `cards?: ReactNode[]`: Content for the three cards, back to front, each filling a 158 x 208 px rounded card (before scaling). Leave it out for the default document lines; an image or a short preview works well.
- `className?: string`: Extra classes for the root, which fills its parent and centers the folder. Any other div prop is spread onto it too.

Parts:
- `FolderColor` (type): The color themes: "auto" (white on light pages, black on dark ones) | "black" | "white" | "blue".

```tsx
import { Folder } from "@/components/ui/folder-component"

export function Demo() {
  return (
    <div className="h-96">
      <Folder label="Design files" />
    </div>
  )
}

// put your own previews on the cards, back to front:
// <Folder color="blue" cards={[<img src="/a.jpg" alt="" />, <img src="/b.jpg" alt="" />, <img src="/c.jpg" alt="" />]} />
```

Docs: https://wingo-ui.com/components/folder-component (Markdown: https://wingo-ui.com/components/folder-component.md)

#### Gantt (`gantt`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add gantt`

A project timeline: tasks as bars you drag and resize, progress, dependency arrows, milestones, folding groups and a phone task list.

Drag a bar to move it and drag its edges to resize it; it snaps to whole days (or weeks) on release, a pill above it shows the new dates and the original stays behind faded until you let go. Near the timeline's edge the view scrolls along. With progressEditable a small handle under the bar sets the progress. Click or tap a bar, or a name in the task list, for its details: dates, progress and Save, in a popover on a desktop and a bottom sheet on a phone. Arrows join dependent tasks and turn dashed red when a task starts before its predecessor ends. Chevrons fold groups; drag the task list's edge to widen it. The zoom switches between days, weeks and months and keeps the date in the middle in place; Today and Fit scroll for you. On touch, press and hold a bar to pick it up. Keyboard: Tab lands on one task; Up / Down, Page Up / Page Down, Home / End move between tasks; Enter opens the details; Alt+Left / Right moves a task by one snap step, Alt+Shift+Left / Right changes its end; Left / Right fold and unfold a group; t scrolls to today; Escape cancels a drag. Below 512px of width the chart becomes a list of tasks with mini bars.

npm: date-fns, @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: avatar, badge, button, date-picker, empty-state, popover, progress, segmented-control, slider, tooltip, use-controllable-state, use-locale, use-long-press, date-utils, relative-time, motion, tones, ui-config

Props:
- `tasks: GanttTask[]`: { id, name, start, end (inclusive), progress? 0 to 1, parentId?, dependencies? (finish to start), milestone?, assignee? { name, avatar? }, tone?, color?, status? { label, tone? }, readOnly? }. Order is display order within each parent; a task with children is a group whose span and progress are computed.
- `title?: ReactNode` = "": A heading at the start of the toolbar, like the project's name.
- `defaultZoom?: "day" | "week" | "month"` = "week": Starting zoom while uncontrolled: day is 40px a day with day headers, week 20px a day with week numbers, month 6px a day with month names. Pair zoom with onZoomChange to control it.
- `zoom?: "day" | "week" | "month"`: The controlled zoom; the toolbar's segmented control and Fit call onZoomChange.
- `onZoomChange?: (zoom: GanttZoom) => void`: Fires when the zoom control, Fit or the API changes the zoom.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The default bar color; a task's own tone or color wins.
- `color?: string` = "": Any CSS color for the bars; replaces the tone. Leave empty to use the tone.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the panel: 0 / 12 / 16 / 24px.
- `rowHeight?: number` = 44: Row height in px. Bars stay 28px tall and keep a 44px touch target.
- `listWidth?: number` = 320: Width of the task list in px (at least 200). People can drag its edge, or focus the edge and use the arrow keys. From 512 to 1023px the list keeps only the names, at most 220px (and 40% of the width).
- `maxHeight?: number` = 520: Height in px after which the body scrolls, with sticky headers and a sticky task list. 0 grows with the rows.
- `showList?: boolean` = true: The task list beside the timeline. Off, group bars carry their names.
- `toolbar?: boolean` = true: The row with the title, the zoom, Today and Fit.
- `listColumns?: ("assignee" | "start" | "end" | "duration" | "progress" | "status")[]` = "[\"assignee\", \"start\", \"progress\"]": Columns after the name, shown from 1024px of width.
- `editable?: boolean` = true: Bars move and resize by drag, by Alt+arrows and from the details. Off, the details only show the task.
- `progressEditable?: boolean` = false: A handle under each bar to drag its progress, in steps of 5%.
- `snap?: "day" | "week"` = "day": What a drag, a resize and Alt+arrows snap to.
- `showDependencies?: boolean` = true: Arrows from each predecessor's end to its task's start; dashed red when the task starts too early.
- `showToday?: boolean` = true: Today's line across the timeline, its day in the header and the Today button.
- `showWeekends?: boolean` = true: Shades the locale's weekend days in the day and week zooms.
- `loading?: boolean` = false: Skeleton rows in place of the tasks.
- `skeletonCount?: number` = 6: How many skeleton rows show while loading.
- `responsive?: boolean` = true: Task details open in a bottom sheet below 768px instead of a popover.
- `locale?: string` = "": Dates, week numbers, month and weekday names, the first day of the week and the weekend. Empty follows the app.
- `onTaskChange?: (task: GanttTask, change: GanttTaskChange) => (void | false | Promise<unknown>)`: A move, a resize, a progress drag or a details save, with { start, end, progress? }. The bar keeps the new place optimistically; return false or reject to spring it back. Dependents are not shifted for you.
- `onTaskClick?: (task: GanttTask) => void`: Replaces the built-in details popover and sheet.
- `columnWidth?: Partial<Record<GanttZoom, number>>` = "{ day: 40, week: 20, month: 6 }": Pixels per day for each zoom.
- `range?: { start: Date; end: Date }`: The visible dates; it grows to include every task. Default: the tasks' span plus 7 days on each side.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: First day of a week column and of the date pickers: 0 Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Monday in en-GB, Sunday in en-US).
- `groupsExpanded?: string[]`: Controlled ids of the open groups; pair it with onGroupsExpandedChange.
- `defaultGroupsExpanded?: string[]`: Open groups while uncontrolled. Default: every group.
- `onGroupsExpandedChange?: (ids: string[]) => void`: Fires when a group folds or unfolds.
- `emptyState?: ReactNode`: Shown when there are no tasks. Default: an EmptyState with labels.empty ("No tasks yet").
- `now?: Date | number`: Where today's line sits. Default: the current time, updated every minute.
- `setApi?: (api: GanttApi) => void`: Receives { scrollToToday(), scrollToTask(id), setZoom(zoom), fit() } after mount.
- `toolbarActions?: ReactNode`: Extra buttons at the end of the toolbar.
- `labels?: Partial<GanttLabels>`: Every string, English by default (DEFAULT_GANTT_LABELS): task, assignee, start, end, date, duration(days, formatted), durationColumn, progress, status, today, fit, zoom, zoomDay, zoomWeek, zoomMonth, week(n), range(start, end), project(range), completed(percent), assignedTo(name), moved(task, range), resized(task, range), progressChanged(task, percent), violation(task, predecessor), failed(task), milestone, group(count, formatted), details, save, cancel, close, expand, collapse, resizeList, timeline, noAssignee, empty, emptyDescription, loading.
- `classNames?: Partial<Record<GanttSlot, string>>`: Extra classes for toolbar, title, body, listHeader, listRow, timelineHeader, grid, row, bar, barProgress, barLabel, milestone, summary, dependencies, today, details, mobile and mobileRow.

```tsx
import { useState } from "react"
import { Gantt, type GanttTask } from "@/components/ui/gantt"
// also exported: computeSummary(tasks) (span and weighted progress of every parent),
// findDependencyViolations(tasks) (tasks starting before a predecessor ends), topoSortTasks(tasks) (predecessors first)

const START: GanttTask[] = [
  { id: "analysis", name: "Analysis", start: new Date(2026, 8, 22), end: new Date(2026, 9, 3) },
  {
    id: "workshop",
    name: "Requirements workshop",
    parentId: "analysis",
    start: new Date(2026, 8, 22),
    end: new Date(2026, 8, 25),
    progress: 1,
    assignee: { name: "Liam Walker" },
  },
  {
    id: "specs",
    name: "Specifications",
    parentId: "analysis",
    start: new Date(2026, 8, 28),
    end: new Date(2026, 9, 3),
    progress: 0.4,
    dependencies: ["workshop"],
  },
  { id: "go-live", name: "Go-live", start: new Date(2026, 10, 3), end: new Date(2026, 10, 3), milestone: true, dependencies: ["specs"] },
]

export function ProjectPlan() {
  const [tasks, setTasks] = useState(START)
  return (
    <Gantt
      title="Acme CRM rollout"
      tasks={tasks}
      locale="en-US"
      onTaskChange={(task, change) =>
        setTasks((list) => list.map((t) => (t.id === task.id ? { ...t, ...change } : t)))
      }
      labels={{ fit: "Fit all", week: (n) => `Week ${n}` }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/gantt (Markdown: https://wingo-ui.com/components/gantt.md)

#### JSON Viewer (`json-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add json-viewer`

A collapsible JSON tree with type colors, search that opens the matching branches, copy value or path, and virtualization for huge payloads.

Click or tap a branch to open or close it: the chevron turns and small branches slide open. Collapsed objects show their first keys and arrays their first values, with a count. Type in the search box (or press Ctrl+F / ⌘F while inside the viewer) and every key or value that matches is highlighted, its branches open and the first hit scrolls to the middle; Enter and Shift+Enter or the arrows step through the hits and the counter reads 2 of 5. Escape clears the search, a second Escape returns to the tree. With a mouse, hovering a row shows Copy value and Copy path; on a phone a long press opens a sheet that repeats the value (and a date in local time) with the same actions plus Expand all from here. The toolbar expands or collapses everything, copies the whole JSON and downloads it as a dated .json file; below 512px of width it folds into a ⋯ menu. The tree is one Tab stop: Up and Down move, Right opens or steps into a branch, Left closes it or goes to the parent, Home and End jump, * opens every sibling, Enter toggles a branch or selects a value, c copies the value and Shift+C its path, and the context menu key opens the row's actions. Long strings stop at maxStringLength with a Show more button (Right and Left on the row show and hide the rest), arrays over 100 items open in pages of 100, and above 300 visible rows only what is on screen is rendered.

npm: @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: action-sheet, button, empty-state, search-input, tooltip, use-clipboard, use-controllable-state, use-locale, use-long-press, use-media-query, file-export, motion, number-format, text-match, ui-config

Props:
- `data: unknown`: Any JSON-compatible value. Dates, undefined, BigInt (123n), NaN and Infinity show as words or numbers, Maps and Sets as objects and arrays, circular references as [Circular → data.parent]. Strings that contain JSON are not parsed: pass the parsed value. undefined shows the empty state.
- `rootName?: string | false` = "": A key label on the root, like "payload". Empty (false) shows the root braces only.
- `defaultExpandDepth?: number` = 1: Levels open on mount: 0 keeps the root closed, 1 shows its keys. Deeper opening goes through the API (expandToDepth).
- `expandedKeys?: string[]`: Controlled open branches as pathKey strings ("$", "$/invoice/lines", pages of long arrays as "$/items/~g100").
- `defaultExpandedKeys?: string[]`: Open branches on mount; replaces defaultExpandDepth when set.
- `onExpandedKeysChange?: (keys: string[]) => void`: Every open or close, including the branches a search opens.
- `searchable?: boolean` = true: The search box in the toolbar. Without it the toolbar shows the root name and its count.
- `searchIn?: "keys" | "values" | "both"` = "both": What the search matches. Values match as their text (numbers, true, null too); case and diacritics are ignored.
- `toolbar?: boolean` = true: The row with search, expand / collapse all, copy and download.
- `pathFormat?: "js" | "pointer"` = "js": Copy path as data.items[0].name (keys with spaces as ["full name"]) or as a JSON Pointer /items/0/name.
- `rootPathName?: string` = "data": The root identifier in js paths: data.invoice.customer.
- `maxStringLength?: number` = 120: Longer strings stop with an ellipsis and a Show more button. A search hit further in shows the whole string.
- `showCounts?: boolean` = true: 3 keys / 12 items after objects and arrays.
- `showTypes?: boolean` = false: A small type chip before each value: string, int, float, bool, null, date, object, array.
- `showLineNumbers?: boolean` = false: A sticky gutter with row numbers that stays put while long lines scroll sideways.
- `quoteKeys?: boolean` = true: "name": like JSON, or name: without quotes.
- `sortKeys?: boolean` = false: Shows object keys alphabetically. Display only: copy and download keep the original order.
- `detectDates?: boolean` = true: ISO date strings get the date color (still quoted) and a native tooltip with the local date and time.
- `size?: "sm" | "md"` = "md": 12px text on 24px rows or 13px on 28px rows. Rows grow to 36px on touch screens.
- `height?: number` = 0: A fixed body height in px. 0 grows with the content up to maxHeight.
- `maxHeight?: number` = 480: The tallest the body grows when height is 0; it scrolls inside after that.
- `virtualThreshold?: number` = 300: Visible rows above which only the rows on screen are rendered (each row measured, 12 rows of overscan).
- `wrap?: "auto" | boolean` = "auto": Long values break onto more lines, indented under their key, instead of scrolling sideways. auto wraps below 512px of the viewer's width (phones).
- `onSelect?: (path: JsonPath, value: unknown) => void`: A value activated with Enter, a click or a tap. With it set, the selected row stays highlighted.
- `fileName?: string` = "data": Download name base; the file is saved as data-2026-09-24-1640.json.
- `downloadable?: boolean` = true: The Download action in the toolbar.
- `copyable?: boolean` = true: The Copy JSON action in the toolbar (indented, circular references and BigInts made safe).
- `rowActions?: boolean` = true: Copy value and Copy path on each row: on hover or focus with a mouse, on long press on touch screens.
- `loading?: boolean` = false: Skeleton rows in place of the tree; the toolbar actions wait.
- `skeletonCount?: number` = 8: Skeleton rows while loading.
- `emptyState?: ReactNode`: Replaces the built-in No data state shown when data is undefined.
- `setApi?: (api: JsonViewerApi) => void`: Called after mount (and when the API changes) with { expandAll, collapseAll, expandToDepth(depth), expandPath(path), scrollToPath(path), search(query) }.
- `locale?: string` = "": Counts and date tooltips. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<JsonViewerLabels>`: Every string: search, matches(i, n), noMatches, previousMatch, nextMatch, expandAll, collapseAll, copy, copyValue, copyPath, download, copied, copyFailed, downloaded(name), items(count, formatted), keys(count, formatted), more(count, formatted), less, expand, collapse, expandHere, moreActions, cancel, circular, empty, loading, tree. English defaults in DEFAULT_JSON_VIEWER_LABELS.
- `classNames?: Partial<Record<"toolbar" | "summary" | "search" | "body" | "row" | "lineNumber" | "toggle" | "key" | "value" | "type" | "preview" | "count" | "actions" | "more" | "empty", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root panel, merged last. Give it a height (h-full) and height={0} with maxHeight={0} to fill a pane.

Parts:
- `formatJsonPath` (function): The path text copy path uses: formatJsonPath(["items", 0, "name"]) is data.items[0].name, with "pointer" /items/0/name. Signature: (path: JsonPath, format?: "js" | "pointer", rootName?: string) => string.
- `pathKey` (function): The key expandedKeys uses for a path: pathKey(["invoice", "lines"]) is "$/invoice/lines". Signature: (path: JsonPath) => string.
- `flattenJson` (function): The visible rows (nodes, array pages and closing braces) for a set of open keys, for tests and custom renderers. Signature: (value: unknown, expandedKeys: Iterable<string>, options?: { rootName?; sortKeys?; detectDates? }) => JsonRow[].
- `JSON_COLORS` (constant): The value color classes, shared with anything that prints JSON inline (log metadata). Type: Record<"key" | "string" | "number" | "boolean" | "null" | "date" | "punctuation", string>.

```tsx
import { JsonViewer, type JsonViewerLabels } from "@/components/ui/json-viewer"

const labels: Partial<JsonViewerLabels> = {
  search: "Search keys and values",
  noMatches: "Nothing found",
}

const webhook = {
  id: "evt_4912873366",
  account: "acct_12345674",
  created_at: "2026-09-24T16:38:12-04:00",
  status: "ok",
  invoice: { number: "2026-0412", customer: { name: "Acme Corp", tax_id: "12-3456740" } },
  warnings: [],
}

export function WebhookDetails() {
  return (
    <JsonViewer
      data={webhook}
      rootName="webhook"
      defaultExpandDepth={2}
      fileName="invoice-2026-0412"
      locale="en-US"
      labels={labels}
      onSelect={(path, value) => console.log(path, value)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/json-viewer (Markdown: https://wingo-ui.com/components/json-viewer.md)

#### Kbd (`kbd`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add kbd`

Keyboard keys and combos in the notation of the device: ⌘K on a Mac, Ctrl+K everywhere else.

Pass a combo like mod+k and it prints ⌘ K on Apple devices and Ctrl K elsewhere; screen readers hear "Command K" instead of the glyphs. In the playground, press ⌘K (Ctrl+K) to jump into the search field, use the arrow keys and Enter to move through the results, and press Esc to close the window and again to bring it back. Turn on listen and the caps sink and light up while you hold the real keys. On a phone the keyboard hints hide themselves and a tap opens a result.
Wingo UI dependencies: ui-config, use-shortcut, use-media-query, tones

Props:
- `children?: ReactNode` = "Esc": A single key label, used when there is no shortcut and no keys. Glyphs like ⌘ or ↵ get a spoken name for screen readers.
- `shortcut?: string` = "": A combo in mod+k notation: "mod+k", "shift+mod+p", "alt+n", "mod+enter", "/". mod is ⌘ on Apple devices and Ctrl elsewhere. Wins over keys and children; an unparseable value falls back to them.
- `keys?: string[]`: One cap per entry, shown as written. For sequences (["G", "I"] with separator "then") and hints that are not one combo (["↑", "↓"]). Used when there is no shortcut.
- `separator?: ReactNode` = "": Rendered between caps when they are not combined, like "+" or "then". A word separator is also read out ("G then I"); a symbol is not.
- `srLabel?: string` = "": What screen readers hear instead of the caps. By default the combo is spelled out in English ("Shift Command P", "Control K", "G then I"); pass a translation on localized pages.
- `variant?: "soft" | "outline" | "solid" | "ghost"` = "soft": soft is the quiet gray key for hints next to fields and buttons. outline draws a border, solid is a raised key like a real keyboard, ghost is text only for menus and inverted surfaces like tooltips.
- `size?: "sm" | "md" | "lg"` = "md": Cap height 16 / 20 / 24px with a matching minimum width, 10 / 11 / 12px type and a radius that scales along.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color. neutral is the gray key from the design system; the other tones tint the key, and a held key (listen) fills with the tone.
- `color?: string` = "": Any CSS color. Replaces the tone in every variant; text on a solid key turns black or white by lightness.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size. md is 4 / 5 / 6px; full makes round caps.
- `combined?: boolean` = false: The whole combo in one cap (⌘K, Ctrl+K) instead of one cap per key. Reads well in tight rows and menus.
- `platform?: "auto" | "apple" | "other"` = "auto": Forces a notation, for docs pages that show both. auto renders the Windows and Linux form on the server and during hydration, then swaps to the device's.
- `hideOnTouch?: boolean` = false: Hides the keys on touch screens, where a keyboard hint means nothing.
- `listen?: boolean` = false: Caps sink and light up while the matching keys are held on a physical keyboard, and the root gets data-pressed once the whole combo is down. It only watches; it never binds or blocks a key.
- `classNames?: Partial<Record<"key" | "separator", string>>`: Extra classes for every cap (also the single cap) and for the separators.
- `className?: string`: Extra classes for the root: the <kbd> for one cap, the group span for several. Merged last.

```tsx
import { Search } from "lucide-react"
import { Kbd } from "@/components/ui/kbd"

export function SearchHint() {
  return (
    <div className="flex items-center gap-2 text-sm text-muted-foreground">
      <Search className="size-4" />
      <span className="flex-1">Search listings</span>
      <Kbd shortcut="mod+k" hideOnTouch />
    </div>
  )
}

export function CloseHint() {
  return (
    <p className="text-sm text-muted-foreground">
      Press <Kbd>Esc</Kbd> to close the window, or <Kbd keys={["G", "I"]} separator="then" /> for the Inbox.
    </p>
  )
}
```

Docs: https://wingo-ui.com/components/kbd (Markdown: https://wingo-ui.com/components/kbd.md)

#### Log Viewer (`log-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add log-viewer`

A streaming log console for 100.000 lines: level colors, level and text or regex filters, follow the tail, ANSI colors and JSON details.

New lines stream in at the bottom and the view follows them. Scroll up (wheel, finger, scrollbar or keys) and following pauses by itself: a pill at the bottom counts the new lines (12 new lines) and a tap on it, the End key or scrolling back to the very end follows again; the follow toggle and the Live / Paused badge in the footer show the state. Type in the search to hide the lines that do not match (case and diacritics are ignored), or turn on the .* toggle for a regular expression (an invalid one is marked and filters nothing); in highlight mode every line stays, hits are marked and Enter / Shift+Enter or the arrows step through them. The level chips turn levels on and off and show their counts. Click, tap or press Enter on a line with details to open its JSON tree under it (the stream pauses so it stays put). The toolbar wraps lines, shows or hides the time, and the ⋯ menu copies the visible lines, downloads everything as a dated .log file or clears the buffer; on a narrow viewer wrap and time move into that menu, and below 768px it opens as a bottom sheet while the chips scroll sideways. The log body is one Tab stop: Up and Down move a focus row, Page Up / Page Down jump a page, Home goes to the first line, End to the newest, Escape drops the focus row (screen readers hear each focus row as it moves), and Ctrl+F / ⌘F inside the viewer jumps to its search (searchShortcut adds a global key). Lines over 10.000 characters are cut with a Show all button; with maxLines reached the oldest lines drop and the footer says how many.

npm: @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: badge, button, dropdown-menu, empty-state, json-viewer, search-input, tag, toggle, tooltip, use-clipboard, use-controllable-state, use-locale, use-media-query, use-stick-to-bottom, file-export, motion, number-format, relative-time, text-match, tones, ui-config

Props:
- `lines?: LogLine[] | string[]` = "[]": The lines: { id?, time?, level?, message, source?, meta? } or raw strings (parsed with parseLogLine). Pass a new array to append: only the new tail is read; a shorter or different array starts over. For high rates use setApi().append, which never re-renders the parent.
- `maxLines?: number` = 100000: A ring buffer: past it the oldest lines drop and the footer says how many. Lowering it at runtime trims from the start.
- `levels?: LogLevel[]` = "all six": The level chips shown in the toolbar ("trace", "debug", "info", "warn", "error", "fatal").
- `levelFilter?: LogLevel[]`: Controlled visible levels. Lines without a level are always shown.
- `defaultLevelFilter?: LogLevel[]` = "all six": Visible levels on mount.
- `onLevelFilterChange?: (levels: LogLevel[]) => void`: A level chip was turned on or off.
- `query?: string`: Controlled search text.
- `defaultQuery?: string` = "": The search on mount. Words match anywhere in the message or source, ignoring case and diacritics; the filter runs 120ms after typing stops.
- `onQueryChange?: (query: string) => void`: Every keystroke in the search.
- `filterMode?: "filter" | "highlight"` = "filter": filter hides the lines that do not match; highlight keeps them, marks the hits and steps through them with Enter / Shift+Enter.
- `regex?: boolean` = false: The search is a regular expression (case-insensitive). The .* toggle in the toolbar flips it; an invalid expression is marked and filters nothing.
- `follow?: boolean`: Controlled following of the newest line.
- `defaultFollow?: boolean` = true: Stick to the newest line on mount. Scrolling up pauses it by itself.
- `onFollowChange?: (follow: boolean) => void`: Following paused (scroll up, a key, an opened line) or resumed (the pill, End, the toggle, scrolling to the end).
- `wrap?: boolean | "auto"`: Controlled line wrapping.
- `defaultWrap?: boolean | "auto"` = "auto": auto wraps below 768px and keeps one line (scrolling sideways) above.
- `onWrapChange?: (wrap: boolean) => void`: The wrap toggle was pressed.
- `showTimestamps?: boolean` = true: The time column. The toolbar clock toggle flips it too.
- `timeFormat?: "time" | "datetime" | "relative" | "iso"` = "time": time 16:38:12.345, datetime 24.09.2026, 16:38:12, relative 2 min ago (ticking), iso as stored. Local times print after hydration.
- `showLevels?: boolean` = true: The 3-letter level tag (INF, WRN, ERR) in the level's tone.
- `showSource?: boolean` = true: The source chip ([spv], [http]), truncated at 14 characters.
- `showLineNumbers?: boolean` = false: Line numbers that keep counting after old lines drop. They are skipped when copying text.
- `ansi?: boolean` = true: Renders ANSI colors (30 to 37, 90 to 97, backgrounds, bold, dim, italic, underline) with the tone palette; false strips them.
- `expandable?: boolean` = true: Lines with meta open a JSON tree under them on click, tap or Enter.
- `size?: "sm" | "md"` = "sm": 12px text on 24px rows or 13px on 28px rows.
- `height?: number` = 420: Height of the log body in px.
- `toolbar?: boolean` = true: The row with search, level chips, toggles and the ⋯ menu.
- `searchShortcut?: string` = "": A global key that focuses the search, like mod+shift+f (shown as a hint in the field). Empty binds nothing; Ctrl+F / ⌘F always works inside the viewer.
- `fileName?: string` = "logs": Download base name: logs-2026-09-24-1640.log.
- `loading?: boolean` = false: Skeleton rows in place of the log; the toolbar waits.
- `emptyState?: ReactNode`: Replaces the built-in No logs yet state.
- `now?: Date | number`: The clock for relative timestamps. Defaults to the current time, ticking every second.
- `setApi?: (api: LogViewerApi) => void`: Called after mount with { append(lines), clear(), scrollToBottom(), follow(on), getLines() }. append takes a line, a string or arrays of either and batches them into one render per frame.
- `locale?: string` = "": Counts and times. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<LogViewerLabels>`: Every string: log, search, regex, invalidRegex, levels { trace, debug, info, warn, error, fatal }, levelsGroup, wrap, timestamps, follow, live, paused, newLines(count, formatted), jumpToLatest, copy, download, clear, moreActions, actions, cancel, lines(…), errors(…), filtered(…), dropped(…), matches(index, total), previousMatch, nextMatch, empty, emptyDescription, noMatches, noMatchesDescription, clearFilters, showAll(…), details, loading, copied, copyFailed, downloaded(fileName). English defaults in DEFAULT_LOG_VIEWER_LABELS.
- `classNames?: Partial<Record<"toolbar" | "search" | "chips" | "chip" | "actions" | "body" | "row" | "number" | "time" | "level" | "source" | "message" | "meta" | "jump" | "empty" | "status", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root panel, merged last.

Parts:
- `parseLogLine` (function): Parses "2026-09-24T16:38:12.345Z INFO [spv] message", "[16:38:12] WARN message", "ERROR message" and JSON lines with level / msg / time (pino numeric levels too; the other keys become meta). Signature: (text: string) => LogLine.
- `stripAnsi` (function): Removes ANSI escape sequences (colors, cursor moves, links). Signature: (text: string) => string.
- `LOG_LEVELS` (constant): The level recipe (tone, 3-letter tag, row tint, text class), for legends and custom rows. Type: Record<LogLevel, { tone: Tone; tag: string; row: string; text: string }>.

```tsx
import { useEffect, useState } from "react"
import { LogViewer, type LogLine, type LogViewerApi } from "@/components/ui/log-viewer"

const initial: LogLine[] = [
  { time: "2026-09-24T13:38:12.345Z", level: "info", source: "sync", message: "Fetching messages for tax ID 12-3456740" },
  { time: "2026-09-24T13:38:12.902Z", level: "warn", source: "sync", message: "Invoice 2026-0409: slow response, retrying (2/5)" },
  {
    time: "2026-09-24T13:38:13.410Z",
    level: "error",
    source: "validator",
    message: "Validation error: BR-CO-17 tax amount differs",
    meta: { invoice: "2026-0411", code: "BR-CO-17" },
  },
]

export function SyncJobLog({ events }: { events: EventSource }) {
  const [api, setApi] = useState<LogViewerApi | null>(null)

  useEffect(() => {
    if (!api) return
    const onMessage = (event: MessageEvent<string>) => api.append(event.data)
    events.addEventListener("message", onMessage)
    return () => events.removeEventListener("message", onMessage)
  }, [api, events])

  return (
    <LogViewer
      lines={initial}
      setApi={setApi}
      fileName="invoices-4812"
      searchShortcut="mod+shift+f"
      locale="en-US"
      labels={{ search: "Filter the log" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/log-viewer (Markdown: https://wingo-ui.com/components/log-viewer.md)

#### Markdown (`markdown`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add markdown`

Markdown in the library's look: tables that scroll in their own box, highlighted code, task lists, and a streaming mode that never flickers.

Read it like any page: headings keep their levels, links are always underlined (external ones get a small arrow and open in a new tab), done tasks are struck through, and fenced code gets a highlighted block with a copy button. A table wider than the column scrolls sideways inside its own rounded box with soft edge fades, never the page; once it overflows it is a focusable region, so Tab reaches it and the arrow keys scroll it. Tab also stops on each link (Enter follows it), on every code block's scroller and on its copy button. An image that fails to load shows its alt text instead of a broken icon. With streaming on, text arrives without flicker: half-typed bold, code spans, links and table headers stay hidden until they complete, only the last block re-renders, each new block fades in and a caret pulses at the end of the text. Press Replay as a stream in the playground to replay the answer. On a phone the text stays at 15px, long words and links wrap, and tables and code scroll with a swipe. Reduced motion drops the fade and stills the caret.

npm: react-markdown, remark-gfm, lucide-react
Wingo UI dependencies: code-block, use-scroll-edges, tones, ui-config

Props:
- `children?: string | number | null` = "I found **3 overdue invoices** in September, **$22,775.95** in total:\n\n| Client | Invoice | Amount | Late |\n|---|---|---:|---:|\n| Acme Corp | #2026-0405 | $12,480.00 | 1 day |\n| Greenleaf Pharmacy | #2026-0371 | $7,315.20 | 53 days |\n| West Side Books | #2026-0366 | $2,980.75 | 57 days |\n\n**What I suggest:**\n1. A polite reminder to Acme Corp, the due date passed yesterday.\n2. A call to Greenleaf Pharmacy: Daniel Reed, `(503) 555-0118`.\n3. For West Side Books, a formal notice. I can use the **Payment notice** template.\n\nShall I draft the emails?": The markdown source (GitHub flavored: tables, task lists, strikethrough, autolinks, footnotes). null, undefined and an empty string render nothing; other values go through String(). Raw HTML in the source is never rendered.
- `size?: "sm" | "md" | "lg"` = "md": Text size and line height: sm 14 / 24px (side panels, reasoning), md 15 / 28px (chat, notes, comfortable on a phone), lg 16 / 28px (documents). Headings, code and tables scale with it.
- `variant?: "prose" | "compact"` = "prose": prose is a document's rhythm: blocks 1em apart and headings up to 1.6em. compact is a chat's rhythm: blocks 0.75em apart and headings never above 1.2em, so an answer never shouts.
- `streaming?: boolean` = false: Text is still arriving. Half-typed syntax is repaired (completeMarkdown), only the last top-level block re-parses per chunk, new blocks fade in, a caret shows at the end and the root gets aria-busy. Turn it off when the answer completes: the whole source then renders in one pass.
- `caret?: "dot" | "bar" | "block" | "none"` = "dot": The caret at the end of streaming text: a pulsing 10px dot, a thin text-high bar, a block cursor, or none. It sits inline after the last word, and on a line of its own after a code block.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the links, the checked task boxes and the blockquote rail. neutral keeps links in the text color with a soft underline that darkens on hover.
- `color?: string` = "": Any CSS color. Replaces the tone for links, task boxes and the quote rail, mixed for contrast in both themes.
- `codeAccent?: string` = "": The accent of fenced code blocks, a hex color that the whole code theme is built from. Empty keeps code-block's own; set it app-wide with UIProvider defaults={{ "code-block": { accent } }}.
- `codeLineNumbers?: boolean` = false: A line-number gutter in fenced code blocks.
- `codeMaxHeight?: number` = 480: The tallest a code block gets, in px; longer code scrolls inside its block. 0 lets it grow with the code.
- `headingIds?: boolean` = false: Gives h1 to h4 an id from slugifyHeading (What's new becomes whats-new, repeats get -2, -3), for #anchors and a table of contents. Ids a plugin already set are kept.
- `linkTarget?: "auto" | "_blank" | "_self"` = "auto": auto opens absolute http(s) links in a new tab with rel noopener noreferrer nofollow and keeps relative links and #anchors in place; _blank opens every link but #anchors in a new tab; _self never does. Links that open a new tab show a small arrow and say so to screen readers.
- `allowImages?: boolean` = true: false renders every image as a link to it with its alt text, so untrusted model output can never load a tracking pixel by itself.
- `breaks?: boolean` = false: A single newline becomes a line break, as in chat apps and GitHub comments, so signatures, addresses and verse keep their lines. Off follows CommonMark, where a single newline is a space. Code keeps its newlines either way.
- `components?: Components (react-markdown)`: Replace any element, e.g. render crm://client/c01 links as chips. Yours win over the built-in look; each receives the element's props plus the hast node. A code override also receives fenced code (className language-x), as in react-markdown. Keep the object stable (module scope or useMemo), or every block re-renders.
- `remarkPlugins?: PluggableList`: Remark plugins, appended after remark-gfm (always on, single tildes stay text). Keep the array stable.
- `rehypePlugins?: PluggableList`: Rehype plugins, run before the heading ids and the caret. Keep the array stable.
- `urlTransform?: (url: string, key: string, node: Element) => (string | null | undefined)`: Runs on every href and src first. The default, react-markdown's defaultUrlTransform, drops javascript: and other unsafe protocols. An empty result renders the link text without a link. Allow your own scheme with url.startsWith("crm://") ? url : defaultUrlTransform(url).
- `onLinkClick?: (href: string, event: MouseEvent<HTMLAnchorElement>) => void`: Called on every link click, for in-app navigation; call event.preventDefault() to stop the browser. The newest handler is used, so an inline function is fine.
- `labels?: Partial<MarkdownLabels>`: Every string it reads out: streaming "Generating" (sr-only after the caret), image "Image", taskDone "Done", taskOpen "Not done", code (language) => `${language} code`, newTab "(opens in a new tab)", footnotes "Footnotes", footnoteBack (index) => `Back to reference ${index}`.
- `classNames?: Partial<Record<MarkdownSlot, string>>`: Extra classes for the parts: heading, paragraph, link, list, listItem, blockquote, code (the block around a CodeBlock), inlineCode, tableWrapper (the bordered box), table, hr, image, caret.
- `className?: string`: Extra classes for the root, merged last. The root spreads every other div prop (id, aria-*, data-*).

Parts:
- `MarkdownLink` (component): The built-in link (target, rel, the new-tab arrow and its sr-only text, onLinkClick), exported so a components.a override can hand back the links it does not handle: href?.startsWith("crm://") ? <Chip /> : <MarkdownLink {...props} />. Props: MarkdownLinkProps.
- `completeMarkdown` (function): The streaming repair, pure: closes an open code fence, appends closers for unmatched ** __ ~~ ` * _ (snake_case and 2*3 stay as they are), drops a marker with nothing after it, turns a half-typed [text](htt into text, holds a table back until its separator row arrives and drops half-typed list markers, # and >. Never touches code. Signature: (text: string) => string.
- `splitMarkdownBlocks` (function): Splits a source into top-level blocks at blank lines, keeping code fences, loose lists and indented continuations whole. The unit the streaming memo works in. Signature: (text: string) => string[].
- `markdownToText` (function): Plain text for copying and screen reader announcements: syntax stripped, list items on their own lines (bullets become •), table cells joined with tabs, code kept as written. Signature: (text: string) => string.
- `slugifyHeading` (function): The id headingIds uses: lowercase, accents folded, anything but letters and digits turned into dashes (What's new in 4.2 becomes whats-new-in-4-2). Signature: (text: string) => string.
- `DEFAULT_MARKDOWN_LABELS` (constant): The English strings, to spread under your own or translate once in UIProvider defaults. Type: MarkdownLabels.

```tsx
import { useEffect, useRef, useState } from "react"
import { Sparkles } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Markdown } from "@/components/ui/markdown"
import { mockStream } from "@/lib/ai-chat"

const answer = `I found **3 overdue invoices**, **$22,775.95** in total:

| Client | Invoice | Amount |
|---|---|---:|
| Acme Corp | #2026-0405 | $12,480.00 |
| Greenleaf Pharmacy | #2026-0371 | $7,315.20 |

Shall I draft the emails?`

export function AssistantAnswer() {
  const [text, setText] = useState("")
  const [streaming, setStreaming] = useState(false)
  const stream = useRef<AbortController | null>(null)
  useEffect(() => () => stream.current?.abort(), [])

  async function generate() {
    stream.current?.abort()
    const controller = new AbortController()
    stream.current = controller
    setText("")
    setStreaming(true)
    for await (const delta of mockStream(answer, { signal: controller.signal })) setText((t) => t + delta)
    // a restart aborted this stream: the new one owns the flag
    if (stream.current === controller) setStreaming(false)
  }

  return (
    <div className="flex flex-col gap-3">
      <Button variant="soft" size="sm" leftIcon={<Sparkles />} onClick={generate}>
        Generate
      </Button>
      <Markdown streaming={streaming} variant="compact">
        {text}
      </Markdown>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/markdown (Markdown: https://wingo-ui.com/components/markdown.md)

#### Presence (`presence`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add presence`

Who is here right now: an avatar stack with status rings and a who-is-here list, a typing indicator, live cursors and last seen.

People joining pop into the stack on a quick spring and the others slide over; people leaving shrink away, and a status change only recolors the ring, so nobody jumps places. Hover or focus an avatar for the name and what they are doing (a long press on touch). Tap any avatar or the +N chip to open the full list, grouped as here now, away or busy, and offline with the time last seen: a popover on desktop, a bottom sheet on phones. Tab lands on the stack once; Left and Right (Home and End) move between avatars, Enter or Space opens the list, Escape closes it and focus returns to the avatar you pressed. The typing line fades in with the names, lingers 400ms after the last keystroke so it never flickers, and is announced politely. Cursors glide to each new position on a spring (they jump with reduced motion) and their name chip fades to the bare arrow after a few idle seconds. In the playground, Daniel can join and leave and Ryan can come back, while two scripted cursors move over the invoice.

npm: motion
Wingo UI dependencies: avatar, tooltip, popover, relative-time, use-locale, use-controllable-state, use-media-query, motion, tones, ui-config

Props:
- `users: PresenceUser[]`: The people, in display order (put the current user first or last). { id, name, avatar?, color?, status?, lastSeen?, activity?, typing? }; status defaults to online. Duplicate ids: the last one wins, with a warning in development.
- `max?: number` = 4: Avatars shown before the +N chip. When only one would hide, it shows instead of a +1. Fine up to a few hundred people: only max avatars render, the list renders every row (no virtualization).
- `size?: "xs" | "sm" | "md" | "lg"` = "sm": Avatar size, 24 / 32 / 40 / 48px. Every size keeps a 44px hit area on touch screens.
- `indicator?: "ring" | "dot" | "none"` = "ring": ring: a 2px ring in the person's color, dashed amber while away, red while busy, none while offline. dot: the avatar's status dot. none: plain avatars. The status is also in every avatar's spoken label.
- `overlap?: "sm" | "md" | "lg"` = "md": How much neighbors overlap: 16 / 26 / 36% of the size (a little less with rings).
- `surfaceColor?: string` = "": The surface behind the stack, used for the rings that separate the avatars. Empty means var(--background); pass var(--surface) or var(--card) on a panel. Sets --presence-surface.
- `showOffline?: boolean` = false: Keeps offline people in the stack, dimmed and grayscale. Off, they only appear in the list.
- `summary?: boolean` = false: A line after the stack from labels.summary: "Emma, Michael and 3 others are here". Counts everyone who is not offline; wraps to two lines at most on narrow screens.
- `currentUserId?: string`: Marks you with labels.you ("You") in the list and the spoken label, and is what hideSelf leaves out.
- `hideSelf?: boolean` = false: Leaves the current user out of the stack. The list still shows you.
- `showList?: boolean` = true: The +N chip, and any avatar when there is no onUserClick, opens the full list: a popover on desktop, a bottom sheet below 768px. Off, +N is a plain count.
- `tooltips?: boolean` = true: The name, status and activity on hover and keyboard focus (a long press on touch).
- `responsive?: boolean` = true: The list becomes a bottom sheet below 768px.
- `align?: "start" | "center" | "end"` = "end": Which edge of the stack the list popover lines up with on desktop. end suits a stack in the top-right of a header; it shifts to stay on screen either way.
- `defaultOpen?: boolean` = false: Starts with the list open (uncontrolled).
- `open?: boolean`: Controls the list; pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Fires when the list opens or closes.
- `onUserClick?: (user: PresenceUser) => void`: Clicking an avatar (or a list row) calls this instead of opening the list, e.g. to jump to that person's cursor. +N still opens the list.
- `now?: Date | number`: The reference time for last seen. Defaults to the live clock (useNow, once a minute); until it is known after hydration, times print as dates.
- `locale?: string` = "": Locale for last seen times. Empty uses UIProvider's locale, then the page's.
- `labels?: Partial<PresenceLabels>`: Every string: group "People here", more(n) "+n", morePeople(n) "n more people", summary(names, rest), you, unknown, online, away, busy, offline, here "Here now", idle "Away or busy", lastSeen(text) "Seen {text}", at, typing(names). DEFAULT_PRESENCE_LABELS has the English set.
- `classNames?: Partial<Record<"avatar" | "ring" | "overflow" | "summary" | "popover" | "list" | "group" | "row" | "self", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `PresenceList` (component): The list the popover shows, exported for side panels: rows with the avatar and its status dot, the name (and a You chip), the activity, and the status word or last seen. Grouped here now, away or busy, offline. Props: { users; currentUserId?; grouped? = true; onUserClick?; now?; locale?; labels?; classNames? }.
- `TypingIndicator` (component): Pass only the people typing. text: three rising dots and "Julia is typing…" (two names, then "Several people are typing…"); dots: the dots alone; bubble: the dots in a chat bubble. role="status", polite; lingers 400ms after the list empties. Reads UIProvider defaults as "typing-indicator". Props: { users; variant?: "dots" | "text" | "bubble" = "text"; showAvatars? = true; size?: "sm" | "md" | "lg" = "md"; surfaceColor?; labels?; classNames? }.
- `PresenceCursor` (component): One live cursor: an arrow in the person's color with a white (dark mode: black) outline and a name chip with black or white text by contrast. New x / y feed a spring (no re-render per frame); it fades out when hidden or outside its container, and the chip fades to the arrow after idleAfter ms (0 never). Reads UIProvider defaults as "presence-cursor". Props: { user; x; y; label?; mode?: "spring" | "instant" = "spring"; idleAfter? = 5000; hidden?; color?; showName? = true }.
- `PresenceCursors` (component): A pointer-events-none layer (absolute inset-0) over a relative container, one PresenceCursor per { userId, x, y, label? }. relative: x and y are 0 to 1 of the container. Decorative (aria-hidden); the list says who is here. Props: { cursors: CursorPosition[]; users: PresenceUser[]; relative?; mode?; idleAfter?; showNames? = true; classNames? }.
- `LastSeen` (component): A <time> with "Seen 5 min ago", "Seen yesterday at 6:20 PM", then the date; the full date and time in its title. The wording comes from labels.lastSeen. Props: { value; now?; locale?; labels?; prefix? = true }.
- `presenceColor` (function): The user's color, else the stable avatarColor(name): the ring, the cursor and the chip use it. Signature: (user: { name; color? }) => string.
- `DEFAULT_PRESENCE_LABELS` (constant): The English labels, to spread under your own. Type: PresenceLabels.

```tsx
import { Presence, PresenceCursors, TypingIndicator, type PresenceUser } from "@/components/ui/presence"

const users: PresenceUser[] = [
  { id: "ana", name: "Emma Carter", avatar: "/demo/ana-pop.jpg", status: "online" },
  { id: "mihai", name: "Michael Reed", status: "online", activity: "editing the lines" },
  { id: "radu", name: "Ryan Mitchell", status: "away" },
  { id: "vlad", name: "Lucas Grant", status: "offline", lastSeen: Date.now() - 40 * 60_000 },
]

export function InvoiceHeader() {
  return (
    <div className="relative rounded-3xl bg-surface p-5 shadow-raised">
      <div className="flex items-center justify-between gap-3">
        <h2 className="text-lg font-semibold">Invoice #2026-0412</h2>
        <Presence users={users} currentUserId="ana" surfaceColor="var(--surface)" labels={{ group: "Viewing now" }} />
      </div>
      <TypingIndicator users={users.filter((user) => user.typing)} labels={{ typing: (names) => `${names[0]} is writing…` }} />
      <PresenceCursors users={users} cursors={[{ userId: "mihai", x: 0.4, y: 0.6 }]} relative />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/presence (Markdown: https://wingo-ui.com/components/presence.md)

#### Scheduler (`scheduler`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add scheduler`

Book rooms, cars and people on a resource timeline: drag to book, move and stretch bookings, conflicts refused, an agenda on phones.

Resources run down the side in collapsible groups (a click on a group heading folds it) and time runs across: a day in 15, 30 or 60 minute slots, or a week of days, with the hours outside someone's working day shaded, unavailable time hatched with its reason, a red now line and a thin utilization bar under every name. The toolbar steps a day or a week back or forward, Today jumps home and the switch picks Day, Week or Agenda; a click on a day in the week header opens that day. With a mouse, drag across free slots to book: the range snaps to the slots, stops at the next booking and opens a quick-book form under it (title focused, Enter saves, Escape cancels). Drag a booking to another time or resource: it follows the pointer, a ghost shows where it will land (red when that time is taken) and it settles into the slot on release, or shakes and springs back with the reason announced when the time is taken or unavailable. Drag either edge to stretch it; it stops at its neighbours. Near the edges the grid scrolls by itself, and Escape cancels any drag. Click a booking for its details with Edit and Cancel booking. Keyboard: the grid is one Tab stop; Left and Right move through the free slots and bookings of a row (a day at a time in the week view), Up and Down move between resources and group headings (Left and Right fold a heading), Home and End jump to the ends of the row (with Ctrl or Cmd to the first or last resource), PageUp and PageDown go a day or a week back or forward, Shift with Left or Right selects more slots and Enter or Space books them, Enter on a booking opens it, Alt with the arrows moves the focused booking a slot or a resource at a time and Alt with Shift with Left or Right changes where it ends. Moves, stretches, new bookings and conflicts are announced. Touch: the grid scrolls freely; a tap on a free slot opens the booking sheet and a long press on a booking picks it up to move it. When the scheduler is narrower than 576px it becomes an agenda: a strip of the week's days (dots mark busy days), the day's bookings grouped by resource with their times, the resources free all day as chips that book them, and a full-width Book button; bookings open as a bottom sheet with Edit and Cancel booking, and the booking form is a sheet too. Reduced motion turns the settles and slides into instant changes and drops the shake.

npm: lucide-react, motion
Wingo UI dependencies: avatar, badge, button, calendar-view, empty-state, input, popover, segmented-control, select, skeleton, time-picker, tooltip, use-controllable-state, use-locale, use-long-press, date-utils, motion, number-format, relative-time, tones, ui-config

Props:
- `resources: SchedulerResource[]`: The rows: { id, name, avatar?, icon?, description?, group?, capacity?, tone?, color?, unavailable?: { start, end, label? }[], workingHours?: { start, end } }. People get their photo or initials, things their icon in a tile. Outside workingHours (whole hours) the lane is shaded, weekends too; unavailable stretches are hatched with their label and refuse every booking.
- `events?: SchedulerEvent[]` = "[]": The bookings: calendar-view's CalendarEvent (id, title, start, end, allDay?, tone?, color?, location?, description?, attendees?, editable?, meta?) plus resourceId and status?: "confirmed" | "tentative" | "cancelled". Tentative ones are dashed, cancelled ones untinted, muted and struck through, and they never block. A resourceId that is not in resources lands in a "No resource" row. The file also exports findConflicts(events, { start, end, resourceId, id? }): the bookings of that resource that overlap the candidate (cancelled ones never do), to check a booking on the server before it is saved.
- `defaultView?: "day" | "week" | "agenda"` = "day": The view it opens in: the day in slots, the week in days (bookings keep their place in each day's hours), or the agenda of one day.
- `view?: "day" | "week" | "agenda"`: The view, controlled; pair it with onViewChange.
- `onViewChange?: (view: SchedulerView) => void`: When the switch, a week header day or the phone switch changes the view.
- `views?: SchedulerView[]` = "[\"day\",\"week\",\"agenda\"]": The views the switch offers, in order. One view hides the switch; a day in the week header only opens the day view when it is listed.
- `date?: Date`: The day on screen (any day of the week in the week view), controlled; pair it with onDateChange.
- `defaultDate?: Date`: The day it opens on. Left out, the server renders the first booking's day and the scheduler moves to today (from now) once the clock is known; with neither, it shows skeleton lanes until then.
- `onDateChange?: (date: Date) => void`: When the arrows, Today, PageUp / PageDown, the day strip or a week header day change the day.
- `mobileView?: "agenda" | "day"` = "agenda": What it shows when it is narrower than 576px (a container query, so a narrow side panel gets it too and the server HTML is already right on a phone): the agenda with the day strip and the Book button, or the day grid scrolling sideways with the names pinned, for tablets in portrait.
- `layout?: "responsive" | "desktop" | "mobile"` = "responsive": responsive switches to the narrow layout under 576px of its own width; desktop and mobile force one, e.g. a phone frame on a wide screen.
- `dayStartHour?: number` = 8: The first visible hour. An end at or before the start falls back to 8 to 20.
- `dayEndHour?: number` = 20: The hour the visible day ends at. Bookings that run past either edge are cut with an arrow and read as continuing.
- `slotMinutes?: 15 | 30 | 60` = "30": The slot: what dragging, stretching and booking snap to, and one column of the day view. Hour lines are stronger than the ones between.
- `slotWidth?: number` = 48: px per slot in the day view; the slots stretch when the scheduler is wider than they need.
- `dayWidth?: number` = 160: px per day in the week view.
- `rowHeight?: number` = 56: px per resource lane (at least 56px on touch screens, so a booking is a 44px target). A row of overlapping bookings grows by this much per stack.
- `resourceWidth?: number` = 220: px of the pinned resource column; it never takes more than 42% of a narrow scheduler.
- `height?: number` = 640: The most the grid (and the agenda list) grows to before it scrolls, in px. The time header and the names stay pinned while it scrolls both ways. When narrow it also stays within 75% of the screen (the agenda list 60%), so the Book button is always in sight.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: The first day of the week view and the day strip: 0 is Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Sunday in en-US, Monday in en-GB).
- `hideWeekends?: boolean` = false: Leaves the locale's weekend out of the week view and the day strip.
- `groupResources?: boolean` = true: Groups the rows under their resource.group, in the order the groups first appear, each heading folding its rows away.
- `defaultCollapsedGroups?: string[]` = "[]": Group names that start folded.
- `showNowIndicator?: boolean` = true: The red line at the current time, with a dot in the time header. It moves once a minute.
- `showUtilization?: boolean` = true: A thin bar and a percentage under every name: the booked share of its working hours in view, unavailable time left out.
- `toolbar?: boolean` = true: The title, the arrows, Today and the view switch. Off, a page can drive view and date itself.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of bookings that have no tone or color of their own or from their resource, and of the drag-to-book selection, the utilization bars and today's dot.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface: a raised panel. outline: a hairline border on the page. plain: no container, for a page that is only the scheduler.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The panel's corners: 0 / 12 / 16 / 24px (full reads as lg).
- `editable?: boolean` = true: Drag and stretch bookings, drag across free time to book (with onCreateEvent or onSlotSelect), and Edit / Cancel booking in the details. Off, it is an availability view: bookings still open their details. A booking with editable: false stays put either way.
- `allowOverlap?: boolean` = false: Off, a drop, a stretch, a selection or a form save that overlaps another booking of the same resource is refused (the selection stops at the neighbour). On, people can be double-booked and overlapping bookings stack in lanes that grow the row. Unavailable time refuses bookings either way.
- `loading?: boolean` = false: Skeleton lanes in the real row shape (skeleton rows in the agenda); the toolbar keeps working.
- `onEventChange?: (event: SchedulerEvent, change: SchedulerChange) => (void | false | Promise<unknown>)`: After a move, a stretch, an Alt+arrow or the edit form: change is { start, end, resourceId, title? }. The booking moves at once; false or a rejected promise puts it back (announced). Without it moves stay on screen until events change.
- `onCreateEvent?: (input: SchedulerCreateInput) => (void | Promise<unknown>)`: The quick-book form's Save, with { start, end, resourceId, title } (an empty title saves as labels.titlePlaceholder). A promise keeps Save loading and a rejection shows the error in the form. Needed, with editable, for booking from the grid and the Book button.
- `onSlotSelect?: (slot: SchedulerSlot) => void`: Replaces the built-in form: a drag across free time, a click, a tap or Enter on a slot (and the Book button, with a suggested free slot) calls it with { start, end, resourceId }.
- `onEventClick?: (event: SchedulerEvent) => void`: Replaces the details popover (and sheet) when a booking is clicked or tapped.
- `onEventCancel?: (event: SchedulerEvent) => (void | Promise<unknown>)`: Adds Cancel booking to the details of bookings that are not cancelled yet; a promise keeps the button loading.
- `renderEvent?: (event: SchedulerEvent, info: { view: SchedulerView; resource: SchedulerResource | null }) => ReactNode`: Replaces the title and time inside a booking bar (the bar, its color, drag and focus stay).
- `renderEventDetails?: (event: SchedulerEvent) => ReactNode`: Replaces the rows of the details (time, resource, location, attendees); the title, the status and the actions stay.
- `renderResource?: (resource: SchedulerResource, info: { utilization: number | null }) => ReactNode`: Replaces what the pinned resource cell shows; utilization is 0 to 1, or null without working time in view.
- `toolbarActions?: ReactNode`: Extra actions at the end of the toolbar, e.g. an "Export" button or a filter.
- `now?: Date | number`: The current time for today, the now line and the Book button's suggestion. Defaults to a live clock that ticks every minute; demos pin 24.09.2026 16:40.
- `locale?: string` = "": Hours (AM/PM in en-US, 24h in en-GB), day names and the week start. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<SchedulerLabels>`: Every string, English by default: today, previous, next, day, week, agenda, views, resources, caption(period), keyboardHint, book, newBooking, editBooking, title, titlePlaceholder, resource, date, start, end, save, cancel, edit, cancelBooking, close, details, location, attendees, allDay, confirmed, tentative, cancelled, unavailable, noResource, noResources, noBookings, freeAllDay, continues, loading, previousWeek, nextWeek, capacity(count), bookings(count, formatted), utilization(percent), slot(resource, time), timeRange(start, end), event({ title, resource, time, status }), conflict(resource), unavailableConflict(resource), invalidRange, moved(title, resource, time), resized(title, time), created(title, resource, time), cancelledBooking(title), failed(title). DEFAULT_SCHEDULER_LABELS has them all, to spread under a translation.
- `classNames?: Partial<Record<"toolbar" | "title" | "nav" | "switch" | "actions" | "body" | "grid" | "header" | "corner" | "group" | "row" | "resource" | "utilization" | "lane" | "slot" | "event" | "unavailable" | "selection" | "now" | "agenda" | "dayStrip" | "agendaEvent" | "booking" | "details", string>>`: Extra classes for the parts. booking goes on the quick-book panel, details on the details panel.
- `className?: string`: Extra classes for the root, merged last. The rest of the props land on the root too.

```tsx
import { useState } from "react"
import { Car, Presentation } from "lucide-react"
import { Scheduler, type SchedulerEvent, type SchedulerResource } from "@/components/ui/scheduler"

const resources: SchedulerResource[] = [
  { id: "hudson", name: "Hudson room", description: "8 seats · screen", group: "Rooms", icon: <Presentation />, tone: "info" },
  { id: "mihai", name: "Michael Reed", avatar: "/demo/mihai-ionescu.jpg", group: "Team", workingHours: { start: 9, end: 18 } },
  { id: "corolla", name: "Toyota Corolla", description: "NY 12 ACM", group: "Cars", icon: <Car /> },
]

const bookings: SchedulerEvent[] = [
  { id: "r1", resourceId: "hudson", title: "Tech Solutions demo", start: new Date(2026, 8, 24, 10, 0), end: new Date(2026, 8, 24, 11, 30) },
  { id: "r2", resourceId: "mihai", title: "BuildRight Group negotiation", start: new Date(2026, 8, 24, 11, 0), end: new Date(2026, 8, 24, 12, 0), status: "tentative" },
  { id: "r3", resourceId: "corolla", title: "Client visit, Denver", start: new Date(2026, 8, 24, 15, 0), end: new Date(2026, 8, 24, 17, 30) },
]

export function Bookings() {
  const [events, setEvents] = useState(bookings)
  return (
    <Scheduler
      resources={resources}
      events={events}
      defaultDate={new Date(2026, 8, 24)}
      onEventChange={(event, change) =>
        setEvents((list) => list.map((e) => (e.id === event.id ? { ...e, ...change } : e)))
      }
      onCreateEvent={(input) => setEvents((list) => [...list, { id: crypto.randomUUID(), ...input }])}
      onEventCancel={(event) =>
        setEvents((list) => list.map((e) => (e.id === event.id ? { ...e, status: "cancelled" } : e)))
      }
      labels={{
        book: "Reserve",
        newBooking: "New reservation",
        conflict: (resource) => `${resource} is already reserved then`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/scheduler (Markdown: https://wingo-ui.com/components/scheduler.md)

#### Tag (`tag`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tag`

Interactive chips: toggling filter chips, removable tags, chips with a dot, icon, avatar or count, and groups that wrap, scroll or fold.

Click a selectable tag to toggle it: it fills in and a check grows in on a quick spring while the chip widens smoothly. Click × to remove a tag; in a group the others slide into its place. With the keyboard a group is one Tab stop: Left / Right (and Up / Down) move between tags, Home / End jump to the ends, Space / Enter toggle, Backspace / Delete remove the focused tag and focus moves to the next one. A lone tag has its × in the Tab order and Backspace / Delete on it removes it too. In a collapsed group the +N tag opens a popover with the hidden tags; below 768px it is a bottom sheet listing them as rows you tap to toggle or remove. While it is open the rows stay put; newly selected tags move into the row when it closes, and Escape returns focus to +N. On a phone the scroll overflow is a swipeable filter bar that fades at its edges, and every chip and × gets a 44px hit area without growing.

npm: @radix-ui/react-slot, lucide-react, motion
Wingo UI dependencies: avatar, motion, navigation, number-format, popover, tones, ui-config, use-controllable-state, use-locale, use-media-query, use-overflow-items, use-scroll-edges, use-selection

Props:
- `children?: ReactNode` = "New York": The label. Long labels truncate at 16rem and show the full text in a title.
- `variant?: "soft" | "outline" | "solid"` = "soft": soft is a tinted fill (a light gray for neutral), outline a hairline border, solid the full tone fill for the loudest labels.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color from the design tokens; it paints the fill, the text, the border and the dot.
- `color?: string` = "": Any CSS color, for CRM or kanban labels. Replaces the tone; soft and outline mix it for contrast in both themes.
- `size?: "sm" | "md" | "lg"` = "md": 24 / 28 / 32px tall, text 12 / 13 / 14px, icons 12 / 14 / 16px. On touch screens the chip keeps its look and gets a 44px hit area.
- `radius?: "sm" | "md" | "full"` = "full": 6px, 8px or a pill.
- `dot?: boolean` = false: A leading 6px dot in the tone. An icon or an avatar takes its place when set.
- `selectedVariant?: "solid" | "soft"` = "solid": The look while selected: a solid fill in the tone (black / white for neutral, like a pressed filter chip) or a toned soft fill with a border. Unselected filter chips stay neutral, so the tone marks only the selected ones.
- `showCheck?: boolean` = true: The check that scales in and draws itself while selected.
- `icon?: ReactNode`: A leading icon; unsized svgs follow the tag size.
- `avatar?: string | { src?: string; name: string }`: A leading avatar (16 / 20 / 24px). A string is a photo url; with a name the initials show while it loads.
- `count?: number` = "": A trailing muted count ("Overdue 3"), formatted for the locale and read with the label. No count by default. In the demo an empty control shows 1,280 and any text that is not a number hides the count.
- `selectable?: boolean` = false: Makes the tag a toggle button (aria-pressed): a filter chip. For a row of them the file also exports TagGroup: items (TagItem[]: { value, label, textValue?, icon?, avatar?, dot?, tone?, color?, count?, disabled?, removable?, href? }); selectionMode "none" | "single" | "multiple" with value / defaultValue / onValueChange (string[]); onRemove(value) shows × on items (removable: false hides one); overflow "wrap" (default), "scroll" (one swipeable row with faded edges, the phone filter bar) or "collapse" (one row, extra tags fold into +N with selected ones pinned); maxVisible caps the visible tags; size, variant, tone, color, radius, selectedVariant, showCheck and disabled apply to every item (items override tone and color); label is the aria-label; labels, container, locale and classNames (tag, more, popover, row). Roving focus with the arrow keys, Home / End, Backspace / Delete.
- `defaultSelected?: boolean` = false: Starting state while uncontrolled.
- `selected?: boolean`: Controlled selected state; pair it with onSelectedChange.
- `onSelectedChange?: (selected: boolean) => void`: Fires when a selectable tag is toggled.
- `onRemove?: () => void`: Shows the × button. Backspace / Delete on the focused tag call it too.
- `removeLabel?: string` = "Remove": The × button's aria-label, followed by the tag's text: "Remove New York". TagGroup takes a partial labels object instead; the file exports the English defaults as DEFAULT_TAG_LABELS: { more: n => "+" + n, moreLabel: (n, names) => "3 more: Boston, Denver, Seattle", moreTitle: "More", remove: "Remove" }.
- `textValue?: string` = "": The plain text of a label that is not a string, for the remove label and the title.
- `href?: string` = "": Renders the tag as a link through the app's router link (NavLink from lib/navigation). The demo ignores it while asChild is on.
- `onClick?: (event: MouseEvent<HTMLElement>) => void`: Makes a plain pressable tag. On a selectable tag, preventDefault skips the toggle.
- `disabled?: boolean` = false: Dims the tag and blocks pressing and removing it.
- `asChild?: boolean` = false: Renders your single child (an <a>, a router Link) as the pressable part, with the check, icon and count around its content. The demo swaps in a link.
- `locale?: string` = "": Intl locale for the count (1,280 in en-US, 1.280 in de-DE). Empty uses the UIProvider locale, then the page's. The demo passes en-US while it is empty.
- `classNames?: Partial<Record<"button" | "check" | "dot" | "icon" | "avatar" | "label" | "count" | "remove", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the chip, merged last. Override the tone vars here, e.g. [--tone-foreground:white].

```tsx
import { useState } from "react"
import { MapPin } from "lucide-react"
import { Tag, TagGroup, type TagItem } from "@/components/ui/tag"

const CITIES: TagItem[] = [
  { value: "new-york", label: "New York", count: 128 },
  { value: "chicago", label: "Chicago", count: 342 },
  { value: "seattle", label: "Seattle", count: 96 },
  { value: "austin", label: "Austin", count: 74 },
]

export function ListingFilters() {
  const [cities, setCities] = useState<string[]>(["new-york"])
  const [freeShipping, setFreeShipping] = useState(true)
  return (
    <div className="flex flex-col gap-3">
      <TagGroup
        label="Cities"
        items={CITIES}
        selectionMode="multiple"
        value={cities}
        onValueChange={setCities}
        overflow="scroll"
        locale="en-US"
      />
      {freeShipping && (
        <Tag icon={<MapPin />} onRemove={() => setFreeShipping(false)} removeLabel="Remove">
          Free shipping
        </Tag>
      )}
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/tag (Markdown: https://wingo-ui.com/components/tag.md)

#### Timeline (`timeline`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add timeline`

Things that happened, in order: activity feeds, audit trails, changelogs and order tracking, with icons, relative times and day groups.

Read it top to bottom: each event has a marker on the line (a dot, an icon tile in its tone, or the person's avatar), a title, an optional description and a timestamp that stays fresh ("5 min. ago", "yesterday"); hover a timestamp on desktop for the full date and time (use timeFormat "datetime" where people on phones need it). Items with details show a Details button: click or tap it (Enter or Space from the keyboard) and the details slide open while the chevron turns; press again to close. New events slide in at the top and the rest glide down. In the feed variant events sit under day headings ("Today", "Yesterday") that can stick while you scroll. In the tracking variant finished steps get a check, the current step pulses, upcoming ones are hollow, a failed one turns red with an X, and the line fills down to the current step when it scrolls into view. Show older at the end loads more and spins while it waits. Tab only stops on real controls (links in titles, Details, Show older, buttons in meta). On a phone or in a narrow panel the side date column folds under the title and every button has a 44px touch target. Reduced motion drops the stagger, the growth and the pulse.

npm: motion, lucide-react
Wingo UI dependencies: avatar, button, empty-state, skeleton, use-controllable-state, use-locale, motion, relative-time, tones, ui-config

Props:
- `items?: TimelineItemData[]` = "[]": The events: { id, title, description?, time?: Date | string | number, icon?, tone?, color?, status?: "complete" | "current" | "upcoming" | "error", actor?: { name, avatar? }, meta?, details?, href? }. Items without a time sort last and group under labels.earlier.
- `variant?: "default" | "feed" | "tracking"` = "default": default: markers on a line with title, description and time. feed: compact activity rows with avatars and one sentence (bold the names with <b>), grouped by day, no line. tracking: order steps with status markers and a line filled up to the current step.
- `size?: "sm" | "md" | "lg"` = "md": Marker 20 / 28 / 36px (dots 8 / 10 / 12px), title 13 / 14 / 15px, and the spacing between events.
- `markers?: "auto" | "dot" | "icon" | "avatar"` = "auto": auto: the icon when an item has one, else the actor's avatar, else a dot (feeds prefer the avatar). The others force a kind and fall back when an item lacks it. Tracking steps always show their status.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The default marker tone: dots, tracking checks and the filled line. Each item can set its own.
- `color?: string` = "": Any CSS color for the markers; replaces the tone. Items with their own tone keep it.
- `order?: "desc" | "asc" | "none"` = "desc": Sorts by time: desc newest first (feeds, logs), asc oldest first (tracking, where it is the default), none keeps your order. Items without a time go last.
- `groupByDay?: boolean` = false: Day headings ("Today", "Yesterday", "Monday", then the date) in the locale. On by default in the feed variant.
- `stickyGroups?: boolean` = false: Day headings stick to the top of the scroll container. Set --timeline-sticky-top to clear a sticky header and --timeline-bg to the surface color behind them.
- `timeFormat?: "relative" | "time" | "date" | "datetime"` = "relative": relative: "5 min. ago", "yesterday", then the date after 4 weeks (under an older day heading it prints the clock time, since the heading names the day). time: 4:40 PM. date: 9/22/2026. datetime: both. Times refresh every minute.
- `timePosition?: "inline" | "side"` = "inline": inline: the time at the end of the title row. side: a date column on the start side (changelogs, audit logs) once the timeline itself is 512px wide; narrower (a phone, a side panel) it folds under the title. It is a container query, so it follows the space the timeline gets, not the screen.
- `line?: boolean` = true: The connector between markers. Off by default in the feed variant.
- `expandable?: boolean` = true: Items with details get a Details toggle. Off shows every item's details open.
- `expandedKeys?: string[]`: Ids of the items whose details are open (controlled). Pair with onExpandedKeysChange.
- `defaultExpandedKeys?: string[]` = "[]": Ids open at first while uncontrolled.
- `onExpandedKeysChange?: (keys: string[]) => void`: Fires with the open ids when a Details toggle is pressed.
- `loading?: boolean` = false: Skeleton events (marker and two lines) in place of the items, with aria-busy.
- `skeletonCount?: number` = 4: How many skeleton events show while loading (1 to 12).
- `hasMore?: boolean` = false: Shows a Show older button at the end (needs onLoadMore).
- `onLoadMore?: () => (void | Promise<unknown>)`: Called by Show older. A returned promise keeps the button spinning until it settles.
- `loadingMore?: boolean` = false: Spins the Show older button when you track the request yourself (shown while hasMore is on).
- `emptyState?: ReactNode`: Replaces the default <EmptyState size="sm" preset="empty" title={labels.empty} /> when there are no items.
- `error?: ReactNode`: Shows the error empty state with this message in place of the items.
- `onRetry?: () => (void | Promise<unknown>)`: Adds Try again to the error state; a returned promise shows it loading.
- `animateIn?: boolean` = true: Events rise in one after another when the list appears after the page loaded (after skeletons, on a tab switch), at most 12, and new events slide in at the top. Off, new events simply appear while the rest still glide down. Server-rendered lists show at once.
- `locale?: string` = "": Locale for times and day headings, e.g. en-US. Empty uses UIProvider's, then the browser's.
- `labels?: TimelineLabelsInput`: Strings: showDetails ("Details"), hideDetails ("Hide details"), loadMore ("Show older"), earlier ("Earlier"), empty ("No activity yet"), status { complete, current, upcoming, error } read before tracking titles. English defaults in DEFAULT_TIMELINE_LABELS.
- `classNames?: Partial<Record<"group" | "groupLabel" | "list" | "item" | "rail" | "marker" | "content" | "header" | "title" | "description" | "actor" | "meta" | "time" | "toggle" | "details" | "footer", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. Set --timeline-bg here when sticky headings sit on a surface.

```tsx
import { Phone, Receipt } from "lucide-react"
import { Timeline, type TimelineItemData } from "@/components/ui/timeline"

const activity: TimelineItemData[] = [
  {
    id: "payment",
    title: "Invoice #2026-0412 paid",
    description: "$12,480.00 by bank transfer",
    time: "2026-09-24T16:20:00",
    icon: <Receipt />,
    tone: "success",
  },
  {
    id: "call",
    title: "Call with Adam Foster",
    description: "12 min",
    time: "2026-09-23T11:05:00",
    icon: <Phone />,
    actor: { name: "Michael Reed", avatar: "/demo/mihai-ionescu.jpg" },
    details: "Asked for training for 2 new teammates.",
  },
]

export function ClientActivity() {
  return (
    <Timeline
      items={activity}
      locale="en-US"
    />
  )
}

// parts, for events the items API does not cover (same file, same look):
// TimelineRoot takes the appearance props of Timeline (variant, size, tone, color, line, timePosition,
//   timeFormat, locale, labels, classNames) and holds the shared clock and locale;
// TimelineGroup { label, sticky } is a day heading and its <ol>; without a label it is just the list;
// TimelineItem { status, tone, color, expanded, index } is one <li>; status only applies in the tracking
//   variant, where the current step gets aria-current="step";
// TimelineMarker { kind: "dot" | "icon" | "avatar" | "status", icon, actor, children } is the marker and
//   the rail down to the next event (hidden on the last one);
// TimelineContent, TimelineTitle { href }, TimelineDescription: the text column, the title (a link with
//   href; tracking steps read their status first to screen readers) and the secondary text;
// TimelineTime { value, format, placement: "inline" | "side" } is a <time> with dateTime and a full-date
//   title once hydrated; side puts it in the start column on timelines 512px wide and up;
// TimelineDetails { open, defaultOpen, onOpenChange, collapsible } is the Details toggle and its panel;
// DEFAULT_TIMELINE_LABELS holds the English strings to spread a translation over
import { Truck } from "lucide-react"
import {
  TimelineRoot, TimelineGroup, TimelineItem, TimelineMarker, TimelineContent, TimelineTitle,
  TimelineDescription, TimelineTime, TimelineDetails,
} from "@/components/ui/timeline"

export function Delivery({ tracking, sentAt }: { tracking: string; sentAt: string }) {
  return (
    <TimelineRoot variant="tracking" locale="en-US" aria-label="Delivery">
      <TimelineGroup>
        <TimelineItem status="current" index={0}>
          <TimelineMarker kind="icon" icon={<Truck />} />
          <TimelineContent>
            <TimelineTitle href={`/parcels/${tracking}`}>Handed to the courier</TimelineTitle>
            <TimelineDescription>Tracking {tracking}</TimelineDescription>
            <TimelineTime value={sentAt} />
            <TimelineDetails>Estimated delivery tomorrow, between 10 AM and 2 PM.</TimelineDetails>
          </TimelineContent>
        </TimelineItem>
      </TimelineGroup>
    </TimelineRoot>
  )
}
```

Docs: https://wingo-ui.com/components/timeline (Markdown: https://wingo-ui.com/components/timeline.md)

#### Tree View (`tree-view`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tree-view`

Folders, categories or permissions as a tree: animated expand, selection, tri-state checkboxes, filter, lazy children, drag to move.

Click a row to select it; clicking a folder also opens or closes it while its children slide in and the chevron turns on a quick spring, and the chevron alone toggles too. Double click a file (or tap it on a phone) to open it. In multiple mode clicks toggle rows and Shift + click selects a range. With checkboxes, clicking a box checks it and, with cascade, everything under it; parents turn to a dash when only some children are checked. With selectionMode none a click on a file row checks it too, while a click on a folder row only opens it. Keyboard (one Tab stop): ArrowDown and ArrowUp move between visible rows, ArrowRight opens a closed folder or steps into an open one, ArrowLeft closes an open folder or jumps to the parent, Home and End go to the first and last row, PageUp and PageDown jump ten rows, Enter opens a file or toggles a folder, Space selects (or checks with checkboxes), Shift + arrows extend a multiple selection, Ctrl+A (Cmd+A on a Mac) selects every visible row, * opens every folder beside the focused one, typing letters jumps to the next row that starts with them (diacritics ignored), Escape clears a multiple selection, and Shift+F10 or the ContextMenu key opens the row's ⋯ menu. With the filter field, typing filters as you go: matches keep their parents, the path to them opens and matched letters turn bold; ArrowDown moves into the tree and Escape clears the field. Folders with lazy children show a spinner row while they load and a Retry row when loading fails. With draggable on, drag a row with the mouse (or long press it on touch) and a line shows where it lands: before or after a row, or a ring around a folder it goes into; hovering a closed folder opens it, and dropping a folder into itself is refused. Alt + ArrowUp and Alt + ArrowDown move the focused row among its siblings, Alt + ArrowRight moves it into the folder above and Alt + ArrowLeft moves it out one level; every move is announced. On a phone rows grow to 44px, the ⋯ button is always visible and opens a bottom sheet, the whole row is the tap target and the filter field uses 16px text. Huge trees only render the rows in view.

npm: @dnd-kit/core, @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: button, checkbox, dropdown-menu, empty-state, input, spinner, use-controllable-state, use-debounce, use-selection, motion, text-match, tones, ui-config

Props:
- `items: TreeNode[]`: The tree: { id, label, textValue?, icon?, expandedIcon?, children?, hasChildren?, disabled?, badge?, description?, href?, actions?: MenuEntry[], draggable?, droppable? }. Ids must be unique across the whole tree (a dev warning names duplicates). A non-string label needs textValue for filtering and type-ahead.
- `selectionMode?: "none" | "single" | "multiple"` = "single": none: rows only open and act. single: one selected row. multiple: clicks toggle rows, Shift extends a range, Ctrl/Cmd+A selects every visible row.
- `selectedKeys?: string[]`: Selected ids (controlled). Pair with onSelectedKeysChange.
- `defaultSelectedKeys?: string[]`: Selected ids while uncontrolled. Default [].
- `onSelectedKeysChange?: (keys: string[]) => void`: Fires with the new selection, in display order.
- `checkboxes?: boolean` = false: Tri-state checkboxes before the icons, independent of selection: the box checks, the row selects.
- `checkedKeys?: string[]`: Checked ids (controlled). With cascade, fully checked parents are part of the keys too.
- `defaultCheckedKeys?: string[]`: Checked ids while uncontrolled. Default [].
- `onCheckedKeysChange?: (keys: string[]) => void`: Fires with the new checked ids.
- `cascade?: boolean` = true: Checking a parent checks its (loaded, enabled) descendants; a parent is checked when all of them are and shows a dash when some are. Disabled rows are skipped. Needs checkboxes.
- `expandedKeys?: string[]`: Open folder ids (controlled). Ids of nodes that do not exist are ignored.
- `defaultExpandedKeys?: string[]`: Open folder ids while uncontrolled. Default [].
- `onExpandedKeysChange?: (keys: string[]) => void`: Fires when a folder opens or closes, including the folders a filter opens.
- `defaultExpandAll?: boolean` = false: Starts with every folder that has children open (lazy folders stay closed).
- `expandOnClick?: boolean` = true: Clicking a folder row also opens or closes it, like a file explorer. Off: only the chevron and the keyboard do.
- `loadChildren?: (node: TreeNode) => Promise<TreeNode[]>`: Lazy children: a node with hasChildren and no children loads on first expand, with a spinner row; a rejected promise shows a Retry row. Results are cached inside the tree. Filtering only sees loaded nodes.
- `onAction?: (node: TreeNode) => void`: Enter, double click or a tap on a leaf: open the file. Without it a node with href follows its link.
- `searchable?: boolean` = false: A filter field above the tree (16px text on phones, Escape clears it, ArrowDown enters the tree).
- `filter?: string` = "": The filter text (controlled, pair with onFilterChange); works without the field too. Case and diacritics never matter, matches keep their ancestors and open the path to them, debounced 150ms.
- `onFilterChange?: (filter: string) => void`: Fires on every keystroke in the filter field.
- `size?: "sm" | "md" | "lg"` = "md": Rows 28 / 32 / 36px with 13 / 14 / 15px text; 44px on touch screens.
- `indent?: number` = 16: Pixels per level.
- `guides?: boolean` = true: Vertical indent guides; the guide of the focused row's branch is darker.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected row (neutral is a gray tint, other tones their soft fill and text) and the checkboxes.
- `color?: string` = "": Any CSS color; replaces the tone for the selected row and the checkboxes.
- `folderIcons?: boolean` = false: Folder / open folder icons for parents and a file icon for leaves, for nodes without their own icon.
- `draggable?: boolean` = false: Drag rows (long press on touch) to reorder them or drop them into folders, and Alt + arrows to move with the keyboard. Needs onMove.
- `onMove?: (event: TreeMoveEvent) => void`: { id, targetId, position: "before" | "after" | "inside", fromParentId, toParentId, index }. index is the position among the new siblings; moveTreeNode(items, event) applies it to your data.
- `virtualize?: boolean | "auto" | "always" | "never"` = "auto": auto renders only the rows in view above 300 visible rows; true / always and false / never force it. Virtualized trees are flat (aria-level, aria-setsize, aria-posinset), skip the expand animation and default to a 420px scroll box.
- `maxHeight?: number | string` = 0: Makes the tree its own scroll box (px or any CSS length). 0 grows with the rows.
- `emptyText?: string` = "No items": Title of the empty state shown in place of the tree when items is empty. A filter without matches shows labels.noResults with a Clear filter button instead.
- `emptyState?: ReactNode`: Replaces the built-in empty state (an EmptyState with emptyText as its title) when items is empty.
- `labels?: Partial<TreeViewLabels>`: Strings: tree (accessible name), search, noResults, clearFilter, loading, loadError, retry, actions, cancel (the phone sheet), and the move announcements pickedUp, dropBefore, dropAfter, dropInside, notAllowed, dropped, cancelled, moved ({item}, {target}, {position}, {total}). English defaults in DEFAULT_TREE_VIEW_LABELS.
- `classNames?: Partial<Record<"search" | "viewport" | "root" | "item" | "row" | "guides" | "chevron" | "checkbox" | "icon" | "label" | "description" | "badge" | "actions" | "group" | "loading" | "error" | "empty" | "overlay", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the wrapper, merged last.

Parts:
- `flattenTree` (function): Depth-first rows with level, parentId, ancestors, index and setSize; with expandedKeys only the visible ones. Signature: (items: TreeNode[], expandedKeys?: Iterable<string>) => FlatTreeNode[].
- `findNode` (function): Finds a node anywhere in the tree. Signature: (items: TreeNode[], id: string) => TreeNode | undefined.
- `getAncestorIds` (function): The parent chain of a node, top level first. Handy for expandedKeys that reveal a node. Signature: (items: TreeNode[], id: string) => string[].
- `getCheckedState` (function): The cascade state of a node, the same rule the checkboxes use. Signature: (node: TreeNode, checkedKeys: Iterable<string>) => boolean | "indeterminate".
- `moveTreeNode` (function): Applies an onMove event to your data and returns new items; untouched branches keep their identity. Signature: (items: TreeNode[], event: TreeMoveEvent) => TreeNode[].

```tsx
import { useState } from "react"
import { TreeView, moveTreeNode, type TreeNode } from "@/components/ui/tree-view"

const documents: TreeNode[] = [
  {
    id: "clients",
    label: "Clients",
    children: [
      {
        id: "tech",
        label: "Tech Solutions Inc.",
        children: [
          { id: "contract", label: "Contract 2026.pdf" },
          { id: "invoice", label: "Invoice 2026-0412.pdf" },
        ],
      },
      { id: "logistic", label: "Summit Logistics", hasChildren: true },
    ],
  },
  { id: "reports", label: "Reports", children: [{ id: "q3", label: "Q3 2026.xlsx" }] },
]

export function Documents({ onOpen }: { onOpen: (id: string) => void }) {
  const [items, setItems] = useState(documents)
  return (
    <TreeView
      items={items}
      folderIcons
      searchable
      draggable
      defaultExpandedKeys={["clients", "tech"]}
      loadChildren={async () => [{ id: "framework", label: "Framework contract 2025.pdf" }]}
      onAction={(node) => onOpen(node.id)}
      onMove={(event) => setItems((prev) => moveTreeNode(prev, event))}
      labels={{ tree: "Documents", search: "Search documents" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/tree-view (Markdown: https://wingo-ui.com/components/tree-view.md)

### Tables & Lists

#### Audit Log (`audit-log`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add audit-log`

Who did what, when and to which record: a filterable activity log with day groups, before / after diffs and a CSV export.

Search the log (actor, sentence, record and IP match, accents ignored), pick a period with quick ranges (Today, Last 7 days, Last 30 days, This month) and add filter chips for user, action, record type, severity or IP; the count updates and is announced. On desktop each event is a table row under a sticky day heading: click the row or its chevron button (Enter / Space) to open the before / after diff and the technical details, where IP, request id and metadata copy on click. The record in the sentence is a link. Tab reaches the toggles, links and copy buttons in order. Export CSV downloads exactly the events on screen (disabled when there are none). Below 768px the table becomes a feed of day groups: tap a row to expand it inline, the record link moves into the details, the period and filters open as bottom sheets, and Load more is a full-width button (or loads on scroll with autoLoadMore). Rows added by Load more slide in; the first page never animates. With reduced motion the rows and details appear without movement.

npm: motion, lucide-react
Wingo UI dependencies: avatar, badge, button, copy-button, date-range-picker, empty-state, filter-builder, progress, search-input, table, use-controllable-state, use-locale, commerce, date-utils, filters, motion, navigation, number-format, relative-time, spreadsheet, text-match, tones, ui-config

Props:
- `events: AuditEvent[]`: The events, newest first ({ id, at, actor: { id, name, avatar?, kind? }, action, target?: { type, id, label, href? }, summary?, changes?, severity?, ip?, device?, location?, requestId?, metadata? }). Not sorted unless sortOrder says so.
- `actions?: Record<string, AuditActionDef>`: Labels, icons, tones and groups per action key: { "invoice.cancelled": { label: "voided", icon, tone: "warning", group: "Invoices" } }. An unknown key prints the key.
- `targetTypes?: Record<string, string>`: Record type names for the filter and the export: { invoice: "Invoice" }.
- `mode?: "client" | "server"` = "client": client filters, searches and limits the period here. server leaves the events alone and only calls onQueryChange; pass the result and totalCount.
- `onQueryChange?: (query: { search: string; period: DateRange | null; filter: FilterGroup }) => void`: Called 300ms after the search, the period or the filter last changed (never on mount).
- `defaultSearch?: string` = "": The search the log starts with. Use search / onSearchChange to control it.
- `search?: string`: The search, controlled.
- `onSearchChange?: (search: string) => void`: Every keystroke of the search.
- `filter?: FilterGroup`: The filter, controlled (a lib/filters group).
- `defaultFilter?: FilterGroup`: The filter the log starts with; an empty AND group by default.
- `onFilterChange?: (filter: FilterGroup) => void`: Every change of the filter chips.
- `filterFields?: FilterBuilderField<AuditEvent>[]`: The filterable fields. Default defaultAuditFilterFields(actions, the events' actors): user, action, record type, severity, IP.
- `views?: FilterView[]`: Saved views in the builder's menu ("Deletions only", "Critical actions").
- `period?: DateRange | null`: The period, controlled.
- `defaultPeriod?: DateRange | null`: The period the log starts with; null shows everything.
- `onPeriodChange?: (period: DateRange | null) => void`: A picked range, or null when cleared.
- `groupByDay?: boolean` = true: Day headings ("Today", "Yesterday", "Monday, September 21") that stick under the table header. Events out of order land under their own day.
- `sortOrder?: "desc" | "asc" | "none"` = "none": none keeps the order you pass; desc and asc sort by time.
- `expandable?: boolean` = true: Rows with changes or details expand into the before / after diff and the IP, device, location and request id.
- `expandedKeys?: string[]`: The expanded event ids, controlled.
- `defaultExpandedKeys?: string[]`: Event ids expanded at first.
- `onExpandedKeysChange?: (keys: string[]) => void`: A row was opened or closed.
- `timeFormat?: "relative" | "time" | "datetime"` = "relative": relative: "5 min ago" today and the time under older day headings. time: the clock (with the date when not grouped). datetime: date and time.
- `showIp?: boolean` = true: The IP column on desktop. The IP stays in the details either way.
- `showSeverity?: boolean` = true: The severity column: notice, warning and critical as soft badges with an icon; info stays quiet.
- `searchable?: boolean` = true: The search field at the start of the toolbar.
- `filterable?: boolean` = true: The filter builder: chips on desktop, a Filters button with a bottom sheet on phones.
- `showPeriod?: boolean` = true: The period picker with quick ranges.
- `exportable?: boolean` = true: The export button: onExport, or a CSV download of the events on screen. Disabled with no events.
- `onExport?: (events: AuditEvent[], query: AuditLogQuery) => (void | Promise<unknown>)`: Replaces the built-in CSV (a server export). A returned promise shows the button loading; a rejection is announced.
- `exportFileName?: string` = "audit-log": The CSV name before the date: "audit-log-2026-09-24.csv".
- `csvDelimiter?: "," | ";"` = ",": The CSV separator. ";" opens straight in Excel set to a European locale, which reads "," as the decimal mark.
- `onEventClick?: (event: AuditEvent) => void`: The record link's click when the target has no href.
- `renderSummary?: (event: AuditEvent, parts: { actor: ReactNode; verb: ReactNode; target: ReactNode }) => ReactNode`: A custom sentence from the three parts. event.summary replaces the sentence for one event.
- `density?: "compact" | "default"` = "default": Row height: 48px with a second line for times and actor kinds, or 36px on one line.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the search, the period, the export and load-more buttons.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active filter chips and the period's selection.
- `loading?: boolean` = false: Skeleton rows with the real shape (feed rows on phones) in place of the events.
- `skeletonCount?: number` = 8: How many skeleton rows loading shows (phones show at most 6).
- `refreshing?: boolean` = false: Keeps the rows and shows a thin indeterminate bar at the top while a request runs.
- `error?: ReactNode` = "": Replaces the rows with an error state and a Try again button (onRetry). Text or a node is the message; true shows labels.error.
- `onRetry?: () => (void | Promise<unknown>)`: The error state's Try again; a promise shows it loading.
- `emptyState?: ReactNode`: Replaces the empty state when there are no events at all.
- `hasMore?: boolean` = false: Shows Load more under the rows. Big logs page on the server with it.
- `onLoadMore?: () => (void | Promise<unknown>)`: Loads the next page; a returned promise keeps the button loading.
- `loadingMore?: boolean` = false: Shows Load more in its loading state (for a request started elsewhere).
- `autoLoadMore?: boolean` = false: Loads the next page when the Load more button scrolls within 200px of view.
- `maxRows?: number` = 200: Renders at most this many events (0 renders all) and says so under the list. Beyond a few hundred, page on the server with hasMore.
- `totalCount?: number`: The count in the toolbar when the server knows the total (server mode).
- `currency?: string` = "USD": ISO 4217 code for money changes without their own currency.
- `now?: Date | number`: The reference time for relative times and day headings. Default: the current minute (useNow).
- `locale?: string` = "": Dates, times, numbers and money. Empty uses the UIProvider locale, then the browser's.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for record links (default the navigation provider's, else <a>).
- `labels?: Partial<AuditLogLabels>`: Every string, English by default (DEFAULT_AUDIT_LOG_LABELS): search, period, export, count(n, formatted), column names, severities, expand / collapse, emptyValue, fieldCount, rangePresets, csvHeaders and more.
- `filterBuilderProps?: Partial<FilterBuilderProps<AuditEvent>>`: Extra props for the filter builder: its labels, applyMode, onSaveView, defaultActiveViewId.
- `dateRangePickerProps?: Partial<DateRangePickerProps>`: Extra props for the period picker: its labels, min, numberOfMonths, your own presets.
- `classNames?: Partial<Record<"toolbar" | "search" | "period" | "filters" | "export" | "count" | "refreshing" | "table" | "group" | "row" | "details" | "diff" | "meta" | "feed" | "item" | "more" | "empty" | "error", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. Set --table-sticky-top here to sit the sticky header under an app bar.

Parts:
- `AuditDiff` (component): The before / after table alone: values formatted by type (money, number, date, boolean, status badge, list), empty values muted. auto stacks the rows below 448px of room. Props: { changes: AuditChange[]; currency?: string; locale?: string; layout?: "auto" | "table" | "stack"; labels?; classNames? }.
- `defaultAuditFilterFields` (function): The default filter fields: user, action, record type, severity and IP, for your own builder or a server that filters with lib/filters. Signature: (actions, actors, options?: { labels?; targetTypes?; types? }) => FilterBuilderField<AuditEvent>[].
- `auditEventsToCsv` (function): The export's rows (header first) for toCsv / downloadCsv from lib/spreadsheet. Signature: (events: AuditEvent[], options?: { actions?; labels?; targetTypes?; locale?; currency?; header? }) => (string | null)[][].
- `formatAuditValue` (function): A change value as text, the way the diff prints it. Signature: (value: unknown, change: AuditChange, context: { locale; currency; labels }) => string.
- `visibleChanges` (function): The changes with a from or a to (the ones the diff shows). Signature: (changes?: AuditChange[]) => AuditChange[].
- `DEFAULT_AUDIT_LOG_LABELS` (constant): The English strings, to spread under your translations. Type: AuditLogLabels.

```tsx
import { FilePlus2, FileX2, Pencil } from "lucide-react"
import { AuditLog, type AuditActionDef, type AuditEvent } from "@/components/ui/audit-log"

const actions: Record<string, AuditActionDef> = {
  "invoice.issued": { label: "issued", icon: <FilePlus2 />, tone: "info", group: "Invoices" },
  "invoice.cancelled": { label: "voided", icon: <FileX2 />, tone: "warning", group: "Invoices" },
  "client.updated": { label: "updated", icon: <Pencil />, group: "Clients" },
}

const events: AuditEvent[] = [
  {
    id: "e-1",
    at: "2026-09-24T16:35:00",
    actor: { id: "jessica", name: "Jessica Dunn", avatar: "/avatars/jessica.jpg" },
    action: "invoice.cancelled",
    target: { type: "invoice", id: "2026-0398", label: "Invoice #2026-0398", href: "/invoices/2026-0398" },
    severity: "warning",
    changes: [{ field: "status", label: "Status", type: "status", from: { label: "Issued", tone: "info" }, to: { label: "Voided", tone: "danger" } }],
    ip: "93.114.52.211",
    device: "Firefox · Windows",
  },
  {
    id: "e-2",
    at: "2026-09-24T16:12:00",
    actor: { id: "anna", name: "Anna Price" },
    action: "client.updated",
    target: { type: "client", id: "c04", label: "Greenleaf Pharmacy" },
    changes: [{ field: "balance", label: "Balance", type: "money", from: 7315.2, to: 0 }],
  },
]

export function ActivityLog() {
  return (
    <AuditLog
      events={events}
      actions={actions}
      targetTypes={{ invoice: "Invoice", client: "Client" }}
      currency="USD"
      exportFileName="activity-log"
      labels={{ search: "Search activity", export: "Download CSV" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/audit-log (Markdown: https://wingo-ui.com/components/audit-log.md)

#### Data Table (`data-table`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add data-table`

The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones.

Type in the search to filter every searchable column at once (accents do not matter, so "cafe" finds Café and "12480" finds $12,480.00). Press a quick filter chip to toggle it; applied column filters show as removable chips with Clear filters. Click a header to sort (text A to Z first, numbers and dates biggest or newest first, a third click clears it) and Shift-click to add a second sort. The chevron on a header opens its menu: sort, filter (checkboxes for statuses and cities, a text box, a number range or a date range), pin left or right, move left or right, hide. Drag a header sideways to reorder columns; with columnResizing drag its edge (double-click resets, or focus the edge and use the arrows). The Columns panel shows and hides columns, reorders them by dragging the handle or with the arrow buttons, switches density and resets the layout. With selection on, click the checkbox (Shift-click selects a range) or the row; the toolbar turns into the bulk bar with its actions, and when the whole page is selected a banner offers every matching row. Rows can expand into a detail panel with the chevron (or a click anywhere on the row when it has no onRowClick and no selection). The ⋯ button and a right-click open the row's actions. Keyboard: the header's sort buttons and menus come first in the Tab order, then the rows are one tab stop (whenever they can be selected, opened, expanded or have actions): Up / Down, Home / End and PageUp / PageDown move between them, Space selects (Shift + Space or Shift + arrows extend), Ctrl/Cmd + A selects all, Escape clears the selection, Enter opens the row (or expands it when that is all it does), Right / Left expand and collapse, Shift+F10 or the context menu key opens the row menu. On a phone every row is a card: long press a card to start selecting, then tap to add more while the bulk bar floats at the bottom; sort, filters and row menus open as bottom sheets, and Load more appends the next rows. 10,000 rows scroll at 60fps because only the visible ones are in the DOM.

npm: @tanstack/react-table, @tanstack/react-virtual, @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, motion, lucide-react
Wingo UI dependencies: table, progress, empty-state, toolbar, pagination, checkbox, dropdown-menu, context-menu, popover, button, badge, avatar, input, number-input, date-range-picker, segmented-control, skeleton, tooltip, text-match, use-selection, use-persisted-state, use-debounce, use-long-press, use-media-query, use-controllable-state, use-locale, number-format, date-utils, relative-time, motion, tones, ui-config

Props:
- `data: T[]`: The rows. In server mode only the current page.
- `columns: DataTableColumn<T>[]`: Each column: id, header, accessor, cell, type (text, number, currency, percent, date, datetime, relative, badge, boolean, avatar), badge map, align, width / minWidth / maxWidth, sortable, sortingFn, filter (text, select, multi-select, number-range, date-range), filterOptions, searchable, hideable, pinned, resizable, footer (sum, avg, count, min, max, a node or a function), mobile role, headerTooltip, truncate. Build them typed with createColumns<T>().
- `getRowId?: (row: T) => string`: The row's key for selection and expansion (default row.id). Ids must be unique; duplicates print a dev warning.
- `caption?: string` = "": The table's name for screen readers; it also names the card list on phones. Always pass one.
- `searchPlaceholder?: string` = "Search": The toolbar search's placeholder and accessible name. The playground shows its own hint while it holds the default.
- `locale?: string` = "": Numbers, money, dates and relative times ("$12,480.00", "6 days ago"). Empty uses the UIProvider's, then the browser's; the playground falls back to en-US.
- `labels?: Partial<DataTableLabels>`: Every string, English by default (DEFAULT_DATA_TABLE_LABELS): search, columns, densities, rows per page, select all / page / row, the select-all banner, sort / filter / pin / move / hide, clear filters, empty and no results, error and retry, expand / collapse, drag announcements, plus toolbar and pagination strings passed through.
- `mode?: "client" | "server"` = "client": client sorts, filters and pages in the browser. server does none of it locally: data is the current page, rowCount the total, and every change reaches onQueryChange (the page goes back to 1 when the search, a filter or the sort changes).
- `rowCount?: number`: Server mode: the total number of matching rows (default data.length). The last page clamps to it.
- `onQueryChange?: (query: DataTableQuery) => void`: Server mode: { page, pageSize, sorting, globalFilter, columnFilters } whenever one of them changes (the search arrives debounced, 300ms). Set refreshing while you fetch.
- `pagination?: "pages" | "load-more" | "infinite" | "none"` = "pages": pages: numbered pages with a rows-per-page picker (compact on phones). load-more: a button. infinite: loads when the end comes into view (with onLoadMore and hasMore for your own fetching). none: every row, best with virtualize.
- `page?: number`: The current page, 1-based, controlled. Pair it with onPageChange.
- `defaultPage?: number` = 1: The starting page while uncontrolled (clamped to the last page).
- `onPageChange?: (page: number) => void`: Called with the new page.
- `pageSize?: number`: Rows per page, controlled. Also the step of load-more.
- `defaultPageSize?: number` = "25": Rows per page while uncontrolled (remembered with persistKey).
- `onPageSizeChange?: (pageSize: number) => void`: Called when the rows-per-page picker changes.
- `pageSizeOptions?: number[]` = "[10, 25, 50, 100]": The choices in the rows-per-page picker.
- `hasMore?: boolean`: load-more / infinite with your own fetching: whether more rows exist.
- `onLoadMore?: () => (void | Promise<unknown>)`: load-more / infinite with your own fetching: append the next rows to data. Without it the table reveals its own data a page at a time.
- `loadingMore?: boolean` = false: load-more / infinite: the next rows are on their way (the button shows a spinner).
- `sorting?: { id: string; desc: boolean }[]`: The sort, controlled (TanStack's SortingState). Shift-click a header to add a column.
- `defaultSorting?: { id: string; desc: boolean }[]` = "[]": The starting sort while uncontrolled.
- `onSortingChange?: (sorting: DataTableSort[]) => void`: Called with the new sort.
- `globalFilter?: string`: The search, controlled. Client mode matches every word over the searchable columns' text, formatted values included, ignoring case and diacritics.
- `defaultGlobalFilter?: string` = "": The starting search while uncontrolled.
- `onGlobalFilterChange?: (value: string) => void`: Called with the debounced search.
- `columnFilters?: { id: string; value: unknown }[]`: Column filters, controlled. Values: text a string, select a string, multi-select a string[], number-range [min, max] (either may be null), date-range { from, to }.
- `defaultColumnFilters?: { id: string; value: unknown }[]` = "[]": The starting filters while uncontrolled.
- `onColumnFiltersChange?: (filters: DataTableColumnFilter[]) => void`: Called with the new filters.
- `quickFilters?: DataTableQuickFilter<T>[]`: Toggle chips in the toolbar: { id, label, icon?, count?, filter: (row) => boolean } (client) or { id, label, columnFilter: { id, value } } (both modes; chips on the same column act like a radio).
- `columnVisibility?: Record<string, boolean>`: Which columns show, controlled (false hides).
- `defaultColumnVisibility?: Record<string, boolean>` = "{}": The starting visibility, e.g. { createdAt: false }. Reset in the Columns panel returns here.
- `onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void`: Called when a column is shown or hidden.
- `columnOrder?: string[]`: Column ids in display order, controlled. Unknown ids are dropped and new columns appended, so a saved order survives column changes.
- `defaultColumnOrder?: string[]` = "[]": The starting order while uncontrolled; empty follows columns.
- `onColumnOrderChange?: (order: string[]) => void`: Called after a drag, a Move left / right or a Move up / down.
- `selectionMode?: "none" | "single" | "multiple"` = "none": Row selection with checkboxes (and long press on phone cards). multiple adds the header box, ranges, Ctrl/Cmd + A and the bulk bar.
- `selectedKeys?: string[]`: Selected row ids, controlled. They survive paging and filtering: rows filtered out stay selected and the banner says how many are hidden.
- `defaultSelectedKeys?: string[]` = "[]": The starting selection while uncontrolled.
- `onSelectedKeysChange?: (keys: string[]) => void`: Called with the selected ids in display order.
- `selectAllScope?: "page" | "all"` = "page": page: the header box selects the page and a banner offers every matching row (Gmail). all: it selects every row that passes the filters at once (client mode).
- `bulkActions?: (rows: T[], keys: string[]) => ToolbarAction[]`: The toolbar's bulk mode while rows are selected: an inline band on desktop, a floating bar on phones. A danger tone stays red; a returned promise shows the button loading.
- `rowActions?: (row: T) => MenuEntry[]`: A ⋯ column pinned to the end (revealed on hover and focus, always on touch; a sheet on phones), the same menu on right-click, and Shift+F10 on a focused row.
- `onRowClick?: (row: T) => void`: Makes the row the target (Enter on a focused row too). With selection, Shift / Ctrl / Cmd + click selects instead.
- `expandable?: boolean | ((row: T) => boolean)` = false: A chevron column that opens renderSubRow under the row (Right / Left arrows too); a function decides per row.
- `renderSubRow?: (row: T) => ReactNode`: The expanded panel, full width, sliding open with the collapse preset.
- `expandedKeys?: string[]`: Expanded row ids, controlled.
- `defaultExpandedKeys?: string[]` = "[]": The rows expanded at first.
- `onExpandedKeysChange?: (keys: string[]) => void`: Called when a row expands or collapses.
- `toolbar?: boolean` = true: The toolbar above the table: search, quick filters, the Filters and Columns panels, page actions and the bulk bar.
- `toolbarActions?: ToolbarAction[]`: Page actions; the primary one stays visible, the rest fold into ⋯ as space runs out.
- `viewOptions?: boolean` = true: The Columns panel: show and hide columns, drag or Move up / down to reorder, density, Reset.
- `columnMenu?: boolean` = true: The menu on each header: Sort ascending / descending, Clear sort, Filter, Pin left / right / Unpin, Move left / right, Hide.
- `columnReorder?: boolean` = true: Drag headers sideways to reorder them (desktop). The header lifts into a floating chip while it moves.
- `columnResizing?: boolean` = false: Drag handles on the header edges (fixed layout); double-click resets, arrows resize a focused handle. Widths are remembered with persistKey.
- `density?: "compact" | "default" | "comfortable"`: Row height, controlled: 36 / 48 / 56px.
- `defaultDensity?: "compact" | "default" | "comfortable"` = "default": The starting row height while uncontrolled; the Columns panel switches it and persistKey remembers it.
- `onDensityChange?: (density: DataTableDensity) => void`: Called when the density changes.
- `variant?: "plain" | "surface"` = "surface": surface: a raised panel. plain: no panel, a header band, for tables inside cards.
- `striped?: boolean` = false: A faint tint on every other row.
- `stickyHeader?: boolean` = true: The header sticks under --table-sticky-top (default var(--topbar-offset, 0px)) while the page scrolls, or at the top of maxHeight.
- `stickyFirstColumn?: boolean` = false: Pins the selection column and the first data column while the table scrolls sideways; a hairline shadow shows once rows slide under.
- `maxHeight?: number | string` = 0: The table scrolls inside this height in px (and virtualizes against it); 0 or empty lets the page scroll.
- `virtualize?: boolean | "auto"` = "auto": Renders only the rows in view (overscan 10) with spacer rows, so the <table> stays semantic. auto turns on past 200 rendered rows. Phone cards use the page's scroll.
- `persistKey?: string` = "": Remembers column visibility, order, widths, density and page size in local storage under this key.
- `loading?: boolean` = false: The first load: skeleton rows in the real column layout (skeleton cards on phones).
- `skeletonCount?: number` = 8: How many skeleton rows the first load shows.
- `refreshing?: boolean` = false: Keeps the rows and slides a thin indeterminate bar along the top edge; sets aria-busy.
- `error?: ReactNode` = "": Replaces the rows with the error state and this text; pair it with onRetry.
- `onRetry?: () => (void | Promise<unknown>)`: The error state's Try again; a returned promise shows it loading.
- `emptyState?: ReactNode`: Shown when there is no data at all (default an EmptyState with labels.empty).
- `showHeaderWhenEmpty?: boolean` = false: With no rows to show (no data, or a search that matches nothing) the table renders the empty state alone, compact, without column headers spread over nothing. Turn it on to keep the headers above the empty state.
- `noResultsState?: ReactNode`: Shown when the search or filters hide every row (default the no-results EmptyState with Clear filters).
- `mobileLayout?: "cards" | "scroll"` = "cards": Below 768px: a card per row (title, subtitle, a badge or amount, up to four fields), or the table scrolling sideways.
- `renderCard?: (row: T) => ReactNode`: Your own phone card instead of the column mapping.
- `mobilePagination?: "pages" | "load-more"` = "load-more": How phones page through pages mode: Load more appends (the default, it feels native), pages keeps the compact pager. Server mode always pages.
- `classNames?: Partial<Record<"toolbar" | "banner" | "table" | "scroll" | "header" | "head" | "body" | "row" | "cell" | "selectCell" | "actionsCell" | "subRow" | "footer" | "empty" | "cards" | "card" | "pagination", string>>`: Extra classes for the inner parts.

Parts:
- `createColumns` (function): A typed column builder: accessor(key) checks the key against T, computed(id, fn) derives a value, display(id) only renders. Signature: <T>() => ((columns) => DataTableColumn<T>[]) & { accessor(key, column), computed(id, fn, column), display(id, column) }.
- `useDataTable` (hook): The headless part: builds the TanStack v9 table from the same props (features registered once at module scope) and returns the rows to render, the useSelection result, the state and the actions, for custom renderings. Signature: (options: DataTableOptions<T>) => { table, rows, phoneRows, filteredRows, selection, state, columns, actions, loaded }.
- `DEFAULT_DATA_TABLE_LABELS` (constant): The English strings; spread it to translate a few. Type: DataTableLabels.

```tsx
import { Download, Mail, Pencil, Plus, Trash2 } from "lucide-react"
import { DataTable, createColumns } from "@/components/ui/data-table"

type Client = { id: string; name: string; city: string; status: string; balance: number; lastInvoice: string | null }

const col = createColumns<Client>()
const columns = col([
  col.accessor("name", { header: "Client", filter: "text" }),
  col.accessor("city", { header: "City", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" }, Prospect: { tone: "info" } },
    filter: "multi-select",
  }),
  col.accessor("balance", { header: "Balance", type: "currency", footer: "sum", filter: "number-range" }),
  col.accessor("lastInvoice", { header: "Last invoice", type: "relative" }),
])

export function Clients({ clients }: { clients: Client[] }) {
  return (
    <DataTable
      data={clients}
      columns={columns}
      caption="Clients"
      locale="en-US"
      selectionMode="multiple"
      searchPlaceholder="Search clients"
      quickFilters={[{ id: "overdue", label: "Overdue", columnFilter: { id: "status", value: ["Overdue"] } }]}
      toolbarActions={[{ label: "New client", icon: <Plus />, primary: true }]}
      bulkActions={(rows) => [
        { label: "Send email", icon: <Mail /> },
        { label: "Export", icon: <Download />, onSelect: () => console.log(rows) },
        { label: "Delete", icon: <Trash2 />, tone: "danger" },
      ]}
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
      persistKey="clients"
    />
  )
}
```

Docs: https://wingo-ui.com/components/data-table (Markdown: https://wingo-ui.com/components/data-table.md)

#### Deal Pipeline (`deal-pipeline`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add deal-pipeline`

The sales pipeline: stages with weighted totals, a forecast summary, drag between stages with a lost reason, and a list view.

The summary on top reads the open pipeline, the weighted forecast, what was won this month and the win rate (a small ring); on a phone it is a 2 x 2 grid that folds to one line ("Pipeline $224,850 · weighted $118,065") with a tap on its chevron. Each stage is a column: its header shows the count and the probability, the line under it the total and the weighted total, and won and lost columns are tinted green and red. Drag a deal with the mouse (after 8px) or a long press on touch (250ms, with a haptic tick) to another stage: while it is lifted its probability bar already grows or shrinks to the stage under it, and on the drop the header totals fade to their new values. Drop it on Lost and a dialog (a bottom sheet on phones) asks why: arrows pick a reason, Enter confirms, the last reason opens a text field (Cmd / Ctrl + Enter confirms from it), Escape or Cancel sends the card back. A deal dropped on Won pops and shows a green check for a moment. While a move saves, the card shows a spinner; if the save fails, the card springs back and the reason is announced. With the keyboard every card is a Tab stop: Space lifts it, arrows move it (Left / Right change stage), Space drops, Escape cancels, Enter opens it, and Shift + F10 or the Menu key opens its ⋯ menu (Move to, Mark as won, Mark as lost and your own actions). The toolbar switches between Board and List (arrows move inside it), filters by owner with avatar chips that toggle (they scroll sideways on a phone) and hides the closed stages with a switch. The list view is a table grouped by stage, with a band per stage and the deal's value, probability, owner, close date and days in stage; rows open on click or Enter, and on a phone every row is a card. Deals past their close date turn red with a crossed calendar, and deals stuck longer than staleAfterDays in a stage get an amber "18 days in stage" chip. On a phone the board shows one stage at a time with the next one peeking and a chip row to jump between stages. Reduced motion drops the pop, the tilt and the growing bars and keeps short fades.

npm: motion, lucide-react
Wingo UI dependencies: avatar, badge, button, dialog, dropdown-menu, empty-state, kanban, progress, radio-group, segmented-control, skeleton, switch, table, textarea, tooltip, use-controllable-state, use-locale, use-persisted-state, commerce, date-utils, motion, number-format, relative-time, tones, ui-config

Props:
- `stages: DealStage[]`: The stages in order: { id, name, probability (0..1, clamped), kind? ("open" | "won" | "lost", default open), tone?, color?, limit? }. Won stages count 100% and are tinted green, lost stages 0% and tinted red; tone / color paint the column dot and the probability bars; limit is the kanban WIP limit.
- `value?: DealData[]`: The deals in order (controlled): { id, stageId, title, company?: { name, logo? }, contact?, amount, currency?, probability? (overrides the stage's), owner?: { id?, name, avatar? }, expectedCloseDate? ("2026-09-30"), stageEnteredAt?, lastActivityAt?, nextStep?, tags?, priority?, lostReason?, href? }. A deal whose stageId does not exist is not shown (a development warning names it).
- `defaultValue?: DealData[]`: The starting deals while uncontrolled. Empty (the default) shows the first-run state.
- `onValueChange?: (deals: DealData[], move?: DealMove) => void`: The whole new array after a drop, a Move to, Mark as won / lost or an added deal. The moved deal carries its new stageId, stageEnteredAt (the moment of the move) and lostReason. move is undefined for added deals and for rollbacks after a failed save.
- `onDealMove?: (move: DealMove) => (void | boolean | Promise<unknown>)`: Runs for every move with { itemId, fromColumnId, toColumnId, fromIndex, toIndex, deal, from, to, lostReason? }. Return false and the card springs back; return a promise and the move is optimistic (the card shows a spinner) and a rejection puts it back and announces it. A drop on a lost stage calls it once the reason is picked.
- `onDealClick?: (deal: DealData) => void`: A click, a tap or Enter on a card or a list row (not after a drag). Without it, a deal with href opens its link.
- `onAddDeal?: (stageId: string, title: string) => (DealData | Promise<DealData> | void)`: Shows + Add deal under every stage. Return the new deal (or a promise of it) and it lands at the end of the stage; a promise shows Add loading and keeps the text if it rejects. Also the action of the empty pipeline's "Add the first deal".
- `getDealActions?: (deal: DealData) => MenuEntry[]`: Your own entries in the card and row ⋯ menu, after Move to, Mark as won and Mark as lost (the dropdown-menu MenuEntry shape; a bottom sheet on phones).
- `renderCard?: (deal: DealData, state: { dragging: boolean; overlay: boolean }) => ReactNode`: Replaces the default DealCard on the board; the board still wraps it in the draggable, focusable surface with the ⋯ menu at its top end. While a card is lifted, deal.stageId is already the stage under it. Build it from DealCardAmount, DealCardProbability, DealCardOwner, DealCardClose and DealCardStale.
- `lostReasons?: string[]`: The lost dialog's reasons, English by default (DEFAULT_LOST_REASONS: Price, Went with a competitor, No budget, No decision, Other). The last one opens a text field for a reason of your own.
- `requireLostReason?: boolean` = true: Moving a deal into a lost stage opens the reason dialog first; cancelling it springs the card back. Off, the move commits at once without a reason.
- `view?: "board" | "list"`: The view (controlled); pair it with onViewChange.
- `defaultView?: "board" | "list"` = "board": The starting view: the kanban board, or a table grouped by stage (cards on phones).
- `onViewChange?: (view: "board" | "list") => void`: Fires when the Board / List switch changes.
- `persistKey?: string` = "": Remembers the view, the owner filter and the closed switch in localStorage under this key (key:view, key:owners, key:closed). Empty remembers nothing.
- `showSummary?: boolean` = true: The forecast tiles above the toolbar: open pipeline, weighted forecast, won this month and the win rate.
- `showWeighted?: boolean` = true: Weighted totals (amount x probability) in the column headers, the list bands and the summary. Off, the average deal takes the weighted tile's place.
- `showClosed?: boolean`: The won and lost stages (controlled); pair it with onShowClosedChange. Their totals stay in the summary.
- `defaultShowClosed?: boolean` = true: Starts with the won and lost stages shown; the toolbar's switch toggles them.
- `onShowClosedChange?: (show: boolean) => void`: Fires when the closed switch changes.
- `ownerFilter?: string[]`: The owners shown (controlled), by owner.id or else the name; empty shows everyone. Pair it with onOwnerFilterChange.
- `defaultOwnerFilter?: string[]`: The starting owner filter while uncontrolled; empty (the default) shows everyone. The summary follows the filter.
- `onOwnerFilterChange?: (owners: string[]) => void`: Fires when an owner chip or All is pressed.
- `staleAfterDays?: number` = 14: Days in an open stage (from stageEnteredAt) before the card gets the amber "18 days in stage" chip; the list shows the days in the same amber badge. 0 never flags.
- `period?: DateRange`: What "won this month" and the win rate count, by the day a deal entered its won / lost stage (else its expected close date). Default: the month of now.
- `columnWidth?: number` = 288: Stage width in px on wide boards. Narrow boards show one stage at 85% of the width with the next one peeking.
- `cardVariant?: "surface" | "outline"` = "surface": Cards as raised white (dark: #1A1A1A) panels, or outlined with no fill.
- `size?: "sm" | "md"` = "md": Density: md has 12px card padding, 14px titles and 17px summary values; sm is 10px, 13px and 15px, with compact list rows.
- `compactAmounts?: boolean` = true: Column totals in compact notation ("$56.4K · weighted $5.6K"), and summary values from 1,000,000 ("$1.2M"). Cards and the list always show the full amount.
- `currency?: string` = "USD": ISO 4217 code of the pipeline. Deals in another currency (deal.currency) keep their own on the card and are summed apart with a "+ 2 in EUR" note; nothing is converted.
- `readOnly?: boolean` = false: No drag, no + Add deal, no Move to or Mark as won / lost; cards still open and your own actions stay.
- `loading?: boolean` = false: Skeleton tiles in the summary and skeleton cards (or rows) in every stage; the toolbar stays usable.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The open stages' dots and probability bars, the pressed owner chips and the win rate ring. Neutral is black in light mode and white in dark mode; a stage's own tone or color wins.
- `toolbarActions?: ReactNode`: Buttons at the end of the toolbar, like "New deal".
- `now?: Date | number`: The clock for days in stage, overdue dates, the default period and the moment stamped on moved deals. Default useNow(), which is unknown until hydration (those values wait for it).
- `locale?: string` = "": Intl locale for amounts, percentages and dates. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<DealPipelineLabels>`: Every string, merged over DEFAULT_DEAL_PIPELINE_LABELS: summary, open, weighted, won, winRate, averageDeal, noClosed, summaryLine(open, weighted), winRateHint(won, closed), weightedShort(amount), otherCurrency(count, currency, total), probability(percent), toolbar, view, board, list, owners, allOwners, ownerChip(name, count, formatted), showClosed, closeDate(date), overdue(date), stale(days, formatted), owner(name), saving, markWon, markLost, moveTo, actions(deal), sheetTitle, back, close, listCaption, column headers (columnDeal, columnCompany, columnValue, columnProbability, columnOwner, columnClose, columnDays), dealCount, days, noDeals, lostReason, the lost dialog (lostTitle, lostOther, lostOtherPlaceholder, lostConfirm, cancel), the empty state (emptyTitle, emptyDescription, addFirst), announcements (moved(deal, stage, weighted), wonAnnounce, lostAnnounce, refused, failed, cancelled) and kanban (the board's own KanbanLabels).
- `classNames?: Partial<Record<"summary" | "stat" | "toolbar" | "view" | "owners" | "owner" | "closed" | "actions" | "board" | "nav" | "column" | "columnMeta" | "card" | "list" | "table" | "listCard" | "empty" | "lostDialog", string>>`: Extra classes for the inner parts. Full-bleed phone boards pass board: "-mx-4 px-4 scroll-px-4", nav: "-mx-4 px-4" and owners: "-me-4 pe-4".
- `className?: string`: Extra classes for the root. The board fills the root's height: give the pipeline one (or flex-1 in a column) so stages scroll on their own.

Parts:
- `DealCard` (component): The default card: title, company with its logo, amount with the probability and its 3px bar, the stale chip and tags, the next step, then the owner, priority and close date. Inside a pipeline it reads the stage, locale, currency and clock from it; on its own pass them. Props: { deal: DealData; stage?; size?; variant?; currency?; locale?; now?; staleAfterDays?; tone?; labels?; overlay?; classNames? }.
- `DealCardAmount` (component): The amount in the deal's currency ("$18,000"), tabular and never wrapping. Props: { deal: DealData; currency?; locale? } & span props.
- `DealCardProbability` (component): The 3px probability bar (a meter) in the stage's tone; it grows on a gentle spring from where it was when the deal changes stage. Props: { deal: DealData; stage?; tone? } & span props.
- `DealCardOwner` (component): The owner's 24px avatar and name (showName, default true). Props: { deal: DealData; showName?: boolean } & span props.
- `DealCardClose` (component): The expected close date ("30 sept.", full: "30.09.2026"); red with a crossed calendar and a spoken "Overdue since" once an open deal is past it. Props: { deal: DealData; full?: boolean; now? } & span props.
- `DealCardStale` (component): The amber "18 days in stage" badge, only while an open deal is stale. Props: { deal: DealData; staleAfterDays?; now? } & span props.
- `PipelineSummary` (component): The summary strip alone (a <dl> of tiles), for a dashboard: pass deals and stages, or stats you computed. Narrower than 672px it is a 2 x 2 grid, and narrower than 576px a chevron folds it to one line. Props: { deals?; stages?; stats?; period?; now?; currency?; locale?; tone?; size?; showWeighted?; compactAmounts?; staleAfterDays?; loading?; collapsible?; labels?; classNames? }.
- `computePipelineStats` (function): The pure math behind the summary and the headers, for servers and dashboards: { byStage: Record<stageId, { count, total, weighted, foreign }>, open, openCount, weighted, won, wonCount, lost, lostCount, winRate, averageDeal, stale, staleIds, foreign, hasWonStage }. Weighted = amount x (deal.probability ?? stage.probability) over open stages; won and lost count within the period; other currencies are summed apart. Signature: (deals: DealData[], stages: DealStage[], options?: { now?; period?; currency?; staleAfterDays? }) => PipelineStats.
- `DEFAULT_DEAL_PIPELINE_LABELS` (constant): The English strings, to spread under a translation. Type: DealPipelineLabels.
- `DEFAULT_LOST_REASONS` (constant): The English lost reasons: Price, Went with a competitor, No budget, No decision, Other. Type: string[].

```tsx
import { useState } from "react"
import { DealPipeline, type DealData, type DealStage } from "@/components/ui/deal-pipeline"

const stages: DealStage[] = [
  { id: "qualified", name: "Qualified", probability: 0.1 },
  { id: "proposal", name: "Proposal sent", probability: 0.5 },
  { id: "negotiation", name: "Negotiation", probability: 0.75 },
  { id: "won", name: "Won", probability: 1, kind: "won" },
  { id: "lost", name: "Lost", probability: 0, kind: "lost" },
]

export function B2BSales() {
  const [deals, setDeals] = useState<DealData[]>([
    {
      id: "d01",
      stageId: "proposal",
      title: "CRM licenses, 25 users",
      company: { name: "Tech Solutions Inc." },
      amount: 18000,
      owner: { id: "emma", name: "Emma Carter" },
      expectedCloseDate: "2026-09-30",
    },
    {
      id: "d02",
      stageId: "negotiation",
      title: "ERP integration",
      company: { name: "Construct Group" },
      amount: 103400,
      owner: { id: "liam", name: "Liam Walker" },
      expectedCloseDate: "2026-10-15",
    },
  ])
  return (
    <div className="h-[640px]">
      <DealPipeline
        stages={stages}
        value={deals}
        onValueChange={(next) => setDeals(next)}
        onDealMove={(move) =>
          fetch(`/api/deals/${move.deal.id}`, {
            method: "PATCH",
            body: JSON.stringify({ stageId: move.to.id, lostReason: move.lostReason }),
          }).then((response) => {
            if (!response.ok) throw new Error("Not saved")
          })
        }
        lostReasons={["Price", "Chose a competitor", "Not enough budget", "No decision", "Other reason"]}
        persistKey="pipeline-sales"
        locale="en-US"
        labels={{ lostTitle: "Why did we lose this deal?" }}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/deal-pipeline (Markdown: https://wingo-ui.com/components/deal-pipeline.md)

#### Editable Grid (`editable-grid`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add editable-grid`

A spreadsheet-like table: typed cells edited in place, range selection, copy and paste with Excel, undo, validation, 2,000 rows at 60fps.

Click a cell to select it and the outline glides there; Shift+click, Shift+arrows or a mouse drag select a range, a row number selects the row, a column header the column, and Ctrl/⌘+A everything. Type to replace a cell, or press Enter, F2 or double-click to edit it: Enter commits and goes down (Shift+Enter up), Tab commits and goes right, wrapping to the next row (Shift+Tab left), Escape cancels, clicking elsewhere commits. The grid is one Tab stop: outside an edit, Tab moves on to the next control. Selects and dates open their picker; Space toggles checkboxes. Arrows move, Ctrl/⌘+arrows jump to the edges, Home / End go to the row ends, Ctrl/⌘+Home / End to the grid corners, PageUp / PageDown by a page. Ctrl/⌘+C copies the range as tab separated values Excel and Sheets understand, Ctrl/⌘+X cuts, Ctrl/⌘+V pastes a block from the active cell (adding rows when needed), Delete or Backspace clears, Ctrl/⌘+Z undoes and Shift+Ctrl/⌘+Z or Ctrl+Y redoes. Bad values stay in the cell with a red corner and the message under the active cell; the toolbar's error count jumps to the next one. Drag a header edge to resize a column, double-click it to fit. Hover a row number (or right-click, Shift+F10) for insert, duplicate and delete. On a phone the grid scrolls both ways with the first column frozen: tap a cell to select it, tap it again (or the row number) to edit the whole row in a bottom sheet, long press a row number for its actions.

npm: @tanstack/react-virtual, motion, lucide-react
Wingo UI dependencies: button, checkbox, currency-input, date-picker, drawer, dropdown-menu, empty-state, input, number-input, select, tooltip, use-controllable-state, use-locale, use-long-press, use-media-query, commerce, date-utils, motion, number-format, tones, ui-config

Props:
- `columns: GridColumn<R>[]`: The columns: { id (the row key), header, type (text, number, currency, select, date, checkbox), width, minWidth, options, currency, decimals, min, max, step, required, validate, readOnly (or a function of the row), align, format, placeholder, frozen }. Columns are not virtualized; a grid here has fewer than 30.
- `value?: R[]`: The rows, controlled. Every row needs a unique string id. Pair with onValueChange.
- `defaultValue?: R[]` = "[]": The starting rows while uncontrolled.
- `onValueChange?: (rows: R[]) => void`: Every change to the rows: edits, pastes, cleared ranges, added, deleted and restored rows.
- `onCellChange?: (change: GridCellChange) => (void | false | Promise<unknown>)`: One committed cell ({ rowId, columnId, value, previous }). Return false or a rejected promise to put the old value back (save to a server and roll back on failure).
- `onCellsChange?: (changes: GridCellChange[]) => (void | false | Promise<unknown>)`: Batches: a paste, a cleared range, a row saved from the sheet, undo and redo. Same revert contract as onCellChange.
- `createRow?: (index: number) => R` = "() => ({ id: crypto.randomUUID() })": Defaults for new rows (the add row button, inserts, rows a paste appends). An id is generated when it returns none.
- `title?: ReactNode`: The toolbar's title, e.g. the sheet name.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar (export, import, filters).
- `emptyState?: ReactNode` = "an EmptyState with Add the first row": Shown under the headers when there are no rows.
- `labels?: Partial<EditableGridLabels>` = "DEFAULT_EDITABLE_GRID_LABELS": Every string in English: addRow, deleteRows(count, n), insertAbove, insertBelow, duplicate, edit, delete, undo, redo, errors(count, n), required, invalidNumber, invalidDate, notAnOption, tooLow, tooHigh, invalidStep, editRow(index), save, cancel, close, pasted(rows, cols), copied, cleared, rowsDeleted and the rest. The demo passes Romanian with plural rules. The English set is exported as DEFAULT_EDITABLE_GRID_LABELS, to spread under your own.
- `density?: "compact" | "default"` = "default": Row height 32 / 40px (40 / 44px on touch screens) and cell text 13 / 14px.
- `rowHeader?: EditableGridRowHeader` = "number": number, checkbox or none. The leading column: row numbers (click selects the row, hover shows the row menu) or checkboxes for bulk actions (the toolbar offers Delete N rows).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active cell outline, the range and the checkboxes.
- `color?: string` = "": Any CSS color for the outline, the range and the checkboxes. Replaces the tone.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the panel: 0 / 12 / 16 / 24px.
- `showToolbar?: boolean` = true: The toolbar row: title, error count, bulk delete (rows picked by their header or checkbox), undo / redo, and Add row once the rows scroll. A read-only grid with nothing to show there hides it.
- `showErrors?: "cell" | "summary" | "both"` = "both": cell: invalid cells get a tint, a red corner with the message and the message under the active cell. summary: an error count in the toolbar that jumps to the next one. both: the two.
- `height?: number` = 480: Max height of the scroller in px; the header sticks inside it. 0 grows with the rows and never virtualizes.
- `frozenColumns?: number` = 1: Columns that stay at the start edge while you scroll sideways (next to the row header), with a shadow once scrolled.
- `resizableColumns?: boolean` = true: Drag a header's end edge to resize a column; double-click it to fit the content.
- `allowAddRows?: boolean` = true: The Add row button and row, inserts from the row menu, and Enter on the last cell adding a row.
- `allowDeleteRows?: boolean` = true: Delete in the row menu and the row sheet, and bulk delete in the toolbar.
- `allowPasteNewRows?: boolean` = true: A paste taller than the rows left appends rows; off, the extra lines are dropped.
- `validateOn?: "change" | "blur"` = "change": change: the cell editor flags a bad value while you type. blur: only once it is committed. Committed cells are always checked (required, type, min / max / step, options, validate) and bad values are kept so they can be fixed.
- `readOnly?: boolean` = false: Selection and copy only: no editing, paste, add or delete. On phones the row sheet shows the row read-only with a Close button.
- `responsive?: boolean` = true: Below 768px a second tap edits the whole row in a bottom sheet and the row menu is an action sheet.
- `locale?: string` = "": Numbers, money, dates and paste parsing ("1,234.50" is 1234.5 in en-US, "1.234,50" in ro-RO). Empty uses the UIProvider or LocaleProvider locale, then the browser's. The parsers are exported too: parseClipboardGrid(text) splits a copied block (tab separated, or a ; / , CSV) into rows of cells, coerceCellValue(text, column, locale) turns a string into the column's value and keeps text that does not parse.
- `virtualThreshold?: number` = 100: Above this many rows only the visible ones render (fixed row height). Needs a height; 0 always virtualizes.
- `rowReadOnly?: (row: R) => boolean`: Rows that can be selected and copied but not edited (a locked invoice line, an approved timesheet).
- `defaultSelection?: GridSelection`: The selection on mount: { anchor: { rowId, columnId }, focus: { rowId, columnId } }.
- `onSelectionChange?: (selection: GridSelection | null) => void`: Fires when the active cell or the range changes.
- `setApi?: (api: EditableGridApi) => void`: The imperative API: focusCell(ref), startEditing(ref?), addRow(values?, index?) returning the id, deleteRows(ids), undo(), redo(), getSelection(), copySelection(), editRow(id) (opens the row form).
- `classNames?: Partial<Record<EditableGridSlot, string>>`: Extra classes for the parts: toolbar, title, scroller, table, header, corner, columnHeader, row, rowHeader, cell, editor, selection, active, add, empty.
- `className?: string`: Extra classes for the panel, merged last.

```tsx
import { useState } from "react"
import { EditableGrid, type GridColumn, type GridRow } from "@/components/ui/editable-grid"

type Product = GridRow & { name: string; category: string; price: number | null; stock: number | null; active: boolean }

const columns: GridColumn<Product>[] = [
  { id: "name", header: "Product", required: true, width: 240 },
  {
    id: "category",
    header: "Category",
    type: "select",
    options: [
      { value: "licenses", label: "Licenses" },
      { value: "services", label: "Services" },
    ],
  },
  { id: "price", header: "Price before tax", type: "currency", currency: "USD", min: 0 },
  { id: "stock", header: "Stock", type: "number", step: 1, min: 0 },
  { id: "active", header: "Active", type: "checkbox" },
]

export function PriceList() {
  const [rows, setRows] = useState<Product[]>([
    { id: "p-1", name: "Acme CRM Business license (month)", category: "licenses", price: 49, stock: 120, active: true },
    { id: "p-2", name: "Setup and training (hour)", category: "services", price: 65, stock: null, active: true },
  ])
  return (
    <EditableGrid
      title="Price list 2026"
      columns={columns}
      value={rows}
      onValueChange={setRows}
      locale="en-US"
      createRow={() => ({ id: crypto.randomUUID(), name: "", category: "licenses", price: null, stock: null, active: true })}
      labels={{ addRow: "New product" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/editable-grid (Markdown: https://wingo-ui.com/components/editable-grid.md)

#### Kanban (`kanban`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add kanban`

A board of columns and cards for pipelines, orders and tasks: drag with mouse, touch or keyboard, WIP limits, inline add and a phone layout.

Drag a card with the mouse (it lifts after 8px, tilts 2 degrees and casts a floating shadow) to reorder it in its column or drop it in another; the cards below slide apart, a dashed outline marks where it lands, the column under it gets a ring and columns that refuse it dim. Near the board's edges the board scrolls sideways and a long column scrolls on its own. Every card is a Tab stop: Space picks it up, Up / Down move it in its column, Left / Right jump to the nearest spot in the neighbouring column, Space or Enter drops, Escape puts it back; Enter on a resting card opens it, and a screen reader hears where it is ("Tech Solutions moved to Negociere, position 2 of 4"). The ⋯ button on a card (shown on hover or focus, always on touch; Shift + F10 or the Menu key opens it too) has Move to, a submenu of columns, as the way to move without dragging. Column counts read 3 or 3 / 5 with a WIP limit: at the limit the count turns amber, over it red with a one-time pulse and a line of text; limitBehavior="block" refuses drops into a full column instead. + Add card opens a composer: Enter adds (and keeps it open for the next card), Shift + Enter makes a new line, Escape cancels. On a phone the board shows one column at a time with the next one peeking and snaps between them; the chip row on top jumps to a column and lights the one in view; a long press (250ms, with a haptic tick) lifts a card so swipes still scroll, and Move to opens as a bottom sheet. Reduced motion drops the tilt, the pulse and the sliding.

npm: @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, lucide-react, motion
Wingo UI dependencies: avatar, badge, button, date-utils, dropdown-menu, empty-state, motion, number-format, relative-time, skeleton, tag, textarea, tones, ui-config, use-controllable-state, use-locale

Props:
- `columns?: KanbanColumnData[]`: The columns in order: { id, title, textValue?, tone?, color?, limit?, description?, total?, disabled?, collapsed? }. tone / color paint the header dot, limit is the WIP limit, total overrides the summed amounts (null hides it), disabled accepts no drops. Collapsed columns are not in v1.
- `value?: KanbanItem[]`: The cards in order (controlled): { id, columnId, title, textValue?, description?, tags?, assignees?, dueDate?, priority?, amount?, cover?, meta?, disabled? }. A card whose columnId does not exist is not rendered (a dev warning names it). If you do not update value after onValueChange, the card springs back.
- `defaultValue?: KanbanItem[]`: The starting cards while uncontrolled.
- `onValueChange?: (items: KanbanItem[], move?: KanbanMoveEvent) => void`: The whole new array after a drop, a Move to or an added card; move is undefined for added cards.
- `onMove?: (event: KanbanMoveEvent) => (void | boolean)`: Runs before a move commits with { itemId, fromColumnId, toColumnId, fromIndex, toIndex }. Return false to cancel it and the card flies back. Dropping on the same spot fires nothing.
- `renderCard?: (item: KanbanItem, state: { dragging: boolean; overlay: boolean }) => ReactNode`: Replaces the default card. The board still wraps it in the draggable, focusable surface and puts the ⋯ menu at its top end; overlay is true for the lifted copy.
- `onCardClick?: (item: KanbanItem) => void`: A click, a tap or Enter on a card (not after a drag). Open the deal or task here.
- `onAddCard?: (columnId: string, title: string) => (void | KanbanItem | Promise<unknown>)`: Shows + Add card under every column. Return the new card (or a promise of it) and the board inserts it at the end of the column; a promise shows Add loading and keeps the text if it rejects.
- `getColumnActions?: (column: KanbanColumnData) => MenuEntry[]`: The column ⋯ menu, in the dropdown-menu MenuEntry shape (a bottom sheet on phones).
- `getCardActions?: (item: KanbanItem) => MenuEntry[]`: The card ⋯ menu. Move to (a submenu of the other columns) is added in front unless readOnly.
- `limitBehavior?: "warn" | "block"` = "warn": What a column limit does. warn: the count turns amber at the limit and red past it, with a pulse and a line of text. block: a full column refuses drops (it dims while you drag) and its Move to entry is disabled.
- `showCounts?: boolean` = true: The card count next to each column title ("3 / 5" with a limit) and in the phone chips.
- `showTotals?: boolean` = true: The sum of the cards' amounts in each column header, in currency. A column's own total wins.
- `columnWidth?: number` = 288: Column width in px on wide boards. Boards narrower than 576px show one column at 85% of the width with the next one peeking.
- `size?: "sm" | "md"` = "md": Card padding and text: md 12px padding and 14px titles, sm 10px and 13px for dense overview boards.
- `variant?: "tile" | "plain"` = "tile": Columns as flat gray tiles, or transparent with a hairline between them.
- `cardVariant?: "surface" | "outline"` = "surface": Cards as raised white (dark: #1A1A1A) panels, or outlined with no fill.
- `currency?: string` = "USD": ISO 4217 code for card amounts and column totals ("$48,920" in en-US).
- `mobileNav?: boolean` = true: The chip row above a phone board: one chip per column with its count, tap to jump, the column in view lights up.
- `readOnly?: boolean` = false: No drag, no + Add card and no Move to; cards still open and custom card actions stay.
- `loading?: boolean` = false: Three skeleton cards per column with the real card shape (three placeholder columns without columns).
- `locale?: string` = "": Intl locale for counts, amounts and due dates. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<KanbanLabels>`: Every string, merged over DEFAULT_KANBAN_LABELS: region, nav, addCard, addCardPlaceholder, add, cancel, back, empty, emptyBoard, loading, moveTo, sheetTitle, cardActions ({item}), columnActions ({column}), cardCount(count), limit ({limit}), overLimit(count, limit), full, instructions, pickedUp / moved / dropped / cancelled ({item} {column} {n} {total}), movedTo, due / overdue ({date}), assignees ({names}), priority { low, medium, high, urgent }.
- `classNames?: Partial<Record<"nav" | "navItem" | "board" | "column" | "header" | "dot" | "title" | "count" | "total" | "menu" | "description" | "list" | "card" | "cardBody" | "cover" | "cardTitle" | "cardDescription" | "tags" | "cardFooter" | "cardMenu" | "empty" | "footer" | "add" | "composer" | "overlay", string>>`: Extra classes for the inner parts. Full-bleed phone boards pass nav: "-mx-4 px-4" and board: "-mx-4 px-4 scroll-px-4".
- `className?: string`: Extra classes for the root. The board fills its container's height; give the container one so columns scroll on their own.

Parts:
- `KanbanCard` (component): The default card: 16:9 cover, a two-line title, description, a meta line, tags, then due date (red once overdue), priority icon, amount and up to three assignee avatars. Use it inside renderCard to wrap or extend it; inside a board it reads the board's size, variant, currency and locale. Props: { item: KanbanItem; size?; variant?; currency?; locale?; labels?; overlay?; classNames? }.
- `KanbanColumn` (component): One column on its own (a backlog in a side panel, a dashboard widget), with drag, add and menus. Props: KanbanProps & { column: KanbanColumnData }.
- `DEFAULT_KANBAN_LABELS` (constant): The English strings, to spread under a translation. Type: KanbanLabels.

```tsx
import { useState } from "react"
import { Kanban, type KanbanColumnData, type KanbanItem } from "@/components/ui/kanban"

const columns: KanbanColumnData[] = [
  { id: "lead", title: "New lead", tone: "info" },
  { id: "offer", title: "Proposal sent", limit: 5 },
  { id: "won", title: "Won", tone: "success" },
]

export function Pipeline() {
  const [deals, setDeals] = useState<KanbanItem[]>([
    { id: "c02", columnId: "offer", title: "Northwind Logistics", amount: 48920, dueDate: "2026-09-26", tags: [{ label: "VIP", tone: "warning" }] },
    { id: "c05", columnId: "won", title: "Summit Builders", amount: 103400, assignees: [{ name: "Daniel Reed" }] },
  ])
  return (
    <div className="h-[560px]">
      <Kanban
        columns={columns}
        value={deals}
        onValueChange={(next) => setDeals(next)}
        locale="en-US"
        onAddCard={(columnId, title) => ({ id: crypto.randomUUID(), columnId, title })}
        labels={{ empty: "Drop deals here" }}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/kanban (Markdown: https://wingo-ui.com/components/kanban.md)

#### List (`list`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add list`

Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder.

Tap or click a row to open it; navigation rows end in a chevron and tint on hover and press. On a phone, swipe a row left to uncover its trailing actions (Archive, Delete) or right for the leading ones (Mark read): the icons grow in as they come out, a short swipe snaps open, and swiping past 60% runs the outermost action with a haptic tick while a delete slides the row away and the list closes the gap. Only one row stays open; tapping it, tapping elsewhere or scrolling closes it. Long press a row on touch for a bottom sheet with the same actions; on desktop the ⋯ button (shown on hover or focus, always on touch) opens them as a menu, right click does too, and swipeWithMouse lets a mouse drag swipe. Selectable lists are one Tab stop: Up / Down, Home / End and PageUp / PageDown move, Space toggles, Shift + Space, Shift + arrows and Shift + click select a range, Ctrl / Cmd + A selects all, Escape clears, Enter opens. Shift + F10 or the Menu key opens the row menu and focus comes back to the row when it closes; Delete runs an action marked with the delete shortcut. Sortable lists show a grip: drag it (a long press on touch, so the page still scrolls), or focus it and press Space to lift, arrows to move, Space to drop, Escape to cancel; Alt + Up / Down on a focused row or grip moves it one step. Rows enter and leave on a soft spring; reduced motion turns movement into fades and snaps.

npm: @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, @radix-ui/react-slot, lucide-react, motion
Wingo UI dependencies: avatar, button, checkbox, dropdown-menu, empty-state, motion, navigation, progress, skeleton, tones, ui-config, use-controllable-state, use-long-press, use-selection

Props:
- `items?: ListItemData[]`: The rows: { id, title, textValue?, description?, leading?, icon?, iconTone?, iconColor?, avatar?: { src?, name, status? }, trailing?, value?, badge?, href?, onSelect?, disabled?, tone?: "neutral" | "danger" | "brand", chevron?, actions?: MenuEntry[], swipe?: { leading?: SwipeAction[], trailing?: SwipeAction[] } }. trailing may hold controls (a Switch); the row then gets a stretched pressable so nothing nests in a button.
- `groups?: ListGroupData[]`: { id, label?, footer?, items }[]: grouped rows with a small header and a footer note (iOS settings). Replaces items; sorting stays within a group.
- `variant?: "inset" | "plain" | "separated" | "card"` = "inset": inset: the iOS grouped panel (a raised surface with hairlines); plain: full-bleed rows with hairlines, no container; separated: each row its own raised panel with an 8px gap; card: one flat gray tile with hairlines.
- `size?: "sm" | "md" | "lg"` = "md": Row height 44 / 56 / 64px with matching padding, avatars (32 / 40 / 48px) and icon tiles. Every size keeps a 44px target on touch.
- `dividers?: "full" | "inset" | "none"` = "inset": Hairlines between rows. inset starts them at the text, after the icon or avatar (iOS); full spans the row.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the panel (inset, card) or of each row (separated): 0 / 12 / 16 / 24px. First and last rows follow it.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selection color: the checkbox fill, the check mark and the highlight tint.
- `color?: string` = "": Any CSS color for the selection; replaces the tone.
- `iconVariant?: "soft" | "solid" | "plain"` = "soft": Icon tiles: a soft tint (gray, or the icon tone), a solid fill (the iOS settings look, with iconColor), or the bare icon.
- `selectionIndicator?: "auto" | "checkbox" | "check" | "highlight"` = "auto": How a selected row shows: a leading checkbox, a trailing check (iOS pickers) or the row fill alone (with aria-selected). auto is a checkbox for multiple and a check for single.
- `actionsVisibility?: "hover" | "always"` = "hover": The ⋯ row menu button: revealed on hover and focus with a mouse (always visible on touch), or always shown.
- `selectionMode?: "none" | "single" | "multiple"` = "none": none: navigation rows in the Tab order (labelled groups become labelled lists). single / multiple: a listbox with roving focus, Space to toggle, Shift ranges and Ctrl / Cmd + A (through useSelection); give it an aria-label. Inside an option the ⋯ button is pointer-only and Shift + F10 opens the menu.
- `selectedKeys?: string[]`: Controlled selection, in display order. Pair with onSelectedKeysChange.
- `defaultSelectedKeys?: string[]` = "[]": Selection while uncontrolled.
- `onSelectedKeysChange?: (keys: string[]) => void`: Fires with the selected ids in display order.
- `loading?: boolean` = false: Skeleton rows in the row shape (a leading circle when the rows have avatars or icons) inside the same container, with aria-busy.
- `refreshing?: boolean` = false: Keeps the rows and runs a thin indeterminate bar along the top edge of the first group (in the selection tone), with aria-busy. For pull to refresh and background reloads.
- `skeletonCount?: number` = 4: How many skeleton rows show while loading.
- `emptyState?: ReactNode`: Shown when there are no rows; defaults to <EmptyState preset="empty" size="sm" title={labels.empty} />.
- `error?: ReactNode`: Replaces the rows with the error EmptyState, this text as its description.
- `onRetry?: () => (void | Promise<unknown>)`: Adds Try again to the error state; a returned promise shows it loading.
- `showChevron?: boolean` = true: Navigation rows (href or onSelect) end in a chevron. item.chevron overrides it per row.
- `sortable?: boolean` = false: Drag handles (dnd-kit): mouse after 8px, touch after a 250ms press, keyboard with Space and arrows, plus Alt + Up / Down on a focused row or grip. The lifted row floats with a shadow and a slight tilt; groups reorder within themselves.
- `onReorder?: (ids: string[], move: { id: string; from: number; to: number }) => void`: Fires after a drop or an Alt + Arrow move with the new order of that group. The list keeps the new order until you pass new items.
- `swipeable?: boolean` = true: Rows with swipe actions can be swiped on touch. Off: the actions stay in the ⋯ menu and the long-press sheet.
- `swipeWithMouse?: boolean` = false: Mouse drags swipe too. Off, desktop uses the ⋯ menu and right click, so text and clicks behave as usual.
- `fullSwipe?: boolean` = true: Swiping past 60% of the row runs the outermost action (iOS swipe to delete), with a haptic tick when it arms.
- `onAction?: (id: string, item: ListItemData) => void`: Row activation (click, tap, Enter), after the item's own onSelect.
- `getActions?: (item: ListItemData) => (MenuEntry[] | undefined)`: Row menu entries per item, instead of item.actions. The menu also lists the row's swipe actions.
- `labels?: Partial<ListLabels>`: English defaults (DEFAULT_LIST_LABELS): actions "More actions for {item}", select, dragHandle "Drag to reorder {item}", pickedUp, moved "{item} moved to position {n} of {total}.", dropped, cancelled, empty, loading, sheetTitle, cancel.
- `classNames?: Partial<Record<ListSlot, string>>`: Extra classes per part: group, header, items, footer, item, row, select, leading, icon, body, content, title, description, trailing, value, chevron, actions, handle, swipe, swipeAction, overlay, refreshing, empty.
- `className?: string`: Classes for the root. Override the swipe surface with [--list-bg:var(--card)] when the list sits on another surface.

```tsx
import { Archive, Bell, Globe, Trash2, User } from "lucide-react"
import { List, type ListGroupData } from "@/components/ui/list"
import { Switch } from "@/components/ui/switch"

export function Settings({ onDelete }: { onDelete: (id: string) => void }) {
  const groups: ListGroupData[] = [
    {
      id: "account",
      label: "Account",
      items: [
        { id: "profile", title: "Profile", description: "emma.carter@northwind.app", icon: <User />, href: "/settings/profile" },
        { id: "notifications", title: "Notifications", icon: <Bell />, trailing: <Switch defaultChecked aria-label="Notifications" /> },
        { id: "language", title: "Language", icon: <Globe />, value: "English", href: "/settings/language" },
      ],
    },
    {
      id: "clients",
      label: "Recent clients",
      footer: "Swipe a row to the left to archive it.",
      items: [
        {
          id: "c01",
          title: "Acme Corp",
          description: "San Francisco · Nathan Price",
          avatar: { name: "Acme Corp" },
          value: "$12,480.00",
          swipe: {
            trailing: [
              { id: "archive", label: "Archive", icon: <Archive />, tone: "neutral", destructive: true, onSelect: () => onDelete("c01") },
              { id: "delete", label: "Delete", icon: <Trash2 />, tone: "danger", destructive: true, onSelect: () => onDelete("c01") },
            ],
          },
        },
      ],
    },
  ]
  return <List groups={groups} />
}

// parts, for rows the items API does not cover (same file, same look):
// ListRoot takes every appearance and behavior prop of List (variant, size, dividers, radius, tone, color,
//   selectionMode + selection props, sortable + onReorder, swipeable / swipeWithMouse / fullSwipe, onAction(id),
//   labels, classNames) plus keys / disabledKeys (read from the rows when left out); role list, or listbox;
// ListGroup { label, footer, refreshing } holds the variant's surface and animates rows in and out;
// ListItem takes every ListItemData field as a prop plus selected / onSelectedChange (standalone rows),
//   asChild (your router Link as the row), interactive and size; children replace the generated content;
// content parts: ListItemLeading, ListItemIcon { tone, color, variant }, ListItemContent, ListItemTitle,
//   ListItemDescription, ListItemTrailing (sits above the stretched pressable, so controls stay clickable);
// ListItemActions { items: MenuEntry[], open, onOpenChange, title, label } is the ⋯ menu (a sheet on phones);
// ListSortableHandle { label } is the grip of a sortable row (renders nothing outside a sortable list);
// SwipeActions { leading, trailing, disabled, swipeWithMouse, fullSwipe, onOpenChange, onRemovingChange }
//   wraps any row; DEFAULT_LIST_LABELS holds the English strings to spread a translation over
import { Star } from "lucide-react"
import {
  ListRoot, ListGroup, ListItem, ListItemLeading, ListItemIcon, ListItemContent, ListItemTitle,
  ListItemDescription, ListItemTrailing, ListItemActions,
} from "@/components/ui/list"

export function Favorites({ rows }: { rows: { id: string; name: string; city: string; total: string }[] }) {
  return (
    <ListRoot variant="separated" size="lg" aria-label="Favorite clients">
      <ListGroup label="Favorites">
        {rows.map((row) => (
          <ListItem key={row.id} id={row.id} title={row.name} href={`/clients/${row.id}`}>
            <ListItemLeading>
              <ListItemIcon tone="warning" variant="solid">
                <Star />
              </ListItemIcon>
            </ListItemLeading>
            <ListItemContent>
              <ListItemTitle>{row.name}</ListItemTitle>
              <ListItemDescription>{row.city}</ListItemDescription>
            </ListItemContent>
            <ListItemTrailing className="tabular-nums">{row.total}</ListItemTrailing>
            <ListItemActions items={[{ id: "open", label: "Open", href: `/clients/${row.id}` }]} />
          </ListItem>
        ))}
      </ListGroup>
    </ListRoot>
  )
}
```

Docs: https://wingo-ui.com/components/list (Markdown: https://wingo-ui.com/components/list.md)

#### Members table (`members-table`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add members-table`

The team page of a B2B app: members with a role select per row, status, activity and 2FA, pending invitations, seats and an invite dialog.

Switch between Members and Invitations with the tabs (arrow keys move between them) and type in the search to filter by name or email, with the matches highlighted and the result count announced. Click the Member, Role or Last active header to sort (a third click clears it). Pick a new role right in the row: it applies at once with a spinner in the picker and, if the request fails, rolls back with an alert icon and a red outline that stay until the picker is opened again. Your own role and the owner's are locked (hover or focus them for the reason; on a phone your own card says it). The ⋯ menu per row fades in on hover or focus and is always visible on touch; Remove from team asks first, the row slides out once it is done and focus moves to the next row. On the Invitations tab each row can be resent or revoked, and expired ones say so. Invite members opens a dialog focused on the address field: press Enter, comma or space after each address, or paste a whole list ("Ana Pop <ana@firma.ro>; ..."), and addresses that are invalid, already members or already invited are listed under Not added with the reason. Cmd+Enter or Ctrl+Enter sends from the address field or the message; more addresses than free seats keeps Send disabled and explains why, and the new invitations slide into the Invitations tab. Below 768px of its own width (a phone, a narrow settings column) every row is a card with a full-width role picker, two cards to a row from 672px, and the invite button turns into an icon; on a phone the menus, pickers and the dialog become bottom sheets.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, avatar, badge, button, dialog, dropdown-menu, empty-state, progress, search-input, select, table, tabs, tag-input, textarea, tooltip, use-controllable-state, use-locale, motion, number-format, relative-time, text-match, tones, ui-config

Props:
- `members: MemberData[]`: The team: { id, name, email, avatar?, role, status?: "active" | "suspended", lastActiveAt?, joinedAt?, twoFactor?, isYou?, isOwner?, title? }. isYou and isOwner lock the role and removal (owner rules win).
- `roles: MemberRole[]`: The roles the select offers, in rank order: { value, label, description?, disabled? }. A member whose role is not listed shows the raw value with Unknown role.
- `invites?: PendingInvite[]` = "[]": Pending invitations: { id, email, role, invitedAt, invitedBy?: { name, avatar? }, expiresAt? }. Expired ones sort last with an Expired badge and stop reserving a seat.
- `onRoleChange?: (member: MemberData, role: string) => (void | Promise<unknown>)`: Optimistic: the row shows the new role with a spinner while the promise runs; a rejection rolls it back, outlines the select and announces labels.roleError.
- `onRemove?: (member: MemberData) => (void | Promise<unknown>)`: Runs after the confirmation (unless confirmRemove is false). A returned promise keeps the confirmation loading; a rejection shows labels.removeError in it.
- `onInvite?: (input: MemberInviteInput) => (void | Promise<unknown>)`: { emails, role, message? }. Shows the invite button. A returned promise keeps the dialog loading; on success it closes and switches to the Invitations tab, on rejection the error shows under the address field. The dialog is also exported alone as InviteMembersDialog (a bottom sheet on phones): roles, members?, invites?, defaultRole?, defaultEmails?, freeSeats?, onInvite?, showMessage (true), maxMessageLength (500), tone, color, locale, labels, plus the Dialog props (open, defaultOpen, onOpenChange, trigger, responsive, size...); classNames takes the Dialog parts and emails, rejected, role, message, summary, send. splitEmailList(text) splits a pasted list (commas, semicolons, new lines, tabs, spaces, "Name <email>") into lowercased addresses.
- `onResendInvite?: (invite: PendingInvite) => (void | Promise<unknown>)`: Adds Resend invitation to each invitation's menu; the ⋯ button spins while it runs.
- `onRevokeInvite?: (invite: PendingInvite) => (void | Promise<unknown>)`: Adds Revoke invitation. The row leaves at once and comes back if the promise rejects.
- `getActions?: (member: MemberData) => MenuEntry[]`: Extra entries for a member's ⋯ menu, above Remove from team (the W1 MenuEntry shape).
- `confirmRemove?: boolean` = true: Ask before removing someone, in an alert dialog with their name and email. Off, the row leaves at once and comes back if the request fails.
- `canManage?: boolean` = true: false is a member's view: roles read as text, no remove, no invite, no invitation actions.
- `seats?: { used: number; total: number }`: The seats meter in the header. Pending invitations reserve seats (the lighter part of the bar), and the invite dialog refuses more addresses than are free with labels.noSeats.
- `defaultInviteRole?: string` = "": The role picked when the invite dialog opens. Empty picks the last enabled role (the least access).
- `tab?: "members" | "invites"`: The active tab, controlled. Pair it with onTabChange.
- `defaultTab?: "members" | "invites"` = "members": The tab shown first while uncontrolled.
- `onTabChange?: (tab: "members" | "invites") => void`: Called when the tab changes, also after invitations were sent.
- `showInvites?: boolean` = true: The Invitations tab. Off shows the members alone under a heading.
- `searchable?: boolean` = true: The search field. It filters by name and email, ignoring case and diacritics, and highlights the matches.
- `sort?: TableSort | null`: The sort, controlled: { key: "name" | "role" | "lastActive", direction }. null is unsorted.
- `defaultSort?: TableSort | null` = "{ key: \"name\", direction: \"asc\" }": The first sort while uncontrolled. Role sorts by the order of roles, with the owner first.
- `onSortChange?: (sort: TableSort | null) => void`: Called when a header is pressed.
- `showStatus?: boolean` = true: The Status column: Active (success) or Suspended (neutral) badges with a dot.
- `showTwoFactor?: boolean` = true: The 2FA column: a green shield when on, an Off warning badge when not.
- `showLastActive?: boolean` = true: The Last active column (sortable, newest first).
- `timeFormat?: "relative" | "time" | "date" | "datetime"` = "relative": How last activity and sent times read: "5 min ago", a clock time, a date or both.
- `density?: "compact" | "default" | "comfortable"` = "default": Row height 36 / 48 / 56px with a 24 / 32 / 40px avatar. Compact puts the email on the name's line. Cards (below 768px of width) keep one size.
- `variant?: "surface" | "plain"` = "surface": surface sits the table in a raised panel; plain drops the panel, for a table inside a settings card.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The invite button, the active tab's bar, the seats bar and the dialog's Send button.
- `color?: string` = "": Any CSS color in place of the tone.
- `inviteOpen?: boolean`: The invite dialog, controlled. Pair it with onInviteOpenChange.
- `defaultInviteOpen?: boolean` = false: Opens the invite dialog on mount.
- `onInviteOpenChange?: (open: boolean) => void`: Called when the invite dialog opens or closes.
- `responsive?: boolean` = true: Below 768px the role picker, the row menus and the invite dialog open as bottom sheets.
- `loading?: boolean` = false: Skeleton rows (cards on phones) with the real shape: avatar, two lines, a role pill.
- `skeletonCount?: number` = 5: Skeleton rows while loading (at most four cards on phones).
- `emptyState?: ReactNode`: Replaces the empty state shown when there are no members (the default offers the invite button).
- `now?: Date | number`: The reference time for relative times and expiry. Defaults to a live clock that ticks every minute; demos pin 24.09.2026 16:40.
- `locale?: string` = "": Formats times, dates and counts. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<MembersTableLabels>` = "DEFAULT_MEMBERS_TABLE_LABELS": Every string, English by default (DEFAULT_MEMBERS_TABLE_LABELS, exported to spread under a translation): caption, members(count, formatted), invites(count, formatted), invite, search, results, member, role, status, sortAscending / sortDescending / clearSort ({column} is the header text), lastActive, twoFactor, twoFactorOn / Off, you, owner, active, suspended, never, joined(date), roleFor(name), unknownRole, selfRole, ownerRole, roleChanged(name, role), roleError, savingRole, remove, removeTitle(name), removeDescription, removeConfirm, removing, cancel, selfRemove, ownerRemove, removed(name), removeError, actions, actionsFor(name), email, invitedBy, sentAt, expiresAt, expired, expires(date), resend, revoke, resent(email), revoked(email), inviteActionError, seats(used, total), seatsReserved(count), noSeats(free), freeSeats(free), inviteTitle, inviteDescription, emails, emailsPlaceholder, emailsHint, invalidEmail, alreadyMember, alreadyInvited, notAdded, dismiss(email), inviteRole, message, messagePlaceholder, summary(count, formatted, role), send(count), sending, sent(count, formatted), inviteError, close, empty, emptyDescription, noResults, noResultsDescription(query), clearSearch, noInvites, noInvitesDescription.
- `classNames?: Partial<Record<"header" | "tabs" | "search" | "seats" | "invite" | "table" | "row" | "cards" | "card" | "invites" | "empty" | "dialog", string>>`: Extra classes for the parts. dialog goes on the invite dialog's content.
- `className?: string`: Extra classes for the root, merged last. Other props spread onto it.

```tsx
import { useState } from "react"
import { MembersTable, type MemberData, type MemberRole, type PendingInvite } from "@/components/ui/members-table"

const ROLES: MemberRole[] = [
  { value: "admin", label: "Admin", description: "Full access, including billing and the team" },
  { value: "sales", label: "Sales", description: "Clients, quotes and the pipeline" },
  { value: "viewer", label: "Read only", description: "Sees everything, changes nothing" },
]

export function TeamSettings({ initial }: { initial: MemberData[] }) {
  const [members, setMembers] = useState(initial)
  const [invites, setInvites] = useState<PendingInvite[]>([])
  return (
    <MembersTable
      members={members}
      roles={ROLES}
      invites={invites}
      seats={{ used: members.length, total: 12 }}
      onRoleChange={async (member, role) => {
        await fetch(`/api/members/${member.id}`, { method: "PATCH", body: JSON.stringify({ role }) })
        setMembers((list) => list.map((m) => (m.id === member.id ? { ...m, role } : m)))
      }}
      onRemove={async (member) => {
        await fetch(`/api/members/${member.id}`, { method: "DELETE" })
        setMembers((list) => list.filter((m) => m.id !== member.id))
      }}
      onInvite={async ({ emails, role }) => {
        await fetch("/api/invites", { method: "POST", body: JSON.stringify({ emails, role }) })
        setInvites((list) => [
          ...emails.map((email) => ({ id: email, email, role, invitedAt: Date.now() })),
          ...list,
        ])
      }}
      labels={{ invite: "Add teammates", search: "Search the team" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/members-table (Markdown: https://wingo-ui.com/components/members-table.md)

#### Permissions Matrix (`permissions-matrix`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add permissions-matrix`

Who can do what: roles as columns, permissions by module as rows, with dependencies, unsaved-change dots and a per-role list on phones.

Tick a cell to grant a permission to a role; the group row's box grants or clears the whole module and shows a dash while only some are on. Granting a permission that needs others (Issue invoices needs View invoices) ticks them too and the cells that changed on their own flash once; revoking a requirement clears what depends on it, and both are announced. Cells that differ from the saved state get a dot, a faint tint and a count in the toolbar. The Owner column is locked (hover, focus or long-press a cell for why), and a role name cut by a narrow column shows whole on hover or a long press. Type in the search field to keep only the matching rows, with the letters marked and the number of matches at the end of the field; a matching module name keeps the whole module. Click a module name (or press Enter or Space on it) to fold it, during a search too (the next query opens it again); Expand all / Collapse all does every module. The grid is one Tab stop: arrows move between cells, module rows and labels included, Home / End jump to the first / last role, Ctrl or Cmd + Home / End to the corners, PageUp / PageDown move eight rows, Space toggles the focused box or opens the level select. The head sticks while you scroll and the label column stays pinned while wide grids scroll sideways, each gaining a hairline shadow only while something slides under it. Below 768px the grid becomes one accordion card per role with a switch per permission and a switch per module (or role chips over one list with mobileLayout="role-picker"); level selects open as bottom sheets.

npm: motion, lucide-react
Wingo UI dependencies: accordion, badge, button, checkbox, empty-state, search-input, select, switch, tooltip, use-controllable-state, use-media-query, use-scroll-edges, text-match, motion, tones, ui-config

Props:
- `roles: PermissionRole[]`: The columns: { id, name, description?, locked? (every permission, not editable), tone? / color? (a dot and the granted bar), memberCount? }. Zero roles shows an empty state.
- `groups: PermissionGroup[]`: The rows, by module: { id, label, description?, icon?, permissions: { id, label, description?, requires?: string[], dangerous? }[] }.
- `value?: PermissionsValue`: Controlled grants. Boolean mode: Record<roleId, string[]>. Levels mode: Record<roleId, Record<permissionId, level>>. Ids that are not in groups are kept untouched; locked roles are ignored (always everything).
- `defaultValue?: PermissionsValue` = "{}": The grants to start with while uncontrolled.
- `onValueChange?: (value: PermissionsValue, change: { roleId: string; permissionIds: string[]; granted: boolean | string }) => void`: Every change with the next value. permissionIds lists every cell that changed, dependencies included (the one you pressed first). The grid resolves them with the exported resolvePermissionDependencies(groups, value, roleId, permissionId | ids, checked, { mode?, levels?, enforce? }), a pure function you can reuse to validate a change on the server (cycles stop at visited ids).
- `compareTo?: PermissionsValue`: The saved state. Cells that differ get data-changed, a dot (with a screen reader "changed") and a faint tint, and the toolbar shows the count. The exported countPermissionChanges(value, compareTo, { emptyLevel?, ignoreRoles? }) gives the same count for a save bar, on the server too.
- `mode?: PermissionsMatrixMode = "boolean" | "levels"` = "boolean": levels: every cell is a compact ghost select of levels (None / View / Edit / Full), the module row sets all at once.
- `levels?: PermissionLevel[]` = "[{ value: \"none\", label: \"None\" }, { value: \"view\", label: \"View\" }, { value: \"edit\", label: \"Edit\" }, { value: \"full\", label: \"Full\" }]": { value, label, short? } for levels mode; the cell shows short or the label. The first level means not granted, the second is what a requirement is raised to. An unknown value in the data shows as is.
- `defaultSearch?: string` = "": The search to start with, uncontrolled. Pair search / onSearchChange to drive it.
- `search?: string`: Controlled search text.
- `onSearchChange?: (query: string) => void`: Called as the search text changes.
- `searchPlaceholder?: string` = "Search permissions": The search field's placeholder and accessible name.
- `labels?: Partial<PermissionsMatrixLabels>`: Every visible and announced string, English by default (DEFAULT_PERMISSIONS_MATRIX_LABELS): caption, permission, changes(n), changed, locked, requires(names), dangerous, granted(permission, role), revoked(permission, role), levelSet(permission, role, level), alsoGranted(names), alsoRevoked(names), expandAll, collapseAll, noResults, noResultsDescription, clearSearch, results(n) (the match count in the search field, announced), noRoles, noRolesDescription, members(n), count(granted, total), group(label, role), mixed, yes, no, role.
- `density?: "compact" | "default"` = "default": Rows of 40 or 48px; the compact row grows to 44px on touch.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The checkbox, switch, role chip and changed-dot color.
- `color?: string` = "": Any CSS color; replaces the tone. The check turns black or white by lightness.
- `showDescriptions?: boolean` = true: Permission descriptions under their labels (two lines at most).
- `showCounts?: boolean` = true: The granted count ("12/18") and a small bar under every role; on phones the count badge of each role and the count beside each module switch.
- `readOnly?: boolean` = false: Cells become check and dash icons (levels show their name); module rows show a count. All roles locked means read-only too.
- `searchable?: boolean` = true: A search field that keeps only the matching rows (modules with no match hide) and marks the matches.
- `enforceDependencies?: boolean` = true: Granting adds what a permission requires, revoking a requirement revokes its dependents; the cells that changed on their own flash and the change is announced.
- `collapsibleGroups?: boolean` = true: Module rows fold their permissions away; adds Expand all / Collapse all to the toolbar.
- `defaultCollapsedGroups?: string[]` = "[]": Module ids folded at first.
- `stickyHeader?: boolean` = true: The role row sticks to the top of the scroller (or of the page at --topbar-offset when maxHeight is 0 and the grid fits sideways).
- `maxHeight?: number` = 0: Caps the grid's height in px so it scrolls inside; 0 grows with the page.
- `mobileLayout?: "accordion" | "role-picker"` = "accordion": Below 768px: one accordion card per role with switches, or a row of role chips over one list. The grid never scrolls sideways on a phone.
- `layout?: "auto" | "grid" | "list"` = "auto": auto: the grid from 768px, the phone list below. grid or list force one, e.g. list in a narrow side panel.
- `onRoleClick?: (role: PermissionRole) => void`: Turns the role headers into buttons (edit the role); they join the grid's arrow navigation.
- `classNames?: Partial<Record<"toolbar" | "search" | "changes" | "expandAll" | "panel" | "scroller" | "table" | "head" | "role" | "group" | "groupToggle" | "row" | "permission" | "cell" | "mobile" | "mobileRole" | "empty", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root; the remaining props spread onto it.

```tsx
import { useState } from "react"
import { FileText, Users } from "lucide-react"
import {
  PermissionsMatrix,
  countPermissionChanges,
  type PermissionGroup,
  type PermissionRole,
  type PermissionsValue,
} from "@/components/ui/permissions-matrix"

const roles: PermissionRole[] = [
  { id: "owner", name: "Owner", locked: true, memberCount: 1 },
  { id: "sales", name: "Sales", memberCount: 3 },
  { id: "accounting", name: "Accounting", memberCount: 1 },
]

const groups: PermissionGroup[] = [
  {
    id: "clients",
    label: "Clients",
    icon: <Users />,
    permissions: [
      { id: "clients.view", label: "View clients" },
      { id: "clients.delete", label: "Delete clients", requires: ["clients.view"], dangerous: true },
    ],
  },
  {
    id: "invoices",
    label: "Invoices",
    icon: <FileText />,
    permissions: [
      { id: "invoices.view", label: "View invoices" },
      { id: "invoices.issue", label: "Issue invoices", requires: ["invoices.view"] },
    ],
  },
]

const saved: PermissionsValue = { sales: ["clients.view"], accounting: ["clients.view", "invoices.view", "invoices.issue"] }

// 1 change, 3 changes
const changesLabel = (n: number) => (n === 1 ? "1 change" : `${n} changes`)

export function RolePermissions() {
  const [value, setValue] = useState<PermissionsValue>(saved)
  const changes = countPermissionChanges(value, saved, { ignoreRoles: ["owner"] })
  return (
    <div className="flex flex-col gap-3">
      <PermissionsMatrix
        roles={roles}
        groups={groups}
        value={value}
        onValueChange={setValue}
        compareTo={saved}
        searchPlaceholder="Search permissions"
        labels={{ changes: changesLabel, permission: "Permission", caption: "Permissions by role" }}
      />
      {changes > 0 && <p className="text-sm text-muted-foreground">{changesLabel(changes)} to save</p>}
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/permissions-matrix (Markdown: https://wingo-ui.com/components/permissions-matrix.md)

#### Table (`table`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add table`

The library's one table look: semantic table parts plus a props API for small read-only tables that turn into cards on phones.

Click a sortable header to sort: text sorts A to Z first, numbers and dates biggest or newest first, a third click clears it, and the arrow flips on a spring. Clickable rows tint on hover and press; Tab reaches each row's first cell, where Enter or Space opens it, and the row shows a focus ring; Shift+F10 or the context menu key opens that row's actions menu. Row actions fade in on hover or focus and stay visible on touch. A table wider than its box scrolls sideways with a fade at the edge that still has content, and a pinned first column casts a hairline shadow once rows slide under it. On a phone every row becomes a card (title, amount at the top end, up to four label and value pairs, a Show more toggle for the rest), totals move into their own card, clickable cards dip when pressed, and a row of Sort by chips above the cards sorts them the way the headers do (tap to cycle, the arrow shows the direction). The stack layout lists receipt lines instead (pressable when rows are clickable) and the scroll layout keeps the table with its first column pinned.

npm: motion, lucide-react
Wingo UI dependencies: empty-state, skeleton, use-controllable-state, use-locale, use-scroll-edges, date-utils, motion, number-format, ui-config

Props:
- `caption?: ReactNode` = "": The table's name. It stays for screen readers even when hidden, and names the card list on phones. Always pass one. The playground falls back to the invoice number.
- `hideCaption?: boolean` = true: Keeps the caption for screen readers only. Turn it off to show it under the table.
- `emptyTitle?: string` = "No data": Title of the default empty state (the playground's Clear button empties the invoice).
- `variant?: "plain" | "surface" | "lined"` = "surface": surface is a raised panel with a hairline under the header; plain has no container and a tinted header band; lined keeps only the horizontal hairlines, for tables inside a card.
- `density?: "compact" | "default" | "comfortable"` = "default": Row height 36 / 48 / 56px with matching padding and type.
- `striped?: boolean` = false: Tints every second row with a 2.5% foreground wash.
- `loading?: boolean` = false: Skeleton rows (and skeleton cards on phones) in the real column layout, with aria-busy.
- `skeletonCount?: number` = 5: How many skeleton rows or cards show while loading.
- `showFooter?: boolean` = true: The footer row with each column's footer (totals). Automatic when any column has a footer; false hides it. On phones the totals become their own card.
- `stickyHeader?: boolean` = false: The header sticks while rows scroll: to the page (offset by --table-sticky-top, e.g. var(--topbar-offset)), or to the table's own box with maxHeight.
- `stickyFirstColumn?: boolean` = false: The first column stays put while scrolling sideways and casts a hairline shadow once rows slide under it.
- `maxHeight?: number | string` = 0: Caps the table's height (px or any CSS length); the rows scroll inside with a fade at the bottom. 0 means no cap.
- `mobileLayout?: "cards" | "scroll" | "stack"` = "cards": Below 768px: cards (each row a card), scroll (the table scrolls sideways with its first column pinned) or stack (label and value lines without card chrome, for receipts). Both layouts are in the server HTML, so nothing jumps.
- `mobileSort?: boolean` = true: Below 768px, a row of Sort by chips above the cards or stack, one per sortable column, since the headers are not there to press. Hidden when nothing is sortable.
- `cardVariant?: "separate" | "grouped"` = "separate": Phone cards as separate raised cards, or one iOS-style grouped panel with hairlines.
- `locale?: string` = "": Intl locale for numbers, money and dates ("$12,480.00", "9/18/2026" in en-US). Empty uses the UIProvider's, then the browser's. The playground falls back to en-US.
- `currency?: string` = "USD": ISO 4217 code for currency columns that do not set their own.
- `columns: TableColumn<T>[]`: { key, header, accessor?, cell?, type?: "text" | "number" | "currency" | "percent" | "date" | "datetime" | "boolean", currency?, align?, width?, minWidth?, sortable?, sortValue?, truncate?, footer?: ReactNode | ReactNode[], mobile?: "title" | "subtitle" | "meta" | "field" | "hidden", className?, headerClassName? }. Numbers end-align with tabular figures; cell always wins over the type. On phones the first column is the card title and the last numeric one its top-end value unless mobile says otherwise.
- `data: T[]`: The rows. A column without accessor reads row[key]; empty values show a muted dash.
- `getRowKey?: (row: T, index: number) => string` = "row.id ?? index": A stable key per row. Duplicate keys log a warning in development.
- `sort?: { key: string; direction: "asc" | "desc" } | null`: Controlled sort. When set (null included), the table only draws the arrows and leaves sorting the data to you.
- `defaultSort?: { key: string; direction: "asc" | "desc" } | null` = "null": Starting sort while uncontrolled; the table sorts on the client with a locale-aware collator.
- `onSortChange?: (sort: TableSort | null) => void`: Fires on every header press, controlled or not.
- `onRowClick?: (row: T) => void`: Makes rows clickable. The first cell renders a real button for the keyboard; clicks on controls inside the row (menus, links) never open it.
- `isRowSelected?: (row: T) => boolean`: Paints rows (and cards) as selected. Behavior stays with you; data-table owns selection.
- `rowActions?: (row: T) => ReactNode`: A trailing cell on desktop (revealed on hover or focus, always on touch) and the card's top-end slot on phones, typically a DropdownMenu with a "⋯" trigger.
- `renderCard?: (row: T, index: number) => ReactNode`: Your own phone card, built from the TableCard parts.
- `emptyState?: ReactNode` = "<EmptyState size=\"sm\" />": Replaces the default empty state, spanning every column.
- `labels?: Partial<TableLabels>`: Strings: sortAscending / sortDescending / clearSort ("Sort by {column}, ascending"), empty, actions, showMore, showLess, yes, no, totals, sortBy. DEFAULT_TABLE_LABELS holds the English defaults.
- `classNames?: Partial<Record<"root" | "scroll" | "table" | "caption" | "header" | "head" | "body" | "row" | "cell" | "footer" | "empty" | "cards" | "card" | "cardTitle" | "cardFields" | "stack", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the outer wrapper that holds the table and its phone layout.

```tsx
import { Table, type TableColumn } from "@/components/ui/table"

type Line = { id: string; product: string; qty: number; price: number; vat: number }

const lines: Line[] = [
  { id: "l1", product: "Northwind CRM Business license (yearly)", qty: 1, price: 1200, vat: 0.08 },
  { id: "l2", product: "Extra users", qty: 5, price: 120, vat: 0.08 },
  { id: "l3", product: "Setup and data migration", qty: 12, price: 95, vat: 0.08 },
]

const columns: TableColumn<Line>[] = [
  { key: "product", header: "Product / service", sortable: true, footer: ["Subtotal", "Sales tax 8%", "Total"] },
  { key: "qty", header: "Qty", type: "number" },
  { key: "price", header: "Unit price", type: "currency" },
  { key: "vat", header: "Tax", type: "percent" },
  {
    key: "total",
    header: "Total",
    type: "currency",
    sortable: true,
    accessor: (line) => line.qty * line.price,
    footer: ["$2,940.00", "$235.20", "$3,175.20"],
  },
]

export function InvoiceLines() {
  return <Table caption="Invoice #2026-0412" columns={columns} data={lines} locale="en-US" />
}

// parts, for tables the props API does not cover (same file, same look):
// TableRoot { density, variant, striped, stickyHeader, stickyFirstColumn } holds the context;
// TableScroll { maxHeight, fades, pinnedStart } scrolls with edge fades;
// TableHead { align, sort, onSort, pinned, width, minWidth, sortLabel, firstDirection } renders TableSortButton + aria-sort;
// TableRow { selected, clickable }, TableCell { align, pinned, truncate, numeric, wrap },
// TableEmpty { colSpan }, TableSkeleton { rows, columns, align };
// phone cards: TableCards { variant } > TableCard { interactive, selected } > TableCardHeader
// (TableCardTitle { onClick }, TableCardSubtitle, TableCardMeta, TableCardActions) + TableCardFields > TableCardField { label, wide };
// helpers: formatCellValue(value, type, { locale, currency }), compareValues(a, b, type, locale),
// TABLE_DENSITY, MOBILE_CARD, MOBILE_CARD_FIELDS (shared with data-table)
import {
  TableRoot, TableScroll, TableElement, TableCaption, TableHeader, TableBody,
  TableRow, TableHead, TableCell, formatCellValue,
} from "@/components/ui/table"

export function PriceList({ items }: { items: { id: string; name: string; price: number }[] }) {
  return (
    <TableRoot density="compact" variant="lined">
      <TableScroll>
        <TableElement>
          <TableCaption hidden>Price list</TableCaption>
          <TableHeader>
            <TableRow>
              <TableHead>Service</TableHead>
              <TableHead align="end">Price</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {items.map((item) => (
              <TableRow key={item.id}>
                <TableCell>{item.name}</TableCell>
                <TableCell align="end" numeric>{formatCellValue(item.price, "currency", { locale: "en-US" })}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </TableElement>
      </TableScroll>
    </TableRoot>
  )
}
```

Docs: https://wingo-ui.com/components/table (Markdown: https://wingo-ui.com/components/table.md)

#### Task List (`task-list`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add task-list`

A checklist that strikes out completed tasks and moves them to the bottom of the list, with each row also exported as a standalone TaskItem.

Click or tap a row to toggle it. Ticking fills the circle and draws a check, a line strikes through the label, the row gives a little flick, then it springs down to join the finished tasks at the bottom. Unticking runs the same road backwards and brings the row back up. Rows are real checkboxes, so Tab and Space or Enter work too.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `size?: "sm" | "md" | "lg"` = "md": Row size. Text, circle, padding and radius all scale together, and the circle always matches one line of the label.
- `accent?: string` = "#FF5F2E": Any CSS color for the filled circle and the focus ring. The strike and the faded text stay grey.
- `surfaceColor?: string` = "auto": Fill of each row card, any CSS color. Auto is white on light pages and #1F1F1F on dark ones.
- `textColor?: string` = "auto": Color of open task labels, any CSS color. Auto is a near black or near white that follows the theme.
- `doneTextColor?: string` = "auto": Color of finished task labels and of the strike line, any CSS color. Auto is a mid gray tuned per theme.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of each row card: square, 4px tighter, the original 10 / 14 / 16px per size, 6px rounder, or a pill.
- `checkColor?: string` = "#ffffff": Any CSS color for the tick drawn inside the filled circle.
- `strike?: boolean` = true: Draws a line through finished labels. Off, they only fade to doneTextColor.
- `reorder?: boolean` = true: Springs finished tasks down to the bottom of the list, and back up when reopened. Off, every row stays where it is.
- `completedLabel?: string` = "completed": Announced after a task label when it is ticked, e.g. "finalizat".
- `reopenedLabel?: string` = "reopened": Announced after a task label when it is unticked.
- `tasks?: Task[]`: The rows to show, each one an id, a label, and an optional done flag. Pass this with onTasksChange to drive the list yourself.
- `defaultTasks?: Task[]` = "[]": The rows to start with when you are not driving the list. The list tracks which ones are done on its own.
- `onTasksChange?: (tasks: Task[]) => void`: Called with the full list every time a row is ticked or unticked.
- `className?: string`: Extra classes merged onto the root element (data-slot="task-list"); other ul props are spread onto it too.

Parts:
- `TaskItem` (component): One row on its own, no list around it: a checkbox button that ticks, strikes and flicks. The list renders one per task. Takes button props.
- `Task` (type): One entry of tasks: { id, label, done? }.

```tsx
"use client"

import { TaskList } from "@/components/ui/task-list"

export function Demo() {
  return (
    <TaskList
      defaultTasks={[
        { id: "ship", label: "Ship a new component to the registry", done: true },
        { id: "preview", label: "Record a preview for the gallery" },
        { id: "star", label: "Star the repository" },
      ]}
    />
  )
}

// one row on its own, no list around it (see TaskItem under Parts):
// <TaskItem label="Star the repository" size="sm" onCheckedChange={setDone} />
```

Docs: https://wingo-ui.com/components/task-list (Markdown: https://wingo-ui.com/components/task-list.md)

#### Virtual List (`virtual-list`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add virtual-list`

Long and endless lists at 60fps: thousands of list rows virtualized, sticky group headers, infinite loading and scroll restoration.

Scroll through thousands of rows: only the rows on screen (plus a few past each edge) are in the DOM, so a flick stays smooth on a phone with native momentum and no scroll chaining into the page. With getGroup the current group's header (a letter, a day) stays pinned at the top on a frosted band and the next one pushes it up as it arrives. Near the end the next page loads on its own (loadMode auto), from a Load more button (button), or by pulling past the last row until the label reads Release to load and letting go (pull, on touch and trackpads; the indicator spins with the pull and is also a button). New rows fade in, a failed page shows an inline error row with Try again and keeps what loaded, and after the last page a quiet end line appears. Rows are list rows, so taps, swipe actions, long press menus and selection work as in List. Keyboard: Up / Down move between rows and scroll the next row into view even when it is not rendered yet, PageUp / PageDown jump 10 rows, Home / End go to the first and last loaded row; in selectable lists Space toggles, Shift + arrows extend and Ctrl / Cmd + A selects every row, rendered or not. A focused row stays in the DOM while it scrolls away. Screen readers hear the position in the set (unknown while more can load) and a polite announcement after each page. With persistKey the list opens where you left it after back navigation. Reduced motion drops the fades; the pull still follows the finger.

npm: @tanstack/react-virtual, lucide-react, motion
Wingo UI dependencies: button, empty-state, list, motion, number-format, skeleton, spinner, ui-config, use-locale, use-persisted-state, use-scroll-state

Props:
- `items: T[]`: Every loaded row. Append a page to load more; a shorter array (a filter) keeps the scroll position clamped.
- `renderItem: (item: T, index: number) => ReactNode`: Renders one row, usually a <ListItem /> returned directly (not wrapped in your own component), so it inherits size and dividers and receives aria-posinset / aria-setsize. Keep images at a fixed size so rows measure right the first time.
- `getItemKey?: (item: T, index: number) => string` = "item.id": Stable row keys for measurement, selection and scroll restoration. Define it at module scope or with useCallback.
- `getGroup?: (item: T) => string`: Consecutive items with the same key share a group header (32px, eyebrow style) that pins to the top while you are in that group. Letters for contacts, groupByDay keys for feeds. Unset: no headers.
- `renderGroupHeader?: (group: string, firstItem: T) => ReactNode` = "the group string": The header content: "A", "Today", "September 2026".
- `emptyState?: ReactNode` = "<EmptyState preset=\"empty\" size=\"sm\" />": Shown when there are no items, nothing is loading and nothing more can load.
- `endMessage?: ReactNode` = "": The quiet line after the last page (hasMore false and onLoadMore set). Empty uses labels.end ("You have reached the end"); null hides it.
- `variant?: "plain" | "inset"` = "plain": plain: rows on the page background. inset: one raised panel (the iOS grouped look) that is also the scroll box.
- `size?: "sm" | "md" | "lg"` = "md": Row size passed to every ListItem: 44 / 56 / 64px, with matching avatars, header padding and skeletons.
- `dividers?: "full" | "inset" | "none"` = "inset": Hairlines between rows. inset starts after the icon or avatar; a group header starts a fresh run.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corners of the inset panel: 0 / 12 / 16 / 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Selection color (checkboxes, the check mark) and the Load more button's tint.
- `color?: string` = "": Any CSS color; replaces the tone.
- `scroll?: "self" | "window"` = "self": self: the list scrolls inside height. window: the page scrolls (useWindowVirtualizer), or the nearest ScrollContainerProvider (an app shell's content column, a demo frame) when there is one.
- `height?: number | string` = "100%": The scroll box height with scroll="self" (a number is px, any CSS length works). The server renders the rows that fit a px height, so hydration never jumps.
- `estimateSize?: number or ((index: number) => number)` = "44 / 56 / 64 by size": A first guess per row. Rows are measured after render (one-line and two-line descriptions both fit); a close guess only avoids a jump.
- `overscan?: number` = 8: Rows rendered past each edge of the viewport. More hides blank flashes on very fast flicks; fewer keeps the DOM smaller.
- `stickyOffset?: number` = 0: px between the scroll edge and the pinned group header, e.g. the height of a sticky app bar above a window list.
- `loading?: boolean` = false: The first load: skeleton rows in the real row shape (avatar, two lines) fill the viewport, and aria-busy is set.
- `skeletonCount?: number` = 0: Skeleton rows while loading. 0 fills the scroll box (height / row estimate).
- `hasMore?: boolean` = false: More pages exist. Turns on the loading footer (auto), the Load more button or the pull indicator, and makes aria-setsize -1 (unknown). The demo pages in 50 clients at a time when it is on and shows all 5,000 when it is off.
- `loadingMore?: boolean` = false: Controlled flag for a page in flight. Not needed when onLoadMore returns a promise: that sets it automatically.
- `error?: ReactNode`: A failed page load. With rows: an inline error row with Try again under them (the loaded rows stay, automatic loading pauses). Without rows: the error empty state. true uses labels.error.
- `onRetry?: () => (void | Promise<unknown>)`: The Try again button of the error row.
- `loadMode?: "auto" | "button" | "pull"` = "auto": auto: loads when the last row comes within threshold px (no gesture needed, the default). button: a full-width Load more button that shows its own spinner. pull: at the end, pull past 64px (rubberband, touch and trackpad) and let go.
- `threshold?: number` = 600: px before the end at which auto mode asks for the next page, so it usually arrives before you get there.
- `onLoadMore?: () => (void | Promise<unknown>)`: Asks for the next page. A returned promise drives the loading state; calls while a page is loading are ignored.
- `onEndReached?: () => void`: Fires once per page when the bottom of the last row comes into view (analytics).
- `persistKey?: string` = "": Restores the scroll position (sessionStorage, anchored to a row so measured heights do not drift) when the list mounts again, e.g. after back navigation. Skipped when the first row changed.
- `selectionMode?: "none" | "single" | "multiple"` = "none": Selectable rows, like List: the list becomes a listbox with one Tab stop, checkboxes (multiple) or a check (single). Ctrl / Cmd + A selects every row, rendered or not.
- `selectedKeys?: string[]`: The selected row keys (controlled).
- `defaultSelectedKeys?: string[]`: The initial selection (uncontrolled).
- `onSelectedKeysChange?: (keys: string[]) => void`: Called with the new selection, in row order.
- `selectionIndicator?: "auto" | "checkbox" | "check" | "highlight"` = "auto": auto: a checkbox for multiple, a trailing check for single; highlight tints the row only.
- `showChevron?: boolean` = true: Rows with href or onSelect end in a chevron.
- `onAction?: (key: string, item: T) => void`: Row activation, after the row's own onSelect.
- `handleRef?: RefObject<VirtualListHandle> or (handle: VirtualListHandle | null) => void`: { scrollToIndex(index, { align, smooth }), scrollToKey(key, options), scrollToTop({ smooth }), getVirtualizer() }. Indexes count items, not group headers; smooth turns off under reduced motion.
- `onRangeChange?: (range: { startIndex; endIndex; rendered; total }) => void`: The visible item indexes and how many rows are in the DOM, whenever that changes (a position readout, analytics).
- `locale?: string` = "": Formats the loaded-count announcement. Empty uses UIProvider, then the page language.
- `labels?: Partial<VirtualListLabels>` = "{ loadMore: \"Load more\", loading: \"Loading…\", end: \"You have reached the end\", pull: \"Pull to load more\", release: \"Release to load\", error: \"Could not load more\", retry: \"Try again\", empty: \"Nothing here yet\", loaded: (n, formatted) => `${formatted} more loaded` }": Every string of the list itself; DEFAULT_VIRTUAL_LIST_LABELS is exported.
- `listLabels?: Partial<ListLabels>`: Strings of the rows (the row menu button, the checkbox), passed to the list context.
- `classNames?: Partial<Record<"content" | "inner" | "row" | "groupHeader" | "footer" | "loading" | "loadMore" | "pull" | "end" | "error" | "empty" | "skeleton", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root (the scroll box with scroll="self"), merged last.

```tsx
import { useRef } from "react"
import { ListItem } from "@/components/ui/list"
import { VirtualList, type VirtualListHandle } from "@/components/ui/virtual-list"

type Client = { id: string; name: string; city: string; balance: string }

const letter = (client: Client) => client.name.charAt(0).toLocaleUpperCase("en")

export function Clients({ clients, hasMore, loadPage }: { clients: Client[]; hasMore: boolean; loadPage: () => Promise<void> }) {
  const list = useRef<VirtualListHandle>(null)
  return (
    <div className="h-[560px]">
      <VirtualList
        aria-label="Clients"
        items={clients}
        getGroup={letter}
        renderItem={(client) => (
          <ListItem id={client.id} title={client.name} description={client.city} avatar={{ name: client.name }} value={client.balance} />
        )}
        hasMore={hasMore}
        onLoadMore={loadPage}
        persistKey="clients"
        handleRef={list}
        labels={{ end: "You reached the end" }}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/virtual-list (Markdown: https://wingo-ui.com/components/virtual-list.md)

### Charts & Stats

#### Animated Counter (`animated-counter`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add animated-counter`

A number that counts to its new value on a wheel of digits, like an odometer.

Drag along the ruler, or focus it and use the arrow keys, to change the value. Digits roll up as the number grows and back down as it shrinks, fading in and out at the top and bottom of each window rather than being cut off. A number that keeps changing spins instead of stuttering. The width always matches the number: a place that is gained slides in, one that is lost fades out while the rest close up, and the separators glide along with them.

npm: motion
Wingo UI dependencies: motion, ui-config

Props:
- `value: number`: The number to show. Each change animates from whatever is on screen, so it can be updated as often as you like. Negative values get a leading minus.
- `decimals?: number` = 0: How many decimal places to keep, up to 15. The value is rounded to that precision, so the wheels always land on a whole digit.
- `duration?: number` = 0.6: Roughly how many seconds a digit takes to settle on its new face. Lower it when the value updates continuously, so the wheels stay close to the number.
- `padStart?: number` = 1: Fewest whole digits to show, up to 24, padded with leading zeros. Use it to hold the width steady when the number crosses a power of ten.
- `separator?: string` = ",": Placed between digit groups. Pass an empty string to group nothing.
- `decimalSeparator?: string` = ".": Character between the whole and decimal digits.
- `locale?: string` = "": Intl locale whose group and decimal marks replace separator and decimalSeparator, unless you pass those: "en-US" writes 1,234.5, "de-DE" 1.234,5, "fr-FR" 1 234,5. Falls back to UIProvider's locale; empty keeps the separators.
- `grouping?: "western" | "indian"` = "western": Where the separators land. Western groups every three digits, 1,234,567. Indian groups the last three then pairs, 12,34,567.
- `size?: "inherit" | "sm" | "md" | "lg" | "xl"` = "inherit": Font size: 24px (sm), 36px (md), 60px (lg) or 72px (xl). Inherit takes the size of the surrounding text, so a text class on the counter or its parent sizes it instead.
- `font?: "inherit" | "sans" | "mono" | "serif"` = "inherit": Font family from your theme tokens. Figures are tabular in every family, so the width only changes when a place is gained or lost.
- `weight?: "inherit" | "normal" | "medium" | "semibold" | "bold"` = "inherit": Font weight of the digits, the separators and any string prefix or suffix.
- `color?: string` = "currentColor": Text color, any CSS color. currentColor follows the surrounding text, so it adapts to light and dark on its own.
- `fade?: boolean` = true: Fades each digit window at its top and bottom edge, so rolling faces blur in and out. Turn it off for a hard cut like a mechanical counter.
- `fadeSize?: number` = 22: How deep the top and bottom fade of each digit reaches, as a percent of the line box. Only with fade on.
- `bounce?: number` = 0.18: Spring bounce of the wheels and the width changes, from 0 (settles with no overshoot) to 1.
- `prefix?: ReactNode`: Rendered before the number, for a currency mark or an icon. It sits outside the wheels and never animates, but glides when the width changes.
- `suffix?: ReactNode`: Rendered after the number, for a unit or a percent sign.
- `className?: string`: Extra classes merged onto the root element (data-slot="animated-counter"). With size, font and weight left on inherit it styles like text, so a text class here or on a parent works too. The digit columns carry data-slot="animated-counter-digit" and the separators data-slot="animated-counter-mark", for reaching either from the root.

```tsx
"use client"

import { AnimatedCounter } from "@/components/ui/animated-counter"

export function Revenue({ total }: { total: number }) {
  return <AnimatedCounter value={total} size="lg" weight="medium" />
}

// money: two decimals and a currency mark that stays put
// <AnimatedCounter value={total} decimals={2} prefix={<span>₹</span>} grouping="indian" />

// fixed width, so a timer never shifts as it rolls over
// <AnimatedCounter value={seconds} padStart={4} separator="" />
```

Docs: https://wingo-ui.com/components/animated-counter (Markdown: https://wingo-ui.com/components/animated-counter.md)

#### Area chart (`area-chart`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add area-chart`

Volumes over time as filled areas: overlapping gradients, stacked bands for parts of a total, or 100% stacked shares.

Move the mouse over the plot for a crosshair, a dot on every band and a readout of every visible series (stacked charts list the top band first and add a Total row; percent charts show the value and its share, "$48,920 · 38.1%"). On a phone, tap a month to pin the readout above your finger, drag sideways to scrub (vertical drags still scroll the page), tap the same month again or anywhere outside to clear it. With the keyboard, Tab to the plot, then Left / Right walk the points, Home / End jump to the ends, PageUp / PageDown move by ten, Enter fires onDatumClick, Escape clears; a live region reads each point. Legend entries are buttons: click or tap one to hide or show its series (the stack re-flows with a glide), hover or focus one to highlight it. Switching type between overlap, stacked and percent glides the areas to their new shape and cross-fades the y ticks. Areas rise from the baseline and the lines draw in the first time the chart scrolls into view; reduced motion shows the final chart at once.

npm: motion, d3-shape, d3-scale
Wingo UI dependencies: chart-kit, motion, ui-config, use-locale

Props:
- `data: ChartDatum[]`: One row per x position: { month: "2026-09", directe: 48920, online: 36400 }. Data order is x order (the chart does not sort).
- `xKey?: string` = "date": The row key for the x axis. ISO days ("2026-09-24") and months ("2026-09") print as local dates.
- `series?: AreaChartSeries[]`: Which keys to draw ({ key, label?, color?, name? }), in color and stack order: series 1 is the bottom band. Inferred from the numeric keys of the first rows when omitted.
- `colors?: string[]`: Per-position palette overrides: slots ("series-3"), tones ("neutral", "brand", "success") or any css color.
- `type?: "overlap" | "stacked" | "percent"` = "overlap": overlap: every area from zero, the first series on top. stacked: bands add up (negative values stack below zero, diverging). percent: 100% stacked shares, y axis 0 to 100 %, the readout and table add each share with one decimal ("38,1 %"), negatives drawn as 0.
- `fill?: "gradient" | "solid" | "none"` = "gradient": gradient fades the series color from fillOpacity to transparent; solid is a flat fill at fillOpacity; none draws lines only (always on, whatever showLine says).
- `fillOpacity?: number` = 0.22: The top of the gradient or the solid fill. Stacked bands add 0.1 so they read as bands; overlapping fills of two or more series never exceed 0.22.
- `showLine?: boolean` = true: The line on each area's top edge. Stacked bands keep a thin surface gap between them without it.
- `curve?: "monotone" | "linear" | "natural" | "step"` = "monotone": How points are joined. monotone never overshoots the data.
- `strokeWidth?: number` = 2: Width of the top lines in px.
- `connectNulls?: boolean` = false: Bridge null gaps instead of breaking the area (overlap only; stacked types treat nulls as 0).
- `height?: number` = 240: Plot height in px, reserved before measuring so nothing jumps. The width always fills the parent.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the readout, the ticks and the table: "128,450", "128K", "$128,450", "12.4%" (percent takes whole numbers). Ticks go compact on their own from 10,000.
- `currency?: string` = "USD": ISO 4217 code for valueFormat="currency", printed with its narrow symbol ("$", "€"). Anything that is not a three-letter code prints as plain numbers with the text as a suffix.
- `decimals?: number`: Fraction digits in the readout and the table (ticks stay short). Auto by magnitude.
- `formatValue?: (value: number, context: { series: string; kind: "tooltip" | "tick" | "label" | "table" }) => string`: Full control over value text, e.g. v => `${v} buc.`. Percent ticks and shares keep the kit format.
- `formatX?: (value: unknown, context: "axis" | "tooltip" | "table") => string`: x labels; default formatChartLabel ("Sep" on the axis, "September 2026" in the readout).
- `locale?: string` = "": Intl locale for numbers and dates; empty uses UIProvider's locale, then the page's.
- `yDomain?: AreaChartDomain = [number | "auto", number | "auto"]` = "[\"auto\", \"auto\"]": Fixed value bounds. Areas always include zero; percent charts are always 0 to 100.
- `showGrid?: boolean` = true: Hairlines at the value ticks.
- `showXAxis?: boolean` = true: x labels under the plot, thinned from the newest backwards so they never collide.
- `showYAxis?: boolean` = true: Value tick labels.
- `yAxisSide?: "start" | "end"` = "start": end puts the value ticks on the right (finance style).
- `showLegend?: boolean` = true: The legend; only rendered with two or more series (one series is named by the card title).
- `legendPosition?: "top" | "bottom"` = "top": Legend above or below the plot. It wraps on narrow widths.
- `legendToggle?: boolean` = true: Legend entries are buttons that hide and show their series (the last visible series cannot be hidden).
- `showTooltip?: boolean` = true: The floating readout. When off, the crosshair, keyboard and live region still work.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": float rides beside the crosshair, fixed pins above the plot; auto is fixed on touch screens.
- `referenceLines?: { value: number; label?: string; color?: string }[]`: Dashed targets or averages ("Media 261"). In percent charts the value is a share (0 to 100).
- `animated?: boolean` = true: Areas rise and lines draw the first time the chart scrolls into view; data, type and legend changes glide.
- `loading?: boolean` = false: A skeleton in the plot's shape, same height.
- `emptyState?: ReactNode`: Shown when data is empty or every value is null. Default: an icon tile and labels.empty.
- `label?: string` = "": Accessible name of the figure and caption of its data table. Empty joins the series names.
- `description?: string` = "": A one-sentence takeaway for screen readers (aria-describedby).
- `surface?: string` = "": The color behind the chart, used for dot rings and the gaps between stacked bands. Empty = var(--surface).
- `hiddenSeries?: string[]`: Hidden series keys (controlled). Pair with onHiddenSeriesChange.
- `defaultHiddenSeries?: string[]` = "[]": Series hidden at first (uncontrolled).
- `onHiddenSeriesChange?: (keys: string[]) => void`: Called when a legend toggle hides or shows a series.
- `activeIndex?: number | null`: The inspected x index (controlled), so two charts can share one crosshair.
- `defaultActiveIndex?: number | null` = "null": The inspected index at first (uncontrolled).
- `onActiveIndexChange?: (index: number | null) => void`: Called while hovering, scrubbing or walking with the keyboard.
- `onDatumClick?: (event: { index: number; datum: ChartDatum; series?: string }) => void`: A click on the plot (series = the band under the pointer) or Enter on the inspected point (series = the first visible one).
- `labels?: Partial<AreaChartLabels>`: English defaults: empty, loading, table, total, other, inspectHint, showSeries, hideSeries and shareColumn (the percent table's share column).
- `classNames?: Partial<Record<"legend" | "plot" | "tooltip" | "table" | "area" | "line" | "dot" | "grid" | "xAxis" | "yAxis", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the figure root, merged last.

```tsx
import { AreaChart } from "@/components/ui/area-chart"

const data = [
  { month: "2026-07", direct: 41460, online: 28700, partners: 18070 },
  { month: "2026-08", direct: 38030, online: 27300, partners: 15600 },
  { month: "2026-09", direct: 48920, online: 36400, partners: 22130 },
]

export function RevenueByChannel() {
  return (
    <AreaChart
      data={data}
      xKey="month"
      series={[
        { key: "direct", label: "Direct sales" },
        { key: "online", label: "Online store" },
        { key: "partners", label: "Partners" },
      ]}
      type="stacked"
      valueFormat="currency"
      currency="USD"
      label="Revenue by channel, 2026"
    />
  )
}
```

Docs: https://wingo-ui.com/components/area-chart (Markdown: https://wingo-ui.com/components/area-chart.md)

#### Bar chart (`bar-chart`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add bar-chart`

Compares categories or periods as columns or horizontal bars, grouped, stacked or 100%, with negatives below a clear zero line.

The bars grow out of the zero line the first time the chart scrolls into view, one category a beat after the other; value labels fade in after their bar. Move the mouse over the plot and the whole column (or row, when horizontal) under it lights up with a soft band while a readout lists every visible series in it (stacked charts add a total, 100% charts add each share). On a phone, tap a column to pin the readout above the plot, drag sideways to scrub (a vertical drag still scrolls the page), tap it again or anywhere outside to clear it. With the keyboard, Tab to the plot: Left / Right walk the categories (Up / Down for horizontal bars), Home / End jump to the ends, PageUp / PageDown move by ten, Enter fires onDatumClick for the first visible series and Escape clears; a live region reads each category. Click or tap a legend entry to hide its series (the rest regroup and the axis rescales with a glide), hover or focus one to highlight it. Switching between grouped, stacked and 100% glides every bar to its new place.

npm: motion
Wingo UI dependencies: chart-kit, motion, ui-config, use-locale

Props:
- `data: ChartDatum[]`: One row per category, in drawing order: { month: "2026-09", collected: 128450, expenses: 81200 }. Negative values grow down (or left) from zero.
- `xKey?: string` = "date": The row key for the categories. ISO days ("2026-09-24") and months ("2026-09") print as local dates; other strings print as they are.
- `series?: BarChartSeries[]`: Which keys to draw, in color and stack order: { key, label?, color?, name? }. Inferred from the numeric keys of the first rows when omitted.
- `colors?: string[]`: Per-position palette overrides: a slot ("series-3"), a tone ("neutral", "success") or any CSS color.
- `height?: number` = 240: Plot height in px, reserved before the chart measures so nothing jumps.
- `orientation?: "vertical" | "horizontal"` = "vertical": horizontal puts the categories in a label column on the left (at most 40% of the width, long names end in an ellipsis; the tooltip and table keep the full text). The better choice on phones with long names.
- `type?: "grouped" | "stacked" | "percent"` = "grouped": grouped sets the series side by side, stacked piles them (negatives below zero), percent piles their shares to 100%.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius of the data end: 0 / 2 / 4 / 6px or half the thickness. The base stays square; stacks round only their outermost segment.
- `barSize?: number` = 24: Maximum bar thickness in px. Bars shrink to fit narrow plots instead of overlapping.
- `barGap?: number` = 2: Px between the bars of one group and between stacked segments, painted in the surface color.
- `categoryGap?: number` = 0.3: The share of each category's band left empty between groups.
- `showValues?: boolean` = false: A value at each bar's tip (grouped), the total at each stack's end (stacked) or the share inside each segment (percent). Every label uses one form: full amounts when they all fit, else the compact form; when they still collide every k-th category is labelled, counted back from the newest. A label with no room goes inside its bar or is skipped, never clipped; bars thinner than 14px carry none.
- `getBarColor?: (datum: ChartDatum, series: ResolvedChartSeries, index: number) => (string | undefined)`: A color per bar (a slot, a tone or any CSS color): "danger" for negatives, "brand" for the current month. undefined keeps the series color.
- `highlightLast?: boolean` = false: Dims every category but the last to 45%, for the current-period look. The inspected category lights up too.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the tooltip, ticks, value labels and table. Percent takes whole numbers (12.4 -> "12,4 %").
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency, printed with the narrow symbol ("$128,450").
- `decimals?: number`: Fraction digits in the tooltip, labels and table; auto by magnitude when unset. Ticks stay short.
- `formatValue?: (value: number, context: { series: string; kind: "tooltip" | "tick" | "label" | "table" }) => string`: Replaces the built-in value formatting everywhere.
- `formatX?: (value: unknown, context: "axis" | "tooltip" | "table") => string`: Replaces the category label formatting (short on the axis, long in the tooltip and table).
- `locale?: string` = "": Locale for numbers and dates. Empty uses the UIProvider / LocaleProvider locale.
- `yDomain?: BarChartDomain = [number | "auto", number | "auto"]` = "[\"auto\", \"auto\"]": Fixed value bounds; zero is always included. Ignored by percent (always 0 to 100%).
- `showGrid?: boolean` = true: Hairlines at the value ticks (horizontal lines, or vertical ones for horizontal bars).
- `showXAxis?: boolean` = true: The labels under the plot: categories (thinned so they never collide), or value ticks for horizontal bars.
- `showYAxis?: boolean` = true: The labels beside the plot: compact value ticks ("$128K"), or the category column for horizontal bars.
- `yAxisSide?: "start" | "end"` = "start": end puts the value ticks on the right, finance style (vertical bars; horizontal bars keep categories on the left).
- `showLegend?: boolean` = true: The legend; it only renders with two or more series (one series is named by the card title).
- `legendPosition?: "top" | "bottom"` = "top": Legend above or below the plot.
- `legendToggle?: boolean` = true: Legend entries are buttons that hide and show their series. The last visible series cannot be hidden.
- `showTooltip?: boolean` = true: The floating readout. When off, the band, keyboard and screen reader announcements still work.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": float rides beside the inspected bars, fixed pins above the plot (never under a finger); auto is fixed on touch screens.
- `referenceLines?: { value: number; label?: string; color?: string }[]`: Dashed target or average lines with a label ("Target $120,000"); always inside the value range.
- `animated?: boolean` = true: Bars grow on first view and glide on data, type and legend changes. Reduced motion always shows the final state.
- `loading?: boolean` = false: A bar-shaped skeleton in the plot's box.
- `emptyState?: ReactNode`: Replaces the built-in empty state (shown when data is empty or every value is null).
- `label?: string` = "": Accessible name of the figure and caption of its data table. Empty joins the series names.
- `description?: string` = "": A one-sentence takeaway for screen readers ("September brought the highest collections of the year").
- `surface?: string` = "": The color behind the chart, used for label halos. Empty uses the surface token; set it when the chart sits on a card.
- `hiddenSeries?: string[]`: Hidden series keys when you control legend toggling; pair with onHiddenSeriesChange.
- `defaultHiddenSeries?: string[]`: Series keys hidden at first, when the legend toggles on its own.
- `onHiddenSeriesChange?: (keys: string[]) => void`: Called when a legend entry hides or shows a series.
- `activeIndex?: number | null`: The inspected category index when you control it, so two charts can share one highlight.
- `defaultActiveIndex?: number | null`: The category inspected at first (a pinned readout), uncontrolled.
- `onActiveIndexChange?: (index: number | null) => void`: Called as the highlighted category changes (mouse, touch or keyboard) and with null when it clears.
- `onDatumClick?: (event: { index: number; datum: ChartDatum; series?: string }) => void`: A click or tap on a category (series is the bar under the pointer, else the first visible series) or Enter on the inspected one.
- `labels?: Partial<BarChartLabels>`: Strings: empty, loading, table, total, inspectHint, inspectHintVertical, showSeries, hideSeries, category (Category, the table's first column).
- `classNames?: Partial<Record<BarChartSlot, string>>`: Classes for legend, plot, tooltip, table, grid, xAxis, yAxis, bar, band, value, category, referenceLine and inspect.

```tsx
import { BarChart } from "@/components/ui/bar-chart"

const data = [
  { month: "2026-07", collected: 106300, expenses: 72400 },
  { month: "2026-08", collected: 97500, expenses: 69900 },
  { month: "2026-09", collected: 128450, expenses: 81200 },
]

export function MonthlyCollections() {
  return (
    <BarChart
      data={data}
      xKey="month"
      series={[
        { key: "collected", label: "Collected" },
        { key: "expenses", label: "Expenses" },
      ]}
      valueFormat="currency"
      currency="USD"
      label="Collected vs. expenses per month"
    />
  )
}
```

Docs: https://wingo-ui.com/components/bar-chart (Markdown: https://wingo-ui.com/components/bar-chart.md)

#### Donut chart (`donut-chart`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add donut-chart`

Parts of a whole as a donut or pie, with the total in the middle, a legend with values and shares, and a selectable slice.

The slices sweep in clockwise from the start angle the first time the chart scrolls into view, while the total in the middle counts up. Hover a slice and it lifts, the others dim and the center reads its value, name and share (a pie, or a donut too small for a center, shows a floating readout instead; the folded Other slice lists what is inside it above the chart). Click a slice to select it: it stays lifted and the center keeps its value (click it again, or click the hole, to clear). On a phone, tap a slice to select it (the ring is widened by 12px on each side, so thin rings and slivers are easy to hit), slide a finger along the ring to scrub (the center reads each slice and the one you let go on is selected), tap the hole or outside the ring to clear. Legend rows are buttons: tap or click one to select its slice, hover or focus it to preview the slice in the center. With the keyboard, Tab to the chart: Left / Right (or Up / Down) walk the slices, Home / End jump to the first and last, Enter or Space selects the inspected slice and Escape clears the selection; a live region reads each slice. When the data changes, the slices glide to their new angles. The legend sits beside the chart from a 480px wide container and below it on phones.

npm: motion, d3-shape
Wingo UI dependencies: chart-kit, motion, ui-config, use-controllable-state, use-locale

Props:
- `data: DonutChartDatum[] = { id: string; label: ReactNode; value: number; color?: string; name?: string }[]`: One entry per slice. color takes a palette slot ("series-3"), a tone ("success", "danger") or any CSS color; name is the plain-text name when label is not a string. Negative values are ignored.
- `variant?: "donut" | "pie"` = "donut": pie has no hole and no center content (the legend gets a total row instead).
- `size?: "sm" | "md" | "lg"` = "md": Diameter 140 / 200 / 260px; it shrinks to the container width.
- `thickness?: number` = 0: Ring width in px. 0 = auto (18% of the diameter).
- `gap?: number` = 2: px of surface between slices, measured at the middle of the ring. Slices under 3% give theirs up so they stay visible.
- `cornerRadius?: number` = 4: Rounded slice corners in px.
- `startAngle?: number` = 0: Where the first slice starts, in degrees: 0 is 12 o'clock, clockwise.
- `sort?: "value" | "none"` = "value": value puts the biggest slice first (clockwise from the start angle) and gives it palette slot 1; none keeps the data order.
- `maxSlices?: number` = 6: Named slices kept; the smaller rest fold into one "Other" slice (labels.other, the neutral gray) whose readout lists them. A single leftover slice is never folded.
- `colors?: string[]`: Per-position palette overrides after sorting; a datum's own color wins.
- `showLegend?: boolean` = true: The legend: one button per slice with its value and share.
- `legendPosition?: "auto" | "right" | "bottom"` = "auto": auto puts the legend beside the chart when the container is at least 480px wide and below it otherwise (a container query, right in the server html).
- `showPercent?: boolean` = true: Shares in the legend and the readout.
- `showValues?: boolean` = true: Values in the legend.
- `centerLabel?: ReactNode` = "": The caption under the center value. Default labels.total ("Total").
- `centerValue?: ReactNode`: Replaces the formatted total ("342"); a trailing unit ("342 invoices") is set smaller.
- `value?: string | null`: The selected slice id when you control it: lifted, the others dimmed, the center shows its value, name and share. null clears.
- `defaultValue?: string | null` = "null": The slice selected at first, uncontrolled.
- `onValueChange?: (id: string | null) => void`: Called when a slice or legend row is selected or cleared. The folded slice reports DONUT_CHART_OTHER_ID ("__other__").
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the center, legend, readout and table. Percent takes whole numbers (12.4 -> "12,4 %").
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency, printed with the narrow symbol ("$128,450").
- `decimals?: number`: Fraction digits for values; auto by magnitude when unset.
- `formatValue?: (value: number, context: { series: string; kind: "tooltip" | "label" | "table" }) => string`: Replaces the built-in value formatting everywhere; series is the slice id ("" for the total).
- `locale?: string` = "": Locale for numbers. Empty uses the UIProvider / LocaleProvider locale.
- `showTooltip?: boolean` = true: The floating readout for a pie or a donut too small for a center, and the list of folded slices behind Other. A donut with a center reads the inspected slice in the hole either way; selection and announcements work without it.
- `animated?: boolean` = true: The clockwise sweep and count-up on first view, and gliding slices on data changes. Reduced motion always shows the final state.
- `loading?: boolean` = false: A ring-shaped skeleton and skeleton legend rows in the same box.
- `emptyState?: ReactNode`: Replaces the built-in empty state (shown when there is no data or the total is 0).
- `label?: string` = "": Accessible name of the figure (followed by "total ...") and caption of its data table. Empty joins the slice names.
- `description?: string` = "": A one-sentence takeaway for screen readers ("Direct sales bring in 38% of revenue").
- `surface?: string` = "": The color behind the chart. Empty uses the surface token; the gaps between slices show whatever is behind the chart.
- `labels?: Partial<DonutChartLabels>`: Strings: empty, loading, total (the center caption), other, inspectHint, slice / value / percent (table headers), figure ((label, total) => name), more ((count) => "+3 more").
- `classNames?: Partial<Record<DonutChartSlot, string>>`: Classes for plot (the drawing: svg + center), svg, segment, center, centerValue, centerLabel, centerPercent, legend, legendItem, tooltip, table and inspect.

```tsx
import { DonutChart } from "@/components/ui/donut-chart"

const channels = [
  { id: "direct", label: "Direct sales", value: 48920 },
  { id: "online", label: "Online store", value: 36400 },
  { id: "partners", label: "Partners", value: 22130 },
  { id: "tenders", label: "Public tenders", value: 13600 },
  { id: "other", label: "Other", value: 7400 },
]

export function RevenueByChannel() {
  return (
    <DonutChart
      data={channels}
      valueFormat="currency"
      locale="en-US"
      label="Revenue by channel, September 2026"
      onValueChange={(id) => console.log(id)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/donut-chart (Markdown: https://wingo-ui.com/components/donut-chart.md)

#### Funnel chart (`funnel-chart`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add funnel-chart`

A conversion funnel: each step's count, its conversion and the drop-off between steps, as aligned bars or a tapered funnel shape.

The bars grow in one step after the other the first time the chart scrolls into view while the counts tick up, and each drop-off chip fades in after its row; when the numbers change, the bars glide to their new length. Every number is printed on the row (step, count, conversion, and between rows the drop-off with how many were lost), so there is nothing to hover. When you pass onValueChange or onStepClick the rows become buttons: click or tap one to select it (the others fade to 55%), click it again to clear. With the keyboard the rows are one tab stop: Up / Down (or Left / Right) move between them, Home / End jump to the first and last, Enter or Space select and Escape clears. In the funnel variant the segments are revealed top to bottom (left to right when horizontal); hover a step, or tap it on a phone, to highlight it and read its value, conversion and drop-off in a readout, drag a finger along the funnel to scrub, tap outside to clear. Tab to the funnel and use the arrow keys, Home / End and PageUp / PageDown to walk the steps, Enter to select and Escape to clear; a live region reads each step. A horizontal funnel stacks top to bottom in containers narrower than 480px.

npm: motion, d3-shape
Wingo UI dependencies: chart-kit, motion, tones, ui-config, use-controllable-state, use-locale

Props:
- `steps: FunnelStep[] = { id: string; label: ReactNode; value: number; description?: ReactNode; name?: string; color?: string }[]`: The steps in order, from the widest to the narrowest. name is the plain-text name when label is not a string; description is a quieter second line; color (a palette slot "series-3", a tone or any CSS color) overrides the fill of that step. Negative values draw as 0.
- `variant?: "bars" | "funnel"` = "bars": bars: one aligned row per step with every number printed (the readable default and the phone layout). funnel: a tapered shape of trapezoids with the labels beside it.
- `orientation?: "vertical" | "horizontal"` = "vertical": Funnel variant: top to bottom, or left to right with the labels above each step. Horizontal falls back to vertical when the chart is narrower than 480px.
- `curve?: "linear" | "smooth"` = "linear": Funnel variant: straight trapezoid sides, or smooth S-curves from one step's width to the next.
- `baseline?: "first" | "previous"` = "first": What the conversion percent is measured against: the first step ("3.3% of leads") or the step before it (step-to-step conversion; the first step then shows none).
- `showConversion?: boolean` = true: The conversion percent next to each value.
- `showDropoff?: boolean` = true: The chip between steps: how much of the previous step was lost, in percent and in units. A step larger than the one before shows a gain instead.
- `dropoffThreshold?: number` = 10: Drop-offs from this percent up are printed in the danger text color; smaller ones and gains stay calm. 0 turns the danger color off (every chip muted).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill of the bars and segments. Neutral is the foreground ink (black in light mode, white in dark mode).
- `color?: string` = "": Any CSS color for the fill; replaces the tone. Empty uses the tone.
- `stepColors?: boolean` = false: Paint each step in its own chart palette slot (series-1, series-2...) instead of one tone.
- `size?: "sm" | "md" | "lg"` = "md": Bars: track 8 / 12 / 16px, row spacing and text size. Funnel: 200 / 280 / 360px tall.
- `radius?: "none" | "sm" | "md" | "full"` = "full": The corners of the bars and their tracks (bars variant).
- `value?: string | null`: The selected step id when you control it: the other steps fade to 55%. null clears.
- `defaultValue?: string | null` = "null": The step id selected at first, uncontrolled.
- `onValueChange?: (id: string | null) => void`: Called when a step is selected or cleared. Passing it (or onStepClick) turns the rows into buttons.
- `onStepClick?: (step: FunnelStep, index: number) => void`: Called when a step is clicked, tapped or activated with Enter / Space, e.g. to open the deals in that stage.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How the step values print in the rows, the readout and the table. Percent takes whole numbers (12.4 -> "12,4 %").
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency, printed with the narrow symbol ("$128,450").
- `decimals?: number`: Fraction digits for values; auto by magnitude when unset (0 for counts, 1 for percent values).
- `formatValue?: (value: number, context: { series: string; kind: "label" | "tooltip" | "table" }) => string`: Replaces the built-in value formatting everywhere (series is the step id), e.g. compact dollars on the rows and full amounts in the table.
- `locale?: string` = "": Locale for numbers and percents. Empty uses the UIProvider / LocaleProvider locale.
- `showTooltip?: boolean` = true: Funnel variant: the readout beside a hovered or keyboard-inspected step (pinned above the chart on touch). Bars print every number and need none.
- `animated?: boolean` = true: Bars grow and counts tick up on first view, the funnel is revealed top to bottom, and changes glide. Reduced motion always shows the final state.
- `loading?: boolean` = false: Skeleton rows (or a skeleton funnel) in the shape of the chart.
- `emptyState?: ReactNode`: Replaces the built-in empty state (shown when steps is empty).
- `label?: string` = "": Accessible name of the figure (followed by the overall conversion) and caption of its data table. Empty joins the step names.
- `description?: string` = "": A one-sentence takeaway for screen readers ("The biggest loss is at the proposal stage").
- `labels?: Partial<FunnelChartLabels>`: Strings: empty, loading, inspectHint, selected (appended to the funnel's live readout on the selected step), stepHeader / valueHeader / conversionHeader / dropoffHeader / gainHeader (table and readout), and the functions conversion ((pct, { baseline, reference }) => "50.0% of first"), dropoff ((pct, lost) => "50.0% drop-off, 620 lost"), gain ((pct, gained) => ...), step ((label, value, conversion, change) => the screen reader text) and figure ((label, overall) => ...).
- `classNames?: Partial<Record<FunnelChartSlot, string>>`: Classes for list, step, header, label, description, value, conversion, track, bar, dropoff (bars), svg, segment, stepLabel, tooltip, inspect (funnel) and table.

```tsx
import { FunnelChart } from "@/components/ui/funnel-chart"

const pipeline = [
  { id: "lead", label: "Leads", value: 1240 },
  { id: "qualified", label: "Qualified", value: 620 },
  { id: "proposal", label: "Proposal sent", value: 248 },
  { id: "negotiation", label: "Negotiation", value: 96 },
  { id: "won", label: "Won", value: 41 },
]

export function SalesPipeline() {
  return (
    <FunnelChart
      steps={pipeline}
      locale="en-US"
      label="Sales pipeline, September 2026"
      labels={{
        conversion: (pct, { reference }) => `${pct} of ${reference.toLowerCase()}`,
        dropoff: (pct, lost) => `${pct} · ${lost} lost`,
      }}
      onValueChange={(id) => console.log(id)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/funnel-chart (Markdown: https://wingo-ui.com/components/funnel-chart.md)

#### Gauge (`gauge`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add gauge`

One value against a scale and its zones: a speedometer arc, needle or segmented dial with a target tick and a counting value.

A read-only meter, not focusable: nothing to tap or hover. The first time it scrolls into view the arc sweeps from the minimum on a soft spring (the needle turns, the segment marker rides the track) while the number counts up; later values glide from where they were, and the arc changes color as the value crosses into another zone. A long label or description that would not fit the bowl moves under the dial. Screen readers hear it as a meter with the formatted value, the zone and the target ("67.6%, Close zone, target 75%"). Drag the playground's slider to move the value. Reduced motion shows the final state at once.

npm: motion, d3-shape
Wingo UI dependencies: chart-kit, motion, number-format, tones, ui-config, use-locale

Props:
- `value: number | null` = 67.6: The current value. Outside min..max it is clamped for drawing, the text still shows the real number. null draws the track only and a dash.
- `min?: number` = 0: Start of the scale. min >= max renders the empty state (with a warning in development).
- `max?: number` = 100: End of the scale.
- `variant?: "arc" | "needle" | "segments"` = "arc": arc fills the track up to the value; needle is a thin zone-colored track with a needle; segments cuts the track into zones (the current one solid, the rest at 25%, a ring marker at the value) or, with a segments count, into equal steps that light up.
- `sweep?: 180 | 240 | 270` = "240": Degrees of the dial, symmetric around 12 o'clock. 180 is a half circle, 270 an open ring.
- `size?: "sm" | "md" | "lg"` = "md": Width 120 / 200 / 280px (the dial shrinks with a narrower container) and the value 18 / 28 / 40px.
- `thickness?: number` = 0: Track width in px. Auto is 10% of the width (12 / 20 / 28px), 4px for the needle track.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The arc color when no zone applies (no thresholds, colorByZone off, or a value below the first zone). neutral is the foreground ink.
- `color?: string` = "": Any css color, a palette slot ("series-3") or a tone name. Replaces the tone; zones still win while colorByZone is on.
- `thresholds?: { value: number; tone: Tone; label?: string }[]`: Zone starts, in any order (they are sorted): each zone runs from its value to the next one or max. Labels name the zone in the chip and the spoken text. Lower is better? List them success, warning, danger.
- `colorByZone?: boolean` = true: The arc and the chip take the tone of the zone the value is in.
- `showBands?: boolean` = true: A thin 3px zone band outside the arc (arc variant with thresholds); the zones the value is not in fade back.
- `segments?: number` = 0: Equal steps for the segments variant that light up to the value (tinted by their zone when there are thresholds). Auto is one segment per zone, or 10 steps without thresholds.
- `target?: number`: A tick across the track, cut into the surface so it reads over any color, and part of the spoken text. Hidden outside min..max. No default: without it there is no tick (the playground sets it at 75 % of the range).
- `roundCaps?: boolean` = true: Rounded arc ends (segment corners get a 4px radius). Off gives square ends.
- `label?: ReactNode` = "": Under the value, e.g. "Monthly goal". A string also names the meter; other nodes label it through aria-labelledby.
- `description?: ReactNode` = "": Under the label in muted text, e.g. "$6,760 of $10,000". Linked with aria-describedby.
- `showValue?: boolean` = true: The big number in the bowl.
- `showMinMax?: boolean` = true: The scale ends under the arc ends, compact for big numbers ("$190K").
- `showZone?: boolean` = true: A small chip in the zone's tone with its label, when the current zone has one.
- `valueFormat?: ChartValueFormat ("number" | "compact" | "currency" | "percent")` = "number": How the value and the scale ends print. percent takes whole numbers: 67.6 is "67,6 %".
- `currency?: string` = "USD": ISO 4217 code for valueFormat="currency", with its narrow symbol ("$", "€").
- `decimals?: number`: Fraction digits of the value. Auto keeps the final value's digits all through the count (67,6 counts in tenths, 42 in whole numbers).
- `formatValue?: (value: number, context: { kind: "value" | "tick" | "label" }) => string`: Full control over the text, e.g. v => `${v.toLocaleString("en-US")} h`. value is called on every frame of the count, tick for min / max, label for the spoken text.
- `locale?: string` = "": Intl locale for every number. Empty follows the UIProvider, then the page.
- `surface?: string` = "": The color behind the gauge: the target notch and the segment marker are cut in it. Empty uses the surface token.
- `animated?: boolean` = true: Sweeps and counts in the first time it scrolls into view, then glides between values. Off renders the final state (thumbnails, print).
- `loading?: boolean` = false: The chart kit's gauge skeleton and a placeholder for the value; the label stays.
- `labels?: { target?: string; zone?: (label: string) => string; valueText?: (value, min, max, info) => string; empty?: string; loading?: string }`: The spoken text. Defaults: "target", "{label} zone", "No data", "Loading"; valueText replaces the whole aria-valuetext (info has the formatted text, zone and target).
- `classNames?: Partial<Record<"dial" | "svg" | "track" | "band" | "arc" | "segment" | "needle" | "marker" | "target" | "content" | "value" | "label" | "description" | "zone" | "min" | "max", string>>`: Extra classes for the parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { Gauge } from "@/components/ui/gauge"

export function SalesGoal() {
  return (
    <Gauge
      value={67.6}
      valueFormat="percent"
      target={75}
      thresholds={[
        { value: 0, tone: "danger", label: "Behind" },
        { value: 50, tone: "warning", label: "Close" },
        { value: 75, tone: "success", label: "Good" },
      ]}
      label="Monthly sales goal"
      description="$6,760 of $10,000"
      locale="en-US"
    />
  )
}
```

Docs: https://wingo-ui.com/components/gauge (Markdown: https://wingo-ui.com/components/gauge.md)

#### GitHub Activity (`github-activity`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add github-activity`

A contribution heatmap with a footer panel that expands over the grid to rank your top repositories.

The grid sweeps in column by column, then the month labels blur into focus. Hover any cell, or press one on a touchscreen, for its count and date. Click the chevron to expand the top repositories over the grid, their avatars flying out of the stack into rows, and again to fold them back. The grid shows as many recent weeks as fit its width, so it never scrolls sideways on a phone.

npm: motion
Wingo UI dependencies: ui-config

Props:
- `username?: string` = "": A GitHub username to load the last year of contributions and the most-pushed repositories for, from public APIs. Ignored for whichever of contributions or repos you pass yourself. An unknown or invalid name shows a not found heading and calls onError.
- `contributions?: Contribution[]` = "[]": Your own contribution data, one { date, count, level } per day in date order, starting on a Sunday. Level 0 to 4 picks the shade.
- `repos?: RepoContribution[]` = "[]": The repositories listed in the footer, highest first: { name, count, logo?, href? }. The first avatarCount (3) stack as avatars; a missing logo shows the initial.
- `year?: number` = 0: Overrides the year in the heading. 0 uses the year of the latest contribution (2025 in this sample).
- `accent?: string | string[]` = "#39d353": The color of the contribution squares. One color is faded per level; an array of four shades (or five, with the empty color first) sets each level exactly.
- `cellSize?: number` = 11: Size of each day square in pixels. The gap scales with it.
- `cellRadius?: number` = 3: Corner radius of each day square in pixels.
- `background?: string` = "": Any CSS color for the card. Empty is white in light mode and black in dark mode. The heading and the panel keep the theme colors, so pick a background that suits the theme.
- `radius?: number` = 28: Corner radius of the card in pixels; the repository panel inside follows it minus 10px.
- `chevronColor?: string` = "": Any CSS color for the round chevron that opens the panel. Empty uses #C4C9CC light, #3E4346 dark. It keeps a 44px hit area on touch screens.
- `avatarCount?: number` = 3: How many repository avatars stack in the closed footer (and, with username, how many repositories are fetched).
- `months?: number` = 12: How many months of history to show, at most. The grid also drops older weeks that do not fit its width.
- `showMonths?: boolean` = false: Adds a row of month names above the grid.
- `label?: string` = "Top contributions in:": Text shown in the footer next to the avatars.
- `locale?: string` = "": Intl locale for the month names, the tooltip date and the heading count. Falls back to UIProvider's locale, then en-US.
- `headingLabel?: string` = "{count} contributions": Heading template; {count} fills in the total.
- `yearLabel?: string` = "in {year}": Appended to the heading when there is a year; {year} fills in.
- `notFoundLabel?: string` = "No public activity found for {login}": Heading when username has no public calendar; {login} fills in.
- `dayLabel?: string` = "{count} contributions on {date}": Tooltip template for a day; {count} and {date} fill in.
- `dayLabelOne?: string` = "{count} contribution on {date}": Tooltip template for a day with exactly one contribution.
- `showReposLabel?: string` = "Show top repositories": Accessible name of the chevron while the panel is closed.
- `hideReposLabel?: string` = "Hide top repositories": Accessible name of the chevron while the panel is open.
- `defaultOpen?: boolean` = false: Starts with the repository panel open. Ignored when open is set.
- `open?: boolean`: Panel state for controlled usage. When set, the component stops managing its own state.
- `onOpenChange?: (open: boolean) => void`: Called with the next state when the chevron is clicked.
- `onError?: (username: string) => void`: Called when username is not a valid GitHub login or its calendar cannot be loaded, for example to fall back to data you pass yourself.
- `className?: string`: Extra classes for the card that wraps the grid. Its width fits the visible weeks (at least 320px) and is capped at the parent width; pass max-w-* to show fewer weeks.

Parts:
- `Contribution` (type): One day of contributions: { date: "YYYY-MM-DD", count, level: 0 | 1 | 2 | 3 | 4 }. Pass them oldest first, starting on a Sunday.
- `RepoContribution` (type): One repository in the footer: { name, count, logo?, href? }.
- `ContributionLevel` (type): The five intensity steps of a day, 0 (none) to 4 (most).

```tsx
import GitHubActivity from "@/components/ui/github-activity"

export function Demo() {
  return <GitHubActivity username="octocat" />
}

// or pass everything yourself:
// <GitHubActivity
//   contributions={contributions}
//   repos={[{ name: "Zero mail", count: 412, logo: <ZeroIcon /> }]}
//   accent={["#0e4429", "#006d32", "#26a641", "#39d353"]}
// />
```

Docs: https://wingo-ui.com/components/github-activity (Markdown: https://wingo-ui.com/components/github-activity.md)

#### Heatmap calendar (`heatmap-calendar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add heatmap-calendar`

Activity by day over weeks or a year: a grid of day cells on a one-hue scale, with month and weekday labels, a total and a legend.

The first time the heatmap scrolls into view its week columns fade and rise from left to right in one quick sweep. Hover a day for a readout of its date and value (the nearest day answers, so gaps never flicker) and click it to select it (click the selected day again to clear it). On a phone the year is a horizontal rail that opens at the newest week, with fading edges and week snapping while the weekday labels stay pinned; vertical drags still scroll the page. A first tap on a day pins its readout above the grid, a second tap on the same day selects it, a tap outside clears the readout. With the keyboard, Tab lands on one day (the selected one, else the newest): Left / Right move by a week, Up / Down by a day, Home / End jump to the first and last day shown, PageUp / PageDown move by four weeks, Enter or Space select (again to clear) and Escape clears the selection. Every day has a spoken label and a screen reader table lists each month's total. When the data changes the colors crossfade.
Wingo UI dependencies: chart-kit, date-utils, use-controllable-state, use-scroll-edges, use-locale, ui-config

Props:
- `data: HeatmapDatum[] = { date: string; value: number; label?: string }[]`: One entry per iso day ("2026-09-24"). Missing days count as 0, duplicate dates add up, days outside the window are ignored and negative values draw as 0. label names the value in the tooltip.
- `endDate?: string` = "": Iso day of the last column. Empty uses the newest date in data (never the clock, so the server and the browser agree).
- `today?: string` = "": Iso day that gets the today ring. Empty uses the viewer's date, read after hydration.
- `weeks?: number` = 53: Week columns in the window, ending with the week of endDate.
- `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | -1` = -1: First row of each column: 0 is Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Monday in en-GB, Sunday in en-US). Changes the row order and the weekday labels.
- `levels?: number` = 5: Color steps including the empty level. Ignored when thresholds are given.
- `thresholds?: number[]`: Lower bound of each level above 0, ascending: [1, 5, 10, 20] gives five levels. Default: quantiles of the non-zero values, so any activity is at least level 1.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hue of the scale. Level 0 is the foreground at 7% (see emptyColor), then the tone from 30% to 100% in equal steps. neutral is the foreground ink.
- `color?: string` = "": Any CSS color, a palette slot ("series-3") or a tone name. Replaces the tone.
- `emptyColor?: string` = "": Fill of the days without activity (level 0 and its legend swatch): any CSS color or a palette slot. Empty uses the foreground at 7%, visible on white and on the dark surface.
- `cellSize?: "sm" | "md" | "lg"` = "md": 10 / 12 / 16px cells with 2 / 3 / 4px gaps.
- `radius?: "none" | "sm" | "md" | "full"` = "sm": Cell corners: 0 / 2 / 3px or circles. The legend swatches follow.
- `overflow?: "scroll" | "fit"` = "scroll": scroll: a horizontal rail that opens at the newest week, with edge fades and week snapping. fit: only the newest weeks that fit the width, nothing scrolls.
- `showMonthLabels?: boolean` = true: Short month names above the first column of each month, skipped when two would collide.
- `showWeekdayLabels?: boolean` = true: Monday, Wednesday and Friday in the locale's two-letter form, pinned while the rail scrolls.
- `showLegend?: boolean` = true: The Less ... More scale under the grid.
- `showTotal?: boolean` = true: The header sentence with the window's total (labels.total).
- `showTooltip?: boolean` = true: The readout on hover, tap and keyboard focus. Cell labels and the table still carry every value when off.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": float rides beside the day, fixed pins above the grid (never under a finger); auto is fixed on touch screens.
- `value?: string | null`: The selected day (iso) when you control it; it gets a 2px ring. Pair with onValueChange.
- `defaultValue?: string | null`: The day selected at first, uncontrolled (none by default).
- `onValueChange?: (date: string | null) => void`: Called when a day is selected, or with null when the selection clears.
- `onDateClick?: (date: string, datum: HeatmapDatum | null) => void`: A click, a second tap or Enter on a day; datum is null for days without data.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the tooltip, the total, the cell labels and the table.
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency ("$12,480").
- `decimals?: number`: Fraction digits; auto by magnitude when unset.
- `formatValue?: (value: number, context: { kind: "tooltip" | "label" | "table" | "total"; date?: string }) => string`: Replaces the built-in value formatting everywhere.
- `locale?: string` = "": Locale for numbers, month and weekday names, dates and the first day of the week. Empty uses the UIProvider / LocaleProvider locale.
- `animated?: boolean` = true: The column sweep on first view and the color crossfade on data changes. Reduced motion always shows the final state.
- `loading?: boolean` = false: A skeleton in the grid's box and in the total.
- `emptyState?: ReactNode`: Replaces the grid when data is empty. Without it an empty heatmap shows the zero grid and labels.noData.
- `label?: string` = "": Accessible name of the figure and the grid, caption of the table. Empty uses labels.table.
- `description?: string` = "": A one-sentence takeaway for screen readers.
- `surface?: string` = "": The color behind the heatmap, painted under the pinned weekday labels and the today ring. Empty uses the surface token; set it when the heatmap sits on another background.
- `actions?: ReactNode`: Trailing content of the header row: a period switch, a link.
- `labels?: Partial<HeatmapCalendarLabels>`: Strings: less, more, total(count, weeks), cell(value, date, datum), empty(date), noData, table, month, valueName, activeDays, loading. English by default.
- `classNames?: Partial<Record<HeatmapCalendarSlot, string>>`: Classes for header, total, actions, scroller, grid, cell, month, weekday, legend, tooltip and table.

```tsx
import { HeatmapCalendar, type HeatmapDatum } from "@/components/ui/heatmap-calendar"

const data: HeatmapDatum[] = [
  { date: "2026-09-21", value: 12 },
  { date: "2026-09-22", value: 9 },
  { date: "2026-09-23", value: 15 },
  { date: "2026-09-24", value: 7 },
]

export function TeamActivity() {
  return (
    <HeatmapCalendar
      data={data}
      endDate="2026-09-24"
      locale="en-US"
      label="Northwind CRM team activity"
      labels={{
        total: (n) => `${n} activities in the last year`,
        cell: (value, date) => `${value} activities on ${date}`,
        empty: (date) => `No activity on ${date}`,
      }}
      onDateClick={(date) => console.log(date)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/heatmap-calendar (Markdown: https://wingo-ui.com/components/heatmap-calendar.md)

#### Leaderboard (`leaderboard`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add leaderboard`

A ranked list of people, teams or products by one metric: medals, proportional bars, rank changes, a podium and a pinned "you" row.

Read top to bottom: rank or medal, avatar, name, a bar that shows how far each one is from the leader, the value and the move since last period (a green ▲2, a red ▼1, a gray dash when nothing moved, a blue "New"). The first time it scrolls into view the bars grow and the values count up; when the numbers change, rows glide to their new place and the rank chips pop. With onItemClick every row is a button: Tab lands on the list once, Up / Down, Home / End and PageUp / PageDown move between rows, Enter opens one. "Show all" expands the rest; your own row stays pinned under the top rows with a gap when it falls outside the limit. On a phone rows are at least 44px, the value never truncates (the name does) and the podium keeps three columns down to 320px. Screen readers hear one sentence per row: "Rank 1, Daniel Reed, $48,921, up 1 place". Reduced motion shows the final state at once.

npm: motion, lucide-react
Wingo UI dependencies: avatar, badge, button, chart-kit, motion, skeleton, tones, trend-badge, ui-config, use-controllable-state, use-locale

Props:
- `items: LeaderboardItem[]`: { id, name, value, avatar?, icon?, description?, previousRank?, delta?, href?, searchName? }. Ranked by value unless sort is none; equal values share a rank (1, 1, 3). previousRank null marks a new entry. icon replaces the avatar with a tile (products, channels).
- `title?: ReactNode` = "": The heading above the list; also the list's accessible name.
- `metric?: ReactNode` = "": The caption under the title: what is ranked and for which period.
- `highlightId?: string` = "": The id of the current user's row: tinted, with a "You" chip. When it falls outside the limit it is pinned as an extra last row after a gap.
- `valueFormat?: LeaderboardValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print, through the chart kit with the locale: "48,921", "49K", "$48,921", "12.4%".
- `currency?: string` = "USD": ISO 4217 code for valueFormat="currency" (and deltaFormat="currency"), printed with its narrow symbol. An unknown code prints as a plain unit after the number.
- `decimals?: number`: Fraction digits for values (0 to 6); auto when unset: 0 from 100 up, 1 for percent, up to 2 for small numbers.
- `formatValue?: (value: number, item: LeaderboardItem) => string`: Full control over the value text, e.g. minutes: v => `${v} min`. The count-up and the spoken sentence use it too.
- `locale?: string` = "": Intl locale for values and deltas. Empty uses the UIProvider locale, then the page's language.
- `actions?: ReactNode`: Controls at the end of the header: a period picker, a button.
- `variant?: "surface" | "plain"` = "surface": surface is a raised panel (a list group); plain is bare rows for use inside a card or on a page.
- `size?: "sm" | "md" | "lg"` = "md": Rows at least 44 / 56 / 64px with 32 / 40 / 48px avatars; a description plus a bar adds a little height. sm never goes below 44px, so it stays a full touch target.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The bar fill. neutral is the foreground ink (black in light mode, white in dark).
- `color?: string` = "": Any CSS color or a chart palette slot ("series-3") for the bars; replaces the tone.
- `showChange?: "rank" | "delta" | "none"` = "rank": rank: ▲2, ▼1, a gray dash or New, from previousRank. delta: a ghost trend badge from each item's delta. none hides the column.
- `deltaFormat?: LeaderboardDeltaFormat = "percent" | "number" | "currency"` = "percent": How deltas print with showChange="delta" (12.4 is +12,4 %).
- `invertTrend?: boolean` = false: With showChange="delta": a falling delta is good and turns green (response time, costs).
- `podium?: boolean` = false: The top three on steps above the list: 2nd left, 1st in the middle and raised with a crown, 3rd right. The list continues from rank 4. Needs at least three items.
- `showRank?: boolean` = true: The rank column (numbers or medals).
- `medals?: boolean` = true: Ranks 1 to 3 as gold, silver and bronze discs, in the list and on the podium.
- `medalColors?: [string, string, string]` = "[\"#E8B923\", \"#A7AFBA\", \"#C27C4E\"]": Gold, silver and bronze. The number on each disc turns dark or white by the color's lightness.
- `showAvatars?: boolean` = true: The avatar (photo or initials) or the item's icon tile before the name.
- `showBars?: boolean` = true: A 4px bar under each name, proportional to the largest value. Hidden when the largest value is zero or less.
- `dividers?: boolean` = true: Hairlines between rows.
- `sort?: "desc" | "asc" | "none"` = "desc": desc ranks the highest first; asc is for lower-is-better metrics (response time); none keeps the given order.
- `limit?: number` = 5: Rows before "Show all" (after the podium when it is on). 0 shows every row; a limit larger than the list hides the button.
- `loading?: boolean` = false: Skeleton rows with the avatar shape; the header stays.
- `defaultExpanded?: boolean` = false: Starts with every row shown. Use expanded / onExpandedChange to control it.
- `expanded?: boolean`: Controlled "show all" state.
- `onExpandedChange?: (expanded: boolean) => void`: Fires when Show all / Show less is pressed.
- `emptyState?: ReactNode`: Shown when items is empty. Defaults to a trophy tile with labels.empty.
- `animated?: boolean` = true: Bars grow and values count up the first time the list scrolls into view; rows glide to their new place when the order changes and rank chips pop. Off (and under reduced motion) everything renders final.
- `onItemClick?: (item: LeaderboardItem, rank: number) => void`: Makes every row a button with roving focus (Up / Down, Home / End, PageUp / PageDown, Enter).
- `renderLink?: (props: ComponentProps<"a">) => ReactElement`: Renders rows whose item has an href, e.g. props => <Link {...props} href={props.href!} />. Defaults to a plain <a>.
- `labels?: Partial<LeaderboardLabels>`: showAll(n), showLess, you, new, up(n), down(n), same, increase(text), decrease(text), rank(n), item(rank, name, value, change), empty, loading, list, podium. English defaults; item defaults to rank(n), name, value and change joined with commas.
- `classNames?: Partial<Record<"header" | "title" | "metric" | "actions" | "podium" | "list" | "item" | "rank" | "avatar" | "name" | "description" | "value" | "change" | "bar" | "more", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { Leaderboard, type LeaderboardItem } from "@/components/ui/leaderboard"

const team: LeaderboardItem[] = [
  { id: "daniel", name: "Daniel Reed", value: 48920.5, avatar: "/demo/mihai-ionescu.jpg", previousRank: 2 },
  { id: "ryan", name: "Ryan Cooper", value: 31200, avatar: "/demo/radu-marin.jpg", previousRank: 1 },
  { id: "emma", name: "Emma Carter", value: 18080, avatar: "/demo/ana-pop.jpg", previousRank: 3 },
  { id: "grace", name: "Grace Kim", value: 14450, avatar: "/demo/maria-toma.jpg", previousRank: 5 },
  { id: "olivia", name: "Olivia Brooks", value: 3450, avatar: "/demo/elena-stan.jpg", previousRank: null },
]

export function TopSellers() {
  return (
    <Leaderboard
      title="Top sellers"
      metric="Revenue, September 2026"
      items={team}
      valueFormat="currency"
      currency="USD"
      locale="en-US"
      highlightId="emma"
      limit={4}
      onItemClick={(item) => console.log(item.id)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/leaderboard (Markdown: https://wingo-ui.com/components/leaderboard.md)

#### Line chart (`line-chart`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add line-chart`

Trends over time as smooth lines, with a crosshair readout of every series, a dashed comparison period, target lines and direct end labels.

Each line draws itself from left to right the first time the chart scrolls into view, the series a beat apart. Move the mouse over the plot and a crosshair snaps to the nearest point, the dots swell and a readout lists every visible series (it flips to the other side near the right edge). On a phone, tap a point to pin the readout above your finger, drag sideways to scrub through the points (a vertical drag still scrolls the page), tap the same point again or anywhere outside to clear it. With the keyboard, Tab to the plot: Left / Right walk the points, Home / End jump to the ends, PageUp / PageDown move by ten, Enter fires onDatumClick and Escape clears; a live region reads each point. Click or tap a legend entry to hide its series (the others rescale and glide), hover or focus one to highlight it. When the data changes, the lines morph to their new shape.

npm: motion, d3-shape
Wingo UI dependencies: chart-kit, motion, ui-config, use-locale

Props:
- `data: ChartDatum[]`: One row per x position, in drawing order (the chart does not sort): { month: "2026-09", incasari: 128450, cheltuieli: 81200 }. null values leave a gap.
- `xKey?: string` = "date": The row key for the x axis. ISO days ("2026-09-24") and months ("2026-09") print as local dates.
- `series?: LineChartSeries[]`: Which keys to draw, in color order: { key, label?, color?, name?, dashed?, strokeWidth? }. dashed draws a comparison period at 70% with a muted tooltip row. Inferred from the numeric keys of the first rows when omitted.
- `colors?: string[]`: Per-position palette overrides: a slot ("series-3"), a tone ("neutral", "brand") or any CSS color.
- `height?: number` = 240: Plot height in px, reserved before the chart measures so nothing jumps.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the tooltip, ticks, end labels and table. Percent takes whole numbers (12.4 -> "12,4 %").
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency, printed with the narrow symbol ("$128,450").
- `decimals?: number`: Fraction digits in the tooltip, labels and table; auto by magnitude when unset. Ticks stay short.
- `formatValue?: (value: number, context: { series: string; kind: "tooltip" | "tick" | "label" | "table" }) => string`: Replaces the built-in value formatting everywhere.
- `formatX?: (value: unknown, context: "axis" | "tooltip" | "table") => string`: Replaces the x label formatting (short on the axis, long in the tooltip and table).
- `locale?: string` = "": Locale for numbers and dates. Empty uses the UIProvider / LocaleProvider locale.
- `yDomain?: LineChartDomain = [number | "auto", number | "auto"]` = "[\"auto\", \"auto\"]": Fixed value bounds (0..100 for percentages). Auto floats around the data and the reference lines, then rounds to nice ticks.
- `curve?: "monotone" | "linear" | "natural" | "step"` = "monotone": Line interpolation. monotone never overshoots a data point; step for values that hold until they change.
- `strokeWidth?: number` = 2: Line width in px; a series' own strokeWidth wins.
- `showDots?: boolean` = false: A dot on every point, up to 31 points (12 on plots narrower than 480px); above that only the inspected point gets one.
- `showArea?: boolean` = false: A soft 16% gradient under the line when exactly one series is visible (use area-chart for several).
- `connectNulls?: boolean` = false: Bridge missing values instead of breaking the line.
- `endLabels?: boolean` = false: The last value and the series name at the right end of each line (up to 4 series). Under 360px the label keeps only the short value ($128K) and a legend names the lines (even with showLegend off); under 240px it hides. A colliding label is dropped, never nudged; the legend and tooltip still carry it.
- `showLastValue?: boolean` = false: A dot with a breathing halo on the last point of each series, for a live-data feel. With reduced motion or animated off the halo stays still.
- `showGrid?: boolean` = true: Hairlines at the value ticks.
- `showXAxis?: boolean` = true: Date / category labels under the plot, thinned from the newest backwards so they never collide.
- `showYAxis?: boolean` = true: Value tick labels, compact for big numbers ("$128K").
- `yAxisSide?: "start" | "end"` = "start": end puts the ticks on the right, finance style.
- `yAxisWidth?: number` = 0: Minimum width of the value axis in px; 0 sizes it to the tick labels. Give stacked or synced charts the same value so their plots and crosshairs line up.
- `showLegend?: boolean` = true: The legend; it only renders with two or more series (one series is named by the card title).
- `legendPosition?: "top" | "bottom"` = "top": Legend above or below the plot.
- `legendToggle?: boolean` = true: Legend entries are buttons that hide and show their series. The last visible series cannot be hidden.
- `showTooltip?: boolean` = true: The floating readout. When off, the crosshair, keyboard and screen reader announcements still work.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": float rides beside the crosshair, fixed pins above the plot (never under a finger); auto is fixed on touch screens.
- `referenceLines?: { value: number; label?: string; color?: string }[]`: Dashed target or average lines with a label ("Target $120,000"); always inside the value range.
- `animated?: boolean` = true: Draw-in on first view and morphs on data changes. Reduced motion always shows the final state.
- `loading?: boolean` = false: A line-shaped skeleton in the plot's box.
- `emptyState?: ReactNode`: Replaces the built-in empty state (shown when data is empty or every value is null).
- `label?: string` = "": Accessible name of the figure and caption of its data table. Empty joins the series names.
- `description?: string` = "": A one-sentence takeaway for screen readers ("Revenue grew 12.4% in September").
- `surface?: string` = "": The color behind the chart, used for dot rings. Empty uses the surface token; set it when the chart sits on a card.
- `hiddenSeries?: string[]`: Hidden series keys when you control legend toggling; pair with onHiddenSeriesChange. defaultHiddenSeries for uncontrolled.
- `defaultHiddenSeries?: string[]`: Series keys hidden at first, when the legend toggles on its own.
- `onHiddenSeriesChange?: (keys: string[]) => void`: Called when a legend entry hides or shows a series.
- `activeIndex?: number | null`: The inspected x index when you control it, so two charts can share one crosshair.
- `defaultActiveIndex?: number | null`: The index inspected at first (a pinned readout), uncontrolled.
- `onActiveIndexChange?: (index: number | null) => void`: Called as the crosshair moves (mouse, touch or keyboard) and with null when it clears.
- `onDatumClick?: (event: { index: number; datum: ChartDatum; series?: string }) => void`: A click or tap on the plot (the nearest point; series is the nearest line) or Enter on the inspected point.
- `labels?: Partial<LineChartLabels>`: Strings: empty, loading, table, inspectHint, showSeries, hideSeries, compare ((comparison)), period (Period).
- `classNames?: Partial<Record<LineChartSlot, string>>`: Classes for legend, plot, tooltip, table, grid, xAxis, yAxis, line, area, dot, endLabel, referenceLine, crosshair and inspect.

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

const data = [
  { month: "2026-07", revenue: 106300, expenses: 72400 },
  { month: "2026-08", revenue: 97500, expenses: 69900 },
  { month: "2026-09", revenue: 128450, expenses: 81200 },
]

export function RevenueChart() {
  return (
    <LineChart
      data={data}
      xKey="month"
      series={[
        { key: "revenue", label: "Revenue" },
        { key: "expenses", label: "Expenses" },
      ]}
      valueFormat="currency"
      locale="en-US"
      referenceLines={[{ value: 120000, label: "Target $120,000" }]}
      label="Revenue vs. expenses"
    />
  )
}
```

Docs: https://wingo-ui.com/components/line-chart (Markdown: https://wingo-ui.com/components/line-chart.md)

#### Radial bar (`radial-bar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add radial-bar`

Several goals at once as concentric activity rings or 270° radial bars, each filling toward its own target and lapping past 100%.

The first time the chart scrolls into view the rings sweep in one after another on a soft spring; a ring past its target keeps going for a second lap, its end cap casting a small shadow on the lap below. Hover a ring (or a legend row) and the others dim while the hole shows that ring's percent and name; when the hole is too small, a readout floats beside the ring's end instead. Click or tap a ring or a legend row to select it: it stays lit (even while you preview another ring) and the center keeps its readout; tap it again, or tap the hole, to clear. On a phone the ring nearest your finger wins (thin rings are easy to hit) and the legend sits below the chart under 480px of width. With the keyboard, Tab to the chart: the arrow keys walk the rings (Up / Left outward, Down / Right inward), Home / End jump to the outermost and innermost ring, Enter or Space selects, Escape clears; a live region reads each ring. The legend rows are buttons in the tab order after the chart. When the values change, the rings glide to their new length.

npm: motion, d3-shape
Wingo UI dependencies: chart-kit, motion, ui-config, use-controllable-state, use-locale

Props:
- `data: RadialBarDatum[] = { id: string; label: ReactNode; value: number; max?: number; color?: string; name?: string }[]`: One ring per item, outermost first. max is the ring's own target (the chart's max when left out); a value past it laps. Negative values draw as 0; a max of 0 or less leaves the ring empty.
- `max?: number` = 100: The target for items without their own max. 100 makes value a percentage.
- `variant?: "rings" | "bars"` = "rings": rings: full 360° activity rings with round caps. bars: 270° radial bars from 12 o'clock, each named just left of its start.
- `size?: "sm" | "md" | "lg" | number` = "md": Diameter 120 / 180 / 240px, or any number of px (a 52px ring for a list row). It shrinks with a narrower container and sets the center readout's type size.
- `thickness?: number` = 0: Ring width in px. 0 fits every ring with the gap and keeps about 46% of the radius as the hole (32% for bars), never under 6px and never past 22% of the radius.
- `gap?: number` = 4: Px of space between rings.
- `showTrack?: boolean` = true: Each ring's full track in its own color at 15%, so the remaining distance to the target is visible.
- `roundCaps?: boolean` = true: Rounded ring ends. Laps only cast their end-cap shadow with round caps.
- `showLabels?: boolean` = true: bars variant: the ring names right-aligned just left of 12 o'clock. They hide on their own when the rings are too close for 11px text.
- `showLegend?: boolean` = true: The list of rings with values and percentages; its rows select a ring.
- `legendPosition?: "auto" | "right" | "bottom"` = "auto": auto: beside the chart from 480px of container width, below it on narrower containers (decided by layout, so the server HTML is already right).
- `showValues?: boolean` = true: The "42 / 60" value and target in each legend row.
- `showPercent?: boolean` = true: The percent of target in each legend row, in a fixed-width column.
- `center?: ReactNode`: Content in the hole ("3 obiective"). While a ring is hovered, focused or selected, its readout (percent, name, and "42 / 60" on large holes) takes the place with a short cross-fade.
- `value?: string | null`: The selected ring id when you control the selection; pair with onValueChange. The other rings dim and the center shows it.
- `defaultValue?: string | null` = "null": The ring selected at first, uncontrolled.
- `onValueChange?: (id: string | null) => void`: Fires when a ring is selected from the chart, the legend or the keyboard, and with null when cleared.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values and targets print in the legend, readouts and table ("$128,450"). Percent takes whole numbers (67.6 -> "67.6%"). The progress percent is always a percent.
- `currency?: string` = "USD": ISO 4217 code for valueFormat currency, printed with the narrow symbol ("$190,000").
- `decimals?: number`: Fraction digits for values and targets; auto by magnitude when unset.
- `formatValue?: (value: number, context: { id: string; part: "value" | "max"; kind: "legend" | "tooltip" | "center" | "table" | "aria" }) => string`: Full override for printing values and targets, per ring (dollars for one ring, a plain count for another).
- `locale?: string` = "": Locale for numbers and percents. Empty uses the UIProvider / LocaleProvider locale.
- `showTooltip?: boolean` = true: A floating readout of the inspected ring when the hole is too small to show it (bars with many rings, size sm). The keyboard and screen reader readout stays on when false.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": float: beside the ring's end. fixed: pinned above the chart. auto: fixed on touch screens, float with a mouse.
- `animated?: boolean` = true: Rings sweep in on first view (laps included) and glide when values change. Reduced motion always shows the final state.
- `loading?: boolean` = false: A ring-shaped skeleton in the chart's box; the legend is hidden.
- `emptyState?: ReactNode`: Replaces the built-in empty state, shown when data is empty.
- `label?: string` = "": Accessible name of the figure and caption of its data table. Empty joins the ring names.
- `description?: string` = "": A one-sentence takeaway for screen readers ("Two of three goals are above 70%").
- `labels?: Partial<RadialBarLabels>`: Strings: empty, loading, inspectHint, ring (Goal), value, target, progress, selected, and valueText(value, max, percent) for "42 of 60, 70%".
- `classNames?: Partial<Record<RadialBarSlot, string>>`: Classes for legend, legendItem, svg, ring (the group), track, fill, lap, label, center, tooltip, table and inspect.
- `className?: string`: Extra classes for the figure (the root), merged last.

```tsx
import { RadialBar } from "@/components/ui/radial-bar"

const goals = [
  { id: "calls", label: "Calls", value: 42, max: 60 },
  { id: "meetings", label: "Meetings", value: 7, max: 10 },
  { id: "quotes", label: "Quotes sent", value: 12, max: 15 },
]

export function TeamActivity() {
  return (
    <RadialBar
      data={goals}
      label="Team activity today"
      center={<span className="text-xl font-semibold">3 goals</span>}
      onValueChange={(id) => console.log(id)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/radial-bar (Markdown: https://wingo-ui.com/components/radial-bar.md)

#### Sparkline (`sparkline`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add sparkline`

A word-sized chart for table cells, list rows, KPI tiles and running text: a line, an area, bars or win / loss ticks.

Read-only by default: the line draws in from the left the first time it scrolls into view and the last point pops in as a dot; screen readers hear the label and a summary ("from $8,200 to $12,480, +52.2%"). With interactive on, the sparkline becomes one tab stop: hover it with a mouse, or tap and drag sideways with a finger (vertical drags still scroll the page), and a compact readout above it shows the point's label and value while a hairline and a dot follow. The whole row height (8px above and below) is the touch target, a second tap on the same point or a tap outside clears it. From the keyboard, Tab focuses it, Left / Right walk the points, Home / End jump to the ends, Page Up / Page Down move by 10, Escape clears, and a polite live region reads each point. When the data changes the line and bars glide to their new shape. Reduced motion shows everything at once.

npm: motion, d3-shape, d3-scale
Wingo UI dependencies: chart-kit, trend-badge, use-controllable-state, use-locale, motion, number-format, tones, ui-config

Props:
- `data: (number | null)[] | { value: number | null; label?: string; date?: string }[]`: The values, oldest first. Rows can carry a label ("Week 39") or an iso date for the readout; null leaves a gap in the line.
- `type?: "line" | "area" | "bar" | "win-loss"` = "line": line, line over a soft fading fill, bars from zero, or win-loss: equal ticks up for positive and down for negative values (streaks, daily goals). Bars fall back to a line above 120 points.
- `width?: number` = 96: Width in px. 0 fills the container (the parent needs a width, e.g. a grid cell or a flex-1 box).
- `height?: number` = 28: Height in px. 28 reads well in a phone row; 16 sits inside a line of text.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The stroke and fill color. neutral is the ink (black in light mode, white in dark mode).
- `color?: string` = "": Any CSS color, a palette slot ("series-3") or a tone name. Replaces tone and trendColor.
- `trendColor?: boolean` = false: Color by the direction from the first to the last value: success when it rose, danger when it fell, the ink when flat. Win-loss paints wins green and losses red.
- `invertTrend?: boolean` = false: Down is good (costs, churn, response time): a fall turns green under trendColor and reads as positive (data-intent).
- `curve?: "monotone" | "linear" | "natural" | "step"` = "monotone": How the line joins the points. monotone never overshoots a value; step suits counts that jump.
- `strokeWidth?: number` = 1.5: Line width in px, with round caps and joins.
- `showLast?: boolean` = true: A 5px dot on the last point, ringed in the surface color. For bars, the last bar keeps the full color and the others soften.
- `showMinMax?: boolean` = false: Small hollow dots at the lowest and the highest point (bars: those bars in full color).
- `reference?: "none" | "first" | "average" | "zero"` = "none": A dashed hairline at the first value, the average or zero (zero widens the range to include it).
- `surface?: string` = "": The color behind the sparkline, used for the rings around dots. Empty is the surface token.
- `min?: number`: Lower bound of the value range. Share min and max across the rows of a table so the sparklines compare.
- `max?: number`: Upper bound of the value range.
- `interactive?: boolean` = false: Focusable and inspectable: hover, tap, drag or arrow keys show each point in a compact readout pinned above the sparkline.
- `activeIndex?: number | null`: The inspected point, controlled (with onActiveIndexChange), so a value next to the sparkline can follow the scrub.
- `defaultActiveIndex?: number | null`: The inspected point on mount, uncontrolled (default null).
- `onActiveIndexChange?: (index: number | null) => void`: Called when a point is inspected or the readout clears.
- `valueFormat?: ChartValueFormat = "number" | "compact" | "currency" | "percent"` = "number": How values print in the readout and the accessible summary ("$12,480" with currency and en-US).
- `currency?: string` = "USD": ISO 4217 code for valueFormat="currency", printed with its narrow symbol.
- `formatValue?: (value: number, context: "tooltip" | "label" | "value") => string`: Full control over printed values, e.g. v => `${v} orders`.
- `locale?: string` = "": Intl locale for values and dates. Empty follows the UIProvider, then the page.
- `label?: string` = "": The accessible name, e.g. "Revenue, last 12 weeks". A summary of the first and last value and the change is appended.
- `animated?: boolean` = true: Draws in the first time it scrolls into view (0.6s), the last dot pops in after it; data changes glide either way. Off under reduced motion.
- `labels?: { summary?: (first: string, last: string, change: string) => string; empty?: string; point?: (index: number, count: number) => string; inspectHint?: string }`: Screen reader strings. Defaults "from {first} to {last}, {change}", "No data", "{n} of {count}" and the arrow-key hint, exported as DEFAULT_SPARKLINE_LABELS.
- `classNames?: Partial<Record<"svg" | "line" | "area" | "bar" | "last" | "reference" | "tooltip", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, e.g. "align-[-0.2em]" inside text. Other props (id, data-*, aria-*, events) spread onto the root span.

Parts:
- `SparklineWithValue` (component): A sparkline with the current value and a TrendBadge, for table cells and list rows. value = the last point (the inspected point while scrubbing); delta = the % change first -> last (with deltaFormat "number" / "currency": last - first); deltaFormat = "percent"; badgeVariant = "ghost"; badgeSize = "sm"; showDelta = true; layout "inline" (default) | "stacked" (value and badge over the sparkline) | "responsive" (stacked below 640px); badgeLabels for the badge's spoken text; classNames { sparkline, value, badge, meta, ...the Sparkline slots }. className and style go to the wrapper, every other prop to the Sparkline, and activeIndex / onActiveIndexChange work the same. Props: SparklineWithValueProps.

```tsx
import { Sparkline, SparklineWithValue } from "@/components/ui/sparkline"

const revenue = [8200, 8650, 8400, 9100, 9480, 9230, 10150, 10600, 10380, 11420, 11900, 12480]

export function ClientRow() {
  return (
    <div className="flex items-center justify-between gap-3">
      <span className="text-sm font-medium">Tech Solutions Inc.</span>
      <Sparkline
        data={revenue}
        valueFormat="currency"
        locale="en-US"
        label="Revenue, last 12 weeks"
        interactive
      />
      <SparklineWithValue
        data={revenue}
        type="area"
        valueFormat="currency"
        locale="en-US"
        layout="responsive"
        min={0}
        max={16000}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/sparkline (Markdown: https://wingo-ui.com/components/sparkline.md)

#### Stat Card (`stat-card`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add stat-card`

The KPI tile of a dashboard: a label, a big number that counts up, a delta pill that knows good from bad, a sparkline and a goal bar.

It is read, not operated. The first time a card scrolls into view its number counts up from zero (900ms, easing out), the delta pill fades in and rises 4px just after, and the sparkline draws from left to right; later value changes count from the number on screen, and a change that arrives mid-count retargets without a jump. The server and the first paint already show the final numbers, and screen readers hear one sentence with the final value and the change ("$128,450, up 12.4% vs. last month"), never the numbers in between. The delta is green when the change is good and red when it is bad; with invertTrend a drop in costs or response time is green. The info icon opens its explanation on hover, on keyboard focus, and on a tap or long press on phones (a 44px hit area); Escape closes it. With href or onClick the whole card is one link or button (Tab to it, Enter to open): it dips to 0.98 while pressed, lifts on hover, and shows a chevron (always visible on touch); the info button and the action slot stay separately clickable. In a StatGroup the tiles count up 60ms apart (capped at 12 tiles); on phones the group is two columns and md values shrink to fit 360px. Under reduced motion numbers and charts appear final at once. In the playground press Simulate a new day: a new day joins the sparkline and the value and delta count to their new numbers.

npm: motion, d3-scale, d3-shape, lucide-react
Wingo UI dependencies: animated-counter, progress, skeleton, tooltip, use-locale, motion, number-format, tones, ui-config

Props:
- `label?: ReactNode` = "": What the number is, in the header; truncates with a title on narrow tiles. When empty the playground shows a sample that follows format (Revenue for currency).
- `value?: number | string | null` = 128450: The number. It counts up and is formatted by format; a string renders as is (no animation); null or no value shows emptyValue. The playground starts at a sample 128450; the component's default is null.
- `format?: "number" | "currency" | "percent" | "compact" | "duration" (StatValueFormat)` = "number": How the number reads, in the locale: 128,450, $128,450 (see symbolDisplay), 12.4% (value 12.4), 128.5K, or a duration from seconds in its largest two units ("2 hr, 15 min", "18 days").
- `currency?: string` = "USD": ISO 4217 code for format="currency" and deltaFormat="currency", printed with its narrow symbol ("$", "€", "£").
- `decimals?: "auto" | "0" | "1" | "2" | "3" | number` = "auto": Fraction digits of the value. auto: 0 for numbers from 100 up, the currency's digits below 1.000 (0 above), 1 for percent and compact. Fixed from the final value, so the count never changes width mid-way.
- `prefix?: ReactNode` = "": Text before the number for units format does not know, set smaller and muted ("≈").
- `suffix?: ReactNode` = "": Text after the number ("km", "/mo", "pcs").
- `delta?: number | null` = 12.4: The change vs the previous period, in deltaFormat units (12.4 is +12.4% with percent). Its sign sets the arrow; |delta| below 0.05 is flat. The playground's sample is 12.4; the component has none (no pill).
- `deltaFormat?: "percent" | "number" | "currency" | "duration" (StatDeltaFormat)` = "percent": Unit of delta: +12.4%, +8, +$1,250, or seconds as a duration (+2 days, 12 hr).
- `trend?: "auto" | "up" | "down" | "flat"` = "auto": The arrow. auto reads the sign of delta; set it to force a direction (a pill with only an arrow when there is no delta). For your own delta badges and tables the file exports the helpers the card uses: getStatTrend(delta, trend?) returns up | down | flat | null, getStatIntent(direction, invert?) returns positive | negative | neutral, and formatStatDuration(seconds, locale, display?) returns the duration text.
- `deltaLabel?: ReactNode` = "": The comparison after the pill, like "vs. last month". Also read in the spoken sentence.
- `period?: ReactNode` = "": A quiet caption at the end of the header, like "Sept. 2026".
- `info?: ReactNode` = "": What the metric means, on an info button beside the label: a tooltip on hover or focus, and on a tap on touch screens.
- `goal?: number` = 190000: Adds a goal bar (value / goal) with "68% of goal" and the formatted target. Numbers only; 0 or less hides it. The playground's sample is 190000; the component has none.
- `emptyValue?: ReactNode` = "–": Shown, muted, when value is null or missing. The playground's readout shows it; clear value in code to see it in the card.
- `size?: "sm" | "md" | "lg"` = "md": sm: compact (20px value, p-3, the sparkline at the end of the value row, 48 x 20); md: 28px value, p-4 / p-5, a 40px chart; lg: the hero (32px, 48px from 768px up, p-5 / p-6, a 64px chart).
- `variant?: "surface" | "card" | "outline" | "plain"` = "surface": surface: a raised white panel (dark: #1A1A1A) with the raised shadow; card: a flat gray tile; outline: a hairline border; plain: no container and no padding, for cards inside your own panel.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corners: 0, 12px, 16px or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accent of the icon tile, the sparkline and the goal bar. The delta never takes it: it is green or red by meaning.
- `color?: string` = "": Any CSS color; replaces the tone for the icon tile, sparkline and goal bar.
- `iconTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"`: The icon tile's own tint, independent of tone: a green Pro tile or an orange revenue tile over a neutral sparkline. Unset, the tile follows tone.
- `symbolDisplay?: "inline" | "muted" (StatSymbolDisplay)` = "inline": The currency symbol of format="currency": at the number's size and weight ("$0", "$128,450"), or smaller and muted beside it.
- `flatDelta?: "label" | "value" | "hidden" (StatFlatDelta)` = "label": How a change under 0.05 reads: a neutral "No change" pill (labels.unchanged), the zero value ("0%"), or no pill at all. A null delta never shows a pill.
- `sparklineType?: "line" | "area" | "bar"` = "area": The built-in sparkline: a line, a line over a soft gradient, or bars with the last one highlighted.
- `durationDisplay?: "long" | "short" | "narrow"` = "short": Unit words for format="duration" and deltaFormat="duration": 2 ore 15 minute, 2 ore 15 min., 2 h 15 m.
- `invertTrend?: boolean` = false: Down is good: costs, churn, response time. A drop turns green and a rise red; the arrow still points the real way.
- `loading?: boolean` = false: Skeletons with the real sizes for the value, delta, chart and goal; the label stays. aria-busy is set. When it turns false the number counts up.
- `animation?: "count" | "roll" | "none"` = "count": count: tweens from 0 the first time the card is seen, then from the previous value; roll: the AnimatedCounter odometer for live numbers (numbers and currency; changes roll, the first paint is final); none: static.
- `duration?: number` = 900: Milliseconds of the count (roll uses 70% of it per digit).
- `locale?: string` = "": Intl locale for every number. Empty uses the UIProvider locale, then the page language. The demo falls back to en-US.
- `icon?: ReactNode`: The header icon, in a tile: gray when neutral, tinted with the tone otherwise.
- `sparkline?: number[]`: Values for the built-in sparkline, oldest first. One point draws a dot; equal values draw a flat line. The file also exports the chart alone as Sparkline, for table cells and list rows: data (number[]), type ("line" | "area" | "bar"), width, height, size, tone, color, curve ("monotone" | "linear"), showLast, strokeWidth, animated, delay. Strokes stay 1.5px at any size, the area gets a soft gradient, and it draws in when it scrolls into view; aria-hidden.
- `chart?: ReactNode`: Replaces the sparkline with your own chart, in the same spot.
- `goalLabel?: (percent: number) => ReactNode`: The goal bar caption; defaults to labels.goal ("68% of goal").
- `formatValue?: (value: number) => string`: Full control over the number text. Called on every frame of the count, so keep it cheap.
- `formatDelta?: (delta: number) => string`: The delta text in place of deltaFormat. It gets |delta|; the sign is added (d => `${d} days`).
- `action?: ReactNode`: A control at the end of the header (a ⋯ menu button). It stays clickable on pressable cards.
- `href?: string` = "": Makes the whole card a link: press, hover lift, focus outline and a chevron hint (always shown on touch). Its accessible name is the label plus the spoken value and delta. The info button and the action slot stay clickable on top. The demo's link does not navigate.
- `selected?: boolean` = false: For a pressable card that filters or picks something (a status tile over a table): a 2px ring in the tone, aria-pressed on the button (onClick) or aria-current on the link (href). Leave it undefined on plain links.
- `linkProps?: Omit<ComponentProps<"a">, "href" | "onClick" | "children" | "className">`: Extra attributes for the link that covers an href card: target, rel (target="_blank" gets noopener), download, data-*.
- `onClick?: (event: MouseEvent<HTMLElement>) => void`: Makes the whole card a button (or runs alongside href).
- `footer?: ReactNode`: A row under a hairline that runs edge to edge ("View report →").
- `children?: ReactNode`: Extra content under the numbers, above the chart.
- `labels?: Partial<StatCardLabels>`: Strings: increase / decrease (text => "Up 12.4%"), unchanged ("No change"), goal (percent => "68% of goal"), info ("About this metric"), loading. Exported as DEFAULT_STAT_CARD_LABELS.
- `classNames?: Partial<Record<"header" | "icon" | "label" | "info" | "period" | "action" | "value" | "unit" | "delta" | "deltaLabel" | "chart" | "goal" | "footer", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the card, merged last. For a row of cards the file also exports StatGroup (role list): columns { base?: 1 | 2; sm?: 2 | 3; lg?: 2 | 3 | 4 } (2 on phones and 4 from 1024px by default), variant "separate" | "joined" (one panel with hairlines between tiles), size and animation passed down to cards that do not set their own, stagger (default true: tiles count 60ms apart, capped at 12) and radius.

```tsx
import { Clock, FileText, UserPlus, Wallet } from "lucide-react"
import { StatCard, StatGroup } from "@/components/ui/stat-card"

export function DashboardKpis({ daily }: { daily: number[] }) {
  return (
    <StatGroup variant="joined">
      <StatCard
        label="Revenue"
        icon={<Wallet />}
        value={128450}
        format="currency"
        delta={12.4}
        deltaLabel="vs. last month"
        sparkline={daily}
        goal={190000}
        locale="en-US"
       
      />
      <StatCard label="Invoices issued" icon={<FileText />} value={342} delta={8} deltaFormat="number" locale="en-US" />
      <StatCard label="New clients" icon={<UserPlus />} value={27} delta={-3.1} locale="en-US" />
      <StatCard
        label="Average time to payment"
        icon={<Clock />}
        value={18 * 86400}
        format="duration"
        delta={-2.5}
        formatDelta={(d) => `${d.toLocaleString("en-US")} days`}
        invertTrend
        locale="en-US"
       
      />
    </StatGroup>
  )
}
```

Docs: https://wingo-ui.com/components/stat-card (Markdown: https://wingo-ui.com/components/stat-card.md)

#### Tracker (`tracker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tracker`

A row of status blocks over time, one per day, hour or deploy: uptime pages, sync health, delivery success and habit streaks.

The first time the tracker scrolls into view its blocks rise from the bottom in one quick left-to-right sweep. Hover a block for a readout above the bar with its date, status and note; the block lifts and the others fade back (the nearest block answers, so thin blocks and gaps never flicker). Click a block to fire onBlockClick. On a phone the whole bar is the target: a tap pins the readout above it, a sideways drag scrubs through the days while a vertical drag still scrolls the page, a second tap on the same block opens it and a tap outside clears the readout. On narrow screens fit="latest" keeps only the newest blocks that fit and the start caption follows. With the keyboard, Tab lands on the bar (the newest block), Left / Right walk the blocks, Home / End jump to the ends, PageUp / PageDown move by ten, Enter or Space fire onBlockClick and Escape clears; a polite live region reads each block ("Degraded on August 14, 2026: Slow responses from the portal"). Screen readers get a summary of the counts per status and a table of every block. When a sliding window gains a block, the row glides one slot left and the new block rises in; status changes crossfade.

npm: motion
Wingo UI dependencies: chart-kit, date-utils, use-locale, motion, tones, ui-config

Props:
- `data: TrackerDatum[] = { id?: string; date?: string; status: string; label?: ReactNode; description?: ReactNode }[]`: One entry per block, oldest first. date is an iso day or date-time (the tooltip title and captions), label replaces the date as the title ("Deploy #482"), description is the note under the status. id (or the date) keys the update animations.
- `statuses?: Record<string, { label: string; tone?: Tone; color?: string }>`: Merged over the defaults key by key: ok (success, "Operational"), degraded (warning, "Degraded"), down (danger, "Outage"), maintenance (info, "Maintenance") and none (foreground at 10%, "No data"). Overriding only a label keeps the default tone and color ({ none: { label: "No data" } }). color takes any CSS color, a palette slot ("series-3") or a tone name and wins over tone. Your own keys come first in the legend. Unknown keys draw as none with a dev warning.
- `label?: ReactNode` = "": The title at the start of the header; also names the figure for screen readers.
- `summary?: ReactNode` = "": The figure at the end of the header, e.g. the uptime.
- `size?: "sm" | "md" | "lg"` = "md": Block height: 24 / 32 / 40px. On touch screens the tap target grows to at least 44px either way.
- `radius?: "none" | "sm" | "md" | "full"` = "sm": Block corners: 0 / 2 / 3px, or pills.
- `gap?: number` = 2: Pixels between blocks. With fit="all" it shrinks when the blocks would not fit otherwise.
- `fit?: "latest" | "all"` = "latest": latest: blocks keep minBlockWidth and the oldest drop off on narrow screens (the start caption follows). all: every block squeezes, down to 1px.
- `minBlockWidth?: number` = 4: The narrowest a block gets with fit="latest", in px.
- `showCaptions?: boolean` = true: Start and end captions under the bar ("90 days ago", "Today"), from labels.start and labels.end.
- `showLegend?: boolean` = false: The statuses present in the shown blocks, as keys with labels.
- `showTooltip?: boolean` = true: The readout on hover, tap and keyboard. The live region and the table still carry every block when off.
- `tooltipMode?: "auto" | "float" | "fixed"` = "fixed": fixed pins the readout above the bar, centered on the block; float rides beside it; auto floats with a mouse and pins on touch.
- `onBlockClick?: (datum: TrackerDatum, index: number) => void`: A click, a second tap on a pinned block, or Enter / Space on the inspected block. index is the position in data.
- `locale?: string` = "": Locale for the dates. Empty uses the UIProvider / LocaleProvider locale.
- `animated?: boolean` = true: The sweep on first view and the slide when blocks are appended. Reduced motion always shows the final state.
- `loading?: boolean` = false: A pulsing skeleton in the bar's shape, plus the summary and captions.
- `emptyState?: ReactNode`: Replaces the bar when data is empty. Default: the kit's empty state with labels.empty.
- `description?: string` = "": A one-sentence takeaway for screen readers, read before the counts per status.
- `labels?: Partial<TrackerLabels>`: Strings: start(count, first), end (string or (last) => string), block(status, date), summary(counts, total), table, date, status, note, loading, empty, inspectHint. English by default ("90 days ago", "Today", "Degraded on 14 August 2026").
- `classNames?: Partial<Record<TrackerSlot, string>>`: Classes for header, label, summary, bar, block, footer, legend, tooltip and table.

```tsx
import { Tracker, type TrackerDatum } from "@/components/ui/tracker"

const data: TrackerDatum[] = [
  { date: "2026-09-18", status: "ok" },
  { date: "2026-09-19", status: "degraded", description: "Higher response times" },
  { date: "2026-09-20", status: "ok" },
  { date: "2026-09-21", status: "ok" },
  { date: "2026-09-22", status: "ok" },
  { date: "2026-09-23", status: "ok" },
  { date: "2026-09-24", status: "ok" },
]

export function EinvoicingStatus() {
  return (
    <Tracker
      data={data}
      label="Tax e-invoicing sync"
      summary="99.82%"
      locale="en-US"
      statuses={{
        ok: { label: "Operational", tone: "success" },
        degraded: { label: "Degraded", tone: "warning" },
        down: { label: "Down", tone: "danger" },
      }}
      onBlockClick={(datum) => console.log(datum.date)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/tracker (Markdown: https://wingo-ui.com/components/tracker.md)

#### Trend badge (`trend-badge`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add trend-badge`

The delta chip for KPIs, table cells and leaderboards: an arrow, a signed change and a color that says whether the change is good.

A read-only chip, not focusable: an arrow and a signed number ("+12.4%", "−$3,200") tinted green when the change is good and red when it is bad, gray when nothing moved. Screen readers hear the direction in words ("Up 12.4% vs. last month"), never the arrow. With animated on it counts up from zero the first time it scrolls into view, glides to every new value without the pill changing width midway, and the arrow cross-fades when the direction flips. Tap the playground's Change button to watch it. Reduced motion shows the final number at once.

npm: motion, lucide-react
Wingo UI dependencies: motion, number-format, tones, ui-config, use-locale

Props:
- `value: number | null` = 12.4: The change, in format units: 12.4 is +12.4% with percent, 3200 is +$3,200 with currency. null or NaN renders emptyText in gray, without an arrow.
- `format?: "percent" | "number" | "currency"` = "percent": How the number prints, through Intl with the locale. Values of a million and up go compact ("+$1.3M").
- `currency?: string` = "USD": ISO 4217 code for format="currency", printed with its narrow symbol ("$", "€", "£").
- `decimals?: number` = -1: Fraction digits (0 to 6). The default -1 is auto: 1 for percent, 0 for numbers, and 0 for currency from 100 up (2 below).
- `formatValue?: (value: number) => string`: Full control over the visible text, e.g. v => `−${Math.abs(v)} days`. The sr sentence uses it too.
- `emptyText?: string` = "–": Shown instead of the number when value is null or NaN. Screen readers hear labels.empty.
- `label?: ReactNode` = "": The comparison, like "vs. last month". Joined into the spoken sentence.
- `labelPosition?: "inside" | "outside"` = "outside": outside puts the label after the pill in muted text (the stat card look) and wraps it below on narrow widths; inside keeps it in the pill.
- `trend?: "auto" | "up" | "down" | "flat"` = "auto": auto reads the sign of value. Force a direction when the meaning does not follow the sign.
- `flatThreshold?: number` = 0.05: A change smaller than this (absolute, in format units) counts as no change and gets the gray look.
- `invertTrend?: boolean` = false: Down is good: costs, churn, response time. A fall turns green and a rise red.
- `variant?: "soft" | "solid" | "outline" | "ghost"` = "soft": soft is the tinted pill, solid a filled chip for emphasis, outline a hairline border, ghost colored text with an arrow and no fill (for table cells).
- `size?: "sm" | "md" | "lg"` = "md": Height 20 / 24 / 28px with 11 / 12 / 13px text (the outside label follows). md matches the stat card's delta pill.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape: square, 4px, 6px, 8px or a pill (the badge's radii).
- `icon?: "arrow" | "trend" | "chevron" | "none"` = "arrow": Diagonal arrows, trend lines or chevrons (a dash or a flat arrow when nothing moved). Mirrors in RTL.
- `showSign?: boolean` = true: Prefix gains with a plus. A loss always shows its minus (the typographic one, as wide as the plus).
- `neutralTone?: boolean` = false: Every direction in the neutral ink, for places where green and red would suggest a judgment.
- `positiveTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": The color of a good change. info suits a metric that is not good or bad, like open tickets.
- `negativeTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "danger": The color of a bad change. warning softens it for metrics that are not alarming.
- `positiveColor?: string` = "": Any CSS color for a good change, replacing positiveTone in every variant. No change stays gray and neutralTone still wins.
- `negativeColor?: string` = "": Any CSS color for a bad change, replacing negativeTone in every variant.
- `animated?: boolean` = false: Counts up from zero when first in view and glides between values. Off by default so a table of badges does not all count at once.
- `locale?: string` = "": Intl locale for the number. Empty follows the UIProvider, then the page.
- `labels?: { up?: (text: string) => string; down?: (text: string) => string; flat?: string; empty?: string }`: The spoken sentence. Defaults "Up {x}", "Down {x}", "No change", "No data"; e.g. up: x => `up ${x}`.
- `classNames?: Partial<Record<"icon" | "value" | "label" | "group", string>>`: Extra classes for the icon, the number, the label and the wrapper around pill and outside label.
- `className?: string`: Extra classes for the pill, merged last. Override the tone vars here, e.g. [--tone-soft:transparent].

```tsx
import { TrendBadge } from "@/components/ui/trend-badge"

export function RevenueKpi() {
  return (
    <div className="flex flex-col gap-1">
      <span className="text-[13px] text-muted-foreground">Revenue</span>
      <span className="text-2xl font-semibold tabular-nums">$128,450</span>
      <TrendBadge value={12.4} label="vs. last month" locale="en-US" animated />
      <TrendBadge
        value={-2.5}
        invertTrend
        formatValue={(v) => `${v < 0 ? "−" : "+"}${Math.abs(v).toLocaleString("en-US")} days`}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/trend-badge (Markdown: https://wingo-ui.com/components/trend-badge.md)

### Layout

#### Accordion (`accordion`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add accordion`

A stack of disclosures for FAQs, settings sections and order details, with four variants, icons, descriptions and one or many open.

Click or tap anywhere on a row to open it: the answer grows out on a smooth spring while the rows below slide down, and the chevron flips (or the plus folds into a minus). In single mode opening one row closes the other. With a keyboard, Tab reaches the rows, Up and Down move between them, Home and End jump to the first and last, and Enter or Space toggles. Rows are at least 44px tall on every size and the whole row is the target, so they are easy to hit on a phone. With keepMounted, the browser's find in page opens the row that holds the match. With reduced motion nothing slides: the answer simply fades in and out.

npm: @radix-ui/react-accordion, lucide-react, motion
Wingo UI dependencies: use-controllable-state, motion, tones, ui-config

Props:
- `items: AccordionItemData[]`: The rows: { value, title, description?, icon?, extra?, content, disabled? }. value must be unique (a duplicate replaces the earlier row); extra is a short value before the indicator, like a price or a count. An empty list renders nothing.
- `type?: "single" | "multiple"` = "single": single keeps one row open at a time (value is a string); multiple lets any number stay open (value is a string[]).
- `collapsible?: boolean` = true: single type only: the open row closes again when clicked. Turn it off for sections where one must always stay open.
- `keepMounted?: boolean` = false: Keeps closed answers in the DOM (collapsed, hidden until found), so form fields keep their values, search engines read every answer and the browser's find in page opens the row that holds the match.
- `headingLevel?: 2 | 3 | 4 | 5 | 6` = 3: The heading level that wraps each row, so the accordion fits the page outline for screen readers.
- `variant?: "ghost" | "outline" | "soft" | "separated"` = "ghost": ghost is flush with hairlines between rows, outline and soft wrap the rows in one container, separated turns every row into its own raised card.
- `size?: "sm" | "md" | "lg"` = "md": Row height 44 / 56 / 64px with title 14 / 15 / 16px and content 13 / 14 / 15px. Even sm stays a full 44px touch target.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the outline and soft containers and of separated cards: 12 / 16 / 24px. On ghost rows it shapes the focus ring.
- `indicator?: "chevron" | "plus" | "none"` = "chevron": The open / closed mark. The chevron turns, the plus folds into a minus; none hides it.
- `indicatorPosition?: "start" | "end"` = "end": end puts the mark after the title. start puts it first, as a chevron that points at the title and turns down like a disclosure triangle; the content indents to the title.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Tints the open row's icon tile and indicator.
- `color?: string` = "": Any CSS color for the open row's tint, mixed for contrast in both themes. Leave empty to use the tone.
- `divided?: boolean` = true: Hairlines between rows. soft insets them to the row padding like a grouped list; separated cards ignore it.
- `disabled?: boolean` = false: Disables every row. Disable a single row with disabled on its item.
- `value?: string | string[]`: The open row (single) or rows (multiple), to control the accordion from outside.
- `defaultValue?: string | string[]`: The open row or rows on first render. Nothing is open by default ("" or []).
- `onValueChange?: (value: string | string[]) => void`: Called with the new value: a string for single ("" when the row closes), a string[] for multiple.
- `classNames?: Partial<Record<"item" | "trigger" | "icon" | "title" | "description" | "extra" | "indicator" | "content", string>>`: Extra classes for the inner parts of every row. content styles the padded inner box, not the animated wrapper.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `AccordionRoot` (component): The parts API, for rows that need custom markup. Takes every prop above except items and shares variant, size, indicator and tone with its parts. Props: AccordionRootProps.
- `AccordionItem` (component): One row. Its value is what the root's value speaks. Props: { value: string; disabled?: boolean }.
- `AccordionTrigger` (component): The clickable row inside its heading. children is the title; extra is a short value before the indicator. Props: { icon?: ReactNode; description?: ReactNode; extra?: ReactNode; children: ReactNode }.
- `AccordionContent` (component): The answer. className and props go to the padded inner box; keepMounted overrides the root's for this row. Props: ComponentProps<"div"> & { keepMounted?: boolean }.

```tsx
import { Accordion, type AccordionItemData } from "@/components/ui/accordion"

const faq: AccordionItemData[] = [
  {
    value: "posting",
    title: "How do I post a listing?",
    content: "Tap Post a listing, pick a category and upload your photos. The listing goes live within minutes.",
  },
  {
    value: "promotion",
    title: "How much does promotion cost?",
    content: "Promotion starts at $9.00 for 7 days, and the listing moves to the top results.",
  },
  {
    value: "returns",
    title: "Can I return an item?",
    content: "Yes, you have 14 days from delivery to return an item bought with delivery through the platform.",
  },
]

export function Faq() {
  return <Accordion items={faq} defaultValue="promotion" variant="separated" />
}
```

Docs: https://wingo-ui.com/components/accordion (Markdown: https://wingo-ui.com/components/accordion.md)

#### App Shell (`app-shell`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add app-shell`

The whole admin layout in one component: a collapsible, resizable sidebar, a top bar and the page; a drawer and a tab bar on phones.

On desktop the sidebar sits beside the page: press Mod+B (Cmd on a Mac, Ctrl elsewhere), the top bar's panel button or the sidebar's collapse button to fold it into a 64px icon rail (or, with collapsible="offcanvas", to slide it out completely); the width animates and the state is remembered in a cookie. With resizable, drag the sidebar's edge between 200 and 400px (the width follows the pointer and is saved on release), drag it below 120px to snap to the rail, double-click it to reset, or focus it with Tab and use Left / Right (16px), Home (rail), End (widest) and Enter (fold / unfold). Below the breakpoint the sidebar becomes a drawer: the top bar's menu button or Mod+B opens it, it closes on navigation, on Escape, on a tap on the dimmed page or by swiping it back, and focus returns to the menu button; with edgeSwipe a swipe from the start edge opens it too. The bottom tab bar shows on phones only. Tab once from the top of the page to reveal "Skip to content", which jumps straight to the page.
Wingo UI dependencies: sidebar, topbar, bottom-tab-bar, sheet, navigation, use-controllable-state, use-media-query, use-persisted-state, use-scroll-state, use-shortcut, motion, ui-config

Props:
- `sidebar?: ReactNode`: A Sidebar. The shell renders it in the desktop column (it drives its collapsed state, width and variant) and, on phones, a second copy with mode="sheet" inside the drawer, mounted only while the drawer is open. A wrapper component must forward its props (mode, variant, collapsible, width, className, style) to the Sidebar.
- `nav?: SidebarNavGroup[]`: A shortcut for small apps: renders <Sidebar groups={nav} /> when sidebar is not given.
- `topbar?: ReactNode`: A Topbar, sticky at the top of the content column. It renders the menu button (sidebar toggle on desktop, hamburger on phones) and gets aria-controls and the shortcut hint from the shell unless you set menuControls / menuShortcut (pass the Topbar element itself, not a wrapper component, for that). For your own header use AppShellTrigger (Button props plus kind, shortcut, tooltip, labels): the sidebar toggle with a tooltip on desktop, a hamburger that turns into an X on phones, nothing without a sidebar.
- `tabs?: ReactNode | NavItem[]`: Phones only: a BottomTabBar, or just its items. Hidden from mobileBreakpoint up. Fixed to the viewport with window scroll (the page is padded by --bottom-bar-offset), a static row under the page with content scroll.
- `banner?: ReactNode`: A full-width strip above everything, e.g. an Alert with radius="none" for a maintenance notice.
- `children?: ReactNode`: The page, rendered in <main id={mainId}>. The shell never animates it on navigation. Inside it, useAppShell() returns isMobile, collapsed / setCollapsed, mobileOpen / setMobileOpen, toggleSidebar, hasSidebar, scroll, labels, mainRef, sidebarWidth / setSidebarWidth, shortcut and the sidebarId / drawerId for aria-controls (it throws outside an AppShell).
- `variant?: "sidebar" | "inset" | "floating"` = "sidebar": sidebar: flush columns with a hairline. inset: the page sits in a raised rounded panel on a tinted shell (Linear, Vercel). floating: the sidebar is a raised panel 8px off the edges. Sets the sidebar's variant unless it has its own.
- `defaultCollapsed?: boolean` = false: Starts with the rail (or the sidebar hidden, with offcanvas). A stored cookie wins after hydration; read it on the server (persistedCookieName(`${persistKey}-collapsed`)) and pass it here so the first paint is right.
- `collapsed?: boolean`: Controlled collapsed state of the desktop sidebar. Pair it with onCollapsedChange.
- `onCollapsedChange?: (collapsed: boolean) => void`: Every change: the shortcut, the top bar button, the sidebar's collapse button, a drag to the rail.
- `collapsible?: "icon" | "offcanvas" | "none"` = "icon": icon: the sidebar folds into a 64px rail with tooltips. offcanvas: it slides out completely and the page takes the width. none: always expanded (the desktop toggle disappears; phones keep the drawer).
- `persistKey?: string` = "app-shell": Remembers collapsed and the width in the cookies `${persistKey}-collapsed` and `${persistKey}-width` (a server layout can read them). "" keeps both in memory.
- `defaultSidebarWidth?: number` = 256: The expanded sidebar width in px, and what a double-click on the resize handle resets to.
- `sidebarWidth?: number`: Controlled width in px. Pair it with onSidebarWidthChange.
- `onSidebarWidthChange?: (width: number) => void`: Fires once per change (pointer up, a key press, a reset), never per frame.
- `resizable?: boolean` = false: A handle on the sidebar's end edge: drag between 200 and 400px, below 120px it snaps to the rail, double-click resets. It is a keyboard-operable separator (arrows ±16px, Home, End, Enter).
- `mobileBreakpoint?: "md" | "lg"` = "md": Below it the sidebar becomes a drawer and the tabs show: md (768px) or lg (1024px, tablets get the phone layout). Layout switches with CSS, so the server HTML is right.
- `defaultMobileOpen?: boolean` = false: Starts with the phone drawer open (it only shows below the breakpoint).
- `mobileOpen?: boolean`: Controlled drawer state. Pair it with onMobileOpenChange.
- `onMobileOpenChange?: (open: boolean) => void`: The drawer opened or closed (menu button, shortcut, edge swipe, navigation, Escape, a tap outside, a swipe back).
- `mobileDrawerSize?: "sm" | "md"` = "sm": The drawer's width: 320 or 400px, always leaving a 48px sliver of the page to tap.
- `edgeSwipe?: boolean` = false: Phones: a 16px strip on the start edge opens the drawer after a 40px drag or a flick. Turn it on in installed PWAs; in Safari that edge is the browser's back gesture.
- `scroll?: "window" | "content"` = "window": window: the document scrolls (router scroll restoration, the iOS toolbar minimizing; the right default for apps). content: the content column scrolls on its own and is provided to the bars as their scroll container (embedded apps, iframes, this demo).
- `height?: "screen" | "full"` = "screen": screen: the viewport height (dvh). full: fills the parent, which needs a height.
- `shortcut?: string` = "mod+b": Toggles the sidebar: the rail on desktop, the drawer on phones. Shown in the top bar button's tooltip. "" binds nothing.
- `skipLinkLabel?: string` = "Skip to content": The skip link, the first focusable element: hidden until tabbed to, then it focuses the page.
- `mainId?: string` = "main": The id of <main>, the skip link's target.
- `container?: HTMLElement | null`: Where the drawer is portaled (default document.body).
- `labels?: { openMenu?: string; closeMenu?: string; collapse?: string; expand?: string; resize?: string; collapsed?: string; navigation?: string }`: English defaults ("Open menu", "Close menu", "Collapse sidebar", "Expand sidebar", "Resize sidebar", "Collapsed", "Navigation"). The first four are shared with the top bar's menu button through the shell context; resize names the resize handle, collapsed is its value text while the sidebar is a rail, navigation is the drawer's hidden title.
- `classNames?: Partial<Record<"sidebar" | "body" | "main" | "topbar" | "tabs" | "drawer" | "resize", string>>`: Extra classes for the parts: the desktop sidebar column, the content column (the raised panel in inset), <main>, the top bar, the tabs row, the drawer body and the resize handle.
- `className?: string`: Extra classes for the root.

```tsx
import type { ReactNode } from "react"
import Link from "next/link"
import { cookies } from "next/headers"
import { usePathname, useRouter } from "next/navigation"
import { FileText, House, Inbox, LayoutDashboard, Settings, Users } from "lucide-react"
import { AppShell } from "@/components/ui/app-shell"
import { Sidebar, type SidebarNavGroup } from "@/components/ui/sidebar"
import { Topbar } from "@/components/ui/topbar"
import { persistedCookieName } from "@/hooks/use-persisted-state"
import { LinkProvider, type NavItem } from "@/lib/navigation"

// app/providers.tsx ("use client"): every NavLink inside renders through next/link
export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter()
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      {children}
    </LinkProvider>
  )
}

const nav: SidebarNavGroup[] = [
  {
    items: [
      { label: "Home", href: "/", icon: <LayoutDashboard /> },
      { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
    ],
  },
  {
    label: "Sales",
    items: [
      { label: "Clients", href: "/clients", icon: <Users /> },
      { label: "Invoices", href: "/invoices", icon: <FileText /> },
    ],
  },
  { label: "Account", items: [{ label: "Settings", href: "/settings", icon: <Settings /> }] },
]

const tabs: NavItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Settings", href: "/settings", icon: <Settings /> },
]

// app/(app)/layout.tsx, a server component: the cookie renders the right sidebar on the first paint
export default async function AppLayout({ children }: { children: ReactNode }) {
  const stored = (await cookies()).get(persistedCookieName("app-shell-collapsed"))?.value
  return (
    <AppShell
      defaultCollapsed={stored === "true"}
      sidebar={<Sidebar groups={nav} filter />}
      topbar={<Topbar title="Summit CRM" />}
      tabs={tabs}
      labels={{ openMenu: "Open menu", closeMenu: "Close menu", collapse: "Collapse", expand: "Expand", navigation: "Main" }}
      skipLinkLabel="Skip to content"
    >
      {children}
    </AppShell>
  )
}
```

Docs: https://wingo-ui.com/components/app-shell (Markdown: https://wingo-ui.com/components/app-shell.md)

#### Card (`card`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add card`

The surface listings, stats, settings and plans sit on: media, header, body and footer parts, four variants and a lift-and-press mode.

A plain card just holds content. An interactive card lifts 2px on hover with a deeper shadow while its photo zooms in a touch, and dips to 98% while pressed; pressing a button inside it (a like, a menu) presses only that button. Link cards are one Tab stop with the focus ring around the whole card: Enter opens them, a click anywhere follows the link, and the buttons on the photo, in the header and in the footer keep working. A card with onClick is a real button to the keyboard (Enter or Space). Selectable cards built on a radio group move with the arrow keys and show a ring in the tone. A disabled card dims and leaves the tab order. Phones get no hover lift, only the press, and horizontal cards stack their photo on top below 640px.

npm: @radix-ui/react-slot
Wingo UI dependencies: tones, ui-config

Props:
- `title?: ReactNode` = "": Simple API: the heading (an h3). Pass a CardLink here to make the whole card a link (interactive turns on by itself). The demo shows its sample listing title while empty.
- `description?: ReactNode` = "": Simple API: the muted line under the title. The demo shows its sample while empty.
- `variant?: "elevated" | "outline" | "soft" | "ghost"` = "elevated": elevated is a raised white panel (the surface token with its shadow), outline a hairline frame, soft the flat gray tile (tinted by a tone), ghost only padding, for lists of cards on a panel. Deviation: elevated is a card-only value.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Tints soft and outline cards (the title takes the tone color) and colors the selected ring. Elevated and ghost cards only show it when selected.
- `color?: string` = "": Any CSS color. Replaces the tone: a 14% tint on soft cards, the border on outline cards, the selected ring.
- `size?: "sm" | "md" | "lg"` = "md": Padding 16 / 20 / 24px (md and lg use one step less on phones), 12 / 16 / 20px between parts, and the title size. Media bleeds and divided footers follow.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner radius: 0, 12, 16 or 24px; full falls back to 24px. Inset media takes the radius minus the padding.
- `interactive?: boolean` = false: Hover lift (2px and a floating shadow, a tint on ghost cards), a 0.98 press, pointer cursor and the focus ring; media zooms on hover. On by default with onClick, with a CardLink as the title prop, and with asChild onto a link, button or label. With the parts, set it next to a CardLink so the card really goes somewhere.
- `selected?: boolean` = false: A ring in the tone around selectable cards (plans, addresses, payment methods). With onClick the card also reports aria-pressed.
- `disabled?: boolean` = false: Dims the card and blocks the pointer, the lift and the press. Link and button cards, and a CardLink inside, get aria-disabled, leave the tab order and ignore clicks; disable other controls inside it yourself.
- `orientation?: "vertical" | "horizontal"` = "vertical": horizontal puts the media at the start from 640px up, bleeding to the top, bottom and start edges; phones keep it on top. With parts, wrap the rest in CardContent.
- `divided?: boolean` = false: A hairline above the footer, edge to edge (stopping at start media). The default for every CardFooter inside, which can still override it.
- `asChild?: boolean` = false: Renders your single child (an <a>, a router Link, a <label> around a radio) as the card, with its look and press. A link card cannot hold buttons; use a CardLink title for that. The demo swaps in a link and drops the like button.
- `children?: ReactNode`: With the simple props, the body (inside CardBody). Without them, the parts: CardMedia, CardHeader, CardBody, CardFooter.
- `action?: ReactNode`: Simple API: a control at the end of the header (a menu, a like, a badge). It stays clickable above a CardLink.
- `media?: ReactNode`: Simple API: an image URL, a <CardMedia> (for aspect, overlays, inset), or any node (a chart, a map), which fills the media slot at its own height.
- `footer?: ReactNode`: Simple API: footer content (end-aligned), or a <CardFooter> for its own align and divided.
- `onClick?: (event: MouseEvent<HTMLDivElement>) => void`: Makes the card a button: role=button, a Tab stop, Enter and Space, interactive on. Not called while disabled. Prefer asChild with a real <a> for navigation.
- `classNames?: Partial<Record<"media" | "content" | "header" | "title" | "description" | "action" | "body" | "footer", string>>`: Extra classes for the parts the simple API renders.
- `className?: string`: Extra classes for the card itself, merged last. Override the spacing vars here, e.g. [--card-padding:12px].

Parts:
- `CardMedia` (component): Photo or custom media that bleeds to the card edges (it reads --card-padding). Its children sit on top of the photo (a badge, a like button; direct child controls stay clickable above a CardLink), or are the media when there is no src.
- `CardHeader` (component): Grid with CardTitle and CardDescription on the start and CardAction at the end, centered on a lone title and top-aligned on two lines. Takes div props.
- `CardTitle` (component): An h3 (15px semibold at md, 14 / 17px at sm / lg) that takes the tone color on tinted cards. Takes h3 props.
- `CardDescription` (component): The muted line under the title; deepens on tinted cards so it keeps 4.5:1. Takes p props.
- `CardAction` (component): The header's end column for a control; relative z-[2], so it stays clickable above a CardLink. Takes div props.
- `CardBody` (component): Body text at the card's size (13 / 14 / 15px). Takes div props.
- `CardFooter` (component): Actions or meta in a row, pinned to the bottom when a grid row stretches the card; its direct buttons and links stay clickable above a CardLink. Takes div props.
- `CardContent` (component): The column next to start media in a horizontal card (the simple API always renders it). Takes div props.
- `CardLink` (component): A stretched link for the title: its ::after covers the card, so a click anywhere opens it (new tab, middle-click and long-press menus included) while CardAction and the direct controls of CardMedia and CardFooter stay separate (give other controls relative z-[2]). As the title prop it is described by the description prop, so a screen reader reads both. The card shows the focus ring; in a disabled card the link leaves the tab order. Takes a props.

```tsx
import { Heart } from "lucide-react"
import { Avatar } from "@/components/ui/avatar"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Card, CardFooter, CardLink, CardMedia } from "@/components/ui/card"

export function ListingCard({ onSave }: { onSave: () => void }) {
  return (
    <Card
      className="max-w-sm"
      media={
        <CardMedia src="/demo/apartment.jpg">
          <Badge variant="solid" size="sm" className="absolute start-3 top-3">New</Badge>
          <Button size="icon-sm" variant="soft" radius="full" aria-label="Save" onClick={onSave} className="absolute end-3 top-3">
            <Heart />
          </Button>
        </CardMedia>
      }
      title={<CardLink href="/listings/10482">2-bedroom apartment, Park Slope</CardLink>}
      description="Brooklyn · 580 sq ft · floor 3 of 4"
      footer={
        <CardFooter align="between">
          <span className="text-[17px] font-semibold">$445,000</span>
          <span className="flex items-center gap-2 text-[13px] text-muted-foreground">
            <Avatar src="/demo/ana-pop.jpg" name="Anna Price" size="xs" /> today, 2:20 PM
          </span>
        </CardFooter>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/card (Markdown: https://wingo-ui.com/components/card.md)

#### Collapsible (`collapsible`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add collapsible`

One section that opens and closes with a spring height animation, plus CollapsibleText, the show more clamp for long descriptions.

Click or tap anywhere on the row, or Tab to it and press Enter or Space, and the content slides open on a spring while the chevron turns and its round well fills with the tone; press again to fold it away, quicker than it opened. Inside outline and soft containers the row tints on hover and while pressed; a ghost row tints only the well. Rows are at least 44px tall at every size, so they are easy to hit on a phone. Long text shows three lines with the last one fading out and a Show more link under it (a 44px touch area on phones); the link only appears when the text really overflows, and collapsing scrolls the text back into view. With keepMounted the closed content stays in the page, so a half-filled form keeps its values and the browser's find in page opens the section on a match. With reduced motion the height changes at once and only the opacity eases.

npm: @radix-ui/react-collapsible, motion, lucide-react
Wingo UI dependencies: button, motion, tones, use-controllable-state, ui-config

Props:
- `title?: ReactNode` = "": The row's label. The demo shows its sample while this is empty.
- `description?: ReactNode` = "": A second, quieter line under the title.
- `extra?: ReactNode` = "": Trailing content before the indicator: a count, a price, a badge. The demo shows the chosen delivery price while this is empty.
- `icon?: ReactNode`: A leading icon in a tinted tile (28 / 32 / 40px by size). The tile takes the tone while open.
- `trigger?: ReactNode`: Your own trigger element instead of the built-in row, rendered with asChild (a Button, a sidebar item). Put a CollapsibleIndicator inside it for the turning chevron.
- `children?: ReactNode`: The content that opens and closes. Padding lives on an inner box, so the height animation never squashes it.
- `variant?: "ghost" | "outline" | "soft"` = "ghost": ghost is the flush row with no container, for panels and sidebars. outline draws a hairline rounded container, soft a tinted one; both inset the row and the content by the same padding.
- `size?: "sm" | "md" | "lg"` = "md": Row height 44 / 52 / 60px with titles of 14 / 15 / 16px and matching icon tiles, padding and content text. Even sm stays a full 44px touch target.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Container corners for outline and soft: 12 / 16 / 24px, full falls back to lg. On a ghost row it shapes the focus outline with the button's per-size radii.
- `indicator?: "chevron" | "plus" | "none"` = "chevron": chevron turns 180 degrees on a snappy spring; plus folds its vertical bar into a minus.
- `indicatorPosition?: "start" | "end"` = "end": end puts the indicator after the title. start makes the chevron a disclosure arrow that points right (left in RTL) and turns down when open, and indents the content so it lines up with the title.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Tints the icon tile and the indicator's round well while open. neutral goes from a gray icon to a full foreground one on a slightly darker tint.
- `color?: string` = "": Any CSS color. Replaces the tone for the open icon tile and indicator. Leave empty to use the tone.
- `divided?: boolean` = false: A hairline between the row and the open content, like a card header.
- `defaultOpen?: boolean` = false: Starts open when uncontrolled. Opening on first render skips the animation.
- `open?: boolean`: Controlled open state. Without onOpenChange it stays where you put it.
- `onOpenChange?: (open: boolean) => void`: Called with the next state when the row is pressed (or find in page opens a kept-mounted section).
- `disabled?: boolean` = false: Dims the row and blocks toggling. Content that is already open stays open.
- `keepMounted?: boolean` = false: Keeps the closed content in the DOM, collapsed to 0 and hidden="until-found": forms keep their values, search engines see the text, and find in page opens the section.
- `classNames?: Partial<Record<"trigger" | "icon" | "title" | "description" | "extra" | "indicator" | "content", string>>`: Extra classes for the parts. content styles the padded inner box of the animated region.
- `className?: string`: Extra classes for the root (the container for outline and soft), merged last.

Parts:
- `CollapsibleRoot` (component): The parts API: the root that holds the state and draws the container. Takes open, defaultOpen, onOpenChange, variant, size, radius, indicator, indicatorPosition, tone, color, divided, keepMounted and disabled, and shares them with its parts. The simple Collapsible is built from these parts. Props: CollapsibleRootProps.
- `CollapsibleTrigger` (component): The full-width row with the title as children, or your own element with asChild. Enter and Space toggle; aria-expanded and aria-controls come from Radix. Props: { icon?: ReactNode; description?: ReactNode; extra?: ReactNode; asChild?: boolean; children: ReactNode }.
- `CollapsibleContent` (component): The animated region. className goes to the padded inner box; the other props go to the wrapper whose height animates. keepMounted overrides the root's. Props: ComponentProps<"div"> & { keepMounted?: boolean }.
- `CollapsibleIndicator` (component): The turning chevron or plus on its own, for custom triggers. Unsized, it follows a Button's icon size. Props: { kind?: "chevron" | "plus" | "none"; position?: "start" | "end" }.
- `CollapsibleText` (component): Clamps long text to lines (default 3; 0 turns the clamp off) and springs to the full height. It measures the text, so short text gets no toggle, and re-measures when the text or width changes. fade (default true) fades the last line. The toggle is a small link Button ("Show more" / "Show less" by default) with aria-expanded and a 44px touch area; collapsing scrolls the text back into view if its start went off screen. Props: { lines?: number; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void; moreLabel?: string; lessLabel?: string; fade?: boolean; classNames?: { body?: string; toggle?: string } }.
- `useCollapsible` (hook): The nearest collapsible's state, e.g. to swap a custom trigger's label. Signature: () => { open: boolean; setOpen: (open: boolean) => void }.

```tsx
import { Truck } from "lucide-react"
import { Collapsible, CollapsibleText } from "@/components/ui/collapsible"

export function ListingDetails() {
  return (
    <div className="flex flex-col gap-4">
      <CollapsibleText lines={3} moreLabel="Read more" lessLabel="Read less" className="text-sm leading-relaxed">
        Linus Roadster city bike, aluminum frame size M, a 7-speed Shimano Nexus hub and brakes
        serviced last month. Only used for the commute and always kept in the garage.
      </CollapsibleText>
      <Collapsible
        variant="outline"
        icon={<Truck />}
        title="Delivery details"
        description="UPS, a parcel locker or local pickup"
      >
        <ul className="flex flex-col gap-2">
          <li>Fast courier (UPS) · $19.99 · 1-2 days</li>
          <li>Parcel locker · $12.99</li>
          <li>Local pickup in Brooklyn · free</li>
        </ul>
      </Collapsible>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/collapsible (Markdown: https://wingo-ui.com/components/collapsible.md)

#### Detail Layout (`detail-layout`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add detail-layout`

The page grid of a record (a client, a contact, an invoice): header, a main column of sections and a side panel, plus the section card.

Read a record the way it is built: the header on top, the main sections (activity, notes, invoices) on the left and the side panel (details, contacts, files) beside them once the layout itself is wide enough (960px of content), which sticks while the long column scrolls and scrolls on its own when it is taller than the screen. Below the breakpoint the panel moves under the main column, above it, or into a second tab: a full-width segmented control that sticks under the top bar, where a tap (or Tab then the arrow keys) switches panes with a short fade and both panes keep their scroll and state. Every section card has a title with a count, a pencil to edit and a ⋯ menu (an action sheet on phones); a collapsible section opens and closes from anywhere on its header row, with a mouse, a tap, or Enter / Space on the focused title, and its chevron turns. Loading sections show skeleton lines and fade into their content; empty ones show a small empty state with an action. Tab order is always header, main, side panel.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, collapsible, dropdown-menu, empty-state, segmented-control, skeleton, use-controllable-state, motion, ui-config

Props:
- `header?: ReactNode`: The top of the page, usually an EntityHeader. Nothing is reserved when it is left out.
- `children?: ReactNode`: The main column, usually DetailSection cards (activity, notes, invoices).
- `aside?: ReactNode`: The side panel's content (details, contacts, files). A <DetailAside> passed here is used as the panel itself, so it can carry its own props. None: a single column at maxWidth.
- `asidePosition?: "end" | "start"` = "end": Which side the panel takes from the breakpoint. The DOM stays main then aside, so reading and Tab order never change; start only reorders the grid.
- `asideWidth?: number` = 360: The side panel's width in px once the layout is 960px wide; with breakpoint md it is 300px between 720 and 960px.
- `asideSticky?: boolean` = true: The panel sticks under the top bar (--topbar-offset), the sticky header and --detail-sticky-offset (room for a bar that pins itself, like EntityHeader's 49px condensed bar) while the main column scrolls, and scrolls inside itself when it is taller than the viewport (--detail-viewport-height when the page scrolls inside a box).
- `stickyHeader?: boolean` = false: The header sticks at the top on a glass bar (use it when the header has no condensed bar of its own) and writes its height to --detail-header-height, so the panel and the phone tabs stick under it.
- `breakpoint?: "md" | "lg"` = "lg": Where the two columns start, measured on the layout's own width (a container query, so it works beside an app sidebar or in a panel): lg at 960px of content (a 1024px screen minus gutters; records need the width) or md at 720px, with a 300px panel up to 960px.
- `mobileAside?: "below" | "above" | "tab"` = "below": Below the breakpoint the panel goes after the main column, before it, or into a second tab (a sticky segmented control with labels.main / labels.aside; the hidden pane stays mounted).
- `gap?: "sm" | "md" | "lg"` = "md": 16 / 24 / 32px between the columns, the header and the main sections; the panel's cards sit a step closer.
- `maxWidth?: "none" | "lg" | "xl" | "2xl"` = "xl": The content width, centered: max-w-5xl / 6xl / 7xl, or the full width. The page provides the side gutters.
- `sectionVariant?: "surface" | "outline" | "plain"` = "surface": The default look of every DetailSection inside: a raised panel, a hairline outline, or plain on the page with a top hairline. A section's own variant wins.
- `loading?: boolean` = false: Every DetailSection inside shows its skeleton (unless it sets loading itself), then fades into its content.
- `tab?: "main" | "aside"`: The controlled phone tab (mobileAside="tab").
- `defaultTab?: "main" | "aside"` = "main": The phone tab to start on while uncontrolled (mobileAside="tab").
- `onTabChange?: (tab: DetailLayoutTab) => void`: Called when the phone tab changes.
- `labels?: Partial<DetailLayoutLabels>`: main ("Activity") and aside ("Details") name the phone tabs, asideRegion ("Details") names the <aside> landmark, tabs ("Page sections") names the tab group. English defaults in DEFAULT_DETAIL_LAYOUT_LABELS.
- `classNames?: Partial<Record<"header" | "body" | "main" | "aside" | "tabs", string>>`: Extra classes for the header wrapper, the grid, the main column, the side panel and the phone tab bar (e.g. a negative margin so the glass bars reach the page edge).
- `className?: string`: Classes for the root, which also takes the rest of the div props. Nested DetailLayouts are not supported.

Parts:
- `DetailSection` (component): The section card (a <section aria-labelledby> with an <h2>). title, description, icon (16px, muted), count (a number renders a soft badge), actions (a node, or MenuEntry[] for a ⋯ menu that is an action sheet on phones), onEdit (a pencil), collapsible with open / defaultOpen = true / onOpenChange (the whole header row toggles, content stays mounted and find-in-page opens it), variant "surface" | "outline" | "plain" (default: the layout's sectionVariant), padding "none" | "sm" | "md" = "md" (none for tables that bleed to the edges), loading, skeleton, empty, emptyState, footer (a "View all (12)" row), headingLevel 2 | 3 | 4 = 2, labels { edit, expand, collapse, actions, empty, emptyDescription ("" hides the line) }, classNames (header, icon, title, count, description, actions, edit, toggle, body, empty, footer). Reads useDefaults("detail-section"). Props: DetailSectionProps.
- `DetailAside` (component): The side column as an <aside aria-label>; pass it as aside when the panel needs its own props. Inside a DetailLayout it follows the layout's position, stickiness and phone tab. Props: ComponentProps<"aside">.
- `DEFAULT_DETAIL_LAYOUT_LABELS` (constant): The English layout strings, to spread under a translation. Type: DetailLayoutLabels.
- `DEFAULT_DETAIL_SECTION_LABELS` (constant): The English section strings: edit "Edit", expand "Expand", collapse "Collapse", actions "More actions", empty "Nothing here yet", emptyDescription "When there is something to show, it will appear here.". Type: DetailSectionLabels.

```tsx
import { Activity, FolderOpen, Info, Pencil, Receipt, Trash2 } from "lucide-react"
import { DetailLayout, DetailSection } from "@/components/ui/detail-layout"
import { EntityHeader } from "@/components/ui/entity-header"

export function ClientPage() {
  return (
    <div className="px-4 pb-12 md:px-6">
      <DetailLayout
        header={
          <EntityHeader
            eyebrow="Client · Company"
            title="Tech Solutions Inc."
            avatar={{ name: "Tech Solutions Inc.", radius: "md" }}
            status={{ label: "Active", tone: "success" }}
            facts={[
              { label: "Balance", value: "$12,480" },
              { label: "Tax ID", value: "12-3456789", copyValue: "12-3456789" },
            ]}
          />
        }
        mobileAside="tab"
        labels={{ asideRegion: "Client details" }}
        aside={
          <>
            <DetailSection title="Details" icon={<Info />} onEdit={() => {}}>
              <p className="text-sm">Tax ID 12-3456789 · Chicago · paid in 30 days</p>
            </DetailSection>
            <DetailSection title="Files" icon={<FolderOpen />} count={3} collapsible>
              <p className="text-sm">Contract 2026.pdf</p>
            </DetailSection>
          </>
        }
      >
        <DetailSection
          title="Activity"
          icon={<Activity />}
          count={8}
          actions={[
            { label: "Edit", icon: <Pencil /> },
            { label: "Delete", icon: <Trash2 />, tone: "danger" },
          ]}
        >
          <p className="text-sm">Invoice #2026-0412 issued today, 4:35 PM.</p>
        </DetailSection>
        <DetailSection title="Invoices" icon={<Receipt />} empty labels={{ empty: "No invoices issued" }} />
      </DetailLayout>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/detail-layout (Markdown: https://wingo-ui.com/components/detail-layout.md)

#### Entity Header (`entity-header`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add entity-header`

The top of a record page (a client, a contact, a deal, an invoice): name, status, key facts, actions, favorite, follow and record pager.

Read the record at a glance: type above the name, status badges, and a strip of key facts (Sold, Responsabil, CUI...) that scrolls sideways on a phone with soft edge fades; when it overflows, Tab reaches it and the arrow keys scroll it. Hover or focus a fact to reveal its copy button (always visible on touch). Double click the name (or press F2 on it, or tap the pencil on touch) to rename it: Enter saves, Escape cancels, an empty name is refused and a failed save rolls back with the error under it while the star and badges stay on the name line. Tap the star to favorite the record (on a phone it stays next to the name whenever it fits); Follow turns into Following with a bell that rings once when the change lands. The primary action stays in view and the rest fold into ⋯ as the header narrows, a bottom action sheet on phones, with the follow toggle inside. The up / down arrows next to "3 of 12" walk to the previous and next record (J / K in the demo, shown in their tooltips; keys never fire while typing), and at the first or last record the arrow is disabled; a phone shows only the arrows. Scroll past the header and a glass bar with the name and the primary action slides down under the top bar. In grid and tiles layouts a phone shows the first maxFacts facts and a Show all (n) button that opens the rest.

npm: motion, lucide-react
Wingo UI dependencies: badge, breadcrumb, button, copy-button, favorite-button, inline-edit, page-header, skeleton, tooltip, use-controllable-state, use-locale, use-media-query, use-scroll-edges, use-shortcut, motion, navigation, number-format, tones, ui-config

Props:
- `title: string` = "Tech Solutions Inc.": The record name, rendered as the page's one <h1> (and in the condensed bar).
- `onTitleChange?: (title: string) => (void | Promise<unknown>)`: Makes the title editable through InlineEdit: a double click or F2 (a pencil button on touch). Called with the trimmed name, which shows optimistically; a rejection restores it and shows the error's message (else labels.renameError) under it. An empty name is refused with labels.titleRequired.
- `eyebrow?: ReactNode` = "": The record type in small caps on its own row above the name, like "Client · Company". It stays outside the h1 (read right after the name), so the heading is the name alone.
- `description?: ReactNode` = "": One line under the title (page-header's description).
- `avatar?: PageHeaderAvatar`: A photo or initials before the title: { src?, name, radius? }. Companies use radius "md" (a rounded square), people "full".
- `icon?: ReactNode`: A tinted icon tile before the title when there is no avatar (a deal, an invoice).
- `status?: EntityStatus | EntityStatus[]`: One or several status badges after the title, each { label, tone?, icon? }: a soft badge with a dot (or the icon) in its tone, so color is never the only signal.
- `facts?: EntityFact[]`: Key facts under the title, each { id?, label, value, icon?, href?, copyValue?, hint? }. href turns the value into a link, copyValue adds a copy button (the value may be any node, copyValue is the text copied), hint is a quiet line under it. None: no strip.
- `factsLayout?: "strip" | "grid" | "tiles"` = "strip": strip: one row with hairline dividers that scrolls sideways (with edge fades) when it does not fit. grid: 2, 3 or up to 6 columns by the header's width. tiles: the grid in flat gray tiles.
- `maxFacts?: number` = 0: Grid and tiles on phones: show this many facts, then a Show all (n) button that reveals the rest. 0 shows all.
- `actions?: PageHeaderAction[]`: page-header's actions: the primary (primary: true, else the last solid one) stays visible, the rest fold into ⋯ from the end as the header narrows; a bottom action sheet on phones. A returned promise keeps the button loading.
- `favorite?: boolean`: Controlled star state. Setting it also shows the star.
- `defaultFavorite?: boolean` = false: The star's starting state while uncontrolled.
- `onFavoriteChange?: (favorite: boolean) => (void | Promise<unknown>)`: A returned promise keeps the star's optimistic state while pending; a rejection rolls it back, shakes and announces labels.favoriteError.
- `showFavorite?: boolean` = true: The star after the title (a FavoriteButton with a Star in the tone).
- `following?: boolean`: Controlled follow state. Setting it also shows the toggle.
- `defaultFollowing?: boolean` = false: The follow toggle's starting state while uncontrolled.
- `onFollowingChange?: (following: boolean) => (void | Promise<unknown>)`: Called with the next state. The toggle flips at once; a returned promise keeps the button loading, and a rejection flips it back and announces labels.followError.
- `showFollow?: boolean` = false: A Follow / Following toggle (Bell / BellRing, aria-pressed) that leads the secondary actions. It folds into ⋯ like them (last, since actions fold from the end) and its bell rings once when turned on.
- `pager?: EntityPager`: Previous / next record: { index (0-based), total, onPrevious?, onNext?, previousHref?, nextHref?, label? } renders "3 of 48" and two arrow buttons at the end of the breadcrumb row. Hidden when total is 0 or 1; the arrow at either end is disabled. On phones only the arrows show.
- `previousShortcut?: string` = "": A key for the previous record in mod+k notation ("k" in the demo), shown in the arrow's tooltip and ignored while typing. Empty binds nothing.
- `nextShortcut?: string` = "": A key for the next record ("j" in the demo).
- `breadcrumb?: BreadcrumbEntry[] | ReactNode`: page-header's trail above the title; the pager sits at the end of its row.
- `backHref?: string` = "": A back button before the title (a ‹ link on phones, where it replaces the breadcrumb; the pager stays).
- `onBack?: () => void`: Runs when the back button is pressed (renders it without backHref).
- `tabs?: ReactNode`: NavTabs (or a Tabs list) on the header's bottom border.
- `meta?: PageHeaderMeta[] | ReactNode`: page-header's small wrapping meta row under the description; facts are the richer choice for records.
- `children?: ReactNode`: Extra content after the facts, before the tabs (a progress bar, a notice).
- `sticky?: "none" | "condensed"` = "condensed": condensed: once the header scrolls away a glass bar with the avatar, the name and the primary action pins under the top bar.
- `maxActions?: number` = 0: The most buttons in the wide row, the primary included (1: only the primary, the rest and the follow toggle in ⋯). 0: as many as fit.
- `mobileActions?: "menu" | "stack"` = "menu": The compact layout (header under 512px): secondary actions and the follow toggle in the ⋯ action sheet, or stacked full width.
- `border?: boolean` = true: The hairline under the header.
- `size?: "sm" | "md" | "lg"` = "md": page-header's sizes (18 / 24 / 32px titles, 18 / 22 / 26px on phones) with fact values at 13 / 14 / 15px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The avatar initials or icon tile color, and the star's on color. neutral keeps the name-based avatar color and a black / white star.
- `color?: string` = "": Any CSS color for the avatar / icon tile and the star; replaces the tone.
- `loading?: boolean` = false: page-header's skeletons plus skeleton facts in the same layout (4 while facts is still an empty array).
- `locale?: string` = "": Formats the pager count and the Show all count ("1,234 of 5,000" in en-US). Empty follows the UIProvider, then the browser.
- `labels?: Partial<EntityHeaderLabels>`: Every string: favorite, addFavorite, removeFavorite, favoriteError, follow, following, followError, previous, next, pager(position, total), showAllFacts(count, formatted), showFewerFacts, copy, copied, copyError, rename, renameError, titleRequired, facts, back, more, cancel. The error strings are announced when a change rolls back. English defaults in DEFAULT_ENTITY_HEADER_LABELS.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for the condensed bar. Default: the nearest ScrollContainerProvider, else the nearest scrolling parent, else the window.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the trail, the actions, fact links and pager hrefs. Default: the LinkProvider's.
- `classNames?: Partial<Record<"facts" | "fact" | "pager" | "title" | "eyebrow" | "badges", string>>`: Extra classes for the facts block, each fact, the pager, the title, the eyebrow and the status badges group.
- `pageHeaderClassNames?: Partial<Record<PageHeaderSlot, string>>`: Passed to page-header's classNames (row, heading, actions, tabs, condensed...). Its badges span is display: contents here (the eyebrow, star and badges lay out in the heading row), so style the badges through classNames.badges.
- `className?: string`: Classes for the header box, which also takes id and style. The data-slot="entity-header" wrapper is display: contents, so the condensed bar stays a child of the scrolling page and can stick; the other rest props (aria-*, data-*, handlers) go on it.

Parts:
- `EntityFacts` (component): The facts block alone, for a card or a side panel: facts, layout, maxFacts, size, loading, skeletonCount, locale, labels, linkComponent, classNames (list, fact, label, value, hint, more). Props: EntityFactsProps.
- `DEFAULT_ENTITY_HEADER_LABELS` (constant): The English strings, to spread under a translation. Type: EntityHeaderLabels.

```tsx
import { Mail, Plus, Trash2 } from "lucide-react"
import { EntityHeader, type EntityFact } from "@/components/ui/entity-header"
import { NavTabs } from "@/components/ui/nav-tabs"

const facts: EntityFact[] = [
  { label: "Balance", value: "$12,480" },
  { label: "Owner", value: "Emma Carter" },
  { label: "Tax ID", value: "12-3456789", copyValue: "12-3456789" },
  { label: "City", value: "Chicago" },
  { label: "Client since", value: "Mar 12, 2024" },
]

export function ClientHeader({ index, onMove, onRename }: { index: number; onMove: (index: number) => void; onRename: (name: string) => Promise<void> }) {
  return (
    <EntityHeader
      breadcrumb={[{ label: "Clients", href: "/clients" }, { label: "Tech Solutions Inc." }]}
      eyebrow="Client · Company"
      title="Tech Solutions Inc."
      onTitleChange={onRename}
      avatar={{ name: "Tech Solutions Inc.", radius: "md" }}
      status={[{ label: "Active", tone: "success" }, { label: "VIP", tone: "brand" }]}
      facts={facts}
      actions={[
        { label: "Send email", icon: <Mail /> },
        { label: "Delete", icon: <Trash2 />, tone: "danger" },
        { label: "New invoice", icon: <Plus />, primary: true, href: "/invoices/new" },
      ]}
      showFollow
      pager={{ index, total: 12, onPrevious: () => onMove(index - 1), onNext: () => onMove(index + 1) }}
      previousShortcut="k"
      nextShortcut="j"
      locale="en-US"
      labels={{ follow: "Watch", following: "Watching" }}
      tabs={<NavTabs items={[{ label: "Overview", href: "/clients/tech-solutions" }, { label: "Invoices", href: "/clients/tech-solutions/invoices", badge: 12 }]} />}
    />
  )
}
```

Docs: https://wingo-ui.com/components/entity-header (Markdown: https://wingo-ui.com/components/entity-header.md)

#### Page Header (`page-header`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add page-header`

The top of an admin page: breadcrumb, title with avatar and badges, description, meta, actions that fold into a menu, and tabs.

Read where you are in the breadcrumb, then act: the primary action always stays in view at the end of the row, and the others fold one by one into a ⋯ menu as the window narrows (they come back when there is room). Actions that return a promise show a spinner until they finish. Tab walks the breadcrumb, the back button, every action and the ⋯ menu (arrow keys and Enter inside it, Escape closes it). With sticky set to condensed, scroll past the header and a glass bar with the title and the primary action slides down under the top bar. On a phone (or whenever the header itself is narrower than 512px, like in a side panel) the actions move under the title: the primary stays as a small button and the rest open from ⋯, as a bottom action sheet on phones (or stack full width with mobileActions set to stack); on phones the title shrinks and a ‹ back link replaces the breadcrumb.

npm: motion, lucide-react
Wingo UI dependencies: avatar, breadcrumb, button, dropdown-menu, skeleton, use-media-query, use-overflow-items, use-scroll-state, motion, navigation, tones, ui-config

Props:
- `title?: ReactNode` = "": The page title, rendered as the page's one <h1>.
- `description?: ReactNode` = "": One or two lines under the title, capped at a readable width.
- `breadcrumb?: BreadcrumbEntry[] | ReactNode`: Entries render a Breadcrumb (it folds the middle when long and becomes a ‹ Parent link on phones). A node renders as is.
- `backHref?: string` = "": Adds a back button before the title (through NavLink). Below 640px it replaces the breadcrumb as a ‹ text link.
- `onBack?: () => void`: Runs when the back button is pressed; without backHref the back button is a plain button.
- `backLabel?: string` = "Back": The back button's accessible name, and its visible text on phones ("Invoices" reads ‹ Invoices).
- `icon?: ReactNode`: An icon in a tinted tile before the title (40px, 48px at lg), colored by tone or color.
- `avatar?: { src?: string; name: string; radius?: AvatarRadius }`: A photo or initials before the title, wins over icon. radius md (default) for companies, full for people.
- `badges?: ReactNode`: Status badges after the title; they wrap under it when space runs out.
- `meta?: PageHeaderMeta[] | ReactNode`: Small facts in a wrapping row under the description: { id?, icon?, label }[], with 14px icons. A node renders as is.
- `actions?: PageHeaderAction[] | ReactNode`: { id?, label, icon?, onSelect?, href?, variant?, tone?, primary?, disabled? }[]. The primary one (or the last solid) stays visible, last in the row; the others are outline buttons that fold into ⋯ from the end while they do not fit, and always in the compact layout (header narrower than 512px: phones, side panels). onSelect returning a promise shows the button loading. A node renders as is, without folding.
- `tabs?: ReactNode`: NavTabs (or a Tabs list) sitting on the header's bottom border.
- `children?: ReactNode`: Extra content between the title row and the tabs, such as filters or a progress bar.
- `size?: "sm" | "md" | "lg"` = "md": Title 18 / 24 / 32px (18 / 22 / 26px on phones), with the icon tile and avatar scaled to match.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The media's color: the icon tile's soft tint, or the avatar's initials when there is no photo (neutral keeps the name-based color).
- `color?: string` = "": Any CSS color for the icon tile or the avatar initials; replaces the tone. Leave empty to use the tone.
- `border?: boolean` = true: The hairline under the header; tabs sit on it.
- `loading?: boolean` = false: Skeletons in the shape of the title, description, meta and actions; the breadcrumb and tabs stay.
- `maxActions?: number` = 0: The most buttons in the wide row, the primary included (1: only the primary, everything else in ⋯). The rest always open from the ⋯ menu, whatever fits. 0: as many as fit.
- `mobileActions?: "menu" | "stack"` = "menu": The compact layout (the header narrower than 512px, so every phone): the primary stays as a small button and the rest open from ⋯ (a bottom action sheet on phones), or every action stacks full width (48px, primary on top).
- `sticky?: "none" | "condensed"` = "none": condensed: once the header scrolls under the top bar, a 48px glass bar with the title and the primary action slides down and pins at top: var(--topbar-offset, 0px).
- `moreLabel?: string` = "More actions": The ⋯ button's accessible name and the phone action sheet's hidden title.
- `cancelLabel?: string` = "Cancel": The cancel row at the bottom of the phone action sheet.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for the condensed bar. Default: the nearest ScrollContainerProvider, else the window.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for link actions, the back link and the breadcrumb. Default: the LinkProvider's.
- `classNames?: Partial<Record<PageHeaderSlot, string>>`: Classes for the parts: breadcrumb, row, back, media, heading, title, badges, description, meta, metaItem, actions, more, tabs, condensed, condensedTitle, condensedAction.

```tsx
import { Pencil, Plus, Trash2 } from "lucide-react"
import { Badge } from "@/components/ui/badge"
import { NavTabs } from "@/components/ui/nav-tabs"
import { PageHeader } from "@/components/ui/page-header"

export function ClientHeader() {
  return (
    <PageHeader
      breadcrumb={[
        { label: "Home", href: "/" },
        { label: "Clients", href: "/clients" },
        { label: "Tech Solutions LLC" },
      ]}
      avatar={{ name: "Tech Solutions LLC" }}
      title="Tech Solutions LLC"
      badges={<Badge tone="success" dot>Active</Badge>}
      description="IT equipment distributor in Austin · EIN 12-3456789"
      meta={[{ label: "Client since Mar 12, 2024" }, { label: "Balance $12,480.00" }]}
      actions={[
        { label: "Edit", icon: <Pencil /> },
        { label: "Delete", icon: <Trash2 />, tone: "danger" },
        { label: "New invoice", icon: <Plus />, primary: true, href: "/invoices/new" },
      ]}
      tabs={
        <NavTabs
          items={[
            { label: "Overview", href: "/clients/tech-solutions" },
            { label: "Invoices", href: "/clients/tech-solutions/invoices", badge: 12 },
          ]}
        />
      }
      sticky="condensed"
    />
  )
}
```

Docs: https://wingo-ui.com/components/page-header (Markdown: https://wingo-ui.com/components/page-header.md)

#### Scroll Area (`scroll-area`)

component · Pro · v1.0.2 · install: `npx wingo-ui@latest add scroll-area`

A scroll container with slim custom scrollbars, edge fades that ease out at the ends, snap scrolling and prev / next buttons for rails.

Scroll with a wheel, a trackpad or a finger: momentum stays native, the content fades out toward every edge that has more to see, and each fade melts away as you reach the end. With a mouse the slim bars appear on hover and the thumb can be dragged or the track clicked to jump. On a phone the bars show while you scroll and are only indicators, like on iOS and Android, so a swipe near the edge always moves the content. Tab to the area to scroll it with the arrows, Page Up / Down, Home / End and Space; a focus ring and the bars show while it has focus, and a focused rail takes Home, End, Page keys and Space sideways too. Rails can snap card by card and, with a mouse, show round prev / next buttons on the sides with more content; they fade out at the ends, and one that hides under keyboard focus hands focus to the rail.

npm: @radix-ui/react-scroll-area, lucide-react
Wingo UI dependencies: button, use-media-query, use-scroll-edges, motion, ui-config

Props:
- `orientation?: "vertical" | "horizontal" | "both"` = "vertical": Which scrollbars render and which edges fade. horizontal turns the area into a rail (the demo swaps the chat for listing cards), both scrolls a wide table either way.
- `type?: "hover" | "scroll" | "auto" | "always"` = "hover": When the bars show: while the pointer is over the area, while it scrolls, whenever the content overflows, or always. On touch screens "hover" behaves like "scroll", since a finger never hovers. Content that fits shows no bars in any mode.
- `scrollHideDelay?: number` = 600: Milliseconds before the bars fade out after the pointer leaves ("hover") or scrolling stops ("scroll").
- `fade?: boolean` = true: Fades the content out toward every edge with more to scroll. It is a mask, not an overlay, so it works on any surface in both themes and never covers the bars.
- `fadeSize?: number` = 24: The largest fade in px. Each fade grows with the distance to its edge, so it eases out as you reach the end instead of popping.
- `scrollbarSize?: "sm" | "md"` = "md": Bar thickness, 8 or 10px. The thumb fills it inside a 2px inset (4 or 6px). On touch screens the bars are indicators only, so a swipe that lands on the thumb still scrolls the content.
- `snap?: "none" | "mandatory" | "proximity"` = "none": CSS scroll snap along the orientation. mandatory always rests on an item (card rails), proximity only near one (chips, long lists). The children set snap-start or snap-center.
- `controls?: boolean` = false: Horizontal and both: floating prev / next buttons on the sides with more content. Mouse and trackpad only (a finger swipes); they fade out at each end and leave the tab order while hidden.
- `scrollStep?: number` = 0.8: Share of the viewport width one control click, or Page Up / Down or Space on a focused rail, scrolls. Smooth, and instant under reduced motion.
- `label?: string` = "": Accessible name of the scrollable region, like "Messages". With a label the viewport is announced as a region. The demo uses a sample while this is empty.
- `focusable?: boolean` = true: Makes the viewport a tab stop while it overflows, so keyboard users can scroll it; the focus ring sits just inside the edge and the bars show while it has focus. Turn it off when the content is itself focusable (a list of links).
- `maxHeight?: number | string` = "": Convenience max height of the viewport: a number (or numeric string) in px, or any CSS length like "50dvh". The area grows with its content up to it. Otherwise size the root with a class (h-72, flex-1 min-h-0). The demo caps the chat with it.
- `viewportRef?: Ref<HTMLDivElement> (a useRef object or an (el) => void callback)`: The scrolling element, for scrollTo, scrollIntoView or measuring. The demo uses it to start the chat at the latest message.
- `controlLabels?: { previous?: string; next?: string }` = "{ previous: \"Scroll back\", next: \"Scroll forward\" }": aria-labels of the prev / next buttons.
- `onEdgesChange?: (edges: { top: boolean; bottom: boolean; left: boolean; right: boolean }) => void`: Which edges have more content, called when one flips (never per scroll frame). Handy for a header hairline that appears once the list scrolls under it.
- `classNames?: Partial<Record<"viewport" | "scrollbar" | "thumb" | "controls", string>>`: Extra classes for the inner parts. viewport takes scroll padding (scroll-px-4) for rails, thumb a custom color (bg-brand/50), controls a different vertical position.
- `className?: string`: Extra classes for the root, merged last: its size (h-72, flex-1 min-h-0) and radius, which the viewport inherits. Other props (style, aria-*, dir) go to the Radix root too; dir="rtl" puts the vertical bar on the left and mirrors the fades, the controls and the Home / End keys of a rail.
- `children?: ReactNode`: The content. Rails lay their items out in a w-max flex row of snap-start items. The file also exports ScrollBar (orientation, size "sm" | "md", classNames.thumb), the same bar as a part for compositions on the Radix root.

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

const listings = [
  { id: "1", title: "Cube Aim bike", city: "Brooklyn", price: "$450" },
  { id: "2", title: "iPhone 13, 128 GB", city: "Boston", price: "$460" },
  { id: "3", title: "Sofa bed", city: "Portland", price: "$280" },
]

export function Notifications({ items }: { items: { id: string; title: string; time: string }[] }) {
  return (
    <ScrollArea label="Notifications" maxHeight={320} className="rounded-2xl bg-surface shadow-raised">
      <ul className="divide-y divide-foreground/10">
        {items.map((item) => (
          <li key={item.id} className="flex min-h-14 flex-col justify-center px-4 py-2.5">
            <span className="text-[15px] font-medium">{item.title}</span>
            <span className="text-[13px] text-muted-foreground">{item.time}</span>
          </li>
        ))}
      </ul>
    </ScrollArea>
  )
}

export function Recommended() {
  return (
    <ScrollArea
      orientation="horizontal"
      snap="mandatory"
      controls
      label="Recommended"
      classNames={{ viewport: "scroll-px-4" }}
    >
      <div className="flex w-max gap-3 px-4 pb-3">
        {listings.map((listing) => (
          <article key={listing.id} className="w-56 shrink-0 snap-start rounded-2xl bg-surface p-4 shadow-raised">
            <h3 className="truncate text-sm font-medium">{listing.title}</h3>
            <p className="text-xs text-muted-foreground">{listing.city}</p>
            <p className="mt-2 text-[15px] font-semibold tabular-nums">{listing.price}</p>
          </article>
        ))}
      </div>
    </ScrollArea>
  )
}
```

Docs: https://wingo-ui.com/components/scroll-area (Markdown: https://wingo-ui.com/components/scroll-area.md)

#### Separator (`separator`)

component · free · v1.0.0 · install: `npx wingo-ui@latest add separator`

A thin divider between groups of content, horizontal or vertical, solid, dashed or dotted, with an optional label or icon in the line.

It is a quiet line, nothing to press. Give it a label and the text or icon sits in the line, centered or near one end, as plain text or a small pill. Vertical separators stretch to the height of the row they sit in, or take the height you give them with a className. Screen readers skip a decorative line and read its label as plain text; with decorative off it is announced as a separator named by its label. The demo around it is a real sign-in card: the buttons load, the email field validates, Enter sends. In the toolbar example the arrow keys, Home and End move between the buttons.

npm: @radix-ui/react-separator
Wingo UI dependencies: tones, ui-config

Props:
- `label?: ReactNode` = "": Text or an icon in the line, like "or", a date or a <Star />. An empty string or no label draws the plain line. The playground falls back to "or".
- `variant?: "solid" | "dashed" | "dotted"` = "solid": Line style. Dashed and dotted are drawn with a border so the pattern stays crisp; in neutral they are a step darker so they read as strong as the solid hairline.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": neutral is the hairline (10% of the text color, so it works on every surface in both themes). Any other tone colors the line with its border color and the label with its text color.
- `color?: string` = "": Any CSS color. Replaces the tone: the line is the color at 45%, the label mixes it toward the text color for contrast. Leave empty to use the tone.
- `thickness?: 1 | 2` = 1: Line thickness in px. 2 suits section breaks and dashed dividers; solid 2px lines get rounded ends.
- `labelVariant?: "plain" | "soft" | "outline"` = "plain": How the label sits in the line: plain text, a soft tinted pill (chat date dividers, "3 new messages") or an outlined pill in the line color.
- `fade?: boolean` = false: Fades the line out toward its ends. With a label, each long side fades toward its outer end (mirrored in right-to-left layouts); the 16px stub of a start or end label stays solid.
- `orientation?: "horizontal" | "vertical"` = "horizontal": Vertical stretches to the height of the flex row it sits in and falls back to 16px in a parent that is not flex, so it never disappears. A height in className (h-3.5 self-center) wins. A vertical label stacks between two line segments and wraps at 96px, so a long one never squeezes the columns beside it.
- `labelPosition?: "start" | "center" | "end"` = "center": Where the label sits. start and end keep a 16px stub of line before or after it.
- `spacing?: "none" | "sm" | "md" | "lg"` = "none": Margin on both sides along the axis: 0, 8, 16 or 24px (above and below a horizontal line, left and right of a vertical one).
- `inset?: number` = 0: Pixels of empty space before the line (after it in right-to-left layouts), taken off its width so it never overflows. For list rows whose divider starts after the icon, like iOS settings.
- `decorative?: boolean` = true: On by default: the line is hidden from assistive tech (role="none"). Turn it off between real sections for role="separator" with aria-orientation; a text label becomes its accessible name.
- `classNames?: Partial<Record<"line" | "label", string>>`: Extra classes for the inner parts: each line segment (the root itself when there is no label) and the label.
- `className?: string`: Extra classes for the root, merged last. A short vertical rule in a text row: className="h-3.5 self-center". Any line color: className="[--separator-color:red]".

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

export function MetaRow() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-3 text-sm text-muted-foreground">
        <span>Brooklyn</span>
        <Separator orientation="vertical" className="h-3.5 self-center" />
        <span>today, 2:20 PM</span>
        <Separator orientation="vertical" className="h-3.5 self-center" />
        <span>$1,200</span>
      </div>
      <Separator label="or" />
      <Separator tone="danger" variant="dashed" label="Danger zone" labelPosition="start" />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/separator (Markdown: https://wingo-ui.com/components/separator.md)

#### Settings Layout (`settings-layout`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add settings-layout`

A settings area like macOS and iOS: a section nav, grouped label and control rows, and a save bar that slides up when something changes.

Pick a section in the sidebar (Up / Down move between items, Home / End jump, Enter opens; disabled items are skipped) and its page fades in at the top while the indicator glides over. Change anything and a dark bar slides up from the bottom: "You have unsaved changes · Discard · Save". Save with the button or mod+s (Cmd+S / Ctrl+S, bound only while there is something to save, even inside a text field): the button spins, then the bar says "Changes saved" for a moment and slides away; a failed save keeps the bar, shakes it and shows the error. Escape inside the bar does nothing, so discarding is always a deliberate click. Switching sections with unsaved changes asks first (Discard / Keep editing; in the tabs, arrow keys then only move focus and Enter or Space switches), and closing the tab warns too. In scroll mode every section sits on one page, the nav follows your scroll and a click glides to the section, below the sticky tabs when there are tabs. Below 768px (the layout's own width) the nav becomes an iOS grouped list: tap a row to push its page, then tap the back button, press Escape or swipe the page to the right to go back; or sticky scrolling pill tabs, or a select whose bottom sheet shows the same groups. On a phone the bar pins above the tab bar and the safe area, lifts over the on-screen keyboard and never covers the last row. Rows bind their label to the control, so tapping "Daily digest" flips its switch.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, badge, button, kbd, select, spinner, split-view, tabs, use-controllable-state, use-keyboard-inset, use-scroll-state, use-shortcut, navigation, motion, tones, ui-config

Props:
- `sections: SettingsNavItem[]`: The sections: { id, label, icon?, description? (the phone list subtitle), group? (eyebrow label), badge? (a number is a count), href? (a route, wins over content), disabled?, danger?, tone? (the phone icon tile), content? }.
- `defaultValue?: string` = "profile": The section open at first, uncontrolled. Pair value / onValueChange to drive it from the URL. The code default is the first enabled section; an unknown id falls back to it too.
- `value?: string`: The active section id, controlled.
- `onValueChange?: (id: string) => void`: Every switch: a nav click (after the leave confirm), a phone row, the tabs or select, and the scroll spy.
- `title?: ReactNode` = "": The page heading (an h1). On phones it becomes the large title of the grouped list.
- `description?: ReactNode` = "": A line under the title.
- `children?: ReactNode | ((activeId: string) => ReactNode)`: The content when sections[].content is not used: a function gets the active id (in scroll mode, each id in turn). Sections with an href always render children.
- `mode?: "pages" | "scroll"` = "pages": pages: only the active section shows and swaps with a fade. scroll: every section stacked on one page, the nav follows the scroll (an IntersectionObserver spy on the page's scroll container) and a click scrolls there.
- `nav?: "sidebar" | "tabs" | "none"` = "sidebar": Desktop navigation: a sticky left column, underline tabs above the content, or none. One section never shows a nav.
- `navWidth?: number` = 240: The sidebar column in px.
- `mobileNav?: "list" | "tabs" | "select"` = "list": Below 768px of its own width: an iOS grouped list that pushes the section (split-view stack with swipe back), scrolling pill tabs, or a select (a bottom sheet). Scroll mode uses tabs for list.
- `dirty?: boolean` = false: Something changed: shows the save bar, binds saveShortcut and arms the leave guards. The demo also turns it on as soon as you edit a field.
- `saving?: boolean` = false: The save button's loading state, for a save you track yourself. It also loads while an onSave promise runs; turning false with dirty off flashes the saved message.
- `onSave?: (() => void | Promise<unknown>)`: Runs from the button or the shortcut. A promise keeps the button loading; resolved flashes labels.saved for 1.2s, rejected keeps the bar, shakes it and shows the error's message (else labels.saveError).
- `onDiscard?: () => void`: The Discard button, and a confirmed leave. Put the saved values back here.
- `saveShortcut?: string` = "mod+s": Saves while dirty (it replaces the browser's Save Page only then). Shown as a key hint on the button, hidden on touch. "" disables.
- `confirmLeave?: boolean` = true: Pages mode: switching sections while dirty asks "Discard changes?" (Discard / Keep editing) and calls onDiscard when confirmed. Links (href items) are the router's to guard.
- `warnBeforeUnload?: boolean` = true: The browser's leave-page warning while dirty.
- `saveBarPosition?: "sticky" | "fixed"` = "sticky": sticky: floats at the bottom of the content column while you scroll; fixed: pinned to the viewport. Phones always pin it above --bottom-bar-offset and the safe area, lifted over the keyboard.
- `size?: "sm" | "md"` = "md": Nav rows 32 / 36px (44px on touch) and the row padding (48 / 56px rows).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The nav indicator (a soft tint of the tone) and the save button. Neutral is a gray pill and an inverted button.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders nav items that have an href (settings as routes). Defaults to the LinkProvider's, else a plain <a>.
- `labels?: Partial<SettingsLayoutLabels>`: Every string: nav "Settings", unsaved "You have unsaved changes", save "Save", saving "Saving…", discard "Discard", saved "Changes saved", saveError "Could not save. Try again.", leaveTitle "Discard changes?", leaveDescription "Your changes in this section will be lost.", leaveConfirm "Discard", leaveCancel "Keep editing", back "Settings", select "Section". Exported as DEFAULT_SETTINGS_LAYOUT_LABELS.
- `classNames?: Partial<Record<"frame" | "header" | "title" | "description" | "nav" | "group" | "item" | "indicator" | "content" | "mobileNav" | "mobileList" | "mobileItem" | "mobileDetail" | "saveBar", string>>`: Extra classes for the parts. The phone stack's height is the --settings-mobile-height variable (default 100dvh minus --topbar-offset).

Parts:
- `SettingsSection` (component): A group of rows: <section aria-labelledby> with an h2 (headingLevel), description, actions and a footer. variant "grouped" (an iOS inset group, the default) or "plain" (hairlines on the page); danger adds a red ring and title. Reads useDefaults("settings-section"). Props: SettingsSectionProps.
- `SettingsRow` (component): One setting: label, description, badge ("Pro"), error and the control on the right. A single child control (an input, switch, select or any component) gets the label's htmlFor, aria-labelledby (so a segmented control or radio group is named too) and aria-describedby automatically; buttons and links keep their own name inside a group named by the label, and a <div> wrapper keeps a plain label (wire it with htmlFor or useSettingsRow). layout "auto" | "inline" | "stacked", controlWidth "auto" | "sm" (200px) | "md" (320px) | "full", align, danger, disabled. Rows go inline once their section is 560px wide. Reads useDefaults("settings-row"). Props: SettingsRowProps.
- `SettingsSaveBar` (component): The floating save bar on its own, for any form: dirty, saving, onSave, onDiscard, saveShortcut, position (sticky | fixed), message, tone, labels, classNames. Props: SettingsSaveBarProps.
- `useSettingsLayout` (hook): Inside the layout: the active section and a stable setter that goes through the unsaved-changes guard (a link row that jumps to another section). Signature: () => { activeId: string; setActiveId: (id: string) => void; dirty: boolean }.
- `useSettingsRow` (hook): Inside a row: the ids to wire a custom control by hand (a radio group takes aria-labelledby={labelId}). Signature: () => { controlId: string; labelId: string; describedBy: string | undefined } | null.
- `DEFAULT_SETTINGS_LAYOUT_LABELS` (constant): The English strings, to spread under a translation. Type: SettingsLayoutLabels.

```tsx
import { Bell, User } from "lucide-react"
import { useState } from "react"
import { Input } from "@/components/ui/input"
import { SettingsLayout, SettingsRow, SettingsSection } from "@/components/ui/settings-layout"
import { Switch } from "@/components/ui/switch"

export function AccountSettings() {
  const [saved, setSaved] = useState({ name: "Emma Carter", digest: true })
  const [draft, setDraft] = useState(saved)
  const dirty = draft.name !== saved.name || draft.digest !== saved.digest

  return (
    <SettingsLayout
      title="Settings"
      dirty={dirty}
      onSave={async () => {
        await fetch("/api/settings", { method: "PUT", body: JSON.stringify(draft) })
        setSaved(draft)
      }}
      onDiscard={() => setDraft(saved)}
      labels={{ unsaved: "You have unsaved changes", save: "Save changes" }}
      sections={[
        {
          id: "profile",
          label: "Profile",
          icon: <User />,
          content: (
            <SettingsSection title="Public profile">
              <SettingsRow label="Name" controlWidth="md">
                <Input value={draft.name} onValueChange={(name) => setDraft({ ...draft, name })} autoComplete="name" />
              </SettingsRow>
            </SettingsSection>
          ),
        },
        {
          id: "notifications",
          label: "Notifications",
          icon: <Bell />,
          content: (
            <SettingsSection title="Email">
              <SettingsRow label="Daily digest" description="Sales and overdue invoices, at 8 AM.">
                <Switch checked={draft.digest} onCheckedChange={(digest) => setDraft({ ...draft, digest })} />
              </SettingsRow>
            </SettingsSection>
          ),
        },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/settings-layout (Markdown: https://wingo-ui.com/components/settings-layout.md)

#### Split View (`split-view`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add split-view`

A list and its detail side by side on wide screens and a push / pop stack with swipe back on phones, as in CRMs and mail apps.

On a wide screen pick a row and its detail fades in beside the list; both panes scroll on their own. Drag the hairline between them to resize the list (it follows the pointer and remembers the width with persistKey), double-click it to reset; focus it with Tab and use Left / Right to move it by 16px, Home / End for the limits and Enter to reset. Below the breakpoint the list fills the screen and a picked row pushes its detail in from the side while the list slides back under a dim; go back with the glass back bar, Escape, or by dragging the detail toward the edge with a finger (it follows the finger and completes past a quarter of the width or on a flick). Focus moves into the detail on push and back to the row on pop.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, button, use-persisted-state, use-scroll-state, motion

Props:
- `list: ReactNode`: The master pane: a list of clients, conversations or tickets. It scrolls on its own and keeps its scroll position while the detail is pushed over it.
- `detail?: ReactNode`: The detail pane's content. Give the element a key (the item id): a new key fades the content in and scrolls the pane back to the top, with no push.
- `showDetail?: boolean`: Whether the detail is open (on phones: pushed). Defaults to Boolean(detail). True without a detail shows the empty state.
- `onBack?: () => void`: Phones: called by the back button, a completed swipe and Escape. Clear the selection here (and call router.back() when the detail is a route).
- `defaultListWidth?: number` = 360: Starting width of the list column in px (also what a double-click or Enter on the divider resets to).
- `listWidth?: number`: Controlled width of the list column in px. Pair it with onListWidthChange.
- `onListWidthChange?: (width: number) => void`: Fires once when a resize ends (pointer up, a key press, a reset), never per frame.
- `minListWidth?: number` = 260: The narrowest the list can get, in px.
- `maxListWidth?: number` = 560: The widest the list can get, in px. A drag also leaves the detail at least minListWidth wide.
- `resizable?: boolean` = true: Drag the divider to resize; arrow keys, Home / End and Enter on the focused divider; double-click resets. Off, the divider is a plain hairline.
- `persistKey?: string` = "": A storage key that remembers the list width across reloads (local storage). Empty keeps it in memory.
- `breakpoint?: "md" | "lg"` = "md": Below this width of the split view itself the panes stack: md (768px) or lg (1024px, tablets and narrow app-shell columns stack too). It is a CSS container query, so the server render is right and it also stacks inside a phone frame.
- `emptyText?: ReactNode` = "Select an item to see it here": The placeholder text in the detail pane while nothing is selected (wide screens).
- `emptyIcon?: ReactNode`: The placeholder icon. Defaults to MousePointerClick in a soft tile.
- `emptyDetail?: ReactNode`: Replaces the whole placeholder, e.g. a summary of the list or a call to action.
- `swipeBack?: boolean` = true: Phones: drag the detail toward the end to go back. It starts anywhere on the pane after an 8px horizontal slop, never inside [data-no-swipe], inputs or horizontal scrollers.
- `showBackButton?: boolean` = true: Phones: a sticky glass back bar at the top of the detail. Turn it off and put SplitViewBackButton (Button props plus label, default "Back"; calls onBack and hides itself while the panes sit side by side) in your own header. useSplitView() inside the split view returns { mode: "split" | "stack", showDetail, back }.
- `backLabel?: ReactNode` = "Back": The back button's text. Use the list's name, like "Clients", as iOS does.
- `resizeLabel?: string` = "Resize list": The accessible name of the divider.
- `bordered?: boolean` = true: The hairline between the panes. Off, the divider is invisible until hovered or dragged.
- `classNames?: Partial<Record<"list" | "detail" | "divider" | "back" | "empty", string>>`: Extra classes for the inner parts: the two scrolling panes, the divider, the phone back bar and the placeholder.
- `className?: string`: Extra classes for the root. It fills its parent's height (h-full), so give the parent a height.

```tsx
import { useState } from "react"
import { SplitView } from "@/components/ui/split-view"

const clients = [
  { id: "tech", name: "Tech Solutions Inc.", city: "New York" },
  { id: "summit", name: "Summit Logistics", city: "Boston" },
  { id: "greenleaf", name: "Greenleaf Pharmacy", city: "Portland" },
]

export function Clients() {
  const [selected, setSelected] = useState<string | null>(null)
  const client = clients.find((c) => c.id === selected)

  return (
    <div className="h-dvh">
      <SplitView
        persistKey="crm:clients:split"
        backLabel="Clients"
        onBack={() => setSelected(null)}
        list={
          <ul className="p-2">
            {clients.map((c) => (
              <li key={c.id}>
                <button type="button" onClick={() => setSelected(c.id)} className="w-full rounded-2xl px-3 py-2.5 text-start">
                  {c.name}
                </button>
              </li>
            ))}
          </ul>
        }
        detail={
          client && (
            <article key={client.id} className="p-6">
              <h2 className="text-lg font-semibold">{client.name}</h2>
              <p className="text-sm text-muted-foreground">{client.city}</p>
            </article>
          )
        }
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/split-view (Markdown: https://wingo-ui.com/components/split-view.md)

#### Toolbar (`toolbar`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add toolbar`

The bar above a list or table: search, filter chips, applied filters, sort, a list / grid switch, the count, actions and a bulk mode.

Type in the search (results update after a short pause, at once on Enter; Escape or × clears it). Tap the filter chips to switch quick filters on and off; when there are more than fit they scroll sideways with snapping and fade at the edges. Applied filters sit on a second row as chips with an ×; Clear filters removes them all. Sort opens a menu of options (arrow keys and Enter, Escape closes); the list / grid switch is a radio group (arrow keys move it). Page actions keep the primary visible and fold the rest into ⋯ as the row narrows. Select rows and the bar turns into a selection bar: the count, the bulk actions (folding into ⋯ when they do not fit) and × to clear, which Escape also does while focus is in the toolbar or the list next to it. On a phone the toolbar takes two rows (search with the primary action and ⋯, then the chips with sort and view as icon buttons), menus open as bottom sheets, every target is 44px, and the selection bar floats as an inverted pill above the tab bar and the home indicator. Sticky toolbars pin under the top bar on glass and show a hairline once stuck.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, dropdown-menu, search-input, segmented-control, toggle, use-locale, use-overflow-items, use-persisted-state, use-scroll-edges, number-format, motion, tones, ui-config

Props:
- `search?: boolean` = true: Shows the search field (a SearchInput): full width on phones, 224 to 288px on wider toolbars.
- `searchPlaceholder?: string` = "Search": The search field's placeholder and accessible name.
- `searchShortcut?: string` = "": A key that focuses the search from anywhere, shown as a hint in the empty field (never on touch). None by default: "/" belongs to the app's global search.
- `searchValue?: string`: The controlled query. Typing stays local; the field follows this value whenever it changes.
- `defaultSearchValue?: string` = "": The starting query while uncontrolled.
- `onSearchChange?: (query: string) => void`: The trimmed query, debounced by searchDebounce; at once on Enter and when the field is cleared.
- `searchDebounce?: number` = 300: Milliseconds of quiet before onSearchChange runs.
- `searchProps?: Partial<SearchInputProps>`: Anything else for the SearchInput: suggestions, recent searches, variant, an aria-label.
- `filters?: ToolbarFilter[]`: Quick toggle chips { id, label, icon?, count?, active?, disabled? }: outline pills with aria-pressed and an optional count. active makes a chip controlled; without it the chip keeps its own state. They scroll sideways with snapping when they do not fit.
- `onFilterToggle?: (id: string, active: boolean) => void`: Runs when a chip is switched on or off.
- `filterTrigger?: ReactNode`: A slot after the chips for a "Filters" button with its own panel (a dropdown, a popover, a filter panel).
- `appliedFilters?: ToolbarAppliedFilter[]`: { id, label }[]: removable chips on a second row. They enter and leave with a spring and the rest slide into place.
- `onRemoveFilter?: (id: string) => void`: Called by an applied chip's × (and Backspace or Delete on it). Without it the chips have no ×.
- `onClearFilters?: () => void`: Shows the Clear filters link after the applied chips.
- `clearLabel?: string` = "Clear filters": The text of the link that removes every applied filter.
- `sort?: ToolbarSort`: { value, options: { value, label }[], onValueChange, label? }: a ghost "Sort: Newest" button opening a radio menu (an icon button on narrow toolbars and phones, where the menu is a bottom sheet).
- `view?: string`: The controlled view (list / grid). A value that is not in views checks no segment.
- `defaultView?: string` = "list": The starting view while uncontrolled.
- `onViewChange?: (view: string) => void`: Runs when the view switch changes.
- `views?: ToolbarView[]`: { value, label, icon }[] for the icon-only segmented switch; labels become tooltips and accessible names. Default list and grid; fewer than two hide the switch.
- `viewPersistKey?: string` = "": Remembers the uncontrolled view in localStorage under this key (use-persisted-state), shared by every toolbar with the same key.
- `resultCount?: number` = 0: "48 results" (through labels.results and the locale) before the actions, announced politely. Shown on toolbars wider than 896px; leave it out to hide the count.
- `actions?: ToolbarAction[] | ReactNode`: { id?, label, icon?, onSelect?, variant?, tone?, primary?, disabled? }[], the page-header shape: the primary (or the last solid) stays visible at the end, the others are outline buttons that fold into ⋯ from the end. On phones the primary is an icon button and the rest open from ⋯ as an action sheet. onSelect returning a promise shows the button loading. A node renders as is.
- `selectedCount?: number` = 0: Above 0 the toolbar becomes the selection bar: "3 selected", the bulk actions and ×.
- `bulkActions?: ToolbarAction[]`: Ghost buttons in the selection bar; they fold into ⋯ when they do not fit, danger keeps its red, and in the floating bar on phones they turn icon-only.
- `onClearSelection?: () => void`: The selection bar's × and Escape (while focus is in the toolbar, the floating bar or the list next to the toolbar).
- `bulkPosition?: "inline" | "floating"` = "inline": inline swaps the toolbar's row for the selection bar; floating shows an inverted pill (bg-primary) pinned to the bottom of the screen, above var(--bottom-bar-offset) and the safe area. Below 768px it always floats.
- `size?: "sm" | "md"` = "md": Controls 32 / 40px (44px on touch); the chips are a step shorter (28 / 32px with a 44px hit area).
- `variant?: "plain" | "surface"` = "plain": plain sits on the page; surface is a raised rounded-2xl panel with 8px padding.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The radius of the search field, the buttons, the view switch and the selection band, per size like the button's.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of pressed filter chips (a soft tint with a tone border).
- `color?: string` = "": Any CSS color for pressed filter chips; replaces the tone. Leave empty to use the tone.
- `sticky?: boolean` = false: Sticks under the top bar (top: var(--topbar-offset, 0px)) on glass, with a hairline that appears once it is stuck.
- `loading?: boolean` = false: The search icon turns into a spinner and the field gets aria-busy.
- `locale?: string` = "": Formats the result count, the selected count and chip counts (1,250 in en-US). Default: the app's locale.
- `labels?: Partial<ToolbarLabels>`: Every string: region ("List controls"), results ((n, formatted) => "48 results"), selected ((n, formatted) => "3 selected"), sort ("Sort"), view ("View"), more ("More actions"), clearSelection ("Clear selection"), filters ("Quick filters"), appliedFilters ("Applied filters"), removeFilter ("Remove filter"), bulkActions ("Selection actions"), cancel ("Cancel", the phone sheets).
- `children?: ReactNode`: Extra controls after the view switch (a density toggle, a columns menu, a select). Below a 48rem toolbar they get their own wrapping row and share its width equally, so they need no fixed widths on phones; from 48rem up they sit inline.
- `classNames?: Partial<Record<ToolbarSlot, string>>`: Classes for the parts: row, search, filters, filter, filterCount, filterTrigger, sort, view, count, actions, more, applied, appliedFilter, clear, bulk, bulkCount, bulkActions, bulkClear, floating, extra (the row holding children).

```tsx
import { useState } from "react"
import { Archive, Download, Plus, Trash2, Upload } from "lucide-react"
import { Toolbar } from "@/components/ui/toolbar"

export function ClientsToolbar() {
  const [query, setQuery] = useState("")
  const [active, setActive] = useState<string[]>(["active"])
  const [sort, setSort] = useState("newest")
  const [view, setView] = useState("list")
  const [selected, setSelected] = useState<string[]>([])

  return (
    <Toolbar
      searchPlaceholder="Search clients"
      searchValue={query}
      onSearchChange={setQuery}
      filters={[
        { id: "active", label: "Active", active: active.includes("active") },
        { id: "vip", label: "VIP", active: active.includes("vip") },
        { id: "overdue", label: "Overdue", count: 3, active: active.includes("overdue") },
      ]}
      onFilterToggle={(id, on) => setActive((list) => (on ? [...list, id] : list.filter((x) => x !== id)))}
      sort={{
        label: "Sort",
        value: sort,
        onValueChange: setSort,
        options: [
          { value: "newest", label: "Newest" },
          { value: "name", label: "Name (A-Z)" },
          { value: "balance", label: "Highest balance" },
        ],
      }}
      view={view}
      onViewChange={setView}
      resultCount={48}
      locale="en-US"
      actions={[
        { label: "Import CSV", icon: <Upload /> },
        { label: "Export", icon: <Download /> },
        { label: "New client", icon: <Plus />, primary: true },
      ]}
      selectedCount={selected.length}
      bulkActions={[
        { label: "Archive", icon: <Archive /> },
        { label: "Delete", icon: <Trash2 />, tone: "danger" },
      ]}
      onClearSelection={() => setSelected([])}
    />
  )
}
```

Docs: https://wingo-ui.com/components/toolbar (Markdown: https://wingo-ui.com/components/toolbar.md)

### Media

#### Audio Player (`audio-player`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add audio-player`

An audio player with a waveform you can see and scrub: a podcast card, a chat voice message or a thin call-log bar.

Press play: the icon turns into pause on a quick spring, the played bars fill in the tone as the recording runs and the time counts up. Tap or click anywhere on the waveform to jump there; drag along it to scrub (the bars and the time follow the finger, the audio seeks on release, and every 120ms with a mouse so you hear where you are). With a mouse, hovering shows a cursor line with the time above it. The card has skip back / forward buttons (15 seconds), a speed menu (a bottom sheet on phones), a volume button with a slider (hidden on touch screens, where the hardware keys do it) and an optional download. The compact voice-message player cycles 1×, 1,5×, 2× on each tap of its chip and shows the length until it starts, then the position. Starting one player pauses the others. While playing, the phone's lock screen and headphone buttons control it. Keyboard: Tab reaches the play button, the waveform and each control; on the waveform Left / Right (or Up / Down) seek 5 s, PageUp / PageDown 30 s, Home / End jump to the start or end, Space, k or Enter play and pause; anywhere in the player Space / k play, j / l seek 10 s, m mutes, Up / Down change the volume, 0 to 9 jump to 0% to 90%, < and > change the speed. A missing file shows a message with a retry. The file also exports Waveform (the bars alone for custom layouts: peaks, progress as a number or a motion value, barCount / barWidth / barGap / barRadius / height, tone / color, onSeek(fraction) makes it a slider with click, drag and arrow keys, onScrub(fraction | null), formatBubble(fraction) for the hover bubble, peaksKey to fade in new bars), computePeaks(buffer, count) (max absolute sample per bucket, normalized 0 to 1), decodePeaks(src, count, { signal }) (fetch, decodeAudioData and computePeaks, cached per src and count) and placeholderPeaks(seed, count) (stable speech-like bars, the same on the server and the client).

npm: motion, lucide-react
Wingo UI dependencies: button, dropdown-menu, popover, slider, spinner, tooltip, use-media-controls, use-locale, file-export, motion, number-format, tones, ui-config

Props:
- `src: string`: The audio file url. Decoding peaks needs the file on the same origin or served with CORS.
- `title?: ReactNode` = "": The card's title, and the lock-screen title while playing (when it is a string).
- `subtitle?: ReactNode` = "": A muted line under the title (show, author, date); the lock-screen artist while playing.
- `cover?: string`: Square artwork url for the card. It sits at 94% while paused and grows to full size while playing. Also the lock-screen artwork.
- `leading?: ReactNode`: Compact only: an avatar or a mic icon before the play button, the chat look.
- `variant?: "card" | "compact" | "minimal"` = "card": card: cover, title, waveform and a controls row on a raised panel. compact: the voice message (play, bars, time, speed chip) for chat bubbles. minimal: play, a thin scrubbable bar and the time for lists and call logs.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the played bars and the play button. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the played bars and the play button; replaces the tone. The play icon turns black or white by lightness.
- `size?: "sm" | "md"` = "md": Button sizes: md has a 40px play button in the card (32px compact and minimal), sm 32px (28px). Every button keeps a 44px touch target.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the card surface (12 / 16 / 24px) and its cover.
- `barCount?: number` = 0: How many bars. 0 fits as many as the width allows (barWidth + barGap each, remeasured on resize); a fixed count spreads over the width.
- `barWidth?: number` = 3: Width of each bar in px.
- `barGap?: number` = 2: Space between bars in px.
- `barRadius?: number` = 2: Corner radius of each bar in px.
- `waveformHeight?: number` = 0: Height of the waveform in px. 0 is automatic: 40px in the card, 28px in the compact player.
- `peaks?: number[]`: Precomputed bar heights from 0 to 1, any length (resampled to the bar count, max per bucket). Skips decoding.
- `decodePeaks?: boolean` = true: Without peaks, fetch and decode the file with Web Audio once the player is on screen (one decode per file, cached), fading from placeholder bars to the real waveform. A CORS-blocked file stays on the placeholder bars.
- `skipSeconds?: number` = 15: Seconds for the card's skip back / forward buttons and the lock-screen skip. 0 hides the buttons.
- `rates?: number[]`: Playback speeds. Compact cycles through them on tap (default [1, 1.5, 2]); the card opens a menu (default MEDIA_RATES, 0.5 to 2). One entry hides the speed control.
- `showVolume?: "auto" | "always" | "never"` = "auto": The card's volume button and slider. auto hides it on touch screens, where people use the hardware keys.
- `downloadable?: boolean` = false: A download button (card and minimal) that saves the file through file-export's downloadUrl and announces it.
- `fileName?: string` = "": The downloaded file's name, sanitized, keeping the source's extension. Empty keeps the name from the url.
- `exclusive?: boolean` = true: Starting this player pauses every other exclusive player on the page, so two voice notes never talk over each other.
- `mediaSession?: boolean` = true: While playing, sets the lock-screen metadata (title, subtitle, cover) and handles play, pause, seek back / forward and seek-to from the lock screen and headphones.
- `preload?: "none" | "metadata" | "auto"` = "metadata": The audio element's preload. metadata loads the duration only; none shows --:-- until the first play.
- `loop?: boolean` = false: Starts over at the end.
- `locale?: string` = "": Formats the speed labels (1.5× in en-US, 1,5× in de-DE). Empty uses UIProvider, then the page language.
- `onPlay?: () => void`: Playback started (passed to useMediaControls).
- `onPause?: () => void`: Playback paused.
- `onEnded?: () => void`: The recording reached its end (the play icon turns into replay).
- `onError?: (error: MediaError | null) => void`: The file could not be loaded or played; the player shows the error row with a retry.
- `onTimeUpdate?: (seconds: number) => void`: Whole seconds while playing and after seeks: resume positions, listening analytics.
- `setApi?: (api: AudioPlayerApi) => void`: The media controls without the ref: playing, second, duration, progress (a motion value), play(), pause(), seek(seconds), seekBy, setRate... Called after mount and again when the state changes (at most once a second while playing), so it can go straight into state.
- `labels?: Partial<AudioPlayerLabels>`: Every string: play "Play", pause "Pause", replay "Replay", loading "Loading", seek "Seek", skipBack(s) "Back {s} seconds", skipForward(s), speed "Speed", cancel "Cancel" (the speed sheet on phones), volume "Volume", mute "Mute", unmute "Unmute", download "Download", downloaded(name), error "The recording could not be played", retry "Try again", live "Live", position(current, total) "{current} of {total}". DEFAULT_AUDIO_PLAYER_LABELS holds the English set.
- `classNames?: Partial<Record<AudioPlayerSlot, string>>`: Classes for the parts: audio, header, cover, meta, title, subtitle, leading, play, waveform, bar, time, controls, skipBack, skipForward, rate, volume, download, error, live.

```tsx
import { AudioPlayer } from "@/components/ui/audio-player"

export function Episode() {
  return (
    <AudioPlayer
      src="/demo/podcast.mp3"
      title="Sales tax for small businesses"
      subtitle="Summit Podcast · Ep. 12 · Sep 24, 2026"
      cover="/demo/mountains.jpg"
      downloadable
      labels={{ download: "Save episode" }}
    />
  )
}

export function VoiceNote() {
  return <AudioPlayer variant="compact" src="/demo/voice-message.mp3" labels={{ play: "Listen", pause: "Stop" }} />
}
```

Docs: https://wingo-ui.com/components/audio-player (Markdown: https://wingo-ui.com/components/audio-player.md)

#### Carousel (`carousel`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add carousel`

Swipeable rows of slides on embla: photos, listing cards, testimonials and onboarding, with peek, arrows, dots, thumbnails and autoplay.

Drag or swipe the slides: embla's physics carry them and they snap to the nearest slide (dragFree lets a rail glide without snapping). On a trackpad, a two-finger swipe sideways moves one slide per swipe (Shift + mouse wheel too), and the page does not go back or forward. With a mouse, round arrows sit on the photo (or beside it, or in the header); they fade out at the ends and hide when there is nothing to scroll. Click a dot, a story bar or a thumbnail to jump there; the active dot stretches on a spring. With focus anywhere inside (the viewport itself is focusable), Left and Right (Up and Down when vertical) move one slide, Home and End jump to the first and last; inputs inside keep their own arrow keys. Dots and thumbnails are one Tab stop each (focus follows the selection), slides out of view are inert so Tab never lands on a hidden link (except in dragFree rails, which scroll a focused slide into view), and an arrow that turns disabled at the end hands its focus to the other one. Autoplay fills the bars as it runs and pauses while hovered, while keyboard focus is inside, while dragging, when the tab is hidden and when the carousel is off screen; the pause / play button is always there. On a phone arrows hide, 12% of the next slide peeks, dots get 44px tap areas and vertical page scrolling is never blocked. Under reduced motion arrows jump, effects are off and autoplay starts paused.

npm: embla-carousel-react, motion, lucide-react
Wingo UI dependencies: button, use-controllable-state, motion, ui-config

Props:
- `children?: ReactNode`: The slides. Each child is wrapped in a CarouselSlide (role group, "3 of 8") unless it already is one. Images inside should be draggable={false}.
- `slidesPerView?: number | "auto" | { base?: number; sm?: number; md?: number; lg?: number }` = "1": Slides visible at once. Fractions peek (1.15 shows 15% of the next slide). An object sets it by the carousel's own width (container queries: base, sm from 640px, md from 768px, lg from 1024px), so a rail in a narrow column shows fewer slides and the server layout is already right. "auto" sizes slides by their content width. The playground offers 1, 1.15, 2, 3 and auto.
- `peek?: boolean` = true: While the carousel is narrower than 640px (a phone), whole-number slidesPerView values show 12% of the next slide (1 becomes 1.12), so it always hints that there is more.
- `gap?: "none" | "sm" | "md" | "lg"` = "md": Space between slides: 0 / 8 / 12 / 16px.
- `align?: "start" | "center"` = "start": Where the selected slide sits in the viewport. center suits the scale effect and testimonials.
- `orientation?: "horizontal" | "vertical"` = "horizontal": vertical scrolls up and down (tickers, stories); give the viewport a height through classNames.viewport (320px by default).
- `loop?: boolean` = false: Wraps from the last slide to the first. Embla turns it off by itself when there are too few slides to fill the view.
- `dragFree?: boolean` = false: Momentum without snapping, for rails of chips or cards.
- `wheel?: boolean` = true: A two-finger trackpad swipe (or Shift + mouse wheel) along the track moves it one slide per swipe; dragFree tracks follow the swipe.
- `arrows?: "auto" | "always" | "never"` = "auto": auto shows the arrows on fine pointers only (phones swipe) and hides them when there is nothing to scroll; always shows them on touch too.
- `arrowPosition?: "inside" | "outside" | "header"` = "inside": inside: round glass buttons over the middle of the viewport. outside: beside the viewport from 1024px up (inside below). header: a pair at the top end, next to the title of a rail.
- `indicator?: "dots" | "bars" | "progress" | "counter" | "none"` = "dots": dots: 6px dots, the active one stretched to 18px. bars: story-like segments that autoplay fills. progress: one thin bar tracking the scroll. counter: a "3 / 8" pill.
- `indicatorPosition?: "below" | "overlay"` = "below": overlay puts the indicator (and the pause button) inside the bottom of the viewport on a dark gradient, for photo galleries.
- `effect?: "none" | "scale" | "parallax"` = "none": scale: slides away from the snap shrink to 0.9 and dim. parallax: media marked data-carousel-parallax shifts against the drag. Both read --slide-progress, written per scroll event (never React state); off under reduced motion.
- `size?: "sm" | "md" | "lg"` = "md": Arrow and indicator sizes: arrows 32 / 40 / 48px, dots 5 / 6 / 8px, thumbnails 48 / 56 / 64px.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Slide and viewport corners: 0 / 12 / 16 / 24px.
- `autoplay?: boolean` = false: Advances every interval (our own timer, no plugin). Pauses while hovered, focused, dragged, hidden or off screen, stops at the end without loop, and always shows a pause / play button (WCAG 2.2.2).
- `interval?: number` = 5000: Milliseconds per slide while autoplaying.
- `pauseOnHover?: boolean` = true: Autoplay waits while a mouse is over the carousel.
- `stopOnInteraction?: boolean` = false: false: a drag, an arrow or a dot restarts the timer; true: autoplay stops until the play button is pressed.
- `label?: string` = "Carousel": The region's aria-label, read as "Carousel, carousel" by screen readers. Name it after its content.
- `title?: ReactNode`: A heading above the viewport; the header arrows sit beside it. It also names the region (aria-labelledby) unless label is set.
- `thumbnails?: (string | ReactNode)[]`: A synced strip under the viewport: image urls or nodes, one per slide. The selected one stays in view.
- `index?: number`: The selected snap, controlled. Pair with onIndexChange.
- `defaultIndex?: number` = 0: The snap shown first, uncontrolled. The playground remounts the carousel when it changes.
- `onIndexChange?: (index: number) => void`: Fires when the selected snap changes, by drag, arrow, dot, key or autoplay.
- `labels?: Partial<CarouselLabels>`: Every string: previous, next, slide(i, n) ("3 of 8"), goTo(i) ("Go to slide 3"), pause, play, carousel and slideRole (the aria-roledescriptions). English by default, DEFAULT_CAROUSEL_LABELS.
- `opts?: EmblaOptionsType`: Anything else for embla (slidesToScroll, skipSnaps, duration, containScroll...). Wins over the props above.
- `setApi?: (api: CarouselApi) => void`: Receives the embla api once it is ready.
- `classNames?: Partial<Record<"header" | "title" | "stage" | "viewport" | "container" | "slide" | "previous" | "next" | "indicator" | "dot" | "counter" | "autoplay" | "thumbnails" | "thumbnail" | "footer" | "overlay", string>>`: Extra classes for the inner parts.

Parts:
- `CarouselRoot` (component): The compound root: a <section aria-roledescription="carousel"> that owns embla, autoplay and the keyboard. Takes every behavior prop above (not the arrow / indicator layout ones), plus scrim (a dark gradient at the bottom of each slide for white controls overlaid on photos). Props: CarouselRootProps.
- `CarouselViewport` (component): The embla viewport and its container; wraps children in slides and numbers them. Props: ComponentProps<"div"> & { classNames?: { container?, slide? } }.
- `CarouselSlide` (component): One slide: role group, data-active, inert while out of view, --slide-progress for effects. Props: ComponentProps<"div"> & { index?: number; total?: number }.
- `CarouselPrevious` (component): The previous arrow, disabled at the start (inside arrows fade out there). Props: ButtonProps & { position?: "inside" | "outside" | "header"; visibility?: "auto" | "always" }.
- `CarouselNext` (component): The next arrow, disabled at the end. Props: ButtonProps & { position?: "inside" | "outside" | "header"; visibility?: "auto" | "always" }.
- `CarouselDots` (component): Dots, story bars or a progress bar; overlay is white-based for photos. Props: ComponentProps<"div"> & { variant?: "dots" | "bars" | "progress"; overlay?: boolean }.
- `CarouselCounter` (component): The "3 / 8" pill. Props: ComponentProps<"span"> & { overlay?: boolean }.
- `CarouselAutoplayToggle` (component): The pause / play button; renders only while autoplay is on. Props: ButtonProps & { overlay?: boolean }.
- `CarouselThumbnails` (component): A second, drag-free embla strip synced to the selection. Props: ComponentProps<"div"> & { items: (string | ReactNode)[] }.
- `useCarousel` (hook): State and controls of the nearest carousel, for custom controls (an onboarding Continue button). progress is the autoplay motion value, 0 to 1. Signature: () => { api, selectedIndex, snapCount, canScrollPrev, canScrollNext, scrollTo, scrollPrev, scrollNext, playing, setPlaying, progress }.

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

const photos = ["/demo/apartment.jpg", "/demo/sofa.jpg", "/demo/city.jpg"]

export function ListingPhotos() {
  return (
    <Carousel label="Apartment photos" indicator="counter" indicatorPosition="overlay" thumbnails={photos}>
      {photos.map((src, i) => (
        <img key={src} src={src} alt={`Photo ${i + 1}`} draggable={false} className="aspect-[4/3] w-full object-cover" />
      ))}
    </Carousel>
  )
}
```

Docs: https://wingo-ui.com/components/carousel (Markdown: https://wingo-ui.com/components/carousel.md)

#### CSV Viewer (`csv-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add csv-viewer`

A CSV and TSV viewer for large files: typed columns, sort, filters, search, selection with copy, resizable and frozen columns, zoom.

The file is read in the browser in small slices, so the first rows show while a big file is still loading and the page never freezes; only the rows and columns in view are drawn, so 200,000 rows scroll smoothly. The delimiter (comma, semicolon, tab or pipe), the text encoding (UTF-8 with or without BOM, UTF-16, Windows-1252) and the header row are detected; change any of them from the status bar or the ⋯ menu. Columns without a header are named A, B, C. Numbers, dates and true / false columns are recognized: numbers align right, numbers and dates are formatted for the locale, sorting follows the type and copies keep the original values. Click a cell, Shift+click or drag for a range, click a column header or a row number for a whole column or row; on touch, tap a cell. The keyboard works like a spreadsheet's: arrows, Tab, Enter, Home / End, Page Up / Down, Ctrl / ⌘ + arrows jump to the edge of the data, Shift extends, Ctrl / ⌘ + A selects all, Ctrl / ⌘ + C copies as tab separated text, Alt + drag selects text inside cells. The bar above the grid shows the address and the full value of the active cell (type an address like C120 and press Enter to go there). Each column header opens a panel (Alt+Down) to sort, filter by text or by a list of its values, fit the width, freeze the columns up to it, hide it or copy it; drag a header edge to resize, double-click it to fit. Search opens from the toolbar or with Ctrl+F / ⌘F inside the viewer: the counter reads 2 of 6 and Enter / Shift+Enter jump between hits. The status bar counts rows and columns, shows how many rows a filter keeps, and the sum, average and count of a selected range. The toolbar zooms, turns the header row, wrapped text, row numbers and formatting on or off, shows or hides columns and downloads the file; below 720px of width these move into the ⋯ menu, which also opens another file (or drop one onto the viewer). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. Menus and panels become bottom sheets on phones.

npm: @tanstack/react-virtual, lucide-react
Wingo UI dependencies: button, checkbox, dropdown-menu, popover, tooltip, use-media-query, ui-config

Props:
- `src?: string` = "/demo/northwind-q3-orders.csv": URL of the .csv, .tsv or .txt: same origin, a CORS-enabled URL or a blob: URL. Empty (and no data) shows the open-a-file state. The playground value is 5,000 sample orders.
- `data?: string` = "": The delimited text itself, instead of src. It wins over src while it is not empty.
- `fileName?: string` = "": Name used for downloads, in the toolbar and in the grid's accessible label. Falls back to the last part of src (data.csv for data); an opened file keeps its own name.
- `delimiter?: "auto" | "comma" | "semicolon" | "tab" | "pipe"` = "auto": auto detects it from the first rows, quotes respected (a .tsv name prefers tab). The status bar and the ⋯ menu switch it for the file in view, or back to detection.
- `encoding?: "auto" | "utf-8" | "utf-16le" | "utf-16be" | "windows-1252" | "windows-1250"` = "auto": auto reads a byte order mark, then UTF-16 by its zero bytes, then UTF-8 when the bytes are valid UTF-8, else Windows-1252. Switch it from the status bar when accents look wrong.
- `header?: "auto" | "first-row" | "none"` = "auto": Whether the first row names the columns. auto compares it with the rows under it (a text first row over numbers or dates is a header). Without one, columns are named A, B, C.
- `defaultZoom?: number` = 1: The zoom each file opens at, 1 is 100%. It scales text, rows and columns together.
- `defaultWrapText?: boolean` = false: Opens with long values wrapped onto up to six lines (rows grow to fit) instead of cut off on one line.
- `defaultRowNumbers?: boolean` = true: Opens with the row number column. Numbers are each row's place in the file, so they stay with the row when it is sorted.
- `defaultFormatValues?: boolean` = true: Opens with numbers and dates formatted for the locale (1,234.50, Jul 14, 2026). Off shows every value as the file writes it.
- `defaultFrozenColumns?: number` = 0: How many columns from the left stay put while scrolling sideways. The column panel freezes or unfreezes up to any column.
- `sortable?: boolean` = true: Sort in the column panel, by the column's type: numbers by value, dates by time, text with the locale's alphabet. Blank cells stay last. The view changes, the file does not.
- `filterable?: boolean` = true: Filter in the column panel: values that contain a text, and a checklist of the values when a column has 200 or fewer different ones.
- `resizable?: boolean` = true: Drag a column header edge to resize it, double-click it to fit the content. Fit width is in the column panel too (touch screens).
- `maxFileSize?: number` = 104857600: Bytes: 100 MB by default. A bigger file shows the file too large state with a download link instead of being read. Slide it under 690 KB to see it with the sample.
- `maxRows?: number` = 1000000: Rows kept after the header. The rest is left out and the status bar says First 1,000,000 rows.
- `locale?: string` = "en-US": Locale for formatted numbers and dates and for text sorting. Unset, it follows the UIProvider locale, then the browser's (en-US here). The file's own decimal mark is detected separately.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `selectionColor?: string` = "#2563eb": Outline of the selection, the tint of a selected range and the mark on selected headers. Any CSS color; also set as --csv-viewer-selection on the frame.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.4)": Fill of every search hit. Keep it translucent so the cell stays readable. Also set as --csv-viewer-highlight on the frame.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.55)": Fill of the current search hit (--csv-viewer-active-highlight).
- `showToolbar?: boolean` = true: The toolbar with zoom, search, view switches, columns and file actions.
- `showDetailBar?: boolean` = true: The bar with the address box (go to) and the full value of the active cell.
- `showStatusBar?: boolean` = true: The bar under the grid: rows and columns, filtered rows, the totals of a selection, and the delimiter and encoding switches.
- `showSearch?: boolean` = true: The search button, and Ctrl+F / ⌘F inside the viewer.
- `showViewSwitches?: boolean` = true: The header row, wrap text, row numbers and format switches (toolbar buttons when wide, the ⋯ menu when narrow).
- `showColumnsMenu?: boolean` = true: The columns menu that shows or hides columns.
- `showDownload?: boolean` = true: The download button (in the ⋯ menu when narrow). It saves the original file, bytes unchanged.
- `showUpload?: boolean` = true: Open a file in the ⋯ menu and dropping a file onto the viewer. The file opens locally; onFileUpload hands it to you.
- `height?: number | string` = 640: Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `zoomLevels?: number[]` = "[0.5, 0.75, 1, 1.25, 1.5, 2]": Steps of the zoom menu and the - / + buttons. The first and last are the limits for pinch and Ctrl / ⌘ + scroll too.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, import, approve.
- `ref?: Ref<CsvViewerHandle> (a useRef object or an (handle) => void callback)`: goTo("C120" | "B12:D20" | "120" | { row, column }, options?), getSelection(), getData(), getRows({ start, end, view }?), clearSort(), clearFilters() and getViewportElement().
- `onCellSelect?: (selection: CsvViewerSelection) => void`: Called when the selection moves, with the address (B12 or B12:D20), the range and the active cell's column, type, raw value and shown text.
- `onFileLoadSuccess?: (file: CsvViewerFileInfo) => void`: Called once a file is read to the end, and again after the delimiter, encoding or header row changes: rows, columns, delimiter, encoding, header, column names and types.
- `onFileLoadError?: (error: unknown) => void`: Called when a file cannot be fetched or read, is too large, empty, binary or an Excel workbook. The viewer shows the matching state.
- `onFileUpload?: (file: File) => void`: Called with the File someone opened or dropped, as the viewer starts reading it.
- `onSortChange?: (sort: CsvViewerSort | null) => void`: Called when a column is sorted ({ column, columnName, direction }) or the sort is cleared (null).
- `labels?: Partial<CsvViewerLabels>`: Every string, English by default (DEFAULT_CSV_VIEWER_LABELS): toolbar, search, column panel, states, status bar and accessible names, including results(active, total), loadingProgress(percent), sortAscending(type), sortDescending(type), columnTypes and cellLabel(address, column, text).
- `classNames?: Partial<Record<"toolbar" | "detailBar" | "viewport" | "header" | "row" | "cell" | "statusBar" | "columnPanel" | "state", string>>`: Extra classes for the toolbar, the detail bar, the scrolling viewport, each header and row number, each row, each cell, the status bar, the column panel and the loading / empty / error states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `CsvViewerHandle` (type): What the ref gets: goTo(target, { behavior }?) which selects and scrolls to "C120", "B12:D20", a row number or { row, column } and returns false when the row is filtered out or missing, getSelection(), getData(), getRows(options?), clearSort(), clearFilters() and getViewportElement().
- `CsvViewerSelection` (type): What onCellSelect receives: address, range (1-based startRow, startColumn, endRow, endColumn), rowCount, columnCount and cell (address, row, column, columnName, type, value, text).
- `CsvViewerFileInfo` (type): What onFileLoadSuccess and getData() return: fileName, rowCount, columnCount, delimiter, encoding (null for data), header, headers, columnTypes, truncated and bytes.
- `CsvViewerSort` (type): What onSortChange receives: column (0-based), columnName and direction.
- `CsvViewerColumnType` (type): "number", "date", "boolean" or "text": what a column was recognized as.
- `CsvViewerLabels` (type): The shape of labels: every string the viewer renders.
- `DEFAULT_CSV_VIEWER_LABELS` (constant): The English labels. Spread it to translate a few strings.

```tsx
import { CsvViewer } from "@/components/ui/csv-viewer"

export function OrdersPreview() {
  return (
    <CsvViewer
      src="/demo/northwind-q3-orders.csv"
      height="80dvh"
      defaultFrozenColumns={1}
      onCellSelect={({ address, cell }) => console.log(address, cell.value)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/csv-viewer (Markdown: https://wingo-ui.com/components/csv-viewer.md)

#### DOCX Editor (`docx-editor`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add docx-editor`

A Word (.docx) editor with real pages, styles, fonts, tables, images, find and replace, comments and tracked changes, saved back to .docx.

Click on a page to place the caret and type; drag, double-click (word) or triple-click (paragraph) to select, Shift+click to extend. Arrow keys move by the lines you see on the page; Tab inserts a tab and Escape moves focus to the toolbars. The formatting bar sets the paragraph style (each style previews in a card), the font (the document's own fonts first), the size (type it, or A- / A+, Shift+Ctrl / ⇧⌘ + < >), bold, italic, underline, strikethrough, superscript, subscript, text color, highlight, links (Ctrl / ⌘+K opens a bar: Enter applies, Escape cancels), alignment, lists, indent (Ctrl / ⌘ + [ ]), line and paragraph spacing, images (pick or drop one, then drag a corner to resize), tables (a 10 x 8 grid; inside a table a menu adds, deletes, merges and splits), page breaks (Ctrl / ⌘+Enter), borders and clear formatting. What does not fit folds into the ⋯ menu; on a phone the bar sits at the bottom, above the keyboard. Ctrl / ⌘+F finds (Enter / Shift+Enter step, 2 of 6), Shift+Ctrl / ⇧⌘+H replaces one or all. Select text and add a comment (Ctrl+Alt / ⌥⌘+M): cards sit beside the pages where they fit, in a panel otherwise, with replies, resolve and reopen; tracked changes have Accept and Reject. The mode menu switches Editing, Suggesting (your edits become tracked changes under author) and Viewing. Zoom with - and +, the zoom menu (fit width, fit page), Ctrl / ⌘ + scroll, pinch, or Ctrl / ⌘ + = / -. The sidebar lists live page thumbnails (Up / Down, Home / End). Save (Ctrl / ⌘+S, with onSave), download, print (Ctrl / ⌘+P) and open another .docx from the toolbar; opening one over unsaved edits asks first.

npm: @eigenpal/docx-editor-core, prosemirror-state, prosemirror-view, prosemirror-model, prosemirror-history, prosemirror-tables, jszip, lucide-react
Wingo UI dependencies: alert-dialog, button, color-picker, dropdown-menu, kbd, popover, select, tooltip, use-controllable-state, use-media-query, ui-config

Props:
- `src?: string` = "/demo/northwind-supply-agreement.docx": URL of the .docx: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-document state. The playground value is the sample agreement.
- `fileName?: string` = "": Name for downloads, onSave and the document's accessible label. Falls back to the last part of src or the opened file's name.
- `author?: string` = "You": The name on comments you add and on suggestions made in Suggesting mode; its initials sit in the status bar.
- `defaultReadOnly?: boolean` = false: Opens in view-only mode: no caret, no formatting bar; Download and Print still work. The mode menu can switch back. Use readOnly to control it.
- `defaultSuggesting?: boolean` = false: Opens in Suggesting mode: insertions and deletions become tracked changes by author. Use suggesting to control it.
- `dirty?: boolean` = false: Adds your own unsaved state to the status bar. Switching it from true to false after you stored ref.exportDocx() marks the content as saved.
- `defaultZoom?: number | "fit-page" | "fit-width" | "automatic"` = "automatic": The zoom each document opens at: a scale (1 is 100%) or a fit mode. Automatic fits the width up to 100%, so a phone shows the whole page width.
- `defaultSidebarOpen?: boolean` = true: Opens with the page thumbnails beside the pages. An editor narrower than 520px starts closed, since there the sidebar covers the page.
- `defaultDarkPages?: boolean` = false: Opens with the pages inverted for reading at night; images keep their colors. Pages are white otherwise, in both themes.
- `webFonts?: boolean` = false: Loads metric-compatible fonts (Carlito for Calibri, Caladea for Cambria) from Google Fonts for closer line breaks. Off by default: no third-party requests.
- `locale?: string` = "en-US": Locale for the dates on comments and changes. Unset, it follows the UIProvider locale, then the browser's (en-US here).
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.45)": Fill of every find hit (--docx-editor-highlight). Keep it translucent so the text stays readable.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.5)": Fill of the current find hit and of text waiting for a new comment (--docx-editor-active-highlight).
- `selectionColor?: string` = "rgba(59, 130, 246, 0.28)": The text selection drawn on the page (--docx-editor-selection).
- `showToolbar?: boolean` = true: The document toolbar: thumbnails, page, mode, zoom, find, view switches, save and the ⋯ menu.
- `showFormatBar?: boolean` = true: The formatting bar. Hidden in view-only mode; below 600px of width it moves to the bottom, above the keyboard.
- `showThumbnails?: boolean` = true: The page thumbnails sidebar and its toggle.
- `showStatusBar?: boolean` = true: The bottom line with the page, the word count, the mode and the saved state.
- `showComments?: boolean` = true: Comment cards, Add comment and their switch.
- `showChanges?: boolean` = true: Tracked change cards with Accept / Reject, their switch and Suggesting in the mode menu.
- `showDarkPages?: boolean` = true: The dark pages switch (in the ⋯ menu when narrow).
- `showFind?: boolean` = true: Find and replace, and Ctrl / ⌘+F inside the editor.
- `showImport?: boolean` = true: Open a document and New blank document in the ⋯ menu, and dropping a .docx onto the editor (not in view-only mode).
- `showDownload?: boolean` = true: Download .docx with your edits (in the ⋯ menu when narrow).
- `showPrint?: boolean` = true: Print in the ⋯ menu and Ctrl / ⌘+P inside the editor.
- `showReadOnlyToggle?: boolean` = true: Viewing in the mode menu, so people can switch to view-only themselves.
- `height?: number | string` = 640: Height of the editor: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `file?: File | Blob | ArrayBuffer`: A document you already hold in memory; wins over src. A new object opens a new document.
- `readOnly?: boolean`: Controls view-only mode: no caret, no formatting bar, Download and Print still work. Pair it with onReadOnlyChange so the mode menu can switch it.
- `onReadOnlyChange?: (readOnly: boolean) => void`: Called when the mode menu or ref.setReadOnly switches view-only mode.
- `suggesting?: boolean`: Controls Suggesting mode. Pair it with onSuggestingChange so the mode menu can switch it.
- `onSuggestingChange?: (suggesting: boolean) => void`: Called when the mode menu switches Suggesting on or off.
- `zoomLevels?: number[]` = "[0.5, 0.75, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2]": Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits.
- `sidebarOpen?: boolean`: Controls the thumbnails sidebar. Inline from 520px of editor width, an overlay below it.
- `onSidebarOpenChange?: (open: boolean) => void`: Called when the sidebar opens or closes.
- `onDirtyChange?: (dirty: boolean) => void`: Called when the document gets unsaved edits, and again when they are saved or undone.
- `onChange?: (details: DocxEditorChangeDetails) => void`: Called 400 ms after the last edit, with the page count, word count and dirty flag. Get the file with ref.exportDocx().
- `onSave?: (blob: Blob, info: DocxEditorSaveInfo) => (void | Promise<unknown>)`: Shows a Save button and binds Ctrl / ⌘+S. Gets the .docx and its file name, page and word counts. Return a promise to show Saving and then Saved, or the error.
- `onDocumentLoadSuccess?: (document: DocxEditorDocument) => void`: Called when a document is ready, with its page and word counts, comments and tracked changes.
- `onDocumentLoadError?: (error: unknown) => void`: Called when a document cannot be fetched or parsed. The editor shows the error state with Try again.
- `onError?: (error: unknown) => void`: Called when an export, a save, an image or a layout pass fails.
- `onDocxUpload?: (file: File) => void`: Called with the File someone opened or dropped.
- `onActivePageChange?: (pageNumber: number) => void`: Called with the page in view as you scroll or jump.
- `onCommentAdd?: (comment: DocxEditorComment) => void`: Called when someone adds a comment or a reply.
- `onCommentResolve?: (comment: DocxEditorComment) => void`: Called when a comment is resolved.
- `onChangeAccept?: (change: DocxEditorChange) => void`: Called when a tracked change is accepted.
- `onChangeReject?: (change: DocxEditorChange) => void`: Called when a tracked change is rejected.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, send for signature, publish.
- `ref?: Ref<DocxEditorHandle> (a useRef object or an (handle) => void callback)`: exportDocx(), download(fileName?), getText(), insertText(text), focus(), undo(), redo(), scrollToPage(n), find(query), setReadOnly(readOnly), isDirty(), markSaved(), getPageCount() and getWordCount().
- `labels?: Partial<DocxEditorLabels>`: Every string, English by default (DEFAULT_DOCX_EDITOR_LABELS): toolbar and menu names, tooltips, find and replace, comments and changes, states, the discard dialog. Strings with numbers are functions, like findResults(active, total), wordCount(words) and tableSize(rows, columns).
- `classNames?: Partial<Record<"toolbar" | "formatBar" | "sidebar" | "thumbnail" | "viewport" | "page" | "annotation" | "statusBar" | "findBar" | "state", string>>`: Extra classes for the toolbar, the formatting bar, the sidebar, each thumbnail, the scrolling viewport, the pages, each card, the status bar, the find bar and the states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `DocxEditorHandle` (type): What the ref gets: exportDocx(): Promise<Blob>, download(fileName?), getText(), insertText(text), focus(), undo(), redo(), scrollToPage(pageNumber), find(query) (opens find and returns the count), setReadOnly(readOnly), isDirty(), markSaved(), getPageCount() and getWordCount().
- `DocxEditorDocument` (type): What onDocumentLoadSuccess receives: pageCount, wordCount, comments (DocxEditorComment[]) and changes (DocxEditorChange[]).
- `DocxEditorComment` (type): A comment or reply: id, author, initials, date, text, anchorText (the commented passage), parentId (for replies) and resolved.
- `DocxEditorChange` (type): A tracked change: id (the revision), kind ("insertion" | "deletion" | "replacement" | "formatting" | "structure"), author, date, text and deletedText.
- `DocxEditorChangeDetails` (type): What onChange receives: pageCount, wordCount and dirty.
- `DocxEditorSaveInfo` (type): The second argument of onSave: fileName, pageCount and wordCount.
- `DocxEditorSource` (type): What file accepts: File | Blob | ArrayBuffer.
- `DocxEditorZoom` (type): A scale or "fit-page" | "fit-width" | "automatic".
- `DocxEditorMode` (type): "editing" | "suggesting" | "viewing", the three modes of the mode menu.
- `DocxEditorLabels` (type): The shape of labels: every string the editor renders.
- `DEFAULT_DOCX_EDITOR_LABELS` (constant): The English labels. Spread it to translate a few strings.

```tsx
import { useRef } from "react"
import { DocxEditor, type DocxEditorHandle } from "@/components/ui/docx-editor"

export function AgreementEditor() {
  const editor = useRef<DocxEditorHandle>(null)
  return (
    <DocxEditor
      ref={editor}
      src="/demo/northwind-supply-agreement.docx"
      author="Emma Carter"
      height="80dvh"
      onSave={async (blob, { fileName }) => {
        const body = new FormData()
        body.append("file", blob, fileName)
        await fetch("/api/documents", { method: "POST", body })
      }}
      onDirtyChange={(dirty) => console.log(dirty ? "Unsaved changes" : "Saved")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/docx-editor (Markdown: https://wingo-ui.com/components/docx-editor.md)

#### DOCX Viewer (`docx-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add docx-viewer`

A Word (.docx) viewer with real pages, headers and footers, thumbnails, zoom, search, comments, tracked changes, download and upload.

Scroll through the pages: each one is laid out like Word's, with its header, footer and page numbers, and a page that runs long is split at its paragraphs and table rows. Type a page number in the toolbar (Enter jumps, Up and Down step, Escape cancels). Zoom with - and +, or pick Automatic, Fit page, Fit width or a percentage from the zoom menu. Search opens from the toolbar or with Ctrl+F / ⌘F while focus is inside the viewer: hits are highlighted, the counter reads 2 of 5, and Enter / Shift+Enter or the arrows step through them. Comments show as cards beside the pages with the commented text highlighted; click a card or the highlighted text to pick it. When the viewer is too narrow for the cards, markers sit on the page edge and open the card in a popover (a bottom sheet on phones). The toolbar switches comments, tracked changes (insertions underlined in green, removals struck through in red) and dark pages on or off and downloads the original file; below 720px of width these move into the ⋯ menu, which also opens another .docx (you can drop one onto the viewer too). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. The sidebar shows page thumbnails: click to jump; in the list Up / Down move, Home / End jump. It starts open beside the pages; below 520px of width it starts closed, slides over the pages when opened and closes after a pick; below 440px the zoom steps move into the ⋯ menu.

npm: docx-preview, lucide-react
Wingo UI dependencies: button, dropdown-menu, popover, tooltip, use-controllable-state, ui-config

Props:
- `src?: string` = "/demo/project-proposal.docx": URL of the .docx: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-document state. The playground value is the sample proposal.
- `fileName?: string` = "": Name used for downloads and in the document's accessible label. Falls back to the last part of src; an uploaded file keeps its own name.
- `defaultZoom?: number | "fit-page" | "fit-width" | "automatic"` = "automatic": The zoom the document opens at: a scale (1 is 100%) or a fit mode. Automatic fits the width up to 100%, so a page never opens blown up on a large screen or cut off on a phone.
- `defaultCommentsVisible?: boolean` = true: Opens with the comments showing: cards beside the pages, or markers on the page edge in a narrow viewer.
- `defaultChangesVisible?: boolean` = false: Opens with tracked changes marked up (insertions underlined, removals struck through) and listed beside the pages. Off shows the document as it reads with every change accepted.
- `defaultDarkPages?: boolean` = false: Opens with the pages inverted for reading at night; images keep their colors. Pages are white otherwise, in both themes.
- `locale?: string` = "en-US": Locale for the dates on comments and changes. Unset, it follows the UIProvider locale, then the browser's (en-US here).
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.4)": Fill of every search hit. Any CSS color; keep it translucent so the text stays readable. Also set as --docx-viewer-highlight on the frame.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.55)": Fill of the current search hit and of the text behind the picked comment (--docx-viewer-active-highlight).
- `commentHighlightColor?: string` = "rgba(250, 204, 21, 0.28)": Fill of commented text while comments are showing (--docx-viewer-comment-highlight).
- `showToolbar?: boolean` = true: The toolbar with page, zoom, search and file controls. Off leaves the bare pages, for previews you drive yourself.
- `showThumbnails?: boolean` = true: The pages sidebar and its toggle.
- `defaultSidebarOpen?: boolean` = true: Opens with the pages sidebar showing beside the pages. A viewer narrower than 520px (a phone) starts closed, since there the sidebar covers the page. Use sidebarOpen and onSidebarOpenChange to control it.
- `showSearch?: boolean` = true: The search button, and Ctrl+F / ⌘F inside the viewer.
- `showComments?: boolean` = true: Comments at all, and their switch in the toolbar (the ⋯ menu when narrow).
- `showChanges?: boolean` = true: The tracked changes switch in the toolbar (the ⋯ menu when narrow).
- `showDarkPages?: boolean` = true: The dark pages switch in the toolbar (the ⋯ menu when narrow).
- `showDownload?: boolean` = true: The download button (in the ⋯ menu when narrow). It saves the original file.
- `showUpload?: boolean` = true: Open a document in the ⋯ menu and dropping a .docx onto the viewer. The file opens locally; onDocxUpload hands it to you.
- `height?: number | string` = 640: Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `sidebarOpen?: boolean`: Controls the pages sidebar. Inline from 520px of viewer width, an overlay below it.
- `onSidebarOpenChange?: (open: boolean) => void`: Called when the sidebar opens or closes.
- `zoomLevels?: number[]` = "[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]": Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, approve, send for signature.
- `ref?: Ref<DocxViewerHandle> (a useRef object or an (handle) => void callback)`: scrollToPage(page), scrollToHeading(id), scrollToAnnotation(id), getOutline() and getViewportElement().
- `renderPageOverlay?: (props: DocxViewerPageOverlayProps) => ReactNode`: Draws on top of every page: stamps, citations, signature fields. Gets the page number, its size at the current zoom and the scale, so boxes in percent always line up.
- `onActivePageChange?: (pageNumber: number) => void`: Called with the page in view as you scroll or jump.
- `onDocumentLoadSuccess?: (document: DocxViewerDocument) => void`: Called when a document is ready, with its page count, its outline (the headings, for a table of contents) and its comments and tracked changes.
- `onDocumentLoadError?: (error: unknown) => void`: Called when a document cannot be fetched or parsed. The viewer shows the error state.
- `onDocxUpload?: (file: File) => void`: Called with the File someone opened or dropped, after the viewer shows it.
- `onAnnotationClick?: (annotation: DocxViewerAnnotation) => void`: Called when a comment or change is picked, from its card, its marker or its text.
- `labels?: Partial<DocxViewerLabels>`: Every string, English by default (DEFAULT_DOCX_VIEWER_LABELS): page, of, pageNumber, pagesSidebar, pages, pageLabel(page), zoomIn, zoomOut, zoomLevel, fitPage, fitWidth, automatic, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, comments, changes, darkPages, download, upload, document, loading, error, emptyTitle, emptyDescription, dropHere, annotations, comment, inserted, deleted, unknownAuthor, annotationLabel(kind, author).
- `classNames?: Partial<Record<"toolbar" | "sidebar" | "thumbnail" | "viewport" | "annotation" | "state", string>>`: Extra classes for the toolbar, the sidebar, each thumbnail, the scrolling viewport, each comment card and the loading / empty / error states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `DocxViewerHandle` (type): What the ref gets: scrollToPage(pageNumber, options?), scrollToHeading(id, options?) with an id from the outline, scrollToAnnotation(id, options?), getOutline() and getViewportElement().
- `DocxViewerDocument` (type): What onDocumentLoadSuccess receives: numPages, outline (DocxViewerHeading[]) and annotations (DocxViewerAnnotation[]).
- `DocxViewerHeading` (type): An outline entry: id, title, level (1 for Heading 1) and pageNumber.
- `DocxViewerAnnotation` (type): A comment or tracked change: id, kind ("comment" | "insertion" | "deletion"), author, initials, date, text, anchorText (the commented passage) and pageNumber.
- `DocxViewerPageOverlayProps` (type): What renderPageOverlay receives: pageNumber, pageWidth and pageHeight at the current zoom, and scale.
- `DocxViewerZoom` (type): A scale or "fit-page" | "fit-width" | "automatic".
- `DocxViewerLabels` (type): The shape of labels: every string the viewer renders.
- `DEFAULT_DOCX_VIEWER_LABELS` (constant): The English labels. Spread it to translate a few strings.

```tsx
import { DocxViewer } from "@/components/ui/docx-viewer"

export function ProposalPreview() {
  return (
    <DocxViewer
      src="/demo/project-proposal.docx"
      fileName="Riverside renovation proposal"
      height="80dvh"
      onDocumentLoadSuccess={({ numPages, outline }) => console.log(numPages, outline)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/docx-viewer (Markdown: https://wingo-ui.com/components/docx-viewer.md)

#### Excel Viewer (`excel-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add excel-viewer`

An Excel (.xlsx) and CSV viewer with real cell styles, number formats, frozen panes, sheet tabs, a formula bar, sort, search and zoom.

Scroll the sheet both ways: only the rows and columns in view are drawn, so tens of thousands of rows stay smooth, and the A B C / 1 2 3 headings and the file's frozen rows and columns stay put. Cells keep the workbook's look: fonts, fills, borders, alignment, wrapping, merged cells, column widths and row heights, hidden rows and columns, number formats (currency, percent, dates through Intl and the locale), conditional formats (color scales, data bars, icon sets, highlight rules), Excel table styles, images and charts. Click a cell to select it, Shift+click or drag for a range, click a heading for a whole column or row; on touch, tap a cell. The keyboard works like Excel's: arrows, Tab, Enter, Home / End, Page Up / Down, Ctrl / ⌘ + arrows jump to the edge of the data, Shift extends, Ctrl / ⌘ + A selects all, Ctrl / ⌘ + C copies as tab separated text. The formula bar shows the address and the formula or value of the active cell; type an address, a range like Team!A2:C9 or a defined name in its box and press Enter to go there. Each column heading has a menu (Alt+Down) to sort A to Z or Z to A in the view only (blank cells stay last, totals rows stay at the bottom) and to clear the sort; drag a heading edge to resize, double-click it to fit. Search opens from the toolbar or with Ctrl+F / ⌘F inside the viewer and looks through every sheet: the counter reads 2 of 6 and Enter / Shift+Enter jump between hits, switching sheets as needed. Sheet tabs sit at the bottom and scroll sideways; hidden sheets are left out and the ☰ menu lists them all. The toolbar zooms (- / + or a percentage, Fit width), turns gridlines, formulas and dark cells on or off and downloads the file; below 720px of width these move into the ⋯ menu, which also opens another .xlsx or .csv (or drop one onto the viewer). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. Menus become bottom sheets on phones.

npm: @tanstack/react-virtual, fflate, lucide-react
Wingo UI dependencies: button, dropdown-menu, popover, tooltip, use-controllable-state, spreadsheet, ui-config

Props:
- `src?: string` = "/demo/q3-sales-report.xlsx": URL of the .xlsx or .csv: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-workbook state. The playground value is the sample sales report (3 sheets, 2,000 orders).
- `fileName?: string` = "": Name used for downloads, in the toolbar and in the grid's accessible label. Falls back to the last part of src; an uploaded file keeps its own name.
- `defaultSheet?: string` = "": The sheet it opens on, by name. Empty opens the sheet the workbook was saved on. Use sheet and onSheetChange to control it.
- `defaultZoom?: number | "fit-width"` = 1: The zoom each workbook opens at: a scale (1 is 100%), or "fit-width", which fits the used columns to the viewer. The playground slider sets the scale.
- `defaultGridlines?: boolean` = true: On, each sheet shows gridlines the way the file says (a sheet saved without them stays clean). Off hides them everywhere. The toolbar switch changes the current sheet.
- `defaultFormulas?: boolean` = false: Opens with formulas shown in the cells instead of their values, like Excel's Show Formulas. Values are the ones saved in the file; nothing is recalculated.
- `defaultDarkCells?: boolean` = false: Opens with dark cells for reading at night: white and light fills turn dark, text turns light, strong colors stay. Cells are white otherwise, in both themes.
- `sortable?: boolean` = true: The menu on each column heading: sort A to Z, Z to A and clear. Sorting reorders the view only; the file and the download stay as they were.
- `resizable?: boolean` = true: Drag a column or row heading edge to resize it, double-click a column edge to fit its content. View only.
- `maxFileSize?: number` = "52428800": Bytes: 50 MB by default. A bigger file shows the file too large state with a download link instead of being parsed. The playground offers 100 KB, smaller than the sample, to show it.
- `locale?: string` = "en-US": Locale for numbers, currency and dates: decimal and thousands separators, month and day names, and the short date of Excel's system date format. Unset, it follows the UIProvider locale, then the browser's (en-US here).
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `selectionColor?: string` = "#217346": Outline of the selection, the tint of a selected range and the mark on selected headings. Any CSS color; also set as --excel-viewer-selection on the frame.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.4)": Fill of every search hit on the sheet. Keep it translucent so the cell stays readable. Also set as --excel-viewer-highlight on the frame.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.55)": Fill of the current search hit (--excel-viewer-active-highlight).
- `showToolbar?: boolean` = true: The toolbar with zoom, search, view switches and file actions.
- `showFormulaBar?: boolean` = true: The bar with the name box (address, go to) and the formula or value of the active cell.
- `showSheetTabs?: boolean` = true: The sheet tabs at the bottom, with the list of sheets and, on a wide viewer, the sum, average and count of a selected range.
- `showHeadings?: boolean` = true: The A B C column and 1 2 3 row headings.
- `showSearch?: boolean` = true: The search button, and Ctrl+F / ⌘F inside the viewer.
- `showGridlines?: boolean` = true: The gridlines switch in the toolbar (the ⋯ menu when narrow).
- `showFormulas?: boolean` = true: The show formulas switch in the toolbar (the ⋯ menu when narrow).
- `showDarkCells?: boolean` = true: The dark cells switch in the toolbar (the ⋯ menu when narrow).
- `showDownload?: boolean` = true: The download button (in the ⋯ menu when narrow). It saves the original file.
- `showUpload?: boolean` = true: Open a workbook in the ⋯ menu and dropping an .xlsx or .csv onto the viewer. The file opens locally; onWorkbookUpload hands it to you.
- `height?: number | string` = 640: Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `sheet?: string`: Controls the sheet shown, by name. Pair it with onSheetChange.
- `onSheetChange?: (sheet: string) => void`: Called with the sheet name when a tab, the sheets menu, a search hit or ref.goTo switches sheets.
- `zoomLevels?: number[]` = "[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]": Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits for pinch and Ctrl / ⌘ + scroll too.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, import, approve.
- `ref?: Ref<ExcelViewerHandle> (a useRef object or an (handle) => void callback)`: selectSheet(name or index), goTo("B12" | "Team!A2:C9" | defined name, options?), getSelection(), getWorkbook(), clearSort() and getViewportElement().
- `onCellSelect?: (selection: ExcelViewerSelection) => void`: Called when the selection moves, with the sheet, the address (B12 or A1:D20), the range and the active cell's value, shown text, formula, note and link.
- `onWorkbookLoadSuccess?: (workbook: ExcelViewerWorkbook) => void`: Called when a workbook is ready, with its file name, sheets (hidden ones flagged, with their used size), defined names and document properties (title, author, dates, company).
- `onWorkbookLoadError?: (error: unknown) => void`: Called when a workbook cannot be fetched or parsed, or is an old .xls. The viewer shows the error state.
- `onWorkbookUpload?: (file: File) => void`: Called with the File someone opened or dropped, as the viewer starts showing it.
- `labels?: Partial<ExcelViewerLabels>`: Every string, English by default (DEFAULT_EXCEL_VIEWER_LABELS): workbook, grid, zoomIn, zoomOut, zoomLevel, fitWidth, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, gridlines, formulas, darkCells, download, upload, loading, error, errorDescription, unsupported, tooLarge, tooLargeDescription(limit), emptyTitle, emptyDescription, dropHere, nameBox, formulaBar, copy, copied, sheets, sheetTabs, selectAll, columnHeader(column), rowHeader(row), columnMenu(column), sortAscending, sortDescending, clearSort, copyColumn, sorted(column, direction), resizeColumn(column), note, openLink, chart, sum, average, count, cellLabel(address, text).
- `classNames?: Partial<Record<"toolbar" | "formulaBar" | "viewport" | "header" | "cell" | "tabs" | "tab" | "state", string>>`: Extra classes for the toolbar, the formula bar, the scrolling viewport, each heading, each cell, the tab strip, each tab and the loading / empty / error states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `ExcelViewerHandle` (type): What the ref gets: selectSheet(sheet), goTo(ref, { behavior }?) which selects and scrolls to "B12", "A1:D20", "Team!A2", "'Q3 Sales'!B2:C9" or a defined name and returns false when it does not exist, getSelection(), getWorkbook(), clearSort() and getViewportElement().
- `ExcelViewerSelection` (type): What onCellSelect receives: sheet, address, range (1-based startRow, startColumn, endRow, endColumn) and cell (address, row, column, value, text, formula, note, link).
- `ExcelViewerWorkbook` (type): What onWorkbookLoadSuccess receives: fileName, sheets (ExcelViewerSheetInfo[]), definedNames ({ name, ref }[]) and properties (title, creator, lastModifiedBy, created, modified, company).
- `ExcelViewerSheetInfo` (type): A sheet of the workbook: name, index, hidden, rowCount and columnCount (the used range).
- `ExcelViewerCellValue` (type): A raw cell value: string, number (dates are Excel serial numbers), boolean or null.
- `ExcelViewerZoom` (type): A scale or "fit-width".
- `ExcelViewerLabels` (type): The shape of labels: every string the viewer renders.
- `DEFAULT_EXCEL_VIEWER_LABELS` (constant): The English labels. Spread it to translate a few strings.

```tsx
import { ExcelViewer } from "@/components/ui/excel-viewer"

export function SalesReportPreview() {
  return (
    <ExcelViewer
      src="/demo/q3-sales-report.xlsx"
      fileName="Q3 2026 sales report.xlsx"
      height="80dvh"
      onCellSelect={({ address, cell }) => console.log(address, cell.text)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/excel-viewer (Markdown: https://wingo-ui.com/components/excel-viewer.md)

#### File System (`file-system`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-system`

A Finder-style file browser: sidebar, icons, list, columns and gallery views, preview panel and Quick Look on real documents.

Browse folders like in Finder. The sidebar lists favorites, locations (Recents and your roots) and colored tags; drag its edge to resize it, the panel button or Alt+⌘S hides it, and in a narrow frame it opens as a sheet. Four views: Icons (a grid of thumbnails), List (Name, Date modified, Size and Kind columns, click a header to sort, the chevron opens a folder in place), Columns (a column per folder level and a preview of the selected file; on phones one level at a time with a back row) and Gallery (a large live preview with a filmstrip). Every view is virtualized, so a folder of 10,000 files scrolls and sorts instantly. Click to select, Shift+click for a range, ⌘ / Ctrl+click to add, drag across empty space for a rectangle, ⌘A for all; arrows move, Shift+arrows extend, typing a name jumps to it. Double-click or Enter opens: folders open in place, images in the lightbox, other files in Quick Look; Space opens Quick Look on any file (PDF, Word, Excel, CSV, PowerPoint, images, video, audio, Markdown, JSON, code and text) and the arrows move through the folder. Back and forward (⌘[ ⌘]), Backspace or ⌘↑ go up, the path bar at the bottom jumps to any parent. Right-click, Shift+F10, a long press or the ⋯ of a row opens the actions: open, Get info (⌘I), rename (F2, Enter saves, Escape cancels), duplicate (⌘D), move to, copy to, copy and paste (⌘C, ⌘V, ⌥⌘V moves), download, copy path, favorites, tags and delete (⌘⌫, with a confirmation). Drag items onto a folder, a crumb or a sidebar row to move them (hold ⌥ to copy, rest on a folder to spring it open), onto a tag to tag them; drop files from the desktop to upload them. Search (⌘F) looks through the whole tree, accents and case ignored, with a 2 of 14 counter and Enter / Shift+Enter between results. The preview panel shows the selection's details. Menus, the search and dialogs become bottom sheets on phones, where rows are 44px or taller and a tap opens.

npm: @tanstack/react-virtual, lucide-react
Wingo UI dependencies: alert-dialog, audio-player, breadcrumb, button, code-block, command-menu, context-menu, csv-viewer, dialog, docx-viewer, dropdown-menu, excel-viewer, file-types, file-upload, image-lightbox, markdown, pdf-viewer, popover, pptx-viewer, relative-time, sheet, text-match, tones, tooltip, tree-view, ui-config, use-clipboard, use-controllable-state, use-locale, use-media-query, use-shortcut, video-player

Props:
- `items?: FileSystemNode[]`: The tree, nested (children) or flat (parentId), or both. A node is { id, name, kind: "file" | "folder", size?, modified?, created?, mime?, url?, thumbnail?, tags?, locked?, info?, hasChildren? }. Files with a url open in the viewers; the rest show their details.
- `loadChildren?: (folder: FileSystemNode | null) => Promise<FileSystemNode[]>`: Fetches the contents of a folder with hasChildren the first time it is shown (null: the root, when items is empty). Skeleton rows while it runs, a Try again state when it rejects.
- `resolveUrl?: ((file: FileSystemNode) => string | Promise<string>)`: A url for files that have none yet (a presigned link), asked once per file when it is previewed or downloaded.
- `rootLabel?: string` = "": The name of the root in the sidebar, the title and the path bar. Empty uses labels.root (Home).
- `tags?: FileSystemTag[]`: Colored tags ({ id, label, color }) listed in the sidebar; a tag opens everything that has it. Nodes reference them by id.
- `locations?: FileSystemLocation[]`: Rows under Locations: { id, label, folderId, icon? }. The root by default.
- `defaultView?: "icons" | "list" | "columns" | "gallery"` = "icons": The view it opens in. ⌘1 to ⌘4 and the toolbar switch it; view and onViewChange control it.
- `iconSize?: "sm" | "md" | "lg"` = "md": Tiles of the Icons view: 88, 104 or 128px wide.
- `foldersFirst?: boolean` = true: Folders before files in every sort, like Finder's Keep folders on top.
- `searchScope?: "all" | "folder"` = "all": Where search looks: the whole tree, or the open folder and everything below it.
- `confirmDelete?: boolean` = true: Asks before deleting (an alert dialog that waits for onDelete's promise); the action reads Delete… while it does.
- `accept?: string` = "": File types the upload takes (".pdf,image/*"). Other files are listed as not uploaded.
- `maxFileSize?: number` = 0: Bytes per uploaded file; bigger files are listed as not uploaded. 0 means no limit.
- `commandShortcut?: string` = "": Opens the Go to palette (actions, places and every file) from anywhere, in mod+k notation. Empty binds nothing; the palette stays in the ⋯ menu.
- `locale?: string` = "en-US": Locale for sizes, dates, relative times and the sort order of names. Unset, it follows the UIProvider locale, then the browser's.
- `loading?: boolean` = false: Skeleton tiles or rows in place of the open folder, for a tree that is still on its way.
- `error?: ReactNode` = "": Replaces the files with an error state and this text; onRetry adds Try again.
- `showToolbar?: boolean` = true: The toolbar: sidebar, back and forward, the folder name, views, sort, new folder, upload, preview, search and the ⋯ menu.
- `showSidebar?: boolean` = true: Favorites, locations and tags; a sheet below 560px of width.
- `defaultSidebarOpen?: boolean` = true: Whether the sidebar starts open where there is room for it.
- `sidebarWidth?: number` = 200: Starting width of the sidebar in px (160 to 320); drag its edge or use the arrow keys on it, double-click resets it.
- `showRecents?: boolean` = true: A Recents location: the 100 most recently modified files.
- `defaultPreviewOpen?: boolean` = true: The preview panel beside the files (from 900px of width): the selection's thumbnail, details, tags, download and delete. ⇧⌘P toggles it.
- `showPathBar?: boolean` = true: The path bar under the files; every crumb opens that folder and takes dropped items.
- `showStatusBar?: boolean` = true: Item and selection counts, and what is running (Moving, Uploading).
- `showSearch?: boolean` = true: The search field (a button and a sheet when narrow) and ⌘F / Ctrl+F inside the component.
- `height?: number | string` = 640: Height of the frame: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Selected rows and name tags, the open sidebar row and drop targets. Neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color; replaces the tone (text on it turns black or white by its lightness).
- `folderColor?: string` = "#4f9ef5": The folder glyphs, back plate in this color and front plate lighter. Also --file-system-folder on the frame.
- `folderId?: string | null`: The open folder, controlled (null is the root). Pair it with onFolderChange.
- `defaultFolderId?: string | null` = "": The folder it opens in, uncontrolled; null or empty is the root. The playground offers folders of the sample drive.
- `onFolderChange?: (folderId: string | null) => void`: Called when another folder opens (double-click, the path bar, the sidebar, back and forward).
- `selectedIds?: string[]`: The selection, controlled. Pair it with onSelectionChange.
- `defaultSelectedIds?: string[]` = "[]": The selection it starts with, uncontrolled.
- `onSelectionChange?: (ids: string[], nodes: FileSystemNode[]) => void`: Called with the ids and the nodes whenever the selection changes.
- `view?: "icons" | "list" | "columns" | "gallery"`: The view, controlled. Pair it with onViewChange.
- `onViewChange?: (view: FileSystemView) => void`: Called when the toolbar, the ⋯ menu, the palette or ⌘1 to ⌘4 switch the view.
- `sort?: FileSystemSort`: The order, controlled: { key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.
- `defaultSort?: FileSystemSort` = "{ key: \"name\", direction: \"asc\" }": The order it starts with, uncontrolled.
- `onSortChange?: (sort: FileSystemSort) => void`: Called when a list header or the sort menu changes the order.
- `favorites?: string[]`: Ids under Favorites in the sidebar, controlled. Add to favorites / Remove from favorites change it.
- `defaultFavorites?: string[]` = "[]": The favorites it starts with, uncontrolled.
- `onFavoritesChange?: (ids: string[]) => void`: Called with the new list of favorite ids.
- `onOpen?: (file: FileSystemNode, event: FileSystemOpenEvent) => void`: Called when a file is opened (double-click, Enter, a tap). event.preventDefault() keeps the lightbox or Quick Look from opening.
- `onPreviewChange?: (file: FileSystemNode | null) => void`: Called when Quick Look opens a file, moves to another one, or closes (null).
- `onCreateFolder?: ((parentId: string | null, name: string) => void | Promise<unknown>)`: Enables New folder (⇧⌘N): a folder appears with its name selected; Enter calls this. A rejected promise keeps the name and shows why.
- `onRename?: ((node: FileSystemNode, name: string) => void | Promise<unknown>)`: Enables rename: F2, the menu, or a slow second click on the name. Enter saves, Escape cancels; a rejected promise keeps the text and shows its message.
- `onMove?: ((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)`: Enables moving: drag onto a folder, a crumb or a sidebar row, Move to…, or ⌥⌘V after ⌘C. A folder never goes into itself.
- `onCopy?: ((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)`: Enables copying: ⌥ while dragging, Copy to…, Duplicate (⌘D, into the same folder) and ⌘C then ⌘V.
- `onDelete?: ((nodes: FileSystemNode[]) => void | Promise<unknown>)`: Enables Delete (⌘⌫ or Delete), after a confirmation unless confirmDelete is off. Locked nodes are never passed.
- `onUpload?: ((files: File[], targetId: string | null) => void | Promise<unknown>)`: Enables Upload files and dropping files from the desktop onto the view, a folder, a crumb or a sidebar row. accept and maxFileSize filter first.
- `onDownload?: (nodes: FileSystemNode[]) => void`: Replaces the built-in download (a link per file with a url or a resolved url).
- `onTagChange?: ((nodes: FileSystemNode[], tagId: string, add: boolean) => void | Promise<unknown>)`: Enables tagging: the Tags submenu, the tag buttons in Get info, and dropping items onto a sidebar tag.
- `onLoadError?: (error: unknown, folder: FileSystemNode | null) => void`: Called when loadChildren rejects; the folder shows the error with Try again.
- `onRetry?: (() => void | Promise<unknown>)`: Adds Try again to the error state; a returned promise shows it loading.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, request files, sync.
- `now?: Date | number`: Relative times (5 minutes ago) are measured from it. Unset, the clock is read after hydration; demos pin it.
- `ref?: Ref<FileSystemHandle> (a useRef object or an (handle) => void callback)`: open(id or path), goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().
- `labels?: Partial<FileSystemLabels>`: Every string, English by default (DEFAULT_FILE_SYSTEM_LABELS): toolbar, sidebar, menus, states, dialogs and announcements, including items(count, formatted), results(active, total), deleteTitle(count, name), busy and kinds.
- `classNames?: Partial<Record<"toolbar" | "sidebar" | "sidebarItem" | "content" | "item" | "name" | "preview" | "pathBar" | "statusBar" | "quickLook" | "state", string>>`: Extra classes for the toolbar, the sidebar and its rows, the content, every tile or row and its name, the preview panel, the path bar, the status bar, Quick Look and the empty, loading and error states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `FileSystemNode` (type): A file or folder: id, name, kind, parentId or children, hasChildren (lazy), size, modified, created, mime, url, thumbnail, tags (tag ids), locked and info (extra rows for the details, like Owner).
- `FileSystemTag` (type): A sidebar tag: { id, label, color }.
- `FileSystemLocation` (type): A row under Locations: { id, label, folderId (null is the root), icon? }.
- `FileSystemHandle` (type): What the ref gets: open(target) with an id or a path of names ("Documents/Q3 2026/Sales"), which returns false when nothing matches; goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().
- `FileSystemSort` (type): { key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.
- `FileSystemOpenEvent` (type): What onOpen receives as its second argument: preventDefault() and defaultPrevented.
- `FileSystemLabels` (type): The shape of labels: every string the component renders.
- `DEFAULT_FILE_SYSTEM_LABELS` (constant): The English labels. Spread it to translate a few strings.
- `DEFAULT_FILE_SYSTEM_SORT` (constant): The default order: { key: "name", direction: "asc" }.

```tsx
import { FileSystem, type FileSystemNode } from "@/components/ui/file-system"

const items: FileSystemNode[] = [
  {
    id: "documents",
    name: "Documents",
    kind: "folder",
    children: [
      { id: "report", name: "Q3 sales report.xlsx", kind: "file", size: 145926, url: "/files/q3-sales-report.xlsx" },
      { id: "agreement", name: "Service agreement.pdf", kind: "file", size: 7905, url: "/files/service-agreement.pdf" },
    ],
  },
  { id: "readme", name: "README.md", kind: "file", url: "/files/readme.md" },
]

export function Drive() {
  return (
    <FileSystem
      items={items}
      height="80dvh"
      onSelectionChange={(ids) => console.log(ids)}
      onRename={async (node, name) => {
        await fetch(`/api/files/${node.id}`, { method: "PATCH", body: JSON.stringify({ name }) })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/file-system (Markdown: https://wingo-ui.com/components/file-system.md)

#### Image Cropper (`image-cropper`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add image-cropper`

Crop a photo before upload: aspect presets, pinch or wheel zoom, fine and 90° rotation, a thirds grid and a sized JPEG, PNG or WebP export.

Drag the photo with a finger or the mouse to move it under the frame; pinch with two fingers or turn the mouse wheel to zoom, and the image always keeps covering the frame. While you move it a rule-of-thirds grid fades in and a small pill on the stage shows the zoom and the angle; a first-run hint says how to move and zoom and disappears after the first touch. Pick a ratio (Free, 1:1, 4:3, 3:4, 16:9, 9:16) from the segmented switch on wide layouts or the scrolling chip rail on phones, where every chip is a 44px target. In Free mode the frame starts at the photo's own ratio and its four corner brackets resize it with a drag (the frame stays centered). The zoom row has minus and plus buttons that glide the zoom on a short tween around a slider; the rotation row has a 90° left turn that animates, a slider from −45° to 45° with a center mark for straightening, and an optional horizontal flip that turns like a card. Reset puts position, zoom, rotation and flip back. Tab to the crop frame (it shows a white focus ring): arrow keys move the photo by 10px (Shift+arrows by 2px for fine nudges), + and − zoom, r turns 90° left, f flips when flippable, 0 resets and Escape cancels a corner drag. The sliders take arrows, Home and End, and read their value as 150% or −12°; aspect changes, turns, flips and resets are announced. On phones the stage caps at 60% of the screen height and the toolbar stacks. The export crops in a canvas with the rotation and flip, steps down large photos in halves for a sharp result, and can mask a circle with transparent corners.

npm: react-easy-crop, motion, lucide-react
Wingo UI dependencies: button, slider, segmented-control, tooltip, skeleton, file-export, use-controllable-state, use-media-query, motion, tones, ui-config

Props:
- `src: string | Blob | File`: The photo: a URL, a data URL or a File / Blob from an input (its object URL is created and revoked for you). Modern browsers apply EXIF orientation to both the preview and the export.
- `value?: CropValue ({ area: CropArea; zoom: number; rotation: number; aspect: number | null; flipH?: boolean })`: The controlled crop. area is { x, y, width, height } in source pixels of the rotated photo. A value from outside that differs from the last one reported restores that exact crop.
- `defaultValue?: CropValue`: The uncontrolled start, for example a crop saved earlier. Without it the frame starts centered at the largest area of the ratio.
- `onValueChange?: (value: CropValue) => void`: Fires when an interaction ends (a drag, a pinch, the wheel settling, a slider released, a key released, a tween finished), never per frame. Also once when the photo is ready, with the starting crop.
- `onCropChange?: (value: CropValue) => void`: Every frame while the crop moves. Rarely needed; prefer onValueChange.
- `aspect?: number | null`: The controlled ratio (width / height). null is a free crop that starts at the photo's own ratio and has corner handles.
- `defaultAspect?: number | null` = "null": The uncontrolled starting ratio, e.g. 4 / 3 for a listing photo.
- `onAspectChange?: (aspect: number | null) => void`: A ratio was picked from the presets.
- `aspectPresets?: AspectPreset[] | false ({ key: string; label: ReactNode; value: number | null; icon?: ReactNode })` = "DEFAULT_ASPECT_PRESETS": The ratios offered: Free, 1:1, 4:3, 3:4, 16:9, 9:16 by default, each with a small outline of its shape. false hides the picker (a fixed ratio). The default Free label follows labels.free. Exported as DEFAULT_ASPECT_PRESETS, so you can spread it and add your own.
- `cropShape?: "rect" | "round"` = "rect": round draws a circular frame for avatars and logos, forces the ratio to 1 and hides the presets; the export masks the circle.
- `showGrid?: "always" | "interacting" | "never"` = "interacting": The rule-of-thirds grid inside the frame. interacting fades it in while you drag, pinch, zoom or rotate.
- `minZoom?: number` = 1: The smallest zoom. At 1 the photo just fits the stage. With a resized free frame the zoom also stops where the photo would stop covering it.
- `maxZoom?: number` = 4: The largest zoom for the slider, the buttons, the wheel and pinch.
- `zoomStep?: number` = 0.1: The slider step and the + / − key step. The zoom buttons move five steps with a short glide.
- `rotatable?: boolean` = true: Shows the rotation row: a 90° left turn and a fine slider from −45° to 45° with a center mark.
- `flippable?: boolean` = false: Adds a horizontal flip button (and the f key). The export mirrors the photo too.
- `restrictPosition?: boolean` = true: Keeps the photo covering the whole frame. Off, the photo can move past the frame and the uncovered part exports as the background.
- `objectFit?: "contain" | "cover"` = "contain": How the photo sits in the stage at zoom 1: contain shows all of it, cover fills the stage.
- `height?: number` = 360: The stage height in px. Phones cap it at 60dvh so the toolbar stays on screen.
- `toolbar?: boolean` = true: The controls under the stage. Off, the photo still moves, pinches, zooms with the wheel and answers the keys; drive the rest through setApi.
- `export?: CropExportOptions ({ type?: ImageType; quality?: number; maxSize?: number; width?: number; height?: number; background?: string; round?: boolean })` = "{ type: \"image/jpeg\", quality: 0.9, maxSize: 2048 }": Defaults for toBlob / toCanvas. maxSize caps the longest side (never upscales), width / height set an exact size, round masks a circle (on by default for a round crop), background fills behind (JPEG gets white). The same crop runs without the component through the exported cropImage(source, value, options) => Promise<Blob> (avatar-upload uses it): rotation-aware, flip, two-step downscaling for large photos, a round mask with transparent PNG / WebP corners; browser only, for handlers.
- `overlayColor?: string` = "rgba(0, 0, 0, 0.55)": The dim outside the frame. Any CSS color.
- `size?: "sm" | "md"` = "md": The toolbar controls: sm 32px buttons and slim sliders, md 40px (44px on touch).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The slider fills, the selected ratio chip and the segmented thumb.
- `color?: string` = "": Any CSS color; replaces the tone for the sliders and the selected ratio.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": The stage corners: 0 / 12 / 16 / 24px.
- `disabled?: boolean` = false: Dims the stage and the toolbar and ignores every gesture and key.
- `setApi?: (api: ImageCropperApi) => void`: Receives { toBlob(options?), toCanvas(options?), reset(), rotateBy(degrees), zoomTo(zoom) } after mount. toBlob rejects with labels.corsError when a remote photo has no CORS headers (the preview still works).
- `onError?: (error: Error) => void`: The photo failed to load, or an export failed. Load errors also show a retry on the stage for URLs.
- `labels?: Partial<ImageCropperLabels>` = "DEFAULT_IMAGE_CROPPER_LABELS": Every string: aspect, free, zoom, zoomIn, zoomOut, rotate, rotateLeft, flip, reset, area (the frame's name for screen readers), loading, error, retry, hint, touchHint, corsError, exportError, and the announcements aspectChanged(label), rotated(degrees, formatted), flipped, resetDone. English defaults in DEFAULT_IMAGE_CROPPER_LABELS.
- `classNames?: Partial<Record<"stage" | "area" | "grid" | "handle" | "toolbar" | "aspects" | "zoom" | "rotate" | "reset" | "pill", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { ImageCropper, type ImageCropperApi } from "@/components/ui/image-cropper"

export function ListingPhoto({ onSave }: { onSave: (file: Blob) => void }) {
  const [api, setApi] = useState<ImageCropperApi | null>(null)
  const [saving, setSaving] = useState(false)

  const crop = async () => {
    if (!api) return
    setSaving(true)
    try {
      onSave(await api.toBlob({ type: "image/jpeg", quality: 0.9, maxSize: 1600 }))
    } finally {
      setSaving(false)
    }
  }

  return (
    <div className="flex max-w-xl flex-col gap-4">
      <ImageCropper
        src="/demo/apartment.jpg"
        defaultAspect={4 / 3}
        setApi={setApi}
        labels={{
          aspect: "Ratio",
          hint: "Drag to move, scroll to zoom",
          touchHint: "Drag to move, pinch to zoom",
        }}
      />
      <Button loading={saving} onClick={crop}>
        Crop
      </Button>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/image-cropper (Markdown: https://wingo-ui.com/components/image-cropper.md)

#### Image Lightbox (`image-lightbox`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add image-lightbox`

A full-screen photo viewer that zooms out of its thumbnail: swipe between images, pinch and double-tap to zoom, swipe down to close.

Tap a thumbnail and the photo grows out of it into a black full-screen viewer (the thumbnail's crop opens up into the whole image); closing flies it back into the thumbnail of the photo you are on, or fades when that thumbnail is off screen. Swipe or drag sideways to move between photos (embla's physics, one photo per swipe); on a phone pull a photo down and it shrinks while the page shows through, then let go past a quarter of the screen or flick to close, or it springs back. Pinch to zoom around your fingers (it resists past 1x and the max, then settles), double-tap or double-click to zoom to the tapped point and again to go back, drag to pan a zoomed photo with momentum and a soft edge, and use ctrl or cmd + wheel (a trackpad pinch) to zoom at the cursor while a plain wheel pans; a horizontal trackpad swipe pages. While zoomed, swipes pan instead of paging and swipe-down is off; changing photo resets the zoom. On desktop the toolbar (counter, zoom level pill that resets on click, zoom out / in, download, share, close), the side arrows, the caption and the thumbnail strip fade after the idle delay and come back on any mouse move or key; on a phone a single tap toggles them, like Photos. Keys: Left / Right previous / next, Home / End first / last, + or = zoom in, - zoom out, 0 reset, Escape resets a zoom first and closes on the second press. Focus stays trapped in the viewer and returns to the thumbnail that opened it; the counter is a polite live region and the caption describes the dialog. Images load only near the current one, show a spinner (over the thumbnail as a placeholder) until ready and an icon when broken. Under reduced motion it fades instead of flying, and double-tap zoom jumps.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, motion, lucide-react
Wingo UI dependencies: carousel, button, spinner, use-media-query, use-shortcut, use-controllable-state, motion, ui-config

Props:
- `images: LightboxImage[]`: { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail?, downloadName? }. width and height let the frame take the photo's shape before it loads (and let it fly from its thumbnail); thumbnail is the small file for the grid, the strip and the placeholder. An empty array never opens.
- `open?: boolean`: Controlled visibility. Pair with onOpenChange.
- `defaultOpen?: boolean` = false: Opens on mount, uncontrolled. The playground opens the gallery at the first photo.
- `onOpenChange?: (open: boolean) => void`: Fires on open and on close (close button, Escape, swipe down).
- `index?: number`: The photo shown, controlled; out of range values clamp. Pair with onIndexChange to sync an outside strip.
- `defaultIndex?: number` = 0: The photo shown first, uncontrolled. The playground opens there with defaultOpen.
- `onIndexChange?: (index: number) => void`: Fires when the photo changes by swipe, arrow, key or thumbnail.
- `loop?: boolean` = false: Wraps from the last photo to the first (embla turns it off with too few photos).
- `zoom?: boolean` = true: Pinch, double tap / double click, ctrl or cmd + wheel (trackpad pinch), plain wheel to pan while zoomed, the +/- and 0 keys, and the zoom buttons (fine pointers).
- `maxZoom?: number` = 4: The largest scale, relative to the fitted photo. A pinch past it resists and settles back.
- `doubleTapZoom?: number` = 2.5: The scale a double tap or double click zooms to, centered on the tapped point (capped at maxZoom).
- `swipeToClose?: boolean` = true: Touch and pen: pull the photo down (while not zoomed) to close. It shrinks toward 0.85 and the black fades as it follows the finger; past a quarter of the screen or a quick flick it closes, else it springs back.
- `showThumbnails?: boolean` = true: A synced strip under the photo from 640px up (phones have the counter instead).
- `showCaptions?: boolean` = true: Each photo's caption at the bottom, on a gradient. It also describes the dialog for screen readers.
- `showCounter?: boolean` = true: The "3 / 8" counter at the top start, a polite live region.
- `download?: boolean` = false: A download button: a link with the download attribute (downloadName per image). Cross-origin files open instead.
- `share?: boolean` = false: A share button that calls navigator.share with the photo's url; hidden where the browser has no share sheet.
- `hideControlsDelay?: number` = 3000: Desktop: the controls and the cursor fade after this many ms without a mouse move or key (never while a control is hovered or focused). 0 keeps them. Phones ignore it: a tap toggles them.
- `toolbar?: ReactNode`: Extra buttons at the start of the toolbar's action group, e.g. "Set as cover". Style them white: variant="ghost" with text-white hover:bg-white/10.
- `trigger?: ReactNode`: An element that opens the viewer at the current index (a Radix Dialog.Trigger with asChild); the photo zooms out of it.
- `getOrigin?: (index: number) => (Element | null | undefined)`: The element each photo flies out of and back into, usually its thumbnail (its first img gives the shape, its border radius the corners). Without one, or when it is off screen, the viewer fades and grows like a dialog. LightboxGallery wires it up.
- `container?: HTMLElement | null`: Portal target; document.body by default.
- `labels?: Partial<ImageLightboxLabels>`: Every string: dialog ("Image viewer", the hidden title), close, previous, next, zoomIn, zoomOut, resetZoom, download, share, counter(i, n) ("3 / 8"), loading, error, slide(i, n) ("3 of 8"), goTo(i), and for the gallery openImage(i, n, alt) and moreImages(n). English by default, DEFAULT_IMAGE_LIGHTBOX_LABELS.
- `classNames?: Partial<Record<"overlay" | "content" | "toolbar" | "counter" | "button" | "stage" | "slide" | "zoom" | "image" | "spinner" | "error" | "footer" | "caption" | "thumbnails" | "thumbnail" | "previous" | "next", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the full-screen content. It carries the dark class on purpose: a photo viewer is black with white controls in both themes, like iOS Photos.

Parts:
- `LightboxGallery` (component): A grid of thumbnail buttons that opens the viewer and zooms out of the tapped tile. Defaults: columns { base: 2, sm: 3, md: 4 }, gap "md" (8px), aspect "square", radius "md" (12px; sm 8px, lg and full 16px), maxVisible 0 (all; otherwise the last tile says "+N"), featured false (the first tile spans 2 x 2). Broken thumbnails show an icon. With children it renders them instead of the grid, for custom triggers with useLightbox. Takes every ImageLightbox prop. Props: ImageLightboxProps & { columns?: number | { base?, sm?, md?, lg? }; gap?: "none" | "sm" | "md" | "lg"; aspect?: "square" | "4/3" | "16/10" | "auto"; radius?: "none" | "sm" | "md" | "lg" | "full"; maxVisible?: number; featured?: boolean; renderThumbnail?: (image, index, { hiddenCount }) => ReactNode; children?: ReactNode }.
- `useLightbox` (hook): Custom triggers inside a LightboxGallery: open(2, event.currentTarget) zooms photo 3 out of the pressed element and returns focus to it. Signature: () => { open(index: number, origin?: Element | null): void; close(): void; index: number; isOpen: boolean }.
- `DEFAULT_IMAGE_LIGHTBOX_LABELS` (constant): The English strings, to spread and override. Type: ImageLightboxLabels.

```tsx
import { useState } from "react"
import { ImageLightbox, LightboxGallery, type LightboxImage } from "@/components/ui/image-lightbox"

const photos: LightboxImage[] = [
  { src: "/demo/apartment.jpg", alt: "Bright living room", caption: "Bright living room, 260 sq ft", width: 960, height: 600 },
  { src: "/demo/sofa.jpg", alt: "Velvet sofa", caption: "Velvet sofa, stays with the apartment", width: 960, height: 600 },
  { src: "/demo/laptop.jpg", alt: "Desk corner", caption: "Desk corner by the window", width: 960, height: 600 },
]

const labels = { dialog: "Photo gallery", download: "Save photo" }

// a grid of tiles; each photo zooms out of the tile you tap and back into it
export function ListingPhotos() {
  return <LightboxGallery images={photos} columns={{ base: 2, md: 3 }} download labels={labels} />
}

// one cover photo as the trigger, the index kept outside
export function CoverPhoto() {
  const [index, setIndex] = useState(0)
  return (
    <ImageLightbox
      images={photos}
      index={index}
      onIndexChange={setIndex}
      labels={labels}
      trigger={
        <button type="button" className="block overflow-hidden rounded-2xl">
          <img src={photos[index].src} alt={photos[index].alt} className="aspect-[16/10] w-full object-cover" />
        </button>
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/image-lightbox (Markdown: https://wingo-ui.com/components/image-lightbox.md)

#### Location Map (`location-map`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add location-map`

A real map to pick or show a place: a pin you drag or drop, an optional radius with a towns count, offline search and a static fallback.

With a mouse the map is live in place: drag to pan, double-click or use the round + and − buttons to zoom, and the wheel zooms only after you clicked into the map, so scrolling the page never gets stuck on it. Click anywhere to drop the pin there (it falls in with a small squash and a ripple) or drag the pin itself; it lifts while you hold it and the circle follows. Type in the search field to find a town, an area or a county offline (an online geocoder finds street addresses); arrows move through the results, Enter picks one and the map flies there. The locate button asks for your position and moves the pin; a refusal is shown under the map. With a radius set, the slider under the map resizes the circle live, shows how many towns fall inside, and fits the view to the circle when you let go. On a phone the inline map does not steal the page scroll: tap it and a full-height sheet opens with the search on top, a fully interactive map (pinch, drag, tap to place) and Done at the bottom; closing the sheet any other way discards the changes. Keyboard: Tab reaches the search, the map (arrows pan, + and − zoom), the pin (arrows move it 10px, Shift+arrows 50px, committed a moment after you stop), the map buttons and the slider. Screen readers get the map as an application described by the place name and coordinates under it, and hear every move. Without network or before the map loads, a drawn static card shows the pin, the place and the coordinates.

npm: leaflet, motion, lucide-react
Wingo UI dependencies: button, drawer, listbox, search-input, skeleton, slider, tooltip, use-controllable-state, use-debounce, use-locale, use-media-query, motion, number-format, ro-locations, tones, ui-config

Props:
- `value?: GeoPoint | null`: The pin, controlled: { lat, lng }. null shows no pin until one is placed.
- `defaultValue?: GeoPoint | null` = "null": The pin while uncontrolled. The demo starts at Str. Memorandumului 28, Cluj-Napoca.
- `onValueChange?: (value: GeoPoint | null) => void`: After a drag ends, a click places the pin, a search result or the locate button moves it, or the keyboard rests.
- `radius?: number | null`: The radius in km, controlled. null or 0 hides the circle and the slider.
- `defaultRadius?: number | null` = 0: The radius in km while uncontrolled; 0 (or null) means no circle and no slider.
- `onRadiusChange?: (radius: number | null) => void`: Every step of the slider.
- `radiusRange?: LocationMapRange ([min, max] in km)` = "[1, 50]": The slider's bounds in km.
- `radiusStep?: number` = 1: The slider's step in km.
- `showRadiusSlider?: boolean` = true: The slider row under the map, while a radius is set and the map is not read-only.
- `showTownsInRadius?: boolean` = true: Adds "14 towns in range" to the radius row, counted from ro-locations (0 outside Romania).
- `center?: GeoPoint`: The first view, and a new view when it changes. Defaults to the value, then Cluj-Napoca (46.7712, 23.6236).
- `zoom?: number`: The zoom level, controlled (1 to 19). The inline map and the sheet share it.
- `defaultZoom?: number` = 13: The zoom level while uncontrolled: 13 shows a neighbourhood, 10 a county, 16 a street.
- `onZoomChange?: (zoom: number) => void`: After every zoom, from the buttons, the wheel, a pinch or a flight.
- `draggable?: boolean` = true: The pin can be dragged, and moved with the arrow keys once focused.
- `clickToPlace?: boolean` = true: A click or a tap on the map moves the pin there.
- `readOnly?: boolean` = false: Shows the pin and the circle only: no search, no slider, no locate, the pin stays put. The map still pans and zooms.
- `searchable?: boolean` = true: The search field above the map.
- `geocoder?: (query: string, options: { signal: AbortSignal; locale: string }) => Promise<GeocodeResult[]>` = "roLocationsGeocoder": What the search asks. roLocationsGeocoder finds Romanian towns, areas and counties offline; nominatimGeocoder({ email }) finds street addresses through OpenStreetMap (one request a second, debounced 700ms). The previous request is aborted.
- `reverseGeocoder?: (point: GeoPoint, options: { signal: AbortSignal; locale: string }) => Promise<GeocodeResult | null>`: Names the pin after it moves ("Str. Memorandumului 28, Cluj-Napoca"), 500ms after it rests. Without it the nearest town from ro-locations names it. nominatimReverseGeocoder({ email }) is ready to use.
- `locate?: boolean` = true: The my-location button. Hidden where the browser has no geolocation; a refusal is shown and announced.
- `height?: number` = 320: The map's height in px. Phones show at most 220px inline, since the full map is a tap away.
- `tileUrl?: string` = "https://tile.openstreetmap.org/{z}/{x}/{y}.png": The raster tiles. OpenStreetMap's public tiles are for light use; a production app should point this at its own tile provider.
- `attribution?: string` = "© OpenStreetMap": The credit in the corner that the tile provider requires. Linked to the OpenStreetMap copyright page for OSM tiles.
- `darkTiles?: "filter" | "url" | "none"` = "filter": Dark mode tiles. filter inverts the light tiles with a hue rotation (no second provider needed), url swaps to darkTileUrl, none keeps light tiles in both themes.
- `darkTileUrl?: string` = "": The tiles for dark mode when darkTiles is "url", e.g. a dark raster style of your provider.
- `lazy?: boolean` = true: Loads Leaflet (42 KB) only once the map is within 200px of the viewport. Until then the static card shows.
- `staticOnly?: boolean` = false: Never loads the map: the drawn static card with the pin, the place and the coordinates. For emails, prints, thumbnails and long lists.
- `interactive?: "auto" | "always" | "expand"` = "auto": auto: live in place with a mouse, tap to open a full-height sheet on touch (the page keeps scrolling over the inline map). always: live in place everywhere. expand: a click or tap always opens the sheet (a dialog on desktop).
- `scrollWheelZoom?: "focus" | "always" | "never"` = "focus": focus: the wheel zooms only after the map was clicked or focused, and stops when the pointer leaves. always and never do what they say.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The pin, the circle, the slider and the sheet's Done button.
- `color?: string` = "": Any CSS color; replaces the tone for the pin, the circle and the slider.
- `locale?: string` = "": Coordinates, distances and the geocoder's language. Empty uses the app's locale, then the browser's.
- `setApi?: (api: LocationMapApi) => void`: Called once with { flyTo(point, zoom?), fitRadius(), locate(): Promise<GeoPoint | null>, getMap(): L.Map | null }. The calls go to the sheet's map while it is open.
- `labels?: Partial<LocationMapLabels>`: Every string, English by default (DEFAULT_LOCATION_MAP_LABELS): search, noResults, locate, locating, locateDenied, locateFailed, zoomIn, zoomOut, expand, done, radius(km, formatted), radiusLabel, towns(count, formatted), pin, map, sheetTitle, offline, placePin, tapToOpen, near(town, distance), coordinates(lat, lng), moved(place).
- `classNames?: Partial<Record<"search" | "map" | "canvas" | "controls" | "control" | "attribution" | "hint" | "radius" | "slider" | "radiusLabel" | "summary" | "error" | "static" | "sheet", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `StaticMap` (component): The fallback card alone, no map library and no network: a drawn neighbourhood with the pin, an optional radius ring and a chip with the place and coordinates. Props: { value?: GeoPoint | null; place?: ReactNode; radius?: number | null; offline?: boolean; height?: number; tone?: Tone; color?: string; locale?: string; labels?: Partial<LocationMapLabels> }.
- `roLocationsGeocoder` (constant): The offline default: Romanian cities, areas and counties from ro-locations, diacritics ignored. Type: Geocoder.
- `nominatimGeocoder` (function): OpenStreetMap address search. countryCodes defaults to "ro", endpoint to nominatim.openstreetmap.org; requests wait for their turn so there is at most one a second. Signature: (options?: { email?: string; countryCodes?: string; endpoint?: string; limit?: number }) => Geocoder.
- `nominatimReverseGeocoder` (function): The street and town under a point, "Strada Memorandumului 28, Cluj-Napoca", in the map's locale. Signature: (options?: { email?: string; endpoint?: string }) => ReverseGeocoder.

```tsx
import { useState } from "react"
import { LocationMap, type GeoPoint } from "@/components/ui/location-map"

export function ListingLocation() {
  const [point, setPoint] = useState<GeoPoint | null>({ lat: 46.77, lng: 23.5857 })
  const [radius, setRadius] = useState<number | null>(5)
  return (
    <LocationMap
      value={point}
      onValueChange={setPoint}
      radius={radius}
      onRadiusChange={setRadius}
      locale="en-US"
      labels={{
        search: "Search a town",
        towns: (count, formatted) => (count === 1 ? "1 town nearby" : `${formatted} towns nearby`),
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/location-map (Markdown: https://wingo-ui.com/components/location-map.md)

#### PDF Viewer (`pdf-viewer`)

component · Pro · v1.1.0 · install: `npx wingo-ui@latest add pdf-viewer`

A PDF viewer on PDFium: sharp pages, search, thumbnails, rotation, and text highlights with notes that export as real PDF annotations.

Scroll through the pages; only the ones on screen render, and zoomed-in pages paint in sharp tiles. Type a page number in the toolbar (Enter jumps, Up and Down step, Escape cancels). Zoom with - and +, or pick Automatic, Fit page, Fit width or a percentage from the zoom menu. Search opens from the toolbar or with Ctrl+F / ⌘F while focus is inside the viewer: hits are highlighted on every page, the counter reads 2 of 5, and Enter / Shift+Enter or the arrows step through them. Drag across text to select it and press Ctrl+C / ⌘C to copy; on a phone a swipe scrolls, and a long press selects the word under the finger and dragging extends it word by word. With highlighting on, a bar opens beside the selection (pinned to the bottom, or the top when the selection is down there, on a phone) with five colors, underline, strikethrough, Add note and Copy; Ctrl+Shift+H / ⇧⌘H highlights the selection, or toggles the Highlighter, in which whatever you select is marked as soon as you let go (Escape turns it off). Clicking a highlight opens its details (a bottom sheet on phones): change the color or style, add or edit the note (Ctrl+Enter / ⌘Enter saves, Escape closes without saving and focus returns), copy the text or delete it. Ctrl+Z / ⌘Z and Ctrl+Shift+Z / ⇧⌘Z undo and redo. The Highlights panel lists every highlight with its page, text, note, author and date, filtered by color; a pick jumps to it and opens its details, Up and Down move through the list and Delete removes one. It sits beside the pages from 900px of width and slides over them below. Highlights also show on the thumbnails and follow zoom and rotation. The sidebar shows page thumbnails: click to jump, Shift+click for a range, Ctrl/⌘+click to add a page; in the list Up / Down move, Home / End jump, Shift extends and Space toggles. The rotate buttons turn the selected pages (or the current one) and the reading position holds. The ⋯ menu holds undo and redo, downloads the file (with your rotations, or with your highlights written in as annotations) and opens another PDF, which you can also drop onto the viewer. Below 520px of width the sidebar starts closed and slides over the pages; below 600px the rotate buttons move into the ⋯ menu, and below 440px the Highlights toggle does too.

npm: @embedpdf/core, @embedpdf/engines, @embedpdf/models, @embedpdf/plugin-document-manager, @embedpdf/plugin-interaction-manager, @embedpdf/plugin-render, @embedpdf/plugin-rotate, @embedpdf/plugin-scroll, @embedpdf/plugin-search, @embedpdf/plugin-selection, @embedpdf/plugin-thumbnail, @embedpdf/plugin-tiling, @embedpdf/plugin-viewport, @embedpdf/plugin-zoom, pdf-lib, lucide-react
Wingo UI dependencies: button, dropdown-menu, popover, tooltip, use-controllable-state, use-media-query, use-shortcut, motion, ui-config

Props:
- `src?: string` = "/demo/service-agreement.pdf": URL of the PDF: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-PDF state. The playground value is the sample contract.
- `fileName?: string` = "": Name used for downloads. Falls back to the last part of src; an uploaded file keeps its own name.
- `defaultZoom?: number | "fit-page" | "fit-width" | "automatic"` = "automatic": The zoom the document opens at: a scale (1 is 100%) or a fit mode. Automatic fits the width up to 100%, so a page never opens blown up on a large screen or cut off on a phone.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.4)": Fill of every search hit. Any CSS color; keep it translucent so the text stays readable.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.55)": Fill of the current search hit.
- `selectionColor?: string` = "rgba(59, 130, 246, 0.18)": Fill drawn over selected text.
- `showToolbar?: boolean` = true: The toolbar with page, zoom, search and file controls. Off leaves the bare pages, for previews you drive yourself.
- `showThumbnails?: boolean` = true: The pages sidebar and its toggle.
- `defaultSidebarOpen?: boolean` = true: Opens with the pages sidebar showing beside the pages. A viewer narrower than 520px (a phone) starts closed, since there the sidebar covers the page. Use sidebarOpen and onSidebarOpenChange to control it.
- `showSearch?: boolean` = true: The search button, and Ctrl+F / ⌘F inside the viewer.
- `showRotateControls?: boolean` = true: The rotate buttons (in the ⋯ menu when the viewer is narrow).
- `showDownload?: boolean` = true: Download in the ⋯ menu. Pages you rotated are saved rotated.
- `showUpload?: boolean` = true: Open a PDF in the ⋯ menu and dropping a PDF onto the viewer. The file opens locally; onPdfUpload hands it to you.
- `highlighting?: boolean` = true: Lets readers mark text: the bar beside a selection, the Highlighter, Ctrl+Shift+H / ⇧⌘H, editing in the details popover and undo / redo. false makes the viewer read-only: highlights you pass (or that the file carries) still show and open with their notes.
- `author?: string` = "": Signed on new highlights, shown in the panel and written into the exported PDF as the annotation author.
- `defaultHighlightColor?: string` = "#FDE047": The pen color the Highlighter and Ctrl+Shift+H / ⇧⌘H start with; the first of highlightColors when unset. Any CSS color; hex is written into the PDF exactly.
- `showHighlightsPanel?: boolean` = true: The Highlights panel and its toolbar toggle (shown once highlighting is on or there are highlights).
- `defaultHighlightsPanelOpen?: boolean` = false: Opens with the Highlights panel showing. Use highlightsPanelOpen and onHighlightsPanelOpenChange to control it.
- `defaultHighlighterMode?: boolean` = false: Starts in Highlighter mode: selected text is marked as soon as the pointer is released. Use highlighterMode and onHighlighterModeChange to control it.
- `importHighlights?: boolean` = true: Highlight, underline, strikeout and squiggly annotations already in the file load as highlights (squiggly becomes underline). They are replaced by the list on export, so one deleted here is gone from the file too.
- `highlightShortcut?: string` = "shift+mod+h": Highlights the selection, or toggles the Highlighter, while focus is inside the viewer. mod is ⌘ on Apple devices and Ctrl elsewhere; empty turns it off.
- `locale?: string` = "": Locale of the dates in the Highlights panel and details. Empty uses the UIProvider locale, then the browser's.
- `height?: number | string` = 640: Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `sidebarOpen?: boolean`: Controls the pages sidebar. Inline from 520px of viewer width, an overlay below it.
- `onSidebarOpenChange?: (open: boolean) => void`: Called when the sidebar opens or closes.
- `highlights?: PdfViewerHighlight[]`: Controlled highlights: { id, page, rects, text, color, type?, note?, author?, createdAt, updatedAt? }, with rects in PDF points from the top-left of the unrotated page. Serializable: store it as JSON and pass it back. Pair it with onHighlightsChange.
- `defaultHighlights?: PdfViewerHighlight[]`: The starting highlights while uncontrolled. Opening another file starts from an empty list.
- `onHighlightsChange?: (highlights: PdfViewerHighlight[]) => void`: Called with the whole list after every add, change, removal, undo, redo and import.
- `onHighlightAdd?: (highlight: PdfViewerHighlight) => void`: Called once per highlight a reader (or ref.addHighlight) adds, and when undo or redo brings one back. Not called for highlights imported from the file.
- `onHighlightChange?: (highlight: PdfViewerHighlight, previous: PdfViewerHighlight) => void`: Called when a highlight's color, style or note changes.
- `onHighlightRemove?: (highlight: PdfViewerHighlight) => void`: Called when a highlight is deleted or an undo takes it away.
- `highlightColors?: PdfViewerHighlightColor[]` = "DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS": The colors of the selection bar, the details and the panel filter, as { value, label }: yellow, green, blue, pink and orange by default.
- `highlightsPanelOpen?: boolean`: Controls the Highlights panel.
- `onHighlightsPanelOpenChange?: (open: boolean) => void`: Called when the Highlights panel opens or closes.
- `highlighterMode?: boolean`: Controls the Highlighter mode.
- `onHighlighterModeChange?: (on: boolean) => void`: Called when the Highlighter turns on or off.
- `zoomLevels?: number[]` = "[0.1, 0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]": Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, sign, approve.
- `wasmUrl?: string` = "https://cdn.jsdelivr.net/npm/@embedpdf/pdfium@2.15.1/dist/pdfium.wasm": Where the PDFium binary (about 4 MB, cached) is loaded from. Defaults to jsDelivr; copy node_modules/@embedpdf/pdfium/dist/pdfium.wasm into public/ and point here for a strict CSP or offline apps. Your CSP needs 'wasm-unsafe-eval' in script-src either way.
- `ref?: Ref<PdfViewerHandle> (a useRef object or an (handle) => void callback)`: scrollToPage(page), scrollToPageArea(page, { top, left }) in percent of the page, getViewportElement(), and for highlights addHighlight(input?) (without input it highlights the selection), updateHighlight(id, patch), removeHighlight(id), scrollToHighlight(id), getHighlights(), exportPdf(), undo() and redo().
- `renderPageOverlay?: (props: PdfViewerPageOverlayProps) => ReactNode`: Draws on top of every page: citations, bounding boxes, comments, signature fields. Gets the page number, its size at the current zoom, the scale and the rotation; it rotates with the page, so boxes in percent always line up.
- `pageClassName?: (pageNumber: number) => (string | undefined)`: Extra classes per page, e.g. a ring around the page a citation points to.
- `onActivePageChange?: (pageNumber: number) => void`: Called with the page in view as you scroll or jump.
- `onDocumentLoadSuccess?: (numPages: number) => void`: Called when a document is ready, with its page count.
- `onDocumentLoadError?: (error: unknown) => void`: Called when a document cannot be fetched or parsed. The viewer shows the error state.
- `onPdfUpload?: (file: File) => void`: Called with the File someone opened or dropped, after the viewer shows it.
- `onPagePointerDown?: (event: PointerEvent<HTMLDivElement>, pageNumber: number) => void`: Pointer down on a page, for drawing boxes or placing fields. Gets the event and the page number.
- `onPagePointerMove?: (event: PointerEvent<HTMLDivElement>, pageNumber: number) => void`: Pointer move over a page.
- `onPagePointerUp?: (event: PointerEvent<HTMLDivElement>, pageNumber: number) => void`: Pointer up on a page.
- `onPagePointerCancel?: (event: PointerEvent<HTMLDivElement>, pageNumber: number) => void`: Pointer cancel on a page (a touch turned into a scroll).
- `labels?: Partial<PdfViewerLabels>`: Every string, English by default (DEFAULT_PDF_VIEWER_LABELS): page, of, pageNumber, pagesSidebar, pages, pageLabel(page), rotateLeft, rotateRight, zoomIn, zoomOut, zoomLevel, fitPage, fitWidth, automatic, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, download, upload, document, loading, error, engineError, emptyTitle, emptyDescription, dropHere, and for highlights highlighter, highlightStyle, highlight, underline, strikeout, highlightWith(color), addNote, note, notePlaceholder, saveNote, cancel, copyText, copied, deleteHighlight, highlights, closeHighlights, allColors, filterByColor, noHighlights, noHighlightsDescription, noHighlightsInColor, selectionActions, highlightDetails, highlightLabel(page, text), highlightAdded(page), highlightRemoved, highlightUpdated, undo, redo, undone, redone, nothingToUndo, downloadWithHighlights, highlighterOn, highlighterOff.
- `classNames?: Partial<Record<"toolbar" | "sidebar" | "thumbnail" | "viewport" | "page" | "state" | "highlight" | "selectionBar" | "highlightsPanel", string>>`: Extra classes for the toolbar, the sidebar, each thumbnail, the scrolling viewport, each page, the loading / empty / error states, each highlight box on a page, the selection bar and the Highlights panel.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `PdfViewerHandle` (type): What the ref gets: scrollToPage(pageNumber, options?), scrollToPageArea(pageNumber, { top, left?, width?, height? }, options?) with the area in percent of the page, getViewportElement(), addHighlight(input?) → Promise<PdfViewerHighlight[]>, updateHighlight(id, patch), removeHighlight(id), scrollToHighlight(id, options?), getHighlights(), exportPdf() → Promise<Blob> (the PDF with every highlight as a /Highlight, /Underline or /StrikeOut annotation, rotations applied), undo() and redo().
- `PdfViewerHighlight` (type): One marked passage on one page: id, page (1-based), rects ({ x, y, width, height } in PDF points from the top-left of the unrotated page, one per line), text, color, type ('highlight' | 'underline' | 'strikeout'), note, author, createdAt and updatedAt (ISO). Plain JSON.
- `PdfViewerHighlightInput` (type): What addHighlight takes: a PdfViewerHighlight whose id and createdAt are optional.
- `PdfViewerHighlightType` (type): "highlight" | "underline" | "strikeout".
- `PdfViewerHighlightRect` (type): { x, y, width, height } in PDF points from the top-left of the unrotated page.
- `PdfViewerHighlightColor` (type): A color of the palette: { value, label }.
- `DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS` (constant): The default palette: Yellow #FDE047, Green #86EFAC, Blue #93C5FD, Pink #F9A8D4 and Orange #FDBA74.
- `PdfViewerPageOverlayProps` (type): What renderPageOverlay receives: pageNumber, pageWidth and pageHeight at the current zoom, scale, and rotation in degrees.
- `PdfViewerZoom` (type): A scale or "fit-page" | "fit-width" | "automatic".
- `PdfViewerLabels` (type): The shape of labels: every string the viewer renders.
- `DEFAULT_PDF_VIEWER_LABELS` (constant): The English labels. Spread it to translate a few strings.
- `PDFIUM_WASM_URL` (constant): The default wasmUrl: PDFium 2.15.1 on jsDelivr.

```tsx
import { useState } from "react"
import { PdfViewer, type PdfViewerHighlight } from "@/components/ui/pdf-viewer"

export function ContractReview() {
  const [highlights, setHighlights] = useState<PdfViewerHighlight[]>([])
  return (
    <PdfViewer
      src="/demo/service-agreement.pdf"
      fileName="Master Services Agreement"
      height="80dvh"
      author="Emma Carter"
      highlights={highlights}
      onHighlightsChange={setHighlights}
      onActivePageChange={(page) => console.log("reading page", page)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/pdf-viewer (Markdown: https://wingo-ui.com/components/pdf-viewer.md)

#### PowerPoint Viewer (`pptx-viewer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add pptx-viewer`

A PowerPoint (.pptx) viewer with real slides, thumbnails, zoom, search, speaker notes, a single slide view and a fullscreen presenter.

Slides render in the browser from the .pptx itself, with nothing uploaded: layouts, masters and the theme's colors and fonts, backgrounds (solid, gradient, picture), shapes with fills, outlines, arrows, rotation and flips, grouped shapes, text with bullets, numbering, spacing and shrink-to-fit, cropped pictures, tables with their styles, bar, line, area and pie charts from the values saved in the file, and SmartArt from its saved drawing; video, audio and embedded objects show an honest labeled placeholder. Text stays real text you can select and search. Scroll through the slides as a column, or switch to one slide at a time (Single slide); only the slides near the view are drawn, so long decks stay light. The toolbar moves between slides (‹ ›, or type a number in the slide field: Enter jumps, Up / Down step, Escape cancels), zooms (- / + or a percentage, Automatic, Fit page, Fit width), searches, shows the speaker notes under the slide, starts the presenter and downloads the file; below 720px of width the switches, Present and Download move into the ⋯ menu, which also opens another .pptx (or drop one onto the viewer). The sidebar lists every slide as a thumbnail, hidden slides dimmed; arrows, Home and End move through it. In the viewer, ← → Page Up / Page Down, Home and End change slides (↑ ↓ too while a slide fits the view), Ctrl+F / ⌘F opens search: the counter reads 2 of 6, Enter / Shift+Enter jump between hits, hits in the notes open the notes. Present goes fullscreen with the hidden slides left out: click, Space, arrows or Page Up / Down to advance, Home / End, Escape to leave; on a phone swipe left or right. Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. Menus become bottom sheets on phones and slides keep their own colors in dark mode.

npm: fflate, lucide-react
Wingo UI dependencies: button, dropdown-menu, popover, tooltip, use-controllable-state, motion, ui-config

Props:
- `src?: string` = "/demo/q3-business-review.pptx": URL of the .pptx: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-presentation state. The playground value is the sample quarterly review (12 slides, 16:9).
- `fileName?: string` = "": Name used for downloads and in the viewer's accessible label. Falls back to the last part of src; an uploaded file keeps its own name.
- `defaultSlide?: number` = 1: The slide it opens on, 1-based. Use slide and onSlideChange to control it.
- `defaultLayout?: "continuous" | "single"` = "continuous": continuous scrolls through every slide in a column; single shows one slide at a time, fitted to the viewer, with swipe on touch. The Single slide switch changes it.
- `defaultZoom?: number | "automatic" | "fit-page" | "fit-width"` = "automatic": The zoom each presentation opens at. "automatic" fits the slide width up to 100% in the column and the whole slide in single view; "fit-page" and "fit-width" fit the viewer; a number is a scale (1 is 100%).
- `defaultNotesVisible?: boolean` = false: Opens with the speaker notes of the current slide shown under it.
- `defaultSidebarOpen?: boolean` = true: Opens with the slides sidebar. It sits beside the slides from 520px of width and slides over them below, where it starts closed. Use sidebarOpen and onSidebarOpenChange to control it.
- `maxFileSize?: number` = "104857600": Bytes: 100 MB by default. A bigger file shows the file too large state with a download link instead of being parsed. The playground offers 100 KB, smaller than the sample, to show it.
- `variant?: "surface" | "outline" | "plain"` = "surface": surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the frame: 0, 12, 16 or 24px.
- `highlightColor?: string` = "rgba(250, 204, 21, 0.4)": Fill of every search hit, on the slides and in the notes. Keep it translucent so the text stays readable. Also set as --pptx-viewer-highlight on the frame.
- `activeHighlightColor?: string` = "rgba(249, 115, 22, 0.55)": Fill of the current search hit (--pptx-viewer-active-highlight).
- `showToolbar?: boolean` = true: The toolbar with slide navigation, zoom, search, view switches and file actions.
- `showThumbnails?: boolean` = true: The slides sidebar and its toggle.
- `showSearch?: boolean` = true: The search button, and Ctrl+F / ⌘F inside the viewer. Search covers the slides and the speaker notes.
- `showLayoutSwitch?: boolean` = true: The Single slide switch in the toolbar (the ⋯ menu when narrow).
- `showNotes?: boolean` = true: The Speaker notes switch in the toolbar (the ⋯ menu when narrow), off while the file has no notes.
- `showPresent?: boolean` = true: The Present button (in the ⋯ menu when narrow): fullscreen, one slide at a time, hidden slides left out.
- `showDownload?: boolean` = true: The download button (in the ⋯ menu when narrow). It saves the original file.
- `showUpload?: boolean` = true: Open a presentation in the ⋯ menu and dropping a .pptx onto the viewer. The file opens locally; onPresentationUpload hands it to you.
- `height?: number | string` = 640: Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
- `slide?: number`: Controls the slide in view, 1-based. Pair it with onSlideChange.
- `onSlideChange?: (slideNumber: number) => void`: Called with the slide number when the slide in view changes: scrolling, the toolbar, the keyboard, a thumbnail, a search hit or the presenter.
- `layout?: "continuous" | "single"`: Controls the layout. Pair it with onLayoutChange.
- `onLayoutChange?: (layout: "continuous" | "single") => void`: Called when the Single slide switch changes the layout.
- `sidebarOpen?: boolean`: Controls the slides sidebar. Pair it with onSidebarOpenChange.
- `onSidebarOpenChange?: (open: boolean) => void`: Called when the sidebar toggle, a pick in the overlay sidebar or its backdrop opens or closes it.
- `zoomLevels?: number[]` = "[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]": Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits for pinch and Ctrl / ⌘ + scroll too.
- `toolbarActions?: ReactNode`: Your own buttons at the end of the toolbar, before the ⋯ menu: share, comment, approve.
- `ref?: Ref<PptxViewerHandle> (a useRef object or an (handle) => void callback)`: goToSlide(slideNumber, { behavior }?), next(), previous(), getActiveSlide(), getSlides() with titles and notes for a table of contents, enterPresentation(slideNumber?), exitPresentation() and getViewportElement().
- `renderSlideOverlay?: (props: PptxViewerSlideOverlayProps) => ReactNode`: Draws on top of each slide in the viewer, sized to the slide at the current zoom: review pins, citations, stamps. Gets slideNumber, slideWidth, slideHeight and scale.
- `onPresentationLoadSuccess?: (presentation: PptxViewerPresentation) => void`: Called when a presentation is ready, with its file name, slide count, slides (number, title, hidden, notes, layout), slide size and aspect ratio, and document properties (title, author, dates, company).
- `onPresentationLoadError?: (error: unknown) => void`: Called when a presentation cannot be fetched or parsed, or is an old .ppt or password-protected file. The viewer shows the error state.
- `onPresentationUpload?: (file: File) => void`: Called with the File someone opened or dropped, as the viewer starts showing it.
- `onPresentingChange?: (presenting: boolean) => void`: Called when the presenter starts and ends.
- `labels?: Partial<PptxViewerLabels>`: Every string, English by default (DEFAULT_PPTX_VIEWER_LABELS): slide, of, slideNumber, previousSlide, nextSlide, slidesSidebar, slides, slideLabel(slide), hidden, zoomIn, zoomOut, zoomLevel, fitPage, fitWidth, automatic, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, singleSlide, notes, notesFor(slide), noNotes, present, exitPresentation, presentationProgress(slide, total), download, upload, presentation, loading, error, errorDescription, unsupported, tooLarge, tooLargeDescription(limit), emptyTitle, emptyDescription, noSlides, dropHere, video, audio, smartArt, embeddedObject, unsupportedImage, chart.
- `classNames?: Partial<Record<"toolbar" | "sidebar" | "thumbnail" | "viewport" | "slide" | "notes" | "state", string>>`: Extra classes for the toolbar, the sidebar, each thumbnail, the scrolling viewport, each slide frame, the notes panel and the loading / empty / error states.
- `className?: string`: Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts:
- `PptxViewerHandle` (type): What the ref gets: goToSlide(slideNumber, { behavior }?), next(), previous(), getActiveSlide(), getSlides(), enterPresentation(slideNumber?), exitPresentation() and getViewportElement().
- `PptxViewerPresentation` (type): What onPresentationLoadSuccess receives: fileName, slideCount, slides (PptxViewerSlideInfo[]), width and height of a slide at 100% in px, aspectRatio (16:9, 4:3, 16:10 or custom) and properties.
- `PptxViewerSlideInfo` (type): A slide: number (1-based), title (the title placeholder, else its first line of text), hidden, notes (plain text) and layout name.
- `PptxViewerSlideOverlayProps` (type): What renderSlideOverlay receives: slideNumber, slideWidth, slideHeight and scale.
- `PptxViewerZoom` (type): A scale or "automatic" | "fit-page" | "fit-width".
- `PptxViewerLayout` (type): "continuous" or "single".
- `PptxViewerLabels` (type): The shape of labels: every string the viewer renders.
- `DEFAULT_PPTX_VIEWER_LABELS` (constant): The English labels. Spread it to translate a few strings.

```tsx
import { PptxViewer } from "@/components/ui/pptx-viewer"

export function QuarterlyReviewPreview() {
  return (
    <PptxViewer
      src="/demo/q3-business-review.pptx"
      fileName="Q3 2026 business review.pptx"
      height="80dvh"
      onSlideChange={(slide) => console.log("slide", slide)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/pptx-viewer (Markdown: https://wingo-ui.com/components/pptx-viewer.md)

#### QR Code (`qr-code`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add qr-code`

A designed QR code: rounded or dotted modules, soft eyes, a center logo, any colors, a caption and one-tap PNG, SVG or image copy.

Point a phone camera at it: the code stays dark on a light tile in both themes, so it scans from a screen or a print. Changing the text crossfades to the new code; the first code springs in once (instantly with reduced motion). With downloadable on, Download opens a menu (a bottom sheet on phones) with a PNG at exportSize, an SVG and, where the device can share files, Share which opens the phone's share sheet; Copy image puts the PNG on the clipboard and turns into Copied for a moment. With showValue on, the encoded text sits under the caption with a copy button (a tooltip names it). Tab reaches the buttons in order, Enter or Space opens the menu, arrows move through it and Escape closes it back onto the trigger. Screen readers read the code as an image named after its text, and hear every copy and download.

npm: qrcode, motion, lucide-react
Wingo UI dependencies: button, dropdown-menu, skeleton, tooltip, use-clipboard, file-export, motion, ui-config

Props:
- `value: string` = "https://acme.com/i/2026-0412": The encoded text: a url, a Wi-Fi string (WIFI:T:WPA;S:Acme;P:...;;), a payment string. Any Unicode works (byte mode). An empty string shows the empty tile, text too long for the level shows the error tile; nothing throws.
- `caption?: ReactNode` = "": A line under the code, like Scan to pay. On the tile it takes the module color; unframed or on a transparent tile it uses the page text color.
- `showValue?: boolean` = false: Shows the encoded text under the caption in mono, truncated, with a copy button.
- `logo?: ReactNode | string`: An image url or a node (an inline svg mark, an <img>) centered on a cleared tile. It raises the error correction to Q, or H when logoSize is above 0.2. Exports embed url logos that can be fetched (same origin, CORS or data urls) and inline svg nodes.
- `size?: number` = 192: Width of the code in px (the frame adds 12px padding). It never grows past its container. Clamped so every module is at least 1.5px, with a warning in development.
- `moduleStyle?: "square" | "rounded" | "dots"` = "rounded": square: classic crisp squares. rounded: neighbouring modules merge into pills and blobs, corners round only where no neighbour touches. dots: circles at 85%.
- `finderStyle?: "square" | "rounded" | "circle"` = "rounded": The three corner eyes: an outer ring and an inner square, both in this shape.
- `color?: string` = "#111111": Module color. It stays dark in dark mode on purpose: scanners need dark modules on a light background.
- `background?: string` = "#ffffff": The tile and the quiet zone. "transparent" is allowed; the contrast is then up to you.
- `finderColor?: string` = "": The eyes in a second color, like the brand orange. Empty uses the module color.
- `framed?: boolean` = true: The tile: background, 12px padding and a raised shadow, so the code reads well on a dark page. Off draws the bare code.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the tile: 0 / 12 / 16 / 24 / 32px. Unframed codes, the loading and empty tiles use a smaller matching step.
- `logoSize?: number` = 0.22: Width of the logo tile as a fraction of the code, clamped to 0.1 to 0.3.
- `excavate?: boolean` = true: Clears the modules under the logo plus at least half a module around it. Off lays the logo tile over them.
- `level?: "L" | "M" | "Q" | "H"` = "M": Error correction: L recovers 7% of damage, M 15%, Q 25%, H 30%. Higher levels mean denser codes. With a logo it is raised to at least Q (H when the logo is wider than 20%); data-level shows the level in use.
- `margin?: number` = 2: Quiet zone in modules, drawn in the background color inside the frame. 4 is the ISO minimum for print without a frame.
- `downloadable?: boolean` = false: Shows the actions row: a Download menu (PNG, SVG, Share where files can be shared) and Copy image where the clipboard takes images.
- `fileName?: string` = "qr-code": Base name of exported files, passed to timestampedFileName: Invoice-2026-0412 becomes Invoice-2026-0412-2026-09-24-1640.png.
- `exportSize?: number` = 1024: Width and height of exported PNGs in px (the SVG export keeps the display size and scales freely).
- `loading?: boolean` = false: A skeleton at the final size while the value is on its way; the code springs in when it arrives.
- `animated?: boolean` = true: The entrance spring the first time a code appears. Value changes always crossfade; reduced motion turns both into a short fade.
- `setApi?: (api: QrCodeApi) => void`: Receives { toSvgString(), toBlob({ size, type, quality, background }), download("png" | "svg"), copy() } once after mount, for your own export buttons. Call copy() straight from a click handler (Safari).
- `onExport?: (file: { action: "download" | "share" | "copy"; format: "png" | "svg"; fileName: string; blob: Blob }) => void`: Called after every finished download, share or image copy, from the built-in actions and the api. The playground uses it for its last export readout.
- `labels?: Partial<QrCodeLabels>`: Every visible and announced string: image(value), download, png, pngHint(size), svg, svgHint, share, copyImage, copied, copyFailed, copyValue, downloaded(fileName), exportFailed, menuTitle, cancel, tooLong, empty. English defaults in DEFAULT_QR_CODE_LABELS.
- `classNames?: Partial<Record<"frame" | "svg" | "logo" | "caption" | "value" | "actions", string>>`: Extra classes for the inner parts.

Parts:
- `qrToSvgString` (function): The same code as standalone SVG text without a DOM: for emails, PDFs and server routes. Options mirror the props (level, size, margin, moduleStyle, finderStyle, color, background, finderColor, logo as a url or svg markup, logoSize, excavate, title). Signature: (value: string, options?: QrSvgOptions) => string.
- `getQrMatrix` (function): The raw module grid from the qrcode package, for custom renderers. Throws when the value does not fit. Signature: (value: string, level?: QrCodeLevel) => { size: number; get(row: number, col: number): boolean }.
- `buildQrGeometry` (function): The path data the component draws (modules, the three finders, the logo box), in module units. Signature: (matrix: QrMatrix, options?: { margin; moduleStyle; finderStyle; logoSize: number | null; excavate }) => QrGeometry.
- `effectiveQrLevel` (function): The level a logo raises the code to: at least Q, H when the logo is wider than 20%. Signature: (level: QrCodeLevel, logoSize: number | null) => QrCodeLevel.

```tsx
import { QrCode } from "@/components/ui/qr-code"

export function PayInvoice() {
  return (
    <QrCode
      value="https://pay.acme.com/invoice/2026-0412?amount=3025.00"
      caption="Scan to pay $3,025.00"
      logo="/logo.svg"
      downloadable
      fileName="Invoice 2026-0412"
      labels={{ menuTitle: "Save the payment code" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/qr-code (Markdown: https://wingo-ui.com/components/qr-code.md)

#### Step Player (`step-player`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add step-player`

An iOS-style stepped progress track with a play, pause and replay button, whose active step fills as it plays.

Press play to start the sequence. The current step stretches into a bar and fills as it runs, then shrinks to a filled dot when it hands off to the next one. Press again to pause mid-fill; the play icon splits into the pause bars as it goes. At the end it fades into a replay arrow. With seekable on, tap any step to jump to it and keep playing; the dots keep a finger-sized tap target and a visible focus ring for keyboard users.

npm: flubber, motion
Wingo UI dependencies: ui-config

Props:
- `steps?: number | StepPlayerStep[]` = 4: How many steps to show. Pass an array of { duration?, label? } to give each one its own duration or accessible label.
- `size?: number` = 48: Height of the track and button in pixels (minimum 12). Every other dimension is a fixed ratio of it, so the dots, bar, gaps, padding, icon, and tap targets all scale from this one number.
- `controlPosition?: "left" | "right"` = "right": Which side of the track the button sits on.
- `showControl?: boolean` = true: Shows the round play button. Turn it off for a track on its own and drive it with the playing prop.
- `trackColor?: string` = "": Any CSS color for the pill track and the round control. Empty uses #F4F4F9 light, #262626 dark.
- `fillColor?: string` = "": Any CSS color for finished steps and the running fill. Empty uses #3C3C43 light, #EBEBF5 dark.
- `pendingColor?: string` = "": Any CSS color for the steps still to come.
- `iconColor?: string` = "": Any CSS color for the play, pause and replay glyph and the focus outline. Empty uses #868593.
- `duration?: number` = 4000: Milliseconds each step runs for. A per-step duration overrides it; 0 stops the timer so you can drive the index yourself.
- `loop?: boolean` = false: Wraps back to the first step instead of stopping. The replay button never appears when this is on.
- `seekable?: boolean` = false: Lets a step be clicked to jump to it (and starts playing from there). The dots keep a finger-sized tap target at every size.
- `playLabel?: string` = "Play": Accessible name of the control while paused.
- `pauseLabel?: string` = "Pause": Accessible name of the control while playing.
- `replayLabel?: string` = "Replay": Accessible name of the control after the last step.
- `positionLabel?: string` = "Step {index} of {count}": Accessible name of the track; {index} and {count} fill in.
- `stepLabel?: string` = "Step {index}": Accessible name of each seek target when seekable and a step has no label; {index} fills in.
- `defaultValue?: number` = 0: Step to start on when uncontrolled. Clamped to the last step.
- `defaultPlaying?: boolean` = false: Whether the sequence starts running on mount when uncontrolled.
- `value?: number`: Active step index, for controlled use. Leave it out and the component tracks its own index.
- `onValueChange?: (value: number) => void`: Fires when the step advances, wraps, or is clicked. Also fires on replay.
- `playing?: boolean`: Play state, for controlled use. Leave it out to let the button drive it.
- `onPlayingChange?: (playing: boolean) => void`: Fires when the button is pressed, when a step is clicked, and when the last step ends without loop.
- `onComplete?: () => void`: Fires when the last step finishes, on every pass when looping.
- `className?: string`: Extra classes merged onto the root element (data-slot="step-player"). It sizes itself from the size prop, so give it a width only if you want the track wider than its content. Other div props are spread onto it too.

Parts:
- `StepPlayerStep` (type): One entry of steps when it is an array: { duration?, label? }. duration (ms) overrides the player's for that step, label names its seek target.

```tsx
"use client"

import { useState } from "react"
import { StepPlayer } from "@/components/ui/step-player"

export function Demo() {
  return <StepPlayer steps={5} duration={3000} />
}

// drive your own carousel off the index
const slides = ["Welcome", "Invite your team", "Ship it"]

export function Carousel() {
  const [index, setIndex] = useState(0)

  return (
    <div className="grid gap-4">
      <p className="text-lg font-medium">{slides[index]}</p>
      <StepPlayer steps={slides.length} value={index} onValueChange={setIndex} loop />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/step-player (Markdown: https://wingo-ui.com/components/step-player.md)

#### Video Player (`video-player`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add video-player`

A video player with controls that hide while you watch, a chapter scrubber, captions, speed, picture in picture and full screen.

Click or tap the big play button (or anywhere on the picture) to start; with a mouse, a click on the picture plays and pauses and a double click goes full screen. While it plays, the controls and the title fade away after 2.5 s of stillness and come back when you move the mouse, tap or focus a control; the captions glide down with them. Hover the scrubber and it thickens, a thumb appears and a pill shows the time and the chapter under the pointer; press and drag to scrub (a mouse seeks as it moves, a finger seeks on release), chapters are small ticks on the bar. The row has play, skip back / forward 10 s, mute with a volume slider, the time, a captions button (a menu when there are several languages), a speed menu, picture in picture and full screen; on phones the menus open as bottom sheets. On a touch screen a tap shows or hides the controls, a tap on the middle of the picture plays and pauses while they show, the big button is flanked by skip buttons, and a double tap on the left or right third jumps 10 s with a ripple and a pill that counts up as you keep tapping. Keyboard (focus the player or any control): Space or k play and pause, Left / Right seek 5 s, j / l 10 s, Up / Down volume, m mute, 0 to 9 jump to 0% to 90%, Home / End, < and > change the speed, f full screen, c captions on or off, i picture in picture; on the focused scrubber Left / Right seek 5 s, PageUp / PageDown 30 s. While it plays in picture in picture the stage says so and the bar stays usable. A missing file shows a message with a retry button.

npm: motion, lucide-react
Wingo UI dependencies: button, dropdown-menu, slider, spinner, tooltip, use-media-controls, use-media-query, motion, tones, ui-config

Props:
- `src: string | VideoSource[]`: The video url, or several { src, type } sources (webm, mp4) for the browser to pick from.
- `poster?: string`: The still shown before the first play (it fades out on play). Also the lock-screen artwork.
- `title?: ReactNode` = "": A title in a top scrim while the controls show; when it is a string, also the region name and the lock-screen title.
- `tracks?: VideoTrack[]` = "[]": WebVTT captions { src, srclang, label, kind?, default? }. The native tracks stay hidden and the player draws the active cue itself, above the controls. Tracks on another origin need CORS (the video gets crossOrigin anonymous).
- `chapters?: VideoChapter[]`: { start, title } in seconds: ticks on the scrubber, the chapter in the time pill and next to the time on wide players.
- `aspectRatio?: string` = "16 / 9": CSS aspect ratio of the stage, e.g. 1 / 1 for a listing card or 9 / 16 for a story.
- `fit?: "contain" | "cover"` = "contain": contain letterboxes the whole picture on black, cover crops it to fill the stage.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corner radius of the stage (0 / 12 / 16 / 24px). Full screen drops the corners.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the played part of the scrubber and the captions-on underline. neutral is white on the black stage in both themes.
- `color?: string` = "": Any CSS color for the played bar; replaces the tone.
- `captionSize?: "sm" | "md" | "lg"` = "md": Caption text size. Each step also grows with the player's own width, so a card and a full-screen player both read well.
- `controls?: "auto" | "always" | "none"` = "auto": auto hides the controls while playing and idle for hideDelay (paused, a menu open, keyboard focus or scrubbing keep them up); always keeps them; none shows only the picture, for background clips.
- `hideDelay?: number` = 2500: Milliseconds of stillness before the controls hide while playing. The mouse cursor hides with them.
- `skipSeconds?: number` = 10: Seconds for the skip buttons, a double tap and j / l. Arrow keys seek half of it.
- `doubleTapSeek?: boolean` = true: Touch: a double tap on the left or right third seeks by skipSeconds; more taps keep adding and the pill counts.
- `pip?: boolean` = true: The picture in picture button (and the i key) where the browser supports it. While it is out, the stage says so.
- `fullscreen?: boolean` = true: The full screen button, the f key and double click. The whole player goes full screen, so the controls and captions stay ours; phones try to turn to landscape. iOS Safari falls back to its native player.
- `autoPlay?: boolean` = false: Starts muted (browsers require it), pauses while scrolled out of view and resumes when back, unless the viewer paused it.
- `muted?: boolean` = false: Starts without sound; the mute button stays usable.
- `loop?: boolean` = false: Starts again from the beginning when it ends.
- `startTime?: number` = 0: Seconds to start from once the metadata loads, for continue watching. 0 starts at the beginning.
- `exclusive?: boolean` = true: Starting this player pauses every other exclusive player and audio player on the page.
- `mediaSession?: boolean` = true: While playing, sets the lock-screen title and artwork and handles play, pause and seek from the lock screen and headphones.
- `preload?: "none" | "metadata" | "auto"` = "metadata": How much the browser loads before play. metadata knows the duration without downloading the film.
- `captionsDefault?: string | "off"` = "": The caption language on at start (a track srclang), or "off". Empty uses the track marked default, else off.
- `rates?: readonly number[]` = "MEDIA_RATES": Speeds in the speed menu (0.5 to 2 by default). One rate hides the menu.
- `onPlay?: () => void`: Called when playback starts.
- `onPause?: () => void`: Called when playback pauses, including the automatic pause of autoPlay off screen.
- `onEnded?: () => void`: Called at the end (never while looping).
- `onError?: (error: MediaError | null) => void`: Called when the video cannot be loaded or played.
- `onTimeUpdate?: (seconds: number) => void`: Whole seconds while playing and after seeks, for saving progress.
- `setApi?: (api: VideoPlayerApi) => void`: The media controls (play, pause, seek, second, duration, progress…) plus fullscreen, pip, captions, enterFullscreen(), exitFullscreen(), togglePip() and setCaptions(lang | "off"). Called after mount and whenever the state changes.
- `labels?: Partial<VideoPlayerLabels>`: Every visible and spoken string, English by default (DEFAULT_VIDEO_PLAYER_LABELS): play, pause, replay, seek, skipBack(s), skipForward(s), skippedBack(s), skippedForward(s), volume, mute, unmute, captions, captionsOff, speed, normal, rate(r), pip, exitPip, pipActive, fullscreen, exitFullscreen, error, retry, cancel (the phone sheet button), live, loading, video, position(current, total).
- `classNames?: Partial<Record<"video" | "poster" | "bigPlay" | "spinner" | "captions" | "cue" | "ripple" | "center" | "skip" | "pip" | "title" | "controls" | "scrubber" | "track" | "thumb" | "bubble" | "row" | "button" | "time" | "error" | "live", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the stage, merged last.

```tsx
import { VideoPlayer } from "@/components/ui/video-player"

export function CityTour() {
  return (
    <VideoPlayer
      src="/demo/city-tour.mp4"
      poster="/demo/city-tour.jpg"
      title="City tour"
      tracks={[
        { src: "/demo/city-tour.en.vtt", srclang: "en", label: "English", default: true },
        { src: "/demo/city-tour.ro.vtt", srclang: "ro", label: "Romanian" },
      ]}
      chapters={[
        { start: 0, title: "The main boulevard" },
        { start: 7.8, title: "The mountains" },
        { start: 11, title: "Home" },
        { start: 16, title: "Final" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/video-player (Markdown: https://wingo-ui.com/components/video-player.md)

### AI Kit

#### Agent Status Card (`agent-status-card`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add agent-status-card`

An AI agent at work at a glance: orb, name, status, current step, progress, elapsed time, steps, logs and the controls that matter now.

The card shows the agent's orb (it thinks while the agent runs, listens while it waits for a person and rests otherwise; it only animates near the viewport and holds still under reduced motion), its name and task, and a status badge whose dot pings while it runs and which pops once with a check when a run finishes with every step green. Under it the current step shimmers while it runs, a progress bar glides from step to step (Step 3 of 5) and the elapsed time ticks every second. Only the controls that matter now appear: Pause and Stop while it runs, Resume and Stop while paused, Reject and Approve in an amber box when it waits for approval, Retry in a red box when it failed, View result in a green box when it finished. Stop asks first in a centered dialog (Escape or Keep running cancels). A handler that returns a promise spins its button and disables the others until it settles; a rejection is announced. The Steps and Logs toggles at the bottom open the step timeline and a monospace log that follows new lines until you scroll up inside it, and scroll with the keyboard once focused. The ⋯ button opens the agent's menu, a bottom sheet on phones. Tab reaches every control in order, Enter and Space press them, and each control's name includes the agent's name (Stop Collections agent). Status changes are announced once to screen readers. The compact variant keeps the orb, name, status, current step, progress and one primary action for grids; the row variant is a 64px list line with a progress ring that opens the agent on click, tap or Enter. Below 400px the orb sits above the text, buttons share the width and grow to 44px on touch, and logs cap at 40% of the screen height.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, badge, button, dropdown-menu, fluid-orb, matrix-orb, progress, tool-call-timeline, use-controllable-state, use-locale, use-stick-to-bottom, ai-chat, motion, number-format, relative-time, tones, ui-config

Props:
- `name?: ReactNode` = "": The agent's name, also used in the controls' accessible names and the stop dialog. Empty shows labels.untitled.
- `task?: ReactNode` = "": What it is doing this run, clamped to two lines with the full text in a tooltip title.
- `status?: "idle" | "queued" | "running" | "paused" | "awaiting-approval" | "complete" | "error" | "canceled"` = "idle": The run's state. It picks the badge (AGENT_STATUS_TONES: running info, paused and awaiting warning, complete success, error danger, the rest neutral), the orb's mood, the box under the progress and which controls show. In the playground Idle plays the live run and any other value forces that state.
- `steps?: ToolCall[]`: The run's steps in the ToolCall shape from lib/ai-chat. The progress (done / total), Step 3 of 5 and the current step derive from them, and the Steps toggle shows them as a tool-call-timeline.
- `currentStep?: ReactNode` = "": Overrides the derived current step (the running or waiting step's title, the failed one, else the last finished one). It shimmers while the agent runs.
- `progress?: number | null`: 0 to 1, clamped; null is an indeterminate bar. Undefined derives it from steps; with no steps it is indeterminate while running and hidden otherwise.
- `startedAt?: Date | string | number`: When the run started; the elapsed time counts from here (live while running or waiting).
- `endedAt?: Date | string | number`: When it ended: Finished in 1 min 48 s, or Stopped after 14 s for failed and stopped runs. Ignored without startedAt.
- `logs?: (AgentLogEntry | string)[]`: Log lines ({ id?, time?, level?: debug | info | warn | error, message } or plain strings). Passing an array (even empty) shows the Logs toggle with its count.
- `approval?: { question: ReactNode; description?: ReactNode; approveLabel?: ReactNode; rejectLabel?: ReactNode }`: The question shown in the amber box while status is awaiting-approval, with Reject and Approve when their handlers are set.
- `result?: ReactNode`: Shown in a green box with a check when the status is complete.
- `error?: ReactNode`: Shown in a red box with an alert icon when the status is error.
- `variant?: "card" | "compact" | "row"` = "card": card: everything, for a detail page. compact: orb, name, status, current step, progress and one primary action, for a grid of agents. row: a 64px list line with a 32px orb, name and current step, a progress ring with the percent (hidden when the row is narrower than 384px), the badge and the menu.
- `visual?: "matrix-orb" | "fluid-orb" | "icon" | "none"` = "matrix-orb": matrix-orb: dots that think while running, listen while waiting and rest otherwise. fluid-orb: a WebGL blob that drifts while running and holds still otherwise. icon: a round Bot mark tinted by the status. Orbs only mount near the viewport.
- `orbColor?: string` = "": A hex color for the orb. Empty follows the status tone (blue while running, green when done, red when failed, gray at rest).
- `size?: "sm" | "md"` = "md": Card orb 56 / 72px and name 15 / 17px. Compact (48px orb) and row (32px) keep their sizes.
- `radius?: "none" | "sm" | "md" | "lg"` = "lg": Corners of the card and compact surfaces: 0, 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The progress fill and the solid buttons (Resume, Approve, Retry). Status colors stay semantic.
- `color?: string` = "": Any CSS color; replaces the tone.
- `shimmer?: boolean` = true: The moving highlight on the current step while it runs (off under reduced motion; turn it off for static stills).
- `showSteps?: "toggle" | "always" | "never"` = "toggle": Card only: the steps timeline behind a Steps toggle, always open under the controls, or not at all.
- `showLogs?: boolean` = true: Card only: the Logs toggle (shown when logs is an array).
- `defaultStepsOpen?: boolean` = false: Start with the steps timeline open.
- `stepsOpen?: boolean`: Controlled open state of the steps panel.
- `onStepsOpenChange?: (open: boolean) => void`: Called when the Steps toggle is pressed.
- `defaultLogsOpen?: boolean` = false: Start with the logs open.
- `logsOpen?: boolean`: Controlled open state of the logs panel.
- `onLogsOpenChange?: (open: boolean) => void`: Called when the Logs toggle is pressed.
- `onPause?: () => (void | Promise<unknown>)`: Shows Pause while running. A returned promise keeps the button loading and the others disabled until it settles.
- `onResume?: () => (void | Promise<unknown>)`: Shows Resume (solid) while paused.
- `onStop?: () => (void | Promise<unknown>)`: Shows Stop while running, paused or queued; asks first when confirmStop is on.
- `onRetry?: () => (void | Promise<unknown>)`: Shows Retry when the run failed or was stopped.
- `onApprove?: () => (void | Promise<unknown>)`: Shows Approve in the approval box.
- `onReject?: () => (void | Promise<unknown>)`: Shows Reject in the approval box.
- `onOpen?: () => (void | Promise<unknown>)`: Shows View result when complete; in the row variant the whole row opens the agent.
- `menu?: MenuEntry[]`: The ⋯ menu's entries (dropdown-menu's shape): Edit agent, Duplicate, Run history, Delete. A bottom sheet below 768px.
- `confirmStop?: boolean` = true: Ask in an alert dialog before onStop (through useConfirm, so mount AlertDialogProvider once).
- `locale?: string` = "": Locale for durations (1 min 58 sec in en-US), percents and counts. Empty uses UIProvider's, then the page's.
- `now?: Date | number`: A fixed clock for the elapsed time (screenshots, tests, a paused run). Without it a running agent ticks on the shared ticker.
- `labels?: Partial<AgentStatusCardLabels>`: Every visible and spoken string: status (one word per status, partial), untitled, pause, resume, stop, stopTitle(name), stopDescription, keepRunning, approve, reject, approvalNeeded, retry, viewResult, steps, logs, stepOf(index, total), elapsed(duration), finishedIn(duration), stoppedAfter(duration), pausedAfter(duration), noLogs, menu, cancel (the menu sheet's close button on phones), announce(name, status), actionFailed. English defaults in DEFAULT_AGENT_STATUS_CARD_LABELS.
- `stepsLabels?: ToolCallTimelineLabelsInput`: Labels for the steps timeline (its status words, Approve, Retry).
- `classNames?: Partial<Record<"visual" | "header" | "name" | "task" | "status" | "menu" | "current" | "progress" | "progressLabel" | "elapsed" | "approval" | "result" | "error" | "controls" | "toggles" | "steps" | "logs", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root article, merged last.

Parts:
- `AgentLogView` (component): The log scroller alone: monospace lines with 16:38:05 times and warn / error tags, following new lines until the reader scrolls up. A focusable labelled region, not a live region. Props: { logs?: (AgentLogEntry | string)[]; label?: string; emptyText?: ReactNode; showTime?: boolean; follow?: boolean; classNames? }.
- `AGENT_STATUS_TONES` (constant): The status to tone map, for your own badges and dots. Type: Record<AgentStatus, Tone>.
- `DEFAULT_AGENT_STATUS_CARD_LABELS` (constant): The English strings, to spread and override. Type: AgentStatusCardLabels.

```tsx
import { AlertDialogProvider } from "@/components/ui/alert-dialog"
import { AgentStatusCard, type ToolCall } from "@/components/ui/agent-status-card"

const steps: ToolCall[] = [
  { id: "s1", name: "search_invoices", title: "Finding overdue invoices", status: "complete", durationMs: 820 },
  { id: "s2", name: "get_client_contacts", title: "Getting the contact details", status: "complete", durationMs: 410 },
  { id: "s3", name: "send_reminders", title: "Sending reminders (2 of 3)", status: "running" },
  { id: "s4", name: "update_statuses", title: "Updating the statuses", status: "pending" },
  { id: "s5", name: "send_report", title: "Sending the report", status: "pending" },
]

export function CollectionsAgent({
  onPause,
  onStop,
}: {
  onPause: () => Promise<void>
  onStop: () => Promise<void>
}) {
  return (
    <>
      <AlertDialogProvider />
      <AgentStatusCard
        name="Collections agent"
        task="Reminders for September's overdue invoices"
        status="running"
        steps={steps}
        startedAt={new Date(2026, 8, 24, 16, 38, 2)}
        logs={[{ time: new Date(2026, 8, 24, 16, 38, 5), message: "Found 3 invoices, $22,775.95 in total" }]}
        onPause={onPause}
        onStop={onStop}
        labels={{
          status: { running: "Working", paused: "On hold", complete: "Done" },
          stopTitle: (name) => `Stop ${name} now?`,
          elapsed: (duration) => `Working for ${duration}`,
        }}
      />
    </>
  )
}
```

Docs: https://wingo-ui.com/components/agent-status-card (Markdown: https://wingo-ui.com/components/agent-status-card.md)

#### Chat Message (`chat-message`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add chat-message`

One message of an AI conversation: the question in a bubble, the answer with its thinking, tools, markdown, sources and actions.

Your question sits in a bubble on the right, the answer reads on the left with a small mark. While it streams, three dots wait for the first word, the thinking row shimmers, tools spin inline and a caret follows the text; the actions appear when it finishes. Under the answer: Copy (a check confirms it), thumbs up or down (the pressed one fills and pops, the other steps aside and "Thanks" shows for a moment), Regenerate, the "‹ 2 / 3 ›" version switcher and the "⋯" menu. On the latest answer the actions always show; elsewhere they fade in on hover or focus, and on a phone a tap on the message shows them and its time (one message at a time) while a long press opens an action sheet with the same actions. Edit turns your bubble into a text box: Cmd or Ctrl + Enter sends, Escape cancels and puts focus back on Edit. Images in attachments open a full-screen viewer with swipe, files and sources open in a new tab, long questions fold behind "Show more", and a failed answer shows its error with Retry. Every action is a button in the Tab order with its own name; thumbs are toggles.

npm: motion, lucide-react
Wingo UI dependencies: markdown, reasoning-indicator, tool-call-timeline, action-sheet, avatar, button, collapsible, copy-button, dropdown-menu, image-lightbox, textarea, tooltip, ai-chat, file-types, relative-time, use-controllable-state, use-locale, use-long-press, use-media-query, motion, tones, ui-config

Props:
- `role?: "user" | "assistant" | "system"` = "assistant": Who wrote it. user: the person's bubble with Copy and Edit. assistant: the answer with its thinking, tools, sources and response actions. system: a quiet centered line between hairlines, without avatar or actions.
- `content?: string` = "": The message as markdown (tables, lists, code). Empty on a finished assistant message renders only the footer; empty while pending or streaming shows the typing dots. The playground falls back to the canonical invoice answer.
- `status?: "pending" | "streaming" | "complete" | "stopped" | "error"` = "complete": pending: sent, nothing back yet (typing dots). streaming: text arriving (caret, aria-busy, actions hidden). stopped: a Stopped note in the meta line, actions still work. error: the error row with Retry.
- `model?: string` = "": The model that wrote the answer, shown in the meta line (a mono chip in the flat header).
- `error?: ReactNode` = "": The message of the error row when status is "error"; empty shows labels.error.
- `edited?: boolean` = false: Adds "edited" to the meta line.
- `variant?: "default" | "bubbles" | "flat"` = "default": default: the person in a bubble on the right, the answer as text on the left (ChatGPT). bubbles: both sides in bubbles (a messenger, a support widget). flat: both on the left with avatars and name headers, no bubbles (team threads, docs).
- `size?: "sm" | "md"` = "md": Text 14 / 15px, bubble padding and avatars 24 / 28px. sm fits copilot side panels.
- `bubble?: "soft" | "solid"` = "soft": The person's bubble: a light tint of the tone, or a solid fill (black / white when neutral).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of the person's bubble and the edit Send button. Neutral is gray (soft) or black / white (solid).
- `color?: string` = "": Any CSS color for the bubble; replaces the tone. Text on a solid fill turns black or white by lightness.
- `showAvatar?: "assistant" | "all" | "none"` = "assistant": Which side shows an avatar. The flat variant always shows both unless "none".
- `assistantAvatar?: ReactNode`: Replaces the assistant's round Sparkles mark: a MatrixOrb, a logo, an image.
- `assistantName?: string` = "": The assistant's name in the flat header and the screen reader heading; falls back to author.name, then labels.assistant.
- `timestamp?: "hover" | "always" | "never"` = "hover": The time (and model) in the meta line: shown on hover, focus or a tap, always, or never. The flat header always shows the time.
- `timeFormat?: "relative" | "time" | "date" | "datetime"` = "time": "16:35", or relative ("5 min. ago", ticking once a minute), a date, or both.
- `actions?: "auto" | "always" | "hover" | "never"` = "auto": auto: always visible on the latest assistant message, on hover, focus or a tap elsewhere. always / hover force one rule; never hides the action bar (the long-press sheet still works).
- `isLatest?: boolean` = false: The last assistant message of a thread (chat-thread sets it). Drives actions="auto".
- `grouped?: boolean` = false: A follow-up from the same sender: the avatar and header hide (the text stays aligned) and the bubble tightens its corner on the sender's side.
- `copyFormat?: "markdown" | "text"` = "markdown": What Copy puts on the clipboard: the markdown source, or plain text through markdownToText.
- `caret?: "dot" | "bar" | "block" | "none"` = "dot": The caret at the end of streaming text.
- `codeAccent?: string` = "": The accent of code blocks in the answer and the tool inputs and outputs; empty keeps the code block's own.
- `maxUserLines?: number` = 8: Long questions fold past this many lines behind "Show more"; 0 never folds.
- `longPress?: boolean` = true: On touch screens a long press on the message opens an action sheet with every action (and a haptic tick). Links, code and the buttons keep their own touch behavior.
- `locale?: string` = "": Times, durations and file sizes. Empty uses UIProvider's locale, then the browser's.
- `createdAt?: Date | string | number`: When it was sent; the meta line, the flat header and the screen reader heading show it.
- `author?: ChatPerson`: { id, name, avatar? }: the person (their avatar and name) or the assistant (its name and picture).
- `attachments?: ChatAttachment[]`: Images in a grid that opens the full-screen viewer (one large, two to four as tiles, more as +N), files as tiles with their type color and size.
- `reasoning?: ChatReasoning`: { content, status?, startedAt?, endedAt?, durationMs? }: the thinking row above the answer (ReasoningIndicator).
- `toolCalls?: ToolCall[]`: The tools it used, as an inline summary that expands into the timeline (ToolCallTimeline variant inline).
- `sources?: ChatSource[]`: Chips under the answer with favicon, domain and number; they open their url in a new tab.
- `id?: string`: The message id, set on the root; keeps the tap-to-show state per message.
- `branch?: { index: number; count: number }`: Which version this is (1-based) of how many: shows the "‹ 2 / 3 ›" switcher when count is above 1, and the text cross-fades on every switch.
- `onBranchChange?: (index: number) => void`: The switcher's previous / next, with the new 1-based index. Without it the arrows are disabled.
- `onCopy?: (text: string) => void`: After copying (Copy is built in).
- `onRegenerate?: () => (void | Promise<unknown>)`: Shows Regenerate on assistant messages; a returned promise keeps it spinning.
- `onEdit?: (content: string) => (void | Promise<unknown>)`: Shows Edit on user messages; Send calls it with the new text (unchanged text just closes the editor). A promise keeps Send loading and the editor open until it resolves.
- `feedback?: "up" | "down" | null`: Controlled thumbs; without onFeedbackChange they are read-only (in the bar and the long-press sheet). The thumbs show when any of feedback, defaultFeedback or onFeedbackChange is set.
- `defaultFeedback?: "up" | "down" | null`: The starting thumbs while uncontrolled.
- `onFeedbackChange?: (feedback: "up" | "down" | null) => (void | Promise<unknown>)`: Pressing the pressed thumb clears it. Optimistic: a rejected promise rolls the choice back.
- `onRetry?: () => (void | Promise<unknown>)`: Shows Retry in the error row; a promise keeps it loading.
- `menu?: MenuEntry[]`: The "⋯" menu (Share, Read aloud, Report, Delete): a dropdown on desktop, a bottom sheet on phones; its items also join the long-press sheet.
- `onSourceClick?: (source: ChatSource) => void`: Replaces opening the source url.
- `onAttachmentClick?: (attachment: ChatAttachment) => void`: Replaces the default: images open the viewer, files open their url.
- `now?: Date | number`: Pins the clock for relative times and live durations (screenshots, tests). Default: a shared ticker.
- `markdownProps?: Partial<MarkdownProps>`: Passed to the Markdown of the content (labels, linkTarget, components). Keep it stable.
- `reasoningProps?: Partial<ReasoningIndicatorProps>`: Passed to the thinking row (labels, variant, peek). Keep it stable.
- `toolCallProps?: Partial<ToolCallTimelineProps>`: Passed to the inline tool timeline (labels, onApprove, onReject). Keep it stable.
- `labels?: Partial<ChatMessageLabels>`: Every visible and spoken string: you, assistant, youWrote, personWrote(name), assistantWrote(name), system, copy, copied, regenerate, edit, save, cancel, good, bad, feedbackThanks, more, retry, error, stopped, edited, sources, attachments, previous, next, branch(index, count), branchLabel(index, count), showMore, showLess, thinking, attachment(name, size), openImage(name), moreImages(count). English by default (DEFAULT_CHAT_MESSAGE_LABELS).
- `classNames?: Partial<Record<"avatar" | "header" | "attachments" | "bubble" | "reasoning" | "tools" | "content" | "typing" | "error" | "sources" | "footer" | "actions" | "action" | "meta" | "editor", string>>`: Extra classes for the inner parts.

Parts:
- `ChatMessageActions` (component): The action bar alone (copy, edit, thumbs, regenerate, versions, menu), for custom message layouts. Props: ChatMessageActionsProps.
- `ChatMessageAttachments` (component): The image grid with its viewer and the file tiles. Props: ChatMessageAttachmentsProps.
- `ChatMessageSources` (component): The rail of source chips. Props: ChatMessageSourcesProps.
- `ChatMessageTyping` (component): The three typing dots of a pending reply, with sr-only text (chat-thread's thinking row uses it). Props: ChatMessageTypingProps.

```tsx
import { ChatMessage, type ChatMessageData, type ChatMessageLabels } from "@/components/ui/chat-message"

const labels: Partial<ChatMessageLabels> = {
  assistant: "Summit Assistant",
  assistantWrote: (name) => `${name} replied`,
  regenerate: "Try again",
  good: "Helpful",
  bad: "Not helpful",
  feedbackThanks: "Thanks for the feedback",
}

export function Answer({ message, onRegenerate }: { message: ChatMessageData; onRegenerate: () => Promise<void> }) {
  return (
    <ChatMessage
      {...message}
      isLatest
      labels={labels}
      onRegenerate={onRegenerate}
      onFeedbackChange={(feedback) => console.log(message.id, feedback)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/chat-message (Markdown: https://wingo-ui.com/components/chat-message.md)

#### Chat Thread (`chat-thread`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add chat-thread`

The scrolling conversation of an AI chat: pinned to the newest message while it streams, with day pills, follow-ups and a pinned composer.

The thread opens at the newest message and follows a reply while it streams. Scroll up (wheel, finger, arrows, Page Up) and it lets go at once; a pill floats above the composer with the number of new replies, and tapping it glides back down and puts focus on the newest message. Sending always brings you to the bottom. Day pills stick to the top while their day scrolls under them. Reach the top of a long history and older messages load above without the view moving. Under the latest answer, follow-up rows send themselves on a tap or Enter (arrow keys move between them). An empty thread shows a greeting with starter cards that scroll sideways on phones. Tab reaches the header, the message list (it scrolls with the keyboard), each message's actions, the follow-ups, the jump pill and the composer. Screen readers hear once when a reply starts and when it is ready, never every streamed word.

npm: motion, lucide-react
Wingo UI dependencies: chat-message, suggestion-chips, markdown, button, skeleton, spinner, use-stick-to-bottom, use-locale, ai-chat, date-utils, number-format, relative-time, motion, ui-config

Props:
- `messages: ChatMessageData[]`: The conversation, oldest first. Keep message objects immutable: give only the message that changed a new object, so only it re-renders while text streams. Repeated ids are skipped.
- `thinking?: boolean` = false: Shows the pending assistant row (the mark and three dots) after sending and before the first token, unless the last message is already a pending or streaming answer.
- `composer?: ReactNode`: Usually a PromptInput. The thread pins it under the reading column above the safe area, with a fade over the messages behind it. Leave it out for a read-only thread.
- `header?: ReactNode`: A bar above the scroller: the title, a model picker, share.
- `emptyState?: ReactNode`: Replaces the greeting of an empty thread entirely.
- `greeting?: ReactNode` = "": The empty state's title. Empty uses labels.greeting.
- `emptyDescription?: ReactNode` = "": A line under the greeting.
- `emptyIcon?: ReactNode`: The empty state's icon. An AI mark by default; a FluidOrb or a logo.
- `suggestions?: ChatSuggestion[]`: Starter cards in the empty state: a grid on desktop, a rail on phones.
- `followUps?: ChatSuggestion[]`: Rows under the latest answer, shown once it is complete and nothing is thinking.
- `onSuggestionSelect?: (suggestion: ChatSuggestion) => void`: A starter card or a follow-up was chosen; send suggestion.prompt ?? suggestion.label.
- `onRegenerate?: ((message: ChatMessageData) => void | Promise<unknown>)`: Regenerate on an assistant message. A returned promise keeps the button loading.
- `onEdit?: ((message: ChatMessageData, content: string) => void | Promise<unknown>)`: A user message was edited in place and sent again.
- `onFeedbackChange?: ((message: ChatMessageData, feedback: ChatFeedback) => void | Promise<unknown>)`: The thumbs on assistant messages. Store it in the message's feedback to control it; a rejected promise rolls back.
- `onRetry?: ((message: ChatMessageData) => void | Promise<unknown>)`: Retry on a message with status error.
- `onCopy?: (message: ChatMessageData, text: string) => void`: After a message was copied (copying is built in).
- `onBranchChange?: (message: ChatMessageData, index: number) => void`: The version switcher of a message with branch.count above 1.
- `messageProps?: Partial<ChatMessageProps>`: Presentation props for every message: bubble, tone, color, showAvatar, assistantAvatar, timestamp, menu, labels, markdownProps. Keep it memoized (a module constant or useMemo) so finished messages never re-render.
- `renderMessage?: (message: ChatMessageData, props: ChatMessageProps) => ReactNode`: Full control over a message (a custom card for some). Return undefined for the default ChatMessage.
- `variant?: "default" | "bubbles" | "flat"` = "default": The messages' layout. default: your bubble on the right, the answer as text on the left. bubbles: both in bubbles (support widgets). flat: both on the left with avatars and names (team threads). messageProps.variant wins.
- `size?: "sm" | "md"` = "md": Message text, avatars and gaps. sm fits copilot side panels.
- `maxWidth?: "sm" | "md" | "lg" | "full"` = "md": The reading column of the messages and the composer: 640 / 768 / 960px or the full width.
- `dateSeparators?: boolean` = true: A day pill between days ("Yesterday", "Today", "Monday", "Sep 22, 2026") that sticks to the top while its day scrolls. Messages without createdAt get none.
- `stickToBottom?: boolean` = true: Follows new content while the reader is at the bottom, and lets go as soon as they scroll up.
- `jumpButton?: boolean` = true: The pill that shows while scrolled up, with the number of replies that arrived since.
- `hasMore?: boolean` = false: Older messages exist: a sentinel at the top calls onLoadMore when it comes within 400px, once per cycle.
- `onLoadMore?: (() => void | Promise<unknown>)`: Prepend older messages. The first visible message stays exactly where it was.
- `loadingMore?: boolean` = false: A spinner at the top while older messages load.
- `loading?: boolean` = false: The first load: three skeleton message pairs in place of an empty thread.
- `announce?: "notice" | "full" | "off"` = "notice": The polite live region. notice: says when a reply starts and when it is ready. full: also reads the first 600 characters of the reply. The thread itself is never a live region.
- `now?: Date | number`: The reference time for day labels and message times (default: the current minute).
- `locale?: string` = "": Day labels, dates and counts. Empty uses the app's locale.
- `labels?: Partial<ChatThreadLabels>`: Every string: conversation, messages, greeting, jump, newMessages(count, formatted), loadMore, loadingMore, loading, thinking, responseStarted, responseReady, responseFailed, today and yesterday (empty uses the locale's word), suggestions, followUps. English by default (DEFAULT_CHAT_THREAD_LABELS). Message strings go in messageProps.labels.
- `classNames?: Partial<Record<"header" | "scroller" | "content" | "list" | "item" | "separator" | "loadMore" | "thinking" | "followUps" | "empty" | "jump" | "composer", string>>`: Extra classes for the inner parts. On a surface other than the page, set the composer fade with className="[--chat-thread-fade:var(--popover)]".

Parts:
- `ChatThreadSeparator` (component): The sticky day pill, with the full date as an sr-only heading. Props: ChatThreadSeparatorProps.
- `ChatThreadEmpty` (component): The greeting of a new conversation: icon, title, description and starter cards. Props: ChatThreadEmptyProps.
- `ChatThreadJump` (component): The floating jump-to-latest pill with its count. Props: ChatThreadJumpProps.

```tsx
import { useState } from "react"
import { ChatThread, type ChatMessageData, type ChatThreadLabels } from "@/components/ui/chat-thread"
import { PromptInput } from "@/components/ui/prompt-input"
import { createChatId, mockStream } from "@/lib/ai-chat"

const labels: Partial<ChatThreadLabels> = {
  greeting: "Hi, Anna! How can I help today?",
  jump: "Back to the latest message",
}

export function Assistant() {
  const [messages, setMessages] = useState<ChatMessageData[]>([])
  const [thinking, setThinking] = useState(false)

  async function send(text: string) {
    const id = createChatId("a")
    setMessages((list) => [...list, { id: createChatId("u"), role: "user", content: text, createdAt: Date.now() }])
    setThinking(true)
    let content = ""
    for await (const part of mockStream("I found **3 overdue invoices**, $22,775.95 in total.")) {
      if (!content) setThinking(false)
      content += part
      const snapshot = content
      // a new object only for the message that changed
      setMessages((list) =>
        list.some((m) => m.id === id)
          ? list.map((m) => (m.id === id ? { ...m, content: snapshot } : m))
          : [...list, { id, role: "assistant", content: snapshot, status: "streaming", createdAt: Date.now() }],
      )
    }
    setMessages((list) => list.map((m) => (m.id === id ? { ...m, status: "complete" } : m)))
  }

  return (
    <div className="h-dvh">
      <ChatThread
        messages={messages}
        thinking={thinking}
        labels={labels}
        composer={<PromptInput onSubmit={(message) => send(message.text)} />}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/chat-thread (Markdown: https://wingo-ui.com/components/chat-thread.md)

#### Conversation List (`conversation-list`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add conversation-list`

The chat history of an AI app: New chat, search, pinned chats and Today / Yesterday / older groups, with rename, pin, archive and delete.

Click or tap a chat to open it: the open one is tinted and keeps its ⋯ button, rows with an href navigate through your router link. Chats sit under sticky day labels (Pinned, Today, Yesterday, Previous 7 days, Previous 30 days, then one per month), newest first; a reply still streaming shows a small spinner and an unread chat a dot. With a mouse the ⋯ appears on hover or focus while the title fades out beneath it; on touch it is always there and the rows are 44px. The ⋯ menu (a bottom sheet on phones) renames, pins or unpins, archives and deletes, below any entries of your own; a long press on a touch screen opens the same menu (the sheet on a phone) with a haptic tick. Rename edits the title in place on a desktop (Enter or a click away saves, Escape cancels, an empty title keeps the old one) and on a phone in a small sheet with Save whose field has the keyboard up at once. Delete asks first, then the chat leaves at once and focus moves to the next one; pin moves a chat into Pinned while the rows around it slide (in one ungrouped list it glides up, lifted over the others). Every change shows right away, stays busy with a spinner while your handler's promise runs, and rolls back with an announcement if it rejects. Typing in the search turns the groups into one ranked list with the matched letters in bold (a match in the last message shows that part of it); Down steps from the search into the results. The rows are one Tab stop: Up and Down move, Home and End jump, Page Up and Page Down skip ten, Enter opens, F2 renames, Delete or Backspace deletes, Shift+F10 or the menu key opens the actions, and Tab reaches the focused row's ⋯. A title cut off or faded under the ⋯ shows in full as the row's tooltip after a moment with a mouse. Load more at the end also runs when it scrolls into view. Reduced motion turns every slide into a short fade.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, button, drawer, dropdown-menu, empty-state, input, kbd, search-input, skeleton, spinner, use-controllable-state, use-locale, use-long-press, use-media-query, use-shortcut, date-utils, motion, navigation, number-format, relative-time, text-match, tones, ui-config

Props:
- `conversations: ConversationItem[]`: The history: { id, title, updatedAt, preview?, pinned?, unread?, streaming?, archived?, href?, icon?, model? }. updatedAt (a Date, an ISO string or ms) sorts and groups them; a missing or invalid one goes to Earlier at the end. An empty title shows labels.untitled. Keep the objects immutable: a new object only for the chat that changed.
- `value?: string`: The open conversation's id (controlled). Without it, rows with an href follow the current page of a LinkProvider (currentPath), and otherwise the last clicked row stays open. An id that is not in the list highlights nothing.
- `defaultValue?: string` = "": The conversation open on the first render while uncontrolled. Empty in the playground opens Overdue invoices, September.
- `onValueChange?: (id: string, item: ConversationItem) => void`: A row was chosen (a click, a tap or Enter). Rows with an href also navigate.
- `onNewChat?: () => void`: Shows the New chat button at the top (and makes newChatShortcut work).
- `onRename?: (id: string, title: string) => (void | Promise<unknown>)`: Enables Rename in the menu, F2 and a double click with a mouse. The new title (trimmed, never empty) shows at once; a returned promise keeps the row busy, and a rejection brings the old title back and announces the error.
- `onPinChange?: (id: string, pinned: boolean) => (void | Promise<unknown>)`: Enables Pin / Unpin. The chat slides into (or out of) Pinned at once and rolls back if the promise rejects.
- `onArchive?: (id: string) => (void | Promise<unknown>)`: Enables Archive. The chat leaves the list at once (unless showArchived) and comes back if the promise rejects.
- `onDelete?: (id: string) => (void | Promise<unknown>)`: Enables Delete (the menu, Delete or Backspace on a focused row). After the confirmation the chat leaves at once and focus moves to the next chat, or New chat; a rejection brings it back.
- `getActions?: (item: ConversationItem) => MenuEntry[]`: Extra dropdown-menu entries above the built-in ones (Share, Move to project, a submenu). Called each time a menu opens, so they can depend on the app's state.
- `search?: boolean` = true: The search field under New chat. Its text still filters the list when you hide it and pass searchValue yourself.
- `searchValue?: string`: The search text (controlled). Pair it with onSearchChange for a server search, then pass the results as conversations and filter={false}.
- `defaultSearchValue?: string` = "": The search text on the first render while uncontrolled.
- `onSearchChange?: (value: string) => void`: Every keystroke in the search, and the clear.
- `searching?: boolean` = false: The search icon turns into a spinner while your server looks for results.
- `searchShortcut?: string` = "": A key combo in mod+k notation that focuses the search from anywhere, shown as a hint in the empty field. "" binds nothing.
- `filter?: boolean` = true: Filters titles, previews and model names locally while searching (case and diacritics ignored, best matches first). false keeps conversations as given, for results that come from a server.
- `groupBy?: "date" | "none"` = "date": date: Pinned, Today, Yesterday, Previous 7 days, Previous 30 days, then one group per month, each under a sticky label. none: one list, pinned chats first with a pin glyph.
- `showPreview?: boolean` = false: A second line with the last message; rows grow to 52 / 56px.
- `showTime?: boolean` = false: A trailing time: "4:35 PM" today, "Yesterday" yesterday, "Sep 22" this year, the full date before. With a mouse the ⋯ takes its place on hover.
- `showArchived?: boolean` = false: Lists archived chats too, muted and with an archive glyph (the demo has one from August).
- `size?: "sm" | "md"` = "md": Rows 36 / 40px (44px on touch), with New chat and the search at the same height.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The rows' corners, the button's radius at the row size (8 / 10px at md); full makes pills.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the open row (a gray tint for neutral, the tone's soft fill otherwise), the unread dot and the streaming spinner.
- `color?: string` = "": Any CSS color. Replaces the tone for the open row, the dot and the spinner. Leave empty to use the tone.
- `actionsVisibility?: "hover" | "always"` = "hover": hover: with a mouse the ⋯ shows on hover and keyboard focus (it is always there on touch and on the open chat). always: on every row, which keeps room for it.
- `confirmDelete?: boolean` = true: Asks in an alert dialog before onDelete. false deletes at once.
- `newChatShortcut?: string` = "": A key combo in mod+k notation that calls onNewChat from anywhere, shown on the button (⇧⌘O on a Mac, Ctrl+Shift+O elsewhere) and hidden on touch. "" binds nothing; the demo uses shift+mod+o.
- `loading?: boolean` = false: Skeleton rows with the real row shape (two lines with showPreview) and aria-busy, while the history loads.
- `skeletonCount?: number` = 8: How many skeleton rows loading shows.
- `hasMore?: boolean` = false: Load more at the end of the list; it also runs onLoadMore when it scrolls into view (once per new page, never while searching).
- `onLoadMore?: () => (void | Promise<unknown>)`: Loads the next page of older chats; a returned promise keeps Load more spinning until it settles.
- `loadingMore?: boolean` = false: Keeps Load more spinning, for apps that track the request themselves.
- `emptyState?: ReactNode`: Replaces the empty state (a chat icon, labels.empty and labels.emptyDescription). A search with no match shows its own, with Clear search.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders rows that have an href: next/link's Link, react-router's Link. Defaults to the LinkProvider's, then a plain <a>.
- `now?: Date | number`: The reference time for the day groups and times; default useNow(), which ticks each minute. Without it the list shows skeleton rows on the server and during hydration, so pass a server time to render the real list there.
- `locale?: string` = "": Formats times, month groups and the result count ("en-US"). Empty uses the UIProvider's locale, then the browser's.
- `labels?: Partial<ConversationListLabels>`: Every visible and spoken string, English by default (DEFAULT_CONVERSATION_LIST_LABELS): group names, the menu, the delete confirmation, the rename sheet, the empty states and the announcements. Counted and titled ones are functions: results(count, formatted), actions(title), deleteTitle(title), renamed(title). Pass a stable object.
- `classNames?: Partial<Record<"header" | "newChat" | "search" | "scroller" | "group" | "groupLabel" | "list" | "item" | "row" | "icon" | "title" | "preview" | "indicator" | "time" | "actions" | "rename" | "more" | "empty" | "skeleton", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root <nav>. It inherits its parent's background so the sticky day labels cover the rows; give it one (bg-card) when the parent is transparent.

Parts:
- `ConversationListItem` (component): One row on its own (a recent-chats card, a search result): item, active, onSelect, size, radius, tone, color, showPreview, showTime, now, locale, linkComponent, labels, classNames. Same look and link behavior, no menu; render it inside a <ul>. Props: ConversationListItemProps.
- `groupConversations` (function): The grouping the list uses, pure: [{ key: "pinned" | "today" | "yesterday" | "week" | "month" | "2026-08" | "earlier", label, items }], newest first inside each group, month labels like "August 2026". Signature: (items: ConversationItem[], options: { now: Date | number; locale?: string; labels?: Partial<ConversationListLabels> }) => ConversationGroup[].
- `DEFAULT_CONVERSATION_LIST_LABELS` (constant): The English strings, to spread a translation over. Type: ConversationListLabels.

```tsx
import { useState } from "react"
import { Share2 } from "lucide-react"
import { ConversationList, type ConversationItem } from "@/components/ui/conversation-list"

// your own wording over the English defaults (DEFAULT_CONVERSATION_LIST_LABELS)
const LABELS = {
  nav: "Assistant chats",
  pinned: "Starred",
  deleteTitle: (title: string) => `Delete “${title}” for good?`,
}

export function ChatHistory({ initial }: { initial: ConversationItem[] }) {
  const [chats, setChats] = useState(initial)
  const [open, setOpen] = useState(initial[0]?.id ?? "")
  const patch = (id: string, change: Partial<ConversationItem>) =>
    setChats((list) => list.map((chat) => (chat.id === id ? { ...chat, ...change } : chat)))

  return (
    <aside className="h-dvh w-72 bg-card">
      <ConversationList
        conversations={chats}
        value={open}
        onValueChange={setOpen}
        onNewChat={() => {
          const id = crypto.randomUUID()
          setChats((list) => [{ id, title: "", updatedAt: Date.now() }, ...list])
          setOpen(id)
        }}
        onRename={async (id, title) => {
          await fetch(`/api/chats/${id}`, { method: "PATCH", body: JSON.stringify({ title }) })
          patch(id, { title })
        }}
        onPinChange={(id, pinned) => patch(id, { pinned })}
        onArchive={(id) => patch(id, { archived: true })}
        onDelete={(id) => setChats((list) => list.filter((chat) => chat.id !== id))}
        getActions={(chat) => [{ id: "share", label: "Share", icon: <Share2 />, onSelect: () => navigator.clipboard.writeText(`/chat/${chat.id}`) }]}
        newChatShortcut="shift+mod+o"
        showTime
        locale="en-US"
        labels={LABELS}
      />
    </aside>
  )
}

// server search: control the text, show the server's results as they come, and keep them unfiltered
// <ConversationList conversations={results} searchValue={query} onSearchChange={setQuery} searching={pending} filter={false} />
// long histories: hasMore + onLoadMore (a promise keeps Load more spinning; it also runs when it scrolls into view)
```

Docs: https://wingo-ui.com/components/conversation-list (Markdown: https://wingo-ui.com/components/conversation-list.md)

#### Fluid Orb (`fluid-orb`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add fluid-orb`

An animated WebGL orb with drifting fluid shading, inspired by ChatGPT's voice mode.

Ambient: the color patches drift left, right, up, down and diagonally on their own, blending and reforming with no interaction required. The top of the orb stays near white (highlightColor) while the middle and bottom take a pale tint and the full color. Honors prefers-reduced-motion by holding a still frame.
Wingo UI dependencies: ui-config

Props:
- `color?: string` = "#1A73F2": Any CSS color for the fluid: hex, rgb(), hsl(), oklch(), a name or var(--token). The middle and bottom bands are derived from it (a pale tint and the full color), while the top takes highlightColor. Anything the browser cannot parse falls back to the original blue.
- `size?: number` = 240: Diameter of the orb in pixels. The canvas renders at up to 2x device pixel ratio, so it stays crisp at any size.
- `highlightColor?: string` = "#FCFFFF": Any CSS color for the top of the orb, where the fluid thins out. The pale middle band is mixed from it and color. Anything the browser cannot parse falls back to near white.
- `turbulence?: number` = 0.8: How far the noise pushes the bands into each other. 0 gives smooth horizontal bands, higher values give deeper, more tangled waves.
- `speed?: number` = 1: Playback rate of the drift. 1 is the original pace, 0 holds the current frame, and changing it mid-flight bends the motion without a jump.
- `paused?: boolean` = false: Freezes the drift on the current frame; color, size and turbulence still update. Unpausing picks up where it stopped.
- `className?: string`: Extra classes merged onto the root element (data-slot="fluid-orb"). Other div props are spread onto it too.
- `style?: React.CSSProperties`: Inline styles merged after the size, so a width or height here overrides the size prop.

```tsx
import FluidOrb from "@/components/ui/fluid-orb"

export function Demo() {
  return <FluidOrb size={280} color="#F75001" />
}
```

Docs: https://wingo-ui.com/components/fluid-orb (Markdown: https://wingo-ui.com/components/fluid-orb.md)

#### Grid Reveal (`grid-reveal`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add grid-reveal`

A loading state for AI images that turns into the real picture when it arrives.

Press Generate and the frame opens as four cells, then keeps splitting the biggest one in two while the image is on its way. When the picture lands the cells take on its colors, busy parts of the image split first, the gutters close up and the photo fades in. A frosted status pill sits in the bottom left with a slow shimmer, crossfading between lines as the caption changes, and fades out once the reveal is done. Honors prefers-reduced-motion by holding a still frame.

npm: motion
Wingo UI dependencies: ui-config

Props:
- `aspect?: number` = 1: Width divided by height of the frame. The frame fills its parent's width, so constrain the parent to size it.
- `caption?: string` = "": Optional status text, shown as a frosted pill in the bottom left of the frame and lit by a slow shimmer. Change it mid-run and the lines crossfade while the pill resizes to suit. Empty renders no pill.
- `alt?: string` = "": Describes the finished image for screen readers. The frame is hidden from assistive tech when it is empty.
- `estimatedDuration?: number` = 6000: Roughly how long the work takes in milliseconds, used to pace the grid when no progress is passed. Overrunning it is fine, the grid keeps creeping instead of stopping.
- `cells?: number` = 180: How many cells the grid ends on before the photo fades in, from 8 to 400. Fewer cells read as big bold blocks, more as a fine mosaic. A new count shows on the next reveal.
- `radius?: number` = 16: Corner radius of the frame in pixels, drawn as a squircle where the browser supports corner-shape.
- `captionPosition?: "bottom-left" | "bottom-right" | "top-left" | "top-right"` = "bottom-left": The corner the caption pill sits in, 12px from the edges.
- `captionColor?: string` = "rgba(0, 0, 0, 0.45)": Any CSS color for the caption pill, drawn over a blur.
- `shimmer?: boolean` = true: Sweeps a highlight across the caption text while the image is on its way. Off (and under reduced motion) the text is plain white at 75%.
- `src?: string | null`: Image to reveal. Keep it null while the image is generating, since the grid only runs while this is empty and a src that is already loaded makes the whole run flash by. Cross-origin images need CORS headers for the color pass; without them the grid stays grey and the photo still fades in.
- `progress?: number`: Position of the wait from 0 to 1, driving how far the grid has split. It holds at 0.72 until the image decodes, and the image landing is what finishes the reveal. Leave it out to pace by estimatedDuration.
- `onRevealComplete?: () => void`: Fires once the image has fully resolved.
- `onError?: () => void`: Fires when the image fails to load. Without it a broken src leaves the grid waiting, so use it to show your own fallback.
- `className?: string`: Extra classes merged onto the root element (data-slot="grid-reveal"). Other div props are spread onto it too.
- `style?: React.CSSProperties`: Inline styles merged after the aspect ratio, so an aspectRatio here overrides the aspect prop.

```tsx
"use client"

import { useState } from "react"
import GridReveal from "@/components/ui/grid-reveal"

export function Demo() {
  const [src, setSrc] = useState<string | null>(null)

  async function generate() {
    setSrc(null)                   // null is the waiting state, the grid runs while it is empty
    setSrc(await createImage())    // setting it resolves the grid into the picture
  }

  return (
    // the frame fills its parent, so give the parent a width
    <div className="w-64">
      <GridReveal src={src} alt="Generated image" caption="Creating image" />
      <button onClick={generate}>Generate</button>
    </div>
  )
}

// Passing a src that is already loaded skips the wait, so the run flashes by.
// Pass progress when your API reports it: <GridReveal src={src} progress={job.progress} />
```

Docs: https://wingo-ui.com/components/grid-reveal (Markdown: https://wingo-ui.com/components/grid-reveal.md)

#### Matrix Orb (`matrix-orb`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add matrix-orb`

A dot-matrix orb that animates through idle, listening and thinking states.

Switch the orb between its idle, listening and thinking states. Idle breathes softly, listening ripples out from the center and blooms with the level, thinking sends bright spots orbiting through the grid. Changing state mid-animation blends from whatever is on screen while the orb springs to its new scale, and the caption below updates for screen readers. Honors prefers-reduced-motion by drawing a still frame per state.
Wingo UI dependencies: ui-config

Props:
- `state?: "idle" | "listening" | "thinking"` = "idle": Which animation the orb plays. Changes blend in place instead of restarting the loop.
- `size?: number` = 240: Diameter of the orb in pixels. The dot grid spans 74% of it and the canvas tracks devicePixelRatio, so zooming stays sharp.
- `color?: string` = "#F75001": Any CSS color for the dots.
- `dots?: number` = 11: How many dots across the grid. Rounded, with a minimum of 3; dots outside the circle are skipped so the outline stays round.
- `speed?: number` = 1: How fast the ripples and orbiters move: 1 is the original pace, 0 holds still. Changing it bends the motion without a restart.
- `spread?: number` = 0.74: Share of the canvas the dot grid covers, 0.2 to 1.
- `dotScale?: number` = 0.6: Largest dot radius as a share of the spacing between dots; above 0.5 neighbours touch at full intensity.
- `showLabel?: boolean` = true: Shows the state caption under the orb. Hidden, it stays in the page as a screen reader status.
- `level?: number`: How far the orb blooms while listening, 0 to 1 (clamped), for example a live microphone level. Leave it out and a built-in envelope drives the bloom.
- `labels?: Partial<Record<MatrixOrbState, string>>`: Caption under the orb, per state. Missing keys fall back to "Idle", "Listening" and "Thinking".
- `className?: string`: Extra classes merged onto the root element (data-slot="matrix-orb", with data-state set to the current state). Other div props are spread onto it too.

```tsx
"use client"

import { useState } from "react"
import MatrixOrb, { type MatrixOrbState } from "@/components/ui/matrix-orb"

export function Demo() {
  const [state, setState] = useState<MatrixOrbState>("idle")

  return (
    <MatrixOrb
      state={state}
      onClick={() => setState(state === "idle" ? "listening" : "idle")}
      className="cursor-pointer"
    />
  )
}

// drive the bloom yourself with any value from 0 to 1
// <MatrixOrb state="listening" level={level} />
```

Docs: https://wingo-ui.com/components/matrix-orb (Markdown: https://wingo-ui.com/components/matrix-orb.md)

#### Model Picker (`model-picker`)

component · Pro · v1.0.1 · install: `npx wingo-ui@latest add model-picker`

A model switcher for AI chats: a quiet trigger that opens a short grouped list of models, each with its name and one line on what it is for.

Click or tap the trigger ("Northwind Standard" with a chevron) to open the list; the chevron turns over on a quick spring. On desktop it is a popover that opens upward from a composer, grouped by model group with sticky section labels; each row shows the model's icon, its name with New / Recommended badges and one line of description; showCapabilities, showSpeed, showCost and showContext add a line of capability icons, speed and cost meters and the context window, whose icons and meters name themselves on hover. Click a row to pick it: the check draws, the list closes and onValueChange gets the id and the model. Locked models stay in the list, dimmed with a lock and the reason as their description, and cannot be picked. Above 8 models (or with search="always") a search row sits on top and takes focus: it matches names, makers, groups, capability names and keywords, ignores case and diacritics and bolds the matched letters. Keyboard: Tab reaches the trigger; Enter, Space or ArrowDown open it on the chosen model, ArrowUp and ArrowDown move, Home and End jump to the ends, typing letters jumps by name, Enter picks, Escape or Tab close and focus stays on the trigger. While closed, letters pick the next model by name like a native select. With shortcut ("mod+.") the list toggles from anywhere on the page, the tooltip shows the keys, and a model picked after the shortcut sends focus back where you were typing. On a phone the list is a bottom sheet titled "Model" with 64px rows, two-line descriptions and no tooltips; a tap picks and closes it, a drag down or a tap outside dismisses it. With reduced motion the chevron flips without the spring and the list fades instead of scaling.

npm: motion, lucide-react
Wingo UI dependencies: select, badge, tooltip, spinner, field, ai-chat, text-match, use-controllable-state, use-locale, use-media-query, use-shortcut, motion, tones, ui-config

Props:
- `models: AiModel[]`: The models: { id, name, provider?, description?, icon?, group?, capabilities?, contextWindow?, speed?: 1 | 2 | 3, cost?: 1 | 2 | 3, pricing?, badge?: { label, tone? }, recommended?, isNew?, disabled?, disabledReason?, keywords? } from lib/ai-chat. A repeated id keeps its first model (with a warning while developing).
- `value?: string`: The chosen model's id, controlled. "" shows the placeholder, and so does an id that is not among the models; the picker never replaces it on its own.
- `defaultValue?: string` = "": The starting model while uncontrolled. "" is automatic: the first recommended model, else the first enabled one (it follows models that arrive later).
- `onValueChange?: (id: string, model: AiModel) => void`: Called with the id and the whole model after a pick or a typeahead jump. Never called for the automatic default.
- `defaultOpen?: boolean` = false: Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.
- `open?: boolean`: Whether the list is open, controlled. It never opens while disabled.
- `onOpenChange?: (open: boolean) => void`: Called when the list opens or closes.
- `disabled?: boolean` = false: Dims the trigger; it never opens and the shortcut does nothing. A disabled Field around it does the same.
- `loading?: boolean` = false: Models are on their way: a spinner replaces the chevron and the list shows a loading row until models arrive.
- `variant?: "ghost" | "soft" | "outline"` = "ghost": ghost for composers and toolbars (a tint on hover and while open); soft and outline copy the field box, so the picker lines up with inputs and selects in a form.
- `size?: "sm" | "md" | "lg"` = "sm": Trigger height 32 / 40 / 48px with matching text and icons. md grows to 44px on touch, sm keeps its look with a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": The trigger's corners, scaled per size like the button; full is a pill.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Paints the trigger's text, tint and border in a tone. neutral keeps the field look; brand is for the one place a premium model should stand out.
- `color?: string` = "": Any CSS color for the trigger; replaces the tone. Leave empty to use the tone.
- `showIcon?: boolean` = true: The chosen model's icon before its name in the trigger (when the model has one).
- `showProvider?: boolean` = false: The provider before the name in the trigger: "Northwind AI · Standard" (a name that repeats the maker is shortened).
- `showCapabilities?: boolean` = false: The row of capability icons in each option (vision, tools, reasoning, web, files, code, image, voice), each with a tooltip.
- `showSpeed?: boolean` = false: The 3-step speed meter in each option.
- `showCost?: boolean` = false: The 3-step cost meter in each option.
- `showContext?: boolean` = false: The context window in each option ("200K context"), formatted for the locale.
- `showDescription?: boolean` = true: One line of description in the menu, two in the phone sheet. A locked model shows its reason either way.
- `fullWidth?: boolean` = false: Stretches the trigger to its container with the chevron at the end, the usual choice as a form field.
- `contentWidth?: number` = 320: The list's width on desktop in px (never narrower than the trigger, never wider than the screen).
- `maxHeight?: number` = 560: The list's maximum height on desktop in px, capped by the room on screen; longer lists scroll with sticky group labels.
- `side?: "top" | "right" | "bottom" | "left"` = "top": Where the list opens. Composers sit low on the screen, so it opens upward; it flips when there is no room.
- `align?: "start" | "center" | "end"` = "start": How the list lines up with the trigger.
- `container?: HTMLElement | null`: Where the list or the sheet is portaled (document.body by default).
- `groupBy?: "group" | "provider" | "none"` = "group": List sections: by model.group, by model.provider, or one flat list. Models without one go last, under a separator with no visible label.
- `search?: "auto" | "always" | "never"` = "auto": The search row on top of the list: auto shows it above 8 models. It matches names, providers, groups, capability names and keywords, diacritics ignored.
- `responsive?: boolean` = true: A bottom sheet with 64px rows and two-line descriptions below 768px instead of the popover.
- `shortcut?: string` = "": A key combo in mod+k notation that toggles the list from anywhere ("mod+." is Cmd+. on a Mac, Ctrl+. elsewhere). Shown in the trigger's tooltip and set as aria-keyshortcuts. Empty binds nothing.
- `name?: string` = "": Renders a hidden native select with this name, so FormData and form reset work.
- `locale?: string` = "": The locale of the context window numbers ("200K" in en-US, "200 K" and "1 mil." in ro-RO). Empty uses the UIProvider's, then the browser's.
- `labels?: Partial<ModelPickerLabels>`: Every string, English by default (DEFAULT_MODEL_PICKER_LABELS): placeholder "Choose a model", trigger "Model" (the accessible name is "Model: Northwind Standard"), tooltip "Switch model", search "Search models", empty "No models found", loading, sheetTitle "Model", recommended, new, context (formatted) => "200K context", speed ["Slower", "Fast", "Fastest"], cost ["Low cost", "Medium cost", "High cost"], unavailable, ungrouped, results (count) => string, clearSearch, capabilities (DEFAULT_AI_CAPABILITY_LABELS).
- `classNames?: Partial<Record<"trigger" | "icon" | "provider" | "name" | "chevron" | "content" | "search" | "group" | "option" | "badges" | "description" | "meta" | "capabilities", string>>`: Extra classes for the inner parts: the trigger and its pieces, the list surface (content), its search row and group labels, and the parts of each option.
- `className?: string`: Extra classes for the trigger button, merged last. Other props (aria-*, data-*, onClick, onBlur, id, form, ref) go there too.

Parts:
- `ModelPickerOption` (component): The rich row on its own, for other lists (a command menu, a settings table): icon tile or provider initials, name and badges, description, capabilities, meters and context, a lock for locked models. Props: { model, density?: "menu" | "sheet", ranges?, showCapabilities?, showSpeed?, showCost?, showContext?, showDescription?, tooltips?, locale?, labels?, classNames?, ...div }.
- `ModelCapabilities` (component): The capability icons as a list; each name is in a tooltip on fine pointers and always there for screen readers. Props: { capabilities: AiCapability[], labels?, tooltips?, size?: "sm" | "md", classNames?, ...ul }.
- `ModelMeter` (component): The 3-step speed or cost indicator: a Zap or Coins glyph and three bars, role="img" with the level's name. Props: { value: 1 | 2 | 3, kind?: "speed" | "cost", label?, icon?, tooltip?, classNames?, ...span }.
- `toModelOptions` (function): Models to select / listbox options, grouped, with provider, group and capability names as search keywords. Pair it with ModelPickerOption in a Listbox or Combobox renderOption. Signature: (models: AiModel[], { groupBy?, showDescription?, labels? }) => SelectItems.
- `DEFAULT_MODEL_PICKER_LABELS` (constant): The English strings, to spread and override. Type: ModelPickerLabels.

```tsx
import { useState } from "react"
import { Feather, Gem, Sparkles } from "lucide-react"
import { ModelPicker, type AiModel } from "@/components/ui/model-picker"

const MODELS: AiModel[] = [
  { id: "swift", name: "Northwind Swift", group: "Northwind AI", description: "Short answers, almost instant", icon: <Feather />, capabilities: ["tools", "files"], contextWindow: 128_000, speed: 3, cost: 1 },
  { id: "standard", name: "Northwind Standard", group: "Northwind AI", description: "Balanced, for everyday work", icon: <Sparkles />, capabilities: ["vision", "tools", "files", "web"], contextWindow: 200_000, speed: 2, cost: 2, recommended: true },
  { id: "pro", name: "Northwind Pro", group: "Northwind AI", description: "Deep reasoning for analysis and reports", icon: <Gem />, capabilities: ["reasoning", "tools", "web", "files", "code", "vision"], contextWindow: 200_000, speed: 1, cost: 3, isNew: true },
]

export function ChatModel() {
  const [model, setModel] = useState("standard")
  return (
    <ModelPicker
      models={MODELS}
      value={model}
      onValueChange={(id) => setModel(id)}
      shortcut="mod+."
      labels={{ placeholder: "Pick a model", sheetTitle: "Switch model" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/model-picker (Markdown: https://wingo-ui.com/components/model-picker.md)

#### Prompt Input (`prompt-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add prompt-input`

The AI chat composer: a growing text box with attachments, tool chips, a model picker, dictation and one round send / stop button.

Type and the box grows up to maxRows, then scrolls. With a keyboard Enter sends and Shift+Enter makes a new line (with submitShortcut mod+enter, Enter is a new line and Cmd/Ctrl+Enter sends); an IME composition is confirmed by Enter, never sent. On a phone Enter always makes a new line and the round button sends without closing the keyboard. Press + for Upload files (and Take a photo on touch); drop files anywhere on the composer (a dashed overlay shows where) or paste a screenshot. Images show thumbnails, files a colored type tile; uploads show a progress ring, failures a retry button, and every attachment has a remove button (Backspace in an empty box jumps to the last one, Backspace again removes it). Tool chips toggle with a click (in a composer narrower than 512px, a phone or a side panel, they live in the + menu, a bottom sheet on phones, and active ones stay visible); the model name opens the model list (a bottom sheet on phones). The mic dictates at the caret: finished words land in the text, words still being heard stay muted in the voice pill. While the answer streams the button is Stop (and stopShortcut; a bare key like Escape works while focus is in the composer); ArrowUp in an empty box edits the last message; focusShortcut (e.g. Shift+Escape) focuses the box from anywhere. Past 80% of maxLength or tokenLimit a counter appears and turns red past the limit, which blocks sending.

npm: motion, lucide-react
Wingo UI dependencies: textarea, button, toggle, tooltip, dropdown-menu, progress, spinner, file-upload, file-types, model-picker, voice-input, ai-chat, use-keyboard-inset, use-controllable-state, use-media-query, use-scroll-edges, use-shortcut, use-locale, number-format, haptics, motion, tones, ui-config

Props:
- `defaultValue?: string` = "": Starting text while uncontrolled. Use value / onValueChange to control it; a rejected onSubmit restores the text through onValueChange.
- `value?: string`: The text, controlled. Pair it with onValueChange.
- `onValueChange?: (value: string) => void`: The new text on every change, dictation and restores included.
- `onSubmit?: (message: PromptInputMessage) => (void | Promise<unknown>)`: Runs on Enter or the button when there is text or a ready attachment: { text (trimmed), attachments (ready or local), model, tools }. The composer clears at once and keeps focus; if the promise rejects, the text and files come back and an error is announced.
- `status?: "idle" | "submitting" | "streaming"` = "idle": submitting: the button spins; streaming: it becomes Stop. Sending is blocked while not idle, typing is not.
- `onStop?: () => void`: The Stop button and stopShortcut while status is streaming.
- `placeholder?: string` = "Ask anything": Also the textarea's accessible name unless aria-labelledby is passed.
- `variant?: "elevated" | "outline" | "soft"` = "elevated": elevated: a floating white panel with a soft shadow (ChatGPT); outline: a bordered field; soft: the filled well of the form fields.
- `size?: "sm" | "md" | "lg"` = "md": Text 14 / 15 / 16px (16px on phones always, so iOS never zooms), toolbar buttons 28 / 32 / 36px, padding 8 / 10 / 12px.
- `radius?: "md" | "lg" | "full"` = "lg": md 16px, lg 24px; full is a 28px pill while the text is one line and 24px once it grows or holds attachments.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The send button, active tool chips and the focus ring's tint. Brand orange is opt-in.
- `color?: string` = "": Any CSS color; replaces the tone. Text on the send button turns black or white by lightness.
- `minRows?: number` = 1: Height of the empty text area in rows.
- `maxRows?: number` = 8: Grows with the text up to this many rows, then scrolls (native field-sizing, no JS per keystroke).
- `position?: "static" | "sticky" | "fixed"` = "static": fixed: pinned to the viewport bottom, lifted above the on-screen keyboard without re-rendering, safe-area padded, and writes its height as --prompt-input-offset on <html> so the page can pad its content; sticky: the bottom of its scroll parent (inside a chat thread). Both center the box in a 768px reading column over a fade.
- `safeArea?: boolean` = true: Pads the bottom by the home-indicator inset (at least 12px) when fixed or sticky.
- `submitShortcut?: "enter" | "mod+enter"` = "enter": enter: Enter sends and Shift+Enter makes a new line on fine pointers (touch keyboards always insert a new line); mod+enter: Enter is a new line and Cmd/Ctrl+Enter sends. Cmd/Ctrl+Enter always sends.
- `maxLength?: number` = 0: A soft character limit: the counter appears near it and turns red past it, and sending is blocked until the text is shorter. 0 = none.
- `tokenLimit?: number` = 0: Estimated tokens (estimateTokens): the hint reads "1,2 K / 8 K tokens" near the limit. 0 = none.
- `showCount?: "auto" | "always" | "never"` = "auto": auto: the hint appears past 80% of maxLength / tokenLimit (warning), and turns danger past 100%; always: always shown (the token estimate without a limit); never: hidden, the limit still blocks.
- `allowAttachments?: boolean` = true: The + button, drop and paste of files.
- `accept?: string` = "image/*,application/pdf,.doc,.docx,.xls,.xlsx,.csv,.txt,.md,.json": Allowed types, like the input's accept attribute; checked by mime type and by extension.
- `maxFiles?: number` = 10: At most this many attachments; extra files are rejected with one message.
- `maxFileSize?: number` = 20971520: Bytes per file (20 MB).
- `camera?: boolean` = true: A "Take a photo" entry (capture="environment") in the + menu on touch devices.
- `voice?: boolean` = false: A dictation button (VoiceInput). Its transcript goes in at the caret, replacing a selection; while recording the voice pill takes the toolbar.
- `focusShortcut?: string` = "": Focuses the box from anywhere and puts the caret at the end, e.g. "shift+escape". Empty binds nothing.
- `stopShortcut?: string` = "": Stops a streaming reply, e.g. "escape". A bare key works while focus is in the composer (so a page dialog keeps its Escape), a combo like "mod+shift+x" works anywhere; an open menu or model list closes first. Empty binds nothing.
- `autoFocus?: boolean` = false: Focuses the box on mount on desktops only; a phone keyboard never pops up by surprise.
- `disabled?: boolean` = false: Dims and blocks the box and every toolbar control.
- `name?: string` = "": The textarea's name for forms.
- `locale?: string` = "": Number formatting of sizes, percentages and token counts (12.5K in en-US). Empty uses the UIProvider locale, then the browser's.
- `attachments?: ChatAttachment[]`: Controlled attachments ({ id, name, type, size, url, previewUrl, status, progress, error }). Pair it with onAttachmentsChange.
- `defaultAttachments?: ChatAttachment[]` = "[]": Starting attachments while uncontrolled (a restored draft).
- `onAttachmentsChange?: (attachments: ChatAttachment[]) => void`: Every add, progress step, finish, failure and removal.
- `onUpload?: (file: File, { signal, onProgress }) => Promise<unknown>`: Uploads each added file with progress (0..1, one render per 100ms at most); resolve with a url string or { url } to set attachment.url. Removing a file aborts through the signal, Retry runs it again. Without it attachments stay local, with object-URL previews revoked on removal and unmount.
- `onRetry?: (attachment: ChatAttachment) => void`: Retry on a failed attachment the composer holds no File for (restored from a draft or added by the app).
- `models?: AiModel[]`: Shows a ModelPicker (ghost, opening upward; a bottom sheet on phones) in the toolbar.
- `model?: string`: The chosen model id, controlled. Uncontrolled it starts at defaultModel, else the first recommended model.
- `defaultModel?: string` = "": Starting model id while uncontrolled. Empty starts at the first recommended model (Acme Standard in the demo).
- `onModelChange?: (model: string) => void`: A model was picked.
- `tools?: PromptTool[]`: Toggle chips in the toolbar ({ id, label, icon, description, disabled }); in a composer narrower than 512px they move into the + menu (a sheet on phones) as checkbox rows and only active ones stay in the toolbar; under 672px the chips show as round icons with the name in a tooltip.
- `activeTools?: string[]`: Active tool ids, controlled.
- `defaultActiveTools?: string[]` = "[]": Active tool ids while uncontrolled.
- `onActiveToolsChange?: (tools: string[]) => void`: A tool was switched on or off (ids in the order of tools).
- `onVoice?: (result: VoiceInputResult) => (void | Promise<unknown>)`: Makes the mic send audio messages (the blob and transcript) instead of dictating into the box.
- `onEditLast?: () => void`: ArrowUp in an empty box with the caret at the start: edit the last message.
- `toolbarStart?: ReactNode`: Extra controls after the model picker (a project picker).
- `toolbarEnd?: ReactNode`: Extra controls before the mic (a usage ring).
- `labels?: Partial<PromptInputLabels>`: Every string: placeholder, send, stop, attach, upload, photo, tools, cancel, attachments, remove(name), retry, uploading(name, percent), progress(percent), uploadFailed, drop, tooMany(max), tooLarge(name, max), typeNotAllowed(name), tokens(used, limit), tokenCount(used), characters(count, max), overLimit, newlineHint, attached(name), removed(name), sendFailed.
- `modelPickerProps?: Partial<ModelPickerProps>`: Passed to the model picker: labels, shortcut, groupBy, showSpeed.
- `voiceInputProps?: Partial<VoiceInputProps>`: Passed to the voice button: labels, lang, maxDuration, mode.
- `classNames?: Partial<Record<"box" | "textarea" | "attachments" | "attachment" | "toolbar" | "submit" | "hint" | "drop", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last. Other props (id, aria-*, data-*) go there too.

Parts:
- `PromptInputAttachments` (component): The attachment rail on its own: thumbnails and file tiles with size, progress ring, error and retry, and a remove button each; a horizontal rail with edge fades. Props: { attachments, onRemove?(attachment, { keyboard }), onRetry?, size?, locale?, disabled?, labels?, classNames?, ...ul }.
- `PromptInputSubmit` (component): The round send button: an arrow, a spinner while submitting, a Stop square while streaming; dimmed but focusable (aria-disabled) with nothing to send. Props: { status?, canSubmit?, onStop?, size?, shortcut?, tooltip?, labels?, ...ButtonProps }.
- `PromptInputTool` (component): A tool chip: an outline pill toggle with aria-pressed and an optional tooltip. Props: { label, icon?, description?, size?, ...ToggleProps }.
- `readAttachments` (function): Validates picked, dropped or pasted files by type (mime or extension), size and count, with object-URL previews for images. Call it from an event handler. Signature: (files, { accept?, maxFiles?, maxFileSize?, current?, preview? }) => { accepted: ChatAttachment[]; rejected: { file; reason: "type" | "size" | "count" }[]; files: Map<string, File> }.
- `DEFAULT_PROMPT_INPUT_LABELS` (constant): The English strings, to spread and override. Type: PromptInputLabels.

```tsx
"use client"

import { useState } from "react"
import { Brain, Database, Globe, Sparkles, Gem } from "lucide-react"
import { PromptInput, type AiModel, type PromptInputMessage, type PromptInputStatus, type PromptTool } from "@/components/ui/prompt-input"

const MODELS: AiModel[] = [
  { id: "standard", name: "Acme Standard", group: "Acme AI", description: "Balanced, for everyday work", icon: <Sparkles />, recommended: true },
  { id: "pro", name: "Acme Pro", group: "Acme AI", description: "Deep reasoning for analysis and reports", icon: <Gem />, isNew: true },
]

const TOOLS: PromptTool[] = [
  { id: "web", label: "Web search", icon: <Globe /> },
  { id: "reasoning", label: "Extended thinking", icon: <Brain /> },
  { id: "crm", label: "CRM data", icon: <Database /> },
]

export function Composer({ ask, stop }: { ask: (message: PromptInputMessage) => Promise<void>; stop: () => void }) {
  const [status, setStatus] = useState<PromptInputStatus>("idle")

  async function send(message: PromptInputMessage) {
    setStatus("streaming")
    try {
      await ask(message)
    } finally {
      setStatus("idle")
    }
  }

  async function upload(file: File, { signal, onProgress }: { signal: AbortSignal; onProgress: (fraction: number) => void }) {
    const body = new FormData()
    body.append("file", file)
    onProgress(0.5)
    const response = await fetch("/api/files", { method: "POST", body, signal })
    if (!response.ok) throw new Error("Upload failed")
    return (await response.json()) as { url: string }
  }

  return (
    <PromptInput
      models={MODELS}
      tools={TOOLS}
      defaultActiveTools={["crm"]}
      voice
      status={status}
      onSubmit={send}
      onStop={stop}
      onUpload={upload}
      stopShortcut="escape"
      focusShortcut="shift+escape"
      labels={{ placeholder: "Ask the Acme assistant" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/prompt-input (Markdown: https://wingo-ui.com/components/prompt-input.md)

#### Reasoning Indicator (`reasoning-indicator`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add reasoning-indicator`

The model's thinking, kept out of the way: a shimmering live timer while it thinks, then a quiet "Thought for 12 s" to expand.

While the model thinks, the label shimmers, a timer counts up in tenths and then whole seconds, and the last two lines of the thought slide up under it. Tap or click the row or the peek (or Tab to the row and press Enter or Space) to open the full reasoning: it follows the newest thought while it streams, and scrolling up inside it lets go. When thinking ends the row settles on "Thought for 12 s" and closes again if it was open from the start; if you opened it yourself it stays open. On a phone the row keeps a 44px hit area and the open body never grows past 40% of the screen.

npm: motion, lucide-react
Wingo UI dependencies: markdown, use-stick-to-bottom, ai-chat, use-controllable-state, use-locale, motion, tones, ui-config

Props:
- `content?: string` = "": The reasoning as markdown. Empty with no children: the row is plain text, with nothing to open.
- `children?: ReactNode`: Replaces the markdown body, e.g. a list of searched sites or steps.
- `label?: ReactNode` = "": Replaces the default label in any state, e.g. "Searching the web" while a phase runs, or labels.stopped(duration) for a stopped message. Leave empty for thinking / thought.
- `icon?: ReactNode` = "<Brain />": The 16px icon before the label (a Globe for a web search).
- `showIcon?: boolean` = true: Shows the icon before the label.
- `showDuration?: boolean` = true: The live timer while thinking and the time in the done label. Off: the done label reads labels.thoughtBriefly.
- `variant?: "ghost" | "soft" | "outline"` = "ghost": ghost is a flush text row for messages; soft and outline wrap the row and the body in a rounded box for standalone use.
- `size?: "sm" | "md"` = "md": The row is 28 / 32px tall with 13 / 14px text. The body is small markdown either way.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the rail beside the body and the icon while thinking. Neutral uses the foreground.
- `color?: string` = "": Any CSS color. Replaces the tone.
- `shimmer?: boolean` = true: The moving highlight on the label and the icon pulse while thinking. Off (and under reduced motion) the label stays still and muted.
- `maxHeight?: number` = 320: Pixels of open body before it scrolls inside. On a phone it is also capped at 40dvh. 0 lets it grow.
- `streaming?: boolean` = false: Thinking now: shimmer, live timer, the two-line peek and the body following new text.
- `defaultOpen?: boolean` = false: Starts open (uncontrolled).
- `open?: boolean`: Controls the disclosure. Pair with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Called when the person toggles it or autoCollapse closes it.
- `startedAt?: Date | string | number`: When thinking began. While streaming the timer counts from here; a second phase continues from it.
- `endedAt?: Date | string | number`: When thinking ended. Before startedAt counts as 0. Without timing data the done label says labels.thoughtBriefly.
- `durationMs?: number`: The final duration, when known; wins over startedAt / endedAt once done.
- `autoCollapse?: boolean` = true: When thinking ends, closes again if it was open when the stream started and nobody touched it. A row the person opened stays open.
- `peek?: boolean` = true: Shows the last two lines of the thought under the label while it streams and the row is closed.
- `locale?: string` = "": Formats the duration ("12 s", "2 min. 5 s"). Empty uses UIProvider, then the browser.
- `now?: Date | number`: Pins the clock for screenshots and tests. By default a shared ticker runs only while streaming.
- `labels?: Partial<ReasoningIndicatorLabels>`: thinking "Thinking", thought (duration) => "Thought for 12 s", thoughtBriefly "Thought for a few seconds", stopped (duration) => "Stopped after 3 s", show "Show reasoning", hide "Hide reasoning" (sr-only on the trigger). DEFAULT_REASONING_INDICATOR_LABELS exports the English set.
- `classNames?: Partial<Record<"trigger" | "icon" | "label" | "duration" | "peek" | "content" | "body", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { ReasoningIndicator } from "@/components/ui/reasoning-indicator"

const labels = {
  thinking: "Working on it",
  thought: (duration: string) => `Worked for ${duration}`,
}

export function Thinking({ text, streaming, startedAt, endedAt }: { text: string; streaming: boolean; startedAt: number; endedAt?: number }) {
  return (
    <ReasoningIndicator
      content={text}
      streaming={streaming}
      startedAt={startedAt}
      endedAt={endedAt}
      labels={labels}
    />
  )
}
```

Docs: https://wingo-ui.com/components/reasoning-indicator (Markdown: https://wingo-ui.com/components/reasoning-indicator.md)

#### Rule Builder (`rule-builder`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add rule-builder`

An if-this-then-that editor for automations: a trigger, conditions and ordered actions as sentence cards, read back as one sentence.

Pick a trigger from the dashed card, then press any step card to edit it: on a desktop the editor opens under the card, on a phone it rises as a bottom sheet. Edits are drafts: Apply, or Enter in a one-line field, saves them; Cancel, Escape or closing the sheet throws them away, and Apply stays dimmed until the required fields are filled (pressing it anyway points at them). Add conditions from the trigger's fields and choose whether all or any must match; add actions from the catalog and reorder them by dragging the grip (on a phone only the grip drags, the rest of the card scrolls the page), with Alt+Up or Alt+Down on a card, or with Space, the arrows and Space again on the grip. Each card's more button offers Edit, Duplicate, Move up, Move down and Remove (the trigger's offers Change trigger). Up, Down, Home and End move between the cards, Tab reaches a card's grip and more button. The header switch turns the rule on or off, and a stopped rule's cards dim; Test runs onTest and shows each action's outcome under the summary, which reads the whole rule as one sentence.

npm: @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, motion, lucide-react
Wingo UI dependencies: button, currency-input, drawer, dropdown-menu, field, input, multi-select, number-input, segmented-control, select, switch, textarea, use-controllable-state, use-locale, use-media-query, ai-chat, commerce, filters, motion, number-format, tones, ui-config

Props:
- `triggers: RuleTriggerDef[]`: The trigger catalog: { type, label, description?, icon?, group?, params?, fields?, summary? }. fields are the lib/filters fields the conditions can test (an invoice, a deal, a lead); summary(params) says the trigger in a sentence with values wrapped in **, like "an invoice is **30 days** overdue".
- `actionTypes: RuleActionDef[]`: The action catalog: { type, label, description?, icon?, group?, tone?, params?, summary?, multiple? }. tone colors the icon tile; multiple: false allows the action once per rule, so it leaves the picker once used. Named actionTypes because actions is the value's list.
- `title?: ReactNode` = "": The rule's name in the header. It also names the switch, so a screen reader hears which rule turns on or off.
- `value?: RuleValue`: The rule: { trigger: { type, params } | null, conditions: FilterGroup, actions: { id, type, params }[] }. conditions is the lib/filters group a saved view or filter-builder uses, root level only.
- `defaultValue?: RuleValue`: The starting rule while uncontrolled; an empty rule (createRule()) when left out.
- `onValueChange?: (value: RuleValue) => void`: Every applied change: an editor's Apply, a picked trigger, an added, duplicated, moved or removed step, the all / any switch. Drafts in an open editor never reach it.
- `enabled?: boolean`: Controlled state of the header switch; pair it with onEnabledChange.
- `defaultEnabled?: boolean` = true: Whether the rule starts switched on. A switched off rule's cards dim to 60%.
- `onEnabledChange?: (enabled: boolean) => void`: Fires when the header switch flips.
- `readOnly?: boolean` = false: Summaries only: cards without editors, menus, grips or add buttons, and a switch that shows its state. Test still works.
- `disabled?: boolean` = false: Dims and locks everything: cards, menus, grips, add buttons, the switch and Test.
- `onTest?: (value: RuleValue) => Promise<RuleTestResult>`: Shows the Test button. While the promise runs the button spins; the result ({ matched, message?, steps?: { actionId, ok, message? }[] }) appears under the summary with each action's outcome, and any edit clears it. A rejection shows labels.testFailed.
- `allowOr?: boolean` = true: Lets the conditions match any instead of all: an all / any switch appears once there are two conditions. Off, conditions always join with and.
- `maxActions?: number` = 0: The most actions a rule may have; the add button hides at the limit. A value below the current count removes nothing. 0 means no limit.
- `validate?: "always" | "touched" | "never"` = "touched": When issues show on the cards (a red ring and a line saying what is missing): always, only after a step was edited once, or never (the app validates with validateRule).
- `responsive?: boolean` = true: Below 768px the step editors, the trigger, field and action pickers and the card menus open as bottom sheets. Off, phones get the desktop editor under the card.
- `showSummary?: boolean` = true: The dashed box that reads the whole rule as one sentence, values in bold.
- `summaryPosition?: "top" | "bottom"` = "bottom": Where the sentence sits: under the header or after the actions.
- `size?: "sm" | "md"` = "md": Step cards 48 / 56px tall with 28 / 32px icon tiles, and sm / md fields in the desktop editors. On touch screens every card is at least 56px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the section pills (When, If, Then), the rails between them, the action numbers and the switch. neutral uses foreground tints.
- `color?: string` = "": Any CSS color; replaces the tone for the pills, rails, numbers and switch. Leave empty to use the tone.
- `currency?: string` = "USD": ISO 4217 code for currency params and currency fields that do not set their own; amounts read like $5,000.
- `locale?: string` = "": Formats numbers, money and dates in cards, fields and the sentence (en-US: $5,000). Empty uses the UIProvider's locale, then the browser's.
- `labels?: RuleBuilderLabelsInput`: Every visible and spoken string, merged over DEFAULT_RULE_BUILDER_LABELS: when, if, then, chooseTrigger, chooseAction, chooseField, addCondition, addAction, all, any, matchAll, matchAny, match, noConditions, noActions, edit, duplicate, moveUp, moveDown, remove, change, more, apply, cancel, required, back, enabled, test, testing, matched, notMatched, testFailed, stepOk, stepFailed, dismiss, summary, summaryEmpty, trigger, condition, field, operator, value, from, to, choose, search, noResults, daysUnit, days(count, formatted), unknownTrigger, unknownAction, unknownField, fieldUnavailable, incomplete, missing(label), sentence { when, if, then, and, or, comma, nothing }, operators (per filter operator), dragHandle(label), dragInstructions and announce { added, removed, moved, pickedUp, cancelled, pruned }.
- `classNames?: Partial<Record<"header" | "title" | "enabled" | "test" | "section" | "sectionLabel" | "rail" | "steps" | "step" | "stepButton" | "stepIcon" | "stepNumber" | "stepSummary" | "stepIssue" | "stepMenu" | "stepHandle" | "joiner" | "editor" | "editorFooter" | "combinator" | "add" | "empty" | "summary" | "testResult" | "sheet", string>>`: Extra classes for the inner parts; step is the card, stepButton the stretched button that opens its editor, sheet the phone editor.
- `className?: string`: Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone-soft:...].

Parts:
- `describeRule` (function): The rule as one plain sentence, the same one the summary box shows: "When an invoice is 30 days overdue, if Amount ≥ $5,000, then …". Only complete conditions are read. Use it for notifications, logs and the automation list. Signature: (value: RuleValue, options: { triggers; actions; locale?; currency?; labels? }) => string.
- `validateRule` (function): What keeps the rule from running, as { path: "trigger" | `conditions.${id}` | `actions.${id}`, message }: a missing or unknown trigger, incomplete conditions or conditions on fields the trigger lacks, unknown actions and required params left empty. Signature: (value: RuleValue, options: { triggers; actions; labels? }) => RuleIssue[].
- `createRule` (function): An empty rule (no trigger, an and group with no conditions, no actions). Call it in handlers or state initializers. Signature: (overrides?: Partial<RuleValue>) => RuleValue.
- `DEFAULT_RULE_BUILDER_LABELS` (constant): The English strings, to spread and override. Type: RuleBuilderLabels.

```tsx
import { useState } from "react"
import { FileWarning, Mail, Tag } from "lucide-react"
import {
  RuleBuilder,
  describeRule,
  type RuleActionDef,
  type RuleTriggerDef,
  type RuleValue,
} from "@/components/ui/rule-builder"

const days = (count: number) => (count === 1 ? "1 day" : `${count} days`)

const triggers: RuleTriggerDef[] = [
  {
    type: "invoice-overdue",
    label: "Invoice overdue",
    icon: <FileWarning />,
    params: [{ id: "days", label: "After", type: "days", required: true, defaultValue: 30 }],
    fields: [
      { id: "amount", label: "Amount", type: "currency" },
      {
        id: "city",
        label: "City",
        type: "select",
        options: [
          { value: "Austin", label: "Austin" },
          { value: "Portland", label: "Portland" },
        ],
      },
    ],
    summary: (params) => `an invoice is **${days(Number(params.days))}** overdue`,
  },
]

const actions: RuleActionDef[] = [
  {
    type: "send-email",
    label: "Send email",
    icon: <Mail />,
    tone: "info",
    params: [
      {
        id: "template",
        label: "Template",
        type: "select",
        required: true,
        options: [{ value: "final-notice", label: "Final notice" }],
      },
    ],
    summary: () => "send the **“Final notice”** email to the client",
  },
  {
    type: "add-tag",
    label: "Add tag",
    icon: <Tag />,
    params: [{ id: "tag", label: "Tag", type: "text", required: true }],
    summary: (params) => `add the **${params.tag}** tag`,
  },
]

export function OverdueRule({
  initial,
  onSave,
}: {
  initial: RuleValue
  onSave: (rule: RuleValue, sentence: string) => void
}) {
  const [rule, setRule] = useState(initial)
  return (
    <RuleBuilder
      title="Final notice after 30 days"
      triggers={triggers}
      actionTypes={actions}
      value={rule}
      onValueChange={(next) => {
        setRule(next)
        onSave(next, describeRule(next, { triggers, actions }))
      }}
      onTest={async () => ({ matched: true, message: "Invoice #2026-0371 would get the final notice." })}
      labels={{ test: "Dry run", enabled: "On" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/rule-builder (Markdown: https://wingo-ui.com/components/rule-builder.md)

#### Suggestion Chips (`suggestion-chips`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add suggestion-chips`

Prompt suggestions people tap instead of typing: pills under a composer, cards on a welcome screen, or follow-up rows under an answer.

Tap or click a suggestion and onSelect hands it to the app, which sends or inserts its prompt; nothing stays selected. Pills and cards dip on a quick spring when pressed and tint on hover; follow-up rows tint and nudge their arrow. On a phone the pills (below 768px) and the cards (below 640px) sit in one row that swipes, snaps per item, runs to the screen edges and fades where more is waiting, with 44px targets; on a desktop they wrap or form a grid. With max set, a +N pill (or Show more under cards and rows) reveals the rest in place and turns into Show less; focus moves to the first revealed suggestion. More ideas spins its icon until your onRefresh promise settles, then only the new suggestions stagger in. The whole group is one Tab stop: Left and Right move between pills and cards (Up and Down between rows of a wrapped or grid layout, and through the list variant), Home and End jump to the ends, Enter or Space picks. While a reply streams, disabled dims everything and blocks picks but keeps focus where it was. Reduced motion turns the stagger and slides into short fades.

npm: motion, lucide-react
Wingo UI dependencies: skeleton, use-locale, use-scroll-edges, ai-chat, motion, number-format, tones, ui-config

Props:
- `suggestions: ChatSuggestion[]`: The suggestions, keyed by id, in order: { id, label, prompt?, description?, icon?, group? } (ChatSuggestion from ai-chat, re-exported here). prompt is what the app should send, defaulting to label. An empty list renders nothing unless loading. Long labels truncate (pill) or clamp to two lines (card) and show the full text as a tooltip.
- `title?: ReactNode` = "": An eyebrow above the suggestions, like "Try" or "Continue with". It also names the group for screen readers (labels.group does when it is empty).
- `showIcons?: boolean` = true: Shows each suggestion's icon: before the label on a pill, in a tinted tile on a card (a Sparkles when the suggestion has none), and as the leading glyph of a row (a reply arrow when it has none).
- `showDescriptions?: boolean` = true: Shows the description under the label on cards (two lines) and rows. Pills never show it.
- `variant?: "chip" | "card" | "list"` = "chip": chip: pills, the classic row under an empty composer. card: tiles with an icon, a label and a two-line description for a new chat's welcome screen. list: full-width rows with a trailing arrow, for follow-ups under an answer or a prompt library.
- `size?: "sm" | "md" | "lg"` = "md": Pills 32 / 36 / 40px tall with 13 / 14 / 15px text (44px on touch screens), cards at least 64 / 76 / 88px tall and 216 / 240 / 264px wide in a rail, rows 40 / 44 / 48px.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape. Pills use the button's radius per size (full is a pill), cards the surface radius (12 / 16 / 24px, full is 24px) with the icon tile following along, rows the pill radius capped at 12px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the icons (and card tiles) and the hover and pressed tint. neutral keeps icons muted and tints with the foreground; the pills themselves always stay a calm gray.
- `color?: string` = "": Any CSS color. Replaces the tone for the icons, the tiles and the tint. Leave empty to use the tone.
- `layout?: "auto" | "wrap" | "scroll" | "grid"` = "auto": auto: pills swipe in one row below 768px and wrap above; cards swipe below 640px and form a grid above. wrap, scroll and grid force one arrangement at every width. The list variant always stacks.
- `columns?: 2 | 3 | 4` = "2": Grid columns from 640px. A narrower container drops columns so a card never gets squeezed below about 170px: three columns need 544px of room, four need 736px.
- `align?: "start" | "center"` = "start": Where wrapped pills, the eyebrow and the card footer sit. center suits a welcome screen with a centered greeting.
- `bleed?: boolean` = true: The swiping row runs 16px into the page gutter, so items slide off the screen edge instead of stopping at a hard cut; list rows reach 8px into it, so their text lines up with the eyebrow while the hover highlight extends outward. Turn it off inside a card or a panel without that much padding.
- `max?: number` = 0: Shows at most this many; the rest wait behind a +N pill (chip) or Show more (card, list) that reveals them in place and turns into Show less. 0 shows all, and a max at or above the count shows no +N.
- `loading?: boolean` = false: Skeleton pills, cards or rows in the variant's exact shape while suggestions load; the group is aria-busy and says so to screen readers once.
- `skeletonCount?: number` = 4: How many skeletons loading shows.
- `disabled?: boolean` = false: Dims every suggestion to 50% and blocks picks, for while a reply streams. Items stay focusable (aria-disabled), so keyboard focus is never thrown back to the page.
- `animate?: boolean` = true: Staggers suggestions in (40ms apart, all in within 0.3s) when they mount in the browser and when the set changes; suggestions that stay keep their place. Server-rendered html already shows the final state. Reduced motion fades without offsets.
- `onSelect?: (suggestion: ChatSuggestion) => void`: Called with the picked suggestion; send or insert suggestion.prompt ?? suggestion.label. Not called while disabled. The component keeps no selection.
- `onRefresh?: () => (void | Promise<unknown>)`: Adds a trailing More ideas pill (or row, or a button under cards). Its icon spins until the returned promise settles and always finishes the turn it is on; then pass the new suggestions and only the new ids stagger in.
- `labels?: Partial<SuggestionChipsLabels>`: Every string, merged over DEFAULT_SUGGESTION_CHIPS_LABELS: group "Suggestions" (the group's name without a title), refresh "More ideas", more (count, formatted) => "+3", showMore "Show more", showLess "Show less", loading "Loading suggestions". The count is formatted in the UIProvider locale.
- `classNames?: Partial<Record<"rail" | "chip" | "icon" | "label" | "description" | "arrow" | "title" | "more" | "refresh" | "footer", string>>`: Extra classes for the parts: the rail (the scroller, wrap or grid), every chip, card or row, their icon, label, description and trailing arrow, the eyebrow, the +N and refresh controls, and the footer under cards.
- `className?: string`: Extra classes for the root group, merged last. Override the tone vars here, e.g. [--tone-soft-foreground:purple].

```tsx
import { CalendarDays, ChartColumn, Mail, Receipt } from "lucide-react"
import { SuggestionChip, SuggestionChips, type ChatSuggestion } from "@/components/ui/suggestion-chips"

const suggestions: ChatSuggestion[] = [
  { id: "overdue", label: "Summarize overdue invoices", description: "What is left to collect this month", icon: <Receipt /> },
  { id: "follow-up", label: "Write a follow-up email", description: "For offer #OF-2026-118", icon: <Mail /> },
  { id: "q3", label: "Compare Q3 collections", description: "July, August and September", icon: <ChartColumn /> },
  { id: "meeting", label: "Prepare Monday's meeting", description: "Agenda and the week's numbers", icon: <CalendarDays /> },
]

export function WelcomeSuggestions({ onSend }: { onSend: (text: string) => void }) {
  return (
    <SuggestionChips
      variant="card"
      title="Try"
      suggestions={suggestions}
      onSelect={(suggestion) => onSend(suggestion.prompt ?? suggestion.label)}
    />
  )
}

// one pill, card or row in your own layout: same look, press and tooltip, without the roving focus
export function PinnedSuggestion({ onSend }: { onSend: (text: string) => void }) {
  return <SuggestionChip variant="card" suggestion={suggestions[0]} onSelect={(s) => onSend(s.prompt ?? s.label)} />
}
```

Docs: https://wingo-ui.com/components/suggestion-chips (Markdown: https://wingo-ui.com/components/suggestion-chips.md)

#### Tool Call Timeline (`tool-call-timeline`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add tool-call-timeline`

What an AI agent did, step by step: each tool call with its status, time, input and output, plus approval and retry.

Each call is a row: a round marker says its status (a dashed ring while queued, a spinner while it runs, a check that pops once when it finishes, a cross when it fails, a hand that pings while it waits for a person), then a human title, the tool's id in a small mono chip and how long it took. A running call's title shimmers and its time ticks in tenths of a second. Click or tap a row, or press Enter or Space on it, to open its input and output as highlighted JSON (text results wrap), its error and its logs; long blocks scroll inside themselves and every block has a copy button. A call that waits for approval shows Reject and Approve; a failed one opens by itself and shows Retry; a button whose handler returns a promise spins until it settles, and focus moves back to the row when the buttons go away. Sub-steps sit indented under their step. The card variant adds a header with the run's state (a spinner, or Needs approval, Failed, Done in words; a hand or an alert in its icon tile when a person is needed or a call failed, which alone carries it in a card narrower than 448px), its progress while it runs (2 of 5 done) and total time, and a button that opens or closes every row at once; the inline variant is a one-line summary (Used 4 tools, 2.8 s) that opens by itself while a call runs or waits for approval and closes again 1.2 s after everything finished, unless you opened it yourself or focus is inside it (you just approved a call), so focus never drops to the page. Status changes are announced once each to screen readers. Rows lay out by their own width, so a timeline in a chat column or a side panel fits: when a row is narrow the tool id moves under the title and Approve and Reject share the width; on a phone they are 44px tall, rows have 44px targets and code blocks scroll sideways inside themselves. Reduced motion swaps the springs for quick fades and stops the shimmer and the ping.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, code-block, copy-button, spinner, tooltip, use-controllable-state, use-locale, use-stick-to-bottom, ai-chat, motion, number-format, relative-time, tones, ui-config

Props:
- `calls: ToolCall[]`: The calls in order, in the ToolCall shape from lib/ai-chat: id, name, title, status, input, output, error, startedAt, endedAt, durationMs, logs and steps (sub-steps). Keep them immutable so only the call that changed re-renders.
- `variant?: "timeline" | "card" | "inline"` = "timeline": timeline: markers on a rail, for an agent page. card: the timeline in a panel with a header (title, progress, total time and the run's state). inline: a one-line summary that opens into the timeline, for a chat message.
- `title?: ReactNode` = "": The card's heading or the inline summary's text. Empty falls back to labels.summary (Used 4 tools). The card's second line shows the progress while the run goes on (2 of 5 done), then the summary, with the total time.
- `size?: "sm" | "md"` = "md": Titles 13 / 14px, rows 32 / 40px, markers 20 / 24px. Sub-steps always use sm. On touch screens md rows grow to 44px and sm rows keep their look with a 44px hit area.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Paints the Approve button, the card header's icon, the inline summary's spinner and the focus tint. Markers always use the status colors (running is info, done success, failed danger, waiting warning).
- `color?: string` = "": Any CSS color; replaces the tone. Text on the Approve button turns black or white by lightness.
- `codeAccent?: string` = "": A hex color the input and output blocks build their syntax colors from (the code block's accent). Empty keeps the code block's own.
- `showToolName?: boolean` = true: The tool's id (search_invoices) in a mono chip next to the title; in a row narrower than 512px it sits under the title (sm rows hide it below 448px).
- `showDurations?: boolean` = true: How long each call took (live while it runs, from startedAt) and the run's total in the card and inline summaries.
- `showInput?: boolean` = true: The arguments the model sent, in an opened row.
- `showOutput?: boolean` = true: What the tool returned, in an opened row.
- `codeMaxHeight?: number` = 240: Height in px an input or output block may reach before it scrolls inside itself. Copy always takes the whole value.
- `defaultOpen?: boolean` = false: inline: start with the timeline open under the summary.
- `open?: boolean`: inline: controlled open state. autoOpen asks for changes through onOpenChange.
- `onOpenChange?: (open: boolean) => void`: inline: called when the summary is pressed and when autoOpen opens or closes it.
- `autoOpen?: boolean` = true: inline: opens while a call runs or waits for approval and closes 1.2 s after everything finished, unless the person opened it themselves or focus is inside it.
- `expandErrors?: boolean` = true: A failed call starts with its details open, and opens by itself when a running call fails.
- `expandedKeys?: string[]`: Controlled: the ids of the calls (and sub-steps) whose details are open.
- `defaultExpandedKeys?: string[]`: The calls whose details start open (failed calls are added when expandErrors is on).
- `onExpandedKeysChange?: (keys: string[]) => void`: Called with the next ids when a row is opened or closed, and when a call fails with expandErrors on.
- `onApprove?: (call: ToolCall) => (void | Promise<unknown>)`: Shows Approve on calls awaiting approval. Return a promise to keep the button spinning (and Reject disabled) until it settles; then set the call's status.
- `onReject?: (call: ToolCall) => (void | Promise<unknown>)`: Shows Reject next to Approve. Set the call to canceled, or back to the model, in the handler.
- `onRetry?: (call: ToolCall) => (void | Promise<unknown>)`: Shows Retry on failed calls, spinning while a returned promise is pending.
- `renderInput?: (call: ToolCall) => ReactNode`: Replaces the JSON view of a call's input (a map, a diff). Return undefined to keep the JSON, null to hide it.
- `renderOutput?: (call: ToolCall) => ReactNode`: Replaces the JSON view of a call's output, e.g. invoices as a small table. Return undefined to keep the JSON, null to hide it.
- `locale?: string` = "": Locale for durations (0.8 s in en-US, 0,8 s in de-DE) and counts. Empty uses UIProvider's, then the page's.
- `now?: Date | number`: A fixed clock for running durations, for screenshots and tests. Without it running calls tick on the shared ticker (lib/ai-chat).
- `emptyState?: ReactNode`: Replaces the No steps yet row shown while calls is empty.
- `labels?: Partial<ToolCallTimelineLabels>`: Every visible and spoken string: summary(count, formatted), progress(done, total, formattedDone, formattedTotal), running(title), input, output, error, logs, approve, reject, retry, showDetails, hideDetails, empty, status (one word per status, partial), announce(title, status), copy, copied. English defaults in DEFAULT_TOOL_CALL_TIMELINE_LABELS.
- `classNames?: Partial<Record<"summary" | "summaryIcon" | "summaryTitle" | "summaryMeta" | "list" | "item" | "rail" | "marker" | "header" | "title" | "name" | "duration" | "status" | "chevron" | "details" | "description" | "input" | "output" | "error" | "logs" | "approval" | "retry" | "steps" | "empty", string>>`: Extra classes for the inner parts; summary is the card header or the inline summary button.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `ToolCallItem` (component): One call as an <li> with its details, approval and sub-steps, for lists of your own: render it inside an <ol> and set last on the final one to end the rail. Props: { call: ToolCall; last?: boolean; expanded?: boolean; defaultExpanded?: boolean; onExpandedChange?; expandErrors?; showInput?; showOutput?; showToolName?; showDurations?; renderInput?; renderOutput?; codeMaxHeight?; codeAccent?; onApprove?; onReject?; onRetry?; size?; tone?; color?; now?; locale?; labels?; classNames? }.
- `ToolCallStatusMarker` (component): The 20 / 24px round status marker on its own (agent steps, workflow node runs); decorative, so pair it with the status in words. Props: { status: ToolCallStatus; size?: "sm" | "md" }.
- `DEFAULT_TOOL_CALL_TIMELINE_LABELS` (constant): The English strings, to spread and override. Type: ToolCallTimelineLabels.

```tsx
import { ToolCallTimeline, type ToolCall } from "@/components/ui/tool-call-timeline"

export function AgentRun({
  calls,
  onApprove,
  onReject,
}: {
  calls: ToolCall[]
  onApprove: (call: ToolCall) => Promise<void>
  onReject: (call: ToolCall) => void
}) {
  return (
    <ToolCallTimeline
      variant="card"
      title="Collections agent"
      calls={calls}
      onApprove={onApprove}
      onReject={onReject}
      locale="en-US"
    />
  )
}

// a call waiting for a person, as the model sent it
export const sendReminder: ToolCall = {
  id: "call-send",
  name: "send_email",
  title: "Sending the email",
  status: "awaiting-approval",
  input: { to: "adam.foster@techsolutions.com", subject: "Reminder for invoice #2026-0405" },
}
```

Docs: https://wingo-ui.com/components/tool-call-timeline (Markdown: https://wingo-ui.com/components/tool-call-timeline.md)

#### Usage Meter (`usage-meter`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add usage-meter`

How much of a plan is used: tokens, messages, images, credits or money against their limits, with resets, warnings and an upgrade offer.

Read it at a glance: each meter shows what is used against its limit, the percent and a bar; the bars grow from empty one after another the first time the card scrolls into view, then glide when the numbers change. At 75% a bar turns amber with an Almost at your limit note, at 90% red, and at the limit it stays full in red and says how far over it went; a word and an icon always say it too, and a screen reader hears each crossing once through a polite status (never on load). Resets read today at 18:00, tomorrow or in 3 days up close and a date further out, with the full date on hover. The upgrade offer slides open once a meter reaches the warning line; its button is a real link when it has an href. The compact variant is a small ring with the percent of the fullest meter for a composer or a topbar: click or tap it, or press Enter or Space on it, and the details open in a popover whose panel takes focus first (Tab goes on to the upgrade button); Escape or a click outside closes it and focus returns to the ring. On a phone the details rise as a bottom sheet with 14px rows and a full width upgrade button pinned at the bottom. Every button has a 44px touch target. In a narrow spot (under 352px) a row puts its value on a line of its own under the label (wider, a value that does not fit wraps instead of breaking the label), and a narrow offer puts its button under the text, so nothing gets squeezed. Press Use 50,000 tokens in the playground to push the token meter over both thresholds. Reduced motion shows the values at once.

npm: motion, lucide-react
Wingo UI dependencies: progress, badge, button, popover, skeleton, commerce, number-format, date-utils, relative-time, ai-chat, use-locale, use-media-query, motion, tones, ui-config

Props:
- `meters: UsageMeterItem[]`: The meters: { id, label, used, limit?, unit?, currency?, icon?, description?, resetsAt?, format? }. limit null or undefined is unlimited. unit is tokens, messages, credits, requests, images, currency or count (the default): tokens print exact in rows and compact (742,3 K) in rings, currency goes through formatPrice with two decimals, the rest through formatNumber, and the word units add their word after the limit. format replaces the number formatting. An empty list renders nothing.
- `variant?: "card" | "inline" | "compact"` = "card": card: a raised panel with the title, the plan badge, the reset date and the upgrade offer, for settings and billing pages. inline: the rows alone (the title is for screen readers), for side panels. compact: a small ring with the percent of the most used meter, for a composer or a topbar; it opens the details in a popover, a bottom sheet on phones.
- `display?: "bar" | "ring"` = "bar": bar: a label, the value and the percent over a bar for each meter. ring: a grid of rings with the percent inside and the label under each, 2 a row on a phone and up to 4 once the list is 448px wide (dashboards).
- `title?: ReactNode` = "": The card title, also the popover title in compact. Empty falls back to labels.title.
- `plan?: { name: ReactNode; tone?: Tone }`: The current plan as a soft badge next to the title, in its own tone (neutral by default).
- `upgrade?: { label: ReactNode; description?: ReactNode; href?: string; onClick?: () => void; tone?: Tone }`: The upgrade offer: a bold line, a muted line and a pill button labelled labels.upgrade. With href the button is a link; in the compact popover picking it closes the popover first. tone gives the offer its own color (brand on neutral meters); without it the offer follows tone and color. No upgrade, no offer.
- `upsell?: "auto" | "always" | "never"` = "auto": When the upgrade offer shows: auto once any meter reaches the warning threshold (it slides open when that happens), always, or never.
- `resetsAt?: Date | string | number`: When the plan's meters reset, shown in the card header (under the rows in inline, under the popover title in compact). A meter's own resetsAt wins and shows in its caption. A reset in the past is hidden.
- `resetFormat?: "auto" | "date" | "relative"` = "auto": auto: today at 18:00 or tomorrow up close, in 3 days within a week, then the date. date: always the date (with the time when it is not midnight). relative: in 1 hour, in 7 days. Before hydration it is always the date, so server and client agree.
- `thresholds?: { warning?: number; danger?: number }` = "{ warning: 75, danger: 90 }": Percentages at which a meter turns warning (amber) and danger (red), with a note under it. At or past the limit a meter is always over, full and red. Out of order values are swapped; leave one out to skip that step.
- `showRemaining?: boolean` = false: Rows read 257,700 tokens left instead of 742,300 / 1,000,000 tokens (labels.remaining), and rings show what is left under them. A meter past its limit keeps used / limit and says how far over it is.
- `showPercent?: boolean` = true: The percent at the end of each row, inside each ring and next to the compact ring. Below the limit it rounds down, so 99.6% never reads as full.
- `size?: "sm" | "md"` = "md": sm: 4px bars, 13px text and 48px rings, for narrow side panels. md: 6px bars, 14px text and 64px rings. The phone sheet of the compact variant always uses md.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill of meters below the warning threshold, the tint of the upgrade offer and its button. Crossed thresholds always use warning and danger.
- `color?: string` = "": Any CSS color. Replaces the tone for healthy meters, the offer's tint and its button; warning and danger keep their colors.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Card corners: 0, 12, 16 or 24px. The upgrade offer inside follows a step smaller.
- `loading?: boolean` = false: Skeleton rows (or rings, or a skeleton trigger) with the real rows' heights, one per meter or 3 when the list is empty, and aria-busy. Data that arrives after loading is never announced as a crossing.
- `currency?: string` = "USD": ISO 4217 code for currency meters without their own currency.
- `open?: boolean`: Compact: whether the details are open (controlled). Pair it with onOpenChange.
- `defaultOpen?: boolean` = false: Compact: the details start open.
- `onOpenChange?: (open: boolean) => void`: Compact: called when the details open or close.
- `responsive?: boolean` = true: Compact: below 768px the details open as a bottom sheet with a pinned, full width upgrade button. Off keeps the floating panel on phones.
- `side?: "top" | "right" | "bottom" | "left"` = "bottom": Compact: the side of the ring the details open on (it flips when there is no room). top suits a composer at the bottom of the screen.
- `align?: "start" | "center" | "end"` = "center": Compact: how the 416px details panel lines up with the ring (never wider than the screen minus 24px). end suits a ring at the right edge.
- `animated?: boolean` = true: Bars and rings grow from empty the first time they are on screen, one after another, and glide on the smooth spring when the numbers change. Off shows the values at once, as reduced motion does.
- `locale?: string` = "": Intl locale for numbers, money, percents and dates. Empty uses UIProvider's locale, then the page's.
- `now?: Date | number`: The reference time for relative resets. Defaults to the current minute (useNow); pin it for stable screenshots and tests.
- `labels?: Partial<UsageMeterLabels>`: Every string, English by default (DEFAULT_USAGE_METER_LABELS): title "Usage", usedOf (used, limit), remaining (formatted, count), unlimited, resets (when, kind), at (day, time), over (formatted, count), warning "Almost at your limit", danger "Limit nearly reached", reached "Limit reached", upgrade "Upgrade", details "Usage details", valueLabel (used, limit, percent) for screen readers, loading, missing (a dash for a value that is not a number) and units { tokens, messages, credits, requests, images }, each a word or a function of the count for plurals.
- `classNames?: Partial<Record<"header" | "title" | "plan" | "reset" | "list" | "row" | "icon" | "label" | "value" | "percent" | "bar" | "ring" | "footer" | "status" | "description" | "upsell" | "upgrade" | "trigger" | "content", string>>`: Extra classes for the inner parts; trigger and content are the compact ring button and its details panel.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `UsageMeterRow` (component): One meter on its own (label, value, percent, bar, status and reset line) for layouts of your own; delay is the ms it waits before growing once on screen. Props: { meter: UsageMeterItem; size?; tone?; color?; thresholds?; showRemaining?; showPercent?; resetFormat?; currency?; locale?; now?; labels?; animated?; delay?: number; classNames? }.
- `getUsageState` (function): Where a meter stands, for your own badges or alerts: the percent used (not capped, 52 of 50 is 104) and its state. No limit (null, undefined or Infinity) is unlimited; a limit of 0 is over as soon as anything is used; negative use counts as 0; a used value or limit that is not a number (NaN) has no percent and its row shows a dash with no bar. Signature: (meter: { used: number; limit?: number | null }, thresholds?) => { percent: number | null; state: "ok" | "warning" | "danger" | "over" | "unlimited" }.
- `DEFAULT_USAGE_METER_LABELS` (constant): The English strings, to spread and override. Type: UsageMeterLabels.
- `DEFAULT_USAGE_METER_THRESHOLDS` (constant): The default thresholds, for getUsageState and your own checks. Type: { warning: 75; danger: 90 }.

```tsx
import { Coins, ImageIcon, MessageSquare, Wallet } from "lucide-react"
import { UsageMeter, type UsageMeterItem } from "@/components/ui/usage-meter"

const meters: UsageMeterItem[] = [
  { id: "tokens", label: "Tokens", used: 742300, limit: 1000000, unit: "tokens", icon: <Coins /> },
  {
    id: "messages",
    label: "Northwind Pro messages",
    used: 38,
    limit: 50,
    unit: "messages",
    icon: <MessageSquare />,
    resetsAt: "2026-09-24T18:00:00-04:00",
  },
  { id: "images", label: "Generated images", used: 12, limit: 20, unit: "images", icon: <ImageIcon /> },
  { id: "cost", label: "Cost API", used: 412.8, limit: 500, unit: "currency", icon: <Wallet /> },
]

export function PlanUsage() {
  return (
    <UsageMeter
      meters={meters}
      plan={{ name: "Pro" }}
      resetsAt="2026-10-01T00:00:00-04:00"
      upgrade={{ label: "Upgrade to Business", description: "$59 / month, unlimited tokens", href: "/billing" }}
      locale="en-US"
    />
  )
}
```

Docs: https://wingo-ui.com/components/usage-meter (Markdown: https://wingo-ui.com/components/usage-meter.md)

#### Voice Input (`voice-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add voice-input`

Talk instead of typing: a mic that grows into a recording pill with a live waveform and transcript, a full-width bar, or a voice orb.

Tap the mic and, once the browser has your permission (asked only after that first tap; the mic spins meanwhile and a desktop tooltip says to allow it), it grows on a smooth spring into a pill: Cancel, a pulsing red dot, a waveform that ripples with your voice, a timer and Send, and it shrinks back into the mic when you are done. The words you say appear above it as the browser hears them, the unsure ones muted; Send hands the app the audio and the transcript, Cancel or Escape throws it away. Ten seconds before maxDuration the timer turns amber and pulses, and at the limit the recording sends itself. In hold mode you press and hold to talk and let go to send; slide more than 80px toward the start, or off the pill, and it tints red with a tick of haptics, so letting go cancels instead. A tap that is too short says so and fades, with the mic still there for the next try. A blocked or missing microphone explains itself in place with Try again, and a send your promise rejects can be sent again. The bar variant is always there at full width, and a tap anywhere on it starts; the orb variant is a voice mode, listening, thinking while your promise runs and blooming with getLevel while the app talks back. With a keyboard, Tab to the mic and press Enter or Space; focus moves to Send while recording, Escape cancels (or closes an error), and in hold mode holding Space records and releasing it sends while Enter works like a tap. Screen readers hear Listening, Transcribing and the recorded length once, never the ticking timer. On phones every target is 44px, the held mic stops the page from scrolling, and a halo under your finger breathes with your voice. Reduced motion swaps the morph for a cross-fade and the waveform for a still level meter.

npm: motion, lucide-react
Wingo UI dependencies: button, matrix-orb, spinner, tooltip, use-controllable-state, use-locale, use-media-query, ai-chat, haptics, motion, tones, ui-config

Props:
- `variant?: "button" | "bar" | "orb"` = "button": button: a mic icon button that expands in place into the recording pill, for composers and toolbars. bar: the full-width bar, always visible like WhatsApp's, with the transcript above it. orb: a MatrixOrb voice mode that listens, thinks and blooms while the app talks back.
- `size?: "sm" | "md" | "lg"` = "md": The mic is the button's icon-sm / icon / icon-lg (32 / 40 / 48px, 44px on touch for md) and the pill keeps its height, the bar is 40 / 48 / 56px tall, the orb 160 / 220 / 280px wide.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the waveform, the Send button, the bar's mic and the orb. The recording dot stays red whatever the tone, because red means recording.
- `color?: string` = "": Any CSS color. Replaces the tone for the waveform, the buttons and the orb (the orb's canvas gets the resolved color, so oklch and CSS variables work too). Leave empty to use the tone.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corners of the mic, the pill and the bar. The buttons inside the pill take its corner minus their 4px inset, so every size reads as one shape.
- `bars?: number` = 0: How many waveform bars. 0 fits the width with 3px bars and 2px gaps; a fixed count spreads the bars across the pill.
- `transcript?: string` = "": Words the app streams in while recording (a server transcriber) or while speaking (the answer in voice mode). Wins over the browser's recognizer and becomes the result's transcript.
- `showTranscript?: boolean` = true: Shows the live transcript: above the pill and the bar (four lines, scrolled to the newest words), under the orb in large centered type. Final words in the text color, interim ones muted.
- `showWaveform?: boolean` = true: Shows the live waveform in the pill. Hidden, the pill says Recording in its place. In hold mode the slide hint takes this spot and the level shows as a halo around the held mic.
- `showTimer?: boolean` = true: Shows the elapsed time (0:07). It turns amber and pulses in the last 10 seconds before maxDuration.
- `defaultStatus?: "idle" | "requesting" | "recording" | "processing" | "error"` = "idle": The starting status. recording without a tap never opens the microphone: the timer runs, getLevel drives the visuals and Send hands over the length and the transcript prop, which is how demos and screenshots show the pill.
- `status?: "idle" | "requesting" | "recording" | "processing" | "error"`: Controlled status, with onStatusChange. Drive processing yourself while a server transcribes, or set idle to stop listening from outside (the recording is discarded).
- `onStatusChange?: (status: VoiceInputStatus) => void`: Fires on every change: requesting after the tap, recording, processing after Send, idle or error.
- `error?: "denied" | "noMic" | "unsupported" | "tooShort" | "interrupted" | "failed" | string` = "": What status error shows. A kind picks its sentence from labels (denied, noMic, unsupported, tooShort, interrupted, failed); any other text shows as it is, like a message from your server. Empty shows the component's own error.
- `speaking?: boolean` = false: Orb variant: the app is talking back. The orb blooms with getLevel (your text to speech output), the status reads Speaking and the transcript prop shows the answer. A tap on the mic interrupts it.
- `disabled?: boolean` = false: Dims everything and blocks starting; a recording in progress is canceled.
- `mode?: "toggle" | "hold"` = "toggle": toggle: tap to start, then Send or Cancel. hold: push to talk, release to send, slide away (or Escape) to cancel; the held element sets touch-action none and keeps the pointer while it turns into the pill, and Space works the same way from the keyboard.
- `audio?: boolean` = true: Records audio with MediaRecorder (audio/webm with Opus, audio/mp4 on Safari) and hands the Blob to onRecordingComplete. Off, only the transcript and the length are sent.
- `transcribe?: "browser" | "none"` = "browser": browser: live words from the Web Speech API where it exists (Chrome, Edge, Safari), restarted when Chrome ends a run; elsewhere the transcript stays empty and the audio still records. none: no live words, for server transcription.
- `lang?: string` = "": The recognition language, like "en-US". Empty uses the resolved locale.
- `maxDuration?: number` = 120: Seconds. The timer warns 10 seconds before, and at the limit the recording stops, sends itself and announces labels.maxReached. 0 means no limit.
- `minDuration?: number` = 500: Milliseconds. A shorter recording is a mis-tap: it is discarded and labels.tooShort shows for a moment.
- `haptics?: boolean` = true: A light tick on start, success on send, warning on cancel and a medium tick when a slide arms cancel. Touch and pen only; a mouse never vibrates a laptop.
- `locale?: string` = "": The locale that picks the recognition language when lang is empty. Empty uses the UIProvider's, then the page's.
- `getLevel?: () => number`: A 0 to 1 level read every frame in place of the microphone analyser: a WebRTC call, your text to speech output in voice mode, or a simulation. With getLevel, audio off and transcribe none, nothing opens the microphone at all.
- `onRecordingComplete?: (result: VoiceInputResult) => (void | Promise<unknown>)`: Send, the hold release or the time limit: { blob?, mimeType?, durationMs, transcript? }. Return a promise to keep the processing spinner until it settles; a rejection shows the failed error and Try again sends the same recording again.
- `onTranscript?: (text: string, info: { final: boolean }) => void`: Live words from the browser's recognizer: the whole transcript of this recording so far, final once no words are pending. Dictation into a field uses it.
- `onCancel?: () => void`: Cancel, Escape or a hold released while armed. The recording is gone.
- `labels?: Partial<VoiceInputLabels>`: Every string, English by default (DEFAULT_VOICE_INPUT_LABELS): start, stop, send, cancel, recording, listening, speaking, requesting, processing, denied, unsupported, noMic, tooShort, interrupted, failed, holdHint, tapHint, releaseToSend, slideToCancel, releaseToCancel, retry, dismiss, maxReached and recorded(duration), e.g. (d) => `Recording, ${d}`.
- `classNames?: Partial<Record<"trigger" | "bar" | "cancel" | "dot" | "waveform" | "timer" | "send" | "hint" | "transcript" | "orb" | "status" | "controls" | "error" | "retry", string>>`: Extra classes for the parts: the mic, the pill or bar, Cancel, the recording dot, the waveform, the timer, Send, the hint, the transcript, the orb, its status line and controls row, the error line and Try again.
- `className?: string`: Extra classes for the root, merged last. The root sets the --tone vars, so [--tone:purple] recolors the waveform and Send.

Parts:
- `VoiceWaveform` (component): The bars on their own, fed by any level source: level (a MotionValue), getLevel, or values for the still waveform of a recorded note; bars, active, idleHeight, tone, color. Transforms are written straight to the bars in a rAF loop, never through React state, and pause off screen. Props: VoiceWaveformProps.
- `useVoiceRecorder` (hook): The engine for custom UIs: { status, start, stop, cancel, retry, dismiss, level, elapsed, transcript, interim, error, supported, metered }. Options mirror the component (status, audio, transcribe, lang, getLevel, minDuration, maxDuration, onComplete, onTranscript, onCancel, onError, onLimit). start only works from a tap or a key press; every track, context and recognizer stops on stop, cancel and unmount, and a second recorder starting stops the first. Signature: (options: UseVoiceRecorderOptions) => VoiceRecorder.
- `DEFAULT_VOICE_INPUT_LABELS` (constant): The English strings, exported so an app can translate from a complete object. Type: VoiceInputLabels.

```tsx
"use client"

import { useState } from "react"
import { VoiceInput, type VoiceInputResult } from "@/components/ui/voice-input"

export function VoiceNote({ clientId }: { clientId: string }) {
  const [note, setNote] = useState("")

  async function save(result: VoiceInputResult) {
    if (result.transcript) setNote((text) => [text, result.transcript].filter(Boolean).join(" "))
    if (!result.blob) return
    const body = new FormData()
    body.append("audio", result.blob, "voice-note.webm")
    const response = await fetch(`/api/clients/${clientId}/voice-notes`, { method: "POST", body })
    if (!response.ok) throw new Error("Upload failed")
  }

  return (
    <div className="flex flex-col gap-3">
      <p className="text-sm">{note || "No note yet"}</p>
      <VoiceInput
        variant="bar"
        lang="en-US"
        maxDuration={180}
        onRecordingComplete={save}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/voice-input (Markdown: https://wingo-ui.com/components/voice-input.md)

#### Workflow Canvas (`workflow-canvas`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add workflow-canvas`

A node editor for automations: a trigger, actions, AI steps and yes / no branches you connect, insert into, tidy up and watch run.

Steps are cards on a dotted canvas, joined by rounded step lines; a condition splits into Yes and No branches with a label on each line. Drag the canvas to pan, scroll or swipe with two fingers to pan, pinch (or Ctrl and the wheel) to zoom. Click a step to select it and open its settings in a panel on the right; drag it to move it (it snaps to a 16px grid and the move is one undo step). Drag from the dot under a step to another step to connect them: a connection into a trigger, one that would make a loop or a second line from the same branch is refused and the line turns red. Drop the line on empty space and the add menu opens there. Hover a line (or select it) for its + button, which inserts a step in between; a step with nothing after it shows a dashed + stub, and a branch that goes nowhere names itself next to it. The add menu searches the step catalog by name, kind or group. Right-click a step for Duplicate, Skip and Delete, or the empty canvas to add a step where you clicked; deleting a connected step asks first and a step in the middle hands its parent to its child. The toolbar adds (after the selected step, on the selected line, or in a free spot), undoes and redoes, tidies the layout (steps glide to their new places), zooms, fits and locks, and shows Run when onRun is set. Shift and click, or Shift and a drag on the canvas, selects several steps; Delete then asks once for all of them. In run mode editing locks, the line into the running step flows, markers turn from queued to running to done or failed, the view follows the running step unless you just panned, and a run that ends with every step done pops its markers once. On a phone one finger pans and two pinch; tap a step to select it, then drag it (an unselected step never moves by accident); long-press a step for its menu or the empty canvas to add a step; handles take 44px of finger reaching away from the card; the toolbar centers above the home indicator with 44px buttons, folding tidy, zoom and lock into a menu; settings open in a sheet that stops at half height, the selected step scrolls above it, and the canvas stays usable. With a keyboard: Tab reaches the canvas, the toolbar (arrow keys move inside it) and every step and connection; Enter or Space selects, Enter again moves into the settings and Escape goes back; arrows move the selected step (Shift for 4 times as far); Delete or Backspace removes the selection; A adds a step after the selection or on the selected line; Ctrl or Cmd with Z undoes, with Shift and Z (or Y) redoes, with D duplicates and with A selects everything; + and - zoom, Shift and 1 fits; the menu key or Shift and F10 opens a step's menu. Validation problems ring the step in red and are listed in its tooltip and settings; changes are announced to screen readers.

npm: @xyflow/react, motion, lucide-react
Wingo UI dependencies: alert-dialog, button, drawer, dropdown-menu, input, listbox, popover, spinner, switch, textarea, tooltip, use-controllable-state, use-long-press, use-media-query, use-shortcut, ai-chat, motion, tones, ui-config

Props:
- `nodeTypes: WorkflowNodeDef[]`: The step catalog: { type, kind (trigger | action | condition | ai | delay | end), label, description, icon, group, tone, outputs, defaults, keywords }. It fills the add menu (grouped by group), gives each card its icon and kind, and a condition's outputs (Yes / No unless you name your own). Keep it at module scope.
- `value?: WorkflowValue`: The graph: { nodes: { id, type, position, data: { title, subtitle, status, error, config, disabled } }[], edges: { id, source, target, sourceHandle, label }[] }. A drag commits once, on drop; a value that arrives mid-drag waits until the drop. Steps that all sit at 0, 0 are laid out once.
- `defaultValue?: WorkflowValue`: The starting graph while uncontrolled; an empty canvas (the trigger picker) without it.
- `onValueChange?: (value: WorkflowValue) => void`: Every committed change: an add, a delete, a connection, a drop, a tidy, an inspector edit, an undo.
- `selectedId?: string | null`: The selected step, which opens the inspector. Several selected steps (Shift and click, a box) report null.
- `defaultSelectedId?: string | null` = "": The step selected at first while uncontrolled, so its settings open with the canvas. The playground offers the steps of the demo workflow; "" selects nothing.
- `onSelectedIdChange?: (id: string | null) => void`: The selection changed. With inspector="none" this is where the app opens its own panel.
- `direction?: "vertical" | "horizontal"` = "vertical": The flow: top to bottom (reads best on phones) or left to right. Handles, the dashed + stubs, the label of a branch and the tidy layout follow it.
- `readOnly?: boolean` = false: View only: pan, zoom, select and inspect. The editing tools, the + buttons and the step menu go away and the inspector shows its fields read only.
- `showMinimap?: "auto" | "always" | "never"` = "auto": auto: from 768px, while part of the graph is outside the view (after zooming in or panning). always also shows it on phones, in the top corner. The minimap pans and zooms the canvas.
- `showControls?: boolean` = true: The floating toolbar: add, undo, redo, tidy up, zoom, fit, lock and Run.
- `background?: "dots" | "lines" | "none"` = "dots": The pattern under the steps, drawn in a faint foreground tint so it works in both themes.
- `snapToGrid?: boolean` = true: Dragged steps land on a 16px grid, and the arrow keys move a step by it (5px without the grid).
- `fitOnMount?: boolean` = true: Fits the whole graph into view on mount, clear of the toolbar and never above 100%, and again when a canvas that mounted hidden (a tab, a sheet) becomes visible. A flow too wide to read at that size (a long horizontal flow in a narrow column) opens at 50% from its trigger instead.
- `inspector?: "auto" | "none"` = "auto": auto: the selected step's settings open in a panel on the right (at the bottom of a narrow canvas) and in a half-height sheet on phones. none: no built-in panel; show your own from onSelectedIdChange.
- `renderInspector?: (node: WorkflowNode, api: { update: (data: Partial<WorkflowNode["data"]>) => void; def: WorkflowNodeDef; fields: ReactNode; readOnly: boolean }) => ReactNode`: The inspector body for a step: its settings form. update merges into the step's data (one undo step per 500ms burst); fields is the default name, description and skip fields; readOnly is true while read only, locked or running.
- `onRun?: () => void`: Shows a Run button in the toolbar. Start the run, then drive running and each step's data.status.
- `running?: boolean` = false: Run mode: editing locks, steps show node.data.status as a marker, the line into a running step flows, finished lines turn green, and the view follows the running step unless the person panned in the last 3 s.
- `confirmDelete?: boolean` = true: Asks before deleting a step that has connections (through useConfirm, so mount AlertDialogProvider once).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selection ring, the dragged connection, a flowing line, the add button and the + buttons.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `labels?: Partial<WorkflowCanvasLabels>`: Every string, English by default (DEFAULT_WORKFLOW_CANVAS_LABELS): canvas, roleDescription, step, instructions, the toolbar's names (addStep, undo, redo, tidy, zoomIn, zoomOut, fit, lock, unlock, more, run, running), searchSteps, noSteps, emptyTitle, emptyDescription, insert, yes, no, the inspector's (inspector, title, subtitle, disabled, duplicate, delete, issuesTitle), deleteTitle(title), deleteManyTitle(count), deleteDescription, kinds, status, issues (the validation messages), announce, nodeLabel(step) and edgeLabel(from, to, label).
- `classNames?: Partial<Record<"flow" | "toolbar" | "minimap" | "menu" | "inspector" | "header" | "body" | "footer" | "empty" | "node" | "edgeLabel" | "insert", string>>`: Extra classes for the parts. The root takes className; drop its frame with className="rounded-none bg-transparent".
- `flowProps?: Partial<ReactFlowProps<WorkflowFlowNode, WorkflowFlowEdge>>`: Extra props for the underlying ReactFlow element (minZoom, maxZoom, zoomOnScroll, proOptions...). The xyflow attribution is hidden by default, which its MIT license allows; pass proOptions to show it.
- `className?: string`: Classes for the root, merged last. It fills its parent (at least 420px tall) in a rounded-3xl bg-card frame; give the parent a height.

Parts:
- `WorkflowNodeCard` (component): The look of one step on its own: the kind's icon tile, the kind, the title, the subtitle and the run marker, with the selected, invalid and skipped looks. For previews, template galleries and lists. Props: { node?: WorkflowNode; def?: WorkflowNodeDef; title?; subtitle?; kind?; icon?; status?; selected?; disabled?; invalid?; tone?; color?; labels?; classNames? }.
- `layoutWorkflow` (function): A layered layout: ranks by the longest path from the trigger, a condition's branches side by side in output order, each row spread evenly around its parents. Returns the steps with new positions (top-left at 0, 0). Signature: (nodes: WorkflowNode[], edges: WorkflowEdge[], options?: { direction?; gapX? = 64; gapY? = 56; nodeWidth? = 260; nodeHeight? = 64; sizes?; nodeTypes? }) => WorkflowNode[].
- `validateWorkflow` (function): The problems that stop an automation from running: no trigger or more than one, a connection into a trigger, loops, a condition branch that goes nowhere, unknown step types and connections to missing steps. Signature: (value: WorkflowValue, nodeTypes: WorkflowNodeDef[], messages?: Partial<WorkflowIssueMessages>) => { nodeId?: string; edgeId?: string; message: string }[].
- `createWorkflowNode` (function): A new step from its definition, with a fresh id and the def's defaults (call it in handlers, not while rendering). Signature: (def: WorkflowNodeDef, position?: { x: number; y: number }) => WorkflowNode.
- `DEFAULT_WORKFLOW_CANVAS_LABELS` (constant): The English strings, to spread under your translations. Type: WorkflowCanvasLabels.

```tsx
import { useState } from "react"
import { CalendarClock, Flag, Mail, Search, Split } from "lucide-react"
import {
  WorkflowCanvas,
  layoutWorkflow,
  type WorkflowEdge,
  type WorkflowNodeDef,
  type WorkflowValue,
} from "@/components/ui/workflow-canvas"
// the component imports @xyflow/react/dist/base.css itself; Next and Vite accept a package css import in a client component
import { AlertDialogProvider } from "@/components/ui/alert-dialog"

// the step catalog, at module scope so it keeps its identity
const nodeTypes: WorkflowNodeDef[] = [
  { type: "schedule", kind: "trigger", label: "Daily at a set time", icon: <CalendarClock />, group: "Triggers" },
  { type: "find-invoices", kind: "action", label: "Find invoices", icon: <Search />, group: "CRM actions" },
  { type: "condition", kind: "condition", label: "Condition", icon: <Split />, group: "Logic" },
  { type: "send-email", kind: "action", label: "Send email", icon: <Mail />, group: "Communication" },
  { type: "end", kind: "end", label: "End", icon: <Flag />, group: "Logic" },
]

const edges: WorkflowEdge[] = [
  { id: "e1", source: "start", target: "find" },
  { id: "e2", source: "find", target: "check" },
  { id: "e3", source: "check", target: "send", sourceHandle: "yes" },
  { id: "e4", source: "check", target: "stop", sourceHandle: "no" },
]

const initial: WorkflowValue = {
  nodes: layoutWorkflow(
    [
      { id: "start", type: "schedule", position: { x: 0, y: 0 }, data: { title: "Daily at 9:00 AM" } },
      { id: "find", type: "find-invoices", position: { x: 0, y: 0 }, data: { title: "Find overdue invoices" } },
      { id: "check", type: "condition", position: { x: 0, y: 0 }, data: { title: "Balance over $1,000?" } },
      { id: "send", type: "send-email", position: { x: 0, y: 0 }, data: { title: "Send reminder", subtitle: "Template: Payment reminder" } },
      { id: "stop", type: "end", position: { x: 0, y: 0 }, data: { title: "Nothing to send" } },
    ],
    edges,
    { nodeTypes },
  ),
  edges,
}

export function AutomationEditor() {
  const [workflow, setWorkflow] = useState(initial)
  return (
    <div className="h-[560px]">
      <WorkflowCanvas
        nodeTypes={nodeTypes}
        value={workflow}
        onValueChange={setWorkflow}
        onRun={() => console.log("Run", workflow)}
        />
      {/* once near the root: confirms deleting a connected step */}
      <AlertDialogProvider />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/workflow-canvas (Markdown: https://wingo-ui.com/components/workflow-canvas.md)

### Text & Effects

#### Gravity Letters (`gravity-letters`)

component · free · v1.0.1 · install: `npx wingo-ui@latest add gravity-letters`

A playful gravity field where letters, numbers, emoji, or any components you pass fall and pile up like real objects.

The field opens by pouring its initial text, letter by letter, onto the floor. Click or tap anywhere to drop a glyph, or press and hold to pour a steady stream that follows your pointer. Glyphs tumble as they fall, bounce softly when they land, and pile up into rounded hills. On phones, tilt the device to spill the pile toward the low side. With reduced motion on, glyphs appear straight on the pile.
Wingo UI dependencies: ui-config

Props:
- `type?: "letters" | "numbers" | "both"` = "letters": Which pool to draw from: letters, digits, or both. Ignored when items is set.
- `initialText?: string` = "HELLO": Letters poured across the middle of the field on mount, one after another, so it never starts empty. Spaces leave gaps; pass an empty string for a blank field.
- `items?: React.ReactNode[]`: Your own drop pool: emoji, icons, or any components. Each drop picks a random entry. Overrides type.
- `gravity?: number` = 800: Downward acceleration in px/s². Lower is floatier, higher is heavier. Changes apply mid-fall.
- `size?: number` = 28: Base glyph size in pixels. Each drop varies by up to 20% around it. Applies to new drops.
- `color?: string` = "currentColor": Glyph color, any CSS color. Defaults to currentColor so it follows your theme.
- `weight?: "normal" | "medium" | "semibold" | "bold"` = "semibold": Font weight of the falling glyphs.
- `sizeVariance?: number` = 0.2: How much a dropped glyph's size varies around size: 0.2 means 80% to 120%. initialText letters always use size exactly.
- `bounce?: number` = 0.22: How much of its speed a glyph keeps on its first touch down, 0 (a thud) to 0.95.
- `holdDelay?: number` = 300: How long a press has to last, in milliseconds, before glyphs start pouring.
- `pourInterval?: number` = 120: Time between glyphs while pouring, in milliseconds.
- `maxGlyphs?: number` = 0: Max glyphs kept in the field; past the cap the oldest fade out and the pile settles into the gap. 0 keeps every glyph, which is the default.
- `deviceTilt?: boolean` = true: Tilting a phone spills the pile toward the low side. iOS asks for motion permission on the first tap.
- `children?: React.ReactNode`: Rendered under the glyph layer, e.g. a hint or an empty state. Clicks on it still drop glyphs unless a handler calls preventDefault.
- `className?: string`: Extra classes for the root element. Use it to size the field; glyphs pile on its bottom edge and are clipped to it. Pointer handlers you pass run before the drop.

```tsx
import GravityLetters from "@/components/ui/gravity-letters"

export function Demo() {
  return (
    <GravityLetters type="letters" className="h-96 w-full rounded-3xl border">
      {/* anything you render inside sits under the falling glyphs */}
      <p className="absolute inset-0 grid place-items-center text-sm text-muted-foreground">
        Click anywhere
      </p>
    </GravityLetters>
  )
}

// A blank field, or your own opening word:
// <GravityLetters initialText="" />
// <GravityLetters initialText="404" type="numbers" />

// Digits instead:
// <GravityLetters type="numbers" />

// Or drop your own content: emoji, icons, any component:
// <GravityLetters items={["🍎", "🍊", "🍇", <Sparkles key="s" className="size-7" />]} />
```

Docs: https://wingo-ui.com/components/gravity-letters (Markdown: https://wingo-ui.com/components/gravity-letters.md)

### Mobile

#### Action Sheet (`action-sheet`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add action-sheet`

The iOS action sheet: a short list of actions about one thing, with a title, red destructive rows and a separate Cancel, plus await show().

Tap the trigger and, on a phone, the page dims while the sheet slides up from the bottom: the title card with its actions floats 8px above the home indicator and Cancel sits in its own card under it (material: one attached sheet with a handle, icon rows and Cancel as the last row). Tap an action to run it and close the sheet; tap Cancel or the dimmed page, or drag the sheet down, to dismiss. An action that returns a promise shows a spinner in its row while the other rows dim and wait; the sheet closes when it resolves, and when it fails the row shakes and stays ready to retry. From 768px it opens as a compact dialog (or a menu anchored to the trigger with desktop="popover", or the same sheet with desktop="sheet"). Keyboard: focus lands on the first action (on Cancel when the first action is destructive), Up and Down move between the actions and Cancel, Home and End jump to the ends, Enter or Space runs the focused one, Tab cycles inside, Escape cancels and focus returns to the trigger, or for show() to whatever had it before. With reduced motion the sheet and dialog fade and nothing shakes.

npm: motion, lucide-react
Wingo UI dependencies: button, dialog, drawer, popover, spinner, use-controllable-state, use-media-query, motion, tones, ui-config

Props:
- `title?: ReactNode` = "": What the actions are about, e.g. the listing's name. Small and gray in the iOS card, a heading in material and the dialog, a group label in the menu. Without one the sheet still has a hidden title (labels.sheetTitle).
- `message?: ReactNode` = "": A short explanation under the title; it becomes the sheet's accessible description.
- `actions?: ActionSheetAction[]`: { id, label, icon?, description?, tone?: "neutral" | "brand" | "danger", disabled?, onSelect?: () => void | Promise<unknown>, keepOpen?, badge? }. A promise from onSelect keeps the sheet open with a spinner in the row until it settles; a rejection shakes the row. keepOpen runs it without closing.
- `groups?: ActionSheetAction[][]`: Several groups: separate cards on iOS, separated blocks in material and on desktop. Replaces actions.
- `cancelLabel?: string` = "Cancel": The Cancel button's text (wins over labels.cancel).
- `labels?: Partial<ActionSheetLabels>`: { cancel, sheetTitle }, merged over DEFAULT_ACTION_SHEET_LABELS ("Cancel", "Actions"). sheetTitle is the hidden accessible title while title is empty.
- `trigger?: ReactNode`: The element that opens it, rendered with asChild (a single element that takes a ref, e.g. a Button).
- `variant?: "ios" | "material"` = "ios": ios: floating cards with 56px centered rows and a separate Cancel card. material: one attached sheet with a handle, 48px rows with icons at the start and Cancel as the last row.
- `align?: "auto" | "center" | "start"` = "auto": Row text alignment. auto centers the iOS sheet's rows and starts material and desktop rows (icons at the start).
- `showIcons?: boolean` = false: Shows each action's icon at the row's start. When unset: off for the iOS sheet, on for material and on desktop; true forces them on, false off.
- `showCancel?: boolean` = true: The Cancel button. Without it the sheet closes by drag, a tap on the dimmed page or Escape. The anchored menu never shows one.
- `classNames?: Partial<Record<ActionSheetSlot, string>>`: Classes for the parts: overlay, content, header, title, message, group, action, icon, label, description, badge, spinner, cancel. className goes on the root (action-sheet).
- `defaultOpen?: boolean` = false: Starts open (uncontrolled). Pass open and onOpenChange instead to control it.
- `open?: boolean`: Controlled open state; pair it with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Called when it opens or closes. Closes are refused while an action's promise is running.
- `desktop?: "dialog" | "popover" | "sheet"` = "dialog": What renders at 768px and up: a compact 400px dialog, a menu anchored to the trigger, or the phone sheet. Phones always get the sheet; without a trigger popover falls back to the dialog.
- `container?: HTMLElement | null`: Portal target; document.body by default.
- `closeOnAction?: boolean` = true: Closes after an action runs (after its promise resolves). Off: the sheet stays open until Cancel or a dismiss; an action can also opt out with keepOpen.
- `onAction?: (id: string) => void`: Fires for every chosen action with its id, after its onSelect (after the promise resolves).

```tsx
"use client"

import { MoreHorizontal, Pencil, Share, Trash2 } from "lucide-react"
import { ActionSheet, ActionSheetProvider, useActionSheet } from "@/components/ui/action-sheet"
import { Button } from "@/components/ui/button"

// declarative: pass a trigger and the actions
export function ListingMenu() {
  return (
    <ActionSheet
      title="2-bedroom apartment, Brooklyn"
      cancelLabel="Cancel"
      trigger={
        <Button variant="ghost" size="icon" radius="full" aria-label="Listing actions">
          <MoreHorizontal />
        </Button>
      }
      actions={[
        { id: "edit", label: "Edit listing", icon: <Pencil /> },
        { id: "promote", label: "Promote", tone: "brand", badge: "from $19" },
        { id: "share", label: "Share", icon: <Share /> },
        {
          id: "delete",
          label: "Delete listing",
          icon: <Trash2 />,
          tone: "danger",
          onSelect: () => new Promise((resolve) => setTimeout(resolve, 1200)),
        },
      ]}
      onAction={(id) => console.log(id)}
    />
  )
}

// imperative: useActionSheet().show(options) opens the provider's sheet and resolves with the
// chosen action's id, or null on cancel or dismiss. options are the ActionSheet props without
// open / defaultOpen / onOpenChange / trigger. a second show() replaces the open sheet (the first
// resolves null), focus returns to whatever had it, and the hook throws without a provider.
function PhotoMenu() {
  const actionSheet = useActionSheet()
  const open = async () => {
    const id = await actionSheet.show({
      actions: [
        { id: "save", label: "Save to photos" },
        { id: "delete", label: "Delete for me", tone: "danger" },
      ],
    })
    if (id) console.log(id)
  }
  return <Button onClick={open}>Photo options</Button>
}

// mount ActionSheetProvider once near the root; its defaults prop (ActionSheetOptions) sits
// under every show() call's own options, e.g. translated labels or a house variant
export function App() {
  return (
    <ActionSheetProvider defaults={{ cancelLabel: "Cancel" }}>
      <ListingMenu />
      <PhotoMenu />
    </ActionSheetProvider>
  )
}
```

Docs: https://wingo-ui.com/components/action-sheet (Markdown: https://wingo-ui.com/components/action-sheet.md)

#### Bottom Tab Bar (`bottom-tab-bar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add bottom-tab-bar`

The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll.

Tap a tab and the pill glides to it on a quick spring while the icon pops and swaps to its filled version; the icon dips while your finger is down. Tap the tab you are already on to scroll its page back to the top, or, on a nested page, to go back to the tab's first screen. The raised center button presses like a button and runs its action. Counts and dots sit on the icons and bounce in when they change. With hideOnScroll the bar follows your finger down out of view and comes back as soon as you scroll up or reach the end. On a keyboard Tab reaches every tab, ArrowLeft / ArrowRight move between them, Home / End jump to the first and last, Enter opens; the bar never hides while keyboard focus is inside it. On a phone it clears the home indicator (safe area) and every tab is far bigger than 44px. Under reduced motion the pill jumps and nothing pops.

npm: motion
Wingo UI dependencies: badge, use-controllable-state, use-scroll-state, motion, navigation, tones, ui-config

Props:
- `items: BottomTabBarItem[]`: 3 to 5 tabs (a dev warning above 5). The shared NavItem shape: id, label, href, icon, activeIcon (shown while active, e.g. a filled glyph), badge (a number is a count, a node renders as is), disabled, match, onSelect; plus dot: true for an 8px dot instead of a count. Items without href are buttons.
- `value?: string`: The active tab's key (navItemKey: id, else href, else the label). Controls the bar.
- `defaultValue?: string`: The first active tab while uncontrolled and no current path is known. Default: the first enabled tab.
- `onValueChange?: (key: string, item: BottomTabBarItem) => void`: Fires whenever another tab is activated, in every mode (controlled, router, uncontrolled).
- `currentPath?: string` = "": The current pathname. Empty: the LinkProvider's. With a path the router decides the active tab (the longest matching href) and clicks store nothing. Try /inbox or /clients/northwind-tech.
- `action?: { label: string; icon: ReactNode; onSelect?: () => void; href?: string }`: The raised center button (Add, Compose, Scan), placed in the middle of the tabs (with 4 tabs: 2, action, 2). label becomes its aria-label; filled with the tone.
- `variant?: "bar" | "floating"` = "bar": bar: full width on the bottom edge with a glass surface and a hairline (iOS). floating: an inset glass pill above the safe area (iOS 26), the pill indicator behind the whole tab.
- `indicator?: "pill" | "line" | "dot" | "none"` = "pill": pill: a 56x32 tinted pill behind the icon (Material 3). line: a 2px bar on the top edge of the tab. dot: a 4px dot under the label. none: color only. Every one moves between tabs on a snappy spring.
- `showLabels?: "always" | "active" | "never"` = "always": active: only the active tab shows its label and the others center their icon. never: icons only; the labels stay for screen readers and as tooltips.
- `size?: "sm" | "md"` = "md": Bar height 56 / 64px, icons 22 / 24px, labels 10 / 11px. Both stay far above 44px targets.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active color (neutral: the foreground, with a gray pill) and the fill of the center action. Other tones tint the pill and the active label.
- `color?: string` = "": Any CSS color. Replaces the tone for the active tab and the action. Leave empty to use the tone.
- `badgeTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "danger": The fill of count badges and dots. Red by default: on every platform people read a red count as unread.
- `badgeLabel?: string` = "unread": Read by screen readers after a count: "Inbox, 4 unread". The visible badge is hidden from them.
- `dotLabel?: string` = "new": Read by screen readers after a dot: "Profile, new".
- `aria-label?: string` = "Primary": The name of the <nav> landmark.
- `hideOnScroll?: boolean` = false: Slides down while you scroll down, following the finger, and comes back on scroll up, at the end of the content and whenever focus is inside. Transform only, no re-render per frame.
- `position?: "auto" | "fixed" | "sticky" | "static"` = "auto": auto: fixed to the viewport, or static inside an app shell whose content column scrolls. sticky: sticky bottom-0 as the last child of a scroll container (phone frames, demos). static: in the flow. Writes --bottom-bar-offset (on <html> when fixed, else on its parent) so floating buttons clear it.
- `safeArea?: boolean` = true: Pads env(safe-area-inset-bottom) so the tabs clear the iPhone home indicator (the floating pill keeps at least 12px). It is 0 in desktop browsers.
- `haptics?: boolean` = true: A 10ms vibration on a tab change where the browser supports it (Android; iOS ignores it).
- `scrollToTopOnReselect?: boolean` = true: Tapping the active tab scrolls its page to the top (iOS). On a nested page the tab first goes back to its root.
- `onReselect?: (item: BottomTabBarItem) => void`: Runs when the active tab is tapped again (refresh a feed, focus a search).
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for hide on scroll and reselect. Default: the nearest ScrollContainerProvider, else the window.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for this bar only (a component, or "a"). Usually set once for the app with LinkProvider.
- `classNames?: Partial<Record<"inner" | "list" | "link" | "icon" | "label" | "indicator" | "action", string>>`: Extra classes for the inner parts: the bar surface, the list, each tab link, icon box, label, the indicator and the action.
- `className?: string`: Extra classes for the <nav>, merged last. Set [--bar-bg:var(--surface)] when the bar sits on a surface other than the page.

```tsx
"use client"

import { House, Inbox, Plus, UserRound, Users } from "lucide-react"
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar"

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House />, activeIcon: <House className="fill-current" /> },
  { label: "Clients", href: "/clients", icon: <Users />, activeIcon: <Users className="fill-current" /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Profile", href: "/profile", icon: <UserRound />, activeIcon: <UserRound className="fill-current" /> },
]

export function MobileNav({ onCreate }: { onCreate: () => void }) {
  return (
    <BottomTabBar
      className="md:hidden"
      items={tabs}
      action={{ label: "Add", icon: <Plus />, onSelect: onCreate }}
      hideOnScroll
    />
  )
}
```

Docs: https://wingo-ui.com/components/bottom-tab-bar (Markdown: https://wingo-ui.com/components/bottom-tab-bar.md)

#### FAB (`fab`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add fab`

The floating action button for a phone screen's main action, with a labelled or radial speed dial and a label that folds while you scroll.

Tap the round button in the thumb zone. Without actions it runs its one action; with actions the page dims and a speed dial rises from it, nearest action first, while the plus turns into an x and the phone ticks once. Vertical dials show a label chip beside each round action and the whole row is the target; radial dials fly small round actions out on an arc (a half arc when centered) and show each label as a tooltip on hover, focus or a long press. Tap an action to run it and close the dial, tap the dimmed page or the x to close without choosing. With a label the button starts extended ("Add"); scroll down and it folds to the icon, scroll up and the label comes back. With hideOnScroll it slides out while you scroll down and returns when you scroll up, never while it is open or focused, and it steps aside while the on-screen keyboard is up. It sits above the bottom tab bar and the sticky buy bar and clears the home indicator (once, never twice). Keyboard: Enter, Space or ArrowUp open the dial and focus the nearest action; ArrowUp / ArrowDown move (radial dials also Left / Right), Home / End jump, Enter or Space runs, Escape closes and returns focus to the button, Tab closes and moves on. shortcut opens it from anywhere. With a mouse the button and every action tint on hover; while the button shows only its icon (or has a shortcut) hovering or focusing it shows its name and the shortcut in a tooltip, and a long press shows it on touch.

npm: motion, lucide-react
Wingo UI dependencies: tooltip, navigation, use-scroll-state, use-keyboard-inset, use-shortcut, use-controllable-state, haptics, motion, tones, ui-config

Props:
- `label?: string` = "": The extended label ("Add") and the button's accessible name. Without it the name is labels.open / labels.close with actions, else labels.action.
- `icon?: ReactNode` = "<Plus />": The button's icon. Unsized svgs follow the size (20 / 24 / 28px).
- `openIcon?: ReactNode`: Shown while the dial is open. Default: the plus turns 45 degrees into an x; a custom icon cross-fades to an <X />.
- `actions?: FabAction[]`: The speed dial, 2 to 6 entries: { id, label, icon, onSelect?, href?, tone?: "neutral" | "danger", disabled? }. Actions with href render a NavLink and close the dial. Without actions the FAB is a plain button (onClick).
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: The action when there is no dial. With actions it runs before the dial toggles; preventDefault keeps it closed.
- `layout?: "vertical" | "radial"` = "vertical": vertical: a column of labelled actions above the button (Material). radial: small round actions on a quarter arc around it (a half arc when centered), labels as tooltips.
- `extended?: "auto" | "always" | "never"` = "auto": Needs a label. auto: the label shows at the top of the page and while scrolling up, and folds to the icon while scrolling down. always keeps it, never shows the icon alone.
- `variant?: "solid" | "soft" | "surface"` = "solid": solid: filled with the tone. soft: a tinted fill that stays opaque over the page. surface: a popover-colored button with a toned icon (Material 3 surface FAB).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color. neutral is black in light mode and white in dark mode; brand is for the one hero action of a marketplace.
- `color?: string` = "": Any CSS color. Replaces the tone; text on a solid fill turns black or white by lightness.
- `size?: "sm" | "md" | "lg"` = "md": Button 48 / 56 / 64px with 20 / 24 / 28px icons and a 14 / 15 / 16px label; dial actions 40 / 44 / 48px (sm grows to 44px on touch).
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape, 0 / 12 / 16 / 20px at md and scaled per size; full is a circle, a pill when extended. Dial actions follow.
- `defaultOpen?: boolean` = false: Starts with the dial open. Control it with open and onOpenChange.
- `open?: boolean`: The dial's open state, controlled.
- `onOpenChange?: (open: boolean) => void`: Runs when the dial opens or closes.
- `position?: "fixed" | "sticky" | "absolute"` = "fixed": fixed to the viewport (the app default); sticky to the bottom of its scroll container (render it as the last child: phone frames, panels); absolute inside a relative container (a map, a card).
- `side?: "end" | "start" | "center"` = "end": Logical side, so end is right in left-to-right pages and left in right-to-left ones. center opens a half-arc dial.
- `offset?: number` = 16: px from the side and from what is below it: the bottom tab bar (--bottom-bar-offset), the sticky buy bar (--cta-bar-offset) and the home indicator.
- `hideOnScroll?: boolean` = false: Slides out while you scroll down, following the finger, and comes back when you scroll up. Never while open or focused.
- `hideOnKeyboard?: boolean` = true: Steps aside while the on-screen keyboard is open (and closes an open dial), so it never covers the field you type in.
- `scrim?: boolean` = true: Dims and softly blurs the page behind an open dial; a tap on it closes. Without it a press anywhere else closes.
- `closeOnAction?: boolean` = true: Closes the dial after an action runs. Actions with href always close.
- `haptics?: boolean` = true: A light tick when the dial opens and when an action runs, on touch only (never for a mouse click or a key).
- `shortcut?: string` = "": A key combo that opens the dial (or runs the action), e.g. "n" or "mod+shift+n". Shown in the button's tooltip and set as aria-keyshortcuts.
- `safeArea?: boolean` = true: Keeps clear of the home indicator and the notch with env(safe-area-inset-*). The insets are 0 on desktops.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for extended="auto" and hideOnScroll. Default: the nearest ScrollContainerProvider, else (sticky and absolute) the scroll parent, else the window.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for actions with href. Default: the LinkProvider's component, else a plain <a>.
- `labels?: Partial<FabLabels>` = "DEFAULT_FAB_LABELS": Screen reader strings: open "Open actions", close "Close actions", menu "Actions", action "Create". The English set is exported as DEFAULT_FAB_LABELS.
- `classNames?: Partial<Record<"scrim" | "actions" | "action" | "actionLabel" | "actionIcon" | "trigger" | "icon" | "label", string>>`: Extra classes for the inner parts. className goes on the positioned root.

```tsx
import { FileText, Handshake, StickyNote, UserPlus } from "lucide-react"
import { Fab, type FabAction } from "@/components/ui/fab"

export function ClientsFab({ onCreate }: { onCreate: (kind: string) => void }) {
  const actions: FabAction[] = [
    { id: "client", label: "New client", icon: <UserPlus />, onSelect: () => onCreate("client") },
    { id: "invoice", label: "New invoice", icon: <FileText />, onSelect: () => onCreate("invoice") },
    { id: "quote", label: "New quote", icon: <Handshake />, href: "/quotes/new" },
    { id: "note", label: "Note", icon: <StickyNote />, onSelect: () => onCreate("note") },
  ]
  return (
    <Fab
      label="Add"
      actions={actions}
      shortcut="n"
      labels={{ open: "Show create actions", close: "Hide create actions", menu: "Create" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/fab (Markdown: https://wingo-ui.com/components/fab.md)

#### Haptic Button (`haptic-button`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add haptic-button`

A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode.

Tap it and it dips on a quick spring while a ripple spreads from under your finger; phones play a light tick (touch and pen only, a mouse click never vibrates). With onLongPress, holding a finger or pen for 450ms plays a medium tick and runs the secondary action; a right click, Shift+F10 or the ContextMenu key do the same, and the click after a long press is swallowed. In hold mode a click does nothing: hold the finger, the mouse button, Space or Enter and the button fills from the start edge; let go early and the fill springs back, a quick tap shakes the button, plays a warning tick and shows a "Hold to confirm" chip above it. Moving more than 8px, leaving the button, switching tabs or blurring the window cancels. When the fill completes the button pops, onConfirm runs (a promise shows the spinner), then a check replaces the label for 1.2s with a success tick; a rejected promise shakes with an error tick. Screen readers, voice control and switch access, which activate with a plain click and cannot hold, get a two-step path: the first activation shows and announces "Activate again to confirm", a second one within 4s confirms. Outcomes are announced to screen readers. Under reduced motion there is no dip, ripple, pop or shake; the fill still grows.

npm: lucide-react, motion
Wingo UI dependencies: haptics, motion, tones, ui-config, use-long-press

Props:
- `children?: ReactNode` = "Send": The label. For icon sizes pass the icon and an aria-label. The playground swaps the sample for "Hold to send" in hold mode.
- `variant?: "solid" | "soft" | "outline" | "ghost"` = "solid": The button's variants (no link: a link has no surface to ripple or fill).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Semantic color from the design tokens. danger for a hold to delete, brand for a hold to pay.
- `color?: string` = "": Any CSS color. Replaces the tone in every variant; text on a solid fill turns black or white by lightness.
- `size?: "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg"` = "md": The button's sizes: 32 / 40 / 48px, square icon sizes. On touch screens md grows to 44px and sm gets a 44px hit area.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape, scaled per size like the button. The ripple and the fill follow it.
- `effect?: "scale" | "ripple" | "both" | "none"` = "both": Press feedback: the 0.97 dip on a snappy spring, a ripple spreading from the touch point (keyboard presses ripple from the center), both, or none. In hold mode the fill replaces the ripple.
- `rippleColor?: string` = "": The ripple color. Empty uses the text color at 16%; a custom color shows at 30%.
- `loading?: boolean` = false: Spinner in place of the label, width kept, aria-busy; presses and holds are ignored and focus stays. Also on while an onConfirm promise runs.
- `loadingText?: ReactNode`: Text next to the spinner while loading. The button reserves room for it.
- `disabled?: boolean` = false: Dims the button and blocks presses, holds and long presses.
- `fullWidth?: boolean` = false: Stretches to the container width, the usual choice for the main action on a phone.
- `mode?: "press" | "hold"` = "press": press is a normal button. hold: a click does nothing; holding a finger, the mouse button, Space or Enter for holdDuration fills the button and calls onConfirm. For destructive or money actions that deserve more than a tap but less than a dialog.
- `holdDuration?: number` = 1200: Milliseconds of holding to confirm, clamped to 300..5000.
- `showSuccess?: boolean` = true: After onConfirm (and its promise) a check replaces the label for 1.2s and the button gets data-confirmed.
- `haptics?: boolean` = true: Haptic ticks through lib/haptics on touch and pen presses (never for a mouse or on desktops). Turn off app-wide with configureHaptics({ enabled: false }).
- `hapticKind?: "selection" | "light" | "medium" | "heavy" | "success" | "warning" | "error"` = "light": The press-mode tick. Hold mode always plays light at the start, success on confirm, warning on a too-short tap and error on a rejected promise; a long press plays medium.
- `type?: "button" | "submit" | "reset"` = "button": Defaults to "button". In hold mode a submit button never submits on a click; submit from onConfirm.
- `leftIcon?: ReactNode`: An icon before the label. Unsized svgs follow the size (14 / 16 / 18px).
- `rightIcon?: ReactNode`: An icon after the label.
- `spinner?: ReactNode`: Replaces the default spinner.
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Press mode only, and not while loading or disabled. Hold mode never calls it: put the action in onConfirm.
- `onConfirm?: () => (void | Promise<unknown>)`: Hold mode's action, called when the fill completes. A promise shows the loading state, then the check; a rejection shakes the button, plays an error tick and announces labels.failed.
- `onHoldStart?: () => void`: A hold began (finger, pen, mouse button, Space or Enter).
- `onHoldCancel?: () => void`: A hold ended before the fill completed: released, moved past 8px, left the button, window blurred, or disabled.
- `onLongPress?: (event: LongPressEvent<HTMLButtonElement>) => void`: Press mode's secondary action: a 450ms touch or pen hold (through useLongPress), a right click, Shift+F10 or the ContextMenu key. The click after a long press is swallowed; screen readers hear labels.longPressHint.
- `labels?: Partial<HapticButtonLabels>`: Strings: holdHint "Hold to confirm", holding "Keep holding", confirmed "Done", failed "That did not work, try again", longPressHint "Press and hold for more options", activateAgain "Activate again to confirm" (hold mode, after a click from assistive tech). DEFAULT_HAPTIC_BUTTON_LABELS holds the defaults.
- `classNames?: Partial<Record<"effects" | "ripple" | "fill" | "content" | "icon" | "spinner" | "check" | "hint", string>>`: Extra classes for the inner parts: the effects layer, each ripple, the hold fill, the label, icons, spinner, check and hint chip.
- `className?: string`: Extra classes for the button itself, merged last. Override the tone vars here, e.g. [--tone-foreground:white].

```tsx
import { Trash2 } from "lucide-react"
import { HapticButton } from "@/components/ui/haptic-button"

export function DeleteClient({ onDelete }: { onDelete: () => Promise<void> }) {
  return (
    <HapticButton
      tone="danger"
      variant="soft"
      mode="hold"
      holdDuration={1200}
      leftIcon={<Trash2 />}
      fullWidth
      onConfirm={onDelete}
      labels={{
        holdHint: "Hold to delete",
        confirmed: "Deleted",
        activateAgain: "Activate again to delete",
      }}
    >
      Delete Old Mill Bakery
    </HapticButton>
  )
}
```

Docs: https://wingo-ui.com/components/haptic-button (Markdown: https://wingo-ui.com/components/haptic-button.md)

#### Hero Header (`hero-header`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add hero-header`

The photo header of a phone detail page: a full-bleed image under the status bar with round glass buttons, parallax and a handover to a bar.

The photo fills the top of the page right up to the edge, under the status bar, with round frosted buttons on top (back, share, favorite) that stay readable on any photo. Scroll and the photo moves slower than the page and slowly darkens; in the last 32px before its bottom edge reaches the bar, the glass or solid bar fades in, the compact title rises into it and the round buttons lose their glass and turn into tinted bar buttons, all following your finger. Pull past the top on an iPhone and the photo stretches from its top edge instead of leaving a gap. With onMediaClick a tap on the photo opens it (a lightbox); on custom media like a carousel a tap on the slide opens it while swipes and its own buttons keep working. With a mouse everything is a click; with the keyboard Tab goes back, actions, then the photo button, each with a visible ring (inside the photo, with a white edge so it reads on dark and light photos). On touch the round buttons are 44px. Under reduced motion there is no parallax and no stretch, and the bar takes over in one short fade.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, button, navigation, use-scroll-state, motion, tones

Props:
- `image?: string` = "": The photo's src. Loaded with fetchPriority="high" and object-cover; a softly pulsing bg-foreground/10 block of the same height holds its place while it loads, so nothing shifts. A broken src shows an icon and labels.imageError.
- `imageAlt?: string` = "": The photo's alt text. Leave empty when the photo is decorative (the page's <h1> says what it is).
- `media?: ReactNode`: Replaces the image: a Carousel, a video, a map. It gets the same parallax, stretch, scrim and shade. Size it to the hero with h-(--hero-header-height).
- `title?: ReactNode` = "": The compact title that rises into the bar after the handover. It is aria-hidden: the page keeps its own <h1> below the hero. Without a title the bar shows only the buttons.
- `backLabel?: string` = "": The back button's text, usually the previous page ("Listings"). The button renders when backHref or onBack is set; without a label it is a round chevron named by backAriaLabel.
- `backAriaLabel?: string` = "Back": The back button's accessible name when it shows only the chevron.
- `backHref?: string` = "": Makes the back button a link through NavLink (the app's router link).
- `onBack?: () => void`: Runs when the back button is pressed (with backHref, before the navigation).
- `actions?: ReactNode`: Trailing round buttons: plain <Button variant="ghost" size="icon" radius="full" aria-label="…" />s. The header restyles its direct button and link children per buttonStyle while they sit on the photo, and turns them into tinted bar buttons after the handover.
- `height?: number` = 320: The hero's height in px, capped at 70dvh so a tall value never hides the whole page on a short phone.
- `buttonStyle?: "glass" | "solid" | "plain"` = "glass": The round buttons over the photo: frosted dark glass with white icons, a solid popover disc with a shadow, or bare white icons (use with the scrim). All become plain bar buttons after the handover.
- `background?: "blur" | "solid"` = "blur": The bar after the handover: frosted glass or the solid page color. Set [--bar-bg:var(--surface)] on the header when the page is not bg-background.
- `border?: "scrolled" | "always" | "never"` = "scrolled": The hairline under the bar: shown once the bar has taken over, always, or never.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The tint of the back button and the actions once they sit in the bar. Over the photo they stay white (glass, plain) or neutral (solid).
- `color?: string` = "": Any CSS color for the bar buttons after the handover. Replaces the tone.
- `scrim?: boolean` = true: A top gradient (black 45% to clear) that stays under the bar while the photo scrolls, so the status bar and the buttons read on bright photos. Turn it off for dark photos.
- `fade?: boolean` = true: The photo darkens (up to 45%) as it scrolls away, which makes the handover to the bar feel deliberate.
- `parallax?: number` = 0.5: How much slower the photo moves than the page: 0 scrolls with it, 0.5 at half speed, 1 stays put while the page slides over it. Off under reduced motion.
- `stretch?: boolean` = true: Pulling past the top (iOS overscroll, where the scroller reports negative offsets) scales the photo from its top edge instead of showing a gap. Nothing happens where browsers do not bounce. Off under reduced motion.
- `safeArea?: boolean` = true: The bar pads env(safe-area-inset-top) and the photo runs under the status bar in a standalone PWA. It is 0 in desktop browsers. A frame that fakes a status bar can set --hero-header-inset on the header instead.
- `onMediaClick?: () => void`: Makes the photo a button named labels.openMedia (open a lightbox). With custom media, a click on the media surface opens it (its own controls and drags do not), and a focusable button appears for the keyboard.
- `onCollapsedChange?: (collapsed: boolean) => void`: Called when the bar has fully taken over and when the photo comes back: switch the status bar theme color, log a view.
- `children?: ReactNode`: Pinned to the bottom of the photo: a "1 / 12" chip, badges. It fades out just before it slides under the bar. Chip look: rounded-full bg-black/50 px-2.5 py-1 text-xs font-medium text-white backdrop-blur-md.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls. Default: the nearest ScrollContainerProvider, else the window. Put the hero at the top of it.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for backHref on this header only. Usually set once for the app with LinkProvider.
- `labels?: Partial<HeroHeaderLabels>`: The strings: openMedia ("Open photos"), imageError ("Photo unavailable"). Defaults in DEFAULT_HERO_HEADER_LABELS.
- `classNames?: Partial<Record<"bar" | "surface" | "hairline" | "leading" | "back" | "title" | "actions" | "media" | "image" | "scrim" | "shade" | "overlay", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. The root is display: contents so the bar sticks to the whole page (not only while the hero is in view); it carries data-collapsed for group-data-[collapsed]/hero: styling and passes CSS variables down (--bar-bg, --hero-header-inset).

```tsx
"use client"

import { useState } from "react"
import { Heart, Share } from "lucide-react"
import { Button } from "@/components/ui/button"
import { HeroHeader } from "@/components/ui/hero-header"

export function ListingPage() {
  const [saved, setSaved] = useState(false)

  return (
    <>
      <HeroHeader
        image="/demo/apartment.jpg"
        title="2-bedroom apartment"
        backLabel="Listings"
        backHref="/listings"
        onMediaClick={() => console.log("open gallery")}
        labels={{ openMedia: "Open photos", imageError: "Photo unavailable" }}
        actions={
          <>
            <Button variant="ghost" size="icon" radius="full" aria-label="Share">
              <Share />
            </Button>
            <Button
              variant="ghost"
              size="icon"
              radius="full"
              aria-label="Save to favorites"
              aria-pressed={saved}
              onClick={() => setSaved((v) => !v)}
            >
              <Heart className={saved ? "fill-current" : undefined} />
            </Button>
          </>
        }
      >
        <span className="rounded-full bg-black/50 px-2.5 py-1 text-xs font-medium text-white backdrop-blur-md">1 / 12</span>
      </HeroHeader>
      <main className="px-4 py-5">
        <h1 className="text-2xl font-bold">2-bedroom apartment, split floor plan</h1>
        <p className="text-sm text-muted-foreground">Brooklyn, New York · $489,000</p>
      </main>
    </>
  )
}
```

Docs: https://wingo-ui.com/components/hero-header (Markdown: https://wingo-ui.com/components/hero-header.md)

#### Install Prompt (`install-prompt`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add install-prompt`

Invites people to install the web app: the browser's install dialog in Chrome and Edge, an Add to Home Screen guide on iPhone and Mac.

A few seconds after the page can be installed, a slim card with the app's icon, name and an Install button slides up from the bottom (or drops from the top) and stays out of the way: it never takes focus and the page keeps working under it. On Android and desktop Chrome or Edge, Install opens the browser's own install dialog; the button shows a spinner while it is open, and once the app is installed the card says Installed with a check for two seconds and leaves. On an iPhone or iPad, where browsers have no such dialog, Install opens a bottom sheet with three numbered steps (tap Share, choose Add to Home Screen, tap Add), each with the icon you will look for, and on an iPhone an arrow at the bottom of the sheet bobs twice toward Safari's share button. On a Mac with Safari the card shows the Add to Dock steps inline. The × (named Not now) hides it for dismissDays and remembers that in localStorage; closing the sheet by dragging it down, tapping outside or pressing Escape counts the same. On a desktop Chrome window the banner is a 380px card in the bottom end corner. With the keyboard, Tab reaches Install and ×, Enter or Space presses them, and in the sheet (a centered dialog from 768px up) Tab stays inside and Escape closes it, returning focus to the button that opened it. Installed or already running as an app, it renders nothing. The outcome is announced to screen readers. Under reduced motion it fades instead of sliding.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, button, drawer, use-controllable-state, use-media-query, use-persisted-state, motion, tones

Props:
- `appName?: string` = "": The app's name, used in the titles ("Install Northwind CRM") and for the letter tile. Empty falls back to labels.fallbackName ("this app").
- `appIcon?: string | ReactNode` = "": The icon: an image src (shown 48px with 12px corners, use your 192px manifest icon) or an element. Empty draws a tile in the tone with the first letter of appName.
- `description?: string` = "": One line under the title: why installing helps. Truncated in the slim banner, wrapped in the sheet and the card.
- `screenshots?: string[]`: Sheet variant: a horizontal rail of screenshots (h-72, 9:16, snapping) between the title and the buttons, keyboard scrollable.
- `variant?: "banner" | "sheet" | "card"` = "banner": banner: a slim floating card pinned to placement, like a Smart App Banner (on iPhone its Install opens the guide sheet; on a Mac it shows the steps inline). sheet: a bottom sheet with details, a centered dialog from 768px up. card: an inline card you place yourself (a settings page), always visible while the app can be installed.
- `placement?: "bottom" | "top"` = "bottom": The banner's edge. Bottom sits above a bottom tab bar and a sticky CTA bar (--bottom-bar-offset, --cta-bar-offset) and the home indicator; top sits under the notch, or under --install-prompt-top when you set it (a fixed header).
- `position?: "fixed" | "absolute"` = "fixed": fixed pins the banner to the viewport (and turns it into a 380px card at the bottom end on desktop); absolute pins it inside the nearest positioned parent (a phone frame, a panel).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Install button and the letter tile. Keep neutral in an app; brand fits a marketing page.
- `color?: string` = "": Any CSS color for the Install button and the letter tile, replacing the tone.
- `radius?: "sm" | "md" | "lg"` = "md": Corners of the card and the floating banner: 12, 16 or 24px.
- `platform?: "auto" | "chromium" | "ios" | "macos-safari" | "unsupported"` = "auto": auto detects it: chromium once the browser has offered an install (beforeinstallprompt), ios on iPhone and iPad in any browser, macos-safari on Safari 17+ for Mac; in-app browsers and everything else are unsupported and render nothing. Force one for demos and QA; a forced chromium without a real event makes Install resolve "unavailable".
- `delay?: number` = 3000: Milliseconds after it becomes possible before the banner or sheet shows, so it never greets people on arrival. Ignored while open is controlled and by the card.
- `dismissDays?: number` = 14: How long Not now hides it, in days. 0 hides it for this session only (sessionStorage).
- `storageKey?: string` = "install-prompt": The localStorage key that remembers Not now (a timestamp). Empty keeps it in memory; with storage blocked it lasts the session.
- `showOnIOS?: boolean` = true: Show the Add to Home Screen guide on iPhone and iPad.
- `showOnDesktop?: boolean` = true: Show it in Chrome and Edge on a computer and the Add to Dock guide in Safari for Mac.
- `defaultOpen?: boolean` = false: Open the banner or sheet at once (no delay, a previous Not now ignored). An initially open banner skips its entrance.
- `open?: boolean`: Controlled open state of the banner or sheet; pair it with onOpenChange. It still renders nothing where there is no install path.
- `onOpenChange?: (open: boolean) => void`: Called when it opens after the delay and when it closes (Not now, installed, the sheet dismissed).
- `onInstall?: (outcome: "accepted" | "dismissed" | "unavailable") => void`: The result of Install in Chromium: accepted, dismissed in the browser dialog (the prompt cannot be shown again until the browser offers it again), or unavailable (no pending event).
- `onDismiss?: () => void`: Not now, the ×, Got it in the guide, or the sheet closed by drag, tap outside or Escape.
- `safeArea?: boolean` = true: Pad the banner off the notch, the home indicator and the rounded side edges (env(safe-area-inset-*)).
- `desktop?: "dialog" | "sheet"` = "dialog": What the sheet (and the iPhone guide) becomes at 768px and up: a centered dialog, or the same bottom sheet capped at 420px.
- `container?: HTMLElement | null`: Portal target of the sheet (default document.body). A transformed or contain:layout element keeps the sheet inside it, like a phone frame.
- `labels?: Partial<InstallPromptLabels>`: Every string: install "Install", notNow "Not now", title(name) "Install {name}", iosTitle(name) "Add {name} to your Home Screen", iosSteps ["Tap Share in the toolbar", "Scroll and choose Add to Home Screen", "Tap Add"], macTitle(name) "Add {name} to the Dock", macSteps ["Choose File in the menu bar", "Choose Add to Dock"], installed "Installed", fallbackName "this app", close "Close", done "Got it", installedAnnouncement(name) "{name} was installed", screenshots "Screenshots", screenshot(i, n) "Screenshot {i} of {n}", addGlyph "Add", fileGlyph "File". Defaults in DEFAULT_INSTALL_PROMPT_LABELS.
- `classNames?: Partial<Record<"icon" | "content" | "title" | "description" | "screenshots" | "steps" | "step" | "actions" | "install" | "dismiss", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root: the banner's pinned wrapper, the card, or the sheet's content.

Parts:
- `useInstallPrompt` (hook): The same engine without the UI, for your own button (a profile menu item). One store per page listens for beforeinstallprompt and appinstalled from the first call on, so call it (or mount InstallPrompt) in the root layout: the event fires once, early. canInstall is true while the browser prompt is pending (chromium) or the guide applies (ios, macos-safari). Signature: (options?: { platform?: "auto" | InstallPlatform; storageKey?: string; dismissDays?: number }) => { platform: InstallPlatform; canInstall: boolean; isStandalone: boolean; installed: boolean; dismissed: boolean; promptInstall: () => Promise<"accepted" | "dismissed" | "unavailable">; dismiss: () => void; reset: () => void }.
- `DEFAULT_INSTALL_PROMPT_LABELS` (constant): The English defaults, to spread and override. Type: InstallPromptLabels.

```tsx
// app/layout.tsx: mount it once in the root layout, the browser offers the install only once and early
import type { ReactNode } from "react"
import { InstallPrompt } from "@/components/ui/install-prompt"

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <InstallPrompt
          appName="Northwind CRM"
          appIcon="/icon-192.png"
          description="Open it right from your home screen, even offline."
          labels={{
            notNow: "Maybe later",
            iosSteps: ["Tap Share in the bottom bar", "Choose Add to Home Screen", "Tap Add"],
          }}
        />
      </body>
    </html>
  )
}
```

Docs: https://wingo-ui.com/components/install-prompt (Markdown: https://wingo-ui.com/components/install-prompt.md)

#### Large Title Header (`large-title-header`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add large-title-header`

An iOS large title that scrolls with the page and hands over to a compact title in a glass bar, with back, actions and search.

Scroll the page and the large title slides up with the content, fading as it passes under the bar; exactly when it disappears the compact title rises into the bar and the glass surface and hairline fade in, all following your finger. Let go halfway through the handover and it settles to fully expanded or fully collapsed. Pull past the top on a phone and the title stretches up to 8% from its corner. Tap the search field and the page scrolls so the field sits right under the bar, the Cancel button slides in from the end and the field makes room; type to filter, tap the clear button to empty it, tap Cancel (or press Escape) to clear, close the keyboard and return to the top. The back button (a link or a button, labelled with the previous page) and the trailing actions stay in the bar at 44px on touch. With the keyboard Tab goes back, actions, search, cancel; the title is the page's only <h1>, and when Escape or Cancel ends a search from the keyboard, focus returns to it instead of getting lost. Under reduced motion the handover is an instant switch and nothing stretches or slides.

npm: motion, lucide-react
Wingo UI dependencies: ui-config, button, input, navigation, use-scroll-state, use-controllable-state, motion, tones

Props:
- `title?: ReactNode` = "": The page title: large under the bar (the page's <h1>), compact in the bar once it scrolls away. Wraps to two lines when long; the compact copy truncates.
- `subtitle?: ReactNode` = "": A muted line under the large title ("23 necitite").
- `compactTitle?: ReactNode`: A shorter title for the bar. Default: the title.
- `backLabel?: string` = "": The back button's text, usually the previous page ("Settings"). The button renders when backHref or onBack is set; without a label it is a chevron named by backAriaLabel.
- `backAriaLabel?: string` = "Back": The back button's accessible name when it shows only the chevron.
- `backHref?: string` = "": Makes the back button a link through NavLink (the app's router link).
- `onBack?: () => void`: Runs when the back button is pressed (with backHref, before the navigation).
- `actions?: ReactNode`: Trailing buttons in the bar: <Button variant="ghost" size="icon" radius="full" aria-label="…" /> for icons, variant="ghost" size="sm" for text.
- `mode?: "collapse" | "large" | "compact"` = "collapse": collapse: the large title scrolls away and hands over to the bar. large: the title stays pinned at full size and never collapses. compact: only the bar, with the title always in it (detail pages).
- `titleSize?: "md" | "lg"` = "lg": The large title at 28px (md) or 34px (lg, iOS).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The tint of the back and cancel buttons and the search field's focus ring and caret (iOS tints them). Neutral keeps the default ring.
- `color?: string` = "": Any CSS color for the back and cancel buttons and the search focus ring and caret. Replaces the tone.
- `background?: "blur" | "solid" | "transparent"` = "blur": The bar's surface once content is under it: frosted glass, the solid page color, or none. The bar is transparent over the large title in every mode. Set [--bar-bg:var(--surface)] when the page is not bg-background.
- `border?: "scrolled" | "always" | "never"` = "scrolled": The hairline under the bar: fades in with the surface, always visible, or never.
- `search?: boolean` = false: A search field under the title. Focusing it scrolls it right under the bar and shows Cancel; Escape or Cancel clears, blurs and scrolls back to the top. Keep the results at least a screen tall while searching (min-h-full) so the field can stay under the bar.
- `searchValue?: string`: The query, controlled. Cancel calls onSearchChange("").
- `defaultSearchValue?: string` = "": The first query while uncontrolled.
- `onSearchChange?: (value: string) => void`: Every change of the query, typing, clearing and Cancel.
- `onSearchingChange?: (searching: boolean) => void`: True while the search is active (focused or holding a query), so the page can swap to results.
- `searchPlaceholder?: string` = "Search": The field's placeholder and accessible name.
- `cancelLabel?: string` = "Cancel": The text of the button that ends the search.
- `searchInputProps?: Partial<InputProps>`: Anything else for the search Input: name, maxLength, loading, a ref, extra handlers.
- `stretch?: boolean` = true: The large title grows up to 8% from its top corner while you pull past the top (iOS overscroll, Safari only). Off under reduced motion.
- `snap?: boolean` = true: A scroll that comes to rest halfway through the handover settles to fully expanded or fully collapsed, so the title never stays half under the bar (iOS). A page too short to collapse settles back to expanded.
- `safeArea?: boolean` = true: Pads env(safe-area-inset-top) above the bar so it clears the notch in a standalone PWA. It is 0 in desktop browsers.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls. Default: the nearest ScrollContainerProvider, else the window.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for backHref on this header only. Usually set once for the app with LinkProvider.
- `classNames?: Partial<Record<"bar" | "surface" | "hairline" | "row" | "leading" | "back" | "compactTitle" | "actions" | "large" | "title" | "subtitle" | "search" | "input" | "cancel", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. The root is display: contents (so the bar sticks to the whole page), except in mode="large" where it is the sticky block. The root carries data-collapsed and data-searching for group- styling.

```tsx
"use client"

import { useState } from "react"
import { SquarePen } from "lucide-react"
import { Button } from "@/components/ui/button"
import { LargeTitleHeader } from "@/components/ui/large-title-header"

const conversations = [
  { id: "1", name: "Daniel Reed", message: "I sent proposal #Q-2026-118." },
  { id: "2", name: "Sophia Lee", message: "Invoice #2026-0412 was paid." },
]

export function MessagesPage() {
  const [query, setQuery] = useState("")
  const results = conversations.filter((c) => c.name.toLowerCase().includes(query.toLowerCase()))

  return (
    <>
      <LargeTitleHeader
        title="Messages"
        subtitle="3 unread"
        backLabel="Settings"
        backHref="/settings"
        search
        searchValue={query}
        onSearchChange={setQuery}
        actions={
          <Button variant="ghost" size="icon" radius="full" aria-label="New message">
            <SquarePen />
          </Button>
        }
      />
      <ul className="min-h-dvh">
        {results.map((c) => (
          <li key={c.id} className="px-4 py-3">
            <p className="font-medium">{c.name}</p>
            <p className="text-sm text-muted-foreground">{c.message}</p>
          </li>
        ))}
      </ul>
    </>
  )
}
```

Docs: https://wingo-ui.com/components/large-title-header (Markdown: https://wingo-ui.com/components/large-title-header.md)

#### Notification Banner (`notification-banner`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add notification-banner`

iOS-style banners for incoming messages, orders and reminders that drop from the top, one at a time, with a queue and an expanded view.

Mount the host once and call notify() from anywhere: a banner drops in from the top edge with a soft spring (the phone ticks once if the page has seen a tap) and leaves on its own after the duration. It shows the app icon, name and time ("acum", "acum 2 min."), the sender's photo or an icon tile, a one-line title and two lines of text. Tap or click it to open (onPress runs and the banner goes). Swipe it up with a finger, or drag it up with the mouse, to throw it away; a short drag springs back. Pull it down and, past 40px of rubber-banded pull, the grabber arms, the phone ticks and the card grows to the full text and its actions (44px buttons on touch); with a mouse, the chevron under the text does the same. The × appears on hover and on keyboard focus (touch uses the swipe). Timers pause while you hover, hold, focus or expand a banner and while the tab is hidden. More banners wait in a queue: the next one peeks out under the card with a "+2" chip and drops in after the current one leaves; a banner sent again with the same id updates in place and cross-fades its text. Keyboard: the hotkey (Alt+N, ⌥N on a Mac) focuses the banner without stealing focus on arrival; Enter opens it, ArrowDown expands and ArrowUp collapses, Tab reaches the actions, the chevron and the ×, and Escape dismisses it and returns focus to where you were. Each new banner is read once by screen readers. Below a 576px wide host banners span the top with 8px gutters under the notch; wider, they are a 380px card at the top end.

npm: motion, lucide-react
Wingo UI dependencies: avatar, button, use-controllable-state, relative-time, use-locale, use-shortcut, haptics, motion, tones, ui-config

Props:
- `position?: "top-center" | "top-right" | "top-left"` = "top-right": Where the card sits once the host is at least 576px wide (a container query, so a phone frame on a desktop still gets the phone layout). Narrower, banners always span the top with 8px gutters.
- `strategy?: "fixed" | "absolute"` = "fixed": fixed pins the host to the viewport (the app default). absolute places it inside a relative container: a phone frame, an embedded panel.
- `width?: number` = 380: Card width in px in the wide layout. Phones always use the full width minus the gutters.
- `offset?: number` = 8: px below the top safe area. In the wide layout it is also the distance from the side.
- `safeArea?: boolean` = true: Pads env(safe-area-inset-top) so banners drop in under the notch or the Dynamic Island. It is 0 in desktop browsers and iframes.
- `variant?: "glass" | "solid"` = "glass": glass: a translucent popover with a strong backdrop blur, like iOS (solid where backdrop-filter is missing). solid: the plain popover surface.
- `radius?: "sm" | "md" | "lg"` = "lg": Card corners: sm 12px, md 16px, lg 24px (iOS). The action buttons and the media tile follow.
- `showAppHeader?: boolean` = true: The row with the app icon, the app name and the time. Off, the time moves next to the title (a compact chat banner).
- `appName?: string` = "": The app name in the header of every banner (a banner's own appName wins). The app icon shows its first letter on the tone's fill; empty shows a bell.
- `appIcon?: ReactNode`: Replaces the letter tile in the header (a 20px logo). A banner's own appIcon wins.
- `duration?: number` = 5000: ms a banner stays before it leaves. The clock pauses while it is hovered, held, focused or expanded. A banner's own duration or sticky wins.
- `expandable?: boolean` = true: Pull down, the chevron, a tap on a banner without onPress, or ArrowDown show the full text and the actions. Off, the actions never show.
- `maxQueue?: number` = 5: How many banners may wait behind the one on screen. Past it the oldest queued banner is dropped (its onDismiss runs with "dropped").
- `haptics?: boolean` = true: A light tick when a banner arrives (only once the page has seen a tap) and a selection tick when it expands. Through lib/haptics.
- `hotkey?: string` = "alt+n": Moves focus to the banner on screen; Escape then dismisses it and returns focus. Empty turns it off.
- `pauseWhenPageIsHidden?: boolean` = true: Timers stop while the tab is in the background, so a banner sent then is still there when you come back.
- `hostId?: string` = "": Shows only banners sent with notify({ hostId }). Several independent hosts on one page (a phone preview next to the app). A second host with the same id stays empty.
- `locale?: string` = "": Formats the time ("2 min ago", "il y a 2 min") through relative-time. Empty uses the UIProvider locale, then the page language.
- `labels?: Partial<NotificationBannerLabels>`: Every string: region "Notifications", dismiss "Dismiss", expand "Show more", collapse "Show less", queued(n) "{n} more", now "now", hint "Swipe up to dismiss, pull down for more" (read with each banner). DEFAULT_NOTIFICATION_BANNER_LABELS has the English set.
- `classNames?: Partial<Record<"item" | "header" | "body" | "media" | "title" | "message" | "actions" | "action" | "close" | "expand", string>>`: Extra classes for the parts of every banner.
- `className?: string`: Extra classes for the host section (the full-width layer at the top).

Parts:
- `notify` (function): Shows a banner and returns its id. Works from anywhere (handlers, fetch helpers, outside React) and before the host mounts; ignored on the server. Options: { id?, hostId?, title, message?, icon?, avatar?: { src?, name }, appName?, appIcon?, time? (default now), tone?, color?, onPress?, actions?: { label, onSelect, tone?: "neutral" | "danger" }[], duration?, sticky?, defaultExpanded?, onDismiss?(reason) }. The same id updates the banner in place. Signature: (options: NotificationBannerOptions) => string. notify.update (id: string, options: Partial<NotificationBannerOptions>) => boolean: Changes a shown or queued banner in place (upload 2/3, a new count) and restarts its clock. false when the id is gone. notify.dismiss (id?: string) => void: Removes one banner, or every banner (shown and queued) without an id. onDismiss runs with "api".
- `useNotificationBanners` (hook): The banner on screen and the ones waiting, for a counter or a "clear all" button. Signature: (hostId?: string) => { current: NotificationBannerRecord | null; queue: NotificationBannerRecord[] }.
- `NotificationBannerCard` (component): One banner as a still surface, without the store, timers or gestures: the same options plus variant, radius, showAppHeader, expanded / defaultExpanded / onExpandedChange, onClose, queued, locale, labels and classNames. For previews and settings screens. Props: NotificationBannerCardProps.

```tsx
import { useEffect, type ReactNode } from "react"
import { ShoppingCart } from "lucide-react"
import { NotificationBanner, notify } from "@/components/ui/notification-banner"

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

export function CrmShell({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <NotificationBanner
        appName="Northwind CRM"
        labels={{ queued: (n) => `+${n} waiting` }}
      />
    </>
  )
}

export function useNewOrders(orders: { id: number; total: number; locker: string }[], openOrder: (id: number) => void) {
  useEffect(() => {
    const order = orders.at(-1)
    if (!order) return
    notify({
      id: `order-${order.id}`,
      title: "New order",
      message: `Order #${order.id} · ${usd.format(order.total)} · ${order.locker}`,
      icon: <ShoppingCart />,
      tone: "success",
      onPress: () => openOrder(order.id),
      actions: [{ label: "View order", onSelect: () => openOrder(order.id) }],
    })
  }, [orders, openOrder])
}
```

Docs: https://wingo-ui.com/components/notification-banner (Markdown: https://wingo-ui.com/components/notification-banner.md)

#### Onboarding Carousel (`onboarding-carousel`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add onboarding-carousel`

First-run slides for an app or a PWA: swipe or tap Next, watch the dots, Skip any time, Get started on the last slide.

Swipe the slides with a finger, or drag them with a mouse or trackpad (embla's physics, vertical page scrolling is never blocked); the illustration trails the swipe at 0.6x and the text at 0.9x, and each slide's background color cross-fades into the next as you go; a finger swipe that lands on a new slide ticks once (haptics). Tap Next to advance; on the last slide it becomes Get started with a quick fade (the circle variant grows from a round arrow, ringed by the progress, into a pill). Skip in the top corner jumps to the last slide (or finishes right away with skipTo="complete") and fades out on the last slide; with showBack a back chevron slides in before Next from the second slide. Tap a dot or a story bar to jump there. With focus anywhere inside, Left and Right move one slide and Home / End jump to the ends; Enter or Space on Next advances, and focus is handed to Next when Skip or Back disappear. Each settled slide is announced ("Slide 2 of 4: ..."), off-screen slides are inert. Finishing fades the whole thing out before onComplete runs; with persistKey the finish (or a skip that ends it: skipTo="complete", closing the modal) is remembered and it never shows again. As a modal it opens from its trigger as a centered card on desktop and slides up as a full screen on a phone, focus lands on Next, and Escape or a click outside counts as Skip. Under reduced motion slides jump, there is no parallax, and everything else fades.

npm: @radix-ui/react-dialog, @radix-ui/react-visually-hidden, motion, lucide-react
Wingo UI dependencies: button, carousel, haptics, use-controllable-state, use-media-query, use-persisted-state, motion, tones, ui-config

Props:
- `slides: OnboardingSlide[]`: { id, title, description?, media?, image?, imageAlt?, background?, foreground? }. media is any node (a composed ui vignette, an svg); image is contained in the media area, or full-bleed behind the text with a bottom scrim when foreground is "light". background is any CSS color or token (var(--info-soft)) and cross-fades while swiping; without one the root's surface shows.
- `layout?: "fill" | "screen" | "card"` = "fill": fill takes the parent's height (a route of its own inside an app shell). screen is min-h-dvh with safe-area padding at the top and bottom. card is a 420 x 640px rounded surface, capped at 85dvh.
- `modal?: boolean` = false: Renders it in a Radix dialog with a focus trap and a hidden title: a full screen below 768px that slides up, a centered card from 768px. Closing (Escape, the overlay) counts as Skip. layout is ignored.
- `defaultOpen?: boolean` = false: Modal mode: open on mount. The playground turns modal on with it.
- `open?: boolean`: Modal mode, controlled. Pair with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Modal mode: the trigger opened it, or Skip, Escape, the overlay or the last button closed it.
- `trigger?: ReactNode`: Modal mode: the element that opens it, rendered asChild (a Button).
- `indicator?: "dots" | "bars" | "progress" | "counter"` = "dots": The carousel's indicators: dots whose active one stretches, story bars, one progress bar, or a 2 / 4 counter. Hidden with a single slide.
- `indicatorPosition?: "top" | "bottom"` = "bottom": bottom sits above Next (beside the circle). top puts it in the header next to Skip, the stories look.
- `nextVariant?: "button" | "circle"` = "button": button: a full-width Next that becomes Get started. circle: a round arrow ringed by the progress that grows into the Get started pill on the last slide.
- `size?: "sm" | "md" | "lg"` = "md": Title 24 / 28 / 32px, description 15 / 16 / 17px, indicators, and the Next button (40 / 48 / 48px, 44px on touch at sm; the circle 48 / 56 / 64px).
- `align?: "center" | "start"` = "center": Text alignment of the title and description.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Next / Get started button, the circle's ring and the active dot or bar.
- `color?: string` = "": Any CSS color. Replaces the tone; text on the button turns black or white by lightness.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the Next and Back buttons in the button variant (the circle is always round).
- `showSkip?: boolean` = true: The Skip button in the header. It fades out on the last slide.
- `showBack?: boolean` = false: A back chevron before Next from the second slide.
- `skipTo?: "last" | "complete"` = "last": Skip jumps to the last slide, or finishes right away (fade out, then onSkip and onComplete).
- `parallax?: boolean` = true: While swiping, the media moves at 0.6x the slide and the text at 0.9x. Off under reduced motion.
- `haptics?: boolean` = true: A "selection" tick through lib/haptics when a finger or pen swipe lands on a new slide. Never on a mouse drag, taps, keys or mount; silent on desktops.
- `persistKey?: string` = "": When set, a finish or a skip that ends the tour (skipTo="complete", closing the modal) is remembered in localStorage (use-persisted-state) and nothing renders afterwards; a modal stays closed unless its trigger opens it. The server renders the slides; a remembered finish fades them out after hydration (a modal never flashes). Clear it with writePersisted(key, null).
- `index?: number`: The current slide, controlled. A jump scrolls there (instantly under reduced motion); values past the end clamp.
- `defaultIndex?: number` = 0: The first slide shown, uncontrolled. The tour also returns here after it finishes.
- `onIndexChange?: (index: number) => void`: Every settled change: a swipe, Next, Back, Skip, a dot or a key.
- `onComplete?: () => void`: The last slide's button (and Skip with skipTo="complete"), after the fade out.
- `onSkip?: (index: number) => void`: Skip was pressed (or the modal was closed) on this slide.
- `labels?: Partial<OnboardingCarouselLabels>`: skip "Skip", next "Next", back "Back", done "Get started", region "Welcome" (the region label and the modal title fallback), slide(i, n) "Slide 2 of 4", goTo(i) "Go to slide 3". DEFAULT_ONBOARDING_CAROUSEL_LABELS is exported.
- `setApi?: (api: CarouselApi) => void`: The embla api, for custom controls.
- `classNames?: Partial<Record<"header" | "skip" | "slide" | "media" | "title" | "description" | "footer" | "indicator" | "back" | "next", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:#0f766e].

```tsx
"use client"

import { useRouter } from "next/navigation"
import { OnboardingCarousel, type OnboardingSlide } from "@/components/ui/onboarding-carousel"

const slides: OnboardingSlide[] = [
  {
    id: "clients",
    title: "Every client in one place",
    description: "Companies, contacts and balances, the same on your phone and at the office.",
    image: "/onboarding/clients.svg",
    background: "var(--info-soft)",
  },
  {
    id: "invoices",
    title: "Invoices in 30 seconds",
    description: "Issue the invoice from your phone and we email it to your client.",
    image: "/onboarding/invoices.svg",
    background: "var(--success-soft)",
  },
  {
    id: "offline",
    title: "Works offline too",
    description: "Everything syncs when you are back online.",
    image: "/onboarding/offline.svg",
  },
]

export default function Welcome() {
  const router = useRouter()
  return (
    <OnboardingCarousel
      layout="screen"
      slides={slides}
      persistKey="onboarding-v1"
      showBack
      labels={{ skip: "Skip", next: "Continue", back: "Back", done: "Get started", region: "Welcome" }}
      onComplete={() => router.replace("/home")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/onboarding-carousel (Markdown: https://wingo-ui.com/components/onboarding-carousel.md)

#### Picker Wheel (`picker-wheel`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add picker-wheel`

The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field.

Flick a column with a finger and it spins with the phone's own momentum, rows tilting away on a cylinder and fading toward the edges, then clicks into place on a row; each row that reaches the center ticks under the thumb where the phone can vibrate (Android, iOS 17.4+). The value changes once, when the wheel comes to rest, never per row passed; a wheel that lands on a disabled (sold out) row glides on to the nearest one that is not. With a mouse, scroll the wheel, click-drag it up or down and let go to keep it spinning with inertia, or click any visible row to bring it to the center. Each column is one Tab stop: ArrowUp / ArrowDown move a row, PageUp / PageDown five, Home / End jump to the ends, typing jumps to the next option that starts with the text ("19" then "199" on a year wheel), ArrowLeft / ArrowRight move to the neighbor column. Looping columns wrap around from the last row to the first. PickerWheelField shows the value in a form field: a tap opens a bottom sheet on phones with the wheels, Done on top and Cancel under it (Enter on a wheel works like Done; dragging the sheet away keeps the old value), a click or Enter / Space / Alt+ArrowDown opens a popover on desktop where the wheel applies live and Enter or Done closes it, Escape closes and returns focus to the field; the field is announced with its label and its current value. With reduced motion the rows stay flat and programmatic moves jump instead of gliding.

npm: @radix-ui/react-popover, motion, lucide-react
Wingo UI dependencies: button, drawer, field, use-controllable-state, use-locale, use-media-query, date-utils, haptics, motion, tones, ui-config

Props:
- `columns?: PickerWheelColumnDef[]`: The wheels, left to right: { id, options, label?, width?: "auto" | number, align?: "start" | "center" | "end", loop?, showLabel? }. label names the listbox and shows beside the center row ("h", "min"). Required unless options is set.
- `options?: PickerWheelOption[]`: Shortcut for a single column. Each option is { value, label, textValue?, disabled? }; textValue feeds type-to-jump and the field text when the label is not plain text.
- `value?: string[]`: One value per column, in column order (controlled). A value that is not an option shows the first enabled option and fires nothing until the user moves.
- `defaultValue?: string[]`: The starting values while uncontrolled; defaults to the first enabled option of each column.
- `onValueChange?: (value: string[], column: string) => void`: Fires once per settle with every column's value and the id of the column that moved, never per row passed.
- `size?: "sm" | "md" | "lg"` = "md": Row height 36 / 44 / 52px with 15 / 17 / 20px text. md matches the wheels of the time picker's sheet.
- `visibleRows?: number` = 5: How many rows show (odd, 3 to 9). The wheel is rowHeight x visibleRows tall: 220px at md with 5 rows.
- `perspective?: "ios" | "subtle" | "flat"` = "ios": How far rows tilt away from the center: 20 / 10 / 0 degrees per row, capped at 55. Opacity falls to 0.35 either way.
- `band?: boolean` = true: The rounded selection band behind the center row, shared by all columns.
- `fade?: boolean` = true: Fades the top and bottom rows out with a mask, like the iOS picker.
- `showColumnLabels?: boolean` = true: Shows each column's label right after its widest option, beside the center row ("2 h 30 min"). A column's own showLabel wins; date columns from useDateWheel turn it off.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": neutral: a light gray band and foreground text. Other tones tint the band and color the centered row.
- `color?: string` = "": Any CSS color; replaces the tone for the band and the centered row.
- `disabled?: boolean` = false: Dims the wheel, stops scrolling and removes the columns from the Tab order.
- `loop?: boolean` = false: Every column wraps around, so 59 is followed by 00 again. A column's own loop wins; lists shorter than half the window never loop.
- `haptics?: boolean` = true: A selection tick each time a new row reaches the center while a finger, a mouse drag or a wheel drives it; never for keys, clicks or outside value changes.
- `aria-label?: string` = "": The name of the group of wheels ("Date of birth"); each column is named by its own label.
- `labels?: Partial<PickerWheelLabels>`: Strings: empty "No options", and for the field done "Done", cancel "Cancel", placeholder "Select". Defaults in DEFAULT_PICKER_WHEEL_LABELS.
- `classNames?: Partial<Record<"band" | "column" | "option" | "columnLabel", string>>`: Extra classes for the band, each column listbox, each option row and the column labels.
- `className?: string`: Extra classes for the root, merged last (width, margins, tone var overrides).

Parts:
- `PickerWheelField` (component): The wheel as a form field: everything PickerWheel takes plus label, description, error, required, invalid, name (a hidden input with the values joined by formatValue or ","), placeholder, variant ("soft" | "outline" | "ghost"), radius, responsive (a bottom sheet below 768px, default true), open / defaultOpen / onOpenChange, sheetTitle, container and formatValue(value) for the text in the box. The sheet commits on Done (or Enter on a wheel); the desktop popover applies live and closes on Enter or Done. Either way the wheel gets focus on open and the field gets it back on close. Props: PickerWheelFieldProps.
- `PickerWheelColumn` (component): One wheel on its own, with the time picker wheel's shape: options, value / defaultValue / onValueChange(value: string), label, showLabel, align, loop and the appearance props (size, visibleRows, perspective, band, fade, tone, color, haptics, disabled). Props: PickerWheelColumnProps.
- `useDateWheel` (hook): Day, month and year columns in the locale's order (ro-RO day / month / year, en-US month / day / year), month names in the locale, days that follow the month (29.02 only in leap years; a day that no longer exists becomes the last one) and years between min and max (ISO dates, default 1900-01-01 to 2100-12-31). Values are local ISO dates ("2026-09-24"). Spread it: <PickerWheel {...useDateWheel({ defaultValue: "1990-05-17", locale: "ro-RO" })} />; date is the current ISO date (not spread). Signature: (options: { value?, defaultValue?, onValueChange?(date: string), locale?, min?, max?, order?, labels? }) => { columns, value, onValueChange, date }.
- `pickerRange` (function): Numbered options either way: pickerRange(0, 23, { pad: 2 }) gives "00" to "23"; pickerRange(0, 55, { step: 5, pad: 2 }) gives minutes every 5; format(n) makes the label, disabled(n) blocks a number. Signature: (start: number, end: number, options?: { step?, pad?, format?, disabled? }) => PickerWheelOption[].
- `DEFAULT_PICKER_WHEEL_LABELS` (constant): The English defaults of labels, for translating once. Type: PickerWheelLabels.

```tsx
import { useState } from "react"
import { PickerWheel, PickerWheelField, pickerRange, useDateWheel } from "@/components/ui/picker-wheel"

const hours = pickerRange(8, 19, { pad: 2 })
const minutes = pickerRange(0, 55, { step: 5, pad: 2 })

export function Appointment() {
  const [time, setTime] = useState(["10", "30"])
  const birthday = useDateWheel({ defaultValue: "1990-05-17", locale: "en-US" })

  return (
    <div className="flex flex-col gap-6">
      <PickerWheel aria-label="Date of birth" {...birthday} />
      <PickerWheel
        aria-label="Appointment time"
        loop
        value={time}
        onValueChange={(value) => setTime(value)}
        columns={[
          { id: "hour", label: "h", options: hours },
          { id: "minute", label: "min", options: minutes },
        ]}
      />
      <PickerWheelField
        label="Model year"
        name="year"
        placeholder="Choose the year"
        options={pickerRange(2026, 1990)}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/picker-wheel (Markdown: https://wingo-ui.com/components/picker-wheel.md)

#### Pull To Refresh (`pull-to-refresh`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add pull-to-refresh`

Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick.

At the top of the list, drag down with a finger: the content follows with growing resistance and the indicator appears in the gap (an arrow, the iOS spokes drawing one by one, or a Material circle whose ring fills). Past the threshold the arrow turns, the spokes complete or the ring saturates, and the phone ticks once. Let go there and it spins while onRefresh runs (500ms at least), shows a check (or an alert when the promise rejects) and the content glides back; let go earlier and it springs back. Swiping sideways or up is left to the page, and pulls never start in inputs, [data-no-pull], a sideways scroller or a nested list that is not at its own top. On a trackpad or mouse wheel, scroll up once more at the very top to pull; stop for a moment to release. With pullWithMouse a mouse drag pulls too. There is no gesture on the keyboard: bind shortcut, or call setApi().refresh() from a refresh button. Screen readers hear Refreshing, then Updated or the error.

npm: motion, lucide-react
Wingo UI dependencies: spinner, use-scroll-state, use-shortcut, haptics, motion, tones, ui-config

Props:
- `children?: ReactNode`: The list or feed that gets pulled.
- `onRefresh?: (() => void | Promise<unknown>)`: The reload. The indicator spins until the returned promise settles, and for 500ms at least so it never flashes. A rejection shows the error state.
- `variant?: "arrow" | "ios" | "material"` = "arrow": arrow: an arrow that turns at the threshold and becomes a spinner; the content moves down. ios: 12 spokes that draw one by one as you pull, then spin like UIRefreshControl; the content moves down. material: a floating circle whose ring fills while you pull, then spins; the content stays put.
- `size?: "sm" | "md" | "lg"` = "md": Indicator 20 / 24 / 28px; the material circle 36 / 40 / 44px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The indicator color. neutral is the quiet muted gray (the material ring is black / white); the other tones use their tone text color and fill.
- `color?: string` = "": Any CSS color for the indicator. Replaces the tone. Leave empty to use the tone.
- `showLabel?: boolean` = false: Text under the indicator that follows the state: pull, release, refreshing, done or error.
- `labels?: Partial<PullToRefreshLabels>`: The strings shown with showLabel and announced to screen readers: pull "Pull to refresh", release "Release to refresh", refreshing "Refreshing…", done "Updated", error "Couldn't refresh". The English defaults are exported as DEFAULT_PULL_TO_REFRESH_LABELS.
- `refreshing?: boolean` = false: Shows the refreshing state for a reload the app started itself (the content parks at the threshold with a spinner). OR-ed with the internal state, so false never blocks a pull.
- `disabled?: boolean` = false: No pulling (offline, editing, a filter is active). Turning it on mid-pull springs back without refreshing.
- `doneDuration?: number` = 600: Milliseconds the check (or the alert) stays before the content glides back. 0 skips the done state.
- `threshold?: number` = 72: Pixels of resisted pull that arm the refresh; also where the content rests while it refreshes.
- `maxPull?: number` = 128: The furthest the content moves, however far the finger goes.
- `indicatorOffset?: number` = 0: Pixels from the top of the root to the indicator's resting line, for a sticky or translucent bar over the list.
- `scroll?: "parent" | "self"` = "parent": parent: watches scrollTarget, else the provided scroll container (ScrollContainerProvider), else the nearest scrolling ancestor, else the window. self: the root is the scroll container (h-full overflow-y-auto overscroll-y-contain).
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: The scroller to watch when scroll is parent. null forces the window.
- `wheel?: boolean` = true: A trackpad or mouse wheel scrolling up at the very top pulls too, the desktop path. Momentum that carries a scroll up to the top never pulls.
- `pullWithMouse?: boolean` = false: A mouse drag at the top pulls, for kiosks and touch emulation. Off by default so it never fights text selection and clicks.
- `haptics?: boolean` = true: A "medium" tick when the pull arms and an "error" buzz when a pulled refresh fails, through lib/haptics.
- `shortcut?: string` = "": A key that refreshes, in mod+k notation ("mod+r", "shift+r"). None by default.
- `setApi?: (api: PullToRefreshApi) => void`: Receives { refresh(): Promise<void> }, which runs the same flow as a pull (indicator, promise, done). Calls during a running refresh return the running promise.
- `classNames?: Partial<Record<"indicator" | "icon" | "spinner" | "label" | "content", string>>`: Extra classes for the indicator row, the arrow / check / alert icon, the spinner, the label and the content wrapper.
- `className?: string`: Extra classes for the root, merged last.

```tsx
"use client"

import { useState } from "react"
import { RotateCw } from "lucide-react"
import { Button } from "@/components/ui/button"
import { PullToRefresh, type PullToRefreshApi } from "@/components/ui/pull-to-refresh"

type Message = { id: string; from: string; text: string }

export function Inbox({ load }: { load: () => Promise<Message[]> }) {
  const [messages, setMessages] = useState<Message[]>([])
  const [api, setApi] = useState<PullToRefreshApi>()

  return (
    <div className="flex h-dvh flex-col">
      <header className="flex h-14 items-center justify-between px-4">
        <h1 className="text-lg font-semibold">Inbox</h1>
        <Button variant="ghost" size="icon" radius="full" aria-label="Reload" onClick={() => api?.refresh()}>
          <RotateCw />
        </Button>
      </header>
      <PullToRefresh
        scroll="self"
        className="min-h-0 flex-1"
        setApi={setApi}
        onRefresh={async () => setMessages(await load())}
        labels={{ pull: "Pull to check for mail", release: "Let go to check", refreshing: "Checking for mail…", done: "Up to date", error: "Could not check for mail" }}
      >
        <ul className="divide-y divide-foreground/10">
          {messages.map((m) => (
            <li key={m.id} className="px-4 py-3">
              <p className="font-medium">{m.from}</p>
              <p className="text-sm text-muted-foreground">{m.text}</p>
            </li>
          ))}
        </ul>
      </PullToRefresh>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/pull-to-refresh (Markdown: https://wingo-ui.com/components/pull-to-refresh.md)

#### Slide To Confirm (`slide-to-confirm`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add slide-to-confirm`

A track whose thumb you slide to the end to confirm an irreversible action, like a payment or a delivery, with loading and success states.

Drag the thumb along the track with a finger or the mouse: the fill grows behind it and the label fades as the thumb passes. Past the threshold the thumb grows a little, the fill deepens and the phone ticks; let go there (or flick hard past 60%) and it glides to the end and confirms, let go earlier and it springs home. A promise from onConfirm shows a spinner on the parked thumb, then a bouncing check with the fill covering the track, or a short shake, the thumb back home and the error text for 2 seconds. Tap the track (or click the thumb) and the thumb hops forward and the label lights up, to teach the gesture. Vertical swipes that start on the track still scroll the page. Keyboard: Tab to the thumb, Enter, Space or End glide it to the end and confirm, Left / Right preview the travel in 10% steps and it springs back after a moment, Home returns it. With a screen reader, activating the thumb (a double tap in VoiceOver or TalkBack) confirms, and loading, success and error are announced. In RTL the thumb starts on the right.

npm: lucide-react, motion
Wingo UI dependencies: spinner, use-controllable-state, haptics, motion, tones, ui-config

Props:
- `label?: string` = "Slide to confirm": The track text and the thumb's accessible name. Keep it short, it truncates on narrow tracks.
- `variant?: "soft" | "solid" | "outline"` = "soft": soft: a tinted track with a toned thumb. solid: the track in the tone fill with a contrasting thumb, for the one hero action. outline: a hairline track in the tone border.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Thumb and fill color from the design tokens. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color. Replaces the tone; icons on the fill turn black or white by lightness.
- `size?: "sm" | "md" | "lg"` = "md": Track height 48 / 56 / 64px, thumb 40 / 48 / 56px, label 14 / 15 / 16px. Every size is a comfortable touch target.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Track radius 0 / 10 / 14 / 18px or a pill; the thumb and fill take the track radius minus their 4px inset.
- `shimmer?: boolean` = true: A highlight that sweeps across the label while idle. Off when disabled, under reduced motion and off screen.
- `disabled?: boolean` = false: Dims the control and blocks dragging and keys. The thumb stays focusable with aria-disabled, so a screen reader still finds it.
- `defaultStatus?: "idle" | "loading" | "success" | "error"` = "idle": Starting status while uncontrolled. success parks the thumb at the end without calling onConfirm.
- `status?: "idle" | "loading" | "success" | "error"`: Controlled status for server-driven flows. Set it to "idle" to reset; set "success" and the thumb moves to the end without calling onConfirm.
- `onStatusChange?: (status: SlideToConfirmStatus) => void`: Fires with every status change: loading when a promise starts, success / error when it settles, idle on reset.
- `onConfirm?: () => (void | Promise<unknown>)`: Runs when the thumb reaches the end or on Enter. Return a promise to show loading, then success when it resolves or error when it rejects (a synchronous throw counts as a rejection). Never runs twice for one slide.
- `threshold?: number` = 0.9: Share of the travel past which a release confirms. Deliberately harder than other swipes: a flick counts only past 0.6. 1 means the very end.
- `resetAfter?: number` = 0: Milliseconds after success before it slides back to idle. 0 keeps it confirmed until you reset the status.
- `haptics?: boolean` = true: A medium tick when the thumb arms, success / error patterns on the outcome (through lib/haptics, phones only).
- `icon?: ReactNode`: The thumb icon, a ChevronsRight by default. Unsized svgs follow the size (18 / 20 / 22px); mirrored in RTL.
- `successIcon?: ReactNode`: Shown on the thumb after success, a Check by default; pops in on a bouncy spring.
- `labels?: Partial<SlideToConfirmLabels>`: Status texts: loading "Processing…", success "Confirmed", error "Something went wrong. Try again.", hint "Drag to the end, or press Enter" (the thumb's screen reader description). Defaults in DEFAULT_SLIDE_TO_CONFIRM_LABELS.
- `classNames?: Partial<Record<"track" | "fill" | "label" | "thumb" | "icon" | "spinner" | "check", string>>`: Extra classes for the inner parts.
- `className?: string`: Classes for the root, merged last. It is full width by default; cap it here, e.g. max-w-sm.

```tsx
import { SlideToConfirm } from "@/components/ui/slide-to-confirm"

export function ConfirmDelivery({ orderId }: { orderId: string }) {
  return (
    <SlideToConfirm
      label="Slide to confirm delivery"
      labels={{ loading: "Confirming…", success: "Delivery confirmed", error: "Could not confirm. Try again." }}
      onConfirm={() => fetch(`/api/orders/${orderId}/delivered`, { method: "POST" }).then((res) => {
        if (!res.ok) throw new Error("failed")
      })}
    />
  )
}
```

Docs: https://wingo-ui.com/components/slide-to-confirm (Markdown: https://wingo-ui.com/components/slide-to-confirm.md)

#### Sticky CTA Bar (`sticky-cta-bar`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add sticky-cta-bar`

The bottom action bar of product, listing and checkout pages on phones: the price on one side, the main action on the other.

The bar sits at the bottom edge, above a bottom tab bar and the home indicator, with the price (an old price struck through, a muted caption) on the left and the main button on the right, plus an optional icon button such as a heart. With showOn="anchor" it stays out of the way while the page's own buy button is on screen and glides up on a smooth spring once you scroll past it (or while you have not reached it yet), then drops away quickly when the button comes back; showOn="scroll" does the same after a scroll distance. With hideOnScroll it follows your finger down and out while you scroll down and comes back as soon as you scroll up. Tap the button: a promise from onAction shows its spinner without changing the width. When the price changes the new amount fades in. When the on-screen keyboard opens (a coupon field) the bar slides away by default, or rides on top of the keyboard with keyboard="lift". Everything is a normal button, reached with Tab and pressed with Enter or Space; while hidden the bar is inert so Tab skips it, and while keyboard focus is inside it never hides. Under reduced motion it fades instead of sliding.

npm: motion
Wingo UI dependencies: button, number-format, use-locale, use-scroll-state, use-keyboard-inset, motion, tones, ui-config

Props:
- `price?: number` = 0: The amount, formatted with locale and currency ("$489,000", "$1,284.90"). 0 hides the price row; pass summary for "Free" or anything else.
- `currency?: string` = "USD": ISO 4217 code, shown with the narrow symbol ($, €, £). Empty shows the plain number.
- `locale?: string` = "": Intl locale for the price, like en-US. Empty uses the UIProvider locale, then the page's language. The demo uses en-US.
- `priceSuffix?: string` = "": Smaller muted text right after the price: "/mo", "/night".
- `compareAtPrice?: number` = 0: The old price, struck through at the start of the line under the price and read as "Was …" by screen readers. Shown only when it is above price.
- `badge?: ReactNode`: A small badge after the price, like <Badge tone="danger" variant="solid" size="sm">−25%</Badge>. It gives way to the price when a very narrow phone has no room for both.
- `caption?: string` = "": One muted line under the price, like "Tax included · Free shipping". Hidden on phones under 360px wide.
- `actionLabel?: string` = "Continue": The primary button's text. On a narrow phone a long label truncates before the price is ever cut.
- `summary?: ReactNode`: Replaces the whole price block: "2 tickets · Madison Square Garden", a seller, a sale badge.
- `actionIcon?: ReactNode`: An icon after the primary button's label, like an arrow.
- `onAction?: (() => void | Promise<unknown>)`: Runs on the primary button. Return a promise and the button shows its spinner (same width, aria-busy) until it settles.
- `actionProps?: Omit<ButtonProps, "children" | "onClick" | "size" | "tone" | "radius" | "color">`: Anything else for the primary Button: leftIcon, type="submit" with form, aria-*.
- `action?: ReactNode`: Replaces the primary button entirely, for example a <Button asChild> link to the checkout.
- `secondaryAction?: ReactNode`: An icon button before the primary: <Button variant="soft" size="icon" radius="full" aria-label="Save">. Match its size to the bar (icon-sm / icon / icon-lg).
- `variant?: "bar" | "floating"` = "bar": bar: an edge-to-edge glass bar with a hairline on top. floating: an inset rounded card with a floating shadow, 12px above the safe area.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary button's color. Brand orange suits the one checkout action.
- `color?: string` = "": Any CSS color for the primary button. Replaces the tone; the text turns black or white by lightness.
- `size?: "sm" | "md" | "lg"` = "md": Button size 32 / 40 / 48px (44px hit areas on touch), bar content height 56 / 64 / 72px, price 16 / 17 / 19px.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The buttons' corner shape, scaled with the size like the button's.
- `loading?: boolean` = false: The primary button's spinner. It keeps its width and focus and ignores presses.
- `disabled?: boolean` = false: Dims and blocks the primary action.
- `showOn?: "always" | "scroll" | "anchor"` = "always": always: on screen from the start. scroll: after threshold px of scrolling. anchor: while anchorRef (the page's own buy button) is out of view, not reached yet or scrolled past. Anything but always renders hidden on the server, so it never flashes.
- `threshold?: number` = 200: Scroll distance in px before the bar appears with showOn="scroll".
- `anchorRef?: RefObject<HTMLElement | null>`: The in-page buy button for showOn="anchor", watched with an IntersectionObserver on the scroll container. Without it the bar shows always (with a dev warning).
- `hideOnScroll?: boolean` = false: Slides away with the finger while scrolling down and comes back when scrolling up and at the end of the page.
- `keyboard?: "hide" | "lift" | "none"` = "hide": While the on-screen keyboard is open: hide keeps a coupon field uncovered, lift rides on top of the keyboard (chat-like flows), none does nothing.
- `position?: "fixed" | "sticky" | "absolute"` = "fixed": fixed: to the viewport, above a bottom tab bar (bottom: var(--bottom-bar-offset)). sticky: the last child of a scroll container (the demo's phone frame). absolute: inside a relative box.
- `hideFrom?: "none" | "md" | "lg"` = "none": Hides the bar with CSS from this breakpoint up, where the page shows its own CTA column.
- `safeArea?: boolean` = true: Pads the home indicator area, minus what a bottom tab bar below already covers (no double padding), and the side insets of a landscape phone. env() is 0 on desktops.
- `scrollTarget?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What scrolls, for showOn, hideOnScroll and the anchor. Default: the nearest ScrollContainerProvider, else the window.
- `labels?: Partial<StickyCtaBarLabels>`: Screen reader strings: region (the landmark name, "Purchase"), compare (read before the old price, "Was"). DEFAULT_STICKY_CTA_BAR_LABELS holds the English defaults.
- `classNames?: Partial<Record<"inner" | "summary" | "price" | "suffix" | "compare" | "badge" | "caption" | "actions" | "secondary" | "primary", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. The bar writes --cta-bar-offset (its visible height in px, 0 while hidden) on <html> when fixed, else on its parent, so floating buttons can sit above it.

```tsx
import { Heart } from "lucide-react"
import { Button } from "@/components/ui/button"
import { StickyCtaBar } from "@/components/ui/sticky-cta-bar"

export function ListingBuyBar({ onBuy }: { onBuy: () => Promise<void> }) {
  return (
    <StickyCtaBar
      price={349}
      compareAtPrice={449}
      caption="Tax included · Free shipping"
      locale="en-US"
      actionLabel="Add to cart"
      tone="brand"
      onAction={onBuy}
      secondaryAction={
        <Button variant="soft" size="icon" radius="full" aria-label="Save">
          <Heart />
        </Button>
      }
      labels={{ region: "Purchase", compare: "Old price" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/sticky-cta-bar (Markdown: https://wingo-ui.com/components/sticky-cta-bar.md)

#### Swipe Deck (`swipe-deck`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add swipe-deck`

A stack of cards you decide on one at a time: swipe right to accept, left to reject, optionally up for later, with undo.

Drag the top card with a finger or the mouse: it follows and tilts, a stamp (Accept, Reject, Later) fades in on the side you are heading for, the matching round button tints and grows, and the cards behind rise into place. Past a quarter of the card (or with a quick flick) the stamp settles at full strength and the phone ticks; let go there and the card flies off at the speed of your throw and the next one is on top, let go earlier and it springs back. With only left and right allowed, vertical swipes on the card still scroll the page and the card only gives a little up and down. The round buttons under the deck throw the card the same way; the small undo button (a circular arrow) brings the last card back, flying in from the side it left. A save that fails (a rejected onSwipe promise) brings the card back with an error pill. Keyboard: Tab to the card, Left / Right (and Up when allowed) decide with the same animation, Backspace or Cmd/Ctrl+Z undo, and focus follows to the next card and to the empty state at the end. Buttons and links inside a card stay clickable and never start a drag. Every decision is announced to screen readers. With reduced motion the card does not tilt and leaves with a short fade and slide.

npm: lucide-react, motion
Wingo UI dependencies: button, empty-state, use-controllable-state, haptics, motion, tones, ui-config

Props:
- `items: T[]`: The cards, each with a stable id. Appending while in use fills the stack; removing clamps the index.
- `renderCard: (item: T, state: { index: number; isTop: boolean }) => ReactNode`: The card's content. The deck draws the card surface (radius, shadow, overflow) around it.
- `getItemLabel?: (item: T) => string` = "item.id": The card's accessible name and the text announced after a decision.
- `directions?: ("left" | "right" | "up")[]` = "left, right": The allowed directions. Adding "up" gives a third choice (Later), a stamp at the bottom of the card and a smaller middle button; without "right" its button is hidden.
- `visibleCards?: number` = 3: Cards drawn in the stack, 1 to 4. The rest mount when they reach it; fewer items draw fewer cards.
- `stack?: "stack" | "fan" | "none"` = "stack": stack: the cards behind peek out below, scaled to 0.95 / 0.9. fan: they lean ±3° alternately. none: only the top card shows; the next fades in as it leaves.
- `rotation?: number` = 12: Degrees of tilt at a full-width drag, around the bottom of the card. 0 keeps it upright.
- `leftTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "danger": The reject stamp and button. Stamps always carry text and an icon, so color is never the only cue.
- `rightTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": The accept stamp and button. Brand orange suits a like on a marketplace.
- `upTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "info": The later stamp and button, when "up" is allowed.
- `radius?: "md" | "lg"` = "lg": Card radius: md 16px (rounded-2xl), lg 24px (rounded-3xl).
- `showActions?: boolean` = true: The round 56px buttons under the deck: the mouse, keyboard and screen reader path to every decision.
- `showUndo?: boolean` = true: The undo button next to them. Off also turns off Backspace and Cmd/Ctrl+Z.
- `stamps?: boolean` = true: The labels that fade in on the card while it is dragged and lock in when a direction is armed.
- `haptics?: boolean` = true: A medium tick when a drag arms a direction, light on commit, selection on undo, error when onSwipe rejects. Through lib/haptics, silent on desktops.
- `disabled?: boolean` = false: Dims the deck and blocks drags, keys and buttons.
- `index?: number`: How many cards are decided, to control the deck from outside (set 0 to start over).
- `defaultIndex?: number` = 0: The starting index while uncontrolled: how many cards count as decided on mount. At the item count the deck opens on its empty state.
- `onIndexChange?: (index: number) => void`: Fires after every decision, undo and failed save.
- `onSwipe?: (item: T, direction: SwipeDeckDirection) => (void | Promise<unknown>)`: Runs once the card has left. Return a promise to save: the deck waits for it before the next decision, and a rejection brings the card back with labels.error.
- `onUndo?: (item: T, direction: SwipeDeckDirection) => void`: Runs when a card comes back through the undo button or a key.
- `onEmpty?: () => void`: Runs after the last card is decided (after its save resolves, when onSwipe returns a promise).
- `emptyState?: ReactNode`: Shown in the deck's place after the last card. Defaults to <EmptyState size="sm" title={labels.empty} /> with a check; its first button gets focus.
- `icons?: Partial<Record<"left" | "right" | "up", ReactNode>>`: Icons for the stamps and buttons per direction. Defaults: X, Check, Clock.
- `setApi?: (api: SwipeDeckApi) => void`: Hands out { swipe(direction), undo(), index } to drive the deck from your own controls. swipe animates like a button press.
- `labels?: Partial<SwipeDeckLabels>`: Every string: left "Reject", right "Accept", up "Later", undo "Undo", empty "All done", region "Cards", instructions (read with the top card; the English default names Up when it is allowed and drops Backspace without undo), decided(label, direction, remaining) for the announcement, error "Couldn't save. Try again.". English defaults in DEFAULT_SWIPE_DECK_LABELS.
- `classNames?: Partial<Record<"stack" | "card" | "stamp" | "actions" | "action" | "undo" | "empty" | "error", string>>`: Extra classes for the inner parts. The stack is aspect-[3/4]; override it here, e.g. { stack: "aspect-[4/5]" }.
- `className?: string`: Extra classes for the root, merged last. The deck is capped at max-w-sm and centered. A thrown card flies past the deck's edges, so give a page that can scroll sideways an overflow-x-clip wrapper.

```tsx
import { useState } from "react"
import { SwipeDeck, type SwipeDeckDirection } from "@/components/ui/swipe-deck"

type Receipt = { id: string; vendor: string; amount: string; category: string }

const receipts: Receipt[] = [
  { id: "exp-2041", vendor: "Whole Foods Market", amount: "$214.50", category: "Hospitality" },
  { id: "exp-2042", vendor: "FedEx", amount: "$86.00", category: "Shipping" },
  { id: "exp-2044", vendor: "Hilton Boston", amount: "$412.00", category: "Lodging" },
]

export function ApproveExpenses({ save }: { save: (id: string, approved: boolean) => Promise<void> }) {
  const [approved, setApproved] = useState(0)
  return (
    <SwipeDeck
      items={receipts}
      getItemLabel={(r) => `${r.vendor}, ${r.amount}`}
      renderCard={(r) => (
        <div className="flex h-full flex-col gap-2 p-5">
          <span className="text-[15px] font-semibold">{r.vendor}</span>
          <span className="text-4xl font-bold tabular-nums">{r.amount}</span>
          <span className="text-sm text-muted-foreground">{r.category}</span>
        </div>
      )}
      onSwipe={(r, direction: SwipeDeckDirection) => {
        if (direction === "right") setApproved((n) => n + 1)
        return save(r.id, direction === "right")
      }}
      labels={{ left: "Reject", right: "Approve", undo: "Undo", empty: `Done: ${approved} approved` }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/swipe-deck (Markdown: https://wingo-ui.com/components/swipe-deck.md)

#### Swipeable Tabs (`swipeable-tabs`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add swipeable-tabs`

Tabs whose pages sit side by side and follow your thumb: swipe and the indicator tracks the finger, tap a tab and the pages slide.

Swipe the content sideways with a finger: the pages move with native momentum, one page per swipe, and the underline, pill or segmented thumb stretches between tabs in step with the pages; the label color flips half way and a light selection tick plays when the swipe settles on a new tab (Android, iOS 17.4+). Vertical scrolling inside a page never changes the tab, and a horizontal rail inside a page scrolls first. Tap a tab and the pages glide to it; tap the active tab again to scroll its page back to the top. On a trackpad, swipe horizontally with two fingers; with swipeWithMouse, drag the pages with the mouse (past a quarter of the width or a quick flick moves one page, a short drag springs back, and the click after a drag never reaches a row). With the keyboard, Tab reaches the selected tab, Left / Right move between tabs (mirrored in RTL, disabled tabs skipped, wrapping at the ends), Home / End jump, and in manual mode Enter or Space selects the focused tab; Tab again moves into the page, and when a swipe carries focus off screen it moves to the new tab instead of getting lost. When the tabs overflow, the row scrolls sideways with edge fades and keeps the active tab in view. Under reduced motion taps jump instead of sliding.

npm: motion
Wingo UI dependencies: badge, use-controllable-state, use-scroll-edges, haptics, motion, tones, ui-config

Props:
- `options: SwipeableTabsOption[]`: The tabs and their pages: { value, label, icon?, badge?, disabled?, content }. A number badge renders a small count (hidden at 0), any other node renders as is. A disabled tab is skipped by the arrows and a swipe never settles on it.
- `value?: string`: The selected tab, controlled. A change that arrives mid-swipe is applied after the swipe settles.
- `defaultValue?: string`: The tab selected at first, uncontrolled. Defaults to the first enabled option.
- `onValueChange?: (value: string) => void`: Fires when a swipe settles on a new page or a tab is pressed (or selected with the arrow keys).
- `variant?: "underline" | "pill" | "segmented"` = "underline": The W1 tabs looks: a 2px underline under the label, a tinted capsule, or a raised thumb in a tinted track. Each one stretches between tabs while you swipe.
- `size?: "sm" | "md" | "lg"` = "md": Trigger height 32 / 40 / 48px with matching type and icons. On touch screens md grows to 44px and sm gets a 44px hit area.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Color of the indicator, the active label and the active count badge. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color for the indicator and the active label. Replaces the tone; leave empty to use it.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the pill and the segmented track and thumb. Scales with the size; full makes capsules.
- `fullWidth?: boolean` = true: Tabs fill the row, the phone pattern: pills and segments in equal cells, underline labels evenly spaced. Off, they size to their labels and the row scrolls sideways with edge fades when they overflow.
- `layout?: "fill" | "auto"` = "fill": fill: the tabs fill their parent's height and every page is its own vertical scroller that keeps its scroll position, like an app screen. auto: pages take their content height and the tabs are as tall as the tallest page (settings sections, short forms).
- `swipe?: boolean` = true: Off: tabs only, the pages swap with a short fade like W1 tabs and the indicator springs between tabs.
- `swipeWithMouse?: boolean` = false: A mouse drag swipes the pages too. Off by default so dragging over text still selects it; touch and trackpads always swipe.
- `lazy?: boolean` = true: A page mounts the first time it is active or next to the active one, so the neighbour is ready before you swipe to it.
- `keepMounted?: boolean` = true: Visited pages stay mounted and keep their scroll position and what was typed. Off, pages more than one page away unmount after a swipe settles.
- `scrollToTopOnReselect?: boolean` = true: Tapping the active tab scrolls its page back to the top (layout="fill").
- `activationMode?: "automatic" | "manual"` = "automatic": automatic: the arrow keys select as they move. manual: the arrows only move focus and Enter or Space selects.
- `haptics?: boolean` = true: A "selection" tick through lib/haptics when a swipe settles on a new tab. Never on taps, keys or mount.
- `aria-label?: string` = "Tabs": Names the tab list for screen readers. Pass aria-labelledby instead when a visible heading names it.
- `labels?: Partial<SwipeableTabsLabels>`: Strings read to screen readers: { swipeHint } describes the gesture on the tab list while swiping is on. Defaults in DEFAULT_SWIPEABLE_TABS_LABELS ("Swipe the content left or right to switch tabs.").
- `classNames?: Partial<Record<"list" | "trigger" | "icon" | "label" | "badge" | "indicator" | "panels" | "panel", string>>`: Extra classes for the inner parts, e.g. { list: "px-4" } to inset pills from the screen edge.
- `className?: string`: Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:var(--info)].

Parts:
- `SwipeableTabsRoot` (component): The parts API root: takes the state (value, defaultValue, onValueChange), the look (variant, size, tone, color, radius, fullWidth), layout and behavior props, labels and classNames. Put a SwipeableTabsList and a SwipeableTabsPanels inside. Props: SwipeableTabsRootProps.
- `SwipeableTabsList` (component): The tablist with the moving indicator. Holds the triggers; loop (default true) wraps the arrow keys. Props: ComponentProps<"div"> & { loop?: boolean }.
- `SwipeableTabsTrigger` (component): One tab. data-state is active while the indicator is over it. Props: { value: string; icon?: ReactNode; badge?: number | ReactNode; disabled?: boolean; children }.
- `SwipeableTabsPanels` (component): The swipe viewport: a native horizontal scroll-snap container. Its panels must be in the same order as the triggers. Takes div props.
- `SwipeableTabsPanel` (component): One page. Mounted per lazy / keepMounted, inert while off screen (focus inside moves to the tab on screen), focusable only when it holds nothing focusable. Props: { value: string; children: ReactNode }.
- `useSwipeableTabs` (hook): The state of the nearest tabs, for custom parts: progress is the page position (1.5 = half way between the second and third page) for a header that fades or a page counter. Signature: () => { value: string; index: number; progress: MotionValue<number>; select: (value: string) => void }.

```tsx
import { useState } from "react"
import { SwipeableTabs } from "@/components/ui/swipeable-tabs"

const CLIENTS = [
  { name: "Tech Solutions Inc.", city: "New York", status: "active" },
  { name: "Summit Logistics", city: "Boston", status: "active" },
  { name: "Greenleaf Pharmacy", city: "Portland", status: "overdue" },
  { name: "Bistro 21", city: "Chicago", status: "prospect" },
]

function List({ status }: { status?: string }) {
  const rows = CLIENTS.filter((c) => !status || c.status === status)
  return (
    <ul className="divide-y divide-foreground/10 px-4">
      {rows.map((c) => (
        <li key={c.name} className="flex min-h-14 flex-col justify-center">
          <span className="text-[15px] font-medium">{c.name}</span>
          <span className="text-[13px] text-muted-foreground">{c.city}</span>
        </li>
      ))}
    </ul>
  )
}

export function Clients() {
  const [tab, setTab] = useState("all")
  return (
    <div className="flex h-dvh flex-col">
      <SwipeableTabs
        value={tab}
        onValueChange={setTab}
        aria-label="Clients"
        options={[
          { value: "all", label: "All", badge: 4, content: <List /> },
          { value: "active", label: "Active", badge: 2, content: <List status="active" /> },
          { value: "overdue", label: "Overdue", badge: 1, content: <List status="overdue" /> },
          { value: "prospects", label: "Prospects", content: <List status="prospect" /> },
        ]}
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/swipeable-tabs (Markdown: https://wingo-ui.com/components/swipeable-tabs.md)

### Commerce

#### Cart drawer (`cart-drawer`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add cart-drawer`

The shop cart: a side panel on desktop and a bottom sheet on phones, with lines, undo, free delivery progress, a promo code and the totals.

Tap or click the bag (or press the shortcut) and the cart slides in from the right on a laptop, or rises as a bottom sheet with a handle on a phone; drag it down, tap outside or press Escape to close it. Each line has its photo and title (both links), the variant, the unit price with the old one struck through, a quantity stepper and the line total. + and - change the quantity at once while the cart saves it (the stepper spins, the totals roll to the new amount); if the shop refuses, the line goes back and says why under it. On a trackpad or mouse the × removes a line; on a phone swipe it left, or press the trash the stepper shows at 1. A removed line folds into a thin row that says what went and offers Undo, with a bar counting down five seconds; hovering or focusing the row stops the clock, Undo puts the line back with focus on its stepper, and closing the cart keeps every removal. The free delivery bar fills as the cart grows and a check pops when you get there. "Have a promo code?" opens the code field; the summary (subtotal, sale savings, codes, delivery, VAT) sits above the checkout button, which carries the total and spins while checkout starts. On a phone, and in a short panel on a laptop screen, the summary folds to the total with a Details toggle, so the lines keep the room. Keyboard: Tab goes close, then each line (title, stepper, remove), the code and the checkout button; arrows, Page Up / Down, Home and End drive a focused stepper, Delete on it at 1 removes the line. The bag's badge bounces and the bag wiggles when something is added. Removals, restores, errors and the new total are read out politely. Under reduced motion everything fades instead of moving.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, coupon-input, drawer, empty-state, list, price, progress, quantity-stepper, use-controllable-state, use-locale, commerce, haptics, motion, number-format, tones, ui-config

Props:
- `items: CartItem[]`: The lines, owned by the caller: CartLineInput from lib/commerce (id, price, quantity, compareAtPrice, taxRate) plus title, href, image, variant, maxQuantity, seller, note and unavailable. A line with quantity 0 counts as removed; an unavailable one is dimmed and left out of the totals.
- `onQuantityChange?: (id: string, quantity: number) => (void | Promise<unknown>)`: Called when a stepper moves. The new quantity shows at once; a returned promise shows the stepper loading, and a rejection puts the old quantity back and prints its message under the line.
- `onRemove?: (id: string) => void`: Called when a removal is final: the undo window ended, the drawer closed, or at once with undoTimeout 0.
- `undoTimeout?: number` = 5000: Milliseconds a removed line can be brought back. Hovering or focusing the undo row pauses the clock. 0 removes at once.
- `defaultOpen?: boolean` = false: Starts open while uncontrolled.
- `open?: boolean`: Controlled open state; pair it with onOpenChange. Closing commits every pending removal.
- `onOpenChange?: (open: boolean) => void`: Called when the cart opens or closes.
- `trigger?: ReactNode` = "<CartButton count={itemCount} />": The element that opens the cart, rendered with asChild. Defaults to a CartButton showing the number of units.
- `coupons?: AppliedCoupon[]`: The applied codes (controlled). Leave it out and the drawer keeps them itself.
- `onCouponsChange?: (coupons: AppliedCoupon[]) => void`: Called when a code is applied or removed.
- `couponProps?: Partial<CouponInputProps>`: Passed to the CouponInput in the footer: the coupons catalogue (whose codes are recomputed as the cart changes), onApply for a server check, labels, maxCoupons.
- `showCoupon?: boolean` = true: Shows the promo code link and field in the footer.
- `shipping?: number | null` = "null": The delivery price before free-delivery rules. null prints labels.shippingLater ("Calculated at checkout"). The demo passes UPS Ground at $19.99.
- `freeShippingThreshold?: number` = 0: Spend this much (items after codes) and delivery is free. Shows a bar with "Add $45.10 more for free delivery" over the lines, and a check when it is reached. 0 hides it.
- `taxRate?: number` = 0: The cart's tax rate as a fraction (0.08 for an 8% sales tax, 0.21 for Romanian VAT). Lines with their own taxRate (a book at 0.11) keep it. Shows "Incl. VAT 8%" under the total, or a tax row added to it with pricesIncludeTax off. 0 hides the tax row.
- `pricesIncludeTax?: boolean` = true: Prices already contain VAT (shops for people). Turn it off for B2B prices: VAT is added on top as its own row.
- `totals?: CartTotals`: The server's totals (from computeCartTotals or your API). They win over the local preview everywhere, so the numbers never disagree.
- `onCheckout?: () => (void | Promise<unknown>)`: The checkout button. A returned promise shows it loading until it settles.
- `checkoutHref?: string` = "": Makes the checkout button a link to this address instead of calling onCheckout.
- `size?: "sm" | "md" | "lg"` = "md": The desktop panel width: 320 / 400 / 540px. sm also uses 64px photos. Phones always get the full-width sheet.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The checkout button's color. Brand orange is the usual choice for a shop's one hero action.
- `color?: string` = "": Any CSS color for the checkout button; replaces the tone.
- `swipeToRemove?: boolean` = true: On touch screens a line swipes left to reveal Remove; a long swipe removes it straight away.
- `haptics?: boolean` = true: Buzzes on phones only: a tick per stepper step, a firm buzz when a swipe removes a line and a success pattern when free delivery is reached.
- `shortcut?: string` = "": A key combo in mod+k notation that opens and closes the cart from anywhere, e.g. "shift+c". Empty binds nothing.
- `currency?: string` = "USD": ISO 4217 code for every amount. One currency per cart.
- `fractionDigits?: "auto" | "0" | "2" | number` = "auto": auto prints whole amounts without ",00" until one amount in a column has cents; then every line (or every summary row and the checkout button) shows them, so "$1,199.00" sits above "$159.80". A number (or "0" / "2") forces that many.
- `locale?: string` = "": Formats prices, counts and VAT rates. Empty uses the UIProvider locale, then the browser's. The demo runs in en-US.
- `note?: ReactNode`: A muted line under the checkout button ("Secure payment · Free 30-day returns").
- `children?: ReactNode`: Shown after the lines, e.g. a "Frequently bought together" rail.
- `emptyState?: ReactNode`: Replaces the empty cart: by default an EmptyState with a bag, labels.emptyTitle and a "Continue shopping" button.
- `onContinueShopping?: () => void`: The empty state's button. Defaults to closing the drawer.
- `modal?: boolean` = true: false: no dimmed overlay and no focus trap, so the page behind stays usable (the docs examples use it).
- `container?: HTMLElement | null`: Portal target. An element with contain: layout keeps the panel inside it (previews, embedded shops).
- `stepperProps?: Partial<QuantityStepperProps>`: Passed to every line's QuantityStepper: labels, variant, holdToRepeat.
- `labels?: Partial<CartDrawerLabels>`: Every string, English by default (DEFAULT_CART_DRAWER_LABELS): title "Cart", titleCount(n) "Cart (3)", subtotal, savings, coupon(code) "Code FALL15", shipping "Delivery", shippingFree "Free", shippingLater, tax(rate) "VAT 8%", taxIncluded(rate) "Incl. VAT 8%", total, checkout(total) "Checkout · $1,284.90", freeShippingRemaining(amount), freeShippingReached, removed(title), removedHint, restored(title), undo, remove, continue, emptyTitle, emptyDescription, unavailable, each, details, cartButton(n), quantity(title), maxQuantity(max), quantityError, seller(name), close.
- `classNames?: Partial<Record<"content" | "shipping" | "lines" | "line" | "summary" | "checkout" | "note" | "empty", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the drawer panel, merged last.

Parts:
- `CartButton` (component): The bag button with a count badge: a ghost icon Button whose badge bounces and whose bag wiggles when the count rises (never on mount). Props: count, max (99), size (icon-sm | icon | icon-lg), icon, label(count) for the accessible name, badgeTone, badgeColor, ringColor, locale, plus every Button prop. Props: CartButtonProps.
- `CartSummary` (component): The totals block on its own (checkout pages): items or totals, coupons, shipping, freeShippingThreshold, taxRate, pricesIncludeTax, extraRows ({ label, amount }[] added to the total, a cash on delivery fee), collapsible (phones, and a short cart panel: the total with a Details toggle), expanded / defaultExpanded / onExpandedChange, announce (true), currency, fractionDigits (auto: cents on every row once one row has them), locale, size, labels, classNames. Props: CartSummaryProps.
- `CartLineItem` (component): One line as an <li>: item, quantity (an optimistic one), onQuantityChange, onRemove, removing with onUndo / onUndoExpire / undoTimeout for the undo row, error, readOnly (a quantity instead of the stepper, for order reviews), swipeToRemove, size, haptics, currency, fractionDigits, locale, labels, stepperProps, classNames. Set --list-bg to the surface it sits on so a swipe paints the right background. Props: CartLineItemProps.
- `DEFAULT_CART_DRAWER_LABELS` (constant): The English strings, to spread under a translation. Type: CartDrawerLabels.

```tsx
import { useState } from "react"
import { CartDrawer, type CartItem } from "@/components/ui/cart-drawer"

const START: CartItem[] = [
  { id: "case", title: "iPhone 14 case, silicone, Midnight", price: 79.9, quantity: 2, image: "/demo/phone.jpg", variant: "Midnight" },
  { id: "book", title: "Rocky Mountains trail guide (book)", price: 64.9, quantity: 1, taxRate: 0.11, image: "/demo/mountains.jpg" },
]

export function ShopCart() {
  const [items, setItems] = useState(START)
  return (
    <CartDrawer
      items={items}
      onQuantityChange={(id, quantity) =>
        setItems((prev) => prev.map((item) => (item.id === id ? { ...item, quantity } : item)))
      }
      onRemove={(id) => setItems((prev) => prev.filter((item) => item.id !== id))}
      shipping={19.99}
      freeShippingThreshold={250}
      taxRate={0.08}
      tone="brand"
      currency="USD"
      note="Secure payment · Free 30-day returns"
      onCheckout={() => new Promise((resolve) => setTimeout(resolve, 1400))}
      labels={{
        titleCount: (_, n) => `Your bag (${n})`,
        checkout: (total) => `Pay ${total}`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/cart-drawer (Markdown: https://wingo-ui.com/components/cart-drawer.md)

#### Category picker (`category-picker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add category-picker`

Browse and pick a category from a tree: icon tiles, drill-down rows with a back button, counts, search across levels and a field.

Tap a tile or a row with subcategories and the next level slides in from the right; the back button (or the breadcrumb under the title, which folds its middle four levels deep) slides you back out. Tap a leaf to pick it: it tints and a check draws in, and parents on the way to your choice carry a small dot. With selectableParents the first row of a level, “All in Electronics”, picks the whole branch. Type in the search to find a category at any depth: matches are highlighted, exact words and leaves come first (then the busier category), each row shows its path, and clearing the search (its X, Escape, the back button, or the Clear search button under “No categories found”) returns to the level you were on. The field shows the picked path in a form box and opens the picker in a popover on desktop and in a full-height bottom sheet on phones, where the sheet's title row doubles as the picker's header (the level's name and the back button appear in it as you drill in); picking a leaf closes it and returns focus to the field. Keyboard: Tab reaches the back button, the search and one item per level; in the grid the arrows move in two dimensions, in lists Up and Down move, Right opens a parent and Left goes back; Home, End, Page Up and Page Down jump; Enter or Space opens or picks; Backspace outside the search goes up; Escape clears the search, then goes up a level, and at the top closes the field's overlay. In the search, Down moves into the list and Enter picks the first match. After a drill focus lands on the first item, after going back on the parent you came from. On phones tiles sit three to a row, rows are 56px and the back button is 44px; the search only takes focus by itself on a mouse or trackpad so the keyboard never covers the tree. Under reduced motion levels cross-fade instead of sliding.

npm: lucide-react, motion
Wingo UI dependencies: button, field, input, popover, use-controllable-state, use-locale, use-media-query, motion, navigation, number-format, text-match, tones, ui-config

Props:
- `categories: CategoryNode[]`: The tree. CategoryNode = { id; label; icon?; image?; color?; count?; description?; keywords?; href?; disabled?; children? }. A node with children drills, one without (or with children: []) is picked. color tints the icon tile and is inherited by the children; keywords feed the search; href turns a leaf into a link (browse mode).
- `value?: string`: The picked category id, controlled. A value that is not in the tree shows nothing selected and never crashes.
- `defaultValue?: string` = "": The starting value while uncontrolled. The picker opens on the level that holds it, so a reopened field shows the current choice in context.
- `onValueChange?: (id: string, path: CategoryNode[]) => void`: Fires when another category is picked, with the path from the top level down to it.
- `onPick?: (id: string, path: CategoryNode[]) => void`: Fires on every pick, including the current value again. Overlays close on it (the field does).
- `variant?: "grid" | "list"` = "grid": grid: icon tiles at the top level and rows below it (a marketplace home). list: rows everywhere, for sheets, sidebars and filter panels.
- `columns?: number` = 0: Tile columns. 0 fits the container: 3 in a phone-width box, 4 from 448px, 6 from 672px (container widths, so it also works in a sidebar or a popover).
- `selectableParents?: boolean` = false: A parent can be picked through an “All in …” row at the top of its level (search a whole branch). Otherwise parents only drill.
- `search?: boolean` = true: The search box over every level. Enter picks the first match; it never submits a surrounding form.
- `showCounts?: boolean` = true: Listing counts on tiles, rows and the level header, formatted for the locale (128.430). Screen readers hear them with labels.count.
- `iconStyle?: "tile" | "plain"` = "tile": tile puts the icon in a rounded square tinted with the node's color (neutral gray without one); plain shows the colored icon alone.
- `size?: "sm" | "md" | "lg"` = "md": Tiles 88 / 104 / 120px tall with 40 / 48 / 56px icon tiles; rows 44 / 56 / 64px; the search box follows.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected tile or row: a gray tint for neutral, the soft tone otherwise, plus the check and the dot on parents that hold the choice.
- `color?: string` = "": Any CSS color for the selected look; replaces the tone. Category colors come from the nodes, not from this.
- `locale?: string` = "": Formats the counts and the results line. Empty uses the UIProvider's locale, then the browser's.
- `query?: string`: The search text, controlled. Pair it with onQueryChange.
- `defaultQuery?: string` = "": The search text on the first render, e.g. a term carried over from the site search.
- `onQueryChange?: (query: string) => void`: Fires as the search text changes.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders leaves that have an href (browse mode) instead of picking them. Defaults to the LinkProvider's component (Next's Link in an app), then a plain <a>.
- `labels?: Partial<CategoryPickerLabels>`: Every string, English by default (DEFAULT_CATEGORY_PICKER_LABELS): search "Search categories", back "Back", allCategories "All categories", all (label) => "All in …", empty "No categories found", results (n, formatted) => "12 categories", count (n, formatted) => "128,430 listings", separator "›", subcategories "has subcategories", containsSelected "contains your choice", clear "Clear search", breadcrumb "Category path".
- `classNames?: Partial<Record<"top" | "header" | "back" | "title" | "breadcrumb" | "search" | "panel" | "grid" | "list" | "item" | "icon" | "label" | "count" | "results" | "empty", string>>`: Extra classes for the inner parts. top wraps the header, breadcrumb and search (the field pins it with sticky).

Parts:
- `CategoryPickerField` (component): The form field: the W2 field anatomy (label, description, error, required, size, variant soft | outline, radius, name for a hidden input) around a box that shows the picked path with the leaf's icon, placeholder "Choose a category". Opens a CategoryPicker variant="list" in a popover on desktop and a full-height bottom sheet on phones (responsive, default true; sheetTitle defaults to the label's text, then "Category", and heads the top level inside the sheet). open / defaultOpen / onOpenChange, container, plus the picker's selectableParents, search, showCounts, iconStyle, tone, color, locale, labels and linkComponent; classNames (field parts, trigger, value, chevron, content), pickerClassNames and fieldProps reach the inner parts. Picking a leaf closes it and returns focus to the field; a form reset restores defaultValue. Props: CategoryPickerFieldProps.
- `findCategoryPath` (function): The path from the top level down to the node with this id (the node last), or [] when it is not in the tree. Breadcrumbs, readouts and filters use it. Signature: (categories: CategoryNode[], id: string) => CategoryNode[].
- `flattenCategories` (function): Every node in reading order with its path; the search runs over it, and a plain select of categories can too. Signature: (categories: CategoryNode[]) => { node: CategoryNode; path: CategoryNode[] }[].
- `DEFAULT_CATEGORY_PICKER_LABELS` (constant): The English strings. Spread and override for another language. Type: CategoryPickerLabels.

```tsx
import { Smartphone, House } from "lucide-react"
import { CategoryPicker, CategoryPickerField, type CategoryNode } from "@/components/ui/category-picker"

const categories: CategoryNode[] = [
  {
    id: "electronics",
    label: "Electronics and appliances",
    icon: <Smartphone />,
    color: "#7C3AED",
    count: 128430,
    children: [
      { id: "mobile-phones", label: "Mobile phones", count: 38420, keywords: ["iphone"] },
      { id: "computers", label: "Laptops and computers", count: 18940 },
    ],
  },
  { id: "real-estate", label: "Real estate", icon: <House />, color: "#16A34A", count: 98215 },
]

export function PickCategory() {
  return (
    <div className="flex flex-col gap-6">
      <CategoryPicker
        categories={categories}
        onValueChange={(id, path) => console.log(id, path.map((n) => n.label).join(" › "))}
        labels={{ search: "Find a category", allCategories: "Everything" }}
      />
      <CategoryPickerField
        categories={categories}
        label="Category"
        placeholder="Pick a category"
        required
        name="category"
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/category-picker (Markdown: https://wingo-ui.com/components/category-picker.md)

#### Checkout steps (`checkout-steps`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add checkout-steps`

A four step checkout: address and invoice, delivery with lockers, payment, then a review that places the order, beside a sticky summary.

Four steps under a stepper: Delivery details (email, a saved address card or a new address with county select, city combobox, street and postal code, then an Individual / Company switch that opens the company fields), Shipping (priced courier, easybox and pickup cards; an easybox opens a searchable list of pickup points), Payment (card, cash on delivery with its fee, bank transfer with the IBAN to copy, instalments that unlock above a total) and Review (every choice with an Edit link, notes, the terms box and Place order with the total). Continue checks the step: the fields that are wrong turn red with a message, the button shakes and focus jumps to the first one; each message clears as you fix it. A saved address missing a field shows Complete the address and opens the form. Changing the county clears the city. Choices that change the price (a coupon, a method that becomes free past the threshold, a payment fee) update the cards and the summary in place, and the new total is read out. Place order spins while the order is sent, turns into a check with a small bounce and locks the review, then the success content fades in and takes focus; a refusal shakes the button and shows the reason above it. The summary is a sticky column when the checkout is wide and a bar at the top when it is narrow (Show summary with the total) that unfolds the lines, the promo code and the totals. On a phone each step is a full-height page: the step count and title on top, the total, Back and Continue at the bottom above the home indicator, hidden while the keyboard is up. Keyboard: Tab through the fields, Enter moves to the next field and continues from the last one, arrows move between radio cards and pickup points, Space picks, mod+Enter in the notes continues; completed steps in the stepper are buttons. Under reduced motion steps and panels fade instead of sliding.

npm: motion, lucide-react
Wingo UI dependencies: alert, badge, button, cart-drawer, checkbox, combobox, coupon-input, form-wizard, input, phone-input, price, radio-group, segmented-control, select, textarea, use-controllable-state, use-keyboard-inset, use-locale, commerce, motion, number-format, tones, ui-config

Props:
- `items: CartItem[]`: The cart lines (CartItem from cart-drawer): id, title, price, quantity, compareAtPrice, taxRate, image, variant. Unavailable lines and quantity 0 are left out; an empty list shows the empty state.
- `value?: CheckoutValue`: Controlled checkout data: email, addressId, address (CheckoutAddress), invoice (CheckoutInvoice), deliveryMethod, lockerId, paymentMethod, notes, acceptTerms, coupons (AppliedCoupon[]). Pair it with onValueChange.
- `defaultValue?: CheckoutValue` = "{}": The starting data while uncontrolled (a returning buyer's email, a remembered method).
- `onValueChange?: (value: CheckoutValue) => void`: Called with the whole value on every change.
- `defaultStep?: "address" | "delivery" | "payment" | "review"` = "address": The step it opens on while uncontrolled; the steps before it count as done.
- `step?: CheckoutStepId`: The controlled step; pair it with onStepChange.
- `onStepChange?: (step: CheckoutStepId) => void`: Called when the step changes (Continue, Back, Edit links, the stepper).
- `steps?: CheckoutStepId[]` = "[\"address\", \"delivery\", \"payment\", \"review\"]": The steps in order, e.g. ["payment", "review"] for a digital product. A step whose data is missing (delivery without deliveryMethods) is skipped with a warning in development.
- `savedAddresses?: CheckoutAddress[]` = "[]": Address cards to pick from, plus New address. The first one is chosen at the start; one missing a required field shows Complete the address and opens the form.
- `regions?: { value: string; label: string; description?: string }[]`: The County select (countyOptions() from ro-locations); without it the county is a text field.
- `getCities?: (region: string) => (CheckoutCity[] | Promise<CheckoutCity[]>)`: The City combobox for the chosen county ({ value, label, description, keywords }[]), sync or async (cityOptions(county) from ro-locations); without it a text field. Typed names outside the list are kept.
- `deliveryMethods?: DeliveryMethod[]`: Required when the delivery step is used: { id, label, description, price, eta, type: courier | locker | pickup, icon, logo, freeFrom, disabled }. Prices turn to Free in place once the threshold or a coupon makes them free.
- `lockers?: CheckoutLocker[] or (methodId: string) => Promise<CheckoutLocker[]>`: The pickup points of a locker method ({ id, label, address, distance, hours }), or a loader called per method (skeleton rows while it runs). A locker method then needs a chosen point.
- `paymentMethods?: PaymentMethod[]`: Required when the payment step is used: { id, label, description, icon, logos, fee, minTotal, disabled, details }. fee joins the summary and the total; below minTotal the card is disabled with Available from; details (a card form slot, the IBAN) unfold under the cards while chosen.
- `invoice?: boolean` = true: Shows the Individual / Company switch and the company fields (name, CUI checked with the ANAF key, trade register no.).
- `requireTerms?: boolean` = true: Shows the terms checkbox in the review step and requires it before the order is placed.
- `termsLabel?: ReactNode` = "labels.terms": The terms checkbox label, with links to the terms and privacy pages.
- `showCoupon?: boolean` = true: The promo code field in the summary.
- `couponProps?: Partial<CouponInputProps>`: Passed to the CouponInput: the coupons catalogue, onApply for a server check, labels.
- `freeShippingThreshold?: number` = 0: Courier and locker delivery is free from this much (items after coupons); a method's freeFrom wins. 0: no offer.
- `taxRate?: number` = 0: The VAT rate as a fraction (0.21); 0 hides the VAT row. Lines can carry their own rate.
- `pricesIncludeTax?: boolean` = true: Prices include VAT (Romanian B2C); false adds VAT on top as its own row.
- `summary?: "aside" | "collapsible" | "none"` = "aside": aside: a sticky summary column once the checkout itself is 896px wide (a container query), a Show summary bar when narrower; collapsible: the bar at every width; none: no summary.
- `stepper?: "horizontal" | "progress"` = "horizontal": The form-wizard header from 768px: numbered steps, or a progress bar with the step title. Phones always show the compact progress.
- `fullScreenOnMobile?: boolean` = true: Below 768px each step fills the container: the summary bar and step count on top, a sticky footer with the total and Continue above the home indicator.
- `onPlaceOrder?: (value: CheckoutValue, totals: CartTotals) => (void | Promise<unknown>)`: Places the order after the review step validates; totals.total includes the payment fee. A promise shows the button loading; a resolve turns it into a check, then successContent; a rejection shows an alert with its message in the review step.
- `successContent?: ReactNode`: Replaces the wizard once the order is placed (order number, next steps).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Continue, Place order and the stepper's active marker.
- `color?: string` = "": Any CSS color for the same parts; replaces the tone.
- `size?: "sm" | "md"` = "md": Fields, cards, the stepper and the buttons: sm for a narrow column, md for the page.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The corners of Back, Continue and Place order.
- `country?: string` = "RO": RO checks the postal code (6 digits) and the CUI control key and starts the phone at +40; other codes relax those checks.
- `currency?: string` = "RON": ISO 4217 code for every amount.
- `locale?: string` = "": Locale for prices and numbers; empty uses the UIProvider's, then the browser's.
- `labels?: Partial<CheckoutStepsLabels>`: Every string, English by default (DEFAULT_CHECKOUT_STEPS_LABELS): the step titles address "Delivery details", delivery "Shipping", payment "Payment", review "Review"; continue, back, placeOrder(total) "Place order · RON 1,284.90", placed, stepOf(i, n), edit, newAddress, incompleteAddress, contact, the field labels (name, phone, email, county, city, street, details, postalCode, companyName, cui, regCom) and placeholders (emailPlaceholder, countyPlaceholder, cityPlaceholder, cuiPlaceholder, regComPlaceholder), invoiceTitle, person, company, locker, lockerSearch, free, fee(amount), minTotal(amount), paymentFee(method), notes, terms, summary, showSummary(total), hideSummary, the summary rows (subtotal, shipping, total...) and the errors (required, invalidEmail, invalidPhone, invalidCui, invalidPostalCode, acceptTerms, chooseDelivery, chooseLocker, choosePayment).
- `classNames?: Partial<Record<"layout" | "wizard" | "summary" | "summaryBar" | "address" | "delivery" | "payment" | "review" | "placeOrder", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `isValidCui` (function): The Romanian tax ID check: an optional "RO" prefix, 2 to 10 digits, and the ANAF control digit (key 753217532). isValidCui("RO12345674") is true, "RO12345678" is false. Signature: (cui: string) => boolean.
- `validateCheckoutStep` (function): The same checks the wizard runs, for a server or a custom flow: field errors keyed "email", "address.phone", "invoice.cui", "deliveryMethod", "lockerId", "paymentMethod", "acceptTerms". Options: country, invoice, requireTerms, savedAddresses, deliveryMethods, lockers, paymentMethods, total, labels. Signature: (step: CheckoutStepId, value: CheckoutValue, options?: CheckoutValidationOptions) => Record<string, string>.
- `DEFAULT_CHECKOUT_STEPS_LABELS` (constant): The English strings, to spread under a translation. Type: CheckoutStepsLabels.

```tsx
import { CheckoutSteps, type DeliveryMethod, type PaymentMethod } from "@/components/ui/checkout-steps"
import type { CartItem } from "@/components/ui/cart-drawer"
import { RO_VAT_RATE } from "@/lib/commerce"
import { cityOptions, countyOptions } from "@/lib/ro-locations"

const items: CartItem[] = [
  { id: "case", title: "iPhone 14 case, silicone, Midnight", price: 79.9, quantity: 2, image: "/demo/phone.jpg" },
  { id: "stand", title: "Aluminum laptop stand", price: 149, quantity: 1, image: "/demo/laptop.jpg" },
]

const delivery: DeliveryMethod[] = [
  { id: "fan", label: "Fan Courier", price: 19.99, eta: "1-2 business days", type: "courier" },
  { id: "pickup", label: "Pick up in Cluj-Napoca", price: 0, type: "pickup" },
]

const payment: PaymentMethod[] = [
  { id: "card", label: "Card" },
  { id: "cash", label: "Cash on delivery", fee: 4.99 },
]

export function Checkout() {
  return (
    <CheckoutSteps
      items={items}
      regions={countyOptions()}
      getCities={(county) => cityOptions(county)}
      deliveryMethods={delivery}
      paymentMethods={payment}
      freeShippingThreshold={250}
      taxRate={RO_VAT_RATE}
      tone="brand"
      onPlaceOrder={(value, totals) =>
        fetch("/api/orders", { method: "POST", body: JSON.stringify({ value, total: totals.total }) })
      }
      successContent={<p>Order #1042 is placed.</p>}
      labels={{
        review: "Confirm",
        placeOrder: (total) => `Pay ${total}`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/checkout-steps (Markdown: https://wingo-ui.com/components/checkout-steps.md)

#### Coupon input (`coupon-input`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add coupon-input`

The promo code field of carts and checkouts: a link that opens it, Apply inside the box, async checks and applied codes as chips.

Tap or click "Have a promo code?" and the field slides open with the cursor in it (the chevron turns). Type a code in any case with any spaces; it shows in capitals. Press Enter or Apply: with a server check the button spins while it waits, and Enter never submits the checkout form around it. A good code lands as a chip with a check that pops, the code, its label and what it saves; at the code limit the field folds away until you remove a chip. A bad code shakes the box and says what to do ("Add $45.20 more to use SAVE50", "This code expired on August 31, 2026"). Escape clears the typed code; a second Escape on an empty field closes it and puts focus back on the link. Escape while a code is being checked does nothing. Tab reaches the remove button of each chip; Enter, Space, Backspace or Delete removes it. When the cart changes, catalogue codes recount what they save and a code that no longer applies turns amber with a note under it. Every outcome is read out once by screen readers; on a phone the outcome also buzzes. Under reduced motion everything fades instead of moving.

npm: motion, lucide-react
Wingo UI dependencies: button, field, spinner, tag, commerce, use-locale, use-controllable-state, haptics, motion, tones, ui-config

Props:
- `subtotal?: number` = 0: The items' subtotal, used for minimum-order checks and to work out what a percent or fixed code saves. The demo uses its $489.70 cart while this is 0.
- `shipping?: number` = 0: The delivery cost a free-delivery code saves. The demo uses $19.99 (UPS) while this is 0.
- `currency?: string` = "USD": ISO 4217 code for the saved amounts and the minimum-order message: "$", "€", "lei".
- `locale?: string` = "": Intl locale for the amounts ("en-US" prints $45.20, "ro-RO" 45,20 lei). Empty uses the UIProvider locale, then the browser's.
- `label?: ReactNode` = "": A visible label above the box, for checkout forms. Without it the input is named by the placeholder text.
- `size?: "sm" | "md" | "lg"` = "md": The field box at 32 / 40 / 48px (44px on touch at md), with a matching Apply button, chips and link text.
- `variant?: "soft" | "outline"` = "soft": soft is the filled well that works on any surface; outline is a hairline box for white forms.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corner shape of the box and the Apply button; scales with the size like the button's.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of the soft Apply button. brand suits a checkout's one orange accent.
- `defaultOpen?: boolean` = false: Starts with the field open instead of the link. Only matters while collapsible.
- `disabled?: boolean` = false: Dims and blocks the link, the field, Apply and the chips' remove buttons.
- `collapsible?: boolean` = true: Starts as the "Have a promo code?" link that opens the field. Off keeps the field open (checkout pages).
- `maxCoupons?: number` = 1: How many codes can be applied together. At the limit the field hides until a chip is removed.
- `haptics?: boolean` = true: A success or error buzz on touch devices when a check ends (lib/haptics). Never on a mouse click.
- `value?: AppliedCoupon[]`: The applied codes, controlled. AppliedCoupon = { code: string; label?: ReactNode; amount?: number; type?: CouponType; valid?: boolean }.
- `defaultValue?: AppliedCoupon[]` = "[]": The applied codes to start with, uncontrolled.
- `onValueChange?: (value: AppliedCoupon[]) => void`: Called with the new list after a code is applied or removed.
- `onApply?: ((code: string) => CouponResult | Promise<CouponResult>)`: The server check, called with the trimmed upper-case code. Resolve the exported CouponResult, { ok: true, coupon } or { ok: false, error }; a rejected promise shows its Error.message or labels.invalid. Wins over coupons.
- `coupons?: Coupon[]`: A local catalogue (lib/commerce) checked case-insensitively with couponDiscount against subtotal when onApply is absent. Applied catalogue codes are also rechecked whenever subtotal or shipping change.
- `open?: boolean`: Whether the field is open, controlled. Pair with onOpenChange.
- `onOpenChange?: (open: boolean) => void`: Called when the link, Escape or reaching the code limit opens or closes the field.
- `icon?: ReactNode`: The icon on the link and at the start of the box; a TicketPercent by default, null hides it.
- `labels?: Partial<CouponInputLabels>`: Every string: trigger "Have a promo code?", placeholder "Promo code", apply "Apply", checking "Checking…", remove(code), applied(code), saved(amount) "-$45", freeShipping "Free delivery", invalid, minSubtotal(missing, code), duplicate, limit "One code per order", empty "Enter a code", noLongerValid(code), removed(code), list "Applied codes" (names the chip list for screen readers). The English set is exported as DEFAULT_COUPON_INPUT_LABELS.
- `classNames?: Partial<Record<"trigger" | "label" | "box" | "input" | "apply" | "error" | "list" | "chip" | "warning", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { CouponInput, type AppliedCoupon } from "@/components/ui/coupon-input"
import type { Coupon } from "@/lib/commerce"
import { useState } from "react"

const COUPONS: Coupon[] = [
  { code: "FALL15", type: "percent", value: 15, maxDiscount: 150, label: "Fall sale" },
  { code: "FREESHIP", type: "shipping", value: 0, label: "Free delivery" },
  { code: "SAVE50", type: "fixed", value: 50, minSubtotal: 300 },
]

export function CartCoupon() {
  const [applied, setApplied] = useState<AppliedCoupon[]>([])
  return (
    <CouponInput
      value={applied}
      onValueChange={setApplied}
      coupons={COUPONS}
      subtotal={489.7}
      shipping={19.99}
      locale="en-US"
      labels={{
        trigger: "Got a discount code?",
        invalid: "We don't recognize that code",
        minSubtotal: (missing, code) => `Add ${missing} more to use ${code}`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/coupon-input (Markdown: https://wingo-ui.com/components/coupon-input.md)

#### Favorite button (`favorite-button`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add favorite-button`

The heart that saves a listing: fills with a spring pop and a burst, keeps a count, saves optimistically and rolls back on failure.

Tap or click the heart to save: it dips, pops past its size on a bouncy spring, fills in and throws a ring and a handful of particles; tap again and the fill shrinks away. With a count the number rolls up or down by one right away. While the save request is pending further taps are ignored; when it fails the heart shakes, goes back to how it was and the error is read out. On a phone a light tick answers the tap, every size has a 44px target, and the glass heart on a photo sits above the card's link so it never opens the listing. With a mouse the action shows as a tooltip. Tab to it and press Space or Enter to toggle; screen readers hear one constant name, the pressed state and the count.

npm: lucide-react, motion
Wingo UI dependencies: tooltip, use-controllable-state, use-locale, use-media-query, haptics, motion, number-format, tones, ui-config

Props:
- `defaultPressed?: boolean` = false: Starts saved. The button then owns its state.
- `pressed?: boolean`: Controlled on / off. While a request is pending, a change of this prop wins and the pending answer is ignored.
- `onPressedChange?: ((pressed: boolean) => void | Promise<unknown>)`: Called with the new state when a person toggles it. Return a promise to keep the optimistic state while it is pending (clicks are ignored meanwhile); a rejection, or a synchronous throw, rolls back, shakes, buzzes on touch and announces labels.error.
- `variant?: "ghost" | "overlay" | "soft" | "outline"` = "ghost": ghost: a bare icon button for rows and headers. overlay: a round glass button for photos (white heart, black glass in both themes). soft and outline: a chip for counts and labels.
- `size?: "sm" | "md" | "lg"` = "md": Icon only: 32 / 40 / 48px (the overlay 32 / 36 / 44px) with a 16 / 20 / 22px heart; md grows to 44px on touch and the rest get a 44px hit area. Chips take the button heights.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape, scaled per size like the button. full is a circle, or a pill for chips.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The on color. neutral fills black / white (white on photos); the classic red heart is danger. The chip tints use the tone's soft colors.
- `color?: string` = "": Any CSS color for the filled heart, the burst and the chip tint. Replaces the tone.
- `icon?: ReactNode` = "<Heart />": Any lucide icon: ThumbsUp for a helpful vote, Bookmark for saved searches, Star. The on copy is drawn with fill-current.
- `count?: number` = 0: The total including this person's vote, as the server knows it. The shown number moves by one right away when toggled and never goes below 0. Compact from 10.000 (12,4 K).
- `showCount?: boolean` = false: Shows the count beside the icon; it rolls up or down when it changes and is described to screen readers.
- `showLabel?: boolean` = false: Shows labels.save / labels.saved beside the icon. Both share one cell, so the chip never changes width. The accessible name stays constant (labels.name, or labels.save when no name is given) while aria-pressed flips.
- `burst?: boolean` = true: A ring and particles when a person turns it on. Never on mount, on a prop change or under reduced motion.
- `particleCount?: number` = 8: How many particles the burst throws, spread evenly around the heart with a fixed jitter.
- `tooltip?: boolean` = true: Shows the action (labels.add / labels.remove) as a tooltip on hover and focus. Never on touch.
- `haptics?: boolean` = true: A light tick on touch when it turns on and an error buzz on rollback. Never from a mouse or on mount.
- `disabled?: boolean` = false: Dims the button and blocks it.
- `locale?: string` = "": Formats the count (1.284 in ro-RO, 1,284 in en-US). Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<FavoriteButtonLabels>`: Every string: name "Save" (the constant accessible name), add "Add to favorites", remove "Remove from favorites", save "Save", saved "Saved", error "Could not save. Try again.", count (n, formatted) => "128 saves". The English set is exported as DEFAULT_FAVORITE_BUTTON_LABELS.
- `classNames?: Partial<Record<"icon" | "burst" | "label" | "count", string>>`: Extra classes for the inner parts.
- `onClick?: (event: MouseEvent<HTMLButtonElement>) => void`: Runs before the toggle; event.preventDefault() cancels it.
- `className?: string`: Extra classes for the button, merged last.

```tsx
import { FavoriteButton } from "@/components/ui/favorite-button"

const labels = {
  name: "Save listing",
  add: "Add to your watchlist",
  remove: "Remove from your watchlist",
  error: "We could not save it. Try again.",
}

export function ListingPhoto({ saved, onSave }: { saved: boolean; onSave: (saved: boolean) => Promise<unknown> }) {
  return (
    <div className="relative aspect-[4/3] overflow-hidden rounded-2xl bg-foreground/5">
      <img src="/demo/bicycle.jpg" alt="Pegas Popular city bike" className="size-full object-cover" />
      <FavoriteButton
        variant="overlay"
        tone="danger"
        pressed={saved}
        onPressedChange={onSave}
        labels={labels}
        className="absolute end-2.5 top-2.5"
      />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/favorite-button (Markdown: https://wingo-ui.com/components/favorite-button.md)

#### Filter panel (`filter-panel`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add filter-panel`

Faceted marketplace filters: a sidebar that applies as you go on wide screens, a full-height sheet with a live result count on phones.

On a wide screen the filters sit in a sidebar and every change applies at once: tap a section title to fold or unfold it (a dot marks the ones in use, and a folded section shows its choice under the title, like “Apple, Samsung”), drag the price thumbs over the histogram and let go, type a price and press Enter, pick a category row, tick a brand, tap a condition or radius chip, flip a switch. Tap “Show 7 more” for the rest of a long list, or type in its search field when it has more than ten options. The chips under the title remove one value each with their × (or Backspace and Delete while focused), and “Clear all” in the header clears every filter. With applyMode set to apply the sidebar keeps a draft until you press Apply. Below the breakpoint a Filters pill with the active count takes the sidebar’s place: tap it and a full-height sheet slides up (a side panel on desktop in sheet mode) with the same sections, the first two open, and a footer button that counts your draft as you choose (“Show 1.240 results”, a spinner while it counts, “No results, try fewer filters” when nothing matches). The button applies and closes; swiping the sheet down, tapping the backdrop or pressing Escape throws the draft away, and Reset clears only the draft. The place field opens its own searchable sheet on a phone, and “My location” fills it in when the page can locate you. Keyboard: Tab walks the sections, Enter or Space folds them and arrows move between their titles; every control keeps its own keys (arrows and Page keys on the sliders, Enter in the inputs, arrows in the chip and radio groups). A shortcut prop (like mod+shift+f) opens the sheet, or jumps to the first section while the sidebar shows. Under reduced motion sections, chips and the count fade instead of moving.

npm: lucide-react, motion
Wingo UI dependencies: accordion, badge, button, category-picker, checkbox, combobox, commerce, drawer, input, kbd, motion, number-format, number-input, price-range, radio-group, slider, spinner, switch, tag, text-match, tones, ui-config, use-controllable-state, use-debounce, use-locale, use-media-query, use-shortcut

Props:
- `filters: FilterDef[]`: The sections, in order. A union on type: category (a CategoryPicker list), price (a PriceRange over a histogram), location (a place combobox, popular places and radius chips; "My location" with onLocate), checkbox (rows with counts, a limit and "Show more", a search field past ten options), radio (with an "any" row), chips (single or multiple), range (a two-thumb slider and two number inputs with a unit), toggle (a switch row) and custom (render, describe, isActive). Every filter has an id, a label, an optional description and defaultCollapsed. Unknown types are skipped with a warning in development.
- `value?: FilterValues`: The committed filters, keyed by filter id: category and radio a string, price and range [min, max] with null for an open end, location { place, radius }, checkbox and chips string[], toggle true. Inactive filters leave the object; keys of filters not in the list are kept.
- `defaultValue?: FilterValues`: The starting filters while uncontrolled. Defaults to {}.
- `onValueChange?: (values: FilterValues) => void`: The sidebar in instant mode calls it on every commit (a slider release, a toggle, a pick, never per keystroke); the sheet and apply mode call it on the Apply button; chips and Clear all call it at once in the sidebar.
- `mode?: "auto" | "sidebar" | "sheet"` = "auto": auto shows the sidebar from the breakpoint up and the Filters button with a bottom sheet below it (switched with CSS, so the server HTML is right). sidebar always shows the sidebar; sheet always shows the button, with a side panel on desktop.
- `breakpoint?: "md" | "lg"` = "lg": Where auto switches from the sheet to the sidebar: 768px or 1024px. Crossing it with the sheet open closes the sheet.
- `applyMode?: "instant" | "apply"` = "instant": The sidebar's behavior: instant commits each change, apply keeps a draft until the Apply button in its footer. The sheet always keeps a draft.
- `getResultCount?: (values: FilterValues) => (number | Promise<number>)`: Counts the sheet's draft for its button, 250ms after the last change (the first count of an opening runs at once). A promise shows a spinner; an older answer never overwrites a newer one; a rejection falls back to the plain Show results label.
- `resultCount?: number` = 0: A fixed count for the sheet's button when there is no getResultCount. 0 reads Show results.
- `open?: boolean`: The sheet's open state, controlled. Opening copies the committed value into a draft; a value changing while it is open does not touch the draft.
- `defaultOpen?: boolean` = false: Starts with the sheet open (only where the sheet is in use: sheet mode, or auto below the breakpoint).
- `onOpenChange?: (open: boolean) => void`: Called when the sheet opens or closes, by the button, a shortcut, a swipe, the backdrop or Escape.
- `trigger?: ReactNode` = "<FilterPanelTrigger />": Replaces the Filters button that opens the sheet (a single element that takes a ref). null renders none, so you can open the sheet from a toolbar with open and onOpenChange.
- `showChips?: boolean` = true: The active filters as removable chips under the title (sidebar) or at the top of the sheet.
- `collapsible?: boolean` = true: Sections fold like an accordion. false keeps every section open under a plain heading.
- `defaultExpanded?: string[]`: Filter ids open at first. Defaults to the first four sections in the sidebar and the first two in the sheet (skipping toggles and those with defaultCollapsed).
- `hideEmpty?: boolean` = false: Hides options with a count of 0 instead of showing them disabled. A picked option always stays.
- `sticky?: boolean` = true: The sidebar sticks under var(--topbar-offset, 0px) and scrolls on its own when it is taller than the screen.
- `size?: "sm" | "md"` = "md": The controls inside: checkboxes, switches, sliders, fields and chips. sm suits a narrow sidebar.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Checked boxes, picked chips, the slider ranges, the lit histogram bars, the section dots, the count badge and the Apply button.
- `color?: string` = "": Any CSS color; replaces the tone everywhere it paints.
- `shortcut?: string` = "": A key combo in mod+k notation that opens (and closes) the sheet, or jumps to the first section while the sidebar shows. The button shows it as a key hint on devices with a keyboard. None by default.
- `currency?: string` = "USD": ISO 4217 code for the price section, its chips and summaries.
- `locale?: string` = "": Counts, prices and ranges (1,240 in en-US). Empty uses the UIProvider's locale, then the browser's.
- `container?: HTMLElement | null`: Portal target of the sheet. Defaults to document.body.
- `labels?: Partial<FilterPanelLabels>`: Every string, English by default (DEFAULT_FILTER_PANEL_LABELS): title "Filters", clearAll "Clear all", reset "Reset", apply "Apply", showResults (count, formatted), showResultsUnknown "Show results", noResults "No results, try fewer filters", any "Any", anywhere "Anywhere", radius (km) "+25 km" ("Only here" for 0), distance, myLocation "My location", showMore (count), showLess, searchOptions, noMatches, from, to, rangeFrom (value), rangeTo (value), trigger "Filters", active (count) "3 active", chips, remove, clear, cancel (the place field and its phone sheet), plus priceRange and categoryPicker labels passed through.
- `classNames?: Partial<Record<"sidebar" | "header" | "chips" | "section" | "trigger" | "content" | "footer" | "apply", string>>`: Extra classes for the parts: the sidebar's aside (give it a panel look here), the headers, the chip row, each section, the Filters button, the sheet, the footers and the Apply buttons.
- `className?: string`: Extra classes for the root; the page sets the sidebar's width here (lg:w-72).

Parts:
- `FilterPanelTrigger` (component): The Filters pill on its own: an outline button with the sliders icon and a count badge that pops when it changes; its accessible name reads "Filters, 3 active" and a shortcut goes to aria-keyshortcuts (its key hint is hidden from screen readers and on touch). tone and color paint the badge. Props: ButtonProps & { count?: number; label?: ReactNode; activeLabel?: (count: number) => string; shortcut?: string; locale?: string }.
- `FilterChips` (component): The active filters as removable chips for a toolbar or over the results, with Clear all once there are two. Renders nothing while no filter is active. Props: { filters; value?; defaultValue?; onValueChange?; showClearAll?; size?; tone?; color?; currency?; locale?; labels?; classNames? }.
- `describeFilters` (function): The chips as data, also the shape of toolbar's appliedFilters: one per checkbox or chip value ("Apple"), one per other filter ("Price: $500 to $3,000", "Chicago +25 km"). Signature: (filters: FilterDef[], values: FilterValues, options?: { locale?; currency?; labels? }) => { id: string; filterId: string; label: ReactNode }[].
- `removeFilterValue` (function): The values without one chip: a single checkbox value, or the whole filter. Signature: (filters: FilterDef[], values: FilterValues, chipId: string) => FilterValues.
- `countActiveFilters` (function): How many filters are in use (two brands count once), for a badge or a heading. Signature: (filters: FilterDef[], values: FilterValues) => number.
- `FilterDef` (type): FilterOption is { value, label, count?, icon?, description?, disabled?, keywords?, textValue? }; a count of 0 disables the option. Also exported: FilterLocationValue, FilterRangeValue, FilterChip, FilterPanelLabels and DEFAULT_FILTER_PANEL_LABELS. Shape: type.

```tsx
import { useState } from "react"
import { Truck } from "lucide-react"
import { FilterPanel, type FilterDef, type FilterValues } from "@/components/ui/filter-panel"

const filters: FilterDef[] = [
  { type: "price", id: "price", label: "Price", min: 0, max: 1800, presets: [{ min: null, max: 100 }, { min: 100, max: 300 }] },
  {
    type: "chips",
    id: "condition",
    label: "Condition",
    options: [
      { value: "new", label: "New", count: 310 },
      { value: "used", label: "Used", count: 843 },
      { value: "parts", label: "For parts", count: 87 },
    ],
  },
  {
    type: "checkbox",
    id: "brand",
    label: "Brand",
    options: [
      { value: "apple", label: "Apple", count: 312 },
      { value: "samsung", label: "Samsung", count: 287 },
      { value: "xiaomi", label: "Xiaomi", count: 164 },
    ],
  },
  { type: "toggle", id: "delivery", label: "Delivery only", icon: <Truck /> },
]

export function PhoneFilters({ count }: { count: (values: FilterValues) => Promise<number> }) {
  const [values, setValues] = useState<FilterValues>({})
  return (
    <div className="flex flex-col gap-4 lg:flex-row lg:items-start">
      <FilterPanel
        filters={filters}
        value={values}
        onValueChange={setValues}
        getResultCount={count}
        locale="en-US"
        className="lg:w-72 lg:shrink-0"
      />
      <main className="min-w-0 flex-1">{/* results */}</main>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/filter-panel (Markdown: https://wingo-ui.com/components/filter-panel.md)

#### Listing card (`listing-card`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add listing-card`

The ad card of a marketplace: swipeable photos, the price, place and time, badges and a heart, in grid, list and compact layouts.

Tap or click anywhere on the card to open the listing: the title is one link stretched over the whole card, so long-press and middle-click give the native link menu. Swipe the photos sideways on a phone (vertical scrolling always wins, and a swipe never opens the listing); with a mouse, drag them or use the arrows that appear on hover, and the photo zooms in a touch. Tap the heart to save the listing: it pops with a small burst, and rolls back with a shake if saving fails. Keyboard: Tab meets the title link, the photo arrows (they show while the card holds focus) and the heart once each; Left / Right change the photo while focus is on the photo's controls; Enter opens the listing, Space or Enter toggles the heart. Dots under the photo show where you are (at most five, sliding along); a camera chip tells how many photos there are when not all of them are in the card. The first photo is a plain image until you touch, hover or focus it, so a grid of 48 cards stays light; under reduced motion the photo does not zoom.

npm: lucide-react
Wingo UI dependencies: avatar, badge, card, carousel, favorite-button, price, skeleton, use-locale, use-media-query, date-utils, navigation, number-format, relative-time, tones, ui-config

Props:
- `listing: ListingData`: The ad: { id, title, href?, images?: (string | { src, alt?, width?, height? })[], price (null: on request), currency?, compareAtPrice?, priceType?, priceSuffix?, unit?: { quantity, unit }, location?, distanceKm?, postedAt?, promoted?, delivery?, condition?: "new" | "used", attributes?: string[], badges?: { label, tone?, icon? }[], seller?: { name, avatar?, business?, verified?, rating? }, status?: "active" | "reserved" | "sold" | "expired", favorite?, favoriteCount? }.
- `layout?: "grid" | "list" | "compact"` = "grid": grid: the photo on top (result grids). list: the photo at the start, a 112px square while the card is narrow and 240px wide in imageAspect once the card is 560px wide (search results). compact: a 64px thumbnail row with no carousel and no distance (recently viewed, a seller's other listings). For loading states the file also exports ListingCardSkeleton, the placeholder with the card's exact shape (the photo block, a price bar, the title lines and a meta line): layout, variant, size, radius and imageAspect as here, lines (3), announce (true: a role="status" wrapper named by label, "Loading"; set false inside a grid that announces its own loading) and className.
- `variant?: "elevated" | "outline" | "soft" | "ghost"` = "elevated": The card surfaces: a raised panel, a hairline frame or the flat gray tile. ghost has no surface: a rounded photo with the text under it, like a fashion grid.
- `size?: "sm" | "md" | "lg"` = "md": Paddings, title and price size. sm is for two-column phone grids, lg for a featured listing.
- `radius?: "sm" | "md" | "lg"` = "md": Card corners: 12 / 16 / 24px. The photo of a list row or a ghost card takes the matching inner corner.
- `imageAspect?: "1/1" | "4/3" | "3/2" | "16/10" | "3/4"` = "4/3": The photo box in grid and list layouts (list rows stay square on phones). 3/4 suits fashion, 16/10 cars and homes.
- `maxImages?: number` = 5: Photos in the card's carousel. 1 shows a single photo with no swipe: use it for cards inside horizontal rails, which must never nest a carousel. When the listing has more photos, a camera chip shows the real total.
- `showDots?: boolean` = true: Dots under the photo (at most five, sliding along with the photo), over a soft shade so they read on any image.
- `showArrows?: boolean` = true: Previous / next buttons on the photo. They appear while the card is hovered or holds focus, on fine pointers only (phones swipe).
- `showFavorite?: boolean` = true: The heart: round glass on the photo in the grid layout, a plain icon button at the end of list and compact rows.
- `defaultFavorite?: boolean` = false: Starts saved (uncontrolled). Falls back to listing.favorite.
- `favorite?: boolean`: Controlled saved state; pair it with onFavoriteChange.
- `onFavoriteChange?: ((favorite: boolean, listing: ListingData) => void | Promise<unknown>)`: Called when the heart toggles. Return a promise to keep the heart in its new state while it is pending; a rejection rolls it back, shakes it and announces the error.
- `favoriteTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The saved heart's color. Neutral is white on photos and black / white elsewhere; danger gives the classic red heart.
- `showBadges?: boolean` = true: The promoted chip on the photo and the small badges under the text: delivery, new or used, business seller and listing.badges.
- `showAttributes?: boolean` = true: The attributes line ("2019 · 51,000 mi · Gasoline"): one line in grids, up to two in list rows.
- `showSeller?: boolean` = false: The seller line: a small avatar, the name, a check when verified and the rating. In grids it sits at the bottom, over a hairline.
- `promotedStyle?: "badge" | "ring" | "both"` = "badge": How a promoted listing stands out: a labelled chip on the photo, a 2px ring in promotedTone around the card, or both.
- `promotedTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "warning": The promoted chip and ring color. Promotion is a status, so it defaults to the amber warning tone; the chip always says it in words.
- `timeFormat?: "day" | "relative" | "date"` = "day": day: "Today at 2:32 PM", "Yesterday at 9:10 AM", then "Sep 22" this year and the full date before. relative: "2 hours ago". date: the short numeric date. The full date and time is in the tooltip. The file also exports the same text as a function, formatListingTime(value, { now, locale?, labels?, format? }): "Azi la 14:32", "Ieri la 09:10", "22 sept.", "18.09.2025"; with now null it prints the date.
- `priority?: boolean` = false: Loads the first photo eagerly with high fetch priority. Set it on the first row of a grid; every other photo loads lazily.
- `locale?: string` = "": Formats the price, distance and time ("$1,200", "4.2 km", "2:32 PM" in en-US). Empty uses the UIProvider locale, then the page.
- `href?: string` = "": Where the card leads; empty uses listing.href. Rendered through linkComponent, so a Next.js Link keeps client navigation. The playground's pretend router prints it.
- `onSelect?: (listing: ListingData) => void`: Without an href, the title becomes a button that calls it (and a click anywhere on the card does too). Without both, the card is not interactive.
- `actions?: ReactNode`: Controls at the top end of the text ("⋯" on your own listings, an edit button). They sit above the stretched link, so a click on them never opens the listing.
- `now?: number | null` = "useNow()": The reference time in ms for "Today at 14:32". Pass the page's clock (one useNow() in the grid) so the cards re-render with it; without it every card on the page shares one minute timer (not one each). null prints dates.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the title and the photos. Defaults to the one given to LinkProvider (lib/navigation), else a plain <a>.
- `labels?: Partial<ListingCardLabels>`: Copy, English by default: promoted, delivery, new, used, business, verified, reserved, sold, expired, today, yesterday, at, photo(title, i, n) (alt text), photos(n), noImage, distance(formatted), previous, next, rating(formatted), plus price (forwarded PriceLabels) and favorite (forwarded FavoriteButtonLabels). The file exports the English copy as DEFAULT_LISTING_CARD_LABELS; spread it to translate only a few keys.
- `classNames?: Partial<Record<"media" | "image" | "carousel" | "dots" | "favorite" | "body" | "title" | "price" | "attributes" | "meta" | "tags" | "seller" | "actions" | "status", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the card (the <article>), merged last.

```tsx
import { ListingCard, type ListingData } from "@/components/ui/listing-card"

const bike: ListingData = {
  id: "l01",
  title: "Trek FX 2 city bike",
  href: "/listings/l01",
  images: ["/demo/bicycle.jpg"],
  price: 280,
  currency: "USD",
  priceType: "negotiable",
  location: "Portland, Pearl District",
  postedAt: "2026-09-24T14:32:00",
  delivery: true,
  condition: "used",
  seller: { name: "Daniel Reed", verified: true, rating: 4.8 },
}

export function SearchResult({ onSave }: { onSave: (id: string, saved: boolean) => Promise<void> }) {
  return (
    <ListingCard
      listing={bike}
      size="sm"
      showSeller
      locale="en-US"
      onFavoriteChange={(saved, listing) => onSave(listing.id, saved)}
      labels={{ delivery: "Ships", price: { negotiable: "OBO" } }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/listing-card (Markdown: https://wingo-ui.com/components/listing-card.md)

#### Listing grid (`listing-grid`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add listing-grid`

The body of a results page: count, sort, view switch and filter chips over a listing grid that loads more as you scroll.

Scroll the results and the next batch loads before you reach the end, rising in with a short stagger; the "Show 24 more" button under the grid does the same by click, tap, Enter or Space, and says how many are left. The header gives the count, the sort (a menu on desktop, a bottom sheet on phones), the grid / list switch (a segmented control on wide headers, one toggle button on phones) and a bell to save the search; applied filters sit under it as chips you remove with their × (they scroll sideways on phones), with "Clear filters" at the end. On a phone the grid is two columns of small cards and the promoted block is a rail you swipe; each card is one Tab stop plus its heart. Sorting swaps the list without animation and scrolls the header back into view; switching the view cross-fades the list once. New batches, sort and view changes are announced to screen readers. While loading, skeletons with the cards' shape hold the place; with no results an empty state offers "Clear filters", and an error offers "Try again".

npm: lucide-react, motion
Wingo UI dependencies: button, empty-state, listing-card, pagination, toolbar, use-controllable-state, use-locale, use-media-query, use-persisted-state, use-scroll-state, motion, number-format, ui-config

Props:
- `items: ListingData[]`: The listings loaded so far, in order. Appending a batch animates the new cards in; replacing the set (a new search, a sort) swaps without animation.
- `renderItem?: (item: ListingData, context: { view: ListingGridView; index: number; promoted: boolean }) => ReactNode`: Replaces the default ListingCard for each item (a custom card, an ad slot every 12 items). Items of the promoted block come with promoted true and view grid.
- `cardProps?: Partial<ListingCardProps>`: Passed to every default card: the favorite handler, labels, the page's now, promotedStyle. Wins over the grid's own card settings.
- `defaultView?: "grid" | "list"` = "grid": The starting view while uncontrolled. List shows one column of list rows (a 112px photo on phones) up to 896px wide.
- `view?: "grid" | "list"`: The controlled view; pair it with onViewChange.
- `onViewChange?: (view: ListingGridView) => void`: Called when the header's switch changes the view.
- `viewPersistKey?: string` = "": Remembers the view in localStorage under this key, so a visitor who prefers the list keeps it. Empty keeps it in memory.
- `showViewSwitch?: boolean` = true: The grid / list switch in the header: a segmented control on wide headers, one toggle button on narrow ones.
- `columns?: ListingGridColumns = { base?; sm?; md?; lg?; xl? }` = "{ base: 2, md: 3, lg: 4 }": Columns by the grid's own width (base, then 640 / 768 / 1024 / 1280px and up); a missing step inherits the smaller one. CSS variables and container queries, so the server layout is already right and a grid next to a filter sidebar gets fewer columns.
- `gap?: "sm" | "md" | "lg"` = "md": Space between cards: 8px; 12px (16px from 768px of grid width); 16px (24px from 768px).
- `cardSize?: "auto" | "sm" | "md" | "lg"` = "auto": The cards' size. auto: sm while the grid is narrower than 768px (two-column phone grids), md from there; list rows stay md so the photo keeps 112px.
- `cardVariant?: "elevated" | "outline" | "soft" | "ghost"` = "elevated": The cards' surface; ghost drops it for a photo-first grid (fashion, Vinted style).
- `imageAspect?: "1/1" | "4/3" | "3/2" | "16/10" | "3/4"` = "4/3": The photo shape of every card and skeleton.
- `total?: number` = 0: The full result count ("1,240 listings" in the header, "Showing 24 of 1,240" under the button). 0 means unknown: the count and the "of N" disappear and the button still offers more while hasMore. The playground fills in its live count at 0.
- `defaultSort?: string` = "newest": The starting sort while uncontrolled, one of sortOptions' values. The playground really sorts its 1.240 results.
- `sort?: string`: The controlled sort; pair it with onSortChange.
- `onSortChange?: (sort: string) => void`: Called with the picked value. Fetch the sorted first page and replace items; the grid scrolls its header back into view.
- `sortOptions?: { value: string; label: ReactNode }[]` = "DEFAULT_LISTING_SORT_OPTIONS": The sort menu (the exported DEFAULT_LISTING_SORT_OPTIONS, map their labels to translate): newest "Newest", price-asc "Price: low to high", price-desc "Price: high to low", relevance "Most relevant". An empty array hides the sort.
- `appliedFilters?: ToolbarAppliedFilter[]`: Removable chips under the header ({ id, label }: "Portland +25 km", "Price: $200 – $3,000"). filter-panel's describeFilters builds them.
- `onRemoveFilter?: (id: string) => void`: Called by a chip's ×.
- `onClearFilters?: () => void`: Adds "Clear filters" after the chips and to the no-results state.
- `filterTrigger?: ReactNode`: The phone "Filtre (3)" button that opens your filter sheet; hide it from 768px (md:hidden) when a sidebar takes over.
- `showHeader?: boolean` = true: The header with the count, sort, view switch, save search and the chips.
- `stickyHeader?: boolean` = false: The header sticks under the top bar (top: var(--topbar-offset, 0px)) on glass, with a hairline once stuck. Scroll the playground to see it.
- `toolbarProps?: Partial<ToolbarProps>`: Anything else for the header's Toolbar: size, radius, variant (surface for a raised panel), even a search field.
- `promoted?: ListingData[]`: A "Promoted" block above the results: a swipeable rail below 768px of grid width (one photo per card on touch, so swipes never nest), the first grid row from there.
- `loading?: boolean` = false: First load: skeleton cards with the real card shape in place of the list (aria-busy on the list), and one announcement.
- `skeletonCount?: number` = 8: Skeleton cards while loading.
- `hasMore?: boolean` = false: Whether there are more listings to load. False with an onLoadMore shows "You have seen all listings". The playground turns it on while its data has more; the control forces it.
- `onLoadMore?: () => (void | Promise<unknown>)`: Loads the next batch and appends it to items. A returned promise keeps the button busy until it settles.
- `loadingMore?: boolean` = false: The next batch is loading (the footer button shows its spinner). Ignored without hasMore.
- `loadMode?: "auto" | "button"` = "auto": auto: loads when the end comes within 200px of the scroll container's edge, with the button kept as the fallback; button: on click only.
- `pageSize?: number` = 24: Listings per batch, for the button label ("Show 24 more", fewer near the end when total is known).
- `error?: ReactNode`: An error message. With no items it replaces the list ("Try again" when onRetry is set); after a failed batch it takes the footer's place under the loaded cards.
- `onRetry?: () => (void | Promise<unknown>)`: The error state's "Try again"; a returned promise keeps it busy.
- `emptyState?: ReactNode` = "EmptyState preset=\"no-results\"": Replaces the no-results state (by default "No listings match" with "Clear filters" when onClearFilters is set).
- `onSaveSearch?: () => (void | Promise<unknown>)`: Shows a bell "Save search" button in the header (icon-only on narrow headers). A returned promise keeps it busy.
- `savedSearch?: boolean` = false: The save button's saved state: "Search saved" with a ringing bell, aria-pressed.
- `animateIn?: boolean` = true: New batches rise in with a 30ms stagger (the first 12 of each batch; a fade only under reduced motion). A replaced or re-sorted set never animates.
- `locale?: string` = "": Formats the counts; defaults to the app's locale (UIProvider), then the browser's. Passed on to the cards.
- `labels?: Partial<ListingGridLabels>` = "DEFAULT_LISTING_GRID_LABELS": Every string, English by default (the exported DEFAULT_LISTING_GRID_LABELS, spread it to translate a few keys): results (n, formatted), sort, view, grid, list, promoted, loadMore (n, formatted), remaining (n, formatted), showing (shown, total), loaded (n, formatted), loading, end, saveSearch, searchSaved, clearFilters, appliedFilters, removeFilter, cancel (the phone sort sheet), emptyTitle, emptyDescription, errorTitle, retry.
- `classNames?: Partial<Record<"header" | "promoted" | "items" | "item" | "footer" | "empty", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { useState } from "react"
import { ListingGrid } from "@/components/ui/listing-grid"
import type { ListingData } from "@/components/ui/listing-card"

export function SearchResults({
  first,
  total,
  fetchPage,
}: {
  first: ListingData[]
  total: number
  fetchPage: (page: number, sort: string) => Promise<ListingData[]>
}) {
  const [items, setItems] = useState(first)
  const [sort, setSort] = useState("newest")
  const [page, setPage] = useState(1)

  return (
    <ListingGrid
      items={items}
      total={total}
      sort={sort}
      onSortChange={async (next) => {
        setSort(next)
        setPage(1)
        setItems(await fetchPage(1, next))
      }}
      hasMore={items.length < total}
      onLoadMore={async () => {
        const next = await fetchPage(page + 1, sort)
        setPage(page + 1)
        setItems((current) => [...current, ...next])
      }}
      viewPersistKey="listings-view"
      locale="en-US"
      sortOptions={[
        { value: "newest", label: "Newest" },
        { value: "price-asc", label: "Price: low to high" },
        { value: "price-desc", label: "Price: high to low" },
        { value: "relevance", label: "Most relevant" },
      ]}
      labels={{ end: "That's every listing" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/listing-grid (Markdown: https://wingo-ui.com/components/listing-grid.md)

#### Order tracker (`order-tracker`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add order-tracker`

Where an order is: number, status, arrival window, milestones, a route with the courier, the tracking number, the shipment history and the total.

Read it top to bottom: the order number (with a copy button), a status badge, when it arrives ("Arrives today between 5:00 PM and 7:00 PM"), five milestones, an illustrated route where the travelled part draws in when it scrolls into view and the courier dot rides its end, then glides on to the next point when the status changes (it pulses while out for delivery, never under reduced motion or off screen). Tap the phone button to call the courier, the copy buttons to copy the order number, the tracking number or the locker PIN, and the tracking link to open the courier's page in a new tab. "Show full history" unfolds the older events (each with its day and time) one after another; press it again to fold them. Tab reaches every button and link once, Enter and Space press them. On a phone the milestones become a "Step 4 of 5" header with a bar, the call button is 44px and the actions stack full width; the page variant puts the history beside the details from about 768px of width.

npm: lucide-react, motion
Wingo UI dependencies: alert, avatar, badge, button, copy-button, price, steps, timeline, use-locale, commerce, date-utils, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `orderNumber: string` = "#1042": The order number in the heading ("Order #1042") and what the copy button copies.
- `status?: "placed" | "confirmed" | "shipped" | "out-for-delivery" | "ready-for-pickup" | "delivered" | "failed" | "cancelled" | "returned"` = "shipped": Drives the badge and its color, the milestones (when not given), the arrival line and where the courier sits on the route. Ended orders (delivered, failed, cancelled, returned) paint in their status color; an unknown value shows as is in a neutral badge.
- `placedAt?: TimeInput`: When the order was placed, under the number ("Placed 22.09.2026, 10:14").
- `eta?: { from: TimeInput; to?: TimeInput } | string`: The arrival window, written relative to now ("Arrives today between 17:00 and 19:00", "tomorrow", a weekday, then the date), or free text. A window that has passed while the order still moves turns the badge into "Delayed".
- `etaNote?: ReactNode` = "": A muted line under the arrival ("Handed over in person", "The courier calls 15 minutes before").
- `deliveredAt?: TimeInput`: With status delivered the arrival line reads "Delivered today at 11:24".
- `milestones?: OrderMilestone[] ({ id; label: ReactNode; status?: "complete" | "current" | "upcoming" | "error"; time?: TimeInput })`: Default: Placed, Confirmed, Shipped, Out for delivery, Delivered (Ready for pickup and Picked up for locker orders), each dated from the first matching event and its state derived from status. A failed or cancelled order shows the error on the step where it stopped.
- `events?: OrderEvent[] ({ id; title: ReactNode; description?: ReactNode; location?: string; time: TimeInput; status?: OrderStatus; icon?: ReactNode })` = "[]": The shipment history, newest first, each event with its day ("Today", "Yesterday", a weekday, then the date) and time. Each status brings its icon; the newest event takes its status color. Empty hides the section.
- `historyLimit?: number` = 3: Events shown before the Show full history button.
- `courier?: OrderCourier ({ name; logo?: ReactNode; trackingNumber?; trackingUrl?; phone?; driver?: { name; avatar?; phone? } })`: The courier tile: logo or a truck, the driver with an avatar, a call button (tel:, until the parcel is delivered or returned), the tracking number with a copy button and the tracking link (new tab). Hidden while none is known and when the order is cancelled.
- `pickup?: { name: string; address: string; code?: string; until?: TimeInput }`: A locker or store pickup. Switches the milestones to Ready for pickup / Picked up and, while ready for pickup, replaces the courier with the locker, the PIN (large, with a copy button) and the deadline.
- `items?: OrderTrackerItem[] ({ id; title: string; image?: string; quantity: number; price: number })`: Overlapping thumbnails, "4 items", the titles and the total.
- `total?: number` = 0: The total shown by the items. 0 sums the items (price times quantity) through lib/commerce.
- `map?: ReactNode | false`: Your own map (an embed, an image) in place of the illustration, or false to hide it. The default illustration is decorative (aria-hidden) with a caption.
- `animated?: boolean` = true: false draws the route at once and stops every pulse (the courier dot, the badge), for thumbnails and static pages. Reduced motion does the same on its own.
- `showMap?: boolean` = true: The route illustration (or your map). Not shown for cancelled and returned orders.
- `showHistory?: boolean` = true: The shipment history section.
- `showItems?: boolean` = true: The items row with the total.
- `notice?: ReactNode | { title?: ReactNode; description?: ReactNode; actions?: ReactNode; tone?: Tone }`: An inline alert under the arrival: the reason of a failed attempt and the next try, a refund note. A failed order without one shows the description of its newest failed event.
- `variant?: "card" | "page"` = "card": card: everything in one panel. page: sections for a full page (status, map, courier and items, with the history in a column beside them once the tracker is about 768px wide).
- `size?: "sm" | "md"` = "md": sm is the compact card of an orders list: the header, the arrival line and the milestones.
- `actions?: ReactNode`: Buttons at the end (contact, report a problem, return). They stack full width on a phone.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The milestones, the arrival icon and the route while the order is in progress (a failed or cancelled order keeps it on the milestones, where the stopped step shows in amber for a failed attempt and red for a cancellation). Ended orders paint the rest in the exported ORDER_STATUS_TONES instead (placed and confirmed neutral, shipped, out for delivery and ready for pickup info, delivered success, failed warning, cancelled danger, returned neutral), so the end state always reads the same; reuse it for your own order badges.
- `color?: string` = "": Any CSS color; replaces the tone while the order is in progress. Leave empty to use the tone.
- `now?: number | Date | null`: The reference time for "today", the delay check and the day headings. Default: the live clock (useNow), null while hydrating.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders the tracking link; default: the LinkProvider's link, else <a>.
- `currency?: string` = "USD": ISO 4217 code of the total.
- `locale?: string` = "": Intl locale for dates, times, counts and the total. Empty uses the UIProvider locale, then the page.
- `labels?: Partial<OrderTrackerLabels>`: Every string, English by default (exported as DEFAULT_ORDER_TRACKER_LABELS, spread it under your own): order (n) => "Order #1042", placedOn, status per OrderStatus, delayed, milestones (placed, confirmed, shipped, outForDelivery, delivered, readyForPickup, pickedUp), steps (Steps labels: progress, step, next), eta, window, at, delivered, trackingNumber, copyOrderNumber, copyTrackingNumber, copyPickupCode, copied, track, newTab, callCourier, pickupCode, pickupUntil, history, showAll, showLess, items (count, formatted), total, mapLabel.
- `classNames?: Partial<Record<"header" | "status" | "eta" | "milestones" | "map" | "courier" | "pickup" | "history" | "items" | "actions", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root section, merged last.

```tsx
import { Button } from "@/components/ui/button"
import { OrderTracker, type OrderEvent } from "@/components/ui/order-tracker"

const events: OrderEvent[] = [
  { id: "e3", title: "Out for delivery", description: "Driver Michael Brooks", time: "2026-09-24T08:12:00", status: "out-for-delivery" },
  { id: "e2", title: "Handed to the courier", location: "Newark, NJ", time: "2026-09-22T15:40:00", status: "shipped" },
  { id: "e1", title: "Order placed", time: "2026-09-22T10:14:00", status: "placed" },
]

export function Order() {
  return (
    <OrderTracker
      orderNumber="#1042"
      status="out-for-delivery"
      placedAt="2026-09-22T10:14:00"
      eta={{ from: "2026-09-24T17:00:00", to: "2026-09-24T19:00:00" }}
      events={events}
      courier={{
        name: "FedEx",
        trackingNumber: "2345 6789 012",
        trackingUrl: "https://www.fedex.com/fedextrack/",
        driver: { name: "Michael Brooks", phone: "(212) 555-0147" },
      }}
      items={[{ id: "p1", title: "City bike", quantity: 1, price: 1199 }]}
      currency="USD"
      locale="en-US"
      labels={{ order: (n) => `Order ${n}`, eta: (w) => `Arrives ${w}` }}
      actions={<Button variant="soft">Contact support</Button>}
    />
  )
}
```

Docs: https://wingo-ui.com/components/order-tracker (Markdown: https://wingo-ui.com/components/order-tracker.md)

#### Price (`price`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add price`

A price written the way a shop writes it: a smaller currency, a struck old price with its discount chip, Negotiable, Free and Swap.

A price is text: it reads in order ("$1,200, Negotiable", "$499, Was $649, 23% off") and nothing in it takes focus, a tap or a key. When the amount changes it fades to the new one, or rolls its digits like an odometer with animate="roll"; with announce a screen reader hears the new total once, never on mount. Under reduced motion the new value simply appears. On a narrow phone the amount never breaks; the old price, the chip and the captions wrap below it.

npm: motion
Wingo UI dependencies: animated-counter, badge, use-locale, commerce, motion, number-format, tones, ui-config

Props:
- `price: number | null` = 1200: The amount in major units (dollars, not cents). null (or NaN) renders labels.onRequest ("Price on request").
- `currency?: string` = "USD": ISO 4217 code, printed with its narrow symbol: "$", "€", "lei". An unknown code prints the number with the code ("1,200 XYZ").
- `locale?: string` = "": Intl locale for grouping, decimals and where the currency goes ("$1,200" in en-US, "1.200 €" in de-DE). Empty uses the UIProvider locale, then the page.
- `fractionDigits?: "auto" | "0" | "2" | number` = "auto": auto prints whole amounts without decimals ("$1,200") and the currency's digits otherwise ("$1,284.90"); a number (or "0" / "2") forces that many.
- `compareAtPrice?: number | null` = 0: The old price. Shown struck through, with the sale color and the discount chip, only when it is above price (and above 0); 0 or null means none.
- `priceType?: "fixed" | "negotiable" | "free" | "exchange" | "on-request"` = "fixed": negotiable adds labels.negotiable after the amount; free, exchange and on-request replace the amount with their label (free in the success color).
- `priceSuffix?: string` = "": Muted text after the currency: "/mo", "/night", "/each".
- `unit?: { quantity: number; unit: string }`: Adds the price per unit to the caption: $489,000 for 580 sq ft prints "$843/sq ft".
- `caption?: ReactNode` = "": One muted line under the price ("Tax included", "+ $9.99 shipping"), after the unit price when both are set.
- `showDiscount?: boolean` = true: The "-25 %" chip next to the old price when on sale. Screen readers hear labels.discount instead of the chip.
- `saleTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "danger": The sale amount's color and the chip's tone. A markdown is a status, so it defaults to danger; the two prices still say it without color.
- `size?: "sm" | "md" | "lg" | "xl"` = "md": 14 / 17 / 22 / 32px amounts (xl grows to 40px from 768px): a cart line, a card, a detail page, a pricing hero. The classes are exported as PRICE_SIZES for bars and tables that print a price without the component.
- `currencyStyle?: "small" | "inline"` = "small": small sets the currency at 0.72em of the amount, in the locale's order; inline prints it at the same size.
- `layout?: "inline" | "stacked"` = "inline": inline keeps everything on one line and wraps between parts; stacked puts the old price, the chip and Negotiable on a second line (cards, plans).
- `animate?: "none" | "fade" | "roll"` = "fade": How a new amount appears: a quick keyed fade, digits rolling like an odometer (totals, plans), or nothing. Reduced motion always swaps instantly.
- `announce?: boolean` = false: Reads a changed price out politely through a live region (cart and checkout totals). Never on mount.
- `labels?: Partial<PriceLabels>`: Copy: negotiable "Negotiable", free "Free", exchange "Swap", onRequest "Price on request", compare "Was" (sr-only before the old price), discount (percent) => "25% off" (sr-only when the chip shows). Defaults in DEFAULT_PRICE_LABELS.
- `classNames?: Partial<Record<"current" | "amount" | "currency" | "suffix" | "label" | "compare" | "discount" | "negotiable" | "caption", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root span, merged last. Other span props (id, aria-*, data-*) spread onto it.

```tsx
import { Price } from "@/components/ui/price"

export function ListingPrice() {
  return (
    <div className="flex flex-col gap-3">
      <Price price={320} priceType="negotiable" labels={{ negotiable: "Or best offer" }} />
      <Price
        price={499}
        compareAtPrice={649}
        size="lg"
        layout="stacked"
        labels={{ compare: "Was", discount: (percent) => `Save ${percent}%` }}
      />
      <Price price={489000} unit={{ quantity: 580, unit: "sq ft" }} />
      <Price price={1900} priceSuffix="/mo" caption="Utilities not included" />
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/price (Markdown: https://wingo-ui.com/components/price.md)

#### Price range (`price-range`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add price-range`

The price filter: a histogram of the results over a two thumb slider, min and max inputs that stay in sync, preset chips and a live count.

Drag either thumb along the histogram: the bars inside the range light up, the thumb shows its price in a bubble and the inputs follow, snapped to a round step. Drag a thumb all the way to an end to open that bound (the input empties to its Min or Max placeholder). On a phone the thumbs have 44px hit areas and a vertical swipe over the slider still scrolls the sheet it sits in. Type in Min or Max for an exact amount, even one beyond the slider's ends (the thumb stays pinned at the end); Enter or leaving both fields applies it, and a min above the max swaps. Tap a preset chip to set both ends at once, tap it again to clear the filter; on phones the chips scroll sideways. Keyboard: Tab to a thumb, Left / Right or Up / Down move by one step, Page Up / Page Down (or Shift with an arrow) by ten, Home and End jump the thumb to the start or the end of the track but never past the other thumb (Home on the minimum and End on the maximum open that bound); arrows move between preset chips and Space selects one. The count under the filter changes with a short fade and is read once by screen readers. Under reduced motion the bars appear without growing.

npm: motion
Wingo UI dependencies: slider, currency-input, tag, field, commerce, number-format, use-locale, use-controllable-state, motion, tones, ui-config

Props:
- `value?: PriceRangeValue`: The controlled range, [min, max] in major units (dollars). null is an open end: [null, 3000] means under $3,000. A value outside the slider pins its thumb to the end while the inputs keep the real number. The type is exported as PriceRangeValue ([min: number | null, max: number | null]), shared with filter-panel.
- `defaultValue?: PriceRangeValue` = "[null, null]": The starting range while uncontrolled. The default leaves both ends open.
- `onValueChange?: (value: PriceRangeValue) => void`: Fires while dragging (at most once per frame), while typing and on presets. Use it for the live readout.
- `onValueCommit?: (value: PriceRangeValue) => void`: Fires when a thumb is released or moved by a key, when an input is left or confirmed with Enter, and when a preset is tapped. Fetch results here. A min above the max arrives swapped.
- `min?: number` = 0: The slider's low end. A thumb dragged here opens the lower bound.
- `max?: number` = 10000: The slider's high end. A thumb dragged here opens the upper bound; prices above it count in the last bar. Equal to min it becomes a single price with locked thumbs.
- `step?: number` = 0: The price step thumbs, arrows and inputs snap to. 0 picks a round one for the range (1, 5, 10, 50, 100, 500...), about a hundredth of it; on a log scale it grows with the price. Currencies without decimals always step in whole units.
- `scale?: "linear" | "log"` = "linear": log spreads cheap prices out and squeezes the expensive tail, for wide ranges like real estate ($100 to $500,000). The histogram's buckets follow the same scale.
- `prices?: readonly number[]`: Raw prices of the results, counted into the histogram. The same counting is exported as binPrices(prices, { min, max, bins, scale }) -> number[] (equal-width or log-spaced buckets; prices outside min..max count in the first or last one), for sending histogram facets from the server.
- `histogram?: readonly number[]`: Precomputed bucket counts (server facets), one per equal-width bucket of the track (log-spaced on a log scale). Wins over prices.
- `bins?: number` = 24: How many bars prices are binned into. Empty buckets leave a gap.
- `showHistogram?: boolean` = true: The bars above the slider. Without prices or a histogram there is nothing to draw and it stays hidden.
- `showInputs?: boolean` = true: The Min and Max currency inputs under the slider.
- `presets?: PriceRangePreset[]`: Chips that set both ends at once: PriceRangePreset = { label?: ReactNode; min: number | null; max: number | null }, e.g. { min: null, max: 500 }. A chip without a label reads labels.under / between / over ("Under $500", "$500 to $1,500"). It stays selected while the value matches it.
- `count?: number` = 0: Results in the current range, shown under the filter as labels.results ("832 results") in a polite live region. 0 hides it.
- `currency?: string` = "USD": ISO 4217 code for the inputs, the bubbles and the chips: "$", "€", "lei".
- `locale?: string` = "": Formats every price ("$1,500" in en-US, "1.500 $" in de-DE). Empty uses UIProvider, then the page.
- `label?: ReactNode` = "": The field label above the histogram; it names the whole group.
- `description?: ReactNode` = "": Helper text under the filter, like "per month".
- `error?: ReactNode` = "": Replaces the description and marks both inputs invalid.
- `size?: "sm" | "md" | "lg"` = "md": Scales the slider (4 / 6 / 8px track), the histogram (40 / 48 / 56px), the inputs (32 / 40 / 48px, 44px on touch for md) and the chips together.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Colors the slider's range, the lit bars (at 55%) and the selected chip. neutral is black in light mode and white in dark mode.
- `color?: string` = "": Any CSS color; replaces the tone everywhere. Leave empty to use the tone.
- `disabled?: boolean` = false: Dims the filter and blocks the thumbs, inputs and chips, e.g. while results load.
- `labels?: Partial<PriceRangeLabels>`: Every string, English by default: min "Min", max "Max", any "Any", thumbMin "Minimum price", thumbMax "Maximum price", under (p) => `Under ${p}`, over (p) => `Over ${p}`, between (a, b) => `${a} to ${b}`, results (n, formatted) => `${formatted} results`, presets "Price presets". Export DEFAULT_PRICE_RANGE_LABELS.
- `classNames?: Partial<Record<"histogram" | "bar" | "slider" | "inputs" | "input" | "presets" | "count", string>>`: Extra classes for the inner parts. className stays on the root (the field wrapper when a label, description or error is set).

```tsx
import { useState } from "react"
import { PriceRange, type PriceRangeValue } from "@/components/ui/price-range"

const PRICES = [320, 450, 890, 1150, 1200, 1490, 1650, 2100, 2450, 2900, 3400, 4300, 5200, 7800]

export function PriceFilter({ onApply }: { onApply: (value: PriceRangeValue) => void }) {
  const [value, setValue] = useState<PriceRangeValue>([null, 3000])
  const count = PRICES.filter((p) => (value[0] === null || p >= value[0]) && (value[1] === null || p <= value[1])).length
  return (
    <PriceRange
      label="Price"
      value={value}
      onValueChange={setValue}
      onValueCommit={onApply}
      min={0}
      max={8000}
      prices={PRICES}
      presets={[
        { min: null, max: 500 },
        { min: 500, max: 1500 },
        { min: 1500, max: null },
      ]}
      count={count}
      labels={{
        results: (n, formatted) => (n === 1 ? "1 listing" : `${formatted} listings`),
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/price-range (Markdown: https://wingo-ui.com/components/price-range.md)

#### Pricing table (`pricing-table`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add pricing-table`

Plans side by side with a Monthly / Yearly switch whose prices roll, a featured plan, feature lists and a full comparison table.

Flip Monthly / Yearly (tap, drag the thumb, or arrow keys once it has focus) and every price rolls to its new value while the billed line cross-fades; a screen reader hears the featured plan's new price once. Each plan's button runs its action and shows a spinner while a returned promise is pending; the current plan shows a check instead. Hover, focus or click an (i) for its hint, or tap it on a phone (tap it again, tap outside or press Escape to close); a screen reader hears it as More info plus the feature it explains. On a phone the plans are swipeable cards that start at the featured one (drag, tap a dot, or Left / Right with focus inside), and the comparison becomes a plan switcher above one column of rows, ending in the picked plan's button. On a laptop the comparison is a real table whose header of plan names and buttons sticks while you scroll.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, carousel, price, segmented-control, table, tooltip, use-controllable-state, use-locale, commerce, motion, tones, ui-config

Props:
- `plans: PricingPlan[]`: The plans, in order. PricingPlan = { id; name; description?; price: number | { monthly; yearly } | null; priceSuffix?; badge?; featured?; current?; features?: PricingFeature[]; featuresTitle?; cta?: { label; href?; onClick?: () => void | Promise<unknown> }; note?; disabled? }. price 0 is free, null is custom (the button defaults to labels.contact). PricingFeature = string | { label; included?; hint? }.
- `comparison?: PricingComparisonGroup[]`: The comparison below the plans, in groups: { label; rows: { label; hint?; values: Record<planId, boolean | ReactNode> }[] }. true is a check, false a dash, anything else prints as text.
- `defaultPeriod?: "monthly" | "yearly"` = "monthly": The billing period shown first while uncontrolled.
- `period?: "monthly" | "yearly"`: The billing period, controlled. Respected even with the toggle hidden.
- `onPeriodChange?: (period: BillingPeriod) => void`: Fires when the toggle changes the period.
- `showToggle?: boolean` = true: Shows the Monthly / Yearly switch. It hides by itself when no plan has a yearly price.
- `yearlyDisplay?: "per-month" | "per-year"` = "per-month": How a yearly price reads: per-month shows the monthly equivalent with "Billed $90 yearly" under it; per-year shows the yearly amount with what it saves.
- `showComparison?: boolean` = true: Shows the comparison table when comparison is given.
- `featuredStyle?: "raised" | "outline" | "inverted"` = "raised": How the featured plan stands out: raised floats higher and is 8px taller in the wide layout, outline draws a ring in the tone, inverted fills the card with the tone.
- `columns?: number` = 0: Plans side by side in the wide layout. 0 is the plan count up to 4. More plans than columns scroll sideways with a peek of the next one.
- `mobileLayout?: "carousel" | "stack"` = "carousel": Below 768px of width: swipeable cards that start at the featured plan, with dots, or the cards stacked one under the other.
- `animatePrice?: boolean` = true: Prices roll their digits to the new value on a period change. Reduced motion shows the new value at once.
- `size?: "sm" | "md" | "lg"` = "md": Card padding, type, price size and button height (sm: 40px buttons, md and lg: 48px).
- `radius?: "md" | "lg"` = "lg": Plan card corners: md 16px, lg 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The featured plan's badge, button, ring or fill, and the feature checks (neutral keeps them in the text color, other tones turn them green).
- `color?: string` = "": Any CSS color for the featured plan. Replaces the tone; text on it turns black or white by lightness.
- `savingsTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": The tone of the "-20 %" badge in the yearly option (a saving is a status, so it is green by default).
- `currency?: string` = "USD": ISO 4217 code for every price: "$", "€", "lei".
- `locale?: string` = "": Intl locale for prices and the savings badge ("$49", "12 €"). Empty uses the UIProvider locale, then the page.
- `labels?: Partial<PricingTableLabels>`: Every string, English by default (DEFAULT_PRICING_TABLE_LABELS): monthly, yearly, save (percent, formatted), perMonth "/mo", perYear "/yr", perMonthSpoken, perYearSpoken, billedYearly (amount), yearlySaving (amount), free, custom, contact, current, popular, included, notIncluded, compare, choose (plan), hint, period, plans, feature, slide (index, total) and showPlan (plan) for the phone carousel.
- `classNames?: Partial<Record<"header" | "toggle" | "plans" | "plan" | "price" | "cta" | "features" | "comparison", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

```tsx
import { PricingTable, type PricingPlan } from "@/components/ui/pricing-table"

const plans: PricingPlan[] = [
  { id: "start", name: "Start", price: 0, features: ["5 active listings", "Basic stats"] },
  {
    id: "pro",
    name: "Pro",
    price: { monthly: 9, yearly: 90 },
    featured: true,
    badge: "Most popular",
    features: ["50 active listings", "3 promotions a month", "Priority support"],
    note: "14 days free, no card",
  },
  { id: "business", name: "Business", price: { monthly: 29, yearly: 290 }, features: ["Unlimited listings"] },
]

export function SellerPlans() {
  return (
    <PricingTable
      plans={plans}
      currency="USD"
      tone="brand"
      labels={{ save: (_, formatted) => formatted, choose: (plan) => `Get ${plan}` }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/pricing-table (Markdown: https://wingo-ui.com/components/pricing-table.md)

#### Product gallery (`product-gallery`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add product-gallery`

The photo gallery of a detail page: a swipeable stage that zooms under the mouse, thumbnails and a full-screen viewer.

With a mouse, rest on the photo and it grows to the zoom scale on a smooth spring, panning with the cursor so the spot under it stays put; the lens mode shows a round magnifier that follows the cursor instead (it stays over the photo, never the letterbox bars). Leave and it settles back; start dragging the photo sideways and the zoom lets go so the carousel can move. Arrows fade in on hover or focus, the expand button sits bottom right and a hint chip says what to do. Click the photo (zoomed or not) or the expand button and the viewer opens, the photo growing out of the stage; swipe or page there and the stage follows, so the viewer closes back into the photo you are on. Thumbnails sit in a rail beside the stage or in a strip below it (a narrow column with a mouse gets the strip), the current one ringed; the last visible one reads +N and opens the viewer there. On a phone the stage is full width: swipe between photos (vertical scrolling always wins), read the 3 / 12 counter or the dots, tap to open the viewer and pinch there; there is no hover zoom and no thumbnail rail, and the favorite and share buttons over the photo keep 44px targets. Keys: Tab to the stage, Left / Right change the photo, Home / End jump to the first / last, Enter or Space open the viewer and focus comes back to the stage when it closes; the thumbnails are one Tab stop where the arrow keys and Home / End move focus and Enter or Space show that photo. Under reduced motion the zoom follows the cursor without the spring and the viewer fades.

npm: lucide-react, motion
Wingo UI dependencies: button, carousel, image-lightbox, use-controllable-state, use-media-query, motion, ui-config

Props:
- `images: ProductGalleryImage[]`: The photos: { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail? } (LightboxImage plus a thumbnail file). width and height let the viewer take its final shape before the file loads; captions show in the viewer.
- `defaultIndex?: number` = 0: The photo on the stage at first. Out of range values clamp to the first or last photo.
- `index?: number`: Controlled photo index. The stage, the thumbnails and the viewer all follow it.
- `onIndexChange?: (index: number) => void`: Called when a swipe, an arrow, a key, a thumbnail or the viewer changes the photo.
- `defaultOpen?: boolean` = false: Starts with the full-screen viewer open at the current photo.
- `open?: boolean`: Controlled viewer state.
- `onOpenChange?: (open: boolean) => void`: Called when the viewer opens (a click, a tap, Enter, the expand button, +N) or closes.
- `thumbnails?: "start" | "bottom" | "none"` = "start": start: a vertical rail beside the stage, exactly as tall as it (it scrolls when the photos do not fit), once the gallery is at least 512px wide (a container query); in a narrower column a mouse gets it as a strip under the stage. bottom: a strip under the stage. On touch screens below 512px the indicator replaces both.
- `aspect?: "1/1" | "4/3" | "3/4" | "16/10"` = "4/3": The stage's shape. Photos are cropped (cover) or letterboxed (contain) into it.
- `fit?: "cover" | "contain"` = "cover": cover fills the stage and crops; contain shows the whole photo on white in light mode and on the tinted stage in dark mode, for product shots.
- `zoom?: "hover" | "lens" | "none"` = "hover": Mouse pointers only. hover scales the photo in place and pans with the cursor; lens shows a round magnifier. The zoom never goes past twice a photo's natural width, and touch screens use the viewer's pinch instead.
- `zoomScale?: number` = 2: How far the hover zoom or the lens magnifies.
- `lightbox?: boolean` = true: A click, a tap or Enter opens the full-screen ImageLightbox at that photo, growing out of the stage. Off: no viewer, no expand button.
- `indicator?: "counter" | "dots" | "none"` = "counter": The position cue where thumbnails do not show (touch screens below 512px of gallery width, or thumbnails="none"): a "3 / 12" chip at the bottom end or dots at the bottom center.
- `showArrows?: boolean` = true: Previous / next buttons over the stage for mouse and trackpad users, shown on hover or keyboard focus; touch screens swipe instead.
- `loop?: boolean` = false: Wraps from the last photo to the first, on the stage and in the viewer.
- `maxThumbnails?: number` = 6: How many thumbnails show. When there are more photos the last visible one reads "+N" and opens the viewer at that photo.
- `radius?: "none" | "sm" | "md" | "lg"` = "md": The stage's corners: 0 / 12 / 16 / 24px. Thumbnails follow one step smaller.
- `bleedOnMobile?: boolean` = false: Below 768px the stage drops its corners, for detail pages that run the gallery edge to edge.
- `badges?: ReactNode`: Top start, over the photo: a "Promovat" badge, the condition.
- `actions?: ReactNode`: Top end, over the photo: e.g. <FavoriteButton variant="overlay" /> and a share button (keep them 44px on touch).
- `lightboxProps?: Partial<ImageLightboxProps>`: Anything else for the viewer (labels, download, share, showThumbnails, maxZoom...). images, open and index belong to the gallery.
- `labels?: Partial<ProductGalleryLabels>`: gallery "Photos", thumbnails "Photo thumbnails", open "Open full screen", thumbnail (i, n) => "Show photo i of n", more (n) => "+n", counter (i, n) => "i / n", zoomHint "Hover to zoom, click to open", noImage "No photos", previous "Previous photo", next "Next photo", slide (i, n) => "i of n".
- `classNames?: Partial<Record<"thumbnails" | "thumbnail" | "stage" | "slide" | "image" | "lens" | "counter" | "dots" | "hint" | "expand" | "badges" | "actions", string>>`: Extra classes for the inner parts.

```tsx
import { ProductGallery, type ProductGalleryImage } from "@/components/ui/product-gallery"
import { FavoriteButton } from "@/components/ui/favorite-button"
import { Badge } from "@/components/ui/badge"
import { Sparkles } from "lucide-react"

const images: ProductGalleryImage[] = [
  { src: "/demo/apartment.jpg", width: 960, height: 600, alt: "Bright living room", caption: "Bright living room, 24 m²" },
  { src: "/demo/sofa.jpg", width: 960, height: 600, alt: "Green velvet sofa", caption: "The lounge corner" },
  { src: "/demo/city.jpg", width: 960, height: 600, alt: "View over the boulevard", caption: "View from the balcony" },
]

export function ListingPhotos() {
  return (
    <ProductGallery
      images={images}
      bleedOnMobile
      badges={<Badge variant="soft" tone="warning" leftIcon={<Sparkles />}>Promovat</Badge>}
      actions={<FavoriteButton variant="overlay" />}
      labels={{ gallery: "Listing photos", open: "Open full screen", noImage: "No photos yet" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/product-gallery (Markdown: https://wingo-ui.com/components/product-gallery.md)

#### Quantity stepper (`quantity-stepper`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add quantity-stepper`

The minus, value, plus control of carts and product pages, with stock hints, hold to repeat, rolling digits and an Add to cart morph.

Tap or click minus and plus to change the quantity; the new number rolls in from below when it grows and from above when it shrinks. Hold a button and it repeats after 400ms, speeding up, and stops at the limit; on a phone a finger that starts to scroll never changes the value. Pressing past a limit shakes the control (and buzzes on a phone), and at the maximum a line under it says why. With removable, minus turns into a trash button at the minimum; with addToCart the control starts as an Add to cart button that morphs into the stepper and collapses back from the first step. Keyboard: Tab reaches the value (one stop), Up and Down step, Page Up and Page Down move 10 steps, Home and End jump to the minimum and maximum, Delete removes the line at the minimum when removable. With editable, type a number and press Enter or leave the field (Escape drops what was typed); it is snapped to the step and clamped, and pressing plus or minus right after typing steps from the typed number. While the cart syncs a spinner replaces the digits, and a failed save rolls back with a message.

npm: motion, lucide-react
Wingo UI dependencies: button, spinner, use-controllable-state, use-locale, haptics, motion, number-format, tones, ui-config

Props:
- `defaultValue?: number` = 1: The starting quantity while uncontrolled. Without it, an addToCart stepper starts at 0 (the button).
- `value?: number`: The controlled quantity. A value outside min and max is shown clamped and never reported back.
- `onValueChange?: (value: number) => (void | Promise<unknown>)`: Called with every new quantity. Return a promise (a cart sync) to show the loading state until it settles; a rejection reverts the value and announces labels.error. Controlled: set the value when the promise resolves.
- `min?: number` = 1: The lowest quantity. With addToCart it is the first step after the button (at least step), and 0 collapses back to the button.
- `max?: number` = 99: The highest quantity, capped by stock when stock is tracked. A max below min becomes min.
- `step?: number` = 1: How much one press changes. Decimals work (0.5 kg) without float noise; typed values snap to it.
- `stock?: number` = 0: Units left. Caps max and shows labels.lowStock at or below lowStockThreshold. A quantity above it is never changed silently: the hint says so and plus stops. 0 means not tracked.
- `lowStockThreshold?: number` = 5: The stock at or below which the low stock line shows.
- `removable?: boolean` = false: At the minimum, minus becomes a red trash button that calls onRemove (Delete on the keyboard does the same).
- `onRemove?: () => void`: Called by the trash button. The stepper keeps its value; remove the line (and offer an undo) in your cart.
- `addToCart?: boolean` = false: At 0 the control is an Add to cart button in the tone. Pressing it sets the first step and morphs into the stepper; minus at the first step collapses it back.
- `editable?: boolean` = false: The value is a text field for bulk quantities: type 120 and press Enter. Clamped and snapped on Enter and blur, numeric keyboard on phones.
- `holdToRepeat?: boolean` = true: Holding a button repeats after 400ms, every 100ms speeding up to every 30ms.
- `suffix?: string` = "": A unit after the number, like "buc." or "kg". Also read by screen readers.
- `size?: "sm" | "md" | "lg"` = "md": Height 32 / 40 / 48px with square buttons. md grows to 44px on touch; sm keeps its look with a 44px hit area.
- `variant?: "soft" | "outline" | "ghost"` = "soft": The field box look: a filled well, a hairline outline, or nothing until hovered.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "full": Corner shape, from the button's per-size map; full is a pill.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of the Add to cart button. Brand orange is opt-in for the one hero action of a product page.
- `color?: string` = "": Any CSS color for the Add to cart button; replaces the tone.
- `loading?: boolean` = false: The cart is syncing: the buttons stop, a spinner takes the digits' place and the width holds still.
- `disabled?: boolean` = false: Dims the control and blocks every input.
- `haptics?: boolean` = true: On phones: a "selection" tick per step (every third while a hold accelerates) and a "warning" buzz at a limit. Never from a mouse.
- `locale?: string` = "": Intl locale for the digits ("1.5" in en-US, "1,5" in de-DE). Empty uses the UIProvider locale, then the page.
- `labels?: Partial<QuantityStepperLabels>`: Every string: group "Quantity", increment "Increase quantity", decrement "Decrease quantity", remove "Remove", add "Add to cart", lowStock (count, formatted) => "Only 3 left", overStock (count, formatted) => "Only 3 in stock", max (count, formatted) => "Max. 3 per order", maxReached "Maximum reached", error "Could not update the quantity". DEFAULT_QUANTITY_STEPPER_LABELS exports them.
- `classNames?: Partial<Record<"box" | "decrement" | "increment" | "remove" | "value" | "digits" | "suffix" | "add" | "hint", string>>`: Extra classes for the inner parts. className goes on the root, which stacks the box and the hint line.
- `aria-label?: string` = "": Names the group and the value, e.g. "Quantity, iPhone 14 case" in a cart with many lines. Empty uses labels.group.

```tsx
import { QuantityStepper } from "@/components/ui/quantity-stepper"

export function CartLine({ quantity, onQuantity, onRemove }: { quantity: number; onQuantity: (value: number) => Promise<void>; onRemove: () => void }) {
  return (
    <QuantityStepper
      value={quantity}
      onValueChange={onQuantity}
      removable
      onRemove={onRemove}
      stock={3}
      aria-label="Quantity, iPhone 14 case"
      labels={{
        remove: "Remove from bag",
        lowStock: (_, n) => `Hurry, only ${n} left`,
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/quantity-stepper (Markdown: https://wingo-ui.com/components/quantity-stepper.md)

#### Reviews (`reviews`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add reviews`

Product and seller reviews: the average, stars and a 5 to 1 breakdown that filters, then sortable reviews with photos, replies and votes.

The summary shows the average, its stars and how many reviews there are; the five bars grow in one after another the first time they scroll into view. Tap or click a bar to see only that many stars (it stays highlighted, the other bars dim), tap it again to see all; the chips above the list do the same and add "With photos", and the list reflows with the reviews sliding into place. Sort opens a menu on a laptop and a bottom sheet on a phone. Long reviews stop after a few lines with "Show more", which springs the rest open. Tap a photo to open it full screen (swipe between photos, pinch or double tap to zoom, swipe down or press Escape to close, and focus returns to the photo). "Helpful" votes at once and rolls back if saving fails; the count moves by one with it. On a wide container the summary sits in a sticky column beside the list; below that it stacks above. Keyboard: Tab through the bars, the sort, the chips (arrow keys move between chips), each review's photos, Show more, Helpful and Report; Space or Enter toggles a bar, a chip or Helpful and opens a photo; in the photo viewer Left and Right change the photo and Escape closes it; in the sort menu the arrow keys pick an order and Enter confirms. Every bar, chip and button has a 44px target on touch.

npm: lucide-react, motion
Wingo UI dependencies: avatar, badge, button, collapsible, empty-state, favorite-button, image-lightbox, navigation, pagination, progress, rating, select, skeleton, tag, use-controllable-state, use-locale, motion, number-format, relative-time, tones, ui-config

Props:
- `reviews: ReviewData[]`: The loaded page of reviews: { id, author: { name, avatar?, href? }, rating, title?, body?, date, photos?, verified?, helpfulCount?, helpful?, reply?: { author, body, date? }, meta?, context? }.
- `summary?: ReviewsSummaryData` = "summarizeRatings(reviews)": { average, count, distribution: [n5, n4, n3, n2, n1], aspects?, photoCount? }. Pass the server's numbers when the list is paged; the bars always use count for their proportions and the average shows one decimal.
- `layout?: "split" | "stacked"` = "split": split: on a container of 768px or more the summary becomes a sticky column beside the list. stacked: the summary sits above the list, with the average beside the bars once there is room.
- `showSummary?: boolean` = true: The average, the stars, the count and the breakdown.
- `showDistribution?: boolean` = true: The 5 to 1 star bars in the summary.
- `filterable?: boolean` = true: The bars become toggle buttons and the chips row appears (All, With photos, one chip per star).
- `sortable?: boolean` = true: The sort select above the list (a bottom sheet on phones).
- `defaultSort?: "relevant" | "newest" | "highest" | "lowest"` = "relevant": The starting order. relevant keeps the order the reviews came in; the others sort the loaded reviews (ties newest first).
- `sort?: ReviewsSort`: Controlled sort.
- `onSortChange?: (sort: ReviewsSort) => void`: Called when a person picks an order. When given, the list is not sorted locally: reload it in the new order.
- `filter?: ReviewsFilter`: Controlled filter, { rating?: 1 to 5; withPhotos?: boolean }.
- `defaultFilter?: ReviewsFilter` = "{}": The starting filter. Filters apply to the loaded reviews; a caller that reloads per filter gets the same result.
- `onFilterChange?: (filter: ReviewsFilter) => void`: Called when a bar or a chip changes the filter.
- `onHelpfulChange?: ((id: string, helpful: boolean) => void | Promise<unknown>)`: Shows the Helpful vote on every review. It flips at once; return a promise to keep it pending, and a rejection rolls it back and announces labels.helpfulError.
- `onReport?: (id: string) => void`: Shows a Report button on every review.
- `onWriteReview?: () => void`: Shows "Write a review" in the summary and in the empty state.
- `maxLines?: number` = 4: Lines of a review's text before "Show more". The toggle only appears when the text is longer.
- `photoLightbox?: boolean` = true: Review photos are buttons that open a full-screen viewer (zoom, swipe, swipe down to close).
- `loading?: boolean` = false: First load: a skeleton summary and skeleton reviews in the real shape.
- `skeletonCount?: number` = 3: Skeleton reviews while loading.
- `hasMore?: boolean` = false: Shows a full-width "Show more reviews" button with "Showing 8 of 126" under the list.
- `onLoadMore?: (() => void | Promise<unknown>)`: Loads the next page. A returned promise shows the loading state until it settles.
- `loadingMore?: boolean` = false: The next page is loading (for callers that do not return a promise). Shows with hasMore.
- `emptyState?: ReactNode`: Replaces the default empty state ("No reviews yet" with a Write a review action).
- `error?: ReactNode`: Shows an error state with the message in place of the list.
- `onRetry?: () => void`: Adds a Try again button to the error state.
- `size?: "sm" | "md"` = "md": md for a product page; sm for sheets, sidebars and seller cards (a 32px average, smaller stars, 56px photos).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The stars, the bars and a voted Helpful chip. neutral is black / white; amber stars are tone="warning".
- `color?: string` = "": Any CSS color for the stars and bars; replaces the tone.
- `now?: number | null` = "useNow()": The reference time for "2 days ago"; older than 28 days prints the date. null prints dates only.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for author.href (pass next/link's Link). Defaults to the one given to LinkProvider (lib/navigation), else a plain <a>.
- `locale?: string` = "": Numbers and dates ("4.6", "126", "9/22/2026"). Empty uses the app's or the browser's locale.
- `labels?: Partial<ReviewsLabels>`: Every string, English by default (DEFAULT_REVIEWS_LABELS): title, average(value), count(n, formatted), stars(n), all, withPhotos(n, formatted), filters, distribution, aspects, sort, sortOptions, verified, helpful, helpfulCount, helpfulError, report, reply, showMore, showLess, write, empty, emptyDescription, emptyFiltered, emptyFilteredDescription, showAll, errorTitle, retry, loadMore, loadingMore, remaining, showing, photos, photo(i, n), photoError.
- `lightboxLabels?: Partial<ImageLightboxLabels>`: Strings of the full-screen photo viewer (close, next, previous, zoom…).
- `classNames?: Partial<Record<"summary" | "distribution" | "bar" | "toolbar" | "list" | "review" | "photos" | "reply" | "footer", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `ReviewsSummary` (component): The summary on its own (a seller card, a product header): summary, layout, size, tone, color, showDistribution, filterable, selectedRating, onSelectedRatingChange, onWriteReview, animated (default true: the bars grow in on first view; false shows them filled), locale, labels, classNames. Props: ReviewsSummaryProps.
- `ReviewItem` (component): One review as an <article>: review, size, tone, color, maxLines, photoLightbox, onHelpfulChange, onReport, now, linkComponent, locale, labels, lightboxLabels, classNames. Props: ReviewItemProps.
- `summarizeRatings` (function): { average, count, distribution: [n5, n4, n3, n2, n1] } from a list; ratings round to the nearest star. Signature: (reviews: { rating: number }[]) => ReviewsSummaryData.

```tsx
import { Reviews, type ReviewData, type ReviewsLabels } from "@/components/ui/reviews"

const labels: Partial<ReviewsLabels> = {
  title: "Customer reviews",
  write: "Review this product",
}

const reviews: ReviewData[] = [
  {
    id: "r1",
    author: { name: "Julia Davis", avatar: "/demo/ioana-dumitrescu.jpg" },
    rating: 5,
    title: "Exactly what I wanted",
    body: "Fast delivery with UPS, and the bike arrived almost assembled.",
    date: "2026-09-22T10:15:00",
    photos: ["/demo/bicycle.jpg"],
    verified: true,
    helpfulCount: 12,
  },
]

export function ProductReviews() {
  return (
    <Reviews
      reviews={reviews}
      summary={{ average: 4.6, count: 126, distribution: [92, 21, 7, 3, 3] }}
      tone="warning"
      labels={labels}
      onHelpfulChange={async (id, helpful) => {
        const res = await fetch(`/api/reviews/${id}/helpful`, { method: helpful ? "POST" : "DELETE" })
        if (!res.ok) throw new Error("vote failed")
      }}
      onWriteReview={() => {}}
    />
  )
}
```

Docs: https://wingo-ui.com/components/reviews (Markdown: https://wingo-ui.com/components/reviews.md)

#### Seller card (`seller-card`)

component · Pro · v1.0.0 · install: `npx wingo-ui@latest add seller-card`

Who you are buying from: avatar, verified mark, stars, reply speed, a phone number you reveal, message, follow and more listings.

Tap the call button to show the seller's number: it fetches the full number (a spinner holds the button's width), the digits fade in, and the button turns into a real phone link, so the next tap dials. With a mouse a copy button appears beside the revealed number. If the number cannot be fetched, the button goes back to masked and a short message says so. Tap Message to start a conversation. Tap Follow to follow the seller: a check draws itself, and it rolls back if saving fails. The name opens the seller's profile; hover or focus it to see what was verified (on touch the same list sits in the stats). The compact row is one big tap target that opens the profile. The other listings are compact rows, or a rail you swipe (drag with a mouse, Left / Right while it has focus). Keyboard: Tab reaches the name, Follow, the call and message buttons, the listings and See all; Enter or Space activates, and focus stays on the call button when it becomes a link. The revealed number and errors are announced. In a narrow two-column bar the call button drops its icon so the digits fit.

npm: lucide-react, motion
Wingo UI dependencies: avatar, badge, button, carousel, copy-button, listing-card, rating, tooltip, use-controllable-state, use-locale, date-utils, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `seller: SellerData`: The seller: { id, name, avatar?, href?, type?: "private" | "business", companyName?, cui?, agent?, verified?: boolean | { phone?, identity?, company? }, rating? (0 to 5), reviewCount?, memberSince?, responseRate? (0 to 1), responseTime? (minutes), lastSeen?: time | "online", location?, listingCount?, phone? }.
- `variant?: "card" | "compact" | "inline"` = "card": card: the side column of a detail page with stats, contact and listings. compact: avatar, name, rating, one stat and a chevron as one tappable row (the phone detail page). inline: a small avatar, the name, the verified mark and a star on one line, no surface.
- `size?: "sm" | "md" | "lg"` = "md": Avatar 40 / 48 / 64px in the card, the type scale, paddings and the contact buttons (md in sm, 48px lg otherwise).
- `radius?: "sm" | "md" | "lg"` = "md": The surface corner: 12 / 16 / 24px. The buttons and listing tiles inside follow it.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The call button (solid) and the message button (soft of the same tone).
- `color?: string` = "": Any CSS color for the contact buttons; replaces the tone.
- `ratingTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The stars' fill. warning gives the classic amber stars.
- `showStats?: boolean` = true: The card's facts: private or business (with the tax id), what was verified, member since, reply time, response rate, place, last activity, listing count.
- `showRating?: boolean` = true: Stars, the value and the review count; a seller without reviews gets a "New seller" badge instead.
- `showContact?: boolean` = true: The call and message buttons (SellerContactActions) in the card.
- `showFollow?: boolean` = false: A Follow toggle in the card's header: icon only in a narrow card, with its label from 400px.
- `defaultFollowing?: boolean` = false: Starts followed (uncontrolled). Use following + onFollowingChange to control it.
- `following?: boolean`: The controlled follow state.
- `onFollowingChange?: (following: boolean) => (void | Promise<unknown>)`: Called on every toggle. Return a promise: a rejection rolls the toggle back and announces labels.followError.
- `onRevealPhone?: () => (string | Promise<string>)`: Show number fetches the full number (marketplaces log reveals). A spinner shows while it runs; a rejection returns the button to masked and says labels.revealError. Without it seller.phone is revealed on tap. The revealed number is kept per seller.id for the page's life, so a sticky contact bar shows it too.
- `onCall?: (phone: string) => void`: Replaces the tel: link of the revealed number (open a call sheet, log the call).
- `onMessage?: () => void`: The Message button. Without it and without messageHref there is no Message button.
- `messageHref?: string` = "": Makes Message a link to the conversation.
- `callingCode?: string` = "": The country calling code for the tel: link: "44" turns 07700 900 123 into tel:+447700900123. Empty keeps the number as written.
- `contactLayout?: "row" | "stack" | "auto"` = "auto": Call and Message side by side, stacked, or auto: stacked while the card is under 400px wide (a sidebar, a phone), side by side above.
- `listings?: ListingData[]`: The seller's other listings (ListingData from listing-card), shown under the contact buttons.
- `showListings?: boolean` = true: The listings section, when there are listings.
- `listingsHref?: string` = "": The "See all (14)" link beside the heading; the count is seller.listingCount.
- `listingLayout?: "compact" | "grid"` = "compact": Compact listing rows, or a swipeable rail of small grid cards with one photo each (no carousel inside a carousel).
- `maxListings?: number` = 3: How many listings to show.
- `listingsLoading?: boolean` = false: Skeleton rows in place of the listings while they load.
- `compactStat?: "auto" | "lastSeen" | "memberSince" | "responseTime" | "location" | "listings"` = "auto": The one fact beside the rating in the compact row. auto: the last activity, else the reply time, the place, then member since.
- `onSelect?: (seller: SellerData) => void`: Without seller.href, the compact row and the name become buttons that call it.
- `now?: number | null`: The page's clock in ms for "Active 5 minutes ago". Defaults to a minute timer (useNow).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the name, the compact row, Message, See all and the listings. Defaults to the LinkProvider's, then <a>.
- `locale?: string` = "": Numbers, dates and relative times. Empty uses the UIProvider locale, then the browser's.
- `labels?: Partial<SellerCardLabels>`: Every string, English by default (DEFAULT_SELLER_CARD_LABELS): verified, verifiedIdentity, verifiedPhone, verifiedCompany, business, private, newSeller, memberSince(date), responseRate(percent), responseTime(text), withinHour, withinDay, online, lastSeen(text), listings(n, formatted), reviews(n, formatted), rating(value), agent(name), cui, call, callSeller(name), showNumber, revealNumber(name), message, messageSeller(name), copyNumber, copiedNumber, revealed(phone), revealError, follow, following, followError, otherListings, seeAll(n, formatted), loadingListings, the hidden stat names (statType, statVerification, statMemberSince, statResponseTime, statResponseRate, statLocation, statActivity, statListings, statAgent) and listing (forwarded ListingCardLabels).
- `classNames?: Partial<Record<"header" | "avatar" | "name" | "verified" | "type" | "rating" | "stats" | "stat" | "contact" | "call" | "message" | "follow" | "listings", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root, merged last.

Parts:
- `SellerContactActions` (component): The call / message pair on its own, with the same reveal (shared per seller.id with every card on the page). It is what a listing page's sticky contact bar holds as its action. Props: { seller?, phone?, onRevealPhone?, onCall?, onMessage?, messageHref?, callingCode?, layout?: "row" | "stack" | "auto" = "row", size?: "sm" | "md" | "lg" = "lg", radius?, tone?, color?, showCopy? = true, linkComponent?, labels?, classNames? }.
- `maskPhone` (function): Keeps the first `visible` digits (7) and the formatting: "0745 123 456" becomes "0745 123 •••". A masked number passes through. Signature: (phone: string, visible?: number) => string.
- `DEFAULT_SELLER_CARD_LABELS` (constant): The English strings; spread them to translate a few. Type: SellerCardLabels.

```tsx
import { SellerCard, type SellerData } from "@/components/ui/seller-card"

const mihai: SellerData = {
  id: "s-mihai",
  name: "Michael Reed",
  avatar: "/demo/mihai-ionescu.jpg",
  href: "/sellers/mihai-ionescu",
  type: "private",
  verified: { phone: true, identity: true },
  rating: 4.8,
  reviewCount: 126,
  memberSince: "2019-03-12",
  responseRate: 0.98,
  responseTime: 40,
  location: "Brooklyn",
  listingCount: 14,
  phone: "07700 900 •••",
}

export function ListingSidebar({ openChat }: { openChat: () => void }) {
  return (
    <SellerCard
      seller={mihai}
      callingCode="44"
      onRevealPhone={async () => {
        const response = await fetch("/api/listings/l01/phone", { method: "POST" })
        return (await response.json()).phone as string
      }}
      onMessage={openChat}
      listingsHref="/sellers/mihai-ionescu"
      labels={{ showNumber: "Reveal number", message: "Chat" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/seller-card (Markdown: https://wingo-ui.com/components/seller-card.md)

### Marketing Sections

#### App Download Section (`app-download-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add app-download-section`

A mobile app promo: a drawn phone with a mini app, store buttons, a QR code to the download page, the rating and feature bullets.

A static section with real links: the store buttons (generic buttons with a glyph and the store name, no real store logos) are links of at least 48px that press in slightly when tapped and show the focus ring when tabbed to. From 1024px a QR code sits under them so desktop visitors can scan the download page with their phone; phones get the store buttons only. The stars are read-only and read as Rated 4.8 out of 5. The phone is drawn in code (status bar, Today list, a progress card in the tone, a tab bar) and themes itself; screen readers hear it as one image. split puts the copy beside the phone with a push notification floating off its edge, centered puts the heading on top and the phone between two feature columns, fading out at the bottom, and card sets everything on a tone panel with the phone rising from its bottom edge; every layout stacks to one column on phones.

npm: lucide-react
Wingo UI dependencies: marketing-section, avatar, qr-code, rating, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Mobile apps": The small line over the title.
- `title?: ReactNode` = "Acme in your pocket": The section title.
- `description?: ReactNode` = "Check off tasks, answer comments and catch up on your team's day from anywhere. Everything syncs the moment you are back online.": The paragraph under the title.
- `actions?: ReactNode`: Extra buttons under the description.
- `layout?: "split" | "centered" | "card"` = "split": split: copy, bullets and downloads beside the phone; centered: heading and downloads on top, the phone between two feature columns; card: a tone panel with the phone rising from its bottom edge.
- `reverse?: boolean` = false: split: the phone on the left from 1024px.
- `features?: AppDownloadFeature[]` = "APP_DOWNLOAD_FEATURES_SAMPLE": The bullets: icon, title and an optional line (the card layout shows titles with a check).
- `stores?: AppDownloadStore[]` = "APP_DOWNLOAD_STORES_SAMPLE": The store buttons: caption, label, href, a lucide icon and an optional aria-label.
- `storeVariant?: "solid" | "outline"` = "solid": Store buttons as solid dark pills or outlined on the surface.
- `rating?: number` = 4.8: The store rating out of 5, drawn proportionally. 0 hides the row.
- `reviewCount?: number` = 12400: The number of reviews, formatted for the locale.
- `showRating?: boolean` = true: Shows the stars and review count.
- `qrValue?: string` = "https://acme.com/download": The download page the QR code opens. Empty hides the code.
- `showQr?: boolean` = true: Shows the QR code from 1024px; phones get the store buttons only.
- `showNotification?: boolean` = true: The push notification floating beside the phone (split at 768 to 1023px and from 1280px, card from 1280px).
- `screen?: ReactNode`: Replaces the drawn app inside the phone, e.g. a screenshot.
- `phone?: Partial<AppDownloadPhoneContent>` = "APP_DOWNLOAD_PHONE_SAMPLE": The copy inside the drawn phone: time, date, heading, user, project, progress, tasks and the notification.
- `phoneColor?: string` = "#0A0A0A": The phone frame and its camera pill.
- `radius?: "sm" | "md" | "lg" | "full"` = "md": Store buttons 8 / 12 / 14px or pills; the card panel and QR tile follow.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Icon tiles, the app's progress card and notification tile, and the card panel.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `ratingTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "warning": The star fill; amber by default.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element; h3 when the section sits under another h2.
- `locale?: string` = "en-US": Formats the rating and review count; default the UIProvider's locale, else en-US.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the store buttons (next/link in an app); default the LinkProvider's.
- `labels?: Partial<AppDownloadLabels>`: stores, reviews, ratingLabel, qrTitle, qrDescription, qrImage and phone.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<AppDownloadSlot, string>>`: Classes for copy, features, feature, feature-icon, stores, store, rating, qr, visual, phone, screen and notification.

Parts:
- `APP_DOWNLOAD_FEATURES_SAMPLE` (constant): Four app features: offline, notifications, Face ID, widgets.
- `APP_DOWNLOAD_STORES_SAMPLE` (constant): App Store and Google Play buttons linking to /download/ios and /download/android.
- `APP_DOWNLOAD_PHONE_SAMPLE` (constant): The drawn app's copy: Emma Carter's Today list in launch week and a notification from Noah Mitchell.
- `DEFAULT_APP_DOWNLOAD_LABELS` (constant): The English strings.
- `AppDownloadFeature` (type): One bullet.
- `AppDownloadStore` (type): One store button.
- `AppDownloadTask` (type): A task row in the drawn app: title, meta and done.
- `AppDownloadPhoneContent` (type): The copy inside the drawn phone.
- `AppDownloadSectionProps` (type): Props of AppDownloadSection.

```tsx
// app/(marketing)/mobile/page.tsx
"use client"

import Link from "next/link"
import { Play, Smartphone } from "lucide-react"
import { AppDownloadSection } from "@/components/blocks/app-download-section"

export default function MobilePage() {
  return (
    <AppDownloadSection
      linkComponent={Link}
      layout="split"
      title="Your workspace, on every phone"
      qrValue="https://acme.com/download"
      rating={4.8}
      reviewCount={12400}
      stores={[
        { caption: "Download on the", label: "App Store", href: "https://apps.apple.com/app/id000000000", icon: <Smartphone /> },
        { caption: "Get it on", label: "Google Play", href: "https://play.google.com/store/apps/details?id=com.acme", icon: <Play /> },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/app-download-section (Markdown: https://wingo-ui.com/components/app-download-section.md)

#### Blog Cards Section (`blog-cards-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add blog-cards-section`

A "From the blog" section: the latest posts as cards, a featured post with a list, dated rows or a sideways rail, with covers drawn in code.

Each post is one link to /blog/<slug>: hovering lifts the card, zooms its cover glyph and underlines the title, and tabbing to it draws the focus ring around the whole card. Covers are drawn in code (a gradient tile per category with its glyph, or a quiet tint in the tone), so nothing loads. The grid shows three cards, two columns on tablets and one on phones; featured puts the latest post large beside a list of compact rows with small covers; list shows rows with a big month and day column and a cover on the right from 768px; rail is a sideways scroller that snaps card by card, swipes on touch and bleeds to the screen edge, with previous and next buttons that disable at the ends. "View all posts" under the heading links to /blog.

npm: lucide-react
Wingo UI dependencies: marketing-section, avatar, badge, button, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Blog": The small line over the title.
- `title?: ReactNode` = "From the blog": The section title.
- `description?: ReactNode` = "Notes on planning, writing and shipping from the team behind Acme.": The paragraph under the title.
- `actions?: ReactNode`: Extra buttons under the heading, after View all posts.
- `posts?: BlogCardsPost[]` = "BLOG_CARDS_SAMPLE": { slug, title, excerpt?, category, author: { name, role?, avatar? }, date (ISO), readingTime? (minutes), href? }.
- `categories?: Record<string, BlogCardsCategory>` = "BLOG_CARDS_CATEGORIES": { label, icon?, color? } per category key: the tag text, the cover glyph and the cover color. Unknown keys show the key with a newspaper glyph.
- `layout?: "grid" | "featured" | "list" | "rail"` = "grid": grid: three cards (two on tablets, one on phones); featured: the latest post large beside compact rows; list: rows with a date column in a 960px column; rail: a snap scroller with previous and next buttons.
- `limit?: number` = 0: How many posts show; 0 picks by layout (grid 3, featured 4, list 4, rail 6).
- `align?: "start" | "center"` = "center": Where the heading sits.
- `cover?: "gradient" | "soft" | "none"` = "gradient": gradient: a colored tile per category with its glyph; soft: a quiet tint with the glyph in the tone; none: text-only cards.
- `card?: "raised" | "flat" | "none"` = "raised": The surface behind grid, featured and rail cards: raised, a flat tint or nothing.
- `radius?: "sm" | "md" | "lg"` = "lg": Card corners: 12, 16 or 24px; the cover follows.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The category tags and the glyph on soft covers.
- `showExcerpt?: boolean` = true: The summary under each title.
- `showAuthor?: boolean` = true: The author's avatar initials and name.
- `showReadingTime?: boolean` = true: "7 min read" next to the date.
- `showViewAll?: boolean` = true: The View all posts button under the heading.
- `viewAllHref?: string` = "/blog": Where View all posts links.
- `basePath?: string` = "/blog": Posts without an href link to basePath/slug.
- `locale?: string` = "en-US": Intl locale for the dates; default the UIProvider's locale, else en-US.
- `headingSize?: "md" | "lg"` = "md": lg when the section opens the page.
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element; post titles are h3.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px. The list layout narrows lg to 960px.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for posts and View all (next/link in an app); default the LinkProvider's.
- `labels?: Partial<BlogCardsSectionLabels>`: viewAll, readingTime ({minutes}), latest, rail (the scroller's label), previous, next, byAuthor ({name}).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<BlogCardsSectionSlot, string>>`: Classes for list, item, cover, body, category, title, excerpt, meta, author, date, controls and viewAll.

Parts:
- `BLOG_CARDS_SAMPLE` (constant): Six Acme posts on planning, docs, automations, insights and product, Aug to Oct 2026.
- `BLOG_CARDS_CATEGORIES` (constant): The sample categories with a lucide glyph and a cover color each.
- `DEFAULT_BLOG_CARDS_SECTION_LABELS` (constant): The English strings.
- `BlogCardsPost` (type): One post.
- `BlogCardsCategory` (type): { label, icon?, color? }.
- `BlogCardsAuthor` (type): { name, role?, avatar? }.
- `BlogCardsSectionLabels` (type): The strings the labels prop overrides.
- `BlogCardsSectionLayout` (type): "grid" | "featured" | "list" | "rail".
- `BlogCardsSectionProps` (type): Props of BlogCardsSection.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { BlogCardsSection, type BlogCardsPost } from "@/components/blocks/blog-cards-section"

const posts: BlogCardsPost[] = [
  {
    slug: "plan-a-quarter-in-one-afternoon",
    title: "How we plan a quarter in one afternoon",
    excerpt: "Our six-step ritual for turning a messy backlog into a plan.",
    category: "planning",
    author: { name: "Emma Carter", role: "CEO" },
    date: "2026-10-01",
    readingTime: 7,
  },
]

export default function Home() {
  return <BlogCardsSection layout="featured" posts={posts} linkComponent={Link} />
}
```

Docs: https://wingo-ui.com/components/blog-cards-section (Markdown: https://wingo-ui.com/components/blog-cards-section.md)

#### CTA Section (`cta-section`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add cta-section`

The closing call to action of a page: a title, two actions or an email signup, social proof and a short checklist on a band.

Both actions are links through your router. With newsletter on, an email field replaces them: it checks the address on submit, shows the error under the field, spins while onSubscribe runs and turns into a confirmation. The inverted band flips the text colors, so a neutral action becomes the band's text color and soft buttons and the field stay readable in both themes. The band rises a little as it first scrolls in (instant under reduced motion); it is never invisible. The band variant draws its scene in tokens (tinted light, a grid fading toward the copy, waves and floating cards around the copy on wide bands, two cards above it on narrow ones). The form variant puts the copy and a checklist beside an inset well with a stacked email form that validates, spins and confirms. On phones the actions stack full width, and the split panel and the form card put the actions under the copy.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, avatar, button, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "": The small uppercase line over the title.
- `title?: ReactNode` = "Ship your next project with Acme": The closing headline.
- `description?: ReactNode` = "Set up your workspace in two minutes and bring the team when you're ready. Your first project is on us.": The paragraph under the title.
- `actions?: ReactNode`: Replaces the primary and secondary buttons.
- `variant?: "inverted" | "soft" | "split" | "plain" | "band" | "form"` = "inverted": A solid band, a gray band, copy and actions side by side on a raised panel, no band, an image band (centered copy over a drawn scene with floating cards) or a raised card with the copy beside an email form.
- `media?: ReactNode`: band only: replaces the drawn scene behind the copy (an image, a video, your own drawing); a soft wash keeps the copy readable.
- `newsletter?: boolean` = false: An email signup instead of the buttons (the form variant always has one).
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: Called with the address; a rejected promise shows the failed message. Without it the form waits 900 ms and succeeds.
- `newsletterLabels?: Partial<NewsletterFormLabels>`: The form's strings: email, placeholder, submit, success, invalid, failed.
- `socialProof?: boolean` = true: Avatars and the Join 12,000 teams line above the title.
- `avatars?: string[]` = "CTA_SECTION_AVATARS": Names for the social proof avatars, drawn as initials.
- `checklist?: ReactNode[]` = "CTA_SECTION_CHECKLIST": Short promises under the actions: Free 14-day trial, No credit card, Cancel anytime.
- `showChecklist?: boolean` = true: Shows the checklist.
- `align?: "start" | "center"` = "center": Where the copy sits (split and form always start, band always centers).
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary action; neutral flips to the band's text color on the inverted band.
- `radius?: "sm" | "md" | "lg"` = "md": Band corners: 16, 24 or 32px.
- `width?: "md" | "lg" | "xl"` = "lg": The column: md 960px, lg 1200px, xl 1400px.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding around the band, as in MarketingSection.
- `headingSize?: "md" | "lg"` = "md": The title scale.
- `headingAs?: "h2" | "h3"` = "h2": The title element.
- `animateIn?: boolean` = true: The band rises a little the first time it scrolls in.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link for the actions; default the LinkProvider's.
- `labels?: Partial<CtaSectionLabels>`: primary (also the form variant's submit), secondary, proof, people, checklist, formTitle and formNote.
- `hrefs?: Partial<CtaSectionHrefs>`: primary (/sign-up) and secondary (/contact).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<CtaSectionSlot, string>>`: Classes for container, band, heading, title, description, actions, proof, checklist and form.

Parts:
- `CTA_SECTION_CHECKLIST` (constant): The sample promises: Free 14-day trial, No credit card, Cancel anytime.
- `CTA_SECTION_AVATARS` (constant): The sample names for the social proof avatars.
- `DEFAULT_CTA_SECTION_LABELS` (constant): The English strings.
- `DEFAULT_CTA_SECTION_HREFS` (constant): The default action links.
- `CtaSectionProps` (type): Props of CtaSection.

```tsx
// app/(marketing)/page.tsx
import Link from "next/link"
import { CtaSection } from "@/components/blocks/cta-section"

export default function HomePage() {
  return (
    <CtaSection
      linkComponent={Link}
      ctaTone="brand"
      title="Ship your next project with Acme"
      hrefs={{ primary: "/sign-up", secondary: "/contact" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/cta-section (Markdown: https://wingo-ui.com/components/cta-section.md)

#### FAQ Section (`faq-section`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add faq-section`

Frequently asked questions for a marketing page: an accordion, a split layout, an open grid or expandable cards, with topics and search.

Click or tap a question to open its answer (Enter and Space on the keyboard, arrow keys move between questions); in single mode opening one closes the other. The topics row filters the list: on phones it scrolls sideways, arrows move between topics. With search on, typing filters questions and answers live, opens every answer that holds the words and marks each match; when nothing matches, an empty state offers to search all topics or contact the team. Links inside answers are underlined. In the split layout the heading and contact card stay in view while the questions scroll on desktop. The grid layout shows every answer at once, one column on phones. The cards layout gives each question its own raised card that expands in place (a button with aria-expanded controlling its answer region), topic chips with counts on top, two columns from 768px and one on phones.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, accordion, button, search-input, segmented-control, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "FAQ": The small uppercase line over the title.
- `title?: ReactNode` = "Frequently asked questions": The section title.
- `description?: ReactNode` = "Everything about plans, your account and your data. Can't find an answer? We are one message away.": The muted paragraph under the title.
- `actions?: ReactNode`: Buttons under the description.
- `items?: FaqItem[]` = "FAQ_SECTION_SAMPLE": { question, answer, answerText?, category?, id? }; answer is any node, links in it are underlined.
- `categories?: FaqCategory[]` = "FAQ_SECTION_CATEGORIES": { value, label, icon? } topics; only topics that hold a question show, and the row hides below two. In the cards layout they show as chips and as a label on each card.
- `showCategories?: boolean` = true: The topics row that filters the list.
- `category?: string`: The selected topic (controlled); "all" or a category value.
- `defaultCategory?: string` = "all": The topic selected at first.
- `onCategoryChange?: (category: string) => void`: Runs when a topic is picked.
- `searchable?: boolean` = false: A search field that filters questions and answers as you type and marks the matches.
- `layout?: "centered" | "split" | "grid" | "cards"` = "centered": centered: one 720px column; split: heading and contact card on the left (sticky on desktop); grid: two columns, always open; cards: a raised card per question in two columns that opens in place, with topic chips and counts on top.
- `type?: "single" | "multiple"` = "single": single: one answer open at a time; multiple: any number.
- `defaultOpen?: boolean` = true: The first question starts open.
- `variant?: "ghost" | "outline" | "soft" | "separated"` = "ghost": The accordion look: hairlines, one outlined or tinted box, or a card per question.
- `indicator?: "chevron" | "plus" | "none"` = "plus": The open / closed sign at the end of each question (in the cards layout a round badge that fills with the tone when open).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected topic, the open question's sign and the contact button.
- `contact?: boolean` = true: The "Still have questions?" card.
- `contactHref?: string` = "/contact": Where the contact buttons link.
- `jsonLd?: boolean` = false: Adds a FAQPage JSON-LD script with the plain text of every answer, for rich results in search.
- `align?: "start" | "center"` = "center": Where the heading sits (split always starts).
- `headingSize?: "md" | "lg"` = "md": lg when the section opens the page (a FAQ page).
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element: h1 on a FAQ page, h2 inside a longer page.
- `width?: "auto" | "sm" | "md" | "lg" | "xl"` = "auto": The column; auto picks by layout (centered sm 720px, the others lg 1200px).
- `background?: "none" | "muted"` = "none": muted: a gray band that sets the section apart.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, from MarketingSection.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (or "a") for the contact buttons; default the LinkProvider's (links inside answers use the provider).
- `labels?: Partial<FaqSectionLabels>`: all, categories, searchLabel, searchPlaceholder, empty ({query}), emptyDescription, searchAll, contactTitle, contactDescription, contactAction.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<FaqSectionSlot, string>>`: Classes for heading, aside, toolbar, categories, search, list, item, question, answer, empty and contact.

Parts:
- `FAQ_SECTION_SAMPLE` (constant): Twelve Acme questions across billing, account, security and integrations.
- `FAQ_SECTION_CATEGORIES` (constant): The four sample topics: Billing, Account, Security, Integrations.
- `DEFAULT_FAQ_SECTION_LABELS` (constant): The English strings.
- `faqNodeText` (function): The plain text of a node: what search and the JSON-LD read from a rich answer.
- `FaqItem` (type): { question, answer, answerText?, category?, id? }.
- `FaqCategory` (type): { value, label, icon? }.
- `FaqSectionProps` (type): Props of FaqSection.

```tsx
// app/(marketing)/faq/page.tsx
"use client"

import Link from "next/link"
import { FaqSection, FAQ_SECTION_CATEGORIES, type FaqItem } from "@/components/blocks/faq-section"

const questions: FaqItem[] = [
  { category: "billing", question: "Can I cancel at any time?", answer: "Yes. You keep access until the end of the billing period." },
  {
    category: "account",
    question: "How do I invite my team?",
    answer: (
      <>
        Open Settings, then Members. <Link href="/docs/members">Read the guide</Link>.
      </>
    ),
  },
]

export default function FaqPage() {
  return (
    <FaqSection
      headingAs="h1"
      items={questions}
      categories={FAQ_SECTION_CATEGORIES}
      searchable
      jsonLd
      linkComponent={Link}
    />
  )
}
```

Docs: https://wingo-ui.com/components/faq-section (Markdown: https://wingo-ui.com/components/faq-section.md)

#### Feature Grid (`feature-grid`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add feature-grid`

A marketing section that lists product features as icon cards, a bento with drawn visuals, illustrated cards, numbered rows or compact rows.

A static section: a heading, then one card per feature with an icon tile, a title and a line of text. A feature with an href turns its whole card into one link (Learn more), which lifts slightly on hover and shows the focus ring around the card when tabbed to. The bento layout puts two wide cells and one tall cell with small product visuals drawn in code (a chart, a task stack, an automation flow) next to three small cells; the illustrated layout tops each card with a small scene drawn in code (the feature visual or a scene picked by position), and the numbered layout lists 01, 02, 03 under hairlines; every layout collapses to one column on phones.

npm: lucide-react
Wingo UI dependencies: marketing-section, avatar, badge, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Features": The small line over the title.
- `title?: ReactNode` = "Everything your team needs to ship": The section title.
- `description?: ReactNode` = "Plan the work, write it down and keep everyone in sync, in one calm workspace.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `features?: FeatureGridItem[]` = "FEATURE_GRID_SAMPLE": Each feature: icon, title, description, and optionally href (the card becomes a link), badge and visual (bento).
- `layout?: "grid" | "bento" | "list" | "illustrated" | "numbered"` = "grid": grid: cards with an icon tile; bento: six cells, the large ones with drawn visuals; list: compact rows in two columns; illustrated: cards with a drawn scene on top (the feature visual, else one drawn per position); numbered: 01, 02, 03 rows under hairlines with a small icon beside the title, two columns from 768px.
- `columns?: 2 | 3 | 4` = 3: Grid and illustrated columns from 1024px; tablets show two, phones one.
- `align?: "start" | "center"` = "center": Where the heading sits.
- `card?: "raised" | "flat" | "none"` = "raised": The surface behind each feature: a raised card, a flat tint or nothing. List rows never get one.
- `radius?: "sm" | "md" | "lg"` = "lg": Card corners: 12, 16 or 24px.
- `iconVariant?: "soft" | "solid" | "outline"` = "soft": The look of the icon tiles.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Icon tiles, badges and the accents in the drawn visuals.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for card links (next/link in an app); default the LinkProvider's.
- `labels?: Partial<FeatureGridLabels>`: learnMore, the link line on linked cards.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<FeatureGridSlot, string>>`: Classes for list, item, icon, body, title, description, badge, link, visual and number.

Parts:
- `FEATURE_GRID_SAMPLE` (constant): Six Acme features (insights, automations, docs, search, security, planning) with visuals for the bento.
- `DEFAULT_FEATURE_GRID_LABELS` (constant): The English strings.
- `FeatureGridItem` (type): One feature.
- `FeatureGridProps` (type): Props of FeatureGrid.

```tsx
// app/(marketing)/features/page.tsx
"use client"

import Link from "next/link"
import { Bot, Calendar, Plug } from "lucide-react"
import { FeatureGrid } from "@/components/blocks/feature-grid"

export default function FeaturesPage() {
  return (
    <FeatureGrid
      linkComponent={Link}
      eyebrow="Platform"
      title="Built for the way small teams work"
      columns={3}
      features={[
        { icon: <Calendar />, title: "Timelines", description: "Plan the quarter in one view.", href: "/product/planning" },
        { icon: <Bot />, title: "AI summaries", description: "Catch up on any project in seconds.", badge: "New" },
        { icon: <Plug />, title: "Integrations", description: "Slack, GitHub and 40 more.", href: "/integrations" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/feature-grid (Markdown: https://wingo-ui.com/components/feature-grid.md)

#### Feature Showcase (`feature-showcase`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add feature-showcase`

A section that shows a few features in depth: alternating rows, tabs that swap the visual, tall cards or a scroll tour past a pinned visual.

Zigzag: each feature is a row with an eyebrow, a title, a short text, a three-item checklist and a Learn more link next to a visual, alternating sides on desktop and stacking copy over visual on phones. The visuals are drawn in code (a roadmap timeline, a doc editor, an automation rule) unless you pass media. Tabs: a row of tabs (or a list of cards beside the visual from 1024px) picks the feature; the visual and copy fade over. Arrow keys move between tabs, Home and End jump. On phones the tabs become a horizontally scrolling segmented row. Cards: one tall card per feature with its visual on top, three to a row from 1024px and a swipeable snap rail below. Sticky: on desktop the copy of each feature scrolls by while the visual column stays pinned and crossfades to the feature crossing the middle of the screen; on phones each feature shows its own visual under its copy. The pin needs the page (or the nearest scroll container) to scroll, so do not wrap it in an overflow container.

npm: motion, @radix-ui/react-tabs, lucide-react
Wingo UI dependencies: marketing-section, avatar, use-controllable-state, use-media-query, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Product": The small line over the section title.
- `title?: ReactNode` = "One workspace, from plan to launch": The section title.
- `description?: ReactNode` = "Acme brings planning, docs and automations together, so the work and the context never drift apart.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `features?: FeatureShowcaseItem[]` = "FEATURE_SHOWCASE_SAMPLE": Each feature: icon, eyebrow, title, description, up to three points, href, and media or a drawn visual.
- `layout?: "zigzag" | "tabs" | "cards" | "sticky"` = "zigzag": zigzag: alternating rows; tabs: one visual that swaps as you pick a feature; cards: tall cards side by side (a swipeable rail on phones); sticky: the copy scrolls past a pinned visual that swaps to the feature in view.
- `tabsPosition?: "top" | "left"` = "top": Tabs only: a centered row above the visual, or a list of cards beside it from 1024px.
- `reverse?: boolean` = false: Zigzag: the first row starts with the visual; sticky: the pinned visual sits on the start side.
- `align?: "start" | "center"` = "center": Where the section heading sits.
- `frame?: "tinted" | "plain"` = "tinted": A gray well around each visual, or none.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Checks, eyebrow icons and the accents in the drawn visuals.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `value?: string`: Tabs: the selected feature (its value, or its index as a string).
- `defaultValue?: string`: Tabs: the feature selected first; default the first one.
- `onValueChange?: (value: string) => void`: Tabs: called when another feature is picked.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for Learn more links; default the LinkProvider's.
- `labels?: Partial<FeatureShowcaseLabels>`: learnMore and tabs (the tab list's aria-label).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<FeatureShowcaseSlot, string>>`: Classes for rows, row, copy, points, point, link, media, tabs, list, trigger, panel, card (cards) and stop (sticky).

Parts:
- `FEATURE_SHOWCASE_SAMPLE` (constant): Three Acme features (planning, docs, automations) with their drawn visuals.
- `DEFAULT_FEATURE_SHOWCASE_LABELS` (constant): The English strings.
- `FeatureShowcaseItem` (type): One feature.
- `FeatureShowcaseProps` (type): Props of FeatureShowcase.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { FeatureShowcase, FEATURE_SHOWCASE_SAMPLE } from "@/components/blocks/feature-showcase"

export default function Home() {
  return (
    <FeatureShowcase
      linkComponent={Link}
      layout="tabs"
      tabsPosition="left"
      features={FEATURE_SHOWCASE_SAMPLE}
      onValueChange={(value) => console.log("viewing", value)}
    />
  )
}
```

Docs: https://wingo-ui.com/components/feature-showcase (Markdown: https://wingo-ui.com/components/feature-showcase.md)

#### Hero Section (`hero-section`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add hero-section`

The top of a landing or product page: an announcement pill, a big title, two actions, social proof and a product shot drawn in code.

A static page header that rises in once when it mounts on the client (never during hydration, under reduced motion or with animateIn off). The announcement pill and both actions are links through your router. The default media is a browser frame with a mini Acme board drawn with tokens, so it follows the theme; it folds its sidebar, columns and chart with its own width, so it fits a split column and a 360px phone without scrolling sideways. On phones the actions stack full width and the split layout puts the media under the copy.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, avatar, button, motion, navigation, tones, ui-config

Props:
- `announcement?: ReactNode` = "AI summaries for every doc": The link pill above the title, after a New badge; an empty string hides it.
- `announcementHref?: string` = "/changelog": Where the pill links to.
- `title?: ReactNode` = "Plan, write and ship in one calm workspace": The page title, on the shared marketing scale.
- `description?: ReactNode` = "Acme brings your roadmap, docs and automations together, so small teams spend less time syncing and more time shipping.": The paragraph under the title.
- `actions?: ReactNode`: Replaces the primary and secondary buttons; they stack full width on phones.
- `media?: ReactNode` = "<ProductMockup />": The picture next to or under the copy (the drawn scene in media, the terminal in terminal, none by default in editorial); null hides it.
- `showMedia?: boolean` = true: Shows the media.
- `socialProof?: boolean` = true: The avatars, five stars and the Loved by line under the actions; in editorial, the rule and the key facts.
- `facts?: HeroSectionFact[]` = "HERO_SECTION_FACTS": The key facts ({ value, label }) under the rule in the editorial layout, up to four.
- `avatars?: string[]` = "HERO_SECTION_AVATARS": Names for the social proof avatars, drawn as initials.
- `layout?: "centered" | "split" | "stacked" | "editorial" | "media" | "terminal"` = "centered": centered: copy over a wide shot; split: copy left, media right; stacked: title and copy side by side over a wide shot; editorial: a magazine cover with huge start-aligned type, a narrow description column, plain buttons and key facts under a rule, no mockup; media: a full-width drawn workspace with the copy in a glass card at the bottom-start (under the scene on phones); terminal: copy beside a drawn terminal with a CLI install and an API call.
- `background?: "glow" | "grid" | "mesh" | "none"` = "glow": A soft radial light in the tone, faint grid lines that fade out, a soft multi-stop gradient mesh, or nothing.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The glow, the New badge and the mockup's accent.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary button; brand is the marketing orange.
- `headingAs?: "h1" | "h2"` = "h1": The title element: h1 when the hero opens the page.
- `headingSize?: "md" | "lg"` = "lg": The title scale: lg for a page's first heading, md for a quieter header.
- `width?: "lg" | "xl"` = "lg": The content width: lg 1200px, xl 1400px.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, as in MarketingSection: sm 40 / 56px, md 56 / 96px, lg 80 / 128px.
- `animateIn?: boolean` = true: Rises in once when mounted on the client; server markup is always final.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (next/link in an app); default the LinkProvider's.
- `labels?: Partial<HeroSectionLabels>`: announcementBadge, primary, secondary, proof, rating, ratingLabel, people, scene and terminal (spoken descriptions of the drawn media), terminalTitle.
- `hrefs?: Partial<HeroSectionHrefs>`: primary (/sign-up) and secondary (/contact).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<HeroSectionSlot, string>>`: Classes for container, background, announcement, heading, title, description, actions, proof, media, card (the glass card in media) and facts (editorial).

Parts:
- `ProductMockup` (component): The default media: a browser frame holding a mini Acme board (sidebar, task columns, a weekly chart), drawn with tokens. It folds with its own width. Takes div props.
- `BrowserFrame` (component): A window chrome (three dots and an address bar) around any children: screenshots, videos, drawn UI. Takes div props.
- `HERO_SECTION_FACTS` (constant): The sample key facts for the editorial layout.
- `HeroSectionFact` (type): One key fact: value and label.
- `HERO_SECTION_AVATARS` (constant): The sample names for the social proof avatars.
- `DEFAULT_HERO_SECTION_LABELS` (constant): The English strings.
- `DEFAULT_HERO_SECTION_HREFS` (constant): The default action links.
- `HeroSectionProps` (type): Props of HeroSection.

```tsx
// app/(marketing)/page.tsx
import Link from "next/link"
import { HeroSection } from "@/components/blocks/hero-section"

export default function HomePage() {
  return (
    <HeroSection
      linkComponent={Link}
      layout="split"
      ctaTone="brand"
      announcement="Timelines are live"
      announcementHref="/changelog"
      hrefs={{ primary: "/sign-up", secondary: "/contact" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/hero-section (Markdown: https://wingo-ui.com/components/hero-section.md)

#### Integrations Section (`integrations-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add integrations-section`

A marketing section of linked integration tiles: a filterable grid, an orbit around the product mark, or copy beside a tile wall.

Each tile is one link to the integration's page (/integrations/<slug>) that lifts slightly on hover and shows a focus ring when tabbed to. The category chips over the tiles filter them (aria-pressed buttons with counts; on phones the row scrolls sideways), new tiles rise in and a screen reader hears the new count. In the orbit layout the product mark sits in the center and the tiles turn slowly on two rings in opposite directions while staying upright; hovering or focusing the orbit pauses it, a round button pauses and plays it, chips dim the tiles outside the category, and under reduced motion the rings stand still. Phones get the grid instead of the orbit. The split layout puts the heading, a checklist, the chips and the link on the left and a wall of compact tiles on the right, stacked on phones. A See all integrations button links to /integrations.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, badge, button, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Integrations": The small line over the title.
- `title?: ReactNode` = "Works with the tools you already use": The section title.
- `description?: ReactNode` = "Acme connects to the apps your team lives in, so updates flow both ways and nobody copies anything twice.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `integrations?: IntegrationsSectionItem[]` = "INTEGRATIONS_SECTION_SAMPLE": Each tool: slug, name, category, icon, and optionally color, description, badge and href (default /integrations/<slug>). The orbit shows the first 13.
- `categories?: IntegrationsSectionCategory[]` = "INTEGRATIONS_SECTION_CATEGORIES": The filter chips as { value, label }, in order; a category with no tile is left out.
- `points?: ReactNode[]` = "INTEGRATIONS_SECTION_POINTS": Split: the checklist under the heading.
- `mark?: ReactNode`: Orbit: replaces the mountain glyph in the center mark.
- `allHref?: string` = "/integrations": Where See all integrations goes; empty hides the button.
- `layout?: "grid" | "orbit" | "split"` = "grid": grid: a card per tool in columns; orbit: the product mark in the center with the tiles on two slowly turning rings (the grid on phones); split: heading, checklist and chips on the left, a wall of compact tiles on the right.
- `columns?: 2 | 3 | 4` = 4: Grid columns from 1024px; tablets show two (three without descriptions).
- `align?: "start" | "center"` = "center": Where the heading, chips and link sit in the grid and orbit layouts; split always starts.
- `filters?: boolean` = true: The category chips over the tiles.
- `category?: string`: The selected chip ("all" or a category value); pass it to control the filter.
- `defaultCategory?: string` = "all": The chip selected at first while uncontrolled.
- `onCategoryChange?: (category: string) => void`: Fires when a chip is picked.
- `showDescription?: boolean` = true: Grid: the line of text under each name; off, the tiles stack and phones fit two per row.
- `iconStyle?: "brand" | "tone"` = "brand": brand fills each glyph tile with the tool's own color; tone draws every glyph in the section tone.
- `card?: "raised" | "flat" | "outline"` = "raised": Grid: the surface of each tile.
- `radius?: "sm" | "md" | "lg"` = "md": Tile corners: 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected chip, badges, checklist marks, tone glyphs and the orbit glow.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `animate?: boolean` = true: Orbit: the rings turn. Always still under reduced motion.
- `orbitDuration?: number` = 90: Orbit: seconds for one turn of the inner ring; the outer ring takes 1.6 times longer.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the tiles and the button (next/link in an app); default the LinkProvider's.
- `labels?: Partial<IntegrationsSectionLabels>`: all, filters (the chip group's name), results ({count} integrations), result (the same for one), empty, seeAll, brand (the name under the orbit mark), pause and play.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<IntegrationsSectionSlot, string>>`: Classes for filters, filter, list, item, tile, icon, name, category, description, badge, orbit, ring, mark, aside, points, wall, footer and empty.

Parts:
- `INTEGRATIONS_SECTION_SAMPLE` (constant): Twelve tools (Slack, GitHub, Google Calendar, Zapier, Microsoft Teams, Linear, Zoom, Google Drive, Sentry, Gmail, Figma, Webhooks) with glyphs and colors.
- `INTEGRATIONS_SECTION_CATEGORIES` (constant): Communication, Productivity, Developer tools and Automation.
- `INTEGRATIONS_SECTION_POINTS` (constant): The three checklist lines of the split layout.
- `DEFAULT_INTEGRATIONS_SECTION_LABELS` (constant): The English strings.
- `IntegrationsSectionItem` (type): One tool.
- `IntegrationsSectionCategory` (type): A filter chip: { value, label }.
- `IntegrationsSectionProps` (type): Props of IntegrationsSection.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { IntegrationsSection } from "@/components/blocks/integrations-section"

export default function HomePage() {
  return (
    <main>
      {/* hero, features... */}
      <IntegrationsSection
        linkComponent={Link}
        layout="orbit"
        eyebrow="Integrations"
        title="Plays well with your stack"
        onCategoryChange={(category) => console.log("filter", category)}
      />
    </main>
  )
}
```

Docs: https://wingo-ui.com/components/integrations-section (Markdown: https://wingo-ui.com/components/integrations-section.md)

#### Logo Cloud (`logo-cloud`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add logo-cloud`

A row of customer wordmarks under a quiet line, as a wrapping grid, an endless marquee with faded edges or a heading beside a ruled grid.

Logos sit in a muted gray and darken under the pointer. The grid wraps to two columns on phones. The marquee scrolls one row forever in pure CSS, fades out at both ends, and pauses while the pointer is over it or a logo link has keyboard focus; under reduced motion it becomes a still, wrapped row. Split puts a larger title and a supporting line on the start side and the logos in a ruled grid beside it; on phones and tablets the heading sits above the grid. Logos with an href are links through your router (the marquee's repeated copy is hidden from assistive tech and the tab order).

npm: lucide-react
Wingo UI dependencies: marketing-section, navigation, ui-config

Props:
- `title?: ReactNode` = "Trusted by teams at": The quiet line over the logos; an empty string hides it.
- `description?: ReactNode` = "From five-person startups to public companies, over 12,000 teams plan their week in Acme.": Split only: the supporting line under the title; an empty string hides it.
- `logos?: LogoCloudItem[]` = "LOGO_CLOUD_SAMPLE": { name, icon?, href?, className? }: className sets the wordmark's type.
- `layout?: "grid" | "marquee" | "split"` = "grid": Rows that wrap, one row that scrolls forever, or a heading on the start side beside a ruled grid of logos.
- `variant?: "plain" | "tiles"` = "plain": Grid look: bare logos (ruled cells in split) or each on a gray tile.
- `columns?: 3 | 4 | 6 | 8` = 4: Grid columns on wide screens; phones always show two. Split shows three (3, 6) or four (4, 8).
- `size?: "sm" | "md" | "lg"` = "md": Wordmark size: 14, 17 or 20px with a 16, 20 or 24px glyph.
- `muted?: boolean` = true: Gray logos that darken on hover; false shows them in the text color.
- `duration?: number` = 40: Seconds for one full marquee loop (at least 5).
- `direction?: "left" | "right"` = "left": Which way the marquee moves.
- `pauseOnHover?: boolean` = true: The marquee stops under the pointer and while a logo has focus.
- `fade?: boolean` = true: Fades the marquee's ends into the page.
- `background?: "none" | "muted"` = "none": A gray well behind the section.
- `spacing?: "none" | "sm" | "md" | "lg"` = "sm": Vertical padding, as in MarketingSection.
- `divider?: boolean` = false: A hairline above the section.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link for logos with an href.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<LogoCloudSlot, string>>`: Classes for container, title, description, intro (split heading), list, item, logo and track.

Parts:
- `LOGO_CLOUD_SAMPLE` (constant): Eight fictional customers (Northwind, Globex, Initech, Umbrella Health, Stark Logistics, Wayne Studio, Hooli, Vandelay), each a lucide glyph and a styled name.
- `LogoCloudItem` (type): One logo: name, icon, href and className.
- `LogoCloudProps` (type): Props of LogoCloud.

```tsx
// app/(marketing)/page.tsx
import Link from "next/link"
import { LogoCloud, LOGO_CLOUD_SAMPLE } from "@/components/blocks/logo-cloud"

export default function HomePage() {
  return (
    <LogoCloud
      linkComponent={Link}
      layout="marquee"
      logos={LOGO_CLOUD_SAMPLE.map((logo) => ({ ...logo, href: "/customers" }))}
    />
  )
}
```

Docs: https://wingo-ui.com/components/logo-cloud (Markdown: https://wingo-ui.com/components/logo-cloud.md)

#### Marketing Footer (`marketing-footer`)

block · free · v1.0.1 · install: `npx wingo-ui@latest add marketing-footer`

The bottom of a SaaS website: brand and tagline, link columns, a newsletter signup, a status dot, legal links and social icons.

Every link is a real link with a visible focus ring; on touch each row grows to 44px. The status line pulses gently (still under reduced motion) and links to the status page. With newsletter on, the email field checks the address on submit, the button spins and a confirmation replaces the form. Social icons open in a new tab and carry their network's name for screen readers. On phones the brand spans the width, the columns sit two by two and the legal row stacks.
Wingo UI dependencies: marketing-section, marketing-header, navigation, tones, ui-config

Props:
- `variant?: "columns" | "simple" | "wordmark" | "centered"` = "columns": columns: brand, link columns and the newsletter; simple: brand and one row of links, for small sites; wordmark: the columns over the brand name in huge type, cropped by the bottom edge; centered: logo, one line of links (the first three of each column), socials and the legal line, stacked in the middle.
- `logo?: ReactNode` = "<MarketingLogo />": Replaces the sample brand.
- `columns?: MarketingFooterColumn[]` = "MARKETING_FOOTER_COLUMNS": Up to three { title, links: { label, href, badge? }[] } columns.
- `legalLinks?: MarketingFooterLink[]` = "MARKETING_FOOTER_LEGAL_LINKS": Privacy, Terms and Cookies next to the copyright.
- `socials?: MarketingFooterSocial[]` = "MARKETING_FOOTER_SOCIALS": { label, href, icon } icon links; SOCIAL_ICONS has X, GitHub, LinkedIn and YouTube.
- `newsletter?: boolean` = false: A newsletter signup next to the columns.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The newsletter's submit; a rejection shows an error. Without it the form waits 900 ms and confirms.
- `status?: boolean` = true: The status dot under the tagline.
- `statusTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": The status dot: success when all is well, warning for degraded, danger for an outage.
- `statusHref?: string` = "/status": Where the status line links; empty for plain text.
- `extra?: ReactNode`: The end of the bottom row: a theme toggle or a language switch.
- `width?: "lg" | "xl"` = "lg": The content width: lg 1200px, xl 1400px.
- `homeHref?: string` = "/": Where the logo links.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (next/link in an app); default the LinkProvider's.
- `labels?: Partial<MarketingFooterLabels>`: brand (also the wordmark), home, tagline, newsletterTitle, newsletterDescription, legal, status, socials.
- `newsletterLabels?: Partial<NewsletterFormLabels>`: Strings of the newsletter form.
- `className?: string`: Classes for the <footer>.
- `classNames?: Partial<Record<MarketingFooterSlot, string>>`: Classes for container, brand, columns, newsletter, bottom, socials and wordmark.

Parts:
- `SOCIAL_ICONS` (constant): Inline svg glyphs for x, github, linkedin and youtube (icon packs ship no company logos).
- `MARKETING_FOOTER_COLUMNS` (constant): The sample Product, Company and Resources columns.
- `MARKETING_FOOTER_LEGAL_LINKS` (constant): Privacy, Terms and Cookies.
- `MARKETING_FOOTER_SOCIALS` (constant): X, GitHub, LinkedIn and YouTube links.
- `DEFAULT_MARKETING_FOOTER_LABELS` (constant): The English strings.
- `MarketingFooterColumn` (type): { title, links }.
- `MarketingFooterProps` (type): Props of MarketingFooter.

```tsx
import Link from "next/link"
import { MarketingFooter, SOCIAL_ICONS } from "@/components/blocks/marketing-footer"

export function SiteFooter() {
  return (
    <MarketingFooter
      linkComponent={Link}
      newsletter
      onSubscribe={(email) => fetch("/api/subscribe", { method: "POST", body: JSON.stringify({ email }) })}
      socials={[{ label: "GitHub", href: "https://github.com/acme", icon: SOCIAL_ICONS.github }]}
      labels={{ legal: "© 2026 Acme Software Inc." }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/marketing-footer (Markdown: https://wingo-ui.com/components/marketing-footer.md)

#### Marketing Header (`marketing-header`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add marketing-header`

The sticky top bar of a SaaS website: logo, links with dropdown panels, Sign in and Get started, an announcement strip and a phone menu.

The bar sticks to the top and blurs the page under it. Hover or focus Product, Solutions or Resources and one shared panel morphs between their link lists (with a featured card); Escape closes it and arrow keys move between the links. The link for the current page is marked. Tab starts with a Skip to content link. The announcement strip above the bar is one link. Below 1024px the links fold into a menu button that opens a bottom sheet with every link, the panels as groups, and Sign in and Get started as full-width buttons; drag it down, tap outside or press Escape to close.

npm: lucide-react
Wingo UI dependencies: button, nav-menu, navigation, tones, ui-config

Props:
- `items?: NavMenuItem[]` = "MARKETING_NAV": The links; an item with items opens a dropdown panel (icons, descriptions, columns, a featured card).
- `logo?: ReactNode` = "<MarketingLogo />": Replaces the sample brand; it links to hrefs.home.
- `actions?: ReactNode`: Replaces Sign in and Get started (in the bar and in the phone menu).
- `mobileActions?: ReactNode`: Replaces actions in the phone menu, where they stack full width.
- `announcement?: ReactNode` = "": A strip above the bar for launch news; a link when announcementHref is set.
- `announcementHref?: string` = "/changelog": Where the announcement links to; empty for plain text.
- `currentPath?: string` = "": The current pathname, so its link is marked; default the LinkProvider's.
- `layout?: "default" | "centered" | "pill"` = "default": default is a full-width bar; centered puts the links on the left, the logo in the middle and the actions on the right; pill floats a rounded bar inset from the edges. Phones keep the bar with the menu sheet in every layout.
- `variant?: "glass" | "solid" | "transparent"` = "glass": glass blurs the page under the sticky bar, solid is opaque, transparent sits on a hero (the pill layout keeps a light blur so its links stay readable).
- `sticky?: boolean` = true: Sticks to the top while the page scrolls.
- `bordered?: boolean` = true: A hairline under the bar.
- `width?: "lg" | "xl"` = "lg": The content width: lg 1200px (like MarketingSection), xl 1400px.
- `indicator?: "pill" | "underline" | "none"` = "pill": The highlight that slides between the links.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Get started button; brand is the marketing orange.
- `skipTo?: string` = "main": The id the Skip to content link jumps to; an empty string removes the link.
- `modal?: boolean` = true: The phone menu traps focus and locks the page; false for inline previews.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link for every link (next/link in an app); default the LinkProvider's.
- `labels?: Partial<MarketingHeaderLabels>`: brand, home, signIn, getStarted, skipLink and the menu's aria labels.
- `hrefs?: Partial<MarketingHeaderHrefs>`: home, signIn and signUp.
- `className?: string`: Classes for the <header>.
- `classNames?: Partial<Record<MarketingHeaderSlot, string>>`: Classes for announcement, bar, container, logo and actions.

Parts:
- `MarketingLogo` (component): The sample brand: a mark on the neutral fill and the name. Takes span props.
- `MarketingHeaderLayout` (type): "default" | "centered" | "pill".
- `MARKETING_NAV` (constant): The sample navigation: Product and Resources panels, Solutions, Pricing, Customers, Contact.
- `DEFAULT_MARKETING_HEADER_LABELS` (constant): The English strings.
- `MarketingHeaderProps` (type): Props of MarketingHeader.

```tsx
// app/(marketing)/layout.tsx
"use client"

import Link from "next/link"
import { usePathname } from "next/navigation"
import { MarketingHeader } from "@/components/blocks/marketing-header"
import { MarketingFooter } from "@/components/blocks/marketing-footer"

export default function MarketingLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <MarketingHeader
        linkComponent={Link}
        currentPath={usePathname()}
        announcement="Acme 3.0 is here: timelines and AI summaries"
        announcementHref="/changelog"
      />
      <main id="main">{children}</main>
      <MarketingFooter linkComponent={Link} />
    </>
  )
}
```

Docs: https://wingo-ui.com/components/marketing-header (Markdown: https://wingo-ui.com/components/marketing-header.md)

#### Marketing Section (`marketing-section`)

block · free · v1.0.1 · install: `npx wingo-ui@latest add marketing-section`

The frame every marketing section sits in: a column with an eyebrow, a title and a description on one shared scale, plus a newsletter form.

A section is static: an eyebrow, a title (h2 by default, h1 for a page's first section), a description and actions, then your content under it. The column widths, paddings and type sizes are the ones every section and template uses, so pages built from parts line up. The newsletter form checks the address when you submit, shows the error under the field, spins while onSubscribe runs and swaps itself for a confirmation; Enter submits.

npm: motion, lucide-react
Wingo UI dependencies: button, input, motion, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Why Acme": The small uppercase line over the title.
- `title?: ReactNode` = "Everything your team needs, nothing it doesn't": The section title; it balances over two lines and caps at 22 characters per line.
- `description?: ReactNode` = "Plan the work, write it down and ship it, in one calm workspace that stays fast at 10 or 10,000 tasks.": The muted paragraph under the title.
- `actions?: ReactNode`: Buttons under the description; they stack full width on phones.
- `children?: ReactNode`: The section's content, placed under the heading.
- `align?: "start" | "center"` = "center": Where the heading sits.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The column: sm 720px (reading), md 960px, lg 1200px (the page width), xl 1400px.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding: sm 40 / 56px, md 56 / 96px, lg 80 / 128px (phone / desktop).
- `background?: "none" | "muted"` = "none": muted paints a gray well so the section stands apart from its neighbours.
- `divider?: boolean` = false: A hairline above the section.
- `headingSize?: "md" | "lg"` = "md": md for sections (26 / 36px titles), lg for a page's first heading (34 / 56px).
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element.
- `id?: string`: The anchor; the title gets <id>-title and labels the section.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<MarketingSectionSlot, string>>`: Classes for container, heading, eyebrow, title, description, actions and content.

Parts:
- `SectionHeading` (component): The heading on its own (eyebrow, title, description, actions), for a hero or a card. Takes div props.
- `NewsletterForm` (component): An email field and a Subscribe button that validates, spins and confirms. Takes form props.
- `DEFAULT_NEWSLETTER_LABELS` (constant): The English strings of the newsletter form.
- `MarketingSectionProps` (type): Props of MarketingSection.
- `SectionHeadingProps` (type): Props of SectionHeading.
- `NewsletterFormProps` (type): Props of NewsletterForm.

```tsx
import { Button } from "@/components/ui/button"
import { MarketingSection, NewsletterForm } from "@/components/blocks/marketing-section"

export function Newsletter() {
  return (
    <MarketingSection
      eyebrow="Newsletter"
      title="Product notes, once a month"
      description="What shipped, what is next and one thing we learned."
      width="sm"
      background="muted"
    >
      <NewsletterForm
        note="No spam. Unsubscribe in one click."
        onSubscribe={(email) => fetch("/api/subscribe", { method: "POST", body: JSON.stringify({ email }) })}
      />
    </MarketingSection>
  )
}

export function Intro() {
  return (
    <MarketingSection
      title="Everything your team needs"
      actions={<Button size="lg">Get started</Button>}
    />
  )
}
```

Docs: https://wingo-ui.com/components/marketing-section (Markdown: https://wingo-ui.com/components/marketing-section.md)

#### Newsletter Section (`newsletter-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add newsletter-section`

A newsletter or product updates signup band for a marketing page: centered, split with the latest issue, a raised card or one compact row.

Type an email and press Subscribe or Enter. An invalid address shows an error under the field; a valid one turns the button into a spinner until onSubscribe settles (or 900 ms without it), then the form gives way to an inline success line and the reader count grows by one ("You and 12,400 others"). A rejected promise shows a retry message. The privacy line links to the privacy policy. On phones the field and button stack at full width with 44px targets. In the split layout the latest issue is one link card with a focus ring; the card layout puts the form in a raised card on a gray band with the benefits beside it; the inline layout fits icon, copy and form on one row from 1024px.

npm: lucide-react
Wingo UI dependencies: marketing-section, avatar, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Newsletter": The small uppercase line over the title (not in the inline layout).
- `title?: ReactNode` = "Product notes, once a month": The section title.
- `description?: ReactNode` = "What we shipped, what we learned and how teams run their week in Acme. Five minutes to read.": The muted paragraph under the title.
- `layout?: "centered" | "split" | "card" | "inline"` = "centered": centered: heading, form and reader count in one column with the benefits in three columns below; split: copy and benefits left, the latest issue and the form in a panel right; card: a raised card on a muted band with the benefits in an inner panel; inline: icon, copy and form in one compact row.
- `bullets?: NewsletterBullet[]` = "NEWSLETTER_SECTION_SAMPLE": { icon?, title, description? } "what you get" points.
- `showBullets?: boolean` = true: The "what you get" points (the inline layout never shows them).
- `subscribers?: number` = 12400: The reader count in the social proof line; 0 hides it.
- `avatars?: string[]` = "NEWSLETTER_SECTION_AVATARS": Names drawn as stacked initials next to the count (up to four).
- `showProof?: boolean` = true: The stacked avatars and reader count.
- `issue?: NewsletterIssue` = "NEWSLETTER_SECTION_ISSUE": { title, excerpt?, date?, href? }: the latest issue, drawn as an email preview in the split layout.
- `showIssue?: boolean` = true: The latest issue card in the split layout.
- `showNote?: boolean` = true: The privacy line under the form.
- `privacyHref?: string` = "/legal/privacy": Where the privacy policy link goes.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: Runs with the trimmed email. A returned promise keeps the button loading, a rejection shows labels.failed; without it the form waits 900 ms and succeeds.
- `size?: "md" | "lg"` = "lg": The field and button height: 40 or 48px (44px minimum on touch).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Subscribe button and the icon tiles.
- `background?: "auto" | "none" | "muted"` = "auto": The band behind the section; auto is muted for the card layout and none for the others.
- `headingSize?: "md" | "lg"` = "md": lg when the section opens the page (a newsletter page); the inline layout keeps its compact title.
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, from MarketingSection.
- `locale?: string` = "en-US": Intl locale for the reader count and the issue date; default the UIProvider's locale, then en-US.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (or "a") for the privacy and issue links; default the LinkProvider's.
- `labels?: Partial<NewsletterSectionLabels>`: email, placeholder, submit, success, invalid, failed, note ({privacy}), privacy, proof ({count}), joined ({count}), readers, bulletsTitle, issueLabel, issueFrom, readIssue.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<NewsletterSectionSlot, string>>`: Classes for heading, card, panel, icon, form, note, proof, bullets, bullet and issue.

Parts:
- `NEWSLETTER_SECTION_SAMPLE` (constant): Three sample benefits: one email a month, early access, playbooks from real teams.
- `NEWSLETTER_SECTION_ISSUE` (constant): The sample latest issue, "How Northwind cut planning time in half" (Oct 1, 2026).
- `NEWSLETTER_SECTION_AVATARS` (constant): Four sample reader names for the stacked avatars.
- `DEFAULT_NEWSLETTER_SECTION_LABELS` (constant): The English strings, including the form's.
- `NewsletterBullet` (type): { icon?, title, description? }.
- `NewsletterIssue` (type): { title, excerpt?, date?, href? }.
- `NewsletterSectionLayout` (type): "centered" | "split" | "card" | "inline".
- `NewsletterSectionProps` (type): Props of NewsletterSection.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { NewsletterSection } from "@/components/blocks/newsletter-section"

export default function Home() {
  return (
    <NewsletterSection
      layout="split"
      subscribers={12400}
      onSubscribe={async (email) => {
        const res = await fetch("/api/newsletter", { method: "POST", body: JSON.stringify({ email }) })
        if (!res.ok) throw new Error("Subscribe failed")
      }}
      linkComponent={Link}
    />
  )
}
```

Docs: https://wingo-ui.com/components/newsletter-section (Markdown: https://wingo-ui.com/components/newsletter-section.md)

#### Pricing Section (`pricing-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add pricing-section`

A compact plans section for a landing page: plans with a Monthly / Yearly switch, a highlighted plan, checklists and a button each.

Flip Monthly / Yearly (tap, drag the thumb, or arrow keys) and every price rolls to its new value while the line under it switches between billed monthly and billed yearly; the Yearly option carries a Save 20% pill worked out from the prices. The recommended plan stands out (raised, outlined or filled) with a Most popular pill and the solid button. Each plan's button follows its link, or runs onSelectPlan and shows a spinner while the returned promise is pending. Under the plans a Compare all features link leads to the full pricing page. In the cards layout a phone gets a swipeable rail that opens on the featured plan, with dots to jump between plans, or stacked cards; the split, minimal and single layouts stack into one column.

npm: lucide-react
Wingo UI dependencies: marketing-section, badge, button, price, segmented-control, use-controllable-state, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Pricing": The small line over the title.
- `title?: ReactNode` = "Simple pricing that grows with your team": The section title.
- `description?: ReactNode` = "Start free and upgrade when you need more. Every plan includes unlimited tasks and docs.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `plans?: PricingSectionPlan[]` = "PRICING_SECTION_SAMPLE": The plans, in order: { id, name, description?, price: number | { monthly, yearly } (per user per month, yearly as the monthly equivalent), badge?, featured?, featuresTitle?, features?: string[], cta?: { label, href? }, note? }.
- `layout?: "cards" | "split" | "minimal" | "single"` = "cards": cards: plans side by side under the heading; split: the heading, switch and compare link on the side with the plans stacked next to it; minimal: one row per plan with its top three features, price and button; single: the featured plan in depth, with its features in a grid and the other plans in one line.
- `align?: "start" | "center"` = "center": Where the heading, switch and footer sit in the cards, minimal and single layouts. split always starts them at the side.
- `defaultPeriod?: "monthly" | "yearly"` = "monthly": The billing period shown first while uncontrolled.
- `period?: "monthly" | "yearly"`: The billing period, controlled.
- `onPeriodChange?: (period: PricingSectionPeriod) => void`: Fires when the switch changes the period.
- `showToggle?: boolean` = true: Shows the Monthly / Yearly switch. It hides by itself when no plan has a yearly price.
- `featuredPlan?: string` = "": The id of the highlighted plan, and the plan the single layout shows. Empty uses the plan marked featured (Pro in the sample).
- `featuredStyle?: "raised" | "outline" | "inverted"` = "raised": How the featured plan stands out: raised floats higher and is a little taller, outline draws a ring in the tone, inverted fills it with the tone.
- `mobileLayout?: "rail" | "stack"` = "rail": The cards layout below 768px: a swipeable snap rail that opens on the featured plan, with dots, or the cards stacked.
- `showCompare?: boolean` = true: Shows the Compare all features link under the plans.
- `compareHref?: string` = "/pricing": Where the compare link goes, usually the full pricing page.
- `animatePrice?: boolean` = true: Prices roll their digits on a period change. Reduced motion shows the new value at once.
- `currency?: string` = "USD": ISO 4217 code; amounts are in major units.
- `locale?: string` = "": BCP 47 locale for the prices. Empty uses the UIProvider locale, then the browser's.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The featured plan's ring, fill, pill and button, and the checklist ticks.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `savingsTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "success": The Save 20% pill on the Yearly option.
- `radius?: "sm" | "md" | "lg"` = "lg": Plan card corners: 12, 16 or 24px.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `onSelectPlan?: (plan: PricingSectionPlan, period: PricingSectionPeriod) => unknown`: Runs instead of following the plan's link (start a checkout); a returned promise keeps that button loading.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for plan buttons and the compare link (next/link in an app); default the LinkProvider's.
- `labels?: Partial<PricingSectionLabels>`: billingPeriod, monthly, yearly, save(percent), perMonth, billedMonthly, billedYearly, free, popular, included, otherPlans, plans, showPlan(name), compare and footnote (empty hides it).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<PricingSectionSlot, string>>`: Classes for aside, toggle, list, plan, name, badge, description, price, billing, features, feature, cta, note, dots, footer and compare.

Parts:
- `PRICING_SECTION_SAMPLE` (constant): Acme's Free, Pro ($12, featured) and Business ($24) plans, 20% off yearly.
- `DEFAULT_PRICING_SECTION_LABELS` (constant): The English strings.
- `PricingSectionPlan` (type): One plan.
- `PricingSectionProps` (type): Props of PricingSection.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { useRouter } from "next/navigation"
import { PricingSection } from "@/components/blocks/pricing-section"

export default function HomePricing() {
  const router = useRouter()
  return (
    <PricingSection
      linkComponent={Link}
      id="pricing"
      layout="cards"
      defaultPeriod="yearly"
      onSelectPlan={async (plan, period) => {
        const res = await fetch("/api/checkout", { method: "POST", body: JSON.stringify({ plan: plan.id, period }) })
        const { url } = await res.json()
        router.push(url)
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/pricing-section (Markdown: https://wingo-ui.com/components/pricing-section.md)

#### Stats Section (`stats-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add stats-section`

Big numbers with labels as plain figures, cards, hairline columns, an inverted band or a grid beside the heading, rolling up on first view.

The server and screenshots render the final numbers. The first time the list scrolls into view on the client, each number drops to zero and its digits roll up to the value (off under reduced motion or with countUp off). Numbers are formatted with the locale's group and decimal marks. Four stats sit two by two on phones and in one row from 1024px; each label is a <dt> read before its value.
Wingo UI dependencies: marketing-section, animated-counter, motion, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "": The small uppercase line over the title.
- `title?: ReactNode` = "Small teams, big numbers": The section title; an empty string hides it.
- `description?: ReactNode` = "Acme keeps 12,000 teams in sync, from the first plan to the last release note.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the description.
- `stats?: StatsSectionItem[]` = "STATS_SECTION_SAMPLE": { value, decimals?, prefix?, suffix?, label, description? }; up to four per row.
- `variant?: "plain" | "cards" | "divided" | "band" | "split"` = "plain": Bare numbers, raised cards, numbers under a hairline, band (an inverted full-width strip with huge numbers and short labels; descriptions are left out, a non-neutral tone draws an accent bar) or split (the heading on the start side, a two by two grid of figures beside it, stacked on phones; always start aligned).
- `align?: "start" | "center"` = "center": Where the heading and each stat sit.
- `size?: "md" | "lg"` = "lg": Number size: md 26 to 40px, lg 30 to 56px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The color of the numbers; neutral is the text color.
- `countUp?: boolean` = true: Rolls the numbers up once when they first scroll into view.
- `duration?: number` = 1.2: Seconds each digit takes to settle.
- `locale?: string` = "en-US": Number formatting (group and decimal marks); default the UIProvider's locale, else en-US.
- `background?: "none" | "muted"` = "none": A gray well behind the section.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, as in MarketingSection.
- `divider?: boolean` = false: A hairline above the section.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<StatsSectionSlot, string>>`: Classes for container, list, item, value, label and description.

Parts:
- `STATS_SECTION_SAMPLE` (constant): Four sample stats: 12,000+ teams, 99.99% uptime, 4.9/5 rating, 38% faster delivery.
- `StatsSectionItem` (type): One stat: value, decimals, prefix, suffix, label and description.
- `StatsSectionProps` (type): Props of StatsSection.

```tsx
// app/(marketing)/about/page.tsx
import { StatsSection } from "@/components/blocks/stats-section"

export default function AboutPage() {
  return (
    <StatsSection
      variant="cards"
      title="Acme in numbers"
      stats={[
        { value: 12000, suffix: "+", label: "Teams" },
        { value: 99.99, decimals: 2, suffix: "%", label: "Uptime" },
        { value: 38, suffix: "%", label: "Faster delivery" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/stats-section (Markdown: https://wingo-ui.com/components/stats-section.md)

#### Steps Section (`steps-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add steps-section`

A How it works section: three to five numbered steps, each with an icon, a title, a line of text and a small drawn product visual.

The horizontal layout puts the numbered steps in one row on desktop, joined by a dashed connector, with a drawn visual under each; tablets show two per row and phones one. The vertical layout runs the steps down a timeline rail with the visual beside the copy from 768px. The cards layout gives each step a raised tile with a large 01, 02, 03 numeral; a step with an href turns its tile into one link that lifts on hover and shows the focus ring around the tile. The tabs layout is a step picker beside a large visual: click a step, or focus the picker and use the arrow keys, Home and End, and the visual swaps with a short fade (no movement under reduced motion); on phones the picker becomes a row of numbered pills that scrolls sideways, with the copy above the visual.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, avatar, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "How it works": The small line over the title.
- `title?: ReactNode` = "From sign-up to shipped in an afternoon": The section title.
- `description?: ReactNode` = "Four steps to move your team onto Acme. No migration project, no consultants.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `steps?: StepsSectionItem[]` = "STEPS_SECTION_SAMPLE": Each step: icon, title, description, and optionally meta (a pill such as 2 minutes), href and visual. Three to five read best.
- `layout?: "horizontal" | "vertical" | "cards" | "tabs"` = "horizontal": horizontal: a numbered row joined by a dashed connector, visuals underneath; vertical: a timeline rail on the left, the visual beside the copy from 768px; cards: raised tiles with large numerals; tabs: a step picker beside one large visual that swaps.
- `marker?: "solid" | "soft" | "outline"` = "solid": The look of the numbered circles (horizontal, vertical and the selected tab).
- `showVisuals?: boolean` = true: The drawn visual per step. The tabs layout always shows it.
- `align?: "start" | "center"` = "center": Where the heading sits.
- `radius?: "sm" | "md" | "lg"` = "lg": Corners of the tiles, visual wells and the tabs panel: 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Markers, icon tiles, the connector and the accents in the drawn visuals.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `defaultValue?: number` = 0: Tabs: the index of the step selected at first.
- `value?: number`: Tabs: the selected step's index, controlled.
- `onValueChange?: (index: number) => void`: Tabs: fires with the index of the step picked.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for step links (next/link in an app); default the LinkProvider's.
- `labels?: Partial<StepsSectionLabels>`: step (Step {n}), stepOf (Step {n} of {total}), learnMore and tabs (the picker's accessible name).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<StepsSectionSlot, string>>`: Classes for list, item, marker, connector, icon, body, title, description, meta, link, visual, tabs, tab and panel.

Parts:
- `STEPS_SECTION_SAMPLE` (constant): Four Acme steps (connect your tools, plan the sprint, automate the busywork, ship and measure) with drawn visuals.
- `DEFAULT_STEPS_SECTION_LABELS` (constant): The English strings.
- `StepsSectionItem` (type): One step.
- `StepsSectionProps` (type): Props of StepsSection.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { Plug, Rocket, Users } from "lucide-react"
import { StepsSection } from "@/components/blocks/steps-section"

export default function HomePage() {
  return (
    <StepsSection
      linkComponent={Link}
      layout="tabs"
      eyebrow="Getting started"
      title="Up and running in three steps"
      steps={[
        { icon: <Plug />, title: "Connect your tools", description: "Slack, GitHub and your calendar in two clicks.", visual: "connect", href: "/integrations" },
        { icon: <Users />, title: "Plan the sprint", description: "Owners, due dates and load per person.", visual: "plan" },
        { icon: <Rocket />, title: "Ship and measure", description: "Cycle time and throughput update on their own.", visual: "ship" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/steps-section (Markdown: https://wingo-ui.com/components/steps-section.md)

#### Team Section (`team-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add team-section`

The people behind a product: portrait cards, tall portrait cards, a compact roster or a list with bios, plus a "We're hiring" tile.

A static section: each person shows a photo or their initials, name, role and a short bio. Social icons open the profile in a new tab and are named for screen readers ("Emma Carter on LinkedIn"); on touch they grow to 44px. The "We're hiring" tile is one link to the careers page with a focus ring around the whole tile; it fills what is left of the last row, or spans the row as a banner. Columns drop to two on tablets and one on phones; list rows stack the bio under the name on phones. Cards give each person a tall portrait panel with large initials over a faint dot pattern (or their photo).

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-footer, avatar, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Our team": The small uppercase line over the title.
- `title?: ReactNode` = "The people building Acme": The section title.
- `description?: ReactNode` = "Eight people in New York and across three US time zones, shipping something new every week since 2021.": The muted paragraph under the title.
- `actions?: ReactNode`: Buttons under the description.
- `members?: TeamMember[]` = "TEAM_SECTION_SAMPLE": { name, role, bio?, avatar?, socials?: { label, href, icon }[] }; initials show without an avatar url.
- `layout?: "grid" | "compact" | "list" | "cards"` = "grid": grid: portrait cards; compact: small avatar, name and role; list: large rows with the bio and socials; cards: large cards with a tall portrait (big initials on a tinted, patterned panel, or the photo), name, role and socials.
- `columns?: 2 | 3 | 4` = "4": Columns from 1024px for grid, cards and compact (two on tablets, one on phones).
- `showBio?: boolean` = true: The short bio (grid and list).
- `showSocials?: boolean` = true: The social icon links (grid, cards and list).
- `colorful?: boolean` = true: Initials on a color picked from the name; off keeps them neutral.
- `hiring?: boolean` = true: The "We're hiring" tile after the people.
- `openRoles?: number` = 4: The open roles count on the hiring tile.
- `hiringHref?: string` = "/careers": Where the hiring tile links.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hiring tile's plus disc and roles badge.
- `align?: "start" | "center"` = "center": Where the heading sits.
- `headingSize?: "md" | "lg"` = "md": lg when the section opens the page.
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element.
- `width?: "auto" | "sm" | "md" | "lg" | "xl"` = "auto": The column; auto picks by layout (list md 960px, the others lg 1200px).
- `background?: "none" | "muted"` = "none": muted: a gray band that sets the section apart.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, from MarketingSection.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (or "a") for the hiring tile; default the LinkProvider's.
- `labels?: Partial<TeamSectionLabels>`: hiringTitle, hiringDescription, hiringRoles / hiringRole ({count}), hiringAction, social ({name} on {network}).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<TeamSectionSlot, string>>`: Classes for list, member, avatar, portrait (cards), name, role, bio, socials and hiring.

Parts:
- `TEAM_SECTION_SAMPLE` (constant): The eight Acme people with roles, bios and social links.
- `DEFAULT_TEAM_SECTION_LABELS` (constant): The English strings.
- `TeamMember` (type): { name, role, bio?, avatar?, socials? }.
- `TeamMemberSocial` (type): { label, href, icon }, the footer's social link shape; icons from SOCIAL_ICONS.
- `TeamSectionProps` (type): Props of TeamSection.

```tsx
// app/(marketing)/about/page.tsx
"use client"

import Link from "next/link"
import { SOCIAL_ICONS } from "@/components/blocks/marketing-footer"
import { TeamSection, type TeamMember } from "@/components/blocks/team-section"

const team: TeamMember[] = [
  {
    name: "Emma Carter",
    role: "Co-founder & CEO",
    bio: "Ran product at two startups before starting Acme.",
    avatar: "/team/emma.jpg",
    socials: [{ label: "LinkedIn", href: "https://www.linkedin.com/in/emmacarter", icon: SOCIAL_ICONS.linkedin }],
  },
  { name: "Liam Brooks", role: "Co-founder & CTO" },
]

export default function AboutPage() {
  return <TeamSection members={team} columns={3} openRoles={2} linkComponent={Link} />
}
```

Docs: https://wingo-ui.com/components/team-section (Markdown: https://wingo-ui.com/components/team-section.md)

#### Testimonials Section (`testimonials-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add testimonials-section`

Customer quotes with people, ratings and results: a grid, featured quote, marquee, carousel, wall of love or one large quote.

Each quote is a card with an optional result ("-38% cycle time"), stars, the quote and the person with their avatar (initials when there is no photo), role and company. Grid lays the cards out in masonry columns; featured puts one large quote with the company and its result beside two small ones. Marquee scrolls two rows in opposite directions; hovering or focusing a row pauses it, and the round button below pauses and resumes both (paused rows scroll sideways by hand). Under reduced motion the rows start paused. Carousel is a swipeable rail with dots and, on desktop, arrows; the arrow keys move it when it has focus. Wall packs many compact cards in mixed formats (a result on an inverted card, a social post with a handle and a date, a short quote) into dense columns that fade out at the bottom; Show more reveals the rest and Show less folds it again. Quote shows one large quote with an oversized quotation mark, the person, their company and result; the round buttons, the dots (a counter on phones) and the arrow, Home and End keys switch quotes with a short cross-fade, and nothing plays on its own.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, avatar, button, carousel, motion, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Customers": The small line over the title.
- `title?: ReactNode` = "Loved by teams that ship": The section title.
- `description?: ReactNode` = "From five-person startups to 40-clinic health networks, teams plan, write and ship with Acme.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `testimonials?: Testimonial[]` = "TESTIMONIALS_SAMPLE": Each quote: quote, name, role, company, companyIcon, avatar, rating, metric, handle and date. The wall without a list adds TESTIMONIALS_WALL_EXTRA between the samples.
- `layout?: "grid" | "featured" | "marquee" | "carousel" | "wall" | "quote"` = "grid": grid: masonry columns; featured: one big quote and two small; marquee: two moving rows; carousel: a swipeable rail; wall: a dense wall of love of mixed compact cards with Show more; quote: one large quote at a time with dots and arrows.
- `columns?: 2 | 3` = 3: Grid columns from 1024px; tablets show two, phones one. The wall adds one more column (3 from 1024px, 4 from 1280px).
- `align?: "start" | "center"` = "center": Where the heading sits.
- `card?: "raised" | "flat"` = "raised": A raised white card or a flat tint.
- `radius?: "sm" | "md" | "lg"` = "md": Card corners: 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Stars and result figures.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `showRating?: boolean` = true: Shows the stars of quotes that have a rating.
- `showMetric?: boolean` = true: Shows the result of quotes that have a metric.
- `duration?: number` = 60: Marquee: seconds for one full loop; lower is faster.
- `autoplay?: boolean` = true: Marquee: the rows move on their own; false shows still rails you scroll by hand.
- `showPause?: boolean` = true: Marquee: a pause and play button under the rows.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `labels?: Partial<TestimonialsLabels>`: rating (the stars' spoken label), pause, play, carousel (the rail's name), showMore and showLess (wall), previous, next, goTo and position (quote).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<TestimonialsSlot, string>>`: Classes for list, card, featured, rating, metric, quote, author, avatar, company, marquee, row, pause, wall, more, spotlight and controls.

Parts:
- `TESTIMONIALS_SAMPLE` (constant): Eight quotes from people at Northwind, Globex, Wayne Studio, Umbrella Health, Stark Logistics, Initech, Hooli and Vandelay.
- `TESTIMONIALS_WALL_EXTRA` (constant): Eight short notes the wall mixes between the sample quotes when no list is given.
- `DEFAULT_TESTIMONIALS_LABELS` (constant): The English strings.
- `Testimonial` (type): One quote.
- `TestimonialsSectionProps` (type): Props of TestimonialsSection.

```tsx
// app/(marketing)/customers/page.tsx
import { TestimonialsSection } from "@/components/blocks/testimonials-section"

export default function CustomersPage() {
  return (
    <TestimonialsSection
      layout="featured"
      eyebrow="Customers"
      title="Teams that left spreadsheets behind"
      testimonials={[
        {
          quote: "We planned our whole launch in Acme and shipped two weeks early.",
          name: "Rachel Kim",
          role: "VP of Engineering",
          company: "Northwind",
          rating: 5,
          metric: { value: "-38%", label: "cycle time" },
        },
        { quote: "Status updates just happen now.", name: "Marcus Webb", role: "Head of Product", company: "Globex" },
        { quote: "Handoffs went from a meeting to a comment.", name: "Priya Shah", role: "Design Director", company: "Wayne Studio" },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/testimonials-section (Markdown: https://wingo-ui.com/components/testimonials-section.md)

#### Timeline Section (`timeline-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add timeline-section`

A marketing section that tells the company story as milestones on a vertical rail, a zigzag around a center line or a horizontal scroller.

Read the milestones in order: each one has a marker on the line (an icon tile or a dot), its year, a title, a short paragraph and an optional stat. The current milestone gets a solid marker with a soft pulse and a Now pill. A milestone with an href turns its whole card into one link (Read the story) that lifts on hover and shows the focus ring around the card when tabbed to. In the vertical layout the big years sit in a column beside the rail and stick while their card scrolls past; the alternating layout zigzags the cards around a center line with the year facing each card, and falls back to the rail on phones. The horizontal layout is a snap scroller: swipe, scroll, focus it and use the arrow keys, or press the round previous and next buttons; the progress line under it fills as you go. Reduced motion stops the pulse and makes the arrow buttons jump instead of glide.

npm: lucide-react, motion
Wingo UI dependencies: marketing-section, badge, button, use-scroll-edges, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Our story": The small line over the title.
- `title?: ReactNode` = "From a Brooklyn apartment to 100,000 teams": The section title.
- `description?: ReactNode` = "Five years of building the calm workspace where small teams plan, write and ship.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `milestones?: TimelineSectionMilestone[]` = "TIMELINE_SECTION_SAMPLE": Each milestone: year, title, description, and optionally icon, stat { value, label }, href (the card becomes a link) and current.
- `layout?: "vertical" | "alternating" | "horizontal"` = "vertical": vertical: a rail with the cards on one side and big sticky years on the other (years move into the cards on phones); alternating: cards zigzag left and right of a center line from 768px, a rail on phones; horizontal: a snap scroller with a progress line and previous / next buttons.
- `align?: "start" | "center"` = "center": Where the heading sits.
- `marker?: "icon" | "dot"` = "icon": The marker on the line: a round tile with the milestone icon, or a small ring. Milestones without an icon get the ring.
- `card?: "raised" | "flat" | "none"` = "raised": The surface behind each milestone: a raised card, a flat tint or nothing.
- `radius?: "sm" | "md" | "lg"` = "lg": Card corners: 12, 16 or 24px.
- `showStats?: boolean` = true: Shows each milestone's stat under a hairline.
- `pulse?: boolean` = true: A soft pulse around the current milestone's marker (off under reduced motion).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Markers, the small years, stat values and the progress line.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `background?: "none" | "muted"` = "none": muted sets the section on a gray band.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding of the section.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px. The vertical rail stays at most 880px wide.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for card links (next/link in an app); default the LinkProvider's.
- `labels?: Partial<TimelineSectionLabels>`: learnMore (the link line), now (the pill on the current milestone), list (the list's accessible name), previous and next (the scroller buttons).
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<TimelineSectionSlot, string>>`: Classes for list, item, rail, marker, connector, year, card, title, description, stat, statValue, statLabel, link, now, progress and controls.

Parts:
- `TIMELINE_SECTION_SAMPLE` (constant): Six Acme milestones from 2021 (founded in New York) to 2026 (100,000 teams), with icons and stats.
- `DEFAULT_TIMELINE_SECTION_LABELS` (constant): The English strings.
- `TimelineSectionMilestone` (type): One milestone.
- `TimelineSectionProps` (type): Props of TimelineSection.

```tsx
// app/(marketing)/about/page.tsx
"use client"

import Link from "next/link"
import { Flag, Rocket, Users } from "lucide-react"
import { TimelineSection } from "@/components/blocks/timeline-section"

export default function AboutPage() {
  return (
    <TimelineSection
      linkComponent={Link}
      layout="alternating"
      eyebrow="Our story"
      title="How we got here"
      milestones={[
        { year: "2023", icon: <Flag />, title: "Day one", description: "Three friends, one idea and a borrowed desk." },
        { year: "2024", icon: <Users />, title: "First hires", description: "The team grows to twelve.", stat: { value: "12", label: "people" } },
        { year: "2025", icon: <Rocket />, title: "Launch", description: "Version 1.0 ships to everyone.", href: "/blog/launch", current: true },
      ]}
    />
  )
}
```

Docs: https://wingo-ui.com/components/timeline-section (Markdown: https://wingo-ui.com/components/timeline-section.md)

#### Video Section (`video-section`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add video-section`

A product video block with no video file: a drawn poster whose play button opens an animated, chaptered walkthrough.

The poster is a browser window drawn in code with a small Acme board inside, a round play button and a "Watch the tour" pill with the length; the ring around the play button breathes (off with reduced motion or pulse off). Click or tap the poster (Enter or Space on the keyboard) to open the tour in a dialog, a bottom sheet below 768px; clicking a chapter opens it at that chapter. With no media the dialog plays a drawn walkthrough: each chapter animates its own scene (cards move on the board, a spec writes itself, an automation runs step by step, a chart grows), a segmented bar fills and the clock counts through the chapter's real timestamps, then it moves to the next chapter and offers Replay at the end. Previous, play / pause and next buttons sit under the stage, the chapter list beside it (under it on phones) jumps to any chapter, and the arrow keys skip chapters while K plays or pauses. Chapter changes are announced to screen readers. With reduced motion the tour starts paused and scenes appear without movement. Escape, the close button or a drag down on the sheet close it and focus returns to what opened it. Layouts: centered puts chapter cards under the player; split keeps the heading and a chapter list beside the player; chapters places a chapter panel with descriptions next to the player (under it on phones).

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, avatar, button, dialog, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `eyebrow?: ReactNode` = "Product tour": The small line over the title.
- `title?: ReactNode` = "See a launch come together in Acme": The section title.
- `description?: ReactNode` = "Watch one team plan, write, automate and ship a release, start to finish. Jump to any chapter.": The paragraph under the title.
- `actions?: ReactNode`: Buttons under the heading.
- `chapters?: VideoSectionChapter[]` = "VIDEO_SECTION_SAMPLE": { title, description?, start (seconds), scene?, id? }; scene is plan, docs, automate, insights or any node drawn inside the app frame.
- `media?: ReactNode`: What the dialog shows instead of the drawn walkthrough: a <video>, an embed iframe. It sits in a 16:9 frame.
- `poster?: ReactNode`: Replaces the drawn browser poster behind the play button.
- `duration?: number` = 150: The tour length in seconds: the play pill, the chapter panel and the end of the last chapter.
- `caption?: ReactNode` = "One launch, from the first task to shipped, in two and a half minutes.": The line under the player.
- `guideHref?: string` = "/docs": A link after the caption (labels.guide); empty hides it.
- `url?: string` = "app.acme.com/launch": The address in the drawn browser bar.
- `layout?: "centered" | "split" | "chapters"` = "centered": centered: the player under the heading with chapter cards below; split: the heading and a chapter list on the left, the player on the right (stacked on phones); chapters: the player with a raised chapter panel beside it from 1024px.
- `showChapters?: boolean` = true: The chapter cards, list or panel next to the player.
- `frame?: "browser" | "none"` = "browser": browser: a window bar with dots and the url over the drawn app; none: the app alone.
- `radius?: "md" | "lg" | "xl"` = "lg": The player corners: 16, 24 or 32px (the chapter panel follows).
- `pulse?: boolean` = true: A ring that breathes around the play button (off with reduced motion).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The play button, chapter timestamps, the progress bar and the accents in the drawn app.
- `color?: string` = "": Any CSS color; replaces the tone. Leave empty to use the tone.
- `align?: "start" | "center"` = "center": Where the heading sits (split always starts).
- `open?: boolean`: The dialog's open state (controlled).
- `defaultOpen?: boolean` = false: The tour starts open.
- `onOpenChange?: (open: boolean) => void`: Runs when the dialog opens or closes.
- `onChapterChange?: (index: number) => void`: Runs when the walkthrough moves to another chapter.
- `headingSize?: "md" | "lg"` = "md": lg when the section opens the page.
- `headingAs?: "h1" | "h2" | "h3"` = "h2": The title element.
- `width?: "sm" | "md" | "lg" | "xl"` = "lg": The content column: 720, 960, 1200 or 1400px.
- `background?: "none" | "muted"` = "none": muted: a gray band that sets the section apart.
- `spacing?: "none" | "sm" | "md" | "lg"` = "md": Vertical padding, from MarketingSection.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "\"a\"": The router link (or "a") for the guide link; default the LinkProvider's.
- `labels?: Partial<VideoSectionLabels>`: watch, chapters, chapterCount ({count}), dialogTitle, dialogDescription, play, pause, replay, previous, next, progress, status ({index}, {total}, {title}), guide.
- `className?: string`: Classes for the <section>.
- `classNames?: Partial<Record<VideoSectionSlot, string>>`: Classes for layout, figure, player, poster, play, caption, chapters, chapter, walkthrough, stage and controls.

Parts:
- `VIDEO_SECTION_SAMPLE` (constant): Four Acme chapters: plan the launch, write the spec, automate the handoffs, track what shipped.
- `DEFAULT_VIDEO_SECTION_LABELS` (constant): The English strings.
- `VideoSectionChapter` (type): { title, description?, start, scene?, id? }.
- `VideoSectionScene` (type): The drawn scenes: plan, docs, automate, insights.
- `VideoSectionLayout` (type): "centered" | "split" | "chapters".
- `VideoSectionFrame` (type): "browser" | "none".
- `VideoSectionRadius` (type): "md" | "lg" | "xl".
- `VideoSectionLabels` (type): The strings of DEFAULT_VIDEO_SECTION_LABELS.
- `VideoSectionSlot` (type): The classNames keys.
- `VideoSectionProps` (type): Props of VideoSection.

```tsx
// app/(marketing)/product/page.tsx
"use client"

import Link from "next/link"
import { VideoSection, VIDEO_SECTION_SAMPLE } from "@/components/blocks/video-section"

export default function ProductPage() {
  return (
    <VideoSection
      layout="chapters"
      chapters={VIDEO_SECTION_SAMPLE}
      duration={150}
      // leave media out to play the drawn walkthrough
      media={<video src="/tour.mp4" controls autoPlay className="size-full object-cover" />}
      linkComponent={Link}
    />
  )
}
```

Docs: https://wingo-ui.com/components/video-section (Markdown: https://wingo-ui.com/components/video-section.md)

### Blocks

#### Admin Dashboard Page (`admin-dashboard-page`)

block · Pro · v1.2.0 · install: `npx wingo-ui@latest add admin-dashboard-page`

The home of a back office: greeting and period, four KPIs, revenue against the previous period, recent orders, alerts and team activity.

Pick the period in the date range field (presets such as Last 7 days or Last month beside two months on desktop, a bottom sheet on phones): every panel fades to the new numbers, the KPI values count to theirs and the chart grows again. Each KPI tile is a link with a spoken name ("Revenue, $248,300, up 12.4%"); the (i) buttons explain revenue and conversion. Switch the revenue chart between Daily and Weekly (weekly needs 14 days or more), hover, tap or arrow through its points to read both periods, and click a legend entry to hide a series. The Needs attention rows are links with a count. In Recent orders, search by number or client, toggle the New, Shipping and Unpaid chips, sort by a header, select rows for the bulk bar (Confirm, Export, Cancel), open a row's menu (View, Confirm order, Print label, Cancel; Shift+F10 on a focused row) or click a row, or press Enter on it, to open the order sheet: its status, the delivery tracker with the carrier and tracking number, the products, the client and the payment, with Confirm order, Print label and Cancel in the footer. Confirming shows a spinner in the row's badge while it saves; cancelling asks first, then offers Undo in a toast for 5 seconds. The sheet slides in from the right (a tall bottom sheet on phones, drag the handle down to close), Escape closes it and focus returns to the row. On phones the orders are cards with Load more, the header keeps the period field, a + button and a menu with Export, and the KPIs sit two by two. Sections rise in once on mount; reduced motion keeps everything still.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, area-chart, avatar, badge, button, data-table, date-range-picker, description-list, dropdown-menu, empty-state, line-chart, list, order-tracker, page-header, segmented-control, sheet, sparkline, stat-card, table, timeline, toast, use-controllable-state, use-media-query, commerce, date-utils, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `userName?: string` = "Anna": The name in the greeting ("Hi, Anna").
- `children?: ReactNode`: Extra sections after the built-in rows (more charts, a funnel, a table), in the page column; they rise in with the rest.
- `period?: DateRange`: The reporting period, controlled; pair it with onPeriodChange.
- `defaultPeriod?: DateRange`: The period while uncontrolled; defaults to August 26 to September 24, 2026. A change regenerates the sample through generateDashboardData when the data props are not given.
- `onPeriodChange?: (period: DateRange) => void`: Called when a complete range is applied in the date field.
- `presets?: DateRangePreset[]`: The quick ranges beside the calendar ({ key, label, value }). Defaults to Last 7 days, Last 30 days, This month, Last month, This quarter and This year, measured from now.
- `kpis?: DashboardKpi[]`: The four tiles ({ id, label, value, format, delta, deltaFormat, sparkline, goal, href, info, icon, tone, caption }); defaults to the sample for the period (ADMIN_DASHBOARD_SAMPLE.kpis). A null value shows a dash. Every card in the row keeps one anatomy: when any card has a sparkline the others get a flat baseline in its place, and when any has a delta the others show caption (default labels.noComparison). A zero change reads No change.
- `revenue?: { date: string; current: number | null; previous: number | null }[]`: Daily revenue for the chart, ISO days; defaults to the sample for the period (ADMIN_DASHBOARD_SAMPLE.revenue).
- `orders?: DashboardOrder[]`: The recent orders ({ id, number, client, date, status, payment, paid, total, items, courier, awb }); defaults to the 40 newest orders of the period (ADMIN_DASHBOARD_SAMPLE.orders).
- `recent?: ReactNode`: Your own content for the recent panel (a table of payments or sign-ups); replaces the orders table. The panel keeps its title (labels.orders) and See all link (ordersHref).
- `tasks?: DashboardTask[]`: The Needs attention rows ({ id, title, description, tone, href, count, icon }); defaults to ADMIN_DASHBOARD_SAMPLE.tasks. An empty list shows "All good".
- `activity?: TimelineItemData[]`: The team feed with actors and times; defaults to ADMIN_DASHBOARD_SAMPLE.activity (8 items).
- `topProducts?: { id; title; quantity; revenue; trend? }[]`: The Products sold table, with a 14 day sparkline from trend; defaults to the five Summit CRM products of the sample.
- `compare?: boolean` = true: The dashed previous-period series, the revenue change and the KPI deltas.
- `chartType?: "area" | "line"` = "area": The revenue chart: AreaChart, or LineChart with a soft area.
- `granularity?: "day" | "week"`: The revenue grouping, controlled; pair it with onGranularityChange.
- `defaultGranularity?: "day" | "week"` = "day": The revenue grouping while uncontrolled; week falls back to days for periods under 14 days.
- `onGranularityChange?: (granularity: DashboardGranularity) => void`: Called when the Daily / Weekly switch changes.
- `showAttention?: boolean` = true: The Needs attention panel beside the chart.
- `attentionEmpty?: "compact" | "panel" (AdminDashboardPageAttentionEmpty)` = "compact": With no tasks (tasks=[]): a slim "All good" strip above the revenue row, with the chart taking the full width, or the full Needs attention panel with its empty state. With tasks the panel always shows.
- `kpiIcons?: boolean` = true: Tinted icon tiles on the KPI cards: kpi.icon and kpi.tone, else an icon and a tone picked from the id (revenue orange, orders blue, clients green, conversion amber).
- `chartTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"`: The revenue line's color. Unset, it follows tone (neutral: the chart's first series color); the previous period stays a muted dashed line.
- `showActivity?: boolean` = true: The team activity feed.
- `showTopProducts?: boolean` = true: The Products sold table.
- `topProductsColumns?: ("quantity" | "revenue" | "trend")[]` = "[\"quantity\", \"revenue\", \"trend\"]": The value columns of the top table, in order. The first one is the phone card's value; ["quantity"] turns it into a plain ranking (installs, views).
- `ordersPageSize?: number` = 8: Orders per page on desktop, and per load on phones.
- `onOrderAction?: (action: DashboardOrderAction, order: DashboardOrder) => (void | Promise<unknown>)`: Runs a row, bulk or sheet action (confirm, cancel or print). The status changes at once and the row shows a spinner until the promise settles; a rejection rolls it back with an error toast. Without it the page waits 900 ms and toasts.
- `onExport?: (period: DateRange) => (void | Promise<unknown>)`: The Export action; a promise keeps the button loading. Without it a toast confirms the export.
- `onCreateOrder?: () => (void | Promise<unknown>)`: The New order action. Without it a toast stands in for the form.
- `orderSheet?: boolean` = true: A row click opens the order sheet; false only calls onOrderClick.
- `onOrderClick?: (order: DashboardOrder) => void`: Called when a row or its View action is chosen (before the sheet opens).
- `defaultOpenOrder?: string` = "": An order id whose sheet is open on mount (o1042 is the one in delivery).
- `ordersHref?: string` = "/orders": Where the orders panel's See all goes.
- `activityHref?: string` = "/activity": Where the activity panel's See all goes.
- `labels?: Partial<AdminDashboardPageLabels>`: Every visible string (English, DEFAULT_ADMIN_DASHBOARD_PAGE_LABELS; ADMIN_DASHBOARD_PAGE_LABELS_EN is the same set). Nested keys (statCard, chart, dateRange, ordersTable, table, list, timeline, orderTracker, sparkline) translate the composed items.
- `locale?: string` = "en-US": Intl locale for numbers, money and dates.
- `currency?: string` = "USD": ISO 4217 code for the KPIs, the chart, the orders and the products.
- `now?: Date | number`: The reference time for today, the presets and the relative times; default the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary actions, the KPI sparklines and goal bar, the chart's current series and the date selection.
- `radius?: "sm" | "md" | "lg"` = "md": Corner size of the KPI tiles and the panels (12 / 16 / 24px).
- `loading?: boolean` = false: Skeletons in the real layout: the header, the tiles, the chart, the rows and the feed.
- `animateIn?: boolean` = true: Sections rise in once when the page mounts on the client; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the panel links and the attention rows; default the surrounding LinkProvider's (the admin shell's).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<AdminDashboardPageSlot, string>>`: Classes for header, kpis, row, revenue, attention, orders, top, activity and orderSheet.

```tsx
// app/(admin)/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell>{children}</AdminShell>)
"use client"

import { useRouter } from "next/navigation"
import { AdminDashboardPage } from "@/components/blocks/admin-dashboard-page"

export default function HomePage() {
  const router = useRouter()
  return (
    <AdminDashboardPage
      userName="Anna"
      onCreateOrder={() => router.push("/orders/new")}
      onOrderAction={async (action, order) => {
        await fetch(`/api/orders/${order.id}/${action}`, { method: "POST" })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/admin-dashboard-page (Markdown: https://wingo-ui.com/components/admin-dashboard-page.md)

#### Admin Shell (`admin-shell`)

block · Pro · v1.1.0 · install: `npx wingo-ui@latest add admin-shell`

The back office layout of Summit CRM: a sidebar with workspaces, a top bar with search and notifications, a command menu and phone tabs.

The sidebar lists the navigation in groups with counts; the active page carries a pill and aria-current, and a record route such as /clients/northwind-tech keeps its section active. The workspace card at the top opens the switcher: picking another workspace spins its row for a moment, switches and confirms with a toast. The account card at the bottom opens the user menu (profile, settings, billing, help, the theme and sign out). Press mod+b or the toggle in the sidebar footer to collapse it to an icon rail with tooltips and flyouts, drag its edge to resize it (double click resets) or use the arrow keys on the handle. The top bar shows the page title or a breadcrumb, the search field (press / to focus it; results for clients, contacts, deals and invoices appear as you type, arrows and Enter open one), the notification bell (tabs for all, unread and mentions, mark as read, swipe to dismiss) and the theme toggle. mod+k opens the command menu: go to any page, create a client, invoice or deal, invite a colleague, switch the theme or toggle the sidebar. Below 1024px the sidebar becomes a drawer behind the menu button, the top bar turns compact with a centered title, a search icon that opens a full screen search, the bell (a sheet) and your avatar, and a five tab bar sits on the bottom edge above the safe area; its More tab opens the drawer and the top bar slides away while you scroll down. The skip link (Skip to content) is the first stop for keyboard users. design="rail" keeps the sidebar on its icon rail (hover or focus an icon for its name); design="topbar" moves the nav into the top bar as tabs, where the arrow keys move between tabs and the More menu holds the ones that do not fit.

npm: lucide-react
Wingo UI dependencies: app-shell, badge, bottom-tab-bar, breadcrumb, button, command-menu, dropdown-menu, global-search, notification-center, sidebar, theme-toggle, toast, topbar, user-menu, workspace-switcher, use-controllable-state, commerce, form-validation, navigation, tones, ui-config

Props:
- `children?: ReactNode`: The page, rendered once inside main (never twice for phone and desktop).
- `nav?: SidebarNavGroup[]`: The sidebar groups (ADMIN_SHELL_SAMPLE.nav: Home, AI assistant; Sales with Clients 128, Contacts, Deals 12, Orders; Finance with Invoices 3 overdue, Reports; Operations; Settings and Help). Also feeds the command menu's Go to group.
- `tabs?: BottomTabBarItem[]`: The phone tab bar, 3 to 5 items (ADMIN_SHELL_SAMPLE.tabs: Home, Clients, Deals, Invoices, More). An item with id "more" and no href opens the drawer. [] hides the bar.
- `currentPath?: string` = "/": The active route (next: usePathname()). Selects the nav item, the tab and the default title; nested routes match by prefix.
- `title?: ReactNode` = "": The top bar title. Empty uses the active nav item's label, or labels.appName when no item matches.
- `breadcrumb?: BreadcrumbEntry[]`: Replaces the title with a breadcrumb (record pages: Clients / Northwind Tech Inc.). Phones show the last entry as the title.
- `actions?: ReactNode`: Extra top bar actions before the notifications, such as a New button.
- `banner?: ReactNode`: A strip above everything, usually a Banner (trial ending, maintenance). Hidden when printing.
- `workspaces?: Workspace[]`: The switcher's list (ADMIN_SHELL_SAMPLE.workspaces: Summit Software Inc., Summit Logistics, Personal). One workspace hides the chevron; none shows the logo instead.
- `workspace?: string`: The active workspace id, controlled. Pair it with onWorkspaceChange.
- `defaultWorkspace?: string` = "summit-software": The workspace selected at first, uncontrolled.
- `onWorkspaceChange?: (id: string, workspace: Workspace) => (void | Promise<unknown>)`: Runs when a workspace is picked. A returned promise keeps the row spinning; once it resolves the switch happens and a toast confirms it, a rejection keeps the old workspace and shows an error toast. Without it a 700 ms request is simulated.
- `user?: { name: string; email: string; avatar?: string; plan?: string } | null`: The signed-in person for the sidebar card and the phone avatar menu (ADMIN_SHELL_SAMPLE.user: Anna Price, Administrator). null shows a sign-in button.
- `userMenuItems?: MenuEntry[]`: The account menu entries above sign out. Default: Profile, Settings, Billing, Help and a separator, navigating through the router.
- `onSignOut?: () => (void | Promise<unknown>)`: The sign-out row; a promise keeps the menu open with a spinner and a rejection shows an error toast. Default: a toast "You signed out".
- `signInHref?: string` = "/sign-in": Where the sign-in button points while there is no user.
- `notifications?: NotificationItem[]`: The bell's inbox (ADMIN_SHELL_SAMPLE.notifications: an overdue invoice, a mention, a payment, a won deal, an import and an accepted invite; 3 unread). Read, unread and dismiss are handled by the notification center.
- `onNotificationSelect?: (item: NotificationItem) => void`: Opening a notification. Default: it turns read and navigates to its href through the router.
- `search?: boolean` = true: The global search in the top bar (an icon that opens a full screen search on phones).
- `searchResults?: SearchResultGroup[]`: Static results filtered as you type (ADMIN_SHELL_SAMPLE.searchResults: clients, contacts, deals and invoices, grouped).
- `loadSearch?: (query: string, context: { signal: AbortSignal; scope: string }) => Promise<SearchResultGroup[]>`: Server search instead of searchResults: debounced, the previous request aborted.
- `searchSuggestions?: SearchResult[]`: Quick links while the search is empty (Overdue invoices, Deals in negotiation, Clients in Chicago).
- `searchShortcut?: string` = "/": Focuses the search (opens it on phones). "" binds nothing.
- `commandMenu?: boolean` = true: The command palette: every nav page, the actions (client, invoice, deal, invite), the theme and the sidebar toggle.
- `commands?: CommandGroup[]`: The palette's root groups. Default: Go to (built from nav) and Actions (ADMIN_SHELL_SAMPLE.commands). The Appearance group is always added.
- `commandShortcut?: string` = "mod+k": Opens the command menu. "" binds nothing.
- `sidebarShortcut?: string` = "mod+b": Toggles the sidebar: the rail on desktop (classic design), the drawer on phones. "" binds nothing.
- `design?: "classic" | "rail" | "topbar"` = "classic": classic: the sidebar with workspaces and the account card. rail: a fixed 64px icon rail with tooltips and flyouts, the workspace logo on top and the avatar at the bottom. topbar: no sidebar on desktop; the logo, the nav as tabs (what does not fit goes under More), search, notifications and the avatar share the top bar. Phones keep the drawer and the tab bar in every design.
- `layout?: "page" | "fill"` = "page": page: the window scrolls under a sticky top bar. fill: the shell is exactly the viewport, the top bar stays put and main is a flex column for boards and inboxes that scroll inside.
- `variant?: "sidebar" | "inset" | "floating"` = "inset": inset: the page is a raised panel beside the sidebar. sidebar: flush columns with a hairline. floating: the sidebar is a raised panel off the edges. Applies to the classic design.
- `defaultCollapsed?: boolean` = false: Starts as the icon rail on desktop. Applies to the classic design.
- `collapsible?: "icon" | "offcanvas" | "none"` = "icon": icon: collapses to a 64px rail. offcanvas: slides out completely. none: always expanded. Applies to the classic design.
- `persistKey?: string` = "admin-shell": Remembers collapsed and width in cookies (readable by a server layout) and the search and palette recents. "" turns it off; the demo passes "".
- `resizable?: boolean` = true: Drag the sidebar edge between 200 and 400px; below 120px it snaps to the rail. Applies to the classic design.
- `mobileBreakpoint?: "md" | "lg"` = "lg": Below it: the drawer, the compact top bar and the tab bar. lg gives an 820px tablet the full width for the page.
- `sidebarActiveStyle?: "soft" | "raised" | "bar"` = "soft": How the sidebar marks the active page: a soft pill, a raised pill or a bar.
- `hideTabBar?: boolean` = false: Hides the phone tab bar (pages with their own bottom bar, thumbnails).
- `logo?: ReactNode`: Shown in the sidebar header when there are no workspaces. Default: a 28px tile with an "S" and Summit CRM.
- `locale?: string` = "en-US": Intl locale for counts and times in the search and the notifications.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of the active nav item, the active tab and the unread dots.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link every nav link renders through (next/link). Default: the LinkProvider's, else <a>.
- `onNavigate?: (href: string) => void`: The router's push for search results, commands and menu items picked without an anchor (next: useRouter().push).
- `labels?: Partial<AdminShellLabels>`: Every visible string, English by default (DEFAULT_ADMIN_SHELL_LABELS; ADMIN_SHELL_LABELS_EN is the same set). Nested sets translate the composed items.
- `classNames?: Partial<Record<"sidebar" | "topbar" | "main" | "tabs", string>>`: Extra classes for the sidebar, the top bar, main and the tab bar row.
- `className?: string`: Extra classes for the root. Other props spread onto it.

Parts:
- `ADMIN_SHELL_DESIGNS` (constant): The design names, classic first: ["classic", "rail", "topbar"].
- `AdminShellDesign` (type): "classic" | "rail" | "topbar".

```tsx
// app/(admin)/layout.tsx
"use client"

import Link from "next/link"
import { usePathname, useRouter } from "next/navigation"
import type { ReactNode } from "react"
import { AdminShell } from "@/components/blocks/admin-shell"

export default function AdminLayout({ children }: { children: ReactNode }) {
  const pathname = usePathname()
  const router = useRouter()
  return (
    <AdminShell currentPath={pathname} linkComponent={Link} onNavigate={router.push}>
      {children}
    </AdminShell>
  )
}
```

Docs: https://wingo-ui.com/components/admin-shell (Markdown: https://wingo-ui.com/components/admin-shell.md)

#### AI Chat Page (`ai-chat-page`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add ai-chat-page`

A full AI assistant screen: the conversation history, a streaming thread with reasoning and tools, a composer and the plan's usage.

The history sits on the left from 1024px (a left drawer behind the menu button below, from 768px with sidebar="open"): New chat (or ⇧⌘O) opens the greeting with six starter cards, the search filters titles, rows group into Pinned, Today, Yesterday and older, and each row's ⋯ menu renames (also F2 or a double click), pins, archives or deletes it after a confirmation. The panel button in the header slides the history away on desktop and the thread glides into the space. Click the title to rename the conversation inline (Enter saves, Escape cancels, an empty title keeps the old one). The model picker sits in the header's center on desktop and inside the composer on phones. Share copies a link with a toast; ⋯ renames, pins, shares, exports the conversation as a Markdown file and deletes it with an Undo toast. Type in the composer and press Enter to send (Shift+Enter for a new line), attach files with + or by dropping them, toggle Web search, Extended thinking and CRM data. The answer arrives as typing dots, then reasoning (Summit Pro or extended thinking), the CRM tool calls one by one and the streamed markdown; Stop or Escape keeps what arrived. Scroll up while it streams and the thread lets go, with a jump button to come back. Under the answer: follow-up rows, copy, regenerate and thumbs; edit a question to ask again. A prompt with the word "error" fails and shows Retry. Switching conversations stops a running answer. The sidebar footer shows the person, the plan and its reset date, a usage ring that opens the four meters and the Upgrade to Business link.

npm: motion, lucide-react
Wingo UI dependencies: avatar, button, chat-message, chat-thread, conversation-list, drawer, dropdown-menu, inline-edit, markdown, model-picker, prompt-input, reasoning-indicator, suggestion-chips, toast, tool-call-timeline, tooltip, usage-meter, use-controllable-state, use-media-query, use-shortcut, ai-chat, date-utils, motion, navigation, relative-time, tones, ui-config

Props:
- `conversations?: AiConversation[]`: The history, controlled: ConversationItem (id, title, updatedAt, pinned, unread, archived, model) plus messages: ChatMessageData[] and optional followUps. Pair it with onConversationsChange, which also fires for every streamed chunk.
- `defaultConversations?: AiConversation[]`: The history while uncontrolled; defaults to AI_CHAT_SAMPLE.conversations (the ten W9 conversations, "Overdue invoices in September" with its reasoning, tool calls, table and email).
- `onConversationsChange?: (conversations: AiConversation[]) => void`: Called with the whole history after every change: a new chat, a message, a streamed chunk, a rename, a pin, an archive or a delete.
- `conversationId?: string | null`: The open conversation, controlled; null is a new chat.
- `defaultConversationId?: string | null` = "overdue-invoices": The conversation open first; null ("new" in the playground) starts on the greeting.
- `onConversationChange?: (id: string | null) => void`: Called when a row, New chat, a delete or a first message changes the open conversation.
- `models?: AiModel[]`: The models of the pickers; defaults to AI_CHAT_SAMPLE.models (Summit Swift, Standard, Pro, Vision, Ultra locked to Business, Local 8B).
- `model?: string`: The chosen model's id, controlled; pair it with onModelChange.
- `defaultModel?: string` = "standard": The model while uncontrolled. Summit Pro answers with a reasoning block first.
- `onModelChange?: (model: string) => void`: Called when the header or composer picker picks a model.
- `tools?: PromptTool[]`: The composer's toggles; defaults to AI_CHAT_SAMPLE.tools (Web search, Extended thinking, CRM data). The mock runs its CRM tool calls only with crm on and thinks first with reasoning on.
- `defaultActiveTools?: string[]` = "[\"crm\"]": The tools switched on at first.
- `suggestions?: ChatSuggestion[]`: The starter cards of a new chat (two columns from 640px, one below); defaults to AI_CHAT_SAMPLE.suggestions, the six W9 starters.
- `usage?: UsageMeterItem[]`: The plan's meters behind the sidebar's usage ring; defaults to AI_CHAT_SAMPLE.usage (tokens, Pro messages, images, API cost). [] hides the ring.
- `plan?: AiChatPlan | null`: { name, resetsAt, upgrade: { label, description, href } } for the footer line "Pro · resets on Oct 1, 2026" and the upsell link; defaults to AI_CHAT_SAMPLE.plan, null hides both.
- `user?: ChatPerson`: The signed-in person ({ id, name, avatar }): the greeting's first name, the questions' author and the footer; defaults to Anna Price.
- `onSend?: (message: PromptInputMessage, context: AiChatSendContext) => (AsyncIterable<string> | Promise<string>)`: AiChatSendHandler; the context is { conversationId, model, tools, signal, messages }. Plug a real model here: yield text deltas to stream the answer or resolve with the whole of it; a rejection shows the message's error with Retry. The signal aborts on Stop, on switching conversations and on unmount. Without it a scripted mock streams (reasoning for Summit Pro, CRM tool calls, the canned answers of AI_CHAT_SAMPLE.replies, a generic answer otherwise; a prompt with the word "error" fails).
- `replies?: AiChatCannedReply[]`: The mock model's scripts ({ id, match: RegExp, reasoning?, toolCalls?, content, followUps? }), tested against the prompt folded to lowercase without diacritics; defaults to AI_CHAT_SAMPLE.replies.
- `initialPrompt?: string` = "": Sent once, shortly after mount, into the open conversation (a new one when none is open), like a ?q= deep link.
- `getShareUrl?: (conversation: AiConversation) => string`: The link Share copies; defaults to origin + /assistant/<id>.
- `sidebarFooter?: ReactNode`: Content under the usage block, in the sidebar and the drawer (a version line, help links).
- `height?: "fill" | "screen"` = "screen": screen is a standalone h-dvh app with its own <main>; fill takes what is left of a shell with layout="fill" (admin-shell) and scrolls inside its panes.
- `sidebar?: "auto" | "open" | "closed"` = "auto": auto: the history is open from 1024px and a left drawer below; open: inline from 768px (tablets too); closed: starts collapsed on desktop, the header button slides it in.
- `variant?: "default" | "bubbles" | "flat"` = "default": The messages' layout, passed to ChatThread: the question in a bubble and the answer as text, both in bubbles, or both on the left with names.
- `newChatShortcut?: string` = "shift+mod+o": Opens a new chat from anywhere, shown in the New chat tooltip; "" binds nothing.
- `searchShortcut?: string` = "": Focuses the history search from anywhere ("mod+k"); "" binds nothing.
- `showUsage?: boolean` = true: The sidebar footer: the person, the plan line, the usage ring and the upsell.
- `assistantName?: string` = "Summit Assistant": The assistant's name in the sidebar brand, the composer placeholder, the message headers (flat) and screen reader text.
- `labels?: Partial<AiChatPageLabels>`: Every visible string, English by default (DEFAULT_AI_CHAT_PAGE_LABELS; AI_CHAT_PAGE_LABELS_EN is the same set). Nested keys (list, thread, message, markdown, reasoning, toolCalls, composer, modelPicker, usageMeter, suggestionChips, inlineEdit) translate the composed items.
- `locale?: string` = "en-US": Intl locale for dates, times, token counts and money.
- `now?: Date | number`: The reference time for the history groups and day separators; new messages move on from it. Defaults to the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of the send button, the question bubbles, the selected row, the starter card icons and the brand mark.
- `loading?: boolean` = false: The history, the title and the thread as skeletons; the composer is disabled.
- `animateIn?: boolean` = true: The thread rises in once when the page mounts in the browser; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the upsell link; defaults to the LinkProvider's (a plain anchor).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<AiChatPageSlot, string>>`: Classes for the parts: sidebar, brand, list, usage, main, header, title, thread, empty, drawer.

```tsx
// app/assistant/page.tsx: a standalone app screen (or inside the admin shell with height="fill")
"use client"

import { AiChatPage, type AiChatSendHandler } from "@/components/blocks/ai-chat-page"

// stream the answer from your own route (server-sent text chunks)
const onSend: AiChatSendHandler = async function* (message, { conversationId, model, tools, signal }) {
  const response = await fetch("/api/assistant", {
    method: "POST",
    body: JSON.stringify({ conversationId, model, tools, text: message.text }),
    signal,
  })
  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader()
  while (true) {
    const { value, done } = await reader.read()
    if (done) break
    yield value
  }
}

export default function AssistantPage() {
  return <AiChatPage onSend={onSend} defaultConversationId={null} />
}
```

Docs: https://wingo-ui.com/components/ai-chat-page (Markdown: https://wingo-ui.com/components/ai-chat-page.md)

#### Automation Builder Page (`automation-builder-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add automation-builder-page`

The CRM automations screen: rules with on / off switches and run health, a visual workflow editor with a cron inspector, tests and run logs.

The list shows every automation with its trigger (a lightning bolt for events, a clock for schedules, described in words), a bar of its last 14 runs, how the last one went and when, and an on / off switch that works without opening the row. Type in the search to filter by name or trigger, press All, Active, Off or With errors; the count is announced. Click or tap a row (Enter on the keyboard) to open it: on a phone the editor slides in over the list and a swipe from the left edge, the back button or Escape brings the list back. Drag the divider to resize the list. In the editor, click the name to rename it, flip Active (turning on a broken workflow is refused with a toast; confirmDisable asks before turning off), press Run a test (the steps light up one after another, the result lands in History; the QuickBooks sync fails with a 503 and jumps to its log), and Save once something changed (mod+s saves; a workflow without a trigger or with a dangling branch shows its problems and selects the step). The ⋯ menu duplicates, exports the automation as JSON or deletes it after a confirm; on phones it also holds Test and Save. The canvas pans and zooms, drags steps, inserts one on a connection, and opens a step's settings on click (a sheet on phones); the schedule trigger opens a cron picker with the next runs. Leaving an automation with unsaved changes asks first. History lists the runs (status, start, duration, trigger; cards on phones) and the selected run's log with level chips, search, wrap and download; on phones a run pushes its log with a back button. New opens a dialog with a name and four templates (Blank, Invoice reminder, Scheduled report, New lead). Sections rise in once on mount; reduced motion keeps them still.

npm: motion, lucide-react
Wingo UI dependencies: alert, alert-dialog, badge, button, cron-picker, dialog, dropdown-menu, empty-state, inline-edit, input, kbd, list, log-viewer, radio-group, search-input, split-view, switch, table, tabs, tag, toast, tracker, workflow-canvas, use-controllable-state, use-media-query, use-shortcut, file-export, form-validation, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `automations?: Automation[]`: The automations, controlled ({ id, name, description?, enabled, trigger: { type: "event" | "schedule", label, cron? }, workflow: WorkflowValue, lastRun?, runs7d }); pair it with onAutomationsChange.
- `defaultAutomations?: Automation[]`: The automations while uncontrolled; defaults to AUTOMATION_BUILDER_SAMPLE.automations (six Summit CRM rules). Workflows without positions are laid out on load.
- `onAutomationsChange?: (automations: Automation[]) => void`: Called with the whole new list after a toggle, save, create, duplicate or delete.
- `runs?: AutomationRun[]`: The run history ({ id, automationId, label?, startedAt, duration, status, trigger, error?, logs: LogLine[] }); defaults to AUTOMATION_BUILDER_SAMPLE.runs (40 runs). Test runs are added on top.
- `nodeTypes?: WorkflowNodeDef[]`: The canvas step catalog (triggers, CRM actions, messages, AI, logic); defaults to AUTOMATION_NODE_TYPES. Keep it stable.
- `selectedId?: string | null`: The open automation, controlled; null shows the Pick an automation placeholder.
- `defaultSelectedId?: string | null` = "invoice-reminder": The automation open first while uncontrolled. Phones start on the list either way.
- `onSelectedIdChange?: (id: string | null) => void`: Called when a row, a create or a delete changes the open automation.
- `tab?: "editor" | "history"`: The editor tab, controlled.
- `defaultTab?: "editor" | "history"` = "editor": The tab shown first: the workflow canvas or the run history with logs.
- `onTabChange?: (tab: AutomationBuilderPageTab) => void`: Called when the tabs switch, and when a failed test or View log opens the history.
- `defaultStepId?: string` = "": A step id whose settings open on mount, or "trigger" for the automation's trigger (the cron picker on schedules).
- `height?: "auto" | "fill" | "screen"` = "fill": fill takes what is left of an admin shell with layout="fill" and scrolls inside its panes; screen is a standalone h-dvh page; auto is as tall as the window (at least 760px) with a fixed 640px canvas.
- `listWidth?: number` = 320: The list column in px (260 to 420); the divider drags it too.
- `saveShortcut?: string` = "mod+s": The key that saves the open automation, shown on the Save button; "" binds nothing.
- `confirmDisable?: boolean` = false: Ask before switching an automation off (from the list or the editor).
- `onToggle?: (automation: Automation, enabled: boolean) => (void | Promise<unknown>)`: The on / off switch, optimistic; a rejection flips it back with a toast. A 600 ms request is simulated by default.
- `onSave?: (automation: Automation) => (void | Promise<unknown>)`: Save and mod+s, after validateWorkflow passes; a rejection keeps the changes with a toast. Simulated by default.
- `onTest?: (automation: Automation) => (void | Promise<unknown>)`: Run a test: resolve when it passes, reject with the reason when it fails. The default takes 1.8 s and fails for QuickBooks sync with QuickBooks responded with 503.
- `onCreate?: (automation: Automation) => (void | Automation | Promise<void | Automation>)`: The new automation dialog; resolve with the stored automation to replace the draft, reject to show the error in the dialog.
- `onDelete?: (automation: Automation) => (void | Promise<unknown>)`: Delete from the ⋯ menu, run while the confirm dialog shows its spinner; a rejection keeps the dialog open with the error.
- `onDuplicate?: (automation: Automation) => (void | Automation | Promise<void | Automation>)`: Duplicate: gets the copy (off, no history); resolve with the stored one to replace it.
- `labels?: Partial<AutomationBuilderPageLabels>`: Every visible string, English by default (DEFAULT_AUTOMATION_BUILDER_PAGE_LABELS; AUTOMATION_BUILDER_PAGE_LABELS_EN is the same set). Nested keys (canvas, cronPicker, logViewer, table, list, inlineEdit) translate the composed items.
- `locale?: string` = "en-US": Intl locale for relative times, durations, dates in the logs and the cron descriptions.
- `now?: Date | number`: The reference time for relative times, test runs and next cron runs; defaults to the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of New and Save, the switches, the pressed chips, the tabs, the canvas selection and the cron picker.
- `radius?: "sm" | "md" | "lg"` = "md": The canvas, the run table, the log and the alerts (12px, 16px or 24px).
- `loading?: boolean` = false: The list rows and the editor as skeletons.
- `animateIn?: boolean` = true: The list and the editor rise in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for links inside the page; defaults to the LinkProvider's (a plain anchor).
- `className?: string`: Merged onto the root.
- `classNames?: Partial<Record<AutomationBuilderPageSlot, string>>`: Classes for the parts: list, editor, header, canvas, history, log, empty, newDialog.

```tsx
// app/(admin)/automations/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell layout="fill">{children}</AdminShell>)
"use client"

import { AutomationBuilderPage, type Automation } from "@/components/blocks/automation-builder-page"

export default function AutomationsPage() {
  return (
    <AutomationBuilderPage
      height="fill"
      onToggle={async (automation: Automation, enabled: boolean) => {
        await fetch(`/api/automations/${automation.id}`, { method: "PATCH", body: JSON.stringify({ enabled }) })
      }}
      onSave={async (automation: Automation) => {
        await fetch(`/api/automations/${automation.id}`, { method: "PUT", body: JSON.stringify(automation) })
      }}
      onTest={async (automation: Automation) => {
        const response = await fetch(`/api/automations/${automation.id}/test`, { method: "POST" })
        if (!response.ok) throw new Error(await response.text())
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/automation-builder-page (Markdown: https://wingo-ui.com/components/automation-builder-page.md)

#### Checkout Page (`checkout-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add checkout-page`

The Summit Market shop from the cart to Order placed: an editable cart, four checkout steps and the order confirmation.

A slim three step bar under the header shows where you are (Cart, Delivery and payment, Confirmation). In the cart the steppers change quantities (hold to repeat, a stock hint at the limit, the trash at 1), the × or a swipe left on touch removes a line and leaves an undo row that counts down for 5 seconds, and Save for later moves a line to a saved list below with Move to cart and Delete. The free delivery bar fills as the cart grows and turns green at the threshold. Have a coupon? opens the code field: FALL15, FREESHIP, SAVE50 and BIG200 apply after a short check with a popping tick, EXPIRED is rejected with its date, and a code that stops applying after a quantity change is removed with a note. The summary, the savings badge and the total follow every change. Continue to delivery (or the phone bar with the total, shown while the summary button is off screen) opens the checkout: saved addresses or a new one with the state picker (Romanian counties and localities under a ro locale), a company invoice with the tax ID check, the delivery methods with the locker list, the payment methods, and the review with the terms. Back to cart returns with everything kept. Place order places it; the card ending 0002 is refused with the bank's message on the review step. The button turns into a check, the confirmation slides in with a bouncy tick, the thank you, the email, Track order, Continue shopping, an account hint for guests and the order tracker. You might also like is a swipeable rail whose Add to cart buttons add to the cart. Every stage change moves focus to its heading and is announced; stages slide in the direction you go, a fade under reduced motion. On phones the cart is one column, the checkout is a full screen app with its own footer and the confirmation buttons are full width.

npm: motion, lucide-react
Wingo UI dependencies: alert, badge, button, carousel, cart-drawer, checkout-steps, coupon-input, empty-state, listing-card, order-tracker, progress, quantity-stepper, skeleton, sticky-cta-bar, toast, commerce, date-utils, motion, navigation, number-format, relative-time, ro-locations, tones, ui-config

Props:
- `items?: CartItem[]`: The cart lines, controlled; pair with onItemsChange. CartItem comes from cart-drawer (price, compareAtPrice, quantity, maxQuantity, taxRate, image, variant, href).
- `defaultItems?: CartItem[]`: The starting cart, uncontrolled (CHECKOUT_PAGE_SAMPLE.items: the city bike $1,199, was $1,399, 2 × iPhone 14 case $79.90, the laptop stand $149 and the trail guide $64.90 at an 11% reduced tax rate).
- `onItemsChange?: (items: CartItem[]) => void`: Every quantity change, removal, save for later and add; the cart empties after an order.
- `stage?: "cart" | "checkout" | "confirmation"`: The stage, controlled; pair with onStageChange.
- `defaultStage?: "cart" | "checkout" | "confirmation"` = "cart": The stage the page opens on. confirmation without a placed order shows order.
- `onStageChange?: (stage: CheckoutStage) => void`: Continue to delivery, Back to cart and a placed order.
- `checkout?: CheckoutValue`: The checkout form value, controlled (checkout-steps' CheckoutValue without the coupons, which come from the cart).
- `defaultCheckout?: CheckoutValue`: The starting form value. The signed-in buyer's email is prefilled unless guest.
- `onCheckoutChange?: (value: CheckoutValue) => void`: Every field of the checkout.
- `checkoutStep?: "address" | "delivery" | "payment" | "review"`: The checkout's step, controlled.
- `defaultCheckoutStep?: "address" | "delivery" | "payment" | "review"` = "address": The step the checkout opens on (the demo fills the steps before it).
- `onCheckoutStepChange?: (step: CheckoutStepId) => void`: Continue, Back and the stepper.
- `coupons?: Coupon[]`: The valid codes (CHECKOUT_PAGE_SAMPLE.coupons: FALL15 15% up to $150, FREESHIP, SAVE50 from $300, BIG200 from $2,000), checked locally and rechecked when the cart changes.
- `onApplyCoupon?: (code: string) => (CouponResult | Promise<CouponResult>)`: The server check of a typed code. Default: a pretend 600 ms request over coupons that rejects EXPIRED with This coupon expired on August 31, 2026.
- `savedAddresses?: CheckoutAddress[]`: The buyer's addresses (Home: 1200 Market St, Apt. 4, San Francisco; Office: Summit Software Inc., 500 Howard St). Ignored for a guest.
- `deliveryMethods?: DeliveryMethod[]`: UPS Ground $19.99, Parcel locker $12.99, FedEx Home Delivery $17.99 and a free pickup in San Francisco. The cheapest paid one is the cart's delivery estimate.
- `lockers?: CheckoutLocker[] or (methodId: string) => Promise<CheckoutLocker[]>`: The locker list (Civic Center, Westfield Centre, Hayes Valley, Union Square), or a loader per locker method.
- `paymentMethods?: PaymentMethod[]`: Visa •••• 4242, Mastercard •••• 0002, Cash on delivery (+$4.99), Bank transfer (with the account) and 3 installments from $600. Methods without an icon get one by id (card, cash or ramburs, transfer, rate).
- `freeShippingThreshold?: number` = 250: Courier and locker delivery are free from this much, after coupons; 0 hides the free delivery bar.
- `recommended?: ListingData[]`: The You might also like rail (CHECKOUT_PAGE_SAMPLE.recommended, 4 shop products with an add button). [] hides it.
- `guest?: boolean` = false: No saved addresses and no prefilled email; the confirmation adds the Create an account hint.
- `customerEmail?: string` = "anna.price@summitcrm.com": The signed-in buyer's email, prefilled in the checkout.
- `onPlaceOrder?: (value: CheckoutValue, totals: CartTotals) => (Promise<CheckoutPlaceResult | void> | CheckoutPlaceResult | void)`: Places the order (CheckoutPlaceResult = { orderNumber: string }; totals.total includes delivery and the payment fee). A rejection shows its message on the review step. Default: a pretend 1.4 s request that returns #1042 and refuses the card ending 0002 with The bank declined the payment.
- `order?: CheckoutOrder`: What the confirmation shows when the page opens on it (CHECKOUT_PAGE_SAMPLE.order, #1042 with UPS Ground). A placed order replaces it.
- `onContinueShopping?: () => void`: Continue shopping on the confirmation. Default: a toast.
- `onTrackOrder?: (orderNumber: string) => void`: Track order on the confirmation. Default: a toast.
- `shopHref?: string` = "/": Browse listings in the empty cart.
- `termsHref?: string` = "/terms": The terms link of the review step's checkbox.
- `privacyHref?: string` = "/privacy": The privacy link of the review step's checkbox.
- `registerHref?: string` = "/register": Create account in the guest's account hint.
- `stickyBar?: boolean` = true: Below 1024px in the cart, a bottom bar with the total and Continue while the summary's button is off screen.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Continue to delivery, the checkout's Continue and Place order, the phone bar and Track order.
- `labels?: Partial<CheckoutPageLabels>`: Every visible string, English by default (DEFAULT_CHECKOUT_PAGE_LABELS; CHECKOUT_PAGE_LABELS_EN is the same set), counted ones as functions; nested cart, stepper, coupon, checkout, tracker, listingCard, carousel and stickyBar for the composed items.
- `locale?: string` = "en-US": Intl locale for prices, counts and dates. A ro locale switches the address region to Romanian counties with their localities.
- `currency?: string` = "USD": The currency of every amount (the demo converts the sample to EUR).
- `now?: Date | number`: The confirmation's clock (the order time, the arrival days). Default: the live clock; the demo passes September 24, 2026, 4:40 PM.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The stage bar, the free delivery bar and the order tracker's milestones.
- `radius?: "sm" | "md" | "lg"` = "md": The panels 12 / 16 / 24px and the buttons, steppers and fields with them.
- `loading?: boolean` = false: The cart, the summary and the rail as skeletons of their real shape.
- `animateIn?: boolean` = true: Sections rise in once when the page mounts on the client (never over server HTML, never with reduced motion).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the empty cart's action, the terms links and the account hint. Default: the provider's (the shell's), then <a>.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"progress" | "header" | "freeShipping" | "lines" | "saved" | "aside" | "summary" | "recommended" | "empty" | "checkout" | "confirmation" | "tracker" | "account" | "stickyBar", string>>`: Classes for the sections.

```tsx
// app/(market)/cart/page.tsx (the shell lives in app/(market)/cart/layout.tsx as <MarketplaceShell variant="minimal">; mount <Toaster /> once there)
"use client"

import { useRouter } from "next/navigation"
import { CheckoutPage } from "@/components/blocks/checkout-page"

export default function CartPage() {
  const router = useRouter()
  return (
    <CheckoutPage
      onItemsChange={(items) => fetch("/api/cart", { method: "PUT", body: JSON.stringify(items) })}
      onPlaceOrder={async (value, totals) => {
        const response = await fetch("/api/orders", { method: "POST", body: JSON.stringify({ value, total: totals.total }) })
        if (!response.ok) throw new Error(await response.text())
        return (await response.json()) as { orderNumber: string }
      }}
      onTrackOrder={(orderNumber) => router.push(`/account/orders/${orderNumber}`)}
      onContinueShopping={() => router.push("/")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/checkout-page (Markdown: https://wingo-ui.com/components/checkout-page.md)

#### CRM Contact Page (`crm-contact-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add crm-contact-page`

A CRM company record page: header with facts and actions, tabs for overview, activity, deals, files and notes, and a details side panel.

The header shows the company with its status, a star and a follow toggle, key facts (copy the tax ID, open the last invoice) and actions: Email and Call open the mail app and the phone, New deal opens a validated dialog (title, value, stage, close date) and the new deal lands in the deals tab, the rest (New invoice, Add contact, Export record, Archive) fold into ⋯ when they do not fit and always on phones. Double click the name, press F2 or tap the pencil to rename it. The pager walks to the previous and next client (keys are off by default; the demo binds Alt + arrows). Once the header scrolls away a glass bar keeps the name and the primary action. The tabs (arrows, Home and End) switch Overview, Activity, Deals, Files and Notes; the panel slides in and the counts follow the data. Overview: the company details with copy buttons, the contacts, the open deals (View all jumps to the tab) and the last four events. Activity: write a comment (@ mentions a colleague, ⌘ Enter sends) and it lands at the top of today; the chips filter emails, calls, meetings and invoices and announce the count. Deals: a sortable table (cards on phones) with the open total. Files: drop or pick files, they upload with progress and join the list; preview, download or delete (asked first). Notes: a rich text editor with mentions, ⌘ Enter or Save note saves; pin, edit or delete a note from ⋯ (delete has an undo toast). The side panel shows the primary contact (call, email, WhatsApp), billing, tags (remove with ×, add from the field) and the team; on phones it is the Details tab. Archiving shows an alert with Restore and makes the record read-only. Failed saves roll back with a toast. Sections rise in once on mount; reduced motion keeps everything still.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, avatar, badge, button, comment-thread, contact-card, currency-input, date-picker, description-list, detail-layout, dialog, dropdown-menu, empty-state, entity-header, file-list, file-upload, input, kbd, rich-text-editor, select, table, tabs, tag, timeline, toast, use-controllable-state, use-shortcut, commerce, date-utils, form-validation, invoicing, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `company?: CrmCompany`: The record ({ id, name, cui, regCom, status, industry, city, address, website, email, phone, iban, bank, owner, tags, createdAt, balance, revenueYtd, lastInvoice, lastPayment, overdueInvoices, paymentTermDays, followers, archived }); defaults to CRM_CONTACT_SAMPLE.company (Tech Solutions Inc.).
- `contacts?: ContactData[]`: The people at the company; defaults to CRM_CONTACT_SAMPLE.contacts (Daniel Brooks, Laura Price, Sam Porter).
- `primaryContactId?: string` = "daniel-brooks": The contact in the side panel card, listed first with the Primary badge; defaults to the first contact.
- `deals?: CrmContactDeal[]`: The client's deals ({ id, title, stageId, amount, currency, probability, owner, expectedCloseDate, href }); defaults to CRM_CONTACT_SAMPLE.deals (3).
- `stages?: CrmDealStage[]`: The pipeline stages the deals point to ({ id, name, probability, kind }); defaults to CRM_CONTACT_STAGES (B2B sales).
- `activity?: CrmActivity[]`: Timeline items with a kind (email, call, meeting, invoice, payment, stage, comment, note, file) for the icon and the filters; defaults to CRM_CONTACT_SAMPLE.activity (14).
- `files?: FileItem[]`: The record's files; defaults to CRM_CONTACT_SAMPLE.files (6).
- `notes?: CrmNote[]`: Notes ({ id, author, createdAt, content (HTML), pinned, editedAt }); defaults to CRM_CONTACT_SAMPLE.notes (3).
- `people?: CommentAuthor[]`: Who can be @mentioned in comments and notes; defaults to CRM_CONTACT_TEAM.
- `currentUser?: CommentAuthor`: The signed-in user: the composer avatar, the author of new notes and comments; defaults to Ana Pop.
- `tab?: "overview" | "activity" | "deals" | "files" | "notes"`: The open tab, controlled; pair it with onTabChange.
- `defaultTab?: "overview" | "activity" | "deals" | "files" | "notes"` = "overview": The tab open first while uncontrolled.
- `onTabChange?: (tab: CrmContactTab) => void`: Called when a tab is picked (also by View all and Add a note).
- `pager?: EntityPager | null` = "3 of 128": Previous / next client ({ index, total, onPrevious, onNext, previousHref, nextHref }); null hides it.
- `previousShortcut?: string` = "": Key for the previous client, e.g. alt+arrowleft; empty binds nothing (the demo binds Alt + arrows).
- `nextShortcut?: string` = "": Key for the next client, e.g. alt+arrowright; empty binds nothing.
- `noteShortcut?: string` = "mod+enter": Saves the note from inside the editor (shown as ⌘ Enter or Ctrl + Enter); empty binds nothing.
- `showAside?: boolean` = true: The side panel with the primary contact, billing, tags and team (the Detalii tab on phones).
- `factsLayout?: "strip" | "grid" | "tiles"` = "strip": The header facts: one scrolling strip, a grid, or gray tiles (grid and tiles fold after 4 on phones).
- `headerSticky?: "none" | "condensed"` = "condensed": condensed pins a glass bar with the name and the primary action once the header scrolls away.
- `defaultUploads?: UploadFile[]`: Uploads already running when the page opens; entries without a picked file finish on a timer (the files example).
- `autoFocusNote?: boolean` = false: The note editor takes focus when the notes tab mounts.
- `defaultFavorite?: boolean` = true: The header star starts on.
- `defaultFollowing?: boolean` = true: The follow toggle starts on (you appear in the team list).
- `listHref?: string` = "/clients": Where Clients in the breadcrumb goes.
- `invoiceHref?: string` = "/invoices/new?client=<id>": Where New invoice goes (header menu and billing).
- `contactHref?: string` = "/contacts/new?client=<id>": Where Add contact goes.
- `onTitleChange?: (title: string) => (void | Promise<unknown>)`: Renaming from the header; a rejection restores the name and shows the error. Simulated by default.
- `onAction?: (action: CrmContactAction, company: CrmCompany) => (void | Promise<unknown>)`: Every header action. Archive and restore are optimistic (a rejection rolls back with a toast); export shows a loading toast.
- `onNoteSave?: (note: CrmNote) => (void | Promise<unknown>)`: A new note (new id) or a changed one (edit, pin); a rejection keeps the draft or rolls back with a toast.
- `onNoteDelete?: (note: CrmNote) => (void | Promise<unknown>)`: Deleting a note: removed at once, with an undo toast; a rejection brings it back.
- `onComment?: (body: string, context: { mentions: string[]; }) => (void | Promise<unknown>)`: A comment from the activity composer; the composer keeps the text until it resolves.
- `onUpload?: (file: File, context: { signal, onProgress }) => Promise<unknown>`: Uploads a picked file; done files join the list. Default: a pretend upload of about 1.6 s.
- `onFileDelete?: (file: FileItem) => (void | Promise<unknown>)`: Deleting a file after the confirmation; the row fades while it runs.
- `onFileOpen?: (file: FileItem) => void`: Clicking a file; default opens its preview url in a new tab.
- `onDealCreate?: (values: CrmNewDealValues) => (void | Promise<unknown>)`: The new deal dialog's submit; a rejection shows its message in the dialog.
- `onTagsChange?: (tags: string[]) => (void | Promise<unknown>)`: Tags added or removed in the side panel; optimistic, rolled back on rejection.
- `onFavoriteChange?: (favorite: boolean) => (void | Promise<unknown>)`: The header star.
- `onFollowingChange?: (following: boolean) => (void | Promise<unknown>)`: The follow toggle.
- `labels?: Partial<CrmContactPageLabels>` = "DEFAULT_CRM_CONTACT_PAGE_LABELS": Every visible string (English by default); CRM_CONTACT_PAGE_LABELS_RO is the ready Romanian set. Nested keys translate the composed items.
- `locale?: string` = "en-US": Intl locale for money, numbers and dates.
- `currency?: string` = "USD": The currency of the balance, revenue and deals.
- `now?: Date | number` = "useNow()": The reference time for relative times and the day headings; the demo pins Sep 24, 2026 16:40.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of the primary actions, the tab indicator, the chips, the editor and the upload progress.
- `radius?: "sm" | "md" | "lg"` = "md": The panels (12, 16 or 24px), the contact card, the dropzone, the editor and the dialog.
- `loading?: boolean` = false: The header, the sections and the side panel as skeletons.
- `animateIn?: boolean` = true: The header, the panel and the side sections rise in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the breadcrumb, the pager, the deal and invoice links; defaults to the LinkProvider's.
- `className?: string`: Merged onto the root.
- `classNames?: Partial<Record<CrmContactPageSlot, string>>`: Classes for the parts: header, tabs, panel, section, aside, archived, dealDialog.

```tsx
// app/(admin)/clients/[id]/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell>{children}</AdminShell>)
"use client"

import { CrmContactPage, type CrmNote } from "@/components/blocks/crm-contact-page"

export default function ClientPage() {
  return (
    <CrmContactPage
      previousShortcut="alt+arrowleft"
      nextShortcut="alt+arrowright"
      onNoteSave={async (note: CrmNote) => {
        await fetch(`/api/clients/c01/notes/${note.id}`, { method: "PUT", body: JSON.stringify(note) })
      }}
      onTagsChange={async (tags) => {
        await fetch("/api/clients/c01", { method: "PATCH", body: JSON.stringify({ tags }) })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/crm-contact-page (Markdown: https://wingo-ui.com/components/crm-contact-page.md)

#### CRM Pipeline Page (`crm-pipeline-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add crm-pipeline-page`

A CRM deals pipeline page: pipeline switcher, search and filters, a board or list with totals, a deal sheet and a new deal dialog.

Switch the pipeline from the title (B2B sales or Partnerships; a bottom sheet on phones): the filters reset, the view stays. Pick a close date range in the header (This month, Next month, This quarter, Next 90 days, or two months of days; clear it with its ×). Type in the search to find a deal by title, company or contact, press Mine, No activity 14+ days or Over $10,000, and Clear filters to reset; the new count is announced. The board's own toolbar switches Board and List, filters by owner chips and hides or shows the won and lost columns; its summary follows the filters. Drag a card to another stage (long press on touch, or focus it and use Space and the arrows), or use its ⋯ menu (Move to, Mark as won, Mark as lost, Open, Delete). A drop on Lost asks for the reason first. Moves save optimistically; a failed save springs the card back with a toast. + Add deal under a column adds one by title. Click, tap or press Enter on a card to open its sheet (from the right, a tall bottom sheet on phones): rename it inline, change the value, stage, close date and owner, read the contact and the details, write a note (⌘ Enter adds it) and read the activity; Save appears once something changed, Mark as won and Lost close it (the reason dialog requires a reason), Reopen brings a closed deal back, ⋯ deletes it with an undo toast. Closing the sheet with unsaved changes asks Discard your changes? first; Escape closes it and focus returns to the card. New deal (or + on phones) opens a validated form: title, a company combobox that can add a new company, its contacts, value, stage, close date (30 days out by default) and owner; the new deal lands in its column. Sections rise in once on mount; reduced motion keeps everything still.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, alert-dialog, avatar, badge, button, combobox, contact-card, currency-input, date-picker, date-range-picker, deal-pipeline, description-list, dialog, dropdown-menu, empty-state, inline-edit, input, kbd, page-header, search-input, select, sheet, tag, textarea, timeline, toast, use-controllable-state, commerce, date-utils, form-validation, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `pipelines?: CrmPipeline[]`: The pipelines ({ id, name, stages: DealStage[] }) of the title switcher; defaults to CRM_PIPELINE_SAMPLE.pipelines (B2B sales and Partnerships).
- `pipeline?: string`: The shown pipeline's id, controlled; pair it with onPipelineChange.
- `defaultPipeline?: string` = "b2b-sales": The pipeline shown first while uncontrolled.
- `onPipelineChange?: (pipeline: string) => void`: Called when the title switcher picks another pipeline.
- `deals?: CrmDeal[]`: Every pipeline's deals, controlled (DealData plus companyId, contactId, createdAt, source, products and activity); a deal belongs to the pipeline that has its stage.
- `defaultDeals?: CrmDeal[]`: The deals while uncontrolled; defaults to CRM_PIPELINE_SAMPLE.deals (the 12 W8 deals and 4 partnerships).
- `onDealsChange?: (deals: CrmDeal[]) => void`: Called with the whole new list after every move, edit, create and delete.
- `view?: "board" | "list"`: The board or the grouped list, controlled.
- `defaultView?: "board" | "list"` = "board": The view while uncontrolled; switching pipelines keeps it.
- `onViewChange?: (view: DealPipelineView) => void`: Called when the board's Board / List switch changes.
- `owners?: { id: string; name: string; avatar?: string; role?: string }[]`: The sales team for the owner pickers; defaults to CRM_PIPELINE_SAMPLE.owners.
- `companies?: CrmPipelineCompany[]`: Clients and their contacts for the new deal form and the sheet's contact card; defaults to CRM_PIPELINE_SAMPLE.companies.
- `lostReasons?: string[]`: The reasons offered when a deal is lost; defaults to Price, Chose a competitor, Not enough budget, No decision, Other reason.
- `currentUserId?: string` = "ana-pop": Who you are: the Mine chip and the default owner of new deals.
- `ownerFilter?: string[]`: The owner ids pressed in the board's owner chips (Mine presses yours), controlled.
- `defaultOwnerFilter?: string[]`: The owner filter while uncontrolled; defaults to [] (everyone).
- `onOwnerFilterChange?: (owners: string[]) => void`: Called when an owner chip or Mine changes the filter.
- `closePeriod?: DateRange | null`: The expected close date filter, controlled; null shows every date.
- `defaultClosePeriod?: DateRange | null`: The close date filter while uncontrolled; defaults to null.
- `onClosePeriodChange?: (period: DateRange | null) => void`: Called when the header's date range is picked or cleared.
- `largeDealAmount?: number` = 10000: The threshold of the Over $10,000 chip, in the page currency.
- `height?: "auto" | "fill" | "screen"` = "auto": fill takes what is left of a shell with layout="fill" and scrolls the board inside; screen is a standalone h-dvh page; auto grows with the longest column. Phones scroll the page around a tall board.
- `showSummary?: boolean` = true: The board's summary tiles (open pipeline, weighted forecast, won this month, win rate, average deal).
- `defaultShowClosed?: boolean` = true: Whether the Won and Lost columns start visible (the board's Show closed switch).
- `staleAfterDays?: number` = 14: Days in a stage before a card shows the stale hint, and the No activity chip's threshold; 0 turns both off.
- `requireLostReason?: boolean` = true: A move to Pierdut (drag, menu, sheet) asks for a reason and blocks until one is chosen.
- `defaultOpenDeal?: string` = "": A deal id whose sheet opens on mount.
- `onDealMove?: (move: DealMove) => (boolean | void | Promise<unknown>)`: A drop, a menu move or a sheet move. false refuses it, a promise keeps the card saving and a rejection springs it back with a toast. Without it a 600 ms request is simulated.
- `onDealSave?: (deal: CrmDeal) => (void | Promise<unknown>)`: The sheet's saves (title, value, close date, owner, a note), optimistic; a rejection rolls back with a toast. Simulated by default.
- `onDealCreate?: (deal: CrmDeal) => (void | CrmDeal | Promise<void | CrmDeal>)`: A deal from the dialog or a column's quick add; resolve with the stored deal to replace the draft. A rejection shows the error in the dialog. Simulated by default.
- `onDealDelete?: (deal: CrmDeal) => (void | Promise<unknown>)`: Deleting from a card or the sheet, after a confirm; an undo toast follows, a rejection restores it. Simulated by default.
- `labels?: Partial<CrmPipelinePageLabels>`: Every visible string (English by default, DEFAULT_CRM_PIPELINE_PAGE_LABELS); CRM_PIPELINE_PAGE_LABELS_RO is the ready Romanian set. Nested keys (pipeline, dateRange, datePicker, datePresets, currencyInput, inlineEdit, select, contactCard, timeline, validation) translate the composed items.
- `locale?: string` = "en-US": Intl locale for money, numbers and dates.
- `currency?: string` = "USD": The pipeline currency; deals in another currency are counted apart, never converted.
- `now?: Date | number`: The reference time for stale hints, overdue dates and new stamps; defaults to the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of the primary actions, the pressed chips, the probability bars and the win rate ring.
- `radius?: "sm" | "md" | "lg"` = "md": The summary tiles, the empty state, the sheet and the dialogs (12px, 16px or 24px tiles).
- `loading?: boolean` = false: The header, the summary and the columns as skeletons.
- `animateIn?: boolean` = true: The header and the board rise in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the company and deal links; defaults to the LinkProvider's (a plain anchor).
- `className?: string`: Merged onto the root.
- `classNames?: Partial<Record<CrmPipelinePageSlot, string>>`: Classes for the parts: header, filters, board, sheet, newDialog, empty.

```tsx
// app/(admin)/deals/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell layout="fill">{children}</AdminShell>)
"use client"

import { CrmPipelinePage, type CrmDeal } from "@/components/blocks/crm-pipeline-page"

export default function OportunitatiPage() {
  return (
    <CrmPipelinePage
      height="fill"
      currentUserId="ana-pop"
      onDealMove={async (move) => {
        await fetch(`/api/deals/${move.deal.id}`, {
          method: "PATCH",
          body: JSON.stringify({ stageId: move.to.id, lostReason: move.lostReason }),
        })
      }}
      onDealCreate={async (deal: CrmDeal) => {
        const response = await fetch("/api/deals", { method: "POST", body: JSON.stringify(deal) })
        return (await response.json()) as CrmDeal
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/crm-pipeline-page (Markdown: https://wingo-ui.com/components/crm-pipeline-page.md)

#### Error Pages (`error-pages`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add error-pages`

Five error screens in one block: not found, server error, scheduled maintenance, offline and no permission, full page or inside a shell.

The illustration rises in and the 404 compass needle swings and settles once; everything else fades up in order when the page mounts on the client (reduced motion keeps only short fades). 404: "Back to the home page" and "Go back" (history back, or home without history); the search focuses with / and Enter searches (a live region says what is being searched); the four suggestion cards are links that lift on hover and press in on tap. 500: "Try again" spins while it checks; a failed try shows a red alert with the time, the error id copies with one click ("Copied"), and "Technical details" opens the time, the path and the stack trace (the code block scrolls sideways on phones and has its own copy button). Maintenance: a live countdown to the end with the return date under it, the status page and support links, a 30 day uptime bar (hover, tap or arrow keys read each day) and "Notify me", an email field that validates when you leave it and ends in a confirmation; when the countdown reaches zero the page says "Maintenance is over" and the primary action becomes "Reload". Offline: an automatic retry every retryInterval seconds with a thin progress bar and "Trying again in 8 s", "Try now" at any time; the browser's online event retries at once, draws the cloud's slash away, says "You are back online" and then reloads (or calls onReconnect); pages saved on the device stay one tap away. Forbidden: "Request access" opens a dialog (a bottom sheet on phones) with an admin picker and a reason of at least 10 characters; submitting empty shows both errors, a valid request closes it, the button turns into a disabled "Request sent · 4:42 PM" and a green confirmation takes focus; "Switch account" signs out, and the signed-in account is shown. State changes are announced politely, never every second; the title takes focus when the page is reached by navigation.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, avatar, badge, button, code-block, collapsible, copy-button, countdown, dialog, input, search-input, select, textarea, toast, tracker, use-cooldown, date-utils, form-validation, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `variant?: "404" | "500" | "maintenance" | "offline" | "forbidden"` = "404": Which error screen to show.
- `layout?: "page" | "inline"` = "page": page: min-h-dvh with the logo on top and a small footer; inline: fills a shell's main (min-h-[70dvh]) without logo or footer.
- `title?: ReactNode` = "": Replaces the variant's title.
- `description?: ReactNode` = "": Replaces the variant's description.
- `illustration?: ReactNode | false`: The art above the eyebrow; default ErrorIllustration for the variant, false hides it.
- `homeHref?: string` = "/": The logo and "Back to the home page".
- `onBack?: () => void`: 404 "Go back". Default: history.back() when there is history, otherwise the home link.
- `supportHref?: string` = "mailto:support@acme.com": "Contact support" on every variant.
- `statusHref?: string` = "https://status.acme.com": The status page in the header, the footer and the maintenance actions; "" hides those links.
- `showSearch?: boolean` = true: 404: the search field (role search).
- `onSearch?: (query: string) => void`: 404: runs on Enter. Default: navigates to /search?q=.
- `searchShortcut?: string` = "/": Focuses the 404 search from anywhere; "" binds nothing.
- `suggestions?: ErrorPageSuggestion[]`: 404 link cards { label, href, icon?, description? }; default ERROR_PAGE_SUGGESTIONS (Dashboard, Clients, Invoices, Help); [] hides them.
- `errorId?: string` = "ERR-7F3K-2026": 500: the id to quote to support, copyable under the actions and in the details; "" hides it.
- `error?: Error | { message: string; stack?: string }`: 500: the details, a sample TypeError by default. Without a stack the details show the message only.
- `errorPath?: string` = "/invoices/2026-0412": 500: the page that failed, in the details.
- `occurredAt?: Date | number | string` = "2026-09-24T16:40:12": 500: when it failed, in the details.
- `showDetails?: boolean` = true: 500: the "Technical details" collapsible.
- `defaultDetailsOpen?: boolean` = false: 500: the details start open.
- `onRetry?: () => (void | Promise<unknown>)`: 500 retry, offline check and the maintenance reload. A rejection shows the failure (500 alert, offline keeps waiting). Default: 500 fails the first try and reloads on the next, offline passes once the browser fired online, maintenance reloads.
- `until?: Date | number | string` = "2026-09-27T04:00:00": Maintenance: the end. In the past the page already says "Maintenance is over".
- `statusHistory?: TrackerDatum[]`: Maintenance: the uptime bar, default ERROR_PAGES_SAMPLE.statusHistory (30 days, one partial day on Sep 18, 2026).
- `uptime?: number` = 0.9995: Maintenance: the uptime share shown next to the bar (99.95%).
- `showStatus?: boolean` = true: Maintenance: the uptime history.
- `showSubscribe?: boolean` = true: Maintenance: the "Notify me" email form.
- `defaultEmail?: string` = "": Maintenance: prefills the email.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: Maintenance: saves the email; a rejection shows its message under the field. Default: simulated.
- `retryInterval?: number` = 10: Offline: seconds between automatic retries (0 = off); each failed try starts a new wait.
- `onReconnect?: () => void`: Offline: runs 1.6 s after the connection came back (and on "Continue"). Default: reloads the page.
- `offlinePages?: ErrorPageOfflinePage[]`: Offline: pages saved on the device { label, href, savedAt, icon? }; default ERROR_PAGE_OFFLINE_PAGES; [] hides the list.
- `admins?: { id: string; name: string; avatar?: string; role?: string }[]`: Forbidden: who can grant access (Emma Carter, Ryan Brooks). [] shows only the support link.
- `resource?: ReactNode` = "Financial reports": Forbidden: what was refused.
- `onRequestAccess?: (input: ErrorPageAccessRequest) => (void | Promise<unknown>)`: Forbidden: sends { adminId, reason }; a rejection shows its message in the dialog. Default: simulated.
- `defaultRequestSent?: { adminId: string; sentAt: Date | number | string }`: Forbidden: opens on the request sent state.
- `onSwitchAccount?: () => void`: Forbidden: "Switch account". Default: a toast.
- `account?: { name: string; email: string; avatar?: string; team?: string } | null`: Forbidden: who is signed in (Noah Hayes, Sales team); null hides the card and shows the home link instead of "Switch account".
- `logo?: ReactNode`: Page layout: the header mark, default the Acme CRM logo.
- `footer?: ReactNode`: Extra content at the start of the footer links (inline layout: under the page).
- `autoFocusTitle?: boolean` = true: Page layout: the title takes focus when the page mounts after a navigation, never on the first load.
- `tone?: Tone` = "neutral": The primary actions, the illustration's accent, the countdown tiles and the retry bar.
- `radius?: "sm" | "md" | "lg"` = "md": Panels, cards, tiles and buttons.
- `animateIn?: boolean` = true: The illustration and the sections rise in once when the page mounts on the client (server html is already final).
- `labels?: ErrorPageLabelsInput`: Every visible string, one group per variant plus common, validation, countdown, tracker and trackerStatuses: DEFAULT_ERROR_PAGE_LABELS (English) by default, ERROR_PAGE_LABELS_RO for the ready Romanian set.
- `locale?: string` = "en-US": Dates, times, numbers and the page language.
- `now?: Date | number`: The reference time for relative times and the maintenance countdown (which then runs live from mount). Default useNow().
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for every link (next/link); default <a>.
- `classNames?: Partial<Record<ErrorPageSlot, string>>`: Classes for header, main, content, illustration, eyebrow, title, description, actions, extra, help and footer.

```tsx
// app/not-found.tsx
"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";
import { ErrorPage } from "@/components/blocks/error-pages";

export default function NotFound() {
  const router = useRouter();
  return (
    <ErrorPage
      variant="404"
      linkComponent={Link}
      onBack={() => router.back()}
      onSearch={(query) => router.push(`/search?q=${encodeURIComponent(query)}`)}
    />
  );
}

// app/error.tsx: <ErrorPage variant="500" error={error} errorId={error.digest} onRetry={reset} />
// inside the admin layout: <ErrorPage variant="forbidden" layout="inline" resource="Financial reports" />
```

Docs: https://wingo-ui.com/components/error-pages (Markdown: https://wingo-ui.com/components/error-pages.md)

#### Inbox Page (`inbox-page`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add inbox-page`

Northwind Market messages: conversations about your listings and the ones you asked about, with the listing pinned on top, offers, photos, voice notes.

The list shows every conversation, newest first: tap or click a row to open it (All, Buying, Selling and Unread filter it; the search finds names, listing titles and message text, accents optional). A long press on a row (or the ... button that appears on hover and focus) opens its menu: mark as read or unread, archive, mute, delete (asks first). The list menu opens the archive and the notification settings. On phones the conversation slides over the list; swipe from the left edge, tap the back arrow or press Escape to go back, and the list keeps its scroll. The header shows the person with their verified badge and when they were last active, or that they are typing; its menu opens the profile, blocks (the composer says You blocked this person, with Unblock), reports, archives or deletes. Under it the listing stays pinned with its photo, price and status: View ad, and on your own listings Reserve / Cancel reservation and Mark as sold (asks first; a sold listing greys out). Messages are grouped by day (Today, Yesterday, then the date) with read receipts; photos open a full screen viewer, voice notes play in place, offers you received have Accept and Decline. Scroll up for older messages (the position holds); when a message arrives while you read back, a New message pill takes you down. The composer: quick replies on short threads fill the field, the photo button attaches an image (a preview chip you can remove), Offer opens a dialog with the amount (buying side), Enter sends on desktop and Shift+Enter adds a line (touch keyboards add lines, the button sends; see sendOnEnter). A failed message shows Retry. With autoReply the other side types for a moment and answers; offers are accepted near the price or countered once. Alt+Arrow up / down move between conversations while focus is in the page. Incoming messages are announced to screen readers.

npm: motion, lucide-react
Wingo UI dependencies: alert-dialog, audio-player, avatar, badge, button, currency-input, dialog, dropdown-menu, empty-state, image-lightbox, presence, price, search-input, split-view, tabs, tag, textarea, toast, use-controllable-state, use-keyboard-inset, use-long-press, use-media-query, use-shortcut, use-stick-to-bottom, commerce, date-utils, form-validation, motion, navigation, relative-time, tones, ui-config

Props:
- `conversations?: InboxConversation[]`: The conversations, controlled ({ id, with: PresenceUser & { verified?, rating? }, listing: { id, title, price, priceType, image, status: "active" | "reserved" | "sold", mine, href?, priceSuffix? }, messages: InboxMessage[], unread, archived?, muted?, blocked? }); pair it with onConversationsChange.
- `defaultConversations?: InboxConversation[]`: The conversations while uncontrolled; defaults to INBOX_SAMPLE.conversations (eight Northwind Market threads: Daniel Reed about the bike, Olivia Brooks about your sofa, Greenleaf Realty, Ryan Cooper about the tent and four older ones). A message is { id, from: "me" | "them", at, kind: "text" | "image" | "voice" | "offer" | "system", text?, image?, audio?: { src, peaks?, duration }, offer?: { amount, status }, status? }.
- `onConversationsChange?: (conversations: InboxConversation[]) => void`: Every change: sent and received messages, receipts, offers, unread counts, archive, mute, block, the listing's status.
- `conversationId?: string | null`: The open conversation, controlled; null shows Pick a conversation on desktop and the list on phones.
- `defaultConversationId?: string | null` = "daniel-bike": The conversation open first while uncontrolled. Phones start on the list unless you pass it explicitly (then they open straight into it).
- `onConversationChange?: (id: string | null) => void`: A conversation was opened (a row, Alt+Arrow keys) or closed (deleted, marked unread).
- `folder?: InboxFolder`: The list filter, controlled: all, buying (other people's ads), selling (your ads) or unread.
- `defaultFolder?: InboxFolder` = "all": The list filter while uncontrolled.
- `onFolderChange?: (folder: InboxFolder) => void`: The filter tabs changed.
- `onThreadOpenChange?: (open: boolean) => void`: Phones: the conversation was pushed over the list or popped back. Hide the shell's tab bar while it is open (the demo does).
- `me?: { id: string; name: string; avatar?: string }` = "Emma Carter": You: the sender of your messages.
- `height?: "fill" | "screen"` = "fill": fill takes what is left inside a shell with layout="fill" (flex-1); screen makes the page exactly the viewport (h-dvh) on its own.
- `listWidth?: number` = 360: The conversation list's width in px from 768px up; the divider drags between 280 and 440.
- `quickReplies?: string[]` = "[\"Is it still available?\", \"What's your best price?\", \"Can you deliver?\"]": Buying side: chips above the field while a thread is short or empty; a tap fills the field. [] hides the rail.
- `sellerQuickReplies?: string[]` = "[\"Yes, it's available.\", \"The price is negotiable.\", \"I can ship it by courier.\"]": The same rail on your own listings (selling side). [] hides it.
- `autoReplies?: string[]` = "INBOX_SAMPLE.replies": The simulated answers with autoReply, picked in turn.
- `offers?: boolean` = true: The Offer button (buying side, priced listings) and the offer cards' Accept / Decline.
- `autoReply?: boolean` = true: After you send, the other side types for 1,5 to 3 s and answers with a canned reply; offers are accepted or countered once. Demo realism: turn it off in a real app.
- `sendOnEnter?: "auto" | "always" | "never"` = "auto": auto: Enter sends on desktop and adds a line on touch keyboards; always: Enter sends everywhere; never: Cmd/Ctrl+Enter sends. Shift+Enter always adds a line.
- `searchShortcut?: string` = "": Focuses the list's search (mod+k notation). Empty by default: the shell's / searches the whole site.
- `conversationShortcuts?: boolean` = true: Alt+Arrow up / down open the previous / next conversation while focus is inside the page.
- `onSend?: (conversationId: string, message: InboxOutgoingMessage) => (void | Promise<unknown>)`: Sends a text or photo message. Optimistic: the bubble shows sending, then sent, delivered and read after the reply; a rejection marks it failed with Retry. Simulated when left out.
- `onOffer?: (conversationId: string, amount: number) => (void | Promise<unknown>)`: Your offer from the dialog, before its card is sent through onSend. A rejection keeps the dialog open with the error.
- `onOfferRespond?: (conversationId: string, messageId: string, accepted: boolean) => (void | Promise<unknown>)`: Accept / Decline on an offer you received; optimistic, rolled back with a toast when it rejects.
- `onListingAction?: (conversationId: string, action: "reserve" | "unreserve" | "sold") => (void | Promise<unknown>)`: Your ad's actions from the pinned strip; every conversation about the same ad follows the new status.
- `onArchive?: (conversationId: string, archived: boolean) => (void | Promise<unknown>)`: Archive or restore (a toast offers Undo). A new message brings an archived conversation back.
- `onDelete?: (conversationId: string) => (void | Promise<unknown>)`: Delete after the confirmation.
- `onMarkUnread?: (conversationId: string, unread: boolean) => (void | Promise<unknown>)`: Mark as read or unread from the row menu.
- `onMute?: (conversationId: string, muted: boolean) => (void | Promise<unknown>)`: Mute or unmute the conversation's notifications.
- `onBlock?: (conversationId: string, blocked: boolean) => (void | Promise<unknown>)`: Block (after the confirmation) or unblock the person.
- `onReport?: (conversationId: string) => (void | Promise<unknown>)`: Report the person after the confirmation.
- `labels?: Partial<InboxPageLabels>` = "DEFAULT_INBOX_PAGE_LABELS": Every visible string, English by default (DEFAULT_INBOX_PAGE_LABELS; INBOX_PAGE_LABELS_EN is the same set under its older name). Nested sets for the composed items: price, audio, lightbox, currencyInput, avatarStatus.
- `locale?: string` = "en-US": Intl locale for prices, times and dates.
- `currency?: string` = "USD": ISO 4217 code of every price, offer and the offer dialog's amount.
- `now?: Date | number` = "useNow()": The reference time for Today / Yesterday, row times and last seen. The demo passes Sep 24, 2026, 4:40 PM.
- `tone?: Tone` = "neutral": Your bubbles, the send button, the unread counts, the selected filter and the primary actions.
- `loading?: boolean` = false: Rows and bubbles as skeletons of their real shape.
- `animateIn?: boolean` = true: The list and the conversation rise in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for View ad, View profile and Browse ads; defaults to the LinkProvider's (a plain anchor).
- `className?: string`: Merged onto the root.
- `classNames?: Partial<Record<InboxPageSlot, string>>`: Classes for the parts: list, row, thread, header, listing, messages, composer, empty.

```tsx
// app/(market)/messages/page.tsx (the shell lives in app/(market)/layout.tsx: <MarketplaceShell layout="fill">{children}</MarketplaceShell>)
"use client"

import { InboxPage, type InboxOutgoingMessage } from "@/components/blocks/inbox-page"

export default function MessagesPage() {
  return (
    <InboxPage
      height="fill"
      autoReply={false}
      onSend={async (conversationId: string, message: InboxOutgoingMessage) => {
        const response = await fetch(`/api/conversations/${conversationId}/messages`, { method: "POST", body: JSON.stringify(message) })
        if (!response.ok) throw new Error("The message could not be sent")
      }}
      onArchive={async (conversationId: string, archived: boolean) => {
        await fetch(`/api/conversations/${conversationId}`, { method: "PATCH", body: JSON.stringify({ archived }) })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/inbox-page (Markdown: https://wingo-ui.com/components/inbox-page.md)

#### Invoice Page (`invoice-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add invoice-page`

An invoice editor and viewer for Romanian B2B: client, series, dates, VAT lines, totals, an A4 preview, sending and e-Factura status.

Switch between Edit and Preview in the header (arrow keys move the segmented control). In edit mode pick the client in the search field (name, CUI or city; a full-height sheet on phones), or type a new name and choose New client to open a dialog where Look up in ANAF (or Enter in the CUI field) fills the company from its CUI; Change swaps the client. Pick the series (the number jumps to the next free one), the issue date (the due date keeps the same term), the due date with the +15, +30 and +45 days presets, and the currency: EUR converts every price at the BNR rate and shows the RON equivalent under the total. Edit the lines like a spreadsheet (product search, quantity, price, VAT rate, discount, drag or Move up / Move down to reorder, remove with undo; cards with an edit sheet on phones) and type the notes. The aside keeps the summary with VAT per rate and the total, the IBAN with a copy button, and the e-Factura switch in view while you scroll (on a laptop with a sidebar the lines take the full width under them instead). A draft saves itself 800 ms after the last change (Saving…, then Saved a few seconds ago); Ctrl or Cmd + S saves at once. Issue invoice checks the client, its CUI, the number (a taken one fails), the dates and the lines: the problems are listed in an alert whose links move focus to each field, and the lines get their own errors. Issuing uploads to SPV when the switch is on and turns to the preview: an A4 sheet in paper colours in both themes, scaled to the width on tablets and phones (pinch to zoom). Send opens the send dialog (a full-height sheet on phones): recipients as chips, CC, subject, message, the PDF attached and an SPV switch; Ctrl or Cmd + Enter sends. Download PDF opens the print dialog, which prints only the document. The ⋯ menu holds Duplicate (a new draft with the next number), Mark as paid (the badge pops), Issue credit note and Void invoice (undo in a toast for 5 seconds). Overdue invoices offer Send reminder; paid and cancelled ones are read-only. On phones a bar at the bottom shows the total with Issue, Send or Download.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, badge, button, combobox, copy-button, date-picker, description-list, dialog, dropdown-menu, input, invoice-line-items, kbd, page-header, segmented-control, select, sticky-cta-bar, switch, tag-input, textarea, toast, use-controllable-state, use-media-query, use-shortcut, commerce, date-utils, form-validation, invoicing, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `invoice?: InvoiceDocument`: The document, controlled ({ id, series, number, status, issueDate, dueDate, currency, client, supplier, lines, notes, paymentTerms, documentDiscount, sentToSpv, paidAt, issuedBy }); pair it with onInvoiceChange.
- `defaultInvoice?: InvoiceDocument`: The document while uncontrolled; defaults to INVOICE_PAGE_SAMPLE (draft CRP #2026-0412 to Tech Solutions SRL). createInvoiceDraft(now) gives an empty one.
- `onInvoiceChange?: (invoice: InvoiceDocument) => void`: Called with the whole document after every edit and status change.
- `mode?: "edit" | "preview"`: The view, controlled; pair it with onModeChange.
- `defaultMode?: "edit" | "preview"` = "edit": The first view while uncontrolled; when left out, edit for drafts and preview for every other status (the sample is a draft).
- `onModeChange?: (mode: InvoiceMode) => void`: Called when the segmented control, issuing or duplicating switches the view.
- `status?: "draft" | "issued" | "sent" | "paid" | "overdue" | "cancelled"` = "draft": Seeds the document's status on mount (a playground shortcut; the sample is a draft). Overdue moves the dates 3 days past due, paid sets today as the payment date.
- `clients?: InvoiceParty[]`: The client picker's options ({ id, name, cui, regCom, address, city, county, email, vatPayer, individual }); defaults to the 12 Northwind CRM clients (INVOICE_PAGE_CLIENTS).
- `products?: InvoiceProduct[]`: The line product search; defaults to the 7 Northwind CRM products and services (INVOICE_PAGE_PRODUCTS).
- `productCurrency?: string` = "RON": The currency of the product prices; they are converted to the document's currency through exchangeRate.
- `supplier?: InvoiceParty`: The issuer printed on the document and shown in Payment; defaults to Northwind Soft SRL (RO40528170, Banca Transilvania).
- `series?: string[]`: The document series; defaults to ["CRP", "CRPX"] (labels.seriesHints describes each).
- `takenNumbers?: Record<string, string[]>`: Numbers already used per series: the next free one is suggested and a taken one fails validation; defaults to INVOICE_PAGE_TAKEN_NUMBERS.
- `exchangeRate?: { currency: string; rate: number; date: Date; source?: string }`: The foreign currency the Currency field offers and its RON rate; defaults to BNR 1 EUR = 4.9713 RON on 2026-09-24.
- `userName?: string` = "Emma Carter": Who signs: Prepared by on the document and the sender of the email, unless the invoice has issuedBy.
- `pricesIncludeVat?: boolean` = false: The price column holds prices with VAT (B2C); totals are computed backwards.
- `eFactura?: boolean`: The Send to SPV automatically on issue switch, controlled.
- `defaultEFactura?: boolean` = true: The SPV switch while uncontrolled: issuing uploads the invoice to e-Factura and marks it Sent to SPV.
- `onEFacturaChange?: (on: boolean) => void`: Called when the SPV switch flips.
- `spvConnected?: boolean` = true: An ANAF certificate is linked; false disables the SPV switches and says Neconectat.
- `onSave?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Saves the draft, 800 ms after the last change and on Ctrl or Cmd + S; simulated by default. A rejection shows Nu am putut salva.
- `onIssue?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Issues a valid draft (blank lines removed); simulated by default. Then the status becomes Issued, or Sent to SPV with e-Factura on.
- `onSend?: (invoice: InvoiceDocument, payload: { to; cc; subject; message; spv }) => (void | Promise<unknown>)`: Sends from the dialog (a draft is issued first); simulated by default. A rejection shows its message in the dialog.
- `onDownload?: (invoice: InvoiceDocument) => void`: Download PDF; default window.print(), where Save as PDF gives a real PDF with only the document on it.
- `onMarkPaid?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Mark as paid; simulated by default, then the status is Paid with today's date.
- `onDuplicate?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Duplicate; simulated by default, then the page opens a new draft with the next number and today's dates.
- `onStorno?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Emite storno for issued, sent, paid and overdue invoices; simulated by default with a toast.
- `onCancel?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Void invoice: the status changes at once with an undo toast; a rejection rolls it back.
- `onRemind?: (invoice: InvoiceDocument) => (void | Promise<unknown>)`: Send reminder on overdue invoices; simulated by default with a toast.
- `onCreateClient?: (client: InvoiceParty) => (void | InvoiceParty | Promise<void | InvoiceParty>)`: Saves a client from the Client nou dialog; a returned party replaces the typed one. Simulated by default; the new client is selected.
- `linesLayout?: "auto" | "table" | "cards"` = "auto": The lines editor: auto shows the spreadsheet table wherever it gets 936px (from a page about 936px wide the lines span the full row under the client and the summary, from 1352px they sit beside the sticky summary), cards with an edit sheet below.
- `stickyBar?: boolean` = true: The phone bar (below 768px) with the total and Issue, Send or Download; hide the shell's tab bar while it shows.
- `defaultSendOpen?: boolean` = false: Opens the send dialog on mount (examples).
- `defaultShowErrors?: boolean` = false: Starts with the issue checks shown, as after pressing Emite factura (examples).
- `saveShortcut?: string` = "mod+s": Saves the draft; "" turns it off.
- `sendShortcut?: string` = "mod+enter": Sends from the open send dialog, also while typing the message; "" turns it off.
- `invoicesHref?: string` = "/invoices": Where the breadcrumb's Facturi goes.
- `labels?: Partial<InvoicePageLabels>`: Every visible string, English by default (DEFAULT_INVOICE_PAGE_LABELS; INVOICE_PAGE_LABELS_EN is the same set under its older name). Nested keys pass strings to the composed items (lineItems, validation, datePicker, tagInput, stickyBar).
- `locale?: string` = "en-US": Intl locale for money, numbers and dates.
- `currency?: string` = "RON": Seeds the document's currency on mount (the sample is in RON); EUR converts the prices at exchangeRate.
- `now?: Date | number`: The reference time for today, overdue days, payments and duplicates; default the live clock.
- `tone?: Tone` = "neutral": The accent of the primary actions, the mode switch, the date pickers and the switches.
- `radius?: "sm" | "md" | "lg"` = "md": The panels' radius: 12, 16 or 24px.
- `loading?: boolean` = false: The header, panels and aside as skeletons in the real layout.
- `animateIn?: boolean` = true: The header and sections rise in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the breadcrumb; default an <a> (or the LinkProvider's).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<InvoicePageSlot, string>>`: Classes for header, alerts, edit, main, client, details, lines, notes, aside, summary, payment, efactura, preview, document, send and bar.

```tsx
// app/(admin)/invoices/[id]/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell>{children}</AdminShell>)
"use client"

import { InvoicePage, type InvoiceDocument } from "@/components/blocks/invoice-page"

export default function InvoiceRoute() {
  return (
    <InvoicePage
      onSave={async (invoice: InvoiceDocument) => {
        await fetch(`/api/invoices/${invoice.id}`, { method: "PUT", body: JSON.stringify(invoice) })
      }}
      onIssue={async (invoice) => {
        await fetch(`/api/invoices/${invoice.id}/issue`, { method: "POST" })
      }}
      onSend={async (invoice, payload) => {
        await fetch(`/api/invoices/${invoice.id}/send`, { method: "POST", body: JSON.stringify(payload) })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/invoice-page (Markdown: https://wingo-ui.com/components/invoice-page.md)

#### KPI Dashboard (`kpi-dashboard`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add kpi-dashboard`

The first screen of a back office: KPI tiles with deltas, revenue against the last period, sources, funnel, top sellers, invoices, activity.

Pick the period in the header: presets (Today, Last 7 days, This month, Last month, This quarter, This year) or any range on the calendar, applied with Apply; on a phone it opens as a bottom sheet. The compare switch turns the dashed previous period in the revenue chart, the KPI deltas and the salespeople's changes on and off. Refresh spins its icon, shows a thin bar under the header and announces "Updated at 16:40" when it is done; a refreshShortcut binds it to a key. Export opens a menu with CSV and PDF. Hover, tap or scrub a chart to read a point, or focus it and use the arrow keys; legend rows toggle a series, a donut slice or a legend row selects a source (Escape clears). KPI tiles with a link lift on hover and open on Enter. Widgets with a menu have a ⋯ button labelled with their title, and View all links end their headers. Below 672px the widgets stack in one column, the KPIs go two per row (an odd last tile takes the full row), the latest invoices turn from a table into cards, and refresh and export fold into one ⋯ that opens as an action sheet. Values count up and charts draw in once; a new period swaps the numbers with a short fade instead of counting again, and reduced motion drops the counts and the chart growth.

npm: motion, lucide-react
Wingo UI dependencies: badge, bar-chart, button, date-range-picker, donut-chart, dropdown-menu, empty-state, funnel-chart, leaderboard, line-chart, progress, skeleton, stat-card, switch, table, timeline, tooltip, use-controllable-state, use-locale, use-shortcut, commerce, date-utils, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `data?: KpiDashboardData` = "KPI_DASHBOARD_SAMPLE": { kpis: KpiItem[]; revenue?: { date, value, previous? }[]; revenueBy?: { label, value }[]; sources?: { label, value, color? }[]; funnel?: { label, value }[]; leaderboard?: { id, name, avatar?, value, change? }[]; invoices?: { id, number, client, amount, issuedAt, dueAt, status, href? }[]; activity?: TimelineItemData[] }. KpiItem: { id, label, value (null shows a dash), format?, delta?, deltaFormat? (percent, number, currency, points), invertTrend?, sparkline?, sparklineType?, icon?, iconTone? (the icon tile tint), href?, goal?, info? }. A widget whose data is missing is hidden; an empty array shows its empty state. The sample (Northwind CRM, September 2026) is pinned to 2026-09-24 4:40 PM.
- `title?: ReactNode` = "Dashboard": The page's one <h1>: 22px on phones, 24px from 768px.
- `description?: ReactNode` = "": A line under the title (the company, the team, a greeting).
- `revenueByLabel?: string` = "": The bar chart's title. Empty uses labels.revenueBy ("Revenue by month"); set "Revenue by city" when the bars are cities.
- `layout?: "comfortable" | "compact"` = "comfortable": comfortable: 24px gaps (16px on phones), md KPI cards and 280px charts. compact: 16px gaps, one joined panel of sm KPI tiles and 240px charts.
- `kpiColumns?: number` = 0: KPI tiles per row on wide dashboards (at most 2 on phones and 3 from 576px). 0 is auto: 2, then 3, then every tile in one row (up to 5) from 1024px. The last row always fills its width.
- `revenueByOrientation?: "vertical" | "horizontal"` = "vertical": vertical columns with the latest one highlighted (months), or horizontal bars for long labels (cities, products).
- `activityLimit?: number` = 5: Activity items shown before View all. 0 shows every item.
- `variant?: "surface" | "card" | "outline"` = "surface": The surface of every widget and KPI tile: raised panels (surface), flat gray tiles (card) or hairline outlines on the page (outline).
- `radius?: "none" | "sm" | "md" | "lg"` = "md": Corners of the widgets and KPI tiles: 0, 12, 16 or 24px.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The accent of the single-series marks: the revenue line and its area, the bars, the funnel, the salespeople's bars, the KPI icons and sparklines. Status colors (paid, overdue, deltas) keep their meaning.
- `color?: string` = "": Any CSS color for the same marks; replaces the tone.
- `currency?: string` = "USD": ISO 4217 code for every amount. The block formats, it never converts: USD data with EUR prints euros.
- `locale?: string` = "": Intl locale for numbers, money and dates (en-US: $248,300, 10/24/2026). Empty uses the UIProvider's, then the browser's.
- `defaultComparePrevious?: boolean` = true: Starts with the previous period on: the dashed series, the KPI deltas and the salespeople's changes. comparePrevious / onComparePreviousChange control it.
- `loading?: boolean` = false: Every KPI tile and widget in its skeleton (charts, rows, table, feed); the period picker and the switch stay usable.
- `animated?: boolean` = true: Values count up and charts draw in once, on first view. Reduced motion turns both off on its own.
- `animateIn?: boolean` = false: Widgets stagger in (40ms apart) when the dashboard mounts on the client. Server HTML and hydration show the final state.
- `refreshShortcut?: string` = "": A key combo for refresh ("shift+r", "mod+shift+r"), shown in the button's tooltip and the ⋯ menu. Empty binds nothing.
- `period?: DateRange`: The period on screen, { from, to } (controlled). The data is the app's job: the block shows the period and hands changes back.
- `defaultPeriod?: DateRange`: The starting period while uncontrolled. Default: this month of now.
- `onPeriodChange?: (period: DateRange) => void`: A preset or a range was applied.
- `comparePrevious?: boolean`: Controlled compare switch.
- `onComparePreviousChange?: (compare: boolean) => void`: The compare switch changed.
- `widgets?: ("revenue" | "revenueBy" | "sources" | "funnel" | "leaderboard" | "invoices" | "activity")[]`: Which widgets show and in what order (DOM order is the phone order). Default: all, in this order, each hidden when its data is missing; a widget listed here shows its empty state instead.
- `onRefresh?: () => (void | Promise<unknown>)`: Shows the refresh button. A returned promise spins it, shows a bar under the header and announces the time when it settles (or labels.refreshError when it rejects).
- `onExport?: (format: "csv" | "pdf") => void`: Shows the Export menu. Exporting is the app's job (the block does not import spreadsheet).
- `widgetErrors?: Partial<Record<KpiDashboardWidgetId, ReactNode>>`: An error state with a Try again button in place of a widget's content (true uses the default message).
- `onWidgetRetry?: (widget: KpiDashboardWidgetId) => (void | Promise<unknown>)`: Try again in a widget's error state; a returned promise spins the button.
- `widgetLinks?: Partial<Record<KpiDashboardWidgetId, string>>`: A View all link at the end of a widget's header (the invoices page, the activity log).
- `widgetDescriptions?: Partial<Record<KpiDashboardWidgetId, ReactNode>>`: A line under a widget's title.
- `widgetActions?: (widget: KpiDashboardWidgetId) => (MenuEntry[] | undefined)`: Menu entries for a widget's ⋯ button, labelled "More actions for <title>"; a bottom sheet on phones.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: Renders View all links and invoice links through your router (default: the LinkProvider's, else <a>).
- `now?: Date | number`: The moment the default period and the relative activity times are measured from. Default: the current time (useNow), or 24.09.2026 16:40 for the sample.
- `labels?: Partial<KpiDashboardLabels>`: Every string: period, presets { today, last7Days, thisMonth, lastMonth, thisQuarter, thisYear }, compare, refresh, refreshing, updated(time), refreshError, export, exportCsv, exportPdf, more, moreFor(title), kpis, vsPrevious, points(value), revenue, current, previous, revenueBy, sources, total, funnel, leaderboard, invoices, activity, viewAll, statuses { paid, unpaid, overdue, draft }, number, client, status, amount, due, empty, error, retry. English defaults in DEFAULT_KPI_DASHBOARD_LABELS.
- `classNames?: Partial<Record<"content" | "header" | "title" | "description" | "status" | "controls" | "period" | "compare" | "actions" | "progress" | "kpis" | "kpi" | "grid" | "widget" | KpiDashboardWidgetId, string>>`: Extra classes for the parts. Each widget's content wrapper takes its id's key.

Parts:
- `DashboardWidget` (component): The frame of every tile, for your own dashboards: a <section aria-labelledby> with an h2 (headingLevel), title, description, icon, iconTone (the icon tile's tint, default neutral), actions (MenuEntry[] for a ⋯ menu, or a node), href + linkLabel (View all), span 1 | 2 | 3 | "full" (columns of the 3 column grid; phones take the full width), rowSpan, padding "none" | "md" (charts and tables bleed), variant, radius, loading + skeleton ("chart" | "list" | "table" | "stat"), empty / emptyState, error / onRetry, footer, labels. Reads useDefaults("dashboard-widget"). Props: DashboardWidgetProps.
- `KpiDashboardGrid` (component): The widget grid: one column, two from 672px and three from 1152px of its own width (container queries, so a sidebar never squeezes it). layout sets the gaps; fill (default true) stretches the last widget of a short row so no layout leaves a hole; animateIn staggers the widgets in on a client mount. Props: KpiDashboardGridProps.
- `KPI_DASHBOARD_SAMPLE` (constant): Northwind CRM, September 2026 against August: $248,300 revenue (+12.4%), 64 invoices, $31,650 outstanding, 9 new clients, 23% conversion, the pipeline funnel, five salespeople, the latest invoices and eight events. Type: KpiDashboardData.
- `DEFAULT_KPI_DASHBOARD_LABELS` (constant): The English strings, to spread under a translation. Type: KpiDashboardLabels.

```tsx
import { useState } from "react"
import { KpiDashboard, KPI_DASHBOARD_SAMPLE } from "@/components/ui/kpi-dashboard"
import type { DateRange } from "@/lib/date-utils"

export function SalesDashboard() {
  const [period, setPeriod] = useState<DateRange>({ from: new Date(2026, 8, 1), to: new Date(2026, 8, 30) })
  return (
    <KpiDashboard
      title="Dashboard"
      description="Northwind Software Inc. · Portland"
      data={KPI_DASHBOARD_SAMPLE}
      period={period}
      onPeriodChange={setPeriod}
      onRefresh={() => fetch("/api/dashboard")}
      onExport={(format) => window.open(`/api/dashboard/export?format=${format}`)}
      widgetLinks={{ invoices: "/invoices", activity: "/activity" }}
      locale="en-US"
      labels={{ invoices: "Recent invoices", viewAll: "See all" }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/kpi-dashboard (Markdown: https://wingo-ui.com/components/kpi-dashboard.md)

#### Listing Detail Page (`listing-detail-page`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add listing-detail-page`

A listing on Northwind Market: photos, price, details, description, an approximate map, the seller, safety tips, contact actions and similar listings.

Swipe or arrow through the photos (thumbnails under the stage or beside it, a counter on phones); hover zooms with a mouse, a click, tap or Enter opens the full screen viewer and Escape closes it. The heart on the photo and Save in the price card save the listing together, at once; a rejected onFavoriteChange rolls both back with a toast. The share button uses the system share sheet where there is one, otherwise it copies the link (Link copied). Send message opens a dialog (a bottom sheet on phones) with the listing, quick replies as tags that fill the text, and the message field: Send or Cmd/Ctrl+Enter sends, an empty message shows its error, a failed send shows an alert and keeps the text; success turns the dialog into Message sent with Go to the conversation. Show phone shows the masked number, fetches the full one through onRevealPhone and fades it in as a tel: link (announced); the sticky bar's Call reveals and dials in one tap. Read more expands the description (clamped at 8 lines); URLs in it stay plain text. The map is read only with the approximate area; on touch a tap opens it full height. Report this listing opens a dialog with the reasons as radio cards and optional details. Similar listings are a swipeable rail with arrows in its header. Below 1024px the title, price and contact buttons sit under the photos, the seller card follows the description, and once those buttons scroll away a bar with the price, Call and Message stays at the bottom. Reserved shows a warning banner; sold shows a neutral banner, disables the contact buttons and puts the similar listings first. Sections rise in once on mount; reduced motion skips it.

npm: motion, lucide-react
Wingo UI dependencies: alert, badge, breadcrumb, button, carousel, collapsible, description-list, dialog, favorite-button, image-lightbox, listing-card, location-map, price, product-gallery, radio-group, seller-card, skeleton, sticky-cta-bar, tag, textarea, toast, commerce, motion, navigation, number-format, relative-time, ro-locations, tones, ui-config

Props:
- `listing?: ListingDetail`: The listing (LISTING_DETAIL_SAMPLE.listing: l01, Trek FX 2 city bike, $280 negotiable, Portland Pearl District). ListingData without attributes plus images (ProductGalleryImage[]), description (plain text, blank lines split paragraphs), attributes (DescriptionListItem[]), views, favorites, adId, place { city, area, point, radiusKm }, courier { name, price } and the breadcrumb path.
- `seller?: SellerData`: The seller card (LISTING_DETAIL_SAMPLE.seller: Daniel Reed, 4.8 from 126 reviews, replies within an hour). Its name labels the contact buttons.
- `sellerListings?: ListingData[]`: The seller's other listings in the seller card, up to three (LISTING_DETAIL_SAMPLE.sellerListings).
- `similar?: ListingData[]`: The similar listings rail (LISTING_DETAIL_SAMPLE.similar, 8 listings around Portland). An empty array hides the section.
- `favorite?: boolean`: Saved to favorites, controlled; pair with onFavoriteChange.
- `defaultFavorite?: boolean` = false: Saved to favorites at first, uncontrolled.
- `onFavoriteChange?: (favorite: boolean) => (void | Promise<unknown>)`: A heart was toggled. The change shows at once; a rejected promise rolls it back and shows a toast.
- `onMessage?: (text: string) => (void | Promise<unknown>)`: Sends the dialog's message. A promise drives the Trimite spinner; a rejection shows its message in the dialog. Default: a pretend 900 ms request.
- `onRevealPhone?: () => (string | Promise<string>)`: Fetches the full number when Show phone or Call is pressed. Default: resolves "(503) 555-0142" after 500 ms.
- `onCall?: (phone: string) => void`: Replaces the tel: link once the number is shown (the demo shows a toast).
- `onShare?: () => void`: The share buttons. Default: navigator.share where available, else copies the listing link and shows Link copiat.
- `onReport?: (report: ListingReport) => (void | Promise<unknown>)`: Sends the report dialog (ListingReport = { reason, details }). A rejection shows an alert in the dialog. Default: a pretend 900 ms request, then a thank you toast.
- `onOpenConversation?: () => void`: Go to the conversation after a sent message. Default: navigates to /messages?listing=<id> through the link provider.
- `status?: "active" | "reserved" | "sold"` = "active": reserved: a warning banner, contact still allowed. sold: a neutral banner, contact disabled, grey photos and similar ads first.
- `galleryThumbnails?: "start" | "bottom" | "none"` = "bottom": Where the gallery's thumbnails sit on wide screens; phones swipe with a counter.
- `showMap?: boolean` = true: The Location section with the map.
- `showSafety?: boolean` = true: The Stay safe note under the seller.
- `stickyBar?: boolean` = true: Below 1024px, the bottom bar with the price, Call and Message once the contact buttons scroll away.
- `defaultMessageOpen?: boolean` = false: Opens the message dialog on mount.
- `labels?: Partial<ListingDetailPageLabels>`: Every visible string (DEFAULT_LISTING_DETAIL_PAGE_LABELS, English), counted ones as functions; nested gallery, lightbox, price, favorite, listingCard, carousel, sellerCard, map, stickyBar and breadcrumbLabels for the composed items. LISTING_DETAIL_PAGE_LABELS_EN is the same set under its older name.
- `locale?: string` = "en-US": Intl locale for prices, counts and dates.
- `currency?: string` = "USD": The currency of amounts without their own (the demo converts the sample to EUR).
- `now?: Date | number`: The clock for Today at 2:32 PM. Default: useNow() (the date while hydrating); the demo passes Sep 24, 2026, 4:40 PM.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Send message, the sticky bar, the map pin, the quick replies and the hearts (neutral hearts are red).
- `radius?: "sm" | "md" | "lg"` = "md": The surfaces: gallery, price card, seller card, map and listing cards 12 / 16 / 24px.
- `loading?: boolean` = false: The gallery, the texts, the price card, the seller and the similar ads as skeletons of their real shape.
- `animateIn?: boolean` = true: Sections rise in once when the page mounts on the client (never over server HTML, never with reduced motion).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the breadcrumb, the seller and the listing cards. Default: the provider's (the shell's), then <a>.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"breadcrumb" | "banner" | "gallery" | "summary" | "attributes" | "description" | "location" | "report" | "aside" | "priceCard" | "seller" | "safety" | "similar" | "stickyBar", string>>`: Classes for the sections.

```tsx
// app/(market)/listing/[slug]/page.tsx (the shell lives in app/(market)/layout.tsx; mount <Toaster /> once there)
"use client"

import { useRouter } from "next/navigation"
import { ListingDetailPage } from "@/components/blocks/listing-detail-page"

export default function ListingPage() {
  const router = useRouter()
  return (
    <ListingDetailPage
      onMessage={(text) => fetch("/api/messages", { method: "POST", body: JSON.stringify({ listing: "l01", text }) })}
      onRevealPhone={() => fetch("/api/listings/l01/phone").then((response) => response.text())}
      onFavoriteChange={(favorite) => fetch("/api/favorites/l01", { method: favorite ? "PUT" : "DELETE" })}
      onOpenConversation={() => router.push("/messages?listing=l01")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/listing-detail-page (Markdown: https://wingo-ui.com/components/listing-detail-page.md)

#### Login Page (`login-page`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add login-page`

The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery.

Sign in with email and password: fields validate when you leave them and as you fix them, Enter submits, a failed attempt shows a red alert above the form and keeps the email (a second failure also clears the password). The eye button reveals the password without moving the caret, and Caps Lock shows a warning. "Forgot password?" in the password label row carries the typed email to the recovery form. "Email me a sign-in link" and "Use your password" switch between the password form and the email link (or code) form. Provider buttons show a spinner on the one you pressed. After an email is sent, the "Check your email" view shows the address, opens Gmail or Outlook when the domain matches, and offers a resend that waits with a countdown ("Resend in 0:24") that survives a reload. Codes: type or paste the 6 digits and the sixth one submits; a wrong code shakes the cells and says how many tries are left, three wrong codes lock the input for a minute with a live countdown; two-step verification can switch to a 10 character backup code. The new password shows a strength meter and a checklist and must match its confirmation; the last view draws a bouncy check. Every secondary view has "Back to sign in"; each view slides in from the side it belongs to, focus moves to its title and the change is announced. On phones the form fills the screen with 48px fields and the hero is gone; with reduced motion views cross-fade.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, avatar, button, checkbox, input, otp-input, password-input, separator, toast, use-controllable-state, use-cooldown, form-validation, motion, navigation, tones, ui-config

Props:
- `defaultView?: LoginView` = "sign-in": The view shown first (uncontrolled); view / onViewChange control it.
- `view?: LoginView`: The current view, controlled. An unknown value shows sign-in.
- `onViewChange?: (view: LoginView) => void`: Runs on every view change (mirror it to the URL hash or the router).
- `layout?: "split" | "centered" | "card"` = "split": split: the form beside a hero from 1024px; centered: no hero, the form in a card from 640px; card: no hero, the form in a raised card at every width, centered on a dotted, softly tinted backdrop with the logo above and the links below.
- `heroSide?: "start" | "end"` = "end": Which side the hero sits on in the split layout.
- `heroImage?: string` = "": A photo behind the hero with a dark scrim and white text; empty keeps the neutral card hero. The demo passes /demo/city.jpg.
- `hero?: ReactNode`: Replaces the hero content (testimonial, badge and customer names from LOGIN_PAGE_SAMPLE).
- `logo?: ReactNode`: Top-left of the form column; default the Northwind CRM mark and name.
- `methods?: LoginMethod[]`: How people sign in, default ["password", "magic-link"]; "otp" emails a 6 digit code. The first is the form shown first; [] with providers leaves only the providers (SSO).
- `providers?: AuthProvider[]`: Social buttons, default AUTH_PROVIDERS (Google, Apple, Microsoft); [] hides them and the divider.
- `showProviders?: boolean` = true: Shortcut for providers={[]} when false.
- `providerLayout?: "stack" | "row"` = "stack": stack: full-width "Continue with Google" buttons; row: icon buttons side by side.
- `twoFactor?: boolean` = false: After a correct password the flow asks for the authenticator code.
- `remember?: boolean` = true: Shows the "Remember me for 30 days" checkbox.
- `defaultEmail?: string` = "": Prefills the email everywhere (a returning user).
- `resendSeconds?: number` = 30: Wait before a link or a code can be sent again (use-cooldown, kept across reloads under the key login-resend).
- `passwordMinLength?: number` = 8: Minimum length of a new password in the reset view (rule, checklist and strength).
- `onSignIn?: (values: SignInValues) => (void | Promise<unknown>)`: Email, password and remember. Default: simulated, rejects "The email or the password is not correct" below 8 characters.
- `onMagicLink?: (email: string) => (void | Promise<unknown>)`: Sends the sign-in link (and resends it). Default: simulated.
- `onSendCode?: (email: string) => (void | Promise<unknown>)`: Sends the 6 digit code for the otp method (and resends it). Default: simulated.
- `onVerifyCode?: (code: string, context: VerifyCodeContext) => (void | Promise<unknown>)`: Checks an otp, two-factor or backup code. Default: 123456 (or any 10 character backup code) passes, anything else rejects "Wrong code. 2 attempts left."; three failures lock the input for 60 s.
- `onForgot?: (email: string) => (void | Promise<unknown>)`: Requests the reset link. Default: simulated and always resolves, so the page never reveals whether an account exists.
- `onReset?: (password: string) => (void | Promise<unknown>)`: Saves the new password. Default: simulated.
- `onProvider?: (id: string) => (void | Promise<unknown>)`: Starts a social sign-in; the button spins until it settles. Default: simulated for 1.2 s.
- `onSuccess?: () => void`: After a sign-in, a verified code, a provider or the reset-done button. Default: the toast "Welcome back, Emma" (the page mounts its own Toaster then).
- `registerHref?: string` = "/signup": The "Create one" link; "" hides it.
- `termsHref?: string` = "/terms": The "Terms" link in the footer; "" hides it.
- `privacyHref?: string` = "/privacy": The "Privacy" link; "" hides it.
- `helpHref?: string` = "/help": The "Help" link; "" hides it.
- `size?: "md" | "lg"` = "lg": Fields and buttons: lg is 48px, md 40px (44px on touch); the code cells stay 48px.
- `tone?: Tone` = "neutral": The primary buttons and the checkbox.
- `radius?: "sm" | "md" | "lg"` = "md": The hero, the card, the icon tiles and the controls' corners.
- `animateIn?: boolean` = true: The logo, form, footer and hero rise in once when the page mounts on the client (server html is already final).
- `labels?: Partial<LoginPageLabels>`: Every visible string, English by default (DEFAULT_LOGIN_PAGE_LABELS; LOGIN_PAGE_LABELS_EN is the same set under its older name); validation takes form-validation messages.
- `locale?: string` = "en-US": Sets the page language (lang).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the sign-up and footer links (next/link); default <a>.
- `classNames?: Partial<Record<LoginPageSlot, string>>`: Classes for formColumn, header, body, footer, hero, view, title and form.

```tsx
// app/(auth)/login/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { LoginPage } from "@/components/blocks/login-page";

export default function Page() {
  const router = useRouter();
  return (
    <LoginPage
      heroImage="/images/office.jpg"
      twoFactor
      onSignIn={async ({ email, password, remember }) => {
        const response = await fetch("/api/login", { method: "POST", body: JSON.stringify({ email, password, remember }) });
        if (!response.ok) throw new Error("The email or the password is not correct");
      }}
      onSuccess={() => router.push("/")}
    />
  );
}
```

Docs: https://wingo-ui.com/components/login-page (Markdown: https://wingo-ui.com/components/login-page.md)

#### Marketplace Home Page (`marketplace-home-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add marketplace-home-page`

The Northwind Market home: a search for what and where, category tiles, a promoted rail, new listings near you, trust points and an app band.

Type what you look for in the hero search, pick the place in the location field (it filters the towns of lib/ro-locations, accents optional, and offers All locations) and press Enter or Search: onSearch gets the text and the city id, by default the page navigates to /search?q=…&loc=…. Below 768px the two fields and the button stack and the location opens a full height sheet. The popular searches under it are links (a sideways scroll on phones). The category tiles are links to /search?cat=…; arrow keys move between them, phones show the first nine and All categories below. Promoted listings is a swipeable rail (1.3 cards on a phone, 4 on a laptop) with arrow buttons in its header on fine pointers and arrow keys when it has focus; the Promoted badge opens an explanation (a popover, a bottom sheet on phones). New listings in Cluj-Napoca: the city chip opens a searchable list of places (a sheet on phones) and the grid shows the newest listings there; a city with nothing yet shows No listings in Sibiu yet with Search every location. Hearts save a listing at once, in the rail and in the grid together; a rejected onFavoriteChange rolls the heart back. See all listings opens the results. The trust tiles and the app band (bullets, App Store and Google Play buttons, a QR code to scan on desktop) close the page. Sections rise in once when the page mounts on the client; reduced motion skips it.

npm: motion, lucide-react
Wingo UI dependencies: badge, button, carousel, category-picker, combobox, empty-state, listbox, listing-card, popover, qr-code, search-input, separator, skeleton, tag, use-controllable-state, use-media-query, commerce, motion, navigation, number-format, relative-time, ro-locations, tones, ui-config

Props:
- `categories?: MarketplaceHomeCategory[]`: The category tiles (MARKETPLACE_HOME_SAMPLE.categories: the 12 Northwind Market categories with lucide icons and counts). Each links to /search?cat=<id> unless it has its own href.
- `promoted?: ListingData[]`: The promoted rail (MARKETPLACE_HOME_SAMPLE.promoted: l02, l04 and six generated promoted ads). Empty hides the section.
- `recent?: ListingData[]`: The newest listings, newest first (MARKETPLACE_HOME_SAMPLE.recent: l01 to l08 plus 16 generated, mostly in Cluj-Napoca). The grid keeps the listings whose location starts with the chosen city.
- `popularSearches?: string[]`: The quick searches under the hero search (MARKETPLACE_HOME_SAMPLE.popularSearches: iPhone 14, Bike, 2-bedroom apartment...).
- `stats?: { listings: number; sellers: number; cities: number }`: The hero subline (MARKETPLACE_HOME_SAMPLE.stats: 1,284,310 listings in 3,180 towns and villages), through labels.stats.
- `location?: string`: The chosen city, a ro-locations id; controlled with onLocationChange. "" is every location, an unknown id reads as All locations.
- `defaultLocation?: string` = "cluj-napoca": The starting city of the recent section and the hero search while uncontrolled.
- `onLocationChange?: (location: string) => void`: Every city change, from the hero field, the chip or the empty state.
- `onSearch?: (query: { query: string; location: string; category: string }) => void`: The hero search. Default: navigates to /cautare?q=…&loc=… through the link provider's navigate.
- `heroVariant?: "panel" | "plain"` = "panel": panel: a tinted rounded hero with a photo mosaic from 768px (flat on phones); plain: the hero sits on the page background.
- `showPromoted?: boolean` = true: The promoted rail.
- `showRecent?: boolean` = true: The new ads grid with the city chip.
- `showTrust?: boolean` = true: The three trust tiles.
- `showApp?: boolean` = true: The app band with the store buttons and the QR code.
- `recentCount?: number` = 12: Ads in the recent grid (fewer when the city has fewer).
- `cardSize?: "sm" | "md"` = "md": Listing card size from 640px; phones always use the compact look in two columns.
- `onFavoriteChange?: (id: string, favorite: boolean) => (void | Promise<unknown>)`: A heart was toggled. The change shows at once in the rail and the grid; a rejected promise rolls it back and the card announces the error.
- `appUrl?: string` = "https://carpati.ro/app": The QR code's value in the app band.
- `appStoreHref?: string` = "#app-store": The App Store button's link.
- `googlePlayHref?: string` = "#google-play": The Google Play button's link.
- `categoriesHref?: string` = "/categories": Where All categories points.
- `deliveryFrom?: number` = 9.99: The lowest courier price in the Courier delivery tile, in currency.
- `labels?: Partial<MarketplaceHomePageLabels>`: Every visible string (DEFAULT_MARKETPLACE_HOME_PAGE_LABELS, English), counted ones as functions; nested listingCard, carousel, categoryPicker, searchInput, listbox and qrCode labels for the composed items. MARKETPLACE_HOME_PAGE_LABELS_EN is the same set under its older name.
- `locale?: string` = "en-US": Intl locale for the counts, prices and dates.
- `currency?: string` = "USD": The currency of listings without their own, and of deliveryFrom.
- `now?: Date | number`: The clock for Azi, 14:32 on the cards. Default: useNow() (a stable placeholder while hydrating); the demo passes 24.09.2026 16:40.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The search button, the hero glow, the selected place, the hearts and the trust icons.
- `radius?: "sm" | "md" | "lg"` = "md": The surfaces: cards and tiles 12 / 16 / 24px, the hero and the app band 16 / 24 / 32px.
- `loading?: boolean` = false: The hero stays; the category tiles, the promoted rail and the grid become skeletons of their real shape.
- `animateIn?: boolean` = true: Sections rise in once when the page mounts on the client (never over server HTML, never with reduced motion).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for every link on the page. Default: the provider's (the shell's), then <a>.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"hero" | "search" | "categories" | "promoted" | "recent" | "grid" | "trust" | "app", string>>`: Classes for the sections.

```tsx
// app/(market)/page.tsx (the shell lives in app/(market)/layout.tsx)
"use client"

import { useRouter } from "next/navigation"
import { MarketplaceHomePage } from "@/components/blocks/marketplace-home-page"

export default function HomePage() {
  const router = useRouter()
  return (
    <MarketplaceHomePage
      defaultLocation="cluj-napoca"
      onSearch={({ query, location }) => router.push(`/search?q=${encodeURIComponent(query)}&loc=${location}`)}
      onFavoriteChange={(id, favorite) => fetch(`/api/favorites/${id}`, { method: favorite ? "PUT" : "DELETE" })}
    />
  )
}
```

Docs: https://wingo-ui.com/components/marketplace-home-page (Markdown: https://wingo-ui.com/components/marketplace-home-page.md)

#### Marketplace Search Page (`marketplace-search-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add marketplace-search-page`

The Northwind Market results page: title and count, facets in a sidebar or phone sheet, filter chips, sort, grid or list and endless results.

The breadcrumb leads back to Home and the parent category; the title names the category and the place (Bikes in Cluj-Napoca) and the count under it is announced after every change. From 1024px the filters sit in a sticky sidebar and apply at once: drag the price thumbs over the histogram or pick a preset, tick Condition or Seller (each option shows how many listings it would give), choose the place with a radius (Only here to +100 km, off for All locations), switch Delivery available, choose Posted and the wheel sizes. Below 1024px the Filters button (with the active count) opens a full height sheet whose button counts the draft (See 312 listings) and applies it; Reset clears the draft, Escape or a swipe down closes it. Active filters and the query show as chips under the header (sideways scroll on phones); × removes one, Clear all removes all. Sort opens a menu (a sheet on phones), the grid or list switch cross-fades the results, the bell saves the search with a toast and pressing it again stops following it. Up to three promoted listings lead the results (a swipeable rail on phones). The next 24 listings load as you near the end (or with Show 24 more in button mode); a failed page shows Try again. Filters that match nothing show an empty state with Clear filters. Hearts save a listing at once. Related searches links close the page on laptops. Sections rise in once on mount; reduced motion skips it.

npm: motion, lucide-react
Wingo UI dependencies: breadcrumb, button, empty-state, filter-panel, listing-card, listing-grid, price-range, tag, toast, use-controllable-state, motion, navigation, number-format, relative-time, ro-locations, text-match, tones, ui-config

Props:
- `state?: MarketplaceSearchState`: The search, controlled with onStateChange: { query, category, location (a ro-locations city id, "" for the whole country), filters (FilterValues keyed by filter id), sort, view }. A real app writes it to the url.
- `defaultState?: Partial<MarketplaceSearchState>`: The starting search while uncontrolled (DEFAULT_MARKETPLACE_SEARCH_STATE: Bikes in Cluj-Napoca, no filters, newest first, grid).
- `onStateChange?: (state: MarketplaceSearchState) => void`: Every change: a filter, a chip, the sort, the view, the place.
- `filters?: FilterDef[]`: The facets. Default: the sample set of the category (createSearchFilters): Price with a histogram, Condition, Location with a radius, Delivery available, Seller, Posted and Wheel size for bikes; Price, Rooms, Floor area, Location, Floor, Layout, Seller and Posted for apartments.
- `items?: MarketplaceSearchListing[]`: The local ads the default search runs over (ListingData plus cityId, facets and keywords). Default: 480 generated ads of the category (getSampleListings, l01 included).
- `search?: (state: MarketplaceSearchState, page: number) => (MarketplaceSearchResult | Promise<MarketplaceSearchResult>)`: Plug the server here: { items, total, promoted?, histogram?, counts? }. Page 0 replaces the results (skeletons while pending), later pages append. Default: searchListings over items during render, the next pages after 700ms.
- `pageSize?: number` = 24: Ads per page.
- `defaultView?: "grid" | "list"` = "grid": The first view while the state names none.
- `viewPersistKey?: string` = "carpati-market-search-view": Remembers grid or list in localStorage while the state is uncontrolled; "" turns it off.
- `columns?: ListingGridColumns`: Cards per row at the grid's own width (container queries). Default { base: 2, md: 3, xl: 3 }: two on phones, three beside the filters.
- `showPromoted?: boolean` = true: Up to three promoted ads above the results.
- `showRelated?: boolean` = true: The Related searches links under the results (from 1024px).
- `relatedSearches?: string[]`: The related searches. Default: the category's sample (E-bike, MTB 29...).
- `loadMode?: "auto" | "button"` = "auto": auto: the next page loads as the end nears (the button stays as a fallback); button: Show 24 more.
- `filterMode?: "auto" | "sidebar" | "sheet"` = "auto": auto: a sticky sidebar from 1024px and a sheet below; sidebar: always beside the results (above them on phones); sheet: the Filtre button and a sheet at every width.
- `filtersOpen?: boolean`: The filters sheet, controlled with onFiltersOpenChange.
- `defaultFiltersOpen?: boolean` = false: Opens the filters sheet on mount (where a sheet is used: below 1024px, or filterMode sheet).
- `onFiltersOpenChange?: (open: boolean) => void`: The sheet opened or closed.
- `savedSearch?: boolean`: The bell's state, controlled. Uncontrolled it belongs to one search and resets when the search changes.
- `defaultSavedSearch?: boolean` = false: The first search starts saved (the bell is on).
- `onSaveSearch?: (state: MarketplaceSearchState, saved: boolean) => (void | Promise<unknown>)`: The bell. A promise keeps it busy; resolved, a toast says Search saved; rejected, an error toast. Default: a simulated 600ms request.
- `onFavoriteChange?: (id: string, favorite: boolean) => (void | Promise<unknown>)`: A heart was toggled; it shows at once and a rejected promise rolls it back.
- `language?: "ro" | "en"` = "en": The sample content's language, kept for compatibility: the default listings, filter names, category names and related searches are English in both. Copy comes from labels.
- `labels?: Partial<MarketplaceSearchPageLabels>`: Every visible string, English by default (DEFAULT_MARKETPLACE_SEARCH_PAGE_LABELS; MARKETPLACE_SEARCH_PAGE_LABELS_EN is the same set under its older name), with nested sets for the grid, the cards, the filter panel and the breadcrumb.
- `locale?: string` = "en-US": Intl locale for the count, prices and dates.
- `currency?: string` = "USD": The default listings' prices (converted at fixed rates; USD, EUR or RON) and the price filter.
- `now?: Date | number`: The clock for Today at 2:32 PM and Posted. Default: useNow() (the sample's Sep 24, 2026, 4:40 PM while hydrating); the demo passes the same.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The filters' checks, chips, sliders and apply button, the filter count badge, the empty state action and the hearts.
- `radius?: "sm" | "md" | "lg"` = "md": The listing cards and the empty state: 12 / 16 / 24px.
- `loading?: boolean` = false: The first page: the count and the grid as skeletons of their real shape.
- `animateIn?: boolean` = true: The title and the results rise in once when the page mounts on the client; new pages fade in (never over server HTML, never with reduced motion).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the breadcrumb, the cards and the related searches. Default: the provider's (the shell's), then <a>.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"top" | "title" | "count" | "body" | "filters" | "results" | "related" | "empty", string>>`: Classes for the parts.

```tsx
// app/(market)/search/page.tsx (the shell lives in app/(market)/layout.tsx)
"use client"

import { useRouter, useSearchParams } from "next/navigation"
import {
  MarketplaceSearchPage,
  type MarketplaceSearchState,
} from "@/components/blocks/marketplace-search-page"

export default function SearchPage() {
  const router = useRouter()
  const params = useSearchParams()
  const state: MarketplaceSearchState = {
    query: params.get("q") ?? "",
    category: params.get("cat") ?? "bikes",
    location: params.get("loc") ?? "cluj-napoca",
    filters: JSON.parse(params.get("f") ?? "{}"),
    sort: params.get("sort") ?? "newest",
    view: params.get("view") === "list" ? "list" : "grid",
  }
  return (
    <MarketplaceSearchPage
      state={state}
      onStateChange={(next) => {
        const query = new URLSearchParams({
          q: next.query,
          cat: next.category,
          loc: next.location,
          f: JSON.stringify(next.filters),
          sort: next.sort,
          view: next.view,
        })
        router.replace(`/search?${query}`, { scroll: false })
      }}
      onSaveSearch={(search, saved) => fetch("/api/saved-searches", { method: saved ? "POST" : "DELETE", body: JSON.stringify(search) })}
    />
  )
}
```

Docs: https://wingo-ui.com/components/marketplace-search-page (Markdown: https://wingo-ui.com/components/marketplace-search-page.md)

#### Marketplace Shell (`marketplace-shell`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add marketplace-shell`

The Northwind Market site layout: a header with one search for what and where, a category strip, the footer, phone tabs and cookie consent.

On desktop the header holds the logo, one joined search box and the actions. Type in the query field (press / to focus it): while it is empty it lists your recent searches (remove one with its x or Delete, or clear them) and the popular ones; while typing it suggests categories (Mobile phones, in Electronics › Phones) and matching listings; arrows and Enter pick one. The location field filters the Romanian cities without diacritics and offers All locations and Near me (your position when the browser allows it, else your own city). Enter or Search submits the query, the place and the category; a category chip in the box scopes the search and its x removes it. Favorites and messages carry counts, the avatar opens the account menu (my account, listings, favorites, messages, settings, the theme and sign out), and Post a listing starts a new listing. The category strip below scrolls sideways with edge fades and marks the active category. Once the page scrolls the header gains a hairline and a soft shadow. Below 768px the header is a compact row: the logo mark, a search field that opens a full height sheet (autofocused input, the location as a row that opens its own sheet, recent searches with remove buttons, popular searches and category tiles; Escape, the handle or Cancel closes it) and the avatar. A bottom tab bar holds Home, Search (opens the sheet), the raised Post action, Messages with its count and Account. The minimal variant keeps only the logo, a back or close button and a trust note. The cookie banner shows until the visitor decides and sits above the tab bar; Cookie settings in the footer reopens its settings. The skip link (Skip to content) is the first stop for keyboard users.

npm: lucide-react
Wingo UI dependencies: badge, bottom-tab-bar, button, combobox, cookie-consent, drawer, search-input, separator, theme-toggle, toast, user-menu, use-media-query, use-scroll-state, use-shortcut, navigation, number-format, ro-locations, text-match, tones, ui-config

Props:
- `children?: ReactNode`: The page, rendered once inside main.
- `variant?: "full" | "minimal"` = "full": minimal: logo, minimalAction and minimalNote only (checkout, the publishing wizard); no search, categories, footer or tabs.
- `layout?: "page" | "fill"` = "page": page: the window scrolls under a sticky header and the footer follows the content. fill: the shell is exactly the viewport, main is a flex column for inboxes, the footer is hidden and the tab bar sits in the flow.
- `currentPath?: string` = "/": The active route (next: usePathname()). Selects the tab and the category chip; nested routes match by prefix.
- `categories?: MarketplaceCategory[]`: The category tree (MARKETPLACE_SHELL_SAMPLE.categories: the 12 Northwind Market categories with lucide icons, counts and subtrees for Vehicles, Real estate and Electronics). The strip shows the top level; the search suggests any level. Compatible with category-picker's CategoryNode.
- `user?: { name: string; email?: string; avatar?: string; city?: string } | null`: The signed-in buyer (MARKETPLACE_SHELL_SAMPLE.user: Emma Carter, city cluj-napoca). null shows Sign in (loginHref). city is the fallback of Near me.
- `userMenuItems?: UserMenuEntry[]`: The account menu entries above sign out. Default: My account, My listings, Favorites, Messages, Settings and a separator.
- `onSignOut?: () => (void | Promise<unknown>)`: The sign-out row. Default: a toast "Te-ai deconectat".
- `favoritesCount?: number` = 4: The favorites badge (99+ above 99). 0 hides the badge, the icon stays.
- `messagesCount?: number` = 2: Unread messages on the header icon and the Mesaje tab. 0 hides the badges.
- `favoritesHref?: string` = "/favorites": Where the heart points.
- `messagesHref?: string` = "/messages": Where the messages icon and tab point.
- `searchPlaceholder?: string` = "Search 1,284,310 listings": The query field's and the phone field's placeholder. Empty uses labels.searchPlaceholder.
- `defaultQuery?: string` = "": The query the search starts with.
- `defaultLocation?: string` = "": A ro-locations city id the search starts with ("cluj-napoca"); "" is All locations. An unknown id shows as typed.
- `defaultCategory?: string` = "": A category id that scopes the search ("phones"); shown as a removable chip in the box.
- `onSearch?: (query: { query: string; location: string; category: string }) => void`: Runs on Enter, Search, a suggestion or a recent search. Default: navigates to /cautare?q=…&loc=…&cat=… through the router.
- `popularSearches?: string[]`: Suggested while the field is empty (MARKETPLACE_SHELL_SAMPLE.popularSearches: iPhone 14, Bike, 2-bedroom apartment, Sofa, Honda Civic).
- `recentSearches?: string[]`: The recent searches the field starts with (city bike, macbook air); each submit adds one, and each can be removed.
- `locations?: LocationOption[]`: The location combobox's cities. Default: cityOptions() from ro-locations, largest first; All locations and Near me are always on top.
- `searchShortcut?: string` = "/": Focuses the search on desktop and opens the search sheet on phones. "" binds nothing.
- `postHref?: string` = "/post": Where Post a listing and the tab bar's raised action point.
- `onPost?: () => void`: Replaces the postHref link with a button (open a dialog, check sign-in first).
- `minimalAction?: "back" | "close" | "none"` = "back": The minimal variant's leading button.
- `minimalNote?: ReactNode`: The minimal variant's trailing trust note. Default: a lock and Secure payment.
- `onBack?: () => void`: The minimal button. Default: history.back() when there is history, else backHref.
- `backHref?: string` = "/": Where the minimal button goes without history.
- `showCategories?: boolean` = true: The category strip under the header (768px and up).
- `footer?: boolean` = true: The footer with the link columns, the app badges, the cookie settings and the theme (page layout, full variant).
- `footerLinks?: { title: string; links: { label: string; href: string }[] }[]`: The footer columns (MARKETPLACE_SHELL_SAMPLE.footerLinks: Northwind Market, Help, Legal, For business).
- `footerNote?: ReactNode`: Extra content in the footer's bottom row, next to Cookie settings.
- `appBadges?: boolean` = true: App Store and Google Play buttons in the footer (neutral buttons with an icon and text, no brand artwork).
- `tabBar?: boolean` = true: The phone tab bar: Home, Search, the raised Post, Messages and Account.
- `hideTabBar?: boolean` = false: Hides the tab bar for a while (a page with its own sticky bar, thumbnails).
- `cookieConsent?: boolean` = true: Renders CookieConsent until the visitor decides; it sits above the tab bar.
- `consentStorageKey?: string` = "northwind-market-consent": The consent cookie's name (the demo appends -demo so it never touches a real choice).
- `consentCategories?: ConsentCategoryConfig[]`: The consent categories. Default: DEFAULT_CONSENT_CATEGORY_CONFIG.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The fill of Post a listing, Search, the tab bar's raised action and the consent's accept button.
- `loginHref?: string` = "/login": Where Sign in points while signed out.
- `accountHref?: string` = "/account": The Cont tab and the account menu's base path.
- `logo?: ReactNode`: Replaces the default mark and Northwind Market wordmark.
- `locale?: string` = "en-US": Intl locale for the counts.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The active category chip and the active tab.
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link every link renders through (next/link). Default: the LinkProvider's, else <a>.
- `onNavigate?: (href: string) => void`: The router's push for the default search and the account menu (next: useRouter().push).
- `labels?: Partial<MarketplaceShellLabels>`: Every visible string. English by default (DEFAULT_MARKETPLACE_SHELL_LABELS; MARKETPLACE_SHELL_LABELS_EN is the same set under its older name).
- `classNames?: Partial<Record<"header" | "search" | "categories" | "main" | "footer" | "tabs", string>>`: Extra classes for the inner parts.
- `className?: string`: Extra classes for the root. Other props spread onto it.

```tsx
// app/(market)/layout.tsx
"use client"

import Link from "next/link"
import { usePathname, useRouter } from "next/navigation"
import type { ReactNode } from "react"
import { MarketplaceShell } from "@/components/blocks/marketplace-shell"

export default function MarketLayout({ children }: { children: ReactNode }) {
  const pathname = usePathname()
  const router = useRouter()
  return (
    <MarketplaceShell currentPath={pathname} linkComponent={Link} onNavigate={router.push}>
      {children}
    </MarketplaceShell>
  )
}
```

Docs: https://wingo-ui.com/components/marketplace-shell (Markdown: https://wingo-ui.com/components/marketplace-shell.md)

#### Mobile App Home (`mobile-app-home`)

block · Pro · v1.1.0 · install: `npx wingo-ui@latest add mobile-app-home`

The home screen of a marketplace phone app: large title, search, story circles, quick actions, recommended ads, feed tabs and a tab bar.

Scroll and the large title "Home" hands over to a compact glass bar; the feed tabs stick under it. Pull down at the top (touch, or a trackpad scroll up) and the iOS spinner refreshes "For you" with a haptic tick and a fade. Tap the search field: the page swaps to your recent searches (tap one to search it again, x removes it, Clear all clears them), typing filters every ad by title and place, Enter saves the query and calls onSearch, Cancel or Escape closes the search. Tap a story circle to open its full-height sheet with three new ads and See all; the ring turns gray once seen (drag the handle down, tap outside, the close button or Escape to close). Quick action tiles and the bell are links with count badges. Recommended ads sit in a 2-column grid: Show more reveals the next row in place, See all opens the full list, and a heart saves an ad (shared between the grid and the feed). Switch For you, Nearby and Following by tapping, swiping the list sideways or with the arrow keys on the tabs; Load more shows the next page. The bottom tab bar hides while you scroll down and comes back on scroll up; Search focuses the search, Home scrolls back to the top and the raised Post button posts an ad. On a desktop the app is a centered 440px column on a gray backdrop.

npm: motion, lucide-react
Wingo UI dependencies: avatar, badge, bottom-tab-bar, button, drawer, empty-state, favorite-button, large-title-header, list, listing-card, price, pull-to-refresh, skeleton, swipeable-tabs, use-controllable-state, haptics, motion, navigation, number-format, relative-time, text-match, tones, ui-config

Props:
- `title?: ReactNode` = "Home": The large title; it shrinks into the bar as you scroll.
- `subtitle?: ReactNode` = "Hi, Emma": The line under the large title.
- `stories?: AppStory[]`: Story circles { id, label, image?, icon?, seen?, href?, description?, ring?, listings? }; [] hides the rail. Defaults to MOBILE_APP_HOME_SAMPLE.stories (Deals, Bikes, Phones, Homes, Daniel Reed, Greenleaf).
- `quickActions?: AppQuickAction[]`: Up to 8 tiles { id, label, icon, href?, badge?, onSelect? } in a 4-column grid; [] hides them. Defaults to Post an ad, Favorites (4), Saved searches (2), My orders.
- `recommended?: ListingData[]`: The 2-column grid of ad cards; [] hides it. Defaults to MOBILE_APP_HOME_SAMPLE.recommended (the 8 canonical ads).
- `feeds?: Partial<Record<"for-you" | "nearby" | "following", ListingData[]>>`: The ads of each tab, merged over MOBILE_APP_HOME_SAMPLE.feeds (20 each); an empty array shows the tab's empty state.
- `recentSearches?: AppRecentSearch[]`: { id, query } rows shown while the search is open; defaults to MOBILE_APP_HOME_SAMPLE.recentSearches.
- `user?: { name: string; avatar?: string }`: The signed-in person shown as the avatar in the header; defaults to Emma Carter.
- `hrefs?: Partial<MobileAppHomeHrefs>`: Where the bell, avatar, Messages, Post, See all and the empty state's action go (notifications, account, messages, add, recommended, discover).
- `labels?: Partial<MobileAppHomeLabels>`: Every visible string (Romanian by default, DEFAULT_MOBILE_APP_HOME_LABELS); MOBILE_APP_HOME_LABELS_EN is the English set. Nested listingCard, pullToRefresh, swipeableTabs and list pass strings to the composed items.
- `tab?: "for-you" | "nearby" | "following"`: Controlled feed tab; pair it with onTabChange.
- `defaultTab?: "for-you" | "nearby" | "following"` = "for-you": The feed tab the screen opens on while uncontrolled.
- `onTabChange?: (tab: MobileAppHomeTab) => void`: Called when a tab is tapped or swiped to.
- `defaultStory?: string` = "": The id of a story whose sheet is open on mount; empty for none.
- `notificationsCount?: number` = 3: The count on the bell; 0 hides the badge.
- `messagesCount?: number` = 2: The count on the Mesaje tab; 0 hides it.
- `showStories?: boolean` = true: The story circles rail.
- `showQuickActions?: boolean` = true: The grid of quick action tiles.
- `showRecommended?: boolean` = true: The recommended ads grid.
- `recommendedCount?: number` = 4: Recommended ads shown at first; Show more adds this many again until all are shown.
- `pullToRefresh?: boolean` = true: Pull down at the top to refresh the feed (off while searching or loading).
- `refreshShortcut?: string` = "": A key combo in mod+k notation that refreshes the feed like a pull; none by default.
- `tabBar?: boolean` = true: The bottom tab bar with the raised Post action.
- `tabBarVariant?: "bar" | "floating"` = "bar": A full-width glass bar on the bottom edge, or a floating glass pill.
- `desktop?: "column" | "full"` = "column": column: from 768px the app is a centered 440px column on a gray backdrop. full: it stretches (a real PWA on a tablet).
- `pageSize?: number` = 8: Ads per page of a feed; Load more shows the next page.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Unseen story rings, the active tab, the tab bar's active color and raised action, and the text actions.
- `loading?: boolean` = false: Skeleton story circles, tiles, cards and rows in the real layout.
- `animateIn?: boolean` = true: Sections rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for prices, distances, times and counts.
- `currency?: string` = "USD": The currency of ads that do not set their own.
- `now?: Date | number` = "useNow()": The clock for "Today at 2:32 PM"; pass it for stable renders (the demo uses Sep 24, 2026 4:40 PM).
- `onRefresh?: () => (void | Promise<unknown>)`: The pull to refresh; the spinner runs until it settles. Without it the feed reshuffles after 1,2 s.
- `onSearch?: (query: string) => void`: Enter in the search field; the query is also added to the recent searches.
- `onStoryOpen?: (story: AppStory) => void`: A story circle was tapped (its sheet opens and it turns seen).
- `onFavoriteChange?: (listing: ListingData, favorite: boolean) => (void | Promise<unknown>)`: A heart was toggled; a rejected promise rolls it back.
- `onLoadMore?: (tab: MobileAppHomeTab) => (void | Promise<unknown>)`: Load more; the button spins until it settles, then the next page shows. Simulated (900 ms) without it.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the screen (next/link in an app).
- `className?: string`: Classes for the app column.
- `classNames?: Partial<Record<MobileAppHomeSlot, string>>`: Classes for backdrop, header, search, stories, story, actions, recommended, feed and tabBar.

```tsx
// app/(app)/page.tsx
"use client"

import Link from "next/link"
import { useRouter } from "next/navigation"
import { MobileAppHome } from "@/components/blocks/mobile-app-home"

export default function HomePage() {
  const router = useRouter()
  return (
    <MobileAppHome
      linkComponent={Link}
      subtitle="Hi, Emma"
      notificationsCount={3}
      messagesCount={2}
      onSearch={(query) => router.push(`/search?q=${encodeURIComponent(query)}`)}
      onRefresh={() => router.refresh()}
    />
  )
}
```

Docs: https://wingo-ui.com/components/mobile-app-home (Markdown: https://wingo-ui.com/components/mobile-app-home.md)

#### Onboarding Flow (`onboarding-flow`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add onboarding-flow`

A marketplace app's first run: welcome slides, a calm ask for notifications and location, a short profile, preferences and a finish.

Swipe or drag the three welcome slides, use the dots, the arrow keys or Continue; Skip on the slides and Get started on the last one go to the permissions. From there a header shows a back button, a three part progress bar and Skip, which jumps straight to the finish with what you entered so far; every step change slides in from the side it belongs to, moves focus to the step title and is announced ("Step 2 of 4: Permissions"). Permissions: Allow opens the real browser prompt for notifications or location (with simulatePermissions it answers after 600 ms), Not now skips it; each card then shows Allowed, Denied with where to change it, Skipped with Allow anyway, or why the browser cannot do it. Continue is always enabled. A granted location fills the city with the nearest one. Profile: tap the photo to choose, crop or take a picture (optional), type the name, search the city (a full height sheet on phones), and tap interest chips, which are toggle buttons; the counter turns green at the minimum. Continue with a missing name or too few interests shows the errors and focuses the first. Preferences: pick Instantly, Daily or Weekly, toggle the newsletter card and read the summary line update. Finish celebrates with a bouncy check and one ring pulse (and a success haptic on phones), then Go to Home finishes and Start over starts over. Everything you enter is saved as you go, so a reload resumes on the same step with a short "Picking up where you left off" note. On laptops a picture beside the card cross fades per step and per slide; on phones the flow fills the screen with the main button pinned above the safe area. With reduced motion steps cross fade and the check simply appears.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, avatar-upload, button, combobox, image-cropper, input, onboarding-carousel, progress, segmented-control, switch, tag, toast, use-persisted-state, commerce, form-validation, haptics, motion, ro-locations, tones, ui-config

Props:
- `defaultStep?: OnboardingStep` = "welcome": The step shown first (uncontrolled, and the fallback before storage is read): "welcome" | "permissions" | "profile" | "preferences" | "done".
- `step?: OnboardingStep`: The current step, controlled (then nothing is restored from storage for it).
- `onStepChange?: (step: OnboardingStep) => void`: Runs on every step change (mirror it to the URL).
- `slides?: OnboardingSlide[]`: The welcome slides (onboarding-carousel's slide shape). Default: the three Acme Market slides from ONBOARDING_FLOW_SAMPLE with their vignettes and the side panel pictures; custom slides show their image in the side panel.
- `interests?: OnboardingInterest[]`: The chips of the profile step: { id, label, icon, description }. Default: the 12 Acme Market categories of ONBOARDING_FLOW_SAMPLE.interests; icon takes a node or a sample icon name.
- `minInterests?: number` = 3: How many interests the profile needs; 0 makes them optional.
- `permissions?: ("notifications" | "location")[]`: The permissions asked for, default both; [] skips the step.
- `simulatePermissions?: boolean` = false: Answer granted after 600 ms instead of calling the browser (demos, tests); a simulated location is Gheorgheni, Cluj-Napoca.
- `user?: OnboardingUser`: The signed-up person ({ name, avatar, city }): the name the profile starts with and the side panel's profile card. Default ONBOARDING_FLOW_SAMPLE.user (Emma Carter).
- `defaultProfile?: OnboardingProfile`: The profile the flow starts with ({ avatar, name, city, interests }); default empty with the name from user.
- `profile?: OnboardingProfile`: The profile, controlled; onProfileChange gets every draft change.
- `onProfileChange?: (profile: OnboardingProfile) => void`: Every change of the profile draft (photo, name, city, interests).
- `defaultPreferences?: OnboardingPreferences`: The preferences the flow starts with; default { frequency: "daily", newsletter: false }.
- `preferences?: OnboardingPreferences`: The preferences, controlled; onPreferencesChange gets every change.
- `onPreferencesChange?: (preferences: OnboardingPreferences) => void`: Every change of the frequency or the newsletter switch.
- `persistKey?: string` = "onboarding-flow": Local storage key that keeps the step, the drafts and the permission answers, so a closed app resumes where it stopped; empty keeps them in memory.
- `showSkip?: boolean` = true: Skip on the slides and in the header of the later steps.
- `allowRestart?: boolean` = true: The Start over button on the finish screen, which clears the saved progress.
- `art?: "image" | "none"` = "image": The picture beside the card from 1024px, cross fading per step and per slide (tablets show the card alone, centered); none centers the card alone everywhere.
- `onComplete?: (result: OnboardingFlowResult) => (void | Promise<unknown>)`: Go to Home: gets { profile, preferences, permissions } (each permission granted, denied or skipped); a promise spins the button. Default: the toast "Welcome to Acme Market".
- `onUpload?: (blob: Blob, context: AvatarUploadContext) => Promise<string | void>`: Uploads the cropped photo and resolves its url. Default: simulated for 900 ms, then kept as a data url; a failed upload shows a note and the flow continues without a photo.
- `tone?: Tone` = "neutral": The primary buttons, the progress bar, the selected chips, the frequency thumb, the switch and the slides' button and dots.
- `radius?: "sm" | "md" | "lg"` = "md": The card and the side panel, the permission tiles and the controls' corners.
- `loading?: boolean` = false: The card as skeletons of the profile step and a pulsing side panel.
- `animateIn?: boolean` = true: The side panel and the card rise in once when the page mounts on the client (server html is already final).
- `labels?: Partial<OnboardingFlowLabels>`: Every visible string: DEFAULT_ONBOARDING_FLOW_LABELS (Romanian) by default, ONBOARDING_FLOW_LABELS_EN for English; carousel, avatarUpload, cropper and validation carry the composed items' strings.
- `locale?: string` = "en-US": Prices and distances on the slides and the page language (lang).
- `classNames?: Partial<Record<OnboardingFlowSlot, string>>`: Classes for art, main, card, header, progress, step, title, description, footer, permission, interests and done.

```tsx
// app/(app)/welcome/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { OnboardingFlow } from "@/components/blocks/onboarding-flow";

export default function Page() {
  const router = useRouter();
  return (
    <OnboardingFlow
      user={{ name: "Emma Carter" }}
      persistKey="onboarding:ana"
      onUpload={async (blob) => {
        const response = await fetch("/api/avatar", { method: "POST", body: blob });
        if (!response.ok) throw new Error("Upload failed");
        return (await response.json()).url;
      }}
      onComplete={async ({ profile, preferences, permissions }) => {
        await fetch("/api/onboarding", { method: "POST", body: JSON.stringify({ profile, preferences, permissions }) });
        router.push("/");
      }}
    />
  );
}
```

Docs: https://wingo-ui.com/components/onboarding-flow (Markdown: https://wingo-ui.com/components/onboarding-flow.md)

#### Post Listing Wizard (`post-listing-wizard`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add post-listing-wizard`

Posting an ad on a marketplace in seven steps: category, details, photos, price, place, contact and a preview, with an autosaved draft.

Pick the category from icon tiles (drill down, Back, or type to search and press Enter for the first match); a fresh pick shows the path as a chip with Change and moves on by itself, and a title typed before offers Looks like it belongs in Bicycles. Continue (or Enter in a field, Cmd/Ctrl+Enter in the description) checks the step: errors appear under the fields, the stepper marks the step with !, the button shakes and focus goes to the first problem. Details has the title with a 70 character counter, the condition as radio cards, the category's own fields (selects open as bottom sheets on phones) and the description. Photos takes up to 8 photos by drop, picker, camera or paste, each uploads with progress (a failed one offers Retry), drag or Space and the arrow keys reorder them and the first is badged Cover. Price switches between fixed, negotiable, free and swap, shows similar ads' range and the delivery switch. Location is the Romanian address form with Show the exact location. Contact prefills the account. Preview shows the ad as a grid and a list card and a summary whose Edit links go back to a step; Publish ad spins, then the success view with a bouncing check, View ad, Post another ad and the promotion packages. A failed publish shows an alert and keeps the draft. Completed steps in the stepper are clickable; Back never validates. Every change is saved to local storage after a moment (Draft saved 3 s ago); a reload restores it with an alert and Start over, and photos that only lived in the page are dropped with a note. Discard asks before deleting a draft. On phones the wizard fills the screen under the shell's header, with the compact progress on top and Back / Continue pinned above the safe area. Under reduced motion steps crossfade and the check just appears.

npm: react-hook-form, zod, motion, lucide-react
Wingo UI dependencies: address-input, alert, alert-dialog, badge, button, category-picker, currency-input, file-upload, form-wizard, input, listing-card, number-input, phone-input, radio-group, select, switch, textarea, toast, use-persisted-state, commerce, date-utils, form-validation, motion, navigation, relative-time, ro-locations, tones, ui-config

Props:
- `categories?: CategoryNode[]`: The category tree (POST_LISTING_SAMPLE.categories: the 12 marketplace categories with their subcategories and counts). Only leaves can be picked.
- `attributes?: Record<string, CategoryAttributeDef[]>`: The Details fields per leaf category id (POST_LISTING_SAMPLE.attributes: Bicycles, Mobile phones, Apartments). CategoryAttributeDef = { id, label, type: "select" | "text" | "number", options?, required?, unit? }.
- `priceHints?: Record<string, { min: number; max: number }>`: Similar ads' price range in RON per category id, shown under the price (POST_LISTING_SAMPLE.priceHints: Bicycles 900 to 1,500 RON).
- `draft?: ListingDraft`: The ad being written, controlled; pair it with onDraftChange. ListingDraft = { category, categoryPath, title, condition, attributes, description, photos: UploadFile[], priceType, price, currency, location: { county, locality, address?, showExact }, contact: { name, phone, hidePhone, chatOnly }, delivery }.
- `defaultDraft?: ListingDraft`: The starting draft, uncontrolled. Default: an empty ad with the contact and the place taken from user (createEmptyListingDraft). POST_LISTING_SAMPLE.draft is the filled l01 bike.
- `onDraftChange?: (draft: ListingDraft) => void`: Every change to the draft.
- `step?: PostListingStep`: The current step, controlled; pair it with onStepChange.
- `defaultStep?: "category" | "details" | "photos" | "price" | "location" | "contact" | "preview"` = "category": The starting step; the steps before it count as done. The playground fills the l01 bike for every step past the first.
- `onStepChange?: (step: PostListingStep) => void`: Called with the new step on every change.
- `user?: { name: string; phone: string; email: string; locality: string }`: The signed-in seller: prefills Contact and the place, shows the email read only (POST_LISTING_SAMPLE.user: Emma Carter, +40745123456, emma.carter@acme.com, Cluj-Napoca).
- `persistKey?: string` = "post-listing-draft": Local storage key of the autosaved draft and step; "" keeps it in memory. The demo uses demo:post-listing and a Delete draft button in the header.
- `maxPhotos?: number` = 8: The most photos an ad takes; more are rejected with the upload's message.
- `requirePhoto?: boolean` = true: Fotografii needs at least one photo to continue.
- `promotions?: { id: string; label: string; price: number; description?: string; featured?: boolean }[]`: The promotion offer after publishing (POST_LISTING_SAMPLE.promotions: No promotion, 7 days 29 RON, 30 days 79 RON Most popular, Auto refresh 15 RON). [] hides it.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Publish ad, View ad and Promote (brand in the examples).
- `onUpload?: (file: File, context: { signal; onProgress }) => Promise<unknown>`: Uploads one photo; resolve with { url } so the photo shows after its step and survives a reload. Default: a pretend 1,2 s upload with progress that resolves with an object url.
- `onPublish?: (draft: ListingDraft) => Promise<{ id: string; url: string }>`: Publishes the ad. The button spins while it runs; a rejection shows its message in an alert and keeps the draft. Default: a pretend 1,2 s request.
- `onPromote?: (promotion: PostListingPromotion, listing: { id; url }) => (void | Promise<unknown>)`: Buys the chosen package. A rejection shows its message. Default: a pretend request, then a toast.
- `onCancel?: () => void`: After Discard deleted the draft (leave the page here). Default: a toast.
- `defaultPublished?: { id: string; url: string } | null`: Opens on the success view for defaultDraft, as if it had just been published (the promotion example).
- `labels?: Partial<PostListingWizardLabels>`: Every visible string (DEFAULT_POST_LISTING_WIZARD_LABELS, Romanian), counted ones as functions; nested validation, categoryPicker, fileUpload, addressInput, phoneInput, currencyInput and listingCard for the composed items. POST_LISTING_WIZARD_LABELS_EN is the English set.
- `locale?: string` = "en-US": Intl locale for prices, counts, sizes and dates.
- `currency?: string` = "RON": The empty draft's currency; the price field switches between RON and EUR.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The stepper, Continue, the selected category, radio cards, switches and upload progress.
- `radius?: "sm" | "md" | "lg"` = "md": The form panel 12 / 16 / 24px, its tiles, the radio cards, the photo tiles and the listing cards.
- `loading?: boolean` = false: The stepper and the category tiles as skeletons.
- `animateIn?: boolean` = true: The header and the form rise in once when the page mounts on the client (never over server HTML, never with reduced motion).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for View ad and the terms. Default: the provider's (the shell's), then <a>.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"header" | "panel" | "wizard" | "success" | "promote", string>>`: Classes for the parts.

```tsx
// app/(market)/post-ad/page.tsx (the shell lives in the layout with variant="minimal"; mount <Toaster /> once there)
"use client"

import { useRouter } from "next/navigation"
import { PostListingWizard } from "@/components/blocks/post-listing-wizard"

export default function PostAdPage() {
  const router = useRouter()
  return (
    <PostListingWizard
      user={{ name: "Emma Carter", phone: "+40745123456", email: "emma.carter@acme.com", locality: "Cluj-Napoca" }}
      onUpload={async (file, { signal }) => {
        const body = new FormData()
        body.append("photo", file)
        const response = await fetch("/api/photos", { method: "POST", body, signal })
        return response.json() // { url }
      }}
      onPublish={async (draft) => {
        const response = await fetch("/api/listings", { method: "POST", body: JSON.stringify(draft) })
        if (!response.ok) throw new Error("We could not publish your ad. Please try again.")
        return response.json() // { id, url }
      }}
      onCancel={() => router.push("/")}
    />
  )
}
```

Docs: https://wingo-ui.com/components/post-listing-wizard (Markdown: https://wingo-ui.com/components/post-listing-wizard.md)

#### Pricing Page (`pricing-page`)

block · Pro · v1.1.0 · install: `npx wingo-ui@latest add pricing-page`

The pricing page of a SaaS: hero, plans with a monthly or yearly and dollar or euro switch, comparison, quotes, FAQ and a closing call.

Switch the billing period between Monthly and Yearly (the yearly option carries a "2 months free" badge) and every price rolls to its new value; switch the currency between dollars and euros and the prices convert at eurRate, rounded to whole euros. Each plan has one action: it spins while onSelectPlan runs, and without a handler a toast confirms the choice ("Pro plan, yearly"). Hover, focus or tap the (i) next to a feature or comparison row to read its hint. Below the plans the comparison is a table with a sticky row of plans on desktop and a plan picker with one list on phones. The FAQ is an accordion: Enter or Space opens a question, arrow keys move between them. On phones the header keeps the logo, Try for free and a menu button that opens a bottom sheet with the links (drag the handle, tap outside or press Escape to close); the plans become a swipeable carousel that starts on the featured plan (or a plain stack), the quotes a snap rail, the FAQ one column and the closing buttons stack. Tab starts with a skip link to the content. Sections rise in once on mount and the closing band as it scrolls into view; reduced motion keeps everything still.

npm: motion, lucide-react
Wingo UI dependencies: accordion, avatar, badge, button, card, drawer, pricing-table, segmented-control, separator, toast, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `plans?: PricingPlan[]`: The plans, priced in USD per user per month; defaults to PRICING_PAGE_SAMPLE.plans (Free, Start, Pro featured, Business).
- `comparison?: PricingComparisonGroup[]`: The comparison table below the plans; defaults to PRICING_PAGE_SAMPLE.comparison (5 groups, 24 rows).
- `faqs?: PricingFaq[]`: { question, answer } pairs for the FAQ accordion; links inside answers are underlined. Defaults to PRICING_PAGE_SAMPLE.faqs (8 questions).
- `testimonials?: PricingTestimonial[]`: { quote, name, role, company, avatar? } cards; defaults to PRICING_PAGE_SAMPLE.testimonials (3 quotes).
- `logos?: string[]`: Customer wordmarks under the plans; defaults to PRICING_PAGE_SAMPLE.logos.
- `labels?: Partial<PricingPageLabels>`: Every visible string (Romanian by default, DEFAULT_PRICING_PAGE_LABELS); PRICING_PAGE_LABELS_EN is the English set. labels.pricingTable passes strings to the plans table.
- `hrefs?: Partial<PricingPageHrefs>`: Where the header, the closing band and the FAQ link go: home, current (the nav link marked current), signIn, signUp, demo, contact.
- `period?: "monthly" | "yearly"`: Controlled billing period; pair it with onPeriodChange.
- `defaultPeriod?: "monthly" | "yearly"` = "yearly": The billing period the page opens on while uncontrolled.
- `onPeriodChange?: (period: BillingPeriod) => void`: Called when the period switch changes.
- `currency?: string` = "USD": The currency the page opens on; the switch changes it afterwards.
- `currencies?: string[]` = "[\"USD\", \"EUR\"]": The options of the currency switch; a single entry hides it.
- `eurRate?: number` = 1.08: Units of the base currency per euro for the conversion; euro prices round to whole euros per plan.
- `design?: "classic" | "bold"` = "classic": The page's look. classic is the original page; bold has heavy display type over a grid backdrop, an inverted featured plan with a strong ring, 28px cards, larger prices, FAQ cards and a full-width closing band.
- `featuredStyle?: "raised" | "outline" | "inverted"` = "raised": How the featured plan stands out, passed to PricingTable. Applies to the classic design; bold always inverts it.
- `mobileLayout?: "carousel" | "stack"` = "carousel": Plans on phones: a swipeable carousel that starts on the featured plan, or a plain stack.
- `showComparison?: boolean` = true: The full comparison under the plans.
- `showLogos?: boolean` = true: The customer wordmarks band.
- `showTestimonials?: boolean` = true: The three customer quotes.
- `showFaq?: boolean` = true: The FAQ section.
- `showCta?: boolean` = true: The closing call to action band.
- `header?: boolean` = true: The sticky marketing header with its phone menu; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer with link columns.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The featured plan, its button, the hero glow and the closing band's main action. brand is the marketing orange.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The switches' thumbs and the FAQ's open state.
- `radius?: "sm" | "md" | "lg"` = "md": Surface radius of the plan cards, quote cards and the closing band.
- `loading?: boolean` = false: Skeleton plan cards and quotes in the real layout; the switches wait.
- `animateIn?: boolean` = true: Sections rise in once on mount and the closing band as it scrolls into view; off in thumbnails.
- `locale?: string` = "en-US": Intl locale for the prices.
- `onSelectPlan?: (planId: string, period: BillingPeriod, currency: string) => (void | Promise<unknown>)`: A plan's action; a returned promise keeps its button loading. Without it the page waits 900 ms and toasts "Pro plan, yearly". A plan's own cta.onClick wins.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link used by the header, nav, buttons and footer (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<PricingPageSlot, string>>`: Classes for header, hero, switches, plans, logos, testimonials, faq, cta and footer.

Parts:
- `PRICING_PAGE_DESIGNS` (constant): The design names in order: ["classic", "bold"].
- `PricingPageDesign` (type): "classic" | "bold", the values of the design prop.

```tsx
// app/(marketing)/pricing/page.tsx
"use client"

import Link from "next/link"
import { useRouter } from "next/navigation"
import { PricingPage } from "@/components/blocks/pricing-page"

export default function PricingRoute() {
  const router = useRouter()
  return (
    <PricingPage
      linkComponent={Link}
      defaultPeriod="yearly"
      onSelectPlan={(planId, period, currency) =>
        router.push(`/sign-up?plan=${planId}&period=${period}&currency=${currency}`)
      }
    />
  )
}
```

Docs: https://wingo-ui.com/components/pricing-page (Markdown: https://wingo-ui.com/components/pricing-page.md)

#### Register Page (`register-page`)

block · Pro · v1.0.1 · install: `npx wingo-ui@latest add register-page`

The sign-up screen of a CRM: account with password rules, company details from the CUI, email code and a welcome step.

Sign up in up to three steps shown as bars above the form; completed bars are buttons that go back, and each change is announced ("Step 2 of 3: Company"). Account: "Sign up with Google" (Apple, Microsoft) spins on the pressed button and skips the email check; name, work email (a gmail, yahoo, outlook, hotmail or icloud address shows a warning to use the company address), a password with a strength meter and a rules checklist that opens on focus, the required terms checkbox with its links, the optional product news checkbox and Continue. Fields validate when you leave them and as you fix them; submitting empty shows every error and focuses the first. An email that already has an account (emma.carter@acme.com in the demo) shows a red alert with Sign in and Forgot password?. Company: type a CUI with or without RO and press Enter or Search; an invalid control digit is an error and never calls the lookup, the button spins while the ANAF lookup runs, a match fades in the name, the address and a VAT registered badge (Edit switches to manual fields), no match asks for manual entry and a failed lookup offers Try again and Fill in by hand. Pick a role (a bottom sheet on phones) and a team size, then Continue, or Skip. Verify: type or paste the 6 digit code and the sixth digit submits (123456 passes), a wrong code shakes the cells and shows an alert, Resend the code waits with a live countdown, Change the email goes back with the email selected. With verify link the step offers Open Gmail or Outlook for those domains and I confirmed my address. Done: a bouncy check, three next step rows and Open Acme CRM. Going back keeps what you typed. Steps slide in from the side they belong to and focus moves to the step title; on phones the form fills the screen with 48px fields and the hero is gone; with reduced motion steps cross-fade.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: alert, badge, button, checkbox, input, otp-input, password-input, segmented-control, select, separator, steps, toast, use-controllable-state, use-cooldown, form-validation, invoicing, motion, navigation, tones, ui-config

Props:
- `defaultStep?: RegisterStep` = "account": The step shown first (uncontrolled); step / onStepChange control it. A step the flow does not have shows account.
- `step?: RegisterStep`: The current step, controlled: "account" | "company" | "verify" | "done".
- `onStepChange?: (step: RegisterStep) => void`: Runs on every step change (mirror it to the URL or the router).
- `companyStep?: boolean` = true: The optional company step: CUI lookup, role and team size, with Skip.
- `verify?: "code" | "link" | "none"` = "code": code: a 6 digit code step; link: a check your email step with a confirm button; none: straight to done.
- `providers?: AuthProvider[]`: Social sign-up buttons, default REGISTER_PROVIDERS (Google, Apple, Microsoft); [] hides them and the divider.
- `showProviders?: boolean` = true: Shortcut for providers={[]} when false.
- `plan?: ReactNode` = "Pro · 14 days free, no card": The badge above the account title (labels.plan by default); a node replaces the badge, null or an empty string hides it.
- `passwordMinLength?: number` = 8: Minimum password length: the rule, the checklist and the strength meter.
- `passwordMinScore?: number` = 2: The lowest scorePassword result (0 to 4) the password must reach; 0 accepts any password of the minimum length.
- `freeMailWarning?: boolean` = true: A warning (not an error) under the email for gmail.com, yahoo.com, yahoo.ro, outlook.com, hotmail.com and icloud.com.
- `defaultValues?: Partial<RegisterValues>`: Prefills every step (name, email, password, terms, marketing, company).
- `defaultCompany?: CompanyLookup | null`: A lookup result the company step opens with (name, address, vatPayer).
- `onRegister?: (values: RegisterValues) => (void | Promise<unknown>)`: After the account step: create the account and send the code. Default: simulated, rejects "There is already an account with this email" for emma.carter@acme.com; a rejection with that message or code "email-taken" shows the sign-in and password links.
- `onLookupCui?: (cui: string) => Promise<CompanyLookup | null>`: Looks up a valid CUI (normalized with formatCui). Default: the REGISTER_PAGE_SAMPLE.companies table (Tech Solutions SRL for RO12345674 and the other sample clients) after 900 ms; null asks for manual entry, a rejection offers a retry.
- `onCompany?: (company: RegisterCompany) => (void | Promise<unknown>)`: Saves the company step (name, cui, role, teamSize, address, vatPayer). Default: simulated.
- `onVerify?: (code: string) => (void | Promise<unknown>)`: Checks the 6 digit code. Default: 123456 passes, anything else rejects "That code is not right".
- `onResend?: () => (void | Promise<unknown>)`: Sends the code or the link again; the button then waits resendSeconds. Default: simulated.
- `onProvider?: (id: string) => (void | Promise<unknown>)`: Starts a social sign-up; the button spins until it settles, then the flow skips to the company step (or done). Default: simulated for 1.2 s.
- `onDone?: () => void`: The Open Acme CRM button. Default: the toast "Welcome to Acme CRM" (the page mounts its own Toaster then).
- `resendSeconds?: number` = 30: Wait before the code or the link can be sent again (use-cooldown).
- `layout?: "split" | "centered" | "card"` = "split": split: the form beside a hero from 1024px; centered: no hero, the form in a card from 640px; card: no hero, the form in a raised card at every width, centered on a dotted, softly tinted backdrop with the logo above and the links below.
- `heroSide?: "start" | "end"` = "end": Which side the hero sits on in the split layout.
- `heroImage?: string` = "": A photo behind the hero with a dark scrim and white text; empty keeps the neutral card hero. The demo passes /demo/laptop.jpg.
- `hero?: ReactNode`: Replaces the hero content (badge, title, feature checklist and customer names).
- `logo?: ReactNode`: Top-left of the form column; default the Acme CRM mark and name.
- `size?: "md" | "lg"` = "lg": Fields and buttons: lg is 48px, md 40px (44px on touch); the code cells stay 48px.
- `loginHref?: string` = "/sign-in": The "Sign in" links (footer and the email taken alert); "" hides them.
- `forgotHref?: string` = "/sign-in#forgot": The "Forgot password?" link of the email taken alert; "" hides it.
- `termsHref?: string` = "/termeni": The terms link in the checkbox and the footer; "" leaves plain text.
- `privacyHref?: string` = "/confidentialitate": The privacy link in the checkbox and the footer; "" leaves plain text.
- `tone?: Tone` = "neutral": The primary buttons, the steps, the checkboxes, the team size thumb and the plan badge.
- `radius?: "sm" | "md" | "lg"` = "md": The hero, the card, the tiles and the controls' corners.
- `animateIn?: boolean` = true: The logo, form, footer and hero rise in once when the page mounts on the client (server html is already final).
- `labels?: Partial<RegisterPageLabels>`: Every visible string: DEFAULT_REGISTER_PAGE_LABELS (Romanian) by default, REGISTER_PAGE_LABELS_EN for English; steps takes the steps indicator strings, validation the form-validation messages.
- `locale?: string` = "en-US": Sets the page language (lang).
- `linkComponent?: (props: LinkComponentProps) => ReactNode`: The router link for the sign-in, legal and next step links (next/link); default <a>.
- `classNames?: Partial<Record<RegisterPageSlot, string>>`: Classes for formColumn, header, body, footer, hero, steps, step, title and form.

```tsx
// app/(auth)/inregistrare/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { RegisterPage } from "@/components/blocks/register-page";

export default function Page() {
  const router = useRouter();
  return (
    <RegisterPage
      heroImage="/images/office.jpg"
      onRegister={async (values) => {
        const response = await fetch("/api/register", { method: "POST", body: JSON.stringify(values) });
        if (response.status === 409) throw Object.assign(new Error("There is already an account with this email"), { code: "email-taken" });
        if (!response.ok) throw new Error("We could not create the account");
      }}
      onLookupCui={async (cui) => {
        const response = await fetch(`/api/anaf?cui=${cui}`);
        return response.ok ? response.json() : null;
      }}
      onVerify={async (code) => {
        const response = await fetch("/api/verify", { method: "POST", body: JSON.stringify({ code }) });
        if (!response.ok) throw new Error("That code is not right");
      }}
      onDone={() => router.push("/")}
    />
  );
}
```

Docs: https://wingo-ui.com/components/register-page (Markdown: https://wingo-ui.com/components/register-page.md)

#### Settings Page (`settings-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add settings-page`

The account settings of a back office: profile, account, notifications, billing, security and a danger zone, with a save bar.

Pick a section in the left column (arrow keys move between them) or, with nav="tabs", in the tabs on top; on phones the sections are an iOS style list that pushes the section in with a back button and swipe back. Profile: upload a photo (crop, progress ring, remove), edit the name, title and a bio with a counter, the phone with its country, the language, a searchable time zone and the date format. Account: the email is read only with Verified; Change opens a dialog (a bottom sheet on phones) that asks for the new address and the current password, sends a 6 digit code (123456 passes, the sixth digit submits, Resend code waits 30 s) and then changes it. The workspace address checks itself when you leave the field (Checking…, then Available or Taken; "acme software" gets "Lowercase letters, digits and hyphens only"). Notifications: a switch per event and channel with a column toggle for all (one group per event on phones); switches save at once and flip back with a toast if the save fails. Quiet hours turn on with a switch and take two times (22:00 to 08:00 reads "next day"); the digest is a segmented choice. Billing: the plan with Change plan (a dialog to pick Start, Pro or Business with the monthly total) and Cancel (a confirmation; the plan then shows its end date and a way to resume it), the usage of users, AI tokens and storage, the card with Update, the company details with a CUI check and the address, and the invoices (cards on phones) with a download link each. Security: Change password opens a dialog with the strength meter and rules; Turn on starts a three step wizard: scan the QR code or copy the key, type the code (123456), then copy or download the ten backup codes; the badge On pops in and Turn off asks first. Revoke any other session or all of them at once; the current one cannot be revoked. Danger zone: Export counts up in a toast and then offers the file; Delete account asks you to type DELETE first. Any text change slides up the save bar with Discard and Save (mod+s); a failed save keeps the draft, shakes the bar and shows why, invalid fields turn red and the first one takes focus. Switching sections with unsaved changes asks first.

npm: motion, lucide-react, react-hook-form, zod
Wingo UI dependencies: settings-layout, avatar-upload, address-input, qr-code, input, textarea, phone-input, select, switch, segmented-control, time-picker, input-group, password-input, otp-input, copy-button, badge, button, table, list, usage-meter, alert-dialog, dialog, alert, toast, form-validation, use-cooldown, use-controllable-state, commerce, date-utils, file-export, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `section?: "profil" | "cont" | "notificari" | "facturare" | "securitate" | "pericol"`: The open section, controlled; pair it with onSectionChange (a route per section).
- `defaultSection?: "profil" | "cont" | "notificari" | "facturare" | "securitate" | "pericol"` = "profil": The section open on mount.
- `onSectionChange?: (section: SettingsPageSection) => void`: Called when another section opens (after the unsaved changes question).
- `sections?: SettingsPageSection[]` = "all six": Which sections exist, in this order.
- `profile?: SettingsProfile`: Emma Carter's profile: photo, name, title, bio, phone, language, time zone, date format (SETTINGS_PAGE_SAMPLE.profile).
- `account?: SettingsAccount`: The email with its verified flag and the workspace name and address (SETTINGS_PAGE_SAMPLE.account).
- `notifications?: SettingsNotificationPrefs`: Event by channel switches, quiet hours and the digest (SETTINGS_PAGE_SAMPLE.notifications).
- `notificationEvents?: { id: string; label: string; description?: string }[]`: The rows of the notifications grid: Overdue invoice, Payment received, Deal won, Mention, Task assigned, Weekly report.
- `channels?: ("email" | "push" | "sms")[]` = "all three": The notification columns.
- `billing?: SettingsBilling`: Plan, renewal, seats, AI tokens, storage, the card, the company details and the invoices (SETTINGS_PAGE_SAMPLE.billing).
- `plans?: SettingsPlan[]`: The plans offered by Change plan: Start, Pro, Business with the price per user (SETTINGS_PAGE_SAMPLE.plans).
- `sessions?: SettingsSession[]`: Signed in devices: MacBook Pro (current), iPhone 14, Windows (SETTINGS_PAGE_SAMPLE.sessions).
- `timeZones?: { value: string; label: string; suggested?: boolean; keywords?: string[] }[]`: The time zone picker's options, suggested ones first (SETTINGS_PAGE_SAMPLE.timeZones).
- `takenSlugs?: string[]`: Workspace addresses already in use, for the default availability check.
- `twoFactorEnabled?: boolean`: Two-step verification, controlled; pair it with onTwoFactorChange.
- `defaultTwoFactorEnabled?: boolean` = false: Two-step verification on at mount (On instead of Turn on).
- `onTwoFactorChange?: (enabled: boolean) => (void | Promise<unknown>)`: Turns two-step verification on (after the code checks out) or off (after the confirmation). Default: a simulated request.
- `twoFactorSecret?: string` = "JBSWY3DPEHPK3PXP": The base32 key shown under the QR code, in groups of four, with a copy button.
- `twoFactorUri?: string` = "otpauth://totp/Acme%20CRM:ana.pop%40acme.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme%20CRM": The otpauth:// address the QR code encodes.
- `backupCodes?: string[]`: The ten backup codes of the last step (generated with a fixed seed in the sample).
- `verifyTwoFactorCode?: (code: string) => (boolean | Promise<boolean>)`: Checks the authenticator code. Default: 123456 passes.
- `passwordChangedAt?: Date | number`: When the password last changed ("Last changed on Jun 12, 2026").
- `loginAlerts?: boolean` = true: The starting state of Alerte la autentificare.
- `verifyEmailCode?: (email: string, code: string) => (boolean | Promise<boolean>)`: Checks the code sent to the new email. Default: 123456 passes.
- `checkWorkspaceAddress?: (slug: string) => (boolean | Promise<boolean>)`: Whether a workspace address is free; runs when the field loses focus and before a save. Default: takenSlugs after 600 ms.
- `nav?: "sidebar" | "tabs"` = "sidebar": The section navigation from 768px: a left column or tabs on top.
- `saveBarPosition?: "sticky" | "fixed"` = "sticky": Where the save bar sits: at the bottom of the content column, or pinned to the window. Phones always pin it.
- `saveShortcut?: string` = "mod+s": Saves the open section while it has changes; "" turns the key off.
- `confirmLeave?: boolean` = true: Asks before switching sections with unsaved changes.
- `resendSeconds?: number` = 30: How long Retrimite codul waits in the email dialog.
- `defaultDialog?: "none" | "email" | "password" | "two-factor" | "plan" | "cancel-plan" | "delete"` = "none": Opens with this dialog on desktop; the section that owns it has to be the one open (email in cont, password and two-factor in securitate, plan and cancel-plan in facturare, delete in pericol).
- `defaultProfileDraft?: Partial<SettingsProfileDraft>`: Edits applied to the profile form on mount, so it opens with unsaved changes.
- `onSave?: (section: SettingsFormSection, values: SettingsSaveValues[SettingsFormSection]) => (void | Promise<unknown>)`: Saves the open section's text fields from the save bar (profil, cont, notificari, facturare). A rejection keeps the draft and shows its message in the bar. Default: a simulated request.
- `onPreferenceChange?: (preference: string, value: boolean) => (void | Promise<unknown>)`: Switches that save on their own: "notificari.matrix.<event>.<channel>", "notificari.matrix.*.<channel>", "notificari.quietHours", "securitate.loginAlerts". A rejection flips the switch back with a toast.
- `onUpload?: (blob: Blob, context: { file; signal; onProgress }) => Promise<string | void>`: Uploads the cropped photo; resolve the new url. Default: a pretend upload with progress that keeps the local preview.
- `onEmailChange?: (email: string, currentPassword: string) => (void | Promise<unknown>)`: Runs after the code for the new address checks out.
- `onPasswordChange?: (values: { currentPassword: string; newPassword: string }) => (void | Promise<unknown>)`: The password dialog's submit; a rejection shows its message in the dialog.
- `onSessionRevoke?: (session: SettingsSession) => (void | Promise<unknown>)`: Signs a device out (once per device for Sign out all others).
- `onExport?: () => (void | Promise<unknown>)`: Export your data. Default: a toast that counts up, then offers a JSON download.
- `onDeleteAccount?: () => (void | Promise<unknown>)`: Runs after the typed confirmation.
- `onPlanChange?: (planId: string | null) => (void | Promise<unknown>)`: A plan id switches (or resumes); null cancels at the end of the period.
- `onDirtyChange?: (dirty: boolean) => void`: The open section has unsaved changes (hide a phone tab bar while true, one bar per edge).
- `paymentMethodHref?: string` = "/settings/billing/card": Where Update on the card goes.
- `labels?: Partial<SettingsPageLabels>` = "DEFAULT_SETTINGS_PAGE_LABELS": Every visible string, Romanian by default; SETTINGS_PAGE_LABELS_EN is the English set. Nested keys carry the composed items' strings (validation, avatarUpload, cropper, phoneInput, timePicker, select, addressInput, qrCode, table, list, usageMeter).
- `locale?: string` = "en-US": Intl locale for numbers, money, dates and relative times.
- `currency?: string` = "USD": The currency of the plan prices and the invoices.
- `now?: Date | number`: The reference time for the sessions and the date format sample; default the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accent of the section navigation, the switches, the primary buttons and the save button.
- `radius?: "sm" | "md" | "lg"` = "md": Corner size of the settings groups (12 / 16 / 24px).
- `loading?: boolean` = false: The open section as skeleton rows in the real layout.
- `animateIn?: boolean` = true: The page rises in once when it mounts on the client; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the card and invoice links; default the surrounding LinkProvider's (the admin shell's).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<"layout" | "section" | "saveBar", string>>`: Classes for the settings layout, every settings group and the save bar.
- `failNextSave?: boolean` = false: The built-in pretend save (no onSave) fails once, so the error in the bar and the kept draft can be seen and tested.

```tsx
// app/(admin)/settings/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell>{children}</AdminShell>)
"use client"

import { SettingsPage } from "@/components/blocks/settings-page"

export default function SettingsRoute() {
  return (
    <SettingsPage
      onSave={async (section, values) => {
        const res = await fetch(`/api/settings/${section}`, { method: "PUT", body: JSON.stringify(values) })
        if (!res.ok) throw new Error("We could not save. Please try again.")
      }}
      onPreferenceChange={async (preference, value) => {
        await fetch("/api/settings/preferences", { method: "PATCH", body: JSON.stringify({ preference, value }) })
      }}
      onTwoFactorChange={async (enabled) => {
        await fetch("/api/security/2fa", { method: enabled ? "POST" : "DELETE" })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/settings-page (Markdown: https://wingo-ui.com/components/settings-page.md)

#### Users Admin Page (`users-admin-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add users-admin-page`

The team page of a back office: members and invitations with seats, roles with a permissions matrix and a save bar, and the audit log.

The header shows the seats in use ("8 of 10 seats", turning amber from 80%), Invite people and a menu with Export members CSV (downloads a ; separated file that opens cleanly in Excel) and Security settings. Switch between Members, Roles and permissions and Audit log with a click or the arrow keys; the panel slides the way you went. In Members, a warning lists who has no two-step verification with Send reminder; search by name or email, sort by name, role or last activity, change a role in its picker (it saves with a spinner, a failure rolls back with a toast, and the last administrator cannot be demoted), remove someone from the row menu after a confirmation (you and the owner cannot be removed), and in Invitations resend or revoke an invitation. Invite people opens the invite dialog (a bottom sheet on phones): paste or type addresses, pick a role, add a message and send; addresses already in the team are refused. With every seat taken it first offers Add 5 seats. In Roles and permissions, pick a role card (or a column heading) to highlight it, create a role with New role (name, description, copy permissions from a role), and tick permissions in the matrix: requirements follow along, changed cells get a dot, and a save bar slides up with the count, Discard and Save (mod+s while it shows). Leaving the tab with unsaved changes asks first. On phones the matrix picks one role at a time with chips and the save bar floats above the edge. In Audit log, search, filter by user, action, record type, severity or IP, change the period, expand a row for its changes, and export the rows as CSV; your own changes on this page appear at the top. Toasts confirm each action. Sections rise in once on mount; reduced motion keeps them still.

npm: motion, lucide-react
Wingo UI dependencies: alert, alert-dialog, audit-log, avatar, badge, button, card, date-range-picker, dialog, filter-builder, input, members-table, page-header, permissions-matrix, select, settings-layout, tabs, textarea, toast, usage-meter, use-controllable-state, date-utils, file-export, filters, motion, navigation, number-format, relative-time, tones, ui-config

Props:
- `companyName?: string` = "Northwind Labs": The workspace named in the description ("Manage who has access to Northwind Labs").
- `members?: MemberData[]`: The team; defaults to the eight people of Northwind Labs (USERS_ADMIN_SAMPLE.members). The member with isYou cannot change their own role or leave.
- `invites?: PendingInvite[]`: Pending invitations; defaults to USERS_ADMIN_SAMPLE.invites (one pending, one expired). Invitations that have not expired hold a seat.
- `roles?: MemberRole[]`: The roles a member can have: Administrator, Manager, Sales, Accounting, Read only (USERS_ADMIN_SAMPLE.roles).
- `permissionRoles?: PermissionRole[]`: The matrix's columns, same ids as roles; the locked Administrator holds every permission (USERS_ADMIN_SAMPLE.permissionRoles).
- `permissionGroups?: PermissionGroup[]`: Six groups (Clients, Deals, Invoices, Reports, Automations, Settings and team) with 4 to 6 permissions and their requirements (USERS_ADMIN_SAMPLE.permissionGroups).
- `permissions?: PermissionsValue`: The saved permissions, controlled (role id to granted permission ids); pair it with onPermissionsSave.
- `defaultPermissions?: PermissionsValue`: The saved permissions while uncontrolled; defaults to USERS_ADMIN_SAMPLE.permissions.
- `onPermissionsSave?: (value: PermissionsValue) => (void | Promise<unknown>)`: The save bar's Save (and mod+s). A promise keeps it saving; a rejection keeps the bar with its message. Default: a simulated request.
- `defaultPermissionsDraft?: PermissionsValue`: Edits already pending when the page opens (the save bar showing); USERS_ADMIN_SAMPLE.permissionsDraft has three.
- `onDirtyChange?: (dirty: boolean) => void`: The matrix differs from the saved value, or no longer does; hide a phone tab bar while true so one bar holds the bottom edge.
- `auditEvents?: AuditEvent[]`: The audit log, newest first; defaults to 120 events over the last 30 days (USERS_ADMIN_SAMPLE.auditEvents). Changes made on this page are added on top.
- `auditActions?: Record<string, AuditActionDef>`: Verb, tone, group and icon per action key; defaults to USERS_ADMIN_SAMPLE.auditActions with icons per key.
- `auditTargetTypes?: Record<string, string>`: Record type names for the filter and the export (member, role, client, invoice, deal, settings, login).
- `defaultAuditFilter?: FilterGroup`: The audit log's first filter; usersAdminAuditTypeFilter(["invoice"]) shows only invoices.
- `auditPeriodDays?: number` = 7: The audit log's period on open: the last n days up to now; 0 shows all time.
- `seats?: { used: number; total: number }` = "{ used: 8, total: 10 }": Seats in the plan. Pending invitations reserve seats; with none free, inviting offers to add seats first.
- `seatStep?: number` = 5: How many seats "Add seats" adds to the plan.
- `tab?: "members" | "roles" | "audit"`: The open tab, controlled; pair it with onTabChange.
- `defaultTab?: "members" | "roles" | "audit"` = "members": The tab open on mount while uncontrolled.
- `onTabChange?: (tab: UsersAdminTab) => void`: Called on a tab switch (after the unsaved changes question, when there is one).
- `require2fa?: boolean` = true: The workspace requires two-step verification: members without it get a warning with Send reminder.
- `canManage?: boolean` = true: False is the read-only view: no invite, role changes, removals, new roles or matrix edits, and an info alert says why.
- `saveShortcut?: string` = "mod+s": Saves the matrix while it has unsaved changes; "" turns the key off.
- `inviteOpen?: boolean`: The invite dialog, controlled (the shell's "Invite a teammate" command can open it).
- `defaultInviteOpen?: boolean` = false: Opens the invite dialog on mount (the seats dialog when every seat is taken).
- `onInviteOpenChange?: (open: boolean) => void`: Called when the invite dialog opens or closes.
- `securityHref?: string` = "/settings/security": Where "Security settings" in the header menu goes.
- `onInvite?: (input: { emails: string[]; role: string; message?: string }) => (void | Promise<unknown>)`: Sends invitations; the page adds them to Invitations. Default: a simulated request.
- `onRoleChange?: (member: MemberData, role: string) => (void | Promise<unknown>)`: A member's new role; a rejection rolls the picker back and shows its message. The last administrator cannot be demoted.
- `onRemove?: (member: MemberData) => (void | Promise<unknown>)`: Removes a member after the confirmation; the seat frees up.
- `onResendInvite?: (invite: PendingInvite) => (void | Promise<unknown>)`: Sends an invitation again and restarts its seven days.
- `onRevokeInvite?: (invite: PendingInvite) => (void | Promise<unknown>)`: Revokes an invitation; a rejection brings the row back.
- `onRoleCreate?: (role: { name: string; description?: string; copyFrom?: string }) => (void | Promise<unknown>)`: Creates a role from the New role dialog; the page adds its column with the copied permissions. A rejection shows under the name.
- `onExport?: (members: MemberData[]) => (void | Promise<unknown>)`: Export members CSV. Default: downloads members-<date>.csv with ; separators and a byte order mark.
- `onRemindTwoFactor?: (members: MemberData[]) => (void | Promise<unknown>)`: Send reminder, with the members who have no two-step verification.
- `onAddSeats?: (count: number) => (void | Promise<unknown>)`: Adds seatStep seats from the seats dialog; then the invite form opens.
- `labels?: Partial<UsersAdminPageLabels>` = "DEFAULT_USERS_ADMIN_PAGE_LABELS": Every visible string, English by default (USERS_ADMIN_PAGE_LABELS_EN); USERS_ADMIN_PAGE_LABELS_RO is the Romanian set. Nested keys carry the composed items' strings (membersTable, permissionsMatrix, auditLog, auditFilters, auditPeriod, usageMeter).
- `locale?: string` = "en-US": Intl locale for numbers, dates and relative times.
- `now?: Date | number`: The reference time for last activity, invitations and the audit period; default the live clock.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accent of the invite button, the tabs, the selected role, the checkboxes and the save bar.
- `radius?: "sm" | "md" | "lg"` = "md": Corner size of the role cards and the skeleton panels (12 / 16 / 24px).
- `loading?: boolean` = false: Skeletons in the real layout: the header, the seats, the member rows, the role cards and the matrix.
- `animateIn?: boolean` = true: The header and the panel rise in once when the page mounts on the client; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header's links; default the surrounding LinkProvider's (the admin shell's).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<UsersAdminPageSlot, string>>`: Classes for header, seats, panels, members, twoFactor, readOnly, roles, roleList, roleCard, permissions, saveBar, audit, seatsDialog and roleDialog.

```tsx
// app/(admin)/team/page.tsx (the shell lives in app/(admin)/layout.tsx: <AdminShell>{children}</AdminShell>)
"use client"

import { UsersAdminPage } from "@/components/blocks/users-admin-page"

export default function TeamPage() {
  return (
    <UsersAdminPage
      companyName="Northwind Labs"
      onInvite={async ({ emails, role }) => {
        await fetch("/api/team/invitations", { method: "POST", body: JSON.stringify({ emails, role }) })
      }}
      onRoleChange={async (member, role) => {
        await fetch(`/api/team/${member.id}`, { method: "PATCH", body: JSON.stringify({ role }) })
      }}
      onPermissionsSave={async (permissions) => {
        await fetch("/api/roles", { method: "PUT", body: JSON.stringify(permissions) })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/components/users-admin-page (Markdown: https://wingo-ui.com/components/users-admin-page.md)

### Templates

#### About Page (`about-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add about-page`

A SaaS about page: hero collage, mission, stats, a milestone timeline, values, team, investors, press, offices and a careers band.

Join the team goes to the careers page; Read our story glides down to the mission (instantly under reduced motion) and moves focus there. The stats roll up once when they scroll into view. The timeline reads top to bottom from 2021 to today, with the current milestone raised and marked Now. Team cards link to each person's socials, and the We're hiring tile goes to the open roles. Each press card is one link to the article (it opens in a new tab). The call to action band leads to open roles or the contact page. The hero rises in once on mount; reduced motion keeps it still.

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, stats-section, feature-grid, team-section, logo-cloud, cta-section, avatar, button, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "editorial" | "bold"` = "classic": The whole page's look. classic follows heroLayout; editorial: a centered header, a magazine story hero with huge start-aligned type and key facts (founded, teams, people, funding) instead of the collage, a larger mission, hairlines between sections, small caps eyebrows, stats beside their heading, the timeline and press as plain entries under rules, numbered values, team rows, a ruled investor grid, offices without tiles, a start-aligned closing and a centered footer; bold: a pill header, a split hero on a gradient mesh with heavy type, an inverted numbers band, illustrated value cards, large team cards, investor tiles, rounder cards with bigger figures, an image band and a wordmark footer. headerProps and footerProps still win.
- `heroLayout?: "split" | "centered" | "stacked"` = "split": split: copy left, the collage right; centered: copy over a wide collage; stacked: title and copy side by side over it. Applies to the classic design.
- `heroMedia?: ReactNode`: Replaces the drawn collage (a team photo, a video); null hides it.
- `stats?: StatsSectionItem[]` = "ABOUT_STATS": { value, decimals?, prefix?, suffix?, label, description? } figures.
- `milestones?: AboutMilestone[]` = "ABOUT_MILESTONES": { year, title, description, metric? } from 2021 to 2026; the last is the current one.
- `values?: FeatureGridItem[]` = "ABOUT_VALUES": { icon?, title, description } rows of the values list.
- `team?: TeamMember[]` = "ABOUT_TEAM": { name, role, bio?, avatar?, socials? } people of the team grid.
- `investors?: LogoCloudItem[]` = "ABOUT_INVESTORS": Investor wordmarks drawn as a glyph and a name.
- `press?: AboutPressQuote[]` = "ABOUT_PRESS": { outlet, icon?, quote, href?, date?, className? } press cards.
- `offices?: AboutOffice[]` = "ABOUT_OFFICES": { city, country, address, description, people, since } studio cards.
- `labels?: Partial<AboutPageLabels>` = "DEFAULT_ABOUT_PAGE_LABELS": Every visible string, including the mission and the collage copy.
- `openRoles?: number` = 9: The count on the We're hiring tile; 0 hides the tile.
- `careersHref?: string` = "/careers": Join the team, the hiring tile and the band's primary action.
- `contactHref?: string` = "/contact": The band's secondary action.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hero glow, the collage's people tile, the current milestone and the hiring tile.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Join the team and the primary action of the careers band.
- `showMission?: boolean` = true: The mission statement.
- `showStats?: boolean` = true: The figures.
- `showTimeline?: boolean` = true: The milestone timeline.
- `showValues?: boolean` = true: The values list.
- `showTeam?: boolean` = true: The team grid.
- `showInvestors?: boolean` = true: The investor logos.
- `showPress?: boolean` = true: The press quotes.
- `showOffices?: boolean` = true: The studios.
- `showCta?: boolean` = true: The careers band.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The hero rises in once on mount and the band lifts as it scrolls in; off in thumbnails.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and inner links (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<AboutPageSlot, string>>`: Classes for header, hero, collage, mission, stats, timeline, values, team, investors, press, offices, cta and footer.

Parts:
- `ABOUT_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "editorial", "bold"].
- `AboutPageDesign` (type): "classic" | "editorial" | "bold".
- `ABOUT_PAGE_SAMPLE` (constant): All the sample content in one object: stats, milestones, values, team, investors, press and offices.
- `ABOUT_STATS` (constant): Four figures: teams, people, funding and rating.
- `ABOUT_MILESTONES` (constant): Six milestones from 2021 to 2026.
- `ABOUT_VALUES` (constant): Six values with lucide icons.
- `ABOUT_TEAM` (constant): The eight people of TEAM_SECTION_SAMPLE.
- `ABOUT_INVESTORS` (constant): Six fictional investor wordmarks.
- `ABOUT_PRESS` (constant): Three press quotes from fictional outlets.
- `ABOUT_OFFICES` (constant): New York, London and Berlin studios.
- `DEFAULT_ABOUT_PAGE_LABELS` (constant): The English strings.
- `AboutPageProps` (type): Props of AboutPage.
- `AboutMilestone` (type): One step of the timeline.
- `AboutPressQuote` (type): One press card.
- `AboutOffice` (type): One studio card.

```tsx
// app/(marketing)/about/page.tsx
"use client"

import Link from "next/link"
import { AboutPage } from "@/components/templates/about-page"

export default function AboutRoute() {
  return <AboutPage linkComponent={Link} openRoles={9} />
}
```

Docs: https://wingo-ui.com/templates/about-page (Markdown: https://wingo-ui.com/templates/about-page.md)

#### Affiliate Page (`affiliate-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add affiliate-page`

A partner program page: a 30% commission hero, an earnings calculator, steps, commission tiers, partner quotes, an application form and FAQ.

Apply now and How it works jump down the page; the announcement pill jumps to the tiers. The hero shows a partner dashboard drawn in code. In the calculator, drag the slider (or use the arrow keys) for the number of teams you refer each month and pick what your audience mostly buys: the monthly commission after a year and the first-year total roll to their new values in USD, with the per-customer amount under them. The tiers (Partner, Pro Partner, Elite: commission, cookie window, what it takes and perks) are a table from 768px and one card per tier on phones. The application form checks name, email, a website or channel link, the audience size and at least 20 characters on how you would promote Acme; errors show under each field and focus jumps to the first one. Send application spins while it sends, then the form turns into a confirmation with Send another application. The FAQ opens one answer at a time.

npm: motion, lucide-react
Wingo UI dependencies: cta-section, faq-section, hero-section, marketing-footer, marketing-header, marketing-section, stats-section, testimonials-section, animated-counter, button, input, select, slider, textarea, motion, navigation, tones, ui-config

Props:
- `planMixes?: AffiliatePlanMix[]` = "AFFILIATE_PLAN_MIXES": The calculator's plan options: { value, label, description, monthlyBill }.
- `steps?: AffiliateStep[]` = "AFFILIATE_STEPS": How it works: { icon, title, description }.
- `tiers?: AffiliateTier[]` = "AFFILIATE_TIERS": Commission tiers: { id, name, rate, cookieDays, requirement, perks, highlight? }.
- `testimonials?: AffiliateQuote[]` = "AFFILIATE_QUOTES": Partner quotes: { quote, name, role, company, metric? }.
- `faq?: AffiliateFaq[]` = "AFFILIATE_FAQ": { question, answer } pairs.
- `audienceSizes?: AffiliateOption[]` = "AFFILIATE_AUDIENCE_SIZES": The audience size options of the form.
- `stats?: StatsSectionItem[]` = "AFFILIATE_STATS": The bold design's numbers band: { value, decimals?, prefix?, suffix?, label }.
- `labels?: Partial<AffiliatePageLabels>` = "DEFAULT_AFFILIATE_PAGE_LABELS": Every visible string, the form errors included.
- `rate?: number` = 0.3: The commission the calculator uses (0.3 = 30%).
- `defaultReferrals?: number` = 5: Teams referred per month the calculator starts on.
- `defaultPlanMix?: string` = "mixed": The plan mix the calculator starts on.
- `maxReferrals?: number` = 50: The end of the referrals slider.
- `design?: "classic" | "bold"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a magazine size title on a gradient mesh with the dashboard under it, an inverted numbers band, the earnings on an inverted panel, solid step icons with big numbers, rounder tier and form cards, a featured quote, FAQ cards, a closing card that emails the partner kit and a wordmark footer. headerProps and footerProps still win.
- `heroLayout?: "split" | "centered" | "stacked"` = "split": split: copy left, dashboard right; centered and stacked put the dashboard under the copy. Applies to the classic design.
- `showDashboard?: boolean` = true: The drawn partner dashboard in the hero.
- `showCalculator?: boolean` = true: The earnings calculator.
- `showSteps?: boolean` = true: How it works.
- `showTiers?: boolean` = true: The commission tiers.
- `showTestimonials?: boolean` = true: Partner quotes.
- `showFaq?: boolean` = true: The program FAQ.
- `showCta?: boolean` = true: The closing call to action.
- `ctaVariant?: "inverted" | "soft" | "split" | "plain"` = "inverted": The look of the closing call to action. Applies to the classic design.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `onApply?: (application: AffiliateApplication) => (void | Promise<unknown>)`: Sends the application { name, email, website, audience, promotion }; a returned promise keeps the button loading and a rejection shows an error. Without it the form waits 900 ms and succeeds.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: Sends the partner kit from the bold design's closing card; a rejected promise shows an error. Without it the form waits 900 ms and succeeds.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The slider, step tiles, the yearly figure, the popular tier badge and FAQ accents.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary buttons of the hero, the form and the closing band.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the amounts (always USD) and percentages.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<AffiliatePageSlot, string>>`: Classes for hero, stats, calculator, steps, tiers, testimonials, apply, form, faq and cta.

Parts:
- `AffiliateCalculator` (component): The earnings calculator on its own: a referrals slider, a plan mix select and the animated monthly and first-year commission. Takes div props.
- `AffiliateTiers` (component): The tiers as a table from 768px and one card per tier on phones. Takes div props.
- `AffiliateApplyForm` (component): The validated application form with loading and an inline confirmation. Takes div props.
- `affiliateEarnings` (function): affiliateEarnings(referralsPerMonth, monthlyBill, rate) returns { perCustomer, monthly, yearly }: the commission at month 12 and the total over the first 12 months.
- `AFFILIATE_PLAN_MIXES` (constant): Mostly Pro ($144 a month), a mix ($252) and mostly Business ($360).
- `AFFILIATE_STEPS` (constant): Apply, share your link, get paid.
- `AFFILIATE_TIERS` (constant): Partner 30%, Pro Partner 35% and Elite 40%.
- `AFFILIATE_STATS` (constant): 1,800+ partners, $2.4M paid out, a 40% top rate and 12 months of commission.
- `AFFILIATE_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold"].
- `AffiliatePageDesign` (type): "classic" | "bold".
- `AFFILIATE_QUOTES` (constant): Three partner quotes with earnings metrics.
- `AFFILIATE_FAQ` (constant): Five program questions.
- `AFFILIATE_AUDIENCE_SIZES` (constant): Four audience size ranges.
- `DEFAULT_AFFILIATE_PAGE_LABELS` (constant): The English strings.
- `AffiliateApplication` (type): { name, email, website, audience, promotion }.
- `AffiliatePlanMix` (type): { value, label, description, monthlyBill }.
- `AffiliateTier` (type): { id, name, rate, cookieDays, requirement, perks, highlight? }.
- `AffiliateStep` (type): { icon, title, description }.
- `AffiliateQuote` (type): { quote, name, role, company, metric? }.
- `AffiliateFaq` (type): { question, answer }.
- `AffiliateOption` (type): { value, label }.
- `AffiliatePageProps` (type): Props of AffiliatePage.

```tsx
// app/(marketing)/partners/page.tsx
"use client"

import Link from "next/link"
import { AffiliatePage } from "@/components/templates/affiliate-page"

export default function PartnersRoute() {
  return (
    <AffiliatePage
      linkComponent={Link}
      onApply={async (application) => {
        const res = await fetch("/api/partners/apply", { method: "POST", body: JSON.stringify(application) })
        if (!res.ok) throw new Error("Application failed")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/affiliate-page (Markdown: https://wingo-ui.com/templates/affiliate-page.md)

#### Blog Page (`blog-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add blog-page`

A SaaS blog index: a featured post, category chips, live search, a grid or list of post cards, pagination and a newsletter band.

The page opens with the featured post as one large card; every card is a single link to /blog/<slug> with its focus ring on the card. Tap a category chip (All, Product, Engineering, Design, Company, Guides; each shows its post count) to filter, or type in the search field (press / to focus it) and the cards filter live by title, excerpt and author while the field shows the result count. While filtering, the featured card steps aside and its post joins the grid; cards slide into place. No match shows an empty state with Clear filters. Load more posts appends the next page (the button spins while it loads and the bar under it shows how many you have seen), or numbered pagination pages through them and scrolls back to the filters. The newsletter band validates the email and confirms inline. On phones the chips become one row that scrolls sideways, the grid collapses to one column and the list layout puts a square cover beside each title.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, avatar, badge, button, empty-state, pagination, search-input, use-controllable-state, motion, navigation, text-match, tones, ui-config

Props:
- `design?: "classic" | "editorial" | "minimal"` = "classic": The whole page's look. classic follows the layout props; editorial: a centered header, a display-size title over a heavy rule, the featured post as a big story with a wide square cover, tab-style category filters, posts as ruled rows with the date in its own column, a split newsletter and a centered footer; minimal: a transparent header, a narrow column, the featured post and every post as plain text lines with no covers or cards, text filters, no gray band and a simple footer. headerProps and footerProps still win.
- `posts?: BlogPost[]` = "BLOG_POSTS": Newest first: { slug, title, excerpt, category, date, readingTime, author, cover?, featured?, href? }. The one with featured: true leads the page.
- `categories?: BlogCategory[]` = "BLOG_CATEGORIES": { value, label } chips after All; a post's category is a value.
- `labels?: Partial<BlogPageLabels>` = "DEFAULT_BLOG_PAGE_LABELS": Every visible string: the heading, chips, search, empty state, pagination and newsletter copy.
- `category?: string`: Controlled category filter ("all" or a category value); pair it with onCategoryChange.
- `defaultCategory?: string` = "all": The category the page opens on while uncontrolled.
- `onCategoryChange?: (category: string) => void`: Called when a chip is picked.
- `defaultQuery?: string` = "": The search text the page opens with.
- `layout?: "grid" | "list"` = "grid": grid: cover on top of each card; list: one post per row with the cover beside it. Applies to the classic design.
- `columns?: 2 | 3` = 3: Grid columns on desktop (one on phones, two on tablets). Applies to the classic design.
- `pagination?: "load-more" | "numbers"` = "load-more": load-more appends a page per press; numbers pages through the posts.
- `pageSize?: number` = 6: Posts per page (after the featured one).
- `onLoadMore?: () => (void | Promise<unknown>)`: Load more; a returned promise keeps the button loading. Without it the page waits 700 ms.
- `showFeatured?: boolean` = true: The featured post card under the heading.
- `showCategories?: boolean` = true: The category chips.
- `showSearch?: boolean` = true: The search field.
- `showNewsletter?: boolean` = true: The newsletter band before the footer.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `cardVariant?: "plain" | "raised"` = "plain": plain: covers and text right on the page; raised: each post on a surface card. Applies to the classic design.
- `covers?: "color" | "mono"` = "color": Drawn covers tinted per category, or all neutral.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected chip, the pagination and the newsletter button.
- `radius?: "sm" | "md" | "lg"` = "md": Radius of covers and cards: 12, 16 or 24px.
- `loading?: boolean` = false: Skeleton cards in the real layout.
- `animateIn?: boolean` = true: The heading and featured post rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for dates and counts.
- `getPostHref?: (post: BlogPost) => string`: Where a card links; default post.href, else /blog/<slug>.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The newsletter signup; a rejected promise shows the error. Without it the form waits 900 ms and succeeds.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<BlogPageSlot, string>>`: Classes for intro, featured, filters, chips, search, posts, pagination and newsletter.

Parts:
- `BlogPostCard` (component): One post as a single stretched link: grid, list or the large featured layout. Takes article props.
- `BlogCover` (component): A cover drawn in code (a category tint, a pattern picked per post and the category glyph), or a photo when src is set. Takes div props; size it with an aspect class.
- `BlogPostMeta` (component): The author avatar, name, date and reading time of a post. Takes div props.
- `formatBlogDate` (function): formatBlogDate("2026-09-29", "en-US") gives "Sep 29, 2026", in UTC so server and browser agree.
- `BLOG_POSTS` (constant): Twelve sample Acme posts from 2026, newest first; the board performance post is featured.
- `BLOG_CATEGORIES` (constant): Product, Engineering, Design, Company and Guides.
- `BLOG_AUTHORS` (constant): The Acme team as BlogAuthor objects with roles and bios.
- `BLOG_CATEGORY_ICONS` (constant): The lucide glyph drawn on each category's covers.
- `BLOG_CATEGORY_TONES` (constant): The tint of each category's covers and label.
- `DEFAULT_BLOG_PAGE_LABELS` (constant): The English strings.
- `BlogPost` (type): { slug, title, excerpt, category, date, readingTime, author, cover?, featured?, href? }.
- `BlogAuthor` (type): { name, role, avatar?, bio?, href? }.
- `BlogCategory` (type): { value, label }.
- `BLOG_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "editorial", "minimal"].
- `BlogPageProps` (type): Props of BlogPage.
- `BlogPageDesign` (type): "classic" | "editorial" | "minimal".

```tsx
// app/(marketing)/blog/page.tsx
"use client"

import Link from "next/link"
import { BlogPage } from "@/components/templates/blog-page"
import { BLOG_POSTS } from "@/components/templates/blog-page-data"

export default function BlogRoute() {
  return (
    <BlogPage
      linkComponent={Link}
      posts={BLOG_POSTS}
      onSubscribe={(email) =>
        fetch("/api/newsletter", { method: "POST", body: JSON.stringify({ email }) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/blog-page (Markdown: https://wingo-ui.com/templates/blog-page.md)

#### Blog Post Page (`blog-post-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add blog-post-page`

One blog article: byline, share actions, a drawn cover, a Markdown body with a sticky table of contents, reading progress and related posts.

A thin bar at the top of the window fills as you read. The breadcrumb links back to the blog and the category (on phones it becomes one back link). Copy link copies the address and turns into "Link copied" for two seconds; X, LinkedIn and email open a share in a new tab. The article is rendered from Markdown: headings, lists, a code block with a copy button, a quote, a table that scrolls sideways on phones and a figure drawn in code. On desktop the table of contents sticks beside the article, marks the section being read with a progress ring and jumps to a section on click; below 1024px it becomes a pill pinned under the header that opens a bottom sheet. Was this helpful? answers Yes with a thank-you, or No with a short comment box. The author card links to more posts, the three related posts are single links, and the newsletter band validates the email and confirms inline.

npm: motion, lucide-react
Wingo UI dependencies: blog-page, marketing-section, marketing-header, marketing-footer, avatar, breadcrumb, button, markdown, table-of-contents, textarea, motion, navigation, tones, ui-config

Props:
- `design?: "classic" | "editorial" | "minimal"` = "classic": The whole page's look. classic follows the layout props; editorial: a centered header, a display-size title, the byline under a heavy rule, a square wide cover, the contents on the left of a narrow reading column, quotes set as pull quotes between rules, ruled boxes, related posts as ruled rows, a split newsletter and a centered footer; minimal: a transparent header, a narrower page with no cover, a plain byline, flat outlined boxes, related posts as text lines, no gray band and a simple footer. headerProps and footerProps still win.
- `article?: BlogArticle` = "BLOG_ARTICLE_SAMPLE": The post: BlogPost fields plus subtitle, body (Markdown), tags and url (for share links; default the page's own address).
- `relatedPosts?: BlogPost[]` = "BLOG_RELATED_SAMPLE": Up to three cards under the article.
- `categories?: BlogCategory[]` = "BLOG_CATEGORIES": Display names for category values.
- `figures?: Record<string, BlogFigureBar[] | ReactNode>`: Drawn figures for Markdown images whose src is #figure-<name>: bars for a bar chart, or any node. The sample has render-times.
- `labels?: Partial<BlogPostPageLabels>` = "DEFAULT_BLOG_POST_PAGE_LABELS": Every visible string: share, contents, feedback, author, related and newsletter copy.
- `showProgress?: boolean` = true: The reading progress bar at the top of the window.
- `showToc?: boolean` = true: The table of contents: sticky beside the article on desktop, a pill and a sheet on phones.
- `showShare?: boolean` = true: Copy link, X, LinkedIn and email, in the byline and after the article.
- `showCover?: boolean` = true: The cover under the byline (the minimal design has none).
- `showFeedback?: boolean` = true: The "Was this helpful?" box.
- `showAuthor?: boolean` = true: The author bio card.
- `showRelated?: boolean` = true: The related posts section.
- `showNewsletter?: boolean` = true: The newsletter band before the footer.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `tocVariant?: "line" | "dots" | "plain"` = "line": The table of contents' look: a rail with a moving indicator, dots or plain links.
- `cardVariant?: "plain" | "raised"` = "plain": Related post cards right on the page or on surface cards. Applies to the classic design.
- `covers?: "color" | "mono"` = "color": Drawn covers tinted per category, or neutral.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The progress bar, the active contents entry, links, figure bars and the buttons.
- `radius?: "sm" | "md" | "lg"` = "md": Radius of the cover, cards and boxes.
- `animateIn?: boolean` = true: The article header rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for dates and figure numbers.
- `blogHref?: string` = "/blog": Where Blog in the breadcrumb and All posts link; the category crumb adds ?category=<value>.
- `onFeedback?: (helpful: boolean, comment?: string) => (void | Promise<unknown>)`: Was this helpful?; called on Yes, on No and again with the comment. A returned promise keeps the button loading; without it the page waits 600 ms.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The newsletter signup; without it the form waits 900 ms and succeeds.
- `markdownProps?: Partial<MarkdownProps>`: Passed to the article's Markdown (components, codeLineNumbers, linkTarget...).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<BlogPostPageSlot, string>>`: Classes for progress, hero, breadcrumb, title, byline, share, cover, toc, body, tags, feedback, author, related and newsletter.

Parts:
- `BlogBarFigure` (component): A horizontal bar chart drawn with spans, so it can sit inside a Markdown paragraph. Takes span props.
- `markdownToc` (function): markdownToc(source) returns the h2 and h3 of a Markdown string as TocItem[], with the ids Markdown's headingIds gives them.
- `BLOG_ARTICLE_SAMPLE` (constant): The sample article: "How we made Acme's board 10x faster" by Noah Mitchell.
- `BLOG_RELATED_SAMPLE` (constant): Three related posts from BLOG_POSTS.
- `DEFAULT_BLOG_POST_PAGE_LABELS` (constant): The English strings.
- `BlogArticle` (type): BlogPost & { subtitle?, body, tags?, url? }.
- `BlogFigureBar` (type): { label, value }.
- `BLOG_POST_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "editorial", "minimal"].
- `BlogPostPageProps` (type): Props of BlogPostPage.
- `BlogPostPageDesign` (type): "classic" | "editorial" | "minimal".

```tsx
// app/(marketing)/blog/[slug]/page.tsx
"use client"

import Link from "next/link"
import { notFound, useParams } from "next/navigation"
import { BlogPostPage } from "@/components/templates/blog-post-page"
import { BLOG_ARTICLE_SAMPLE } from "@/components/templates/blog-post-page-data"

export default function BlogPostRoute() {
  const { slug } = useParams<{ slug: string }>()
  if (slug !== BLOG_ARTICLE_SAMPLE.slug) notFound()
  return (
    <BlogPostPage
      linkComponent={Link}
      article={BLOG_ARTICLE_SAMPLE}
      onFeedback={(helpful, comment) =>
        fetch("/api/feedback", { method: "POST", body: JSON.stringify({ slug, helpful, comment }) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/blog-post-page (Markdown: https://wingo-ui.com/templates/blog-post-page.md)

#### Careers Page (`careers-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add careers-page`

A SaaS careers page: mission, team mosaic, values, benefits, filterable open roles with a job drawer and apply form, hiring steps.

See open roles glides down to the role list (How we hire to the process). Filter the roles by typing in the search field (press / to focus it), by department with the chip row (each chip counts its matches; it scrolls sideways on phones) and by location with the select (a bottom sheet on phones); the count updates as you go, and when nothing matches an empty state offers Clear filters and an open application. Roles are grouped by department. Each row is one link to /careers/<slug>: a plain click opens the job in a side panel (a draggable bottom sheet on phones) with the description, responsibilities, requirements, benefits and an apply form; Cmd or Ctrl click opens the link instead. The form checks name, email, an optional LinkedIn URL and the resume (drop or pick a PDF or Word file), then Submit application spins while onApply runs and the form turns into a confirmation. Escape, the close button or dragging the sheet down closes it. Don't see your role? opens the same form as an open application. The hero rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, avatar, badge, button, drawer, empty-state, file-upload, input, search-input, select, textarea, team-section, cta-section, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic: a centered hero with soft number tiles and the team mosaic, raised value cards, a gray benefits band and a raised closing panel; bold: a pill header, a huge start-aligned hero on a soft glow, the numbers on an inverted band, large team cards with a hiring tile, filled icon tiles, step cards, an inverted closing band and a wordmark footer; minimal: a transparent header, a start-aligned hero with the numbers on one ruled row, compact team rows, values and benefits without cards or gray bands, hairline role rows, a plain closing call and a simple footer. headerProps and footerProps still win.
- `roles?: CareersRole[]` = "CAREERS_ROLES": { slug, title, department, location, workplace, type, salaryMin?, salaryMax?, salaryCurrency?, isNew?, summary, responsibilities, requirements, niceToHave? }; 9 sample roles.
- `departments?: string[]` = "CAREERS_DEPARTMENTS": The department chips and groups, in this order; departments without roles are skipped.
- `values?: CareersValue[]` = "CAREERS_VALUES": { icon?, title, description } cards of the values grid.
- `perks?: CareersPerk[]` = "CAREERS_PERKS": { icon?, title, description } benefits; their titles also list in the job drawer.
- `team?: CareersTeamMember[]` = "CAREERS_TEAM": { name, role } tiles of the team mosaic, drawn as initials on a color from the name.
- `moments?: CareersMoment[]` = "CAREERS_MOMENTS": { title, description, quote? } wide tiles between the faces; the first one is the large inverted tile.
- `stats?: CareersStat[]` = "CAREERS_STATS": { value, label } figures under the hero.
- `steps?: CareersStep[]` = "CAREERS_STEPS": { title, duration?, description } of the hiring process.
- `labels?: Partial<CareersPageLabels>` = "DEFAULT_CAREERS_PAGE_LABELS": Every visible string, including the form's messages.
- `defaultDepartment?: string` = "all": The department chip selected on load: all or a department name.
- `roleHref?: (role: CareersRole) => string` = "(role) => `/careers/${role.slug}`": Where each role row links to.
- `roleDetail?: "drawer" | "link"` = "drawer": drawer: a click opens the job and the apply form in a side panel (a sheet on phones); link: rows navigate to roleHref.
- `onOpenRole?: (role: CareersRole, event: MouseEvent<HTMLAnchorElement>) => void`: Runs when a role row is clicked; event.preventDefault() keeps the drawer closed and stops the navigation.
- `onApply?: (application: CareersApplication) => (void | Promise<unknown>)`: Sends { role?, name, email, linkedin, resume?, note }; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `groupByDepartment?: boolean` = true: Groups the list under department headings while All is selected.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected department chip, the process numbers and the New badges (success while neutral).
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": See open roles, Submit application and Send an open application; brand is the marketing orange.
- `showStats?: boolean` = true: The figures under the hero.
- `showTeam?: boolean` = true: The team mosaic.
- `showValues?: boolean` = true: The values grid.
- `showPerks?: boolean` = true: The benefits band.
- `showProcess?: boolean` = true: The hiring process steps and the How we hire button.
- `showCta?: boolean` = true: The Don't see your role? band.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer (its Careers link counts the open roles).
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the salary ranges (like $165,000 to $195,000).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and role rows (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<CareersPageSlot, string>>`: Classes for header, hero, stats, team, values, perks, roles, filters, role, process, cta, drawer and footer.

Parts:
- `CAREERS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `CareersPageDesign` (type): "classic" | "bold" | "minimal".
- `formatSalary` (function): formatSalary(role, locale?): the role's yearly range in currency, like "$165,000 to $195,000".
- `CAREERS_PAGE_SAMPLE` (constant): All the sample content in one object: roles, departments, values, perks, team, moments, stats and steps.
- `CAREERS_ROLES` (constant): The 9 sample roles across Engineering, Design, Product, Customer success and Marketing.
- `CAREERS_DEPARTMENTS` (constant): The sample department order.
- `CAREERS_VALUES` (constant): Six sample values with lucide icons.
- `CAREERS_PERKS` (constant): Eight sample benefits with lucide icons.
- `CAREERS_TEAM` (constant): Ten sample teammates.
- `CAREERS_MOMENTS` (constant): Three sample mosaic tiles: a quote, release day and team week.
- `CAREERS_STATS` (constant): Four sample figures.
- `CAREERS_STEPS` (constant): The four hiring steps: Intro call, Take-home, Team interview, Offer.
- `DEFAULT_CAREERS_PAGE_LABELS` (constant): The English strings.
- `CareersPageProps` (type): Props of CareersPage.
- `CareersRole` (type): One open role.
- `CareersApplication` (type): { role?, name, email, linkedin, resume?, note }: what onApply receives.

```tsx
// app/(marketing)/careers/page.tsx
"use client"

import Link from "next/link"
import { CareersPage } from "@/components/templates/careers-page"

export default function CareersRoute() {
  return (
    <CareersPage
      linkComponent={Link}
      onApply={async (application) => {
        const body = new FormData()
        body.set("role", application.role?.slug ?? "open")
        body.set("name", application.name)
        body.set("email", application.email)
        body.set("linkedin", application.linkedin)
        body.set("note", application.note)
        if (application.resume) body.set("resume", application.resume)
        const response = await fetch("/api/applications", { method: "POST", body })
        if (!response.ok) throw new Error("Could not apply")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/careers-page (Markdown: https://wingo-ui.com/templates/careers-page.md)

#### Changelog Page (`changelog-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add changelog-page`

A public changelog: email and RSS subscribe, releases on a sticky version rail with drawn covers, New / Improved / Fixed groups.

Subscribe with an email (validated, then confirmed inline) or open the RSS feed. The segmented filter (All, New, Improved, Fixed, each with its count; arrow keys move between them) keeps only the releases and groups of that kind, and the list slides into place while the count updates. Each release shows its version, date and a Latest badge for the newest; from 768px they sit on a rail that sticks beside the release while you read it, on phones they sit above it. The version pill is a permalink to the release. Entries with a Learn more link go to the related page. Load older releases appends the next ones (the button spins, the bar under it shows how many you have seen).

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, badge, button, pagination, segmented-control, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `design?: "classic" | "minimal" | "editorial"` = "classic": The whole page's look. classic follows the layout props; minimal: a transparent header, a smaller heading, one centered column on a plain timeline (a hairline with a dot per release), no covers, plain version links and a simple footer; editorial: a centered header, huge display type, large version numbers on the sticky rail, no covers, small caps group labels, heavy rules between releases and a centered footer. headerProps and footerProps still win.
- `releases?: ChangelogRelease[]` = "CHANGELOG_RELEASES": Newest first: { version, date, title, summary, changes: { type, text, href? }[], cover?, glyph?, tone? }.
- `labels?: Partial<ChangelogPageLabels>` = "DEFAULT_CHANGELOG_PAGE_LABELS": Every visible string; labels.newsletter goes to the subscribe form.
- `filter?: "all" | "new" | "improved" | "fixed"`: Controlled filter; pair it with onFilterChange.
- `defaultFilter?: "all" | "new" | "improved" | "fixed"` = "all": The filter the page opens on while uncontrolled.
- `onFilterChange?: (filter: ChangelogFilter) => void`: Called when the filter changes.
- `pageSize?: number` = 4: Releases shown before Load older releases, and how many each press adds.
- `onLoadMore?: () => (void | Promise<unknown>)`: Load older releases; a returned promise keeps the button loading. Without it the page waits 700 ms.
- `layout?: "rail" | "stacked"` = "rail": rail: version and date on a sticky left rail from 768px; stacked: above each release in one centered column. Applies to the classic design.
- `covers?: "color" | "mono" | "none"` = "color": Drawn covers tinted per release, all neutral, or none. Applies to the classic design.
- `showSubscribe?: boolean` = true: The email form and the RSS button under the heading.
- `showFilter?: boolean` = true: The New / Improved / Fixed filter.
- `rssHref?: string` = "/changelog/rss.xml": The RSS button's link; empty hides it.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The email signup; without it the form waits 900 ms and succeeds.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The filter thumb, the subscribe button and the load bar.
- `radius?: "sm" | "md" | "lg"` = "md": Cover radius: 12, 16 or 24px.
- `animateIn?: boolean` = true: The heading, subscribe row and filter rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for dates and counts.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<ChangelogPageSlot, string>>`: Classes for intro, subscribe, toolbar, releases, release and pagination.

Parts:
- `ChangelogReleaseEntry` (component): One release: the version rail, cover, title, summary and the New / Improved / Fixed groups. Takes article props; its id is the permalink anchor.
- `ChangelogCover` (component): A cover drawn in code: a tint, a grid, the version in large type and a glyph; or a photo when src is set. Takes div props; size it with an aspect class.
- `CHANGELOG_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal", "editorial"].
- `ChangelogPageDesign` (type): "classic" | "minimal" | "editorial".
- `changelogAnchor` (function): changelogAnchor("2.10") gives "v2-10", the id of a release (link to /changelog#v2-10).
- `CHANGELOG_RELEASES` (constant): Eight sample Acme releases from 2026, 3.0 down to 2.4.
- `CHANGELOG_GLYPHS` (constant): The lucide glyphs a release's glyph key picks.
- `CHANGELOG_TYPE_TONES` (constant): The badge tone of each group: New success, Improved info, Fixed neutral.
- `DEFAULT_CHANGELOG_PAGE_LABELS` (constant): The English strings.
- `ChangelogRelease` (type): { version, date, title, summary, changes, cover?, glyph?, tone? }.
- `ChangelogChange` (type): { type: "new" | "improved" | "fixed", text, href? }.
- `ChangelogPageProps` (type): Props of ChangelogPage.

```tsx
// app/(marketing)/changelog/page.tsx
"use client"

import Link from "next/link"
import { ChangelogPage } from "@/components/templates/changelog-page"
import { CHANGELOG_RELEASES } from "@/components/templates/changelog-page-data"

export default function ChangelogRoute() {
  return (
    <ChangelogPage
      linkComponent={Link}
      releases={CHANGELOG_RELEASES}
      rssHref="/changelog/rss.xml"
      onSubscribe={(email) =>
        fetch("/api/changelog/subscribe", { method: "POST", body: JSON.stringify({ email }) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/changelog-page (Markdown: https://wingo-ui.com/templates/changelog-page.md)

#### Compare Page (`compare-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add compare-page`

An "Acme vs competitor" page: a verdict hero, why teams switch, a feature table, a yearly price comparison, migration steps, quotes and FAQ.

Pick Taskly, Boardify or Planhub in the segmented control above the versus card (arrow keys move between them) and the whole page follows: the title and one-line verdict, the three quick facts, the six reasons teams switch, every table row, the price comparison, the import steps, the switcher quotes and the FAQ. The feature table groups rows under Planning, Docs, Automations, Security and Pricing with a check, a cross, a partial mark or a short value; the info button beside a value shows its note in a tooltip (hover or keyboard focus). Its header row with both wordmarks sticks under the page header while you scroll, and the Only show differences switch hides the rows where both products match. Drag the team size slider (or use the arrow keys) from 2 to 100 people, with 10, 25 and 50 marked: both yearly costs roll to their new totals with the per-seat breakdown and add-ons, and the band below says how much Acme saves, or honestly says when the other tool costs less. On phones the table becomes one card per feature with both values side by side and notes written out under them, the steps and price cards stack, and nothing scrolls sideways.

npm: motion, lucide-react
Wingo UI dependencies: cta-section, faq-section, feature-grid, hero-section, marketing-footer, marketing-header, marketing-section, testimonials-section, animated-counter, button, segmented-control, slider, switch, tooltip, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `competitors?: Competitor[]` = "COMPETITORS": Every competitor the switcher offers: { id, name, icon, tagline, verdict, facts, reasons, groups, pricing, steps, quotes, faq }.
- `defaultCompetitor?: string` = "taskly": The competitor the page opens on while uncontrolled.
- `competitor?: string`: Controlled competitor id; pair it with onCompetitorChange (e.g. to route to /compare/<id>).
- `onCompetitorChange?: (id: string) => void`: Called when the switcher changes.
- `design?: "classic" | "bold"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a magazine size title on a gradient mesh with the versus card under it, illustrated reason cards, the table on a raised panel, an inverted Acme price card, big step numbers, a featured quote, FAQ cards, a closing band over a drawn scene and a wordmark footer. headerProps and footerProps still win.
- `showSwitcher?: boolean` = true: The segmented control above the versus card; off for a page about one competitor.
- `heroLayout?: "split" | "centered"` = "split": split: copy left, versus card right; centered: copy over the card. Applies to the classic design.
- `acmePricing?: ComparePricing` = "ACME_PRICING": Acme's side of the price comparison: { plan, perSeat, minSeats?, platformFee?, addOns? }.
- `teamSizes?: number[]` = "[10, 25, 50]": The labeled marks on the team size slider, which runs from 2 to 100 people.
- `defaultTeamSize?: number` = 25: The team size the price comparison opens on (2 to 100).
- `defaultOnlyDifferences?: boolean` = false: The table opens with matching rows hidden.
- `highlight?: boolean` = true: Tints the Acme column of the table.
- `stickyTableHeader?: boolean` = true: The table's header row sticks under the page header from 768px.
- `showReasons?: boolean` = true: The "Why teams switch" feature grid.
- `showTable?: boolean` = true: The feature by feature table.
- `showPricing?: boolean` = true: The yearly price comparison with the team size slider.
- `showMigration?: boolean` = true: The three import steps.
- `showTestimonials?: boolean` = true: Quotes from teams that switched.
- `showFaq?: boolean` = true: The switching FAQ.
- `showCta?: boolean` = true: The closing call to action.
- `ctaVariant?: "inverted" | "soft" | "split" | "plain"` = "inverted": The look of the closing call to action. Applies to the classic design.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The switcher thumb, slider, switch, step numbers, icon tiles and FAQ accents.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary buttons of the hero, the import steps and the closing band.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the prices (always USD).
- `getImportHref?: (competitor: Competitor) => string`: The importer link; default /sign-up?import=<id>.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `labels?: Partial<ComparePageLabels>` = "DEFAULT_COMPARE_PAGE_LABELS": Every visible string; titles that name the competitor are functions of its name.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<ComparePageSlot, string>>`: Classes for switcher, hero, versus, reasons, table, pricing, migration, testimonials, faq and cta.

Parts:
- `CompareTable` (component): The grouped feature table: a real table with a sticky header row from 768px, a card per row on phones. Takes div props.
- `CompareCellView` (component): One value: a check, a cross, a partial mark or text, with its note as a tooltip or inline text. Takes span props.
- `CompareWordmark` (component): A fictional competitor drawn as its lucide glyph and name (never a real logo). Takes span props.
- `compareYearlyCost` (function): compareYearlyCost(pricing, seats): (perSeat + add-ons) x max(seats, minSeats) x 12 + platformFee x 12, in dollars.
- `COMPETITORS` (constant): Taskly, Boardify and Planhub with their verdicts, reasons, 21 table rows, pricing, steps, quotes and FAQ.
- `ACME_PRICING` (constant): Acme Pro at $12 per user per month.
- `DEFAULT_COMPARE_PAGE_LABELS` (constant): The English strings.
- `Competitor` (type): { id, name, icon, tagline, verdict, facts, reasons, groups, pricing, steps, quotes, faq }.
- `CompareGroup` (type): { id, label, rows: CompareRow[] }.
- `CompareRow` (type): { id, label, acme: CompareCell, competitor: CompareCell }.
- `CompareCell` (type): true | false | "partial" | string, or { value, note }.
- `ComparePricing` (type): { plan, perSeat, minSeats?, platformFee?, addOns? }.
- `COMPARE_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold"].
- `ComparePageProps` (type): Props of ComparePage.
- `ComparePageDesign` (type): "classic" | "bold".

```tsx
// app/(marketing)/compare/[competitor]/page.tsx
"use client"

import Link from "next/link"
import { useParams, useRouter } from "next/navigation"
import { ComparePage } from "@/components/templates/compare-page"
import { COMPETITORS } from "@/components/templates/compare-page-data"

export default function CompareRoute() {
  const { competitor } = useParams<{ competitor: string }>()
  const router = useRouter()
  return (
    <ComparePage
      linkComponent={Link}
      competitors={COMPETITORS}
      competitor={competitor}
      onCompetitorChange={(id) => router.replace(`/compare/${id}`, { scroll: false })}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/compare-page (Markdown: https://wingo-ui.com/templates/compare-page.md)

#### Contact Page (`contact-page`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add contact-page`

A SaaS contact page: a validated form, copyable channels with live office hours, offices on a drawn map, a short FAQ and logos.

Pick a topic (Sales, Support, Partnerships, Press) as cards with arrow keys or a tap, then fill in name, work email, company, company size (a bottom sheet on phones) and a message with a live character counter, and tick the consent box. Send message checks every field: each problem shows under its field and focus jumps to the first one; the email is also checked as soon as you leave it, and errors clear as you fix them. Company size is required for Sales only. While onSubmit runs the button spins; then the form turns into a Message sent panel ("Thanks, Emma. We'll reply within one business day.") with Send another, which keeps your name and email. Next to the form (under it on phones) the sales and support addresses and the phone number have copy buttons, Start a chat opens the chat, and Office hours shows Open now or Closed with the next opening, worked out in the office's time zone after the page loads. The office cards show each city's local time; picking one moves the drawn map and its Get directions link. The FAQ opens one answer at a time. The heading, form and channels rise in once on mount; reduced motion keeps them still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, faq-section, logo-cloud, badge, button, checkbox, copy-button, field, input, radio-group, select, textarea, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "minimal" | "bold"` = "classic": The whole page's look. classic: the layout prop, a soft glow, the form and channels on raised cards; minimal: a transparent header, no glow or cards, the form right on the page beside a plain channel list, no gray band, a feature-light FAQ and a simple footer; bold: a solid header, huge heavy type on a grid, the channels and hours on a big inverted panel beside a floating form, logo tiles, an inverted selected office, FAQ cards and a wordmark footer. headerProps and footerProps still win.
- `layout?: "split" | "centered"` = "split": split: the form left, channels and hours right (stacked on phones); centered: the channels in a row above a centered form. Applies to the classic design.
- `topics?: ContactTopic[]` = "CONTACT_TOPICS": { value, label, description?, icon? } topic cards of the form.
- `companySizes?: ContactSizeOption[]` = "CONTACT_COMPANY_SIZES": { value, label } options of the company size select; an empty array hides it.
- `channels?: ContactChannel[]` = "CONTACT_CHANNELS": { kind: email | phone | chat | link, title, description?, value?, href?, icon? }; email and phone values get a copy button, chat shows Start a chat.
- `hours?: ContactHours` = "CONTACT_HOURS": { timeZone, days, open, close, label }: when someone answers; drives the Open now / Closed status.
- `offices?: ContactOffice[]` = "CONTACT_OFFICES": { city, country, address, timeZone, tag?, phone?, description? }: New York, London and Berlin.
- `faq?: FaqItem[]` = "CONTACT_FAQ": Questions of the short FAQ (FaqSection items).
- `logos?: LogoCloudItem[]` = "CONTACT_LOGOS": Customer wordmarks of the logo row.
- `labels?: Partial<ContactPageLabels>` = "DEFAULT_CONTACT_PAGE_LABELS": Every visible string, including the validation messages.
- `defaultTopic?: string` = "sales": The topic selected on load; "" makes the visitor pick one.
- `requireWorkEmail?: boolean` = false: Rejects free mail domains like gmail.com or outlook.com.
- `onSubmit?: (values: ContactFormValues) => (void | Promise<unknown>)`: Sends { name, email, company, companySize, topic, message, consent }; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `onOpenChat?: () => void`: Runs on Start a chat (open your chat widget); without it the button links to chatHref.
- `chatHref?: string` = "/help": Where Start a chat goes when there is no onOpenChat.
- `privacyHref?: string` = "/legal/privacy": The privacy policy link under the form.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected topic card, the consent box, the selected office and the map pin.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Send message; brand is the marketing orange.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the fields and topic cards (cards stop at lg).
- `showChannels?: boolean` = true: The email, phone and chat channels.
- `showHours?: boolean` = true: Office hours with the live open or closed status.
- `showOffices?: boolean` = true: The offices band.
- `showMap?: boolean` = true: The drawn map next to the offices; off shows the offices as a row of cards.
- `showFaq?: boolean` = true: The short FAQ.
- `showLogos?: boolean` = true: The customer logo row under the form.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The heading, form and channels rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the local times and the opening hours (9 AM or 09:00).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and inner links (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<ContactPageSlot, string>>`: Classes for header, hero, form, success, channels, hours, offices, map, faq, logos and footer.

Parts:
- `getContactOpenState` (function): getContactOpenState(hours, date?): { open, closesAt?, opensIn? } in the hours' time zone; what the Office hours status shows.
- `CONTACT_PAGE_SAMPLE` (constant): All the sample content in one object: topics, companySizes, channels, hours, offices, faq and logos.
- `CONTACT_TOPICS` (constant): Sales, Support, Partnerships and Press with lucide icons.
- `CONTACT_COMPANY_SIZES` (constant): Five company size ranges.
- `CONTACT_CHANNELS` (constant): sales@acme.com, support@acme.com, a New York phone number and live chat.
- `CONTACT_HOURS` (constant): Monday to Friday, 9 AM to 6 PM in New York.
- `CONTACT_OFFICES` (constant): New York (headquarters), London and Berlin.
- `CONTACT_FAQ` (constant): Four questions people ask before writing.
- `CONTACT_LOGOS` (constant): The customer wordmarks (LOGO_CLOUD_SAMPLE).
- `DEFAULT_CONTACT_PAGE_LABELS` (constant): The English strings.
- `CONTACT_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal", "bold"].
- `ContactPageDesign` (type): "classic" | "minimal" | "bold".
- `ContactPageProps` (type): Props of ContactPage.
- `ContactFormValues` (type): { name, email, company, companySize, topic, message, consent }: what onSubmit receives.
- `ContactChannel` (type): One way to reach the team.
- `ContactOffice` (type): One office with its address and time zone.

```tsx
// app/(marketing)/contact/page.tsx
"use client"

import Link from "next/link"
import { ContactPage } from "@/components/templates/contact-page"

export default function ContactRoute() {
  return (
    <ContactPage
      linkComponent={Link}
      onSubmit={async (values) => {
        const response = await fetch("/api/contact", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(values),
        })
        if (!response.ok) throw new Error("Could not send")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/contact-page (Markdown: https://wingo-ui.com/templates/contact-page.md)

#### Customer Story Page (`customer-story-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add customer-story-page`

A SaaS case study page: customer facts, results that count up, a story with pull quotes, a sticky company sidebar and more stories.

The breadcrumb leads back to /customers (a Back link on phones). The hero shows the Acme and Northwind lockup, the headline and summary, Talk to sales, Start for free and a Copy link button that copies the page address and confirms with a check. A wordmark panel sits beside the copy, and the industry, size, region and plan facts run under a hairline. The four key results roll up once when they scroll into view (still under reduced motion and in screenshots). The story reads in a 700px column: numbered Challenge, Solution and Results sections, check-marked points, the drawn sprint planning board with a caption and two pull quotes from Northwind's VP of Engineering. From 1024px the sidebar stays in view (a sidebar taller than the window sticks by its bottom edge, so Talk to sales stays reachable): the company card with facts, the four products used (each a link to /product/<x>), integrations and Talk to sales, then an In this story list that tracks the section you are reading and jumps to it. On phones the sidebar follows the story. Below come quotes from three Northwind engineers, three more story cards (each one link to /customers/<slug>) with All customer stories, and the closing band.

npm: motion, lucide-react
Wingo UI dependencies: customers-page, marketing-section, marketing-header, marketing-footer, hero-section, stats-section, testimonials-section, cta-section, avatar, breadcrumb, button, copy-button, table-of-contents, motion, navigation, tones, ui-config

Props:
- `design?: "classic" | "bold" | "editorial"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, heavy display type, an inverted wordmark panel, fact tiles, an inverted numbers band, big pull quotes on tinted cards, an inverted sidebar card, rounder story cards, a closing image band and a wordmark footer; editorial: a centered solid header, huge start-aligned type with no panel or product shot, a heavy rule over the facts, numbers under hairlines, pull quotes between heavy rules, a ruled sidebar and story rows, a single rotating quote and a plain closing line. statsProps, testimonialsProps, ctaProps, headerProps and footerProps still win.
- `story?: CaseStudy` = "CASE_STUDY_SAMPLE": { slug, company, icon?, wordmarkClassName?, headline, summary, about, customerSince?, heroFacts, facts, stats, sections, products, integrations, href? }. sections are { id, title, lead?, paragraphs, points?, quote?, shot? }; the one with shot: true shows the product shot.
- `moreStories?: CustomerStory[]` = "CUSTOMER_STORIES": The cards under the story (the customers page's stories); the current slug is left out.
- `industries?: CustomerFilterOption[]` = "CUSTOMER_INDUSTRIES": { value, label } names for the industry on each card.
- `testimonials?: Testimonial[]` = "CASE_STUDY_TESTIMONIALS": The quotes band: three Northwind engineers.
- `productShot?: ReactNode` = "<CustomerStoryShot />": Replaces the drawn sprint planning board (a screenshot, a video); null hides it.
- `labels?: Partial<CustomerStoryPageLabels>` = "DEFAULT_CUSTOMER_STORY_PAGE_LABELS": Every visible string: breadcrumb, hero actions, sidebar headings, shot caption, section copy.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `statsProps?: Partial<StatsSectionProps>`: Passed to the key results StatsSection, spread last.
- `testimonialsProps?: Partial<TestimonialsSectionProps>`: Passed to the quotes TestimonialsSection, spread last.
- `ctaProps?: Partial<CtaSectionProps>`: Passed to the closing CtaSection, spread last.
- `customersHref?: string` = "/customers": Where the breadcrumb and All customer stories go; story cards link to <customersHref>/<slug>.
- `statsVariant?: "cards" | "divided" | "plain"` = "cards": The key results: raised cards, numbers under a hairline or plain numbers. Applies to the classic design.
- `testimonialsLayout?: "featured" | "grid" | "quote" | "carousel"` = "featured": The quotes band: one big quote and two small, a grid, one quote at a time, or a swipeable rail. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split"` = "inverted": The closing band: solid, gray, or copy beside the actions. Applies to the classic design.
- `cardVariant?: "raised" | "flat"` = "raised": More stories cards on a raised surface or a flat gray tile. Applies to the classic and bold designs.
- `moreCount?: number` = 3: How many story cards (1 to 6).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Quote rules, point checks, product icons, the panel glow, the shot's bars and the active In this story entry.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Talk to sales in the hero and sidebar, the header's Get started and the closing band.
- `showPanel?: boolean` = true: The wordmark panel beside the hero copy.
- `showStats?: boolean` = true: The key results that count up.
- `showProductShot?: boolean` = true: The drawn product shot in the solution section.
- `showSidebar?: boolean` = true: The company sidebar; without it the story is a single column.
- `stickySidebar?: boolean` = true: The sidebar stays in view while the story scrolls (from 1024px); when it is taller than the window it sticks by its bottom edge.
- `showToc?: boolean` = true: The In this story jump list under the sidebar card (from 1024px).
- `showTestimonials?: boolean` = true: The quotes band.
- `showMoreStories?: boolean` = true: The More stories cards.
- `showCta?: boolean` = true: The closing call to action.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `animateIn?: boolean` = true: The hero rises in once on mount and the results count up; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Number formatting for the results; falls back to UIProvider's locale.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<CustomerStoryPageSlot, string>>`: Classes for header, hero, breadcrumb, title, panel, facts, stats, body, article, section, quote, shot, sidebar, toc, aside, testimonials, more, card, cta and footer.

Parts:
- `CUSTOMER_STORY_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "editorial"].
- `CustomerStoryPageDesign` (type): "classic" | "bold" | "editorial".
- `CustomerStoryShot` (component): The drawn sprint planning board in a browser frame: capacity bars per squad, sprint issues and a Ready for release column that folds away in narrow containers. Takes div props.
- `CASE_STUDY_SAMPLE` (constant): The Northwind case study: planning time down 42%, four results, three sections with two pull quotes from Rachel Kim, four products and five integrations.
- `CASE_STUDY_TESTIMONIALS` (constant): Three quotes from Northwind engineers for the quotes band.
- `DEFAULT_CUSTOMER_STORY_PAGE_LABELS` (constant): The English strings.
- `CaseStudy` (type): The page's content: company and wordmark, headline, summary, facts, results, sections, products and integrations.
- `CaseStudySection` (type): { id, title, lead?, paragraphs, points?, quote?, shot? }.
- `CaseStudyQuote` (type): { text, name, role, avatar? }.
- `CaseStudyFact` (type): { label, value }.
- `CaseStudyProduct` (type): { name, description, icon?, href }.
- `CustomerStoryPageLabels` (type): Every visible string.
- `CustomerStoryPageSlot` (type): The classNames keys.
- `CustomerStoryStatsVariant` (type): "cards" | "divided" | "plain".
- `CustomerStoryTestimonialsLayout` (type): "featured" | "grid" | "quote" | "carousel".
- `CustomerStoryCtaVariant` (type): "inverted" | "soft" | "split".
- `CustomerStoryShotProps` (type): Props of CustomerStoryShot.
- `CustomerStoryPageProps` (type): Props of CustomerStoryPage.

```tsx
// app/(marketing)/customers/[slug]/page.tsx
import Link from "next/link"
import { notFound } from "next/navigation"
import { CustomerStoryPage } from "@/components/templates/customer-story-page"
import { CASE_STUDY_SAMPLE } from "@/components/templates/customer-story-page-data"

const STORIES = { [CASE_STUDY_SAMPLE.slug]: CASE_STUDY_SAMPLE }

export default async function CustomerStoryRoute({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const story = STORIES[slug]
  if (!story) notFound()
  return <CustomerStoryPage story={story} linkComponent={Link} />
}
```

Docs: https://wingo-ui.com/templates/customer-story-page (Markdown: https://wingo-ui.com/templates/customer-story-page.md)

#### Customers Page (`customers-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add customers-page`

A SaaS customer stories page: logos, a featured case study, industry and size filters, story cards with a reader drawer, quotes and stats.

The hero's Read their stories button scrolls to the story library; Talk to sales goes to /contact. Under the logo cloud, the featured case study shows the customer's quote and three result metrics, and the whole card is one link. Two chip rows filter the library by industry (Software, Agencies, Healthcare, Logistics, Nonprofit) and company size; each chip shows how many stories it would leave, the count above the grid updates for screen readers and cards slide into place. No match shows an empty state with Clear filters. Every story card is a single link to /customers/<slug>: a plain click opens the case study in a side drawer (a bottom sheet on phones, Escape or the close button dismisses it) with company facts, metrics, the challenge, solution, a pull quote, results and the products used, plus Read the full story and Talk to sales; Cmd or Ctrl click opens the real page. With storyDetail link, cards navigate. Below come scrolling quotes with a pause button, the stats band that counts up once, and the closing call to action. On phones the chips scroll sideways and the grid is one column.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, logo-cloud, testimonials-section, stats-section, cta-section, avatar, badge, button, drawer, empty-state, motion, navigation, tones, ui-config

Props:
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a gradient mesh hero with heavy type, logo tiles, an inverted featured story with a big quote, rounder cards with large results, a wall of quotes, an inverted numbers band, an image band and a wordmark footer; minimal: a transparent header, a stacked hero with no glow, plain logos under a hairline, the featured story and cards without surfaces under hairlines, outlined filter chips, flat quotes with no gray band, extra air and a simple footer. headerProps and footerProps still win.
- `stories?: CustomerStory[]` = "CUSTOMER_STORIES": { slug, company, icon?, wordmarkClassName?, industry, size, employees, location, customerSince, headline, result, excerpt, metrics, quote, challenge, solution, results, products, featured?, href? }. The one with featured: true leads the page.
- `industries?: CustomerFilterOption[]` = "CUSTOMER_INDUSTRIES": { value, label } chips for the industry row; a story's industry is a value.
- `sizes?: CustomerFilterOption[]` = "CUSTOMER_SIZES": { value, label } chips for the company size row.
- `logos?: LogoCloudItem[]` = "LOGO_CLOUD_SAMPLE": The logo cloud under the hero.
- `testimonials?: Testimonial[]` = "TESTIMONIALS_SAMPLE": The quotes band.
- `stats?: StatsSectionItem[]` = "CUSTOMER_PAGE_STATS": The four numbers in the stats band.
- `labels?: Partial<CustomersPageLabels>` = "DEFAULT_CUSTOMERS_PAGE_LABELS": Every visible string: hero, filters, reader headings, section copy.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `defaultIndustry?: string` = "all": The industry chip the page opens on.
- `defaultSize?: string` = "all": The company size chip the page opens on.
- `storyDetail?: "drawer" | "link"` = "drawer": drawer: a card opens the case study in a side panel (a sheet on phones); link: cards navigate to storyHref.
- `storyHref?: (story: CustomerStory) => string` = "story.href ?? /customers/<slug>": Where each story links.
- `onOpenStory?: (story: CustomerStory, event: MouseEvent) => void`: Runs when a story is opened; preventDefault() keeps the drawer closed and the link from navigating.
- `columns?: 2 | 3 | 4` = 4: Story grid columns from 1024px (two on tablets, one on phones).
- `cardVariant?: "raised" | "flat"` = "raised": Story cards on a raised surface or a flat gray tile. Applies to the classic and bold designs; minimal draws cards under a hairline.
- `testimonialsLayout?: "grid" | "featured" | "marquee" | "carousel"` = "marquee": The layout of the quotes band. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Selected chips, metric numbers, stars and the quote rule.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hero button, the drawer's main action and the closing call to action.
- `showLogos?: boolean` = true: The logo cloud under the hero.
- `showFeatured?: boolean` = true: The featured case study card.
- `showFilters?: boolean` = true: The industry and size chip rows.
- `showTestimonials?: boolean` = true: The quotes band.
- `showStats?: boolean` = true: The stats band.
- `showCta?: boolean` = true: The closing call to action.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<CustomersPageSlot, string>>`: Classes for hero, logos, featured, stories, filters, grid, card, testimonials, stats, cta and drawer.

Parts:
- `CUSTOMERS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `CustomersPageDesign` (type): "classic" | "bold" | "minimal".
- `CustomerStoryCard` (component): One story as a single stretched link: wordmark, industry, the headline result, title and excerpt. Takes article props.
- `CustomerStoryReader` (component): The body of a case study: facts, three metrics, challenge, solution, pull quote, results and products used. The page renders it in its drawer. Takes div props.
- `CustomerWordmark` (component): A fictional customer's wordmark: the lucide glyph and the name in its own type. Takes span props.
- `CUSTOMER_STORIES` (constant): Eight Acme customer stories (Northwind, Umbrella Health, Wayne Studio, Stark Logistics, Hooli, Initech, Globex, Vandelay); Northwind is featured.
- `CUSTOMER_INDUSTRIES` (constant): Software, Agencies, Healthcare, Logistics and Nonprofit.
- `CUSTOMER_SIZES` (constant): Under 50 people, 50 to 500 and 500+.
- `CUSTOMER_PAGE_STATS` (constant): Teams, faster delivery, hours saved and renewal rate for the stats band.
- `DEFAULT_CUSTOMERS_PAGE_LABELS` (constant): The English strings.
- `CustomerStory` (type): A case study: company, wordmark, filters, headline result, metrics, quote, challenge, solution, results and products.
- `CustomerMetric` (type): { value, label }, like { value: "−38%", label: "cycle time" }.
- `CustomerQuote` (type): { text, name, role, avatar? }.
- `CustomerFilterOption` (type): { value, label }.
- `CustomersPageProps` (type): Props of CustomersPage.

```tsx
// app/(marketing)/customers/page.tsx
"use client"

import Link from "next/link"
import { useRouter } from "next/navigation"
import { CustomersPage } from "@/components/templates/customers-page"
import { CUSTOMER_STORIES } from "@/components/templates/customers-page-data"

export default function CustomersRoute() {
  const router = useRouter()
  return (
    <CustomersPage
      linkComponent={Link}
      stories={CUSTOMER_STORIES}
      onOpenStory={(story, event) => {
        // stories with their own long page skip the drawer
        if (story.featured) {
          event.preventDefault()
          router.push(`/customers/${story.slug}`)
        }
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/customers-page (Markdown: https://wingo-ui.com/templates/customers-page.md)

#### Demo Booking Page (`demo-booking-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add demo-booking-page`

A book-a-demo page: the agenda, host and customer logos beside a three step booking that ends with add-to-calendar links.

The left column says what the 30 minute call covers (an agenda with minutes per part), who hosts it (Ava Thompson), a customer quote and the wordmarks of teams that booked. The booking card on the right walks through three steps shown by a stepper (a compact Step 1 of 3 header on phones): pick a day in the calendar, which opens on the first day with an open time and says how many times it has, with a Book <first time> shortcut straight to the details (weekends, past days, days past the booking window and days with no open time in your zone are disabled), then a time from Morning, Afternoon and Evening groups. Both steps list times in your time zone, detected from the browser and changeable in a searchable select (a bottom sheet on phones); the list is worked out from the host's New York hours, so a Berlin visitor sees afternoon and evening times. Then name, work email (free mail domains are refused, checked when you leave the field), company size and optional notes with a counter. Continue checks each step, errors show in place and focus moves to the first problem or to the new step's heading; Back and the completed steps in the stepper go back without losing anything. On phones the Back / Continue bar stays pinned to the bottom of the screen. Confirm booking spins while onSubmit runs, then the card shows You're booked with the day, the time range and zone, the length, the host and a copyable meeting link, buttons that add the call to Google Calendar, Outlook or download an .ics file, and Reschedule, which goes back to the times with the details kept and confirms as New time confirmed. A FAQ follows. The heading, card and details rise in once on mount; reduced motion keeps them still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, faq-section, logo-cloud, avatar, button, calendar, copy-button, field, input, select, steps, textarea, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "minimal"` = "classic": The whole page's look. classic: a soft glow, the booking card and host on raised cards, the agenda on a gray tile and the FAQ on a gray band; minimal: a transparent header, no glow, an outlined flat booking card, the agenda and host right on the page, outlined time slots, a borderless FAQ without the band and a simple footer. headerProps and footerProps still win.
- `agenda?: DemoBookingAgendaItem[]` = "DEMO_BOOKING_AGENDA": { title, description?, minutes?, icon? }: what the call covers, in order.
- `facts?: DemoBookingFact[]` = "DEMO_BOOKING_FACTS": { label, icon? } short facts after the length and the video call (from meetingUrl): guests, live questions.
- `host?: DemoBookingHost` = "DEMO_BOOKING_HOST": { name, role, bio?, avatarSrc? }: who runs the call; initials without a portrait.
- `hours?: DemoBookingHours` = "DEMO_BOOKING_HOURS": { timeZone, days, start, end }: when the host takes calls, in the host's zone (weekdays 9 to 5 in New York). Some slots are already taken, picked from the time itself so they stay stable.
- `timeZones?: DemoBookingTimeZone[]` = "DEMO_BOOKING_TIME_ZONES": { value, label, keywords? } zones of the time zone select; the visitor's own zone is added when it is missing.
- `companySizes?: DemoBookingSizeOption[]` = "DEMO_BOOKING_COMPANY_SIZES": { value, label } options of the required company size select; an empty array hides it.
- `quote?: DemoBookingQuote | null` = "DEMO_BOOKING_QUOTE": { quote, name, role }: one customer quote under the host.
- `faq?: FaqItem[]` = "DEMO_BOOKING_FAQ": Questions of the FAQ (FaqSection items).
- `logos?: LogoCloudItem[]` = "DEMO_BOOKING_LOGOS": Customer wordmarks in the left column.
- `labels?: Partial<DemoBookingPageLabels>` = "DEFAULT_DEMO_BOOKING_PAGE_LABELS": Every visible string, including the validation messages and the calendar event text.
- `duration?: number` = 30: The call length in minutes: the facts, the description, the end time and the calendar event.
- `interval?: number` = 30: Minutes between start times.
- `daysAhead?: number` = 42: How many days ahead can be booked; said in the date step.
- `leadHours?: number` = 4: Minimum notice: no slot starts sooner than this from now; said in the date step.
- `defaultTimeZone?: string` = "": The visitor's time zone on load; "" uses the browser's (the host's zone until the page has loaded).
- `hourCycle?: "auto" | "12h" | "24h"` = "auto": 2:30 PM or 14:30; auto follows the locale.
- `requireWorkEmail?: boolean` = true: Rejects free mail domains like gmail.com or outlook.com; the field and the note under the card say work email.
- `meetingUrl?: string` = "https://meet.acme.com/ava-thompson": The video call link: its host in the facts, the link on the confirmation and in the calendar event.
- `privacyHref?: string` = "/legal/privacy": The privacy policy link under the booking card.
- `docsHref?: string` = "/docs": The docs link in the FAQ description and on the confirmation.
- `onSubmit?: (values: DemoBookingValues) => (void | Promise<unknown>)`: Books { start, end, timeZone, name, email, companySize, notes, rescheduled }; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `onStepChange?: (step: "date" | "time" | "details") => void`: Runs when the booking moves to another step (analytics).
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected day and time, the stepper and the glow behind the heading.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Continue and Confirm booking; brand is the marketing orange.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the fields and the time slots.
- `stepsVariant?: "circles" | "bars"` = "circles": The stepper above the steps: numbered circles or bars.
- `showAgenda?: boolean` = true: What you'll see, with minutes per part.
- `showHost?: boolean` = true: The host card.
- `showQuote?: boolean` = true: The customer quote.
- `showLogos?: boolean` = true: The customer wordmarks.
- `showFaq?: boolean` = true: The FAQ under the booking.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The heading, booking card and details rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the calendar, the days and the times (Thursday, October 15 or Donnerstag, 15. Oktober).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and inner links (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<DemoBookingPageSlot, string>>`: Classes for header, hero, intro, info, facts, agenda, host, quote, logos, booking, steps, calendar, slots, form, success, faq and footer.

Parts:
- `getDemoBookingSlots` (function): getDemoBookingSlots(day, { hours, timeZone, duration, interval, notBefore?, hideTaken? }): the open start times on a "YYYY-MM-DD" day of the visitor's zone, from the host's hours.
- `DEMO_BOOKING_PAGE_SAMPLE` (constant): All the sample content: agenda, facts, host, hours, timeZones, companySizes, quote, faq and logos.
- `DEMO_BOOKING_AGENDA` (constant): Planning, docs, automations, then insights and questions, 30 minutes in all.
- `DEMO_BOOKING_FACTS` (constant): Up to 5 teammates, questions answered live.
- `DEMO_BOOKING_HOST` (constant): Ava Thompson from customer success.
- `DEMO_BOOKING_HOURS` (constant): Monday to Friday, 9 AM to 5 PM in New York.
- `DEMO_BOOKING_TIME_ZONES` (constant): 13 zones from Los Angeles to Sydney with search keywords.
- `DEMO_BOOKING_COMPANY_SIZES` (constant): Five company size ranges.
- `DEMO_BOOKING_QUOTE` (constant): A quote from Northwind's head of operations.
- `DEMO_BOOKING_FAQ` (constant): Four questions people ask before they book.
- `DEMO_BOOKING_LOGOS` (constant): Six customer wordmarks from LOGO_CLOUD_SAMPLE.
- `DEFAULT_DEMO_BOOKING_PAGE_LABELS` (constant): The English strings.
- `DEMO_BOOKING_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal"].
- `DemoBookingPageDesign` (type): "classic" | "minimal".
- `DemoBookingPageProps` (type): Props of DemoBookingPage.
- `DemoBookingValues` (type): { start, end, timeZone, name, email, companySize, notes, rescheduled }: what onSubmit receives.
- `DemoBookingHours` (type): The host's weekly hours in their time zone.
- `DemoBookingAgendaItem` (type): One part of the call.
- `DemoBookingStep` (type): "date" | "time" | "details": what onStepChange receives.
- `DemoBookingHourCycle` (type): "auto" | "12h" | "24h".
- `DemoBookingStepsVariant` (type): "circles" | "bars".
- `DemoBookingPageLabels` (type): Every visible string; some are functions of the length, the step or the host.
- `DemoBookingPageSlot` (type): The keys of classNames.
- `DemoBookingFact` (type): { label, icon? }: one fact next to the length.
- `DemoBookingHost` (type): { name, role, bio?, avatarSrc? }.
- `DemoBookingTimeZone` (type): { value, label, keywords? }: one entry of the time zone select.
- `DemoBookingSizeOption` (type): { value, label }: one company size.
- `DemoBookingQuote` (type): { quote, name, role }.

```tsx
// app/(marketing)/demo/page.tsx
"use client"

import Link from "next/link"
import { DemoBookingPage } from "@/components/templates/demo-booking-page"

export default function DemoRoute() {
  return (
    <DemoBookingPage
      linkComponent={Link}
      onSubmit={async (values) => {
        const response = await fetch("/api/demo-bookings", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            ...values,
            start: values.start.toISOString(),
            end: values.end.toISOString(),
          }),
        })
        if (!response.ok) throw new Error("Could not book")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/demo-booking-page (Markdown: https://wingo-ui.com/templates/demo-booking-page.md)

#### Docs Home Page (`docs-home-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add docs-home-page`

A developer docs portal home: a big search palette, quick-start cards, popular guides, API code samples, SDK tiles, the changelog and help.

Press the big search field in the hero, the Search field in the header, or Cmd+K / Ctrl+K anywhere: a search palette opens with results grouped under Guides, API reference, SDKs and Changelog. Type to filter (matches are bold), move with the arrow keys, Enter opens the page and Escape closes; the Popular chips under the field open it with that word already typed. On phones the palette is a full-height sheet. The four quick-start cards, every guide, SDK tile, changelog entry and help option are one link each with the focus ring on the card. In the API section the curl, JavaScript and Python tabs switch the code sample (arrow keys move between tabs) and its copy button copies the snippet; each SDK tile copies its install command. The status option pulses green. The header keeps Guides as a dropdown and folds into a menu sheet below 1024px; cards stack to one column on phones without sideways scrolling.

npm: lucide-react
Wingo UI dependencies: feature-grid, hero-section, marketing-footer, marketing-header, marketing-section, button, code-block, command-menu, copy-button, nav-menu, tabs, use-controllable-state, navigation, tones, ui-config

Props:
- `navItems?: NavMenuItem[]` = "DOCS_NAV": The header links: Guides (a dropdown), API, SDKs, Changelog and Support.
- `quickStart?: DocsQuickStart[]` = "DOCS_QUICK_START": The starting-point cards: { icon, title, description, href }.
- `guides?: DocsGuide[]` = "DOCS_GUIDES": Popular guides: { title, description, category, minutes, href }.
- `codeSamples?: DocsCodeSample[]` = "DOCS_CODE_SAMPLES": The API tabs: { value, label, language, filename, code }.
- `apiFacts?: { label: string; value: string }[]` = "DOCS_API_FACTS": The four tiles beside the code: base URL, auth, rate limit, format.
- `sdks?: DocsSdk[]` = "DOCS_SDKS": SDK tiles: { letters, name, install, version, href, color }.
- `changelog?: DocsChangelogEntry[]` = "DOCS_CHANGELOG": The latest entries: { version, date, kind, title, description, href }.
- `help?: DocsHelpOption[]` = "DOCS_HELP": Community, support and status: { icon, title, description, meta, action, href, live? }.
- `searchGroups?: DocsSearchGroup[]` = "DOCS_SEARCH": What the search palette searches: { label, items: { title, description?, href, keywords? }[] }.
- `popularSearches?: string[]` = "DOCS_POPULAR_SEARCHES": Chips under the hero search that open it with that query.
- `labels?: Partial<DocsHomePageLabels>` = "DEFAULT_DOCS_HOME_PAGE_LABELS": Every visible string.
- `searchShortcut?: string` = "mod+k": Opens the search from anywhere and shows on the fields; empty binds nothing.
- `defaultSearchOpen?: boolean` = false: The search palette starts open.
- `searchOpen?: boolean`: Controlled open state of the search palette.
- `onSearchOpenChange?: (open: boolean) => void`: Called when the palette opens or closes.
- `onSearchSelect?: (item: { title, href, group }) => void`: Called when a result is picked; the page also navigates to its href.
- `defaultLanguage?: string` = "curl": The code tab the API section opens on (a codeSamples value).
- `showQuickStart?: boolean` = true: The quick-start cards.
- `showGuides?: boolean` = true: The popular guides.
- `showApi?: boolean` = true: The API section with code tabs.
- `showSdks?: boolean` = true: The SDK tiles.
- `showChangelog?: boolean` = true: The latest changelog entries.
- `showHelp?: boolean` = true: Community, support and status.
- `header?: boolean` = true: The sticky docs header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (replaces the docs actions when you pass actions).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `design?: "classic" | "minimal"` = "classic": The whole page's look. classic follows the layout props; minimal: a transparent header, the copy and search beside a drawn terminal with no background, the starting points as a plain list, guides, SDKs and help as flat rows under hairlines, outlined API facts, no gray bands, tighter sections and a simple footer. headerProps and footerProps still win.
- `heroBackground?: "grid" | "glow" | "none"` = "grid": Faint lines, a soft light in the tone, or nothing behind the hero. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Icon tiles, the code tabs and the announcement badge.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The solid buttons (Get an API key, API reference).
- `codeAccent?: string` = "#F75001": The code block theme color.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the changelog dates.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link and search result (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<DocsHomePageSlot, string>>`: Classes for hero, search, quickStart, guides, api, sdks, changelog and help.

Parts:
- `DocsGuideCard` (component): One guide as a single stretched link: category, reading time, title and summary. Takes article props.
- `DocsSdkTile` (component): An SDK as a letter tile, name, version and a copyable install command; the tile links to the SDK docs. Takes article props.
- `DOCS_NAV` (constant): The docs header navigation.
- `DOCS_POPULAR_SEARCHES` (constant): Webhooks, Rate limits, Pagination and OAuth.
- `DOCS_QUICK_START` (constant): Get started, Guides, API reference and SDKs.
- `DOCS_GUIDES` (constant): Six popular Acme API guides.
- `DOCS_CODE_SAMPLES` (constant): Create a task with curl, JavaScript and Python.
- `DOCS_API_FACTS` (constant): Base URL, auth, rate limit and format.
- `DOCS_SDKS` (constant): JavaScript, Python, Go, Ruby, PHP and Swift.
- `DOCS_CHANGELOG` (constant): The three latest API changes.
- `DOCS_HELP` (constant): Community, Support and Status.
- `DOCS_SEARCH` (constant): The search index, grouped by section.
- `DEFAULT_DOCS_HOME_PAGE_LABELS` (constant): The English strings.
- `DocsSearchItemPicked` (type): { title, href, group }: what onSearchSelect receives.
- `DocsQuickStart` (type): { icon, title, description, href }.
- `DocsGuide` (type): { title, description, category, minutes, href }.
- `DocsCodeSample` (type): { value, label, language, filename, code }.
- `DocsSdk` (type): { letters, name, install, version, href, color }.
- `DocsChangelogEntry` (type): { version, date, kind, title, description, href }.
- `DocsHelpOption` (type): { icon, title, description, meta, action, href, live? }.
- `DocsSearchGroup` (type): { label, items: DocsSearchItem[] }.
- `DocsSearchItem` (type): { title, description?, href, keywords? }.
- `DOCS_HOME_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal"].
- `DocsHomePageProps` (type): Props of DocsHomePage.
- `DocsHomePageDesign` (type): "classic" | "minimal".

```tsx
// app/(docs)/docs/page.tsx
"use client"

import Link from "next/link"
import { DocsHomePage } from "@/components/templates/docs-home-page"
import { DOCS_SEARCH } from "@/components/templates/docs-home-page-data"

export default function DocsRoute() {
  return (
    <DocsHomePage
      linkComponent={Link}
      searchGroups={DOCS_SEARCH}
      onSearchSelect={(item) => console.log("search pick", item.href)}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/docs-home-page (Markdown: https://wingo-ui.com/templates/docs-home-page.md)

#### Enterprise Page (`enterprise-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add enterprise-page`

An enterprise plan page: a Talk to sales form, security seals, ROI numbers, a Business vs Enterprise comparison, a CIO quote and an FAQ.

Fill in the Talk to sales form beside the hero: full name, work email, company, team size and region (bottom sheets on phones) and an optional message with a live character counter. Picking a team size or region shows a hint under it (the data residency for that region). Talk to sales checks every field: each problem shows under its field and focus jumps to the first one; the email is checked as soon as you leave it and free mail addresses are refused, and errors clear as you fix them. While onSubmit runs the button spins; then the form turns into a Request received panel ("Thanks, Emma. A solutions engineer covering Europe will email you within one business day.") with a summary, the three next steps and Send another request. The security seals (SOC 2, ISO 27001, GDPR, HIPAA, CCPA, CSA STAR) each link to the Trust Center. The ROI numbers count up once when they scroll in. The Business vs Enterprise comparison has an Only show differences switch that hides the shared rows; on phones each row stacks the feature over the two plan values. Read the full story opens the customer story; the FAQ opens one answer at a time, and its contact card and the closing band's Talk to sales jump back to the form. The hero rises in once on mount; reduced motion keeps everything still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, feature-grid, logo-cloud, stats-section, faq-section, cta-section, avatar, button, field, input, select, switch, textarea, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic: the layout props, a soft glow, the form on a raised card, gray bands; bold: a pill header, huge heavy type on a grid, a floating form, illustrated features, an inverted ROI band, the Enterprise column head and the quote on inverted panels, FAQ cards, a scene band and a wordmark footer; minimal: a transparent header, no glow, the form right on the page, outlined seals, a list of features, plain numbers, no gray bands, a ghost FAQ and a simple footer. The *Props overrides still win.
- `featuresLayout?: "grid" | "list" | "numbered"` = "grid": The enterprise features: cards in three columns, compact rows, or numbered rows under hairlines. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split"` = "inverted": The closing band: a solid band, a gray band, or copy beside the actions. Applies to the classic design.
- `alternate?: boolean` = true: Gray bands on every other section. Applies to the classic and bold designs.
- `highlights?: string[]` = "ENTERPRISE_HIGHLIGHTS": The checked promises under the hero copy; an empty array hides them.
- `nextSteps?: string[]` = "ENTERPRISE_NEXT_STEPS": The numbered steps of the success panel.
- `teamSizes?: EnterpriseOption[]` = "ENTERPRISE_TEAM_SIZES": { value, label, hint? } options of the team size select; an empty array hides it.
- `regions?: EnterpriseOption[]` = "ENTERPRISE_REGIONS": { value, label, hint? } options of the region select; the hint is the data residency shown once picked.
- `logos?: LogoCloudItem[]` = "ENTERPRISE_LOGOS": Customer wordmarks under the hero.
- `features?: FeatureGridItem[]` = "ENTERPRISE_FEATURES": SSO and SCIM, audit logs, data residency, the SLA, a success manager and custom contracts.
- `certifications?: EnterpriseCertification[]` = "ENTERPRISE_CERTIFICATIONS": { id, code, detail?, name, description, href } drawn seals that link to the Trust Center.
- `stats?: StatsSectionItem[]` = "ENTERPRISE_STATS": The ROI numbers.
- `plans?: { business: EnterprisePlan; enterprise: EnterprisePlan }` = "ENTERPRISE_PLANS": { name, price, priceNote?, cta, href } heads of the comparison columns.
- `comparison?: EnterpriseCompareGroup[]` = "ENTERPRISE_COMPARISON": { title, rows: { feature, note?, business, enterprise }[] }; true and false draw a check or a dash.
- `quote?: EnterpriseQuote` = "ENTERPRISE_QUOTE": { quote, name, role, company, avatar?, href?, metrics? }: the CIO quote and its results.
- `faq?: FaqItem[]` = "ENTERPRISE_FAQ": Questions of the FAQ (FaqSection items).
- `labels?: Partial<EnterprisePageLabels>` = "DEFAULT_ENTERPRISE_PAGE_LABELS": Every visible string, including the validation messages.
- `defaultRegion?: string` = "": The region selected on load; "" makes the visitor pick one.
- `defaultDifferencesOnly?: boolean` = false: The comparison starts with the rows both plans share hidden.
- `requireWorkEmail?: boolean` = true: Rejects free mail domains like gmail.com or outlook.com, with a hint under the email field.
- `onSubmit?: (values: EnterpriseFormValues) => (void | Promise<unknown>)`: Sends { name, email, company, teamSize, region, message }; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `securityHref?: string` = "/security": The Trust Center: the hero link and Visit the Trust Center.
- `demoHref?: string` = "/demo": Book a demo instead, under the hero copy.
- `privacyHref?: string` = "/legal/privacy": The privacy policy link under the form.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hero glow, the checks, the feature icons, the seals, the numbers and the Enterprise column.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Talk to sales (the form, the Enterprise column and the closing band) and Get started in the header.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": Corners of the form fields.
- `showLogos?: boolean` = true: The customer logos under the hero.
- `showFeatures?: boolean` = true: The enterprise features.
- `showSecurity?: boolean` = true: The row of security seals.
- `showStats?: boolean` = true: The ROI numbers.
- `showComparison?: boolean` = true: The Business vs Enterprise comparison.
- `showQuote?: boolean` = true: The CIO quote.
- `showFaq?: boolean` = true: The FAQ.
- `showCta?: boolean` = true: The closing band.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `logosProps?: Partial<LogoCloudProps>`: Passed to LogoCloud, spread last.
- `featuresProps?: Partial<FeatureGridProps>`: Passed to FeatureGrid, spread last.
- `statsProps?: Partial<StatsSectionProps>`: Passed to StatsSection, spread last.
- `faqProps?: Partial<FaqSectionProps>`: Passed to FaqSection, spread last.
- `ctaProps?: Partial<CtaSectionProps>`: Passed to CtaSection, spread last.
- `animateIn?: boolean` = true: The hero rises in once on mount and the ROI numbers count up; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the ROI numbers (6.5 or 6,5).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and inner links (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<EnterprisePageSlot, string>>`: Classes for header, hero, form, success, logos, features, security, stats, comparison, quote, faq, cta and footer.

Parts:
- `ENTERPRISE_PAGE_SAMPLE` (constant): All the sample content in one object: highlights, nextSteps, teamSizes, regions, features, certifications, stats, plans, comparison, quote, faq and logos.
- `ENTERPRISE_HIGHLIGHTS` (constant): Three promises under the hero copy.
- `ENTERPRISE_NEXT_STEPS` (constant): Intro call, tailored demo, 30-day pilot.
- `ENTERPRISE_TEAM_SIZES` (constant): Five team size ranges, from 25 to 5,000+ people.
- `ENTERPRISE_REGIONS` (constant): Six regions, each with its data residency hint.
- `ENTERPRISE_FEATURES` (constant): Six enterprise features with lucide icons.
- `ENTERPRISE_CERTIFICATIONS` (constant): SOC 2, ISO 27001, GDPR, HIPAA, CCPA and CSA STAR.
- `ENTERPRISE_STATS` (constant): 312% ROI, 5 months payback, 6.5 hours saved, 38% fewer tools.
- `ENTERPRISE_PLANS` (constant): The Business ($24) and Enterprise (custom) column heads.
- `ENTERPRISE_COMPARISON` (constant): Workspace, security and admin, support and terms.
- `ENTERPRISE_QUOTE` (constant): Daniel Ortiz, CIO at Umbrella Health, with three results.
- `ENTERPRISE_FAQ` (constant): Six questions from IT, security and procurement.
- `ENTERPRISE_LOGOS` (constant): The customer wordmarks (LOGO_CLOUD_SAMPLE).
- `DEFAULT_ENTERPRISE_PAGE_LABELS` (constant): The English strings.
- `ENTERPRISE_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `EnterprisePageDesign` (type): "classic" | "bold" | "minimal".
- `EnterprisePageProps` (type): Props of EnterprisePage.
- `EnterpriseFormValues` (type): { name, email, company, teamSize, region, message }: what onSubmit receives.
- `EnterprisePageLabels` (type): Every visible string; successDescription is a function of the first name and the region.
- `EnterprisePageSlot` (type): The classNames keys, from header to footer.
- `EnterprisePageFeaturesLayout` (type): "grid" | "list" | "numbered": the featuresLayout values.
- `EnterpriseOption` (type): { value, label, hint? }: a team size or region option.
- `EnterpriseCompareGroup` (type): One group of comparison rows.
- `EnterpriseCompareRow` (type): { feature, note?, business, enterprise }: one comparison row.
- `EnterpriseCompareValue` (type): boolean | string: true and false draw a check or a dash, text shows as is.
- `EnterprisePlan` (type): { name, price, priceNote?, cta, href }: a comparison column head.
- `EnterpriseQuote` (type): { quote, name, role, company, avatar?, href?, metrics? }: the customer quote.
- `EnterpriseCertification` (type): One security seal.

```tsx
// app/(marketing)/enterprise/page.tsx
"use client"

import Link from "next/link"
import { EnterprisePage } from "@/components/templates/enterprise-page"

export default function EnterpriseRoute() {
  return (
    <EnterprisePage
      linkComponent={Link}
      onSubmit={async (values) => {
        const response = await fetch("/api/sales-leads", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(values),
        })
        if (!response.ok) throw new Error("Could not send")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/enterprise-page (Markdown: https://wingo-ui.com/templates/enterprise-page.md)

#### Events Page (`events-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add events-page`

A SaaS events page: a featured webinar with countdown and sign-up, filterable upcoming events, a replay, past recordings and speakers.

See upcoming events glides down to the list (Watch recordings to the recordings). The featured webinar counts down to its start, live, and its register form checks the name and email; Register for free spins while onRegister runs, then the card turns into a confirmation with Add to calendar (downloads an .ics file) and Register someone else. Filter the upcoming list with the type chips (All, Webinars, Meetups, Conferences, each with its count; the row scrolls sideways on phones); the result count is announced and an empty type shows Show all events. Times read in the event's time zone; Use my time zone switches every date block, row and the featured card to the visitor's zone, and the same link switches back. Each row is one link to /events/<slug>: a plain click opens the event in a side panel (a draggable bottom sheet on phones) with when and where, the agenda, the hosts and a register form whose button sits in the panel footer; Cmd or Ctrl click opens the link instead. The replay plays a chaptered walkthrough in a dialog. Every recording card is one link with a drawn title card, its length and views. The speakers row shows initials, and the closing card subscribes an email to monthly invites. The hero and featured card rise in once on mount; reduced motion keeps them still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, team-section, video-section, cta-section, avatar, badge, button, countdown, drawer, empty-state, input, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "bold"` = "classic": The whole page's look. classic: a centered hero, a raised featured card with soft countdown tiles, date-block rows, a split replay, a recordings grid, compact speaker rows and a form closing card; bold: a pill header, a huge start-aligned hero on a soft glow, the featured session on an inverted panel with large countdown tiles, ringed rows with filled date blocks, a chaptered replay, a bento of recordings, speaker cards, an inverted closing band and a wordmark footer. replayProps, speakersProps, ctaProps, headerProps and footerProps still win.
- `featured?: EventsPageEvent | null` = "EVENTS_FEATURED": The highlighted session with the countdown, agenda, hosts and register form; null hides the card.
- `events?: EventsPageEvent[]` = "EVENTS_UPCOMING": { slug, title, type, start, end?, location, venue?, description, speakers, agenda?, seats?, seatsLeft?, price? }; listed by start date. 7 sample events.
- `recordings?: EventsPageRecording[]` = "EVENTS_RECORDINGS": { slug, title, type, date, duration (seconds), speakers, summary, views? } cards with a drawn title card.
- `speakers?: EventsPageSpeaker[]` = "EVENTS_SPEAKERS": { name, role, avatar? } of the speakers row; also gives the hosts their roles in the detail panel.
- `replayChapters?: VideoSectionChapter[]` = "EVENTS_REPLAY_CHAPTERS": The replay's chapters over the drawn walkthrough.
- `labels?: Partial<EventsPageLabels>` = "DEFAULT_EVENTS_PAGE_LABELS": Every visible string, including the form's messages and the time zone note.
- `defaultType?: "all" | "webinar" | "meetup" | "conference"` = "all": The type chip selected on load.
- `timeZone?: string` = "America/New_York": The IANA time zone the dates and times are shown in; visitors can switch to their own.
- `now?: Date | number`: Pins the countdown's clock (thumbnails, tests); without it the countdown ticks live.
- `eventDetail?: "drawer" | "link"` = "drawer": drawer: a click opens the event and a register form in a side panel (a sheet on phones); link: rows navigate to eventHref.
- `eventHref?: (event: EventsPageEvent) => string` = "(event) => `/events/${event.slug}`": Where each upcoming row links to.
- `recordingHref?: (recording: EventsPageRecording) => string` = "(recording) => `/events/${recording.slug}`": Where each recording card links to.
- `onOpenEvent?: (event: EventsPageEvent, mouseEvent: MouseEvent<HTMLAnchorElement>) => void`: Runs when a row is clicked; mouseEvent.preventDefault() keeps the panel closed and stops the navigation.
- `onRegister?: (registration: EventsRegistration) => (void | Promise<unknown>)`: Sends { event, name, email } from the featured card and the panel; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The closing card's invite signup; a rejection shows an error. Without it: 900 ms, then success.
- `replayLayout?: "split" | "centered" | "chapters"` = "split": The classic design's replay: heading beside the player, player under the heading, or a chapter panel next to it.
- `ctaVariant?: "form" | "inverted" | "soft"` = "form": The classic design's closing invite signup: a raised card with the form beside the copy, a solid band or a gray band.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected type chip, date blocks, type badges, countdown tiles and the replay's play button.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": See upcoming events, Get started, every Register button and Get invites; brand is the marketing orange.
- `showCountdown?: boolean` = true: The live countdown on the featured card.
- `showReplay?: boolean` = true: The replay section with the chaptered walkthrough.
- `showRecordings?: boolean` = true: The past recordings grid and the hero's Watch recordings button.
- `showSpeakers?: boolean` = true: The speakers row.
- `showCta?: boolean` = true: The closing invite signup.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `replayProps?: Partial<VideoSectionProps>`: Passed to the replay's VideoSection, last.
- `speakersProps?: Partial<TeamSectionProps>`: Passed to the speakers' TeamSection, last.
- `ctaProps?: Partial<CtaSectionProps>`: Passed to the closing CtaSection, last.
- `animateIn?: boolean` = true: The hero and featured card rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for dates, times, the countdown and view counts.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer, rows and recording cards (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<EventsPageSlot, string>>`: Classes for header, hero, featured, countdown, register, upcoming, filters, event, replay, recordings, recording, speakers, cta, drawer and footer.

Parts:
- `EVENTS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold"].
- `EventsPageDesign` (type): "classic" | "bold".
- `formatEventWhen` (function): formatEventWhen(event, timeZone, locale?, long?): "Wed, Oct 21 · 1:00 PM to 2:00 PM ET" (an en dash in the output), or a day range for multi-day events.
- `formatDuration` (function): formatDuration(seconds): "42:18" or "1:12:30".
- `zoneAbbreviation` (function): zoneAbbreviation(time, timeZone, locale?): "ET", "PT" or "GMT+1".
- `zoneName` (function): zoneName(time, timeZone, locale?): "Eastern Time".
- `eventToIcs` (function): eventToIcs(event): the event as an .ics calendar file's text.
- `EVENTS_PAGE_SAMPLE` (constant): All the sample content in one object: featured, events, recordings, speakers and replayChapters.
- `EVENTS_FEATURED` (constant): The Acme 3.0 launch webinar on October 21, 2026.
- `EVENTS_UPCOMING` (constant): Seven upcoming webinars, meetups and the Ship Small conference.
- `EVENTS_RECORDINGS` (constant): Six past recordings.
- `EVENTS_SPEAKERS` (constant): Eight speakers from the Acme team.
- `EVENTS_REPLAY_CHAPTERS` (constant): The four chapters of the 2.9 launch recap.
- `DEFAULT_EVENTS_PAGE_LABELS` (constant): The English strings.
- `EventsPageProps` (type): Props of EventsPage.
- `EventsPageEvent` (type): One upcoming or featured event.
- `EventsPageRecording` (type): One past recording.
- `EventsRegistration` (type): { event, name, email }: what onRegister receives.
- `EventsPageEventType` (type): "webinar" | "meetup" | "conference".
- `EventsPageSpeaker` (type): One speaker: a TeamMember { name, role, avatar? }.
- `EventsPageTypeFilter` (type): "all" or an event type: the selected chip.
- `EventsPageEventDetail` (type): "drawer" | "link": what a row click does.
- `EventsPageLabels` (type): The shape of labels: strings plus a few formatters (seatsLeft, hosts, days...).
- `EventsPageSlot` (type): The classNames keys.

```tsx
// app/(marketing)/events/page.tsx
"use client"

import Link from "next/link"
import { EventsPage } from "@/components/templates/events-page"

export default function EventsRoute() {
  return (
    <EventsPage
      linkComponent={Link}
      onRegister={async ({ event, name, email }) => {
        const response = await fetch("/api/registrations", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ event: event.slug, name, email }),
        })
        if (!response.ok) throw new Error("Could not register")
      }}
      onSubscribe={(email) => fetch("/api/newsletter", { method: "POST", body: email })}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/events-page (Markdown: https://wingo-ui.com/templates/events-page.md)

#### FAQ Page (`faq-page`)

block · free · v1.0.0 · install: `npx wingo-ui@latest add faq-page`

A help center FAQ page: a big search, topic cards with counts, 21 answers in five categories, help options and a call to action.

Type in the big search (press / to focus it from anywhere): the answers filter as you type across every topic, the field shows how many match, matching words are marked in the answers, the best match opens, and the topic cards step aside so the results sit right under the field. Enter scrolls to the results; Escape or Clear search brings everything back. Popular searches under the field fill it in one tap (tap again to clear). Each topic card counts its answers; picking one selects that topic in the FAQ and glides down to it (pick it again for all topics). The topic row above the questions switches categories too and scrolls sideways on phones; questions open one at a time. When nothing matches, an empty state offers Clear search and Contact support. With syncUrl the search and topic live in the address bar (?q=invoices#billing), so links open the page already filtered. Below, three help cards (docs, community, support) are each one link, and a call to action band closes the page. The hero rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, faq-section, cta-section, button, empty-state, search-input, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "minimal" | "editorial"` = "classic": The whole page's look. classic: the layout props, a grid behind the hero, raised topic and help cards and a solid closing band; minimal: a transparent header, no grid, a flat search field, outlined chips and topic cards, a borderless FAQ, flat help cards, no gray band, a plain closing call and a simple footer; editorial: a centered header, huge start-aligned type and an underlined search in one narrow column, the topics as a numbered index, numbered questions, help options as ruled rows and a wordmark footer. headerProps and footerProps still win.
- `topics?: FaqPageTopic[]` = "FAQ_PAGE_TOPICS": { value, label, icon?, description? }: the topic cards and the FAQ categories; value matches FaqItem.category.
- `items?: FaqItem[]` = "FAQ_PAGE_ITEMS": { id?, question, answer, answerText?, category? }: 21 sample questions across five topics.
- `popular?: string[]` = "FAQ_PAGE_POPULAR": Quick searches under the field; an empty array hides the row.
- `help?: FaqPageHelpOption[]` = "FAQ_PAGE_HELP": { icon?, title, description, href, action }: the Still need help? cards.
- `labels?: Partial<FaqPageLabels>` = "DEFAULT_FAQ_PAGE_LABELS": Every visible string.
- `defaultCategory?: string` = "all": The topic selected on load: all or a topic value.
- `defaultQuery?: string` = "": The search on load, like a link from elsewhere would set it.
- `syncUrl?: boolean` = true: Reads ?q= and #topic on load (and on hash changes) and keeps them in the address bar.
- `onSearch?: (query: string) => void`: Runs on Enter and when a popular search is picked (analytics, a server search).
- `faqLayout?: "centered" | "split" | "grid"` = "centered": The FAQ: one column with the topic row, the heading on the left, or two columns with every answer open. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split" | "plain"` = "inverted": The look of the closing call to action band. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The selected topic card and chip, the popular search in use and the open answer.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The primary button of the call to action band.
- `showTopics?: boolean` = true: The topic cards (hidden while searching).
- `showPopular?: boolean` = true: The popular searches under the field.
- `showHelp?: boolean` = true: The Still need help? cards.
- `showCta?: boolean` = true: The call to action band.
- `jsonLd?: boolean` = true: A FAQPage json-ld script with every answer, for search engines (left out while searching).
- `contactHref?: string` = "/contact": Where Contact support goes from the empty state.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and help cards (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<FaqPageSlot, string>>`: Classes for header, hero, search, popular, topics, topic, faq, empty, help, cta and footer.

Parts:
- `FAQ_PAGE_SAMPLE` (constant): All the sample content in one object: topics, items, popular and help.
- `FAQ_PAGE_TOPICS` (constant): Getting started, Billing, Account, Security and Integrations with lucide icons.
- `FAQ_PAGE_ITEMS` (constant): 21 sample questions and answers.
- `FAQ_PAGE_POPULAR` (constant): Five popular searches.
- `FAQ_PAGE_HELP` (constant): Docs, community and support cards.
- `DEFAULT_FAQ_PAGE_LABELS` (constant): The English strings.
- `FAQ_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal", "editorial"].
- `FaqPageDesign` (type): "classic" | "minimal" | "editorial".
- `FaqPageProps` (type): Props of FaqPage.
- `FaqPageTopic` (type): A topic card and FAQ category in one.
- `FaqPageHelpOption` (type): One Still need help? card.

```tsx
// app/(marketing)/faq/page.tsx
"use client"

import Link from "next/link"
import { FaqPage } from "@/components/templates/faq-page"

export default function FaqRoute() {
  return (
    <FaqPage
      linkComponent={Link}
      onSearch={(query) => {
        // count what people look for, to write the next answers
        void fetch("/api/search-log", { method: "POST", body: query })
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/faq-page (Markdown: https://wingo-ui.com/templates/faq-page.md)

#### Feature Page (`feature-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add feature-page`

A SaaS feature page: hero with a drawn mockup, how-it-works steps, use case tabs, capabilities, integrations, quotes, FAQ and CTA.

One page per product feature, driven by a single feature object. A breadcrumb (Product / Automations) sits over the hero; the hero rises in once on mount beside a drawn automation rule with its recent runs, which themes itself. How it works shows three numbered steps, each with a small drawn card. The use cases switch with tabs (arrow keys move between them; on phones the row scrolls sideways), each showing the rule it runs. Capabilities list as compact rows. Every integration tile is one link to its integration page, and See all 80+ integrations goes to /integrations. Customer quotes lead with one large quote. Related features are single-link cards. FAQ answers open one at a time, and the closing band links to sign-up and sales. Sections alternate between plain and gray bands. Reduced motion keeps everything still.

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, feature-grid, feature-showcase, testimonials-section, stats-section, faq-section, cta-section, navigation, tones, ui-config

Props:
- `feature?: FeaturePageFeature` = "AUTOMATIONS_FEATURE": { name, icon?, path, parent?, title, description, announcement?, media?, rule?, steps, useCases, capabilities, integrations, testimonials, related, faq, stats?, copy? }; copy overrides any section heading. stats feed the bold design's numbers band and the editorial hero's key facts.
- `design?: "classic" | "bold" | "editorial"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, the drawn rule on a tinted stage with the copy in a glass card over it on a gradient mesh, heavy type, an inverted numbers band from feature.stats, larger step and integration tiles, tour cards, solid icon tiles, a wall of quotes, illustrated related cards, FAQ cards, an image band and a wordmark footer; editorial: a centered header, a magazine cover hero with the feature's key facts and no mockup, start-aligned headings with small caps eyebrows, hairlines between sections, ruled steps with 01 02 03 and no visuals, a pinned tour, numbered capabilities, integration rows, one large quote at a time, an open FAQ grid and a centered footer. The *Props overrides still win.
- `labels?: Partial<FeaturePageLabels>` = "DEFAULT_FEATURE_PAGE_LABELS": The generic strings: section headings a feature does not override, buttons and the drawn mockup's words.
- `heroLayout?: "centered" | "split" | "stacked"` = "split": split: copy left, mockup right; centered: copy over the mockup; stacked: title and copy side by side over it. Applies to the classic design.
- `useCasesLayout?: "tabs" | "zigzag"` = "tabs": The use cases as tabs that swap one visual, or alternating rows. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split"` = "inverted": The closing band: a solid band, a gray band, or copy beside the buttons on a raised panel. Applies to the classic design.
- `showBreadcrumb?: boolean` = true: Product / feature above the hero.
- `showSteps?: boolean` = true: How it works.
- `showUseCases?: boolean` = true: The use case tabs.
- `showCapabilities?: boolean` = true: The capability rows.
- `showIntegrations?: boolean` = true: The integration tiles.
- `showTestimonials?: boolean` = true: The customer quotes.
- `showRelated?: boolean` = true: The related feature cards.
- `showFaq?: boolean` = true: The feature FAQ.
- `showCta?: boolean` = true: The closing call to action.
- `alternate?: boolean` = true: Gray bands on every other visible section. Applies to the classic and bold designs.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accents: the hero glow, the rule's trigger and switch, step numbers, icon tiles and checks.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Get started, the hero's primary button and the closing band; brand is the marketing orange.
- `header?: boolean` = true: The marketing header (the feature's path is marked in its menu); off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `heroProps?: Partial<HeroSectionProps>`: Overrides for the HeroSection.
- `useCasesProps?: Partial<FeatureShowcaseProps>`: Overrides for the use cases FeatureShowcase (tabsPosition, frame...).
- `capabilitiesProps?: Partial<FeatureGridProps>`: Overrides for the capabilities FeatureGrid (layout, columns...).
- `testimonialsProps?: Partial<TestimonialsSectionProps>`: Overrides for the TestimonialsSection (layout...).
- `relatedProps?: Partial<FeatureGridProps>`: Overrides for the related features FeatureGrid.
- `statsProps?: Partial<StatsSectionProps>`: Overrides for the numbers StatsSection that the bold design shows under the hero.
- `faqProps?: Partial<FaqSectionProps>`: Overrides for the FaqSection.
- `ctaProps?: Partial<CtaSectionProps>`: Overrides for the CtaSection.
- `animateIn?: boolean` = true: The hero rises in once on mount and the closing band settles; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the page (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<FeaturePageSlot, string>>`: Classes for header, breadcrumb, hero, stats, steps, step, useCases, capabilities, integrations, integration, testimonials, related, faq, cta and footer.

Parts:
- `RuleVisual` (component): An automation rule drawn with tokens: name and Active switch, When / If / Then blocks and the run summary. Takes div props.
- `AUTOMATIONS_FEATURE` (constant): The sample feature: Automations, with a rule, three steps, four use cases, six capabilities, eight integrations, quotes, related features and FAQ.
- `INSIGHTS_FEATURE` (constant): A second sample feature (Insights) that uses the app mockup and the built-in visuals instead of rules.
- `FEATURE_PAGE_SAMPLE` (constant): The default feature (AUTOMATIONS_FEATURE).
- `FEATURE_INTEGRATIONS` (constant): Eight integration tiles: Slack, GitHub, Figma, Google Calendar, Gmail, Jira, Zendesk and Webhooks.
- `FEATURE_RELATED` (constant): Planning, Docs and Insights cards.
- `DEFAULT_FEATURE_PAGE_LABELS` (constant): The English strings.
- `FEATURE_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "editorial"].
- `FeaturePageDesign` (type): "classic" | "bold" | "editorial".
- `FeaturePageProps` (type): Props of FeaturePage.
- `FeaturePageFeature` (type): Everything one feature page says.
- `FeatureRule` (type): A drawn automation rule.
- `FeatureStep` (type): { title, description, visual?, media? }: one how-it-works step.
- `FeatureStepVisual` (type): { kind: options | chain | log, title, items }: the small card drawn for a step.

```tsx
// app/(marketing)/product/[feature]/page.tsx
"use client"

import Link from "next/link"
import { notFound, useParams } from "next/navigation"
import { FeaturePage } from "@/components/templates/feature-page"
import { AUTOMATIONS_FEATURE, INSIGHTS_FEATURE } from "@/components/templates/feature-page-data"

const FEATURES = { automations: AUTOMATIONS_FEATURE, insights: INSIGHTS_FEATURE }

export default function FeatureRoute() {
  const { feature } = useParams<{ feature: keyof typeof FEATURES }>()
  if (!FEATURES[feature]) notFound()
  return <FeaturePage feature={FEATURES[feature]} linkComponent={Link} />
}
```

Docs: https://wingo-ui.com/templates/feature-page (Markdown: https://wingo-ui.com/templates/feature-page.md)

#### Help Article Page (`help-article-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add help-article-page`

One support article: search, a topic sidebar, a Markdown body with steps and callouts, contents and helpful feedback.

The breadcrumb links back to the help center and the article's topic (on phones it becomes one back link). Press / anywhere to focus the search bar: matching articles from every topic drop down under it with the typed words marked, Arrow Down moves into them, the arrow keys, Home and End walk through them, Escape returns to the field and a press outside closes them. On desktop the sidebar sticks beside the article with every article of the topic (the current one marked) and the other topics; below 1024px it is a button that opens it as a bottom sheet, which closes when you pick a link. The article is rendered from Markdown: numbered steps, Note / Tip / Warning callouts, key caps that show the right modifier for the device, a table that scrolls sideways on phones and a code block with a copy button. From 1280px the table of contents sticks on the right and marks the section being read; below it becomes a pill pinned under the header that opens a sheet. Was this article helpful? thanks you on Yes; No opens a comment box (focused, Cmd/Ctrl+Enter sends, Skip closes it) that ends in a thank-you. The contact card opens an email or the chat, and each related article is one link with the focus ring on the card.

npm: motion, lucide-react
Wingo UI dependencies: help-center-page, marketing-section, marketing-header, marketing-footer, avatar, breadcrumb, button, kbd, markdown, search-input, sheet, table-of-contents, textarea, use-controllable-state, motion, navigation, text-match, tones, ui-config

Props:
- `design?: "classic" | "minimal"` = "classic": The whole page's look. classic: a tinted search bar, tinted sidebar items, a gray feedback box, raised contact and related cards on a gray band; minimal: a transparent header, a flat search, a ruled sidebar, callouts as colored rules, outlined boxes, related articles as hairline rows with no gray band and a simple footer. headerProps and footerProps still win.
- `article?: HelpArticle` = "HELP_ARTICLE_SAMPLE": The article: HelpCenterArticle fields (slug, title, excerpt, category, minutes, updated) plus summary, body (Markdown), author and helpful ({ yes, total }). In the body, > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION] quotes become callouts and `kbd:mod+k` inline code becomes a key cap.
- `articles?: HelpCenterArticle[]` = "HELP_CENTER_ARTICLES": The sidebar's topic list and what the search looks through; each links to /help/<slug>.
- `categories?: HelpCenterCategory[]` = "HELP_CENTER_CATEGORIES": The topics: the breadcrumb, the sidebar and the result labels; each links to /help/<value>.
- `relatedArticles?: HelpCenterArticle[]` = "HELP_ARTICLE_RELATED": Up to three cards under the article.
- `labels?: Partial<HelpArticlePageLabels>` = "DEFAULT_HELP_ARTICLE_PAGE_LABELS": Every visible string: search, sidebar, meta, callout titles, feedback, contact and related copy.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `defaultQuery?: string` = "": The search text on load, with the results open. The playground offers a few real searches and one with no results.
- `query?: string`: Controlled search text; pair it with onQueryChange.
- `onQueryChange?: (query: string) => void`: Fires on every keystroke and clear.
- `onSearch?: (query: string) => void`: Runs once typing pauses and on Enter; with "" on clear. Use it for analytics or a server search.
- `searchShortcut?: string` = "/": Focuses the search from anywhere; "" binds nothing.
- `showSearch?: boolean` = true: The search bar beside the breadcrumb.
- `showSidebar?: boolean` = true: The topic sidebar (a sheet below 1024px).
- `showToc?: boolean` = true: The table of contents: sticky on the right from 1280px, a pill and a sheet below.
- `showMeta?: boolean` = true: The author, last updated date and reading time under the title.
- `showFeedback?: boolean` = true: The "Was this article helpful?" box.
- `showContact?: boolean` = true: The contact support card after the article.
- `showRelated?: boolean` = true: The related articles section.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `tocVariant?: "line" | "dots" | "plain"` = "line": The table of contents' look: a rail with a moving indicator, dots or plain links.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Links in the article and the active contents entry.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The solid buttons: Chat with us, Send feedback and the header's Get started.
- `animateIn?: boolean` = true: The title rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the last updated date.
- `helpHref?: string` = "/help": The help center root: the breadcrumb, Back to the help center, /help/<topic> and /help/<slug>.
- `chatHref?: string` = "/contact?topic=chat": Where Chat with us goes.
- `supportEmail?: string` = "support@acme.com": Email support opens a message to it, with the article title as the subject.
- `onFeedback?: (helpful: boolean, comment?: string) => (void | Promise<unknown>)`: Was this article helpful?; called on Yes, on No and again with the comment. A returned promise keeps the button loading; without it the page waits 600 ms.
- `markdownProps?: Partial<MarkdownProps>`: Passed to the article's Markdown (components, rehypePlugins, codeLineNumbers...).
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<HelpArticlePageSlot, string>>`: Classes for hero, breadcrumb, search, results, sidebar, sidebarTrigger, title, meta, toc, body, feedback, contact and related.

Parts:
- `helpArticleToc` (function): helpArticleToc(source) returns the h2 and h3 of a Markdown string as TocItem[], with the ids Markdown's headingIds gives them.
- `HELP_ARTICLE_SAMPLE` (constant): The sample article: "Set up recurring tasks" in Boards and planning, by Ava Thompson.
- `HELP_ARTICLE_RELATED` (constant): Three related articles from HELP_CENTER_ARTICLES.
- `DEFAULT_HELP_ARTICLE_PAGE_LABELS` (constant): The English strings.
- `HELP_ARTICLE_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal"].
- `HelpArticle` (type): HelpCenterArticle & { summary?, body, author?, helpful? }.
- `HelpArticleAuthor` (type): { name, role, avatar? }.
- `HelpArticleCallout` (type): "note" | "tip" | "important" | "warning" | "caution".
- `HelpArticlePageLabels` (type): The labels object.
- `HelpArticlePageProps` (type): Props of HelpArticlePage.
- `HelpArticlePageDesign` (type): "classic" | "minimal".

```tsx
// app/(marketing)/help/[slug]/page.tsx
"use client"

import Link from "next/link"
import { notFound, useParams } from "next/navigation"
import { HelpArticlePage } from "@/components/templates/help-article-page"
import { HELP_ARTICLE_SAMPLE } from "@/components/templates/help-article-page-data"

export default function HelpArticleRoute() {
  const { slug } = useParams<{ slug: string }>()
  if (slug !== HELP_ARTICLE_SAMPLE.slug) notFound()
  return (
    <HelpArticlePage
      linkComponent={Link}
      article={HELP_ARTICLE_SAMPLE}
      onFeedback={(helpful, comment) =>
        fetch("/api/help-feedback", { method: "POST", body: JSON.stringify({ slug, helpful, comment }) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/help-article-page (Markdown: https://wingo-ui.com/templates/help-article-page.md)

#### Help Center Page (`help-center-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add help-center-page`

A support home: live search with grouped, highlighted results, topic chips, category cards, popular articles, contact options and status.

Press / anywhere (not while typing elsewhere) to focus the big search in the hero. Results appear under the field as you type, grouped by topic (Getting started, Billing...) with the matching words marked in each title and summary, best title matches first, and the field shows how many articles match. Arrow Down moves from the field into the results, the arrow keys, Home and End walk through them, Enter opens one and Arrow Up from the first (or Escape) returns to the field; Escape in the field clears it. More than five results fold behind Show all. When nothing matches, an empty state offers Clear search and Contact support. The Popular chips fill the search in one tap (tap again to clear). The status pill above the title links to /status and its dot pulses in the status color. Each topic card shows its article count and links to /help/<topic>; each popular article and each contact option (chat, email, community) is one link with the focus ring on the card. The chips scroll sideways on phones, cards stack to one column, and every target is 44px on touch.

npm: lucide-react
Wingo UI dependencies: feature-grid, hero-section, marketing-footer, marketing-header, marketing-section, avatar, button, empty-state, search-input, use-controllable-state, navigation, text-match, tones, ui-config

Props:
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a split mesh hero with the search beside a drawn support chat, heavy type, illustrated topic cards, big numbered articles under hairlines, the contact options on a dark band and a wordmark footer; minimal: a transparent header, no backdrop, a flat search, outlined chips, topics as compact rows, hairline lists, no gray bands and a simple footer. headerProps and footerProps still win.
- `categories?: HelpCenterCategory[]` = "HELP_CENTER_CATEGORIES": The topic cards and result groups: { value, label, description, icon?, count? }; each links to /help/<value>.
- `articles?: HelpCenterArticle[]` = "HELP_CENTER_ARTICLES": What the search looks through: { slug, title, excerpt, category, minutes, updated, keywords? }; each links to /help/<slug>.
- `popularArticles?: HelpCenterArticle[]` = "HELP_CENTER_POPULAR": The numbered Popular articles list.
- `topics?: string[]` = "HELP_CENTER_TOPICS": Chips under the field that fill it in; an empty array hides the row.
- `contactOptions?: HelpCenterContactOption[]` = "HELP_CENTER_CONTACT": The Still need help cards: { icon, title, description, meta, action, href, live? }.
- `labels?: Partial<HelpCenterPageLabels>` = "DEFAULT_HELP_CENTER_PAGE_LABELS": Every visible string, including the three status lines.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `defaultQuery?: string` = "": The search text on load, e.g. from ?q= in the address. The playground offers a few real searches and one with no results.
- `query?: string`: Controlled search text; pair it with onQueryChange.
- `onQueryChange?: (query: string) => void`: Fires on every keystroke, chip and clear.
- `onSearch?: (query: string) => void`: Runs once typing pauses, on Enter and when a chip is picked; with "" on clear. Use it for analytics or a server search.
- `maxResults?: number` = 5: Results shown before Show all.
- `searchShortcut?: string` = "/": Focuses the search from anywhere and shows as a key hint in the field; empty binds nothing.
- `status?: "operational" | "degraded" | "outage"` = "operational": The system status shown in the hero pill and the footer: a green, amber or red dot with labels.status.
- `statusHref?: string` = "/status": Where the status pill and the footer status link go.
- `contactHref?: string` = "/contact": Where Contact support goes from an empty search.
- `showStatus?: boolean` = true: The status pill above the title.
- `showTopics?: boolean` = true: The Popular chips under the search.
- `showCategories?: boolean` = true: The topic cards.
- `showPopular?: boolean` = true: The popular articles list.
- `showContact?: boolean` = true: The Still need help options.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `heroBackground?: "grid" | "glow" | "none"` = "grid": Faint lines, a soft light in the tone, or nothing behind the hero. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Icon tiles, the selected chip, the Status badge and the glow.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The solid buttons: Get started in the header and Contact support in the empty search.
- `animateIn?: boolean` = true: The hero rises in once on mount and the status dot pulses; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the Updated dates.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<HelpCenterPageSlot, string>>`: Classes for header, hero, status, search, topics, results, empty, categories, popular, contact and footer.

Parts:
- `HelpCenterSupportCard` (component): The support conversation drawn in code beside the bold hero: an agent, a question, an answer with an article and a composer. Takes div props.
- `HELP_CENTER_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `DEFAULT_HELP_CENTER_PAGE_LABELS` (constant): The English strings.
- `HELP_CENTER_CATEGORIES` (constant): Getting started, Boards and planning, Docs, Automations, Billing and Security with their counts.
- `HELP_CENTER_ARTICLES` (constant): 24 Acme help articles, four per topic.
- `HELP_CENTER_POPULAR` (constant): The six most read articles.
- `HELP_CENTER_POPULAR_SLUGS` (constant): The slugs behind HELP_CENTER_POPULAR.
- `HELP_CENTER_TOPICS` (constant): The chips: Invite teammates, Recurring tasks, Slack, Invoices, SSO, Import.
- `HELP_CENTER_CONTACT` (constant): Chat, email and community.
- `HelpCenterPageProps` (type): Props of HelpCenterPage.
- `HelpCenterPageDesign` (type): "classic" | "bold" | "minimal".
- `HelpCenterPageStatus` (type): "operational" | "degraded" | "outage".
- `HelpCenterPageLabels` (type): The labels object.
- `HelpCenterSearchResult` (type): { article, score }: one ranked search hit.
- `HelpCenterCategory` (type): { value, label, description, icon?, count? }.
- `HelpCenterArticle` (type): { slug, title, excerpt, category, minutes, updated, keywords? }.
- `HelpCenterContactOption` (type): { icon, title, description, meta, action, href, live? }.

```tsx
// app/(marketing)/help/page.tsx
"use client"

import Link from "next/link"
import { useSearchParams } from "next/navigation"
import { HelpCenterPage } from "@/components/templates/help-center-page"

export default function HelpRoute() {
  const params = useSearchParams()
  return (
    <HelpCenterPage
      linkComponent={Link}
      defaultQuery={params.get("q") ?? ""}
      status="operational"
      onSearch={(query) => console.log("help search", query)}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/help-center-page (Markdown: https://wingo-ui.com/templates/help-center-page.md)

#### Integration Detail Page (`integration-detail-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add integration-detail-page`

One integration's page: an install intro, a drawn screenshot, setup steps, permissions, a facts sidebar, FAQ and related integrations.

The intro shows the integration's tile, a Built by Acme badge, the title and its category tags (each a link back to the directory). Add to Slack pretends an OAuth round trip: the button spins with Connecting while the note reads Waiting for Slack to approve, then it turns into a green Connected pill with Disconnect beside it, a check appears on the tile, the note confirms the workspace and a toast says it is connected; Disconnect reverses it the same way. The install button in the sidebar mirrors the same state, and focus moves to the button that replaces the one you pressed. Below, the overview, a grid of features, numbered setup steps and the permissions requested, an accordion where every row opens to show what the permission is for and its scopes (several can stay open, and the browser's find in page opens the right row). On desktop the sidebar card stays in view while you scroll: facts (developer, category, pricing, installs, version) and links to the docs, privacy policy, terms and support. Then the FAQ, related integrations (each card is one link to /integrations/<slug>) and the closing call to action. Below 1024px the screenshot moves under the intro and the sidebar follows the main column.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, faq-section, cta-section, accordion, badge, breadcrumb, button, description-list, tag, toast, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `design?: "classic" | "minimal"` = "classic": The whole page's look. classic: a glow in the integration's color behind the intro, the screenshot beside the copy, flat feature tiles, a raised sidebar card, an outlined permissions accordion, a split FAQ on a gray band, raised related cards and an inverted closing band; minimal: a transparent header, no glow, a stacked intro, the screenshot in the body with a caption, borderless features, a hairline sidebar, a ghost accordion, a centered FAQ, related integrations as rows, a plain closing and a simple footer. headerProps, faqProps, ctaProps and footerProps still win.
- `integration?: IntegrationDetail` = "INTEGRATION_DETAIL": { slug, name, title, tagline, color, icon, builtBy, categories, installs, overview, features, steps, permissions, facts, links, screenshot }. The link with id docs feeds Read the docs.
- `related?: RelatedIntegration[]` = "RELATED_INTEGRATIONS": { slug, name, category, description, color, icon, href? } cards after the FAQ; href defaults to /integrations/<slug>.
- `faq?: FaqItem[]` = "INTEGRATION_DETAIL_FAQ": The questions in the FAQ section.
- `screenshot?: ReactNode`: Replaces the drawn screenshot (an image, a video, your own drawing).
- `labels?: Partial<IntegrationDetailPageLabels>` = "DEFAULT_INTEGRATION_DETAIL_PAGE_LABELS": Every visible string: install states and notes, toasts, section titles, the screenshot's text, FAQ, related and closing copy.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `faqProps?: Partial<FaqSectionProps>`: Passed to FaqSection, spread last.
- `ctaProps?: Partial<CtaSectionProps>`: Passed to CtaSection, spread last.
- `connected?: boolean`: Controlled connection state; pair it with onConnectedChange.
- `defaultConnected?: boolean` = false: The page opens already connected (uncontrolled).
- `onConnectedChange?: (connected: boolean) => void`: Called after a connect or disconnect succeeds.
- `onConnect?: (integration: IntegrationDetail) => (void | Promise<unknown>)`: The install (an OAuth redirect, an API call); a returned promise keeps the button loading, a rejection shows an error note. Without it the page waits 1.2 s and connects.
- `onDisconnect?: (integration: IntegrationDetail) => (void | Promise<unknown>)`: Disconnect; same promise rules. Without it the page waits 600 ms.
- `toastOptions?: ToastOptions | false` = "{}": Options for the toast after connecting and disconnecting ({ toasterId, duration... }; it needs a Toaster on the page); false sends none.
- `introLayout?: "split" | "stacked"` = "split": split: the copy beside the screenshot from 1024px; stacked: the screenshot under the copy. Applies to the classic design.
- `stickySidebar?: boolean` = true: The facts card stays in view while the main column scrolls (from 1024px).
- `relatedLimit?: number` = 4: How many related integrations show.
- `showScreenshot?: boolean` = true: The drawn screenshot (or the screenshot node).
- `showFeatures?: boolean` = true: The feature grid.
- `showSteps?: boolean` = true: The numbered setup steps.
- `showPermissions?: boolean` = true: The permissions accordion.
- `showFaq?: boolean` = true: The FAQ section.
- `showRelated?: boolean` = true: The related integrations.
- `showCta?: boolean` = true: The closing call to action.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Feature icons, step numbers, the open permission and the FAQ.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The install buttons, the header's Get started and the closing call to action.
- `animateIn?: boolean` = true: The intro rises in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<IntegrationDetailPageSlot, string>>`: Classes for intro, logo, actions, screenshot, body, overview, features, steps, permissions, sidebar, faq, related and cta.

Parts:
- `IntegrationScreenshot` (component): The drawn chat app: a channel rail in the integration's color, messages and the app's task card with fields and buttons. Themes itself; takes div props.
- `IntegrationDetailLogo` (component): The integration's tile: a lucide glyph on its color, black or white picked for contrast, with an optional connected check. Takes span props.
- `INTEGRATION_DETAIL` (constant): Acme for Slack: overview, six features, four setup steps, five permissions with scopes, facts, links and the screenshot's messages.
- `RELATED_INTEGRATIONS` (constant): Microsoft Teams, Zoom, Google Calendar, GitHub, Linear, Gmail and Zapier, as glyph tiles.
- `INTEGRATION_DETAIL_FAQ` (constant): Six questions about cost, privacy, installs, workspaces, Enterprise Grid and disconnecting.
- `DEFAULT_INTEGRATION_DETAIL_PAGE_LABELS` (constant): The English strings.
- `INTEGRATION_DETAIL_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal"].
- `IntegrationDetailPageDesign` (type): "classic" | "minimal".
- `IntegrationDetailIntroLayout` (type): "split" | "stacked".
- `IntegrationDetail` (type): One integration with everything the page shows.
- `IntegrationDetailFeature` (type): { icon, title, description }.
- `IntegrationDetailStep` (type): { title, description }.
- `IntegrationDetailPermission` (type): { id, title, description, scopes }.
- `IntegrationDetailFact` (type): { id, label, value, description? } in the sidebar.
- `IntegrationDetailLink` (type): { id, label, href } in the sidebar's resources.
- `IntegrationDetailScreenshot` (type): The drawn screenshot's workspace, channels and messages.
- `IntegrationDetailMessage` (type): One message in the screenshot, optionally from the app with a task card.
- `RelatedIntegration` (type): { slug, name, category, description, color, icon, href? }.
- `IntegrationDetailPageLabels` (type): The strings the page shows.
- `IntegrationDetailPageProps` (type): Props of IntegrationDetailPage.

```tsx
// app/(marketing)/integrations/slack/page.tsx
"use client"

import Link from "next/link"
import { IntegrationDetailPage } from "@/components/templates/integration-detail-page"
import { INTEGRATION_DETAIL } from "@/components/templates/integration-detail-page-data"
import { Toaster } from "@/components/ui/toast"

export default function SlackIntegrationRoute() {
  return (
    <>
      <IntegrationDetailPage
        linkComponent={Link}
        integration={INTEGRATION_DETAIL}
        onConnect={(integration) => {
          window.location.href = `/api/oauth/${integration.slug}/start`
          // never resolves: the button keeps spinning until the redirect
          return new Promise(() => {})
        }}
        onDisconnect={(integration) =>
          fetch(`/api/integrations/${integration.slug}`, { method: "DELETE" })
        }
      />
      <Toaster />
    </>
  )
}
```

Docs: https://wingo-ui.com/templates/integration-detail-page (Markdown: https://wingo-ui.com/templates/integration-detail-page.md)

#### Integrations Page (`integrations-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add integrations-page`

A SaaS integrations directory: hero search, category sidebar, cards with install switches, a detail drawer, a request form and an API band.

Type in the hero search (press / to focus it) and the directory filters live by name, description and category, with the result count in the field; Enter scrolls to the results, and the Popular buttons under the field fill it in. On desktop a sticky sidebar lists All, the seven categories and Installed, each with its count for the current search; below 1024px the same views become one row of chips that scrolls sideways. Every card is a single link to /integrations/<slug>: a plain click opens a side drawer (a bottom sheet on phones) with what the integration does, numbered setup steps and its permissions, and Connect spins, then shows a connected notice and turns into Disconnect. The switch on each card installs or removes the integration in place while it spins, and Installed cards say so in green. No match shows an empty state with Request an integration, which opens a small form (tool name prefilled from the search, use case, work email) that validates, spins and confirms; the dashed tile at the end of the grid opens it too. Below, the API band shows a copyable TypeScript snippet, then the closing call to action. Escape closes the drawer and the dialog.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, cta-section, badge, button, code-block, dialog, drawer, empty-state, input, search-input, switch, textarea, use-controllable-state, motion, navigation, text-match, tones, ui-config

Props:
- `integrations?: Integration[]` = "INTEGRATIONS": { slug, name, category, description, color, letter?, badge?, builtBy?, features, steps?, permissions?, href? }. Without steps or permissions the category's defaults are used.
- `categories?: IntegrationCategory[]` = "INTEGRATION_CATEGORIES": { value, label } views after All; an integration's category is a value.
- `apiSnippet?: string` = "INTEGRATIONS_API_SNIPPET": The TypeScript shown in the API band.
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic: raised cards in a grid; bold: a pill header, a hero on a gradient mesh with heavy type, larger integration tiles with big letter tiles and three-line descriptions, an image band and a wordmark footer; minimal: a transparent header, a quiet hero with no glow, one dense list of rows (letter, name, category, one-line description, switch) under hairlines, a flat API section, a plain closing and a simple footer. headerProps and footerProps still win.
- `labels?: Partial<IntegrationsPageLabels>` = "DEFAULT_INTEGRATIONS_PAGE_LABELS": Every visible string: hero, views, card and drawer copy, the request form and the API band.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (announcement, ctaTone, items...).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `defaultCategory?: string` = "all": The view the page opens on: all, installed or a category value.
- `defaultQuery?: string` = "": The search text the page opens with.
- `installed?: string[]`: Controlled slugs of the installed integrations; pair it with onInstalledChange.
- `defaultInstalled?: string[]` = "INTEGRATIONS_INSTALLED": Installed while uncontrolled: Slack, GitHub and Google Drive.
- `onInstalledChange?: (installed: string[]) => void`: Called after a connect or disconnect succeeds.
- `onConnect?: (integration: Integration) => (void | Promise<unknown>)`: Connect from the drawer or a card switch; a returned promise keeps it loading, a rejection leaves it off. Without it the page waits 900 ms.
- `onDisconnect?: (integration: Integration) => (void | Promise<unknown>)`: Disconnect; same promise rules. Without it the page waits 500 ms.
- `onRequest?: (request: IntegrationRequest) => (void | Promise<unknown>)`: The request form ({ name, useCase, email }); a rejection shows an error. Without it the form waits 900 ms and succeeds.
- `integrationDetail?: "drawer" | "link"` = "drawer": drawer: a card opens the details in a side panel (a sheet on phones); link: cards navigate to integrationHref.
- `integrationHref?: (integration: Integration) => string` = "integration.href ?? /integrations/<slug>": Where each card and the drawer's setup guide link.
- `onOpenIntegration?: (integration: Integration, event: MouseEvent) => void`: Runs when a card is opened; preventDefault() keeps the drawer closed and the link from navigating.
- `columns?: 2 | 3` = 3: Card columns from 1280px (two from 640px, one on phones). Applies to the classic and bold designs; minimal is one list.
- `showInstallToggle?: boolean` = true: The install switch on every card.
- `showApi?: boolean` = true: The API band with the code snippet.
- `showCta?: boolean` = true: The closing call to action.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Selected chips, the sidebar icon and the install switches.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Connect, Request an integration, the API docs button and the closing call to action.
- `loading?: boolean` = false: Skeleton cards in the real layout.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<IntegrationsPageSlot, string>>`: Classes for hero, directory, sidebar, chips, grid, card, api, cta, drawer and request.

Parts:
- `IntegrationCard` (component): One integration as a single stretched link: letter tile, badge, name, category, description and an install switch that sits above the link. Takes article props.
- `IntegrationLogo` (component): The letter tile drawn in place of a brand logo, on the integration's color with black or white text picked for contrast. Takes span props.
- `integrationSetup` (function): integrationSetup(integration) returns { steps, permissions }: its own, else its category's defaults.
- `INTEGRATIONS` (constant): 31 sample integrations across seven categories (Slack, GitHub, Figma, Google Drive, Zapier, HubSpot, Salesforce, Notion, Linear, Jira, Zoom, Stripe...), as text only.
- `INTEGRATION_CATEGORIES` (constant): Communication, Developer tools, Design, CRM & Sales, Storage, Analytics and Automation.
- `INTEGRATION_CATEGORY_DEFAULTS` (constant): Setup steps and permissions per category, as functions of the integration's name.
- `INTEGRATION_CATEGORY_ICONS` (constant): The lucide glyph of each category in the sidebar.
- `INTEGRATIONS_INSTALLED` (constant): The slugs installed in the sample workspace.
- `INTEGRATIONS_API_SNIPPET` (constant): The REST example in the API band: create a task from a support ticket.
- `DEFAULT_INTEGRATIONS_PAGE_LABELS` (constant): The English strings.
- `Integration` (type): One integration: name, category, description, tile color, badge, features, setup and permissions.
- `IntegrationCategory` (type): { value, label }.
- `IntegrationBadge` (type): "popular" | "new" | "beta".
- `IntegrationRequest` (type): { name, useCase, email } from the request form.
- `IntegrationsPageProps` (type): Props of IntegrationsPage.
- `INTEGRATIONS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `IntegrationsPageDesign` (type): "classic" | "bold" | "minimal".
- `IntegrationCardVariant` (type): "card" | "tile" | "row": the look of IntegrationCard.

```tsx
// app/(marketing)/integrations/page.tsx
"use client"

import Link from "next/link"
import { IntegrationsPage } from "@/components/templates/integrations-page"
import { INTEGRATIONS } from "@/components/templates/integrations-page-data"

export default function IntegrationsRoute() {
  return (
    <IntegrationsPage
      linkComponent={Link}
      integrations={INTEGRATIONS}
      onConnect={(integration) => {
        window.location.href = `/api/oauth/${integration.slug}/start`
      }}
      onRequest={(request) =>
        fetch("/api/integration-requests", { method: "POST", body: JSON.stringify(request) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/integrations-page (Markdown: https://wingo-ui.com/templates/integrations-page.md)

#### Job Detail Page (`job-detail-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add job-detail-page`

One open role on a SaaS careers site: the job, benefits, interview steps, team, a sticky apply card, an application form and similar roles.

The breadcrumb leads back to Careers (one back link on phones). Copy link copies the page address and confirms with a check; the LinkedIn, X and email buttons open a share. On desktop the apply card sticks beside the description, and Apply now glides to the form and puts the caret in the first field; below 1024px a bottom bar with the title, the salary and Apply now rides above the safe area while the form is out of view. The form checks name, email, an optional LinkedIn URL, the resume (drop or pick a PDF or Word file) and the consent box, focusing the first problem; Submit application spins while onApply runs, then turns into a confirmation with a link back to all roles. Similar roles at the end link to their own pages. The hero rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, steps-section, avatar, badge, breadcrumb, button, checkbox, copy-button, file-upload, input, sticky-cta-bar, textarea, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "minimal" | "editorial"` = "classic": The whole page's look. classic: raised apply card and form, benefit tiles, team chips and similar roles as cards on a gray band; minimal: a transparent header, a smaller title, a hairline apply card, benefits as ruled rows, outline step numbers, a flat form, similar roles as rows and a simple footer; editorial: a centered header, a large display title over a heavy rule, numbered sections under heavy rules, a ruled apply card, ruled rows and a centered footer. headerProps and footerProps still win.
- `role?: JobDetail` = "JOB_DETAIL_ROLE": { slug, title, department, location, workplace, type, salaryMin?, salaryMax?, salaryCurrency?, postedAt?, isNew?, summary, about, responsibilities, requirements, niceToHave?, hiringManager? }; the sample is a Senior Frontend Engineer, Remote US.
- `similarRoles?: JobRole[]` = "JOB_DETAIL_SIMILAR": The roles under Similar roles, each linking to roleHref(role).
- `benefits?: JobBenefit[]` = "JOB_DETAIL_BENEFITS": { icon?, title, description } of the benefits grid.
- `steps?: StepsSectionItem[]` = "JOB_DETAIL_STEPS": The interview steps ({ icon?, title, description, meta? }), drawn by StepsSection.
- `team?: JobTeamMember[]` = "JOB_DETAIL_TEAM": { name, role, avatar? } of Who you'll work with; the hiring manager reads as such.
- `labels?: Partial<JobDetailPageLabels>` = "DEFAULT_JOB_DETAIL_PAGE_LABELS": Every visible string, including the form's messages.
- `careersHref?: string` = "/careers": Where Careers in the breadcrumb, All open roles and the success link go.
- `roleHref?: (role: JobRole) => string` = "(role) => `/careers/${role.slug}`": Where each similar role links to.
- `url?: string` = "": The address Copy link and the share buttons use; default the page's own.
- `onApply?: (application: JobApplication) => (void | Promise<unknown>)`: Sends { role, name, email, linkedin, resume?, note, consent }; a promise keeps the button loading, a rejection shows labels.failed. Without it the page waits 900 ms and confirms.
- `processLayout?: "vertical" | "cards"` = "vertical": Classic design: the interview steps as a timeline rail or as numbered cards.
- `benefitsLayout?: "tiles" | "list"` = "tiles": Classic design: benefits as soft tiles or as ruled rows.
- `similarLayout?: "cards" | "rows"` = "cards": Classic design: similar roles as raised cards or as ruled rows.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The step numbers, the New badge and the success panel (success while neutral).
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Apply now, the bottom bar, the consent box and Submit application; brand is the marketing orange.
- `showShare?: boolean` = true: Copy link and the share buttons under the title.
- `showBenefits?: boolean` = true: The benefits grid.
- `showProcess?: boolean` = true: The interview steps.
- `showTeam?: boolean` = true: Who you'll work with.
- `showSimilar?: boolean` = true: The similar roles at the end.
- `applyBar?: boolean` = true: The bottom Apply now bar below 1024px, shown while the form is out of view.
- `stepsProps?: Partial<StepsSectionProps>`: Passed to the interview StepsSection (marker, layout, radius...).
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the salary range and the posted date.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, breadcrumb, footer and role links (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<JobDetailPageSlot, string>>`: Classes for header, hero, breadcrumb, title, meta, share, body, content, aside, benefits, process, team, apply, form, similar, bar and footer.

Parts:
- `JOB_DETAIL_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal", "editorial"].
- `JobDetailPageDesign` (type): "classic" | "minimal" | "editorial".
- `formatJobSalary` (function): formatJobSalary(role, locale?): the yearly range in its currency, from the minimum to the maximum.
- `JOB_DETAIL_PAGE_SAMPLE` (constant): All the sample content in one object: role, similarRoles, benefits, steps and team.
- `JOB_DETAIL_ROLE` (constant): The sample role: Senior Frontend Engineer, Remote US, $160,000 to $190,000.
- `JOB_DETAIL_SIMILAR` (constant): Three sample similar roles.
- `JOB_DETAIL_BENEFITS` (constant): Eight sample benefits with lucide icons.
- `JOB_DETAIL_STEPS` (constant): The four interview steps: Intro call, Pairing session, Meet the team, Offer.
- `JOB_DETAIL_TEAM` (constant): Six sample teammates, the hiring manager first.
- `DEFAULT_JOB_DETAIL_PAGE_LABELS` (constant): The English strings.
- `JobDetailPageLabels` (type): Every string of the page; successDescription(name, role) is a function so the sentence can be reordered.
- `JobDetailPageSlot` (type): The keys of classNames: header, hero, breadcrumb, title, meta, share, body, content, aside, benefits, process, team, apply, form, similar, bar, footer.
- `JobDetailProcessLayout` (type): "vertical" | "cards".
- `JobDetailBenefitsLayout` (type): "tiles" | "list".
- `JobDetailSimilarLayout` (type): "cards" | "rows".
- `JobDetailPageProps` (type): Props of JobDetailPage.
- `JobDetail` (type): The role with its long description.
- `JobRole` (type): A role as a list row: slug, title, team, location, type, salary and summary.
- `JobWorkplace` (type): "Remote" | "Hybrid" | "On-site".
- `JobEmployment` (type): "Full-time" | "Part-time" | "Contract".
- `JobBenefit` (type): { icon?, title, description }: one benefit.
- `JobTeamMember` (type): { name, role, avatar? }: one teammate.
- `JobApplication` (type): { role, name, email, linkedin, resume?, note, consent }: what onApply receives.

```tsx
// app/(marketing)/careers/[slug]/page.tsx
"use client"

import Link from "next/link"
import { JobDetailPage } from "@/components/templates/job-detail-page"

export default function JobRoute() {
  return (
    <JobDetailPage
      linkComponent={Link}
      onApply={async (application) => {
        const body = new FormData()
        body.set("role", application.role.slug)
        body.set("name", application.name)
        body.set("email", application.email)
        body.set("linkedin", application.linkedin)
        body.set("note", application.note)
        if (application.resume) body.set("resume", application.resume)
        const response = await fetch("/api/applications", { method: "POST", body })
        if (!response.ok) throw new Error("Could not apply")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/job-detail-page (Markdown: https://wingo-ui.com/templates/job-detail-page.md)

#### Landing Page (`landing-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add landing-page`

A SaaS home page: hero with a drawn product shot, logos, bento features, product tour, numbers, quotes, pricing teaser, FAQ and CTA.

The sticky glass header carries a launch announcement and the site menu (dropdown panels on desktop, a bottom sheet on phones). The hero rises in once on mount over a drawn Acme app that themes itself. Customer logos scroll by in a marquee that pauses on hover or focus. The bento grid cards are single links. The product tour switches between Planning, Docs and Automations with tabs (arrow keys move between them; on phones the tab row scrolls sideways). The numbers roll up the first time they scroll into view. Customer quotes drift past in two rows with a pause button. The pricing teaser toggles Monthly and Yearly and the prices roll to the new amount; each plan button links to sign-up and Compare all plans to /pricing. FAQ answers open and close (one at a time), and the closing band links to sign-up and sales. The footer newsletter validates the email and confirms inline. Sections alternate between plain and gray bands. Reduced motion keeps everything still.

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, logo-cloud, feature-grid, feature-showcase, stats-section, testimonials-section, faq-section, cta-section, animated-counter, badge, button, segmented-control, navigation, tones, ui-config

Props:
- `logos?: LogoCloudItem[]` = "LANDING_LOGOS": { name, icon?, href?, className? } customer wordmarks.
- `features?: FeatureGridItem[]` = "LANDING_FEATURES": Six bento cells: { icon?, title, description, href?, badge?, visual? }; cells 1, 2 and 6 show their drawn visual.
- `showcase?: FeatureShowcaseItem[]` = "LANDING_SHOWCASE": The product tour: { value?, icon?, eyebrow?, title, description, points?, href?, media?, visual? }.
- `stats?: StatsSectionItem[]` = "LANDING_STATS": { value, decimals?, prefix?, suffix?, label, description? } figures.
- `testimonials?: Testimonial[]` = "LANDING_TESTIMONIALS": { quote, name, role?, company?, companyIcon?, avatar?, rating?, metric? } customer quotes.
- `plans?: LandingPlan[]` = "LANDING_PLANS": The pricing teaser: { id, name, description, price: { monthly, yearly }, priceNote?, features, cta, href, featured?, badge? }.
- `faq?: FaqItem[]` = "LANDING_FAQ": { question, answer } pairs; five short ones read best.
- `labels?: Partial<LandingPageLabels>` = "DEFAULT_LANDING_PAGE_LABELS": Every visible string: the announcement, each section heading, the pricing toggle and the CTA copy.
- `design?: "classic" | "bold" | "editorial" | "minimal"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a split hero on a gradient mesh with heavy type, logo tiles, illustrated feature cards, tour cards, an inverted numbers band, a wall of quotes, FAQ cards, an image band and a wordmark footer; editorial: a centered header, a magazine cover hero with no mockup, start-aligned headings with small caps eyebrows, hairlines between sections, numbered features, a pinned tour, one large quote at a time, square plans and a centered footer; minimal: a transparent header, a stacked hero with no glow, a feature list, flat cards, no gray bands, extra air and a simple footer. The *Props overrides still win.
- `announcementHref?: string` = "/blog/acme-3-launch": Where the announcement strip links to.
- `heroLayout?: "centered" | "split" | "stacked"` = "centered": centered: copy over a wide product shot; split: copy left, shot right; stacked: title and copy side by side over the shot. Applies to the classic design.
- `logosLayout?: "grid" | "marquee"` = "marquee": The customer logos as one scrolling row or wrapped rows. Applies to the classic design.
- `showcaseLayout?: "zigzag" | "tabs"` = "tabs": The product tour as tabs that swap one visual, or alternating rows of copy and visual. Applies to the classic design.
- `testimonialsLayout?: "grid" | "featured" | "marquee" | "carousel"` = "marquee": Quotes as two drifting rows, a masonry wall, one large quote with two small, or a swipeable carousel. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split"` = "inverted": The closing band: a solid band, a gray band, or copy beside the buttons on a raised panel. Applies to the classic design.
- `showAnnouncement?: boolean` = true: The strip above the header bar.
- `showLogos?: boolean` = true: The customer logos under the hero.
- `showFeatures?: boolean` = true: The bento feature grid.
- `showShowcase?: boolean` = true: The product tour.
- `showStats?: boolean` = true: The numbers.
- `showTestimonials?: boolean` = true: The customer quotes.
- `showPricing?: boolean` = true: The three-plan pricing teaser.
- `showFaq?: boolean` = true: The short FAQ.
- `showCta?: boolean` = true: The closing call to action.
- `alternate?: boolean` = true: Gray bands on every other visible section, so the page has a rhythm whichever sections are on. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accents across the page: the hero glow and mockup, icon tiles, tour checks, numbers, quote stars and plan checks.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Get started, the hero's primary button, the featured plan's button and the closing band; brand is the marketing orange.
- `defaultPeriod?: "monthly" | "yearly"` = "yearly": The pricing toggle on load.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer with its newsletter form.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `heroProps?: Partial<HeroSectionProps>`: Overrides for the HeroSection (media, background, hrefs...).
- `logosProps?: Partial<LogoCloudProps>`: Overrides for the LogoCloud.
- `featuresProps?: Partial<FeatureGridProps>`: Overrides for the FeatureGrid (layout, columns, card...).
- `showcaseProps?: Partial<FeatureShowcaseProps>`: Overrides for the FeatureShowcase (tabsPosition, frame...).
- `statsProps?: Partial<StatsSectionProps>`: Overrides for the StatsSection (variant, size...).
- `testimonialsProps?: Partial<TestimonialsSectionProps>`: Overrides for the TestimonialsSection.
- `faqProps?: Partial<FaqSectionProps>`: Overrides for the FaqSection (layout, searchable...).
- `ctaProps?: Partial<CtaSectionProps>`: Overrides for the CtaSection (newsletter, checklist, hrefs...).
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The footer newsletter; a rejected promise shows an error. Without it the form waits 900 ms and confirms.
- `animateIn?: boolean` = true: The hero rises in once, the numbers roll up and the quotes drift; false keeps the page still (thumbnails). Reduced motion always does.
- `locale?: string` = "en-US": Intl locale for the numbers and plan prices.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the page (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<LandingPageSlot, string>>`: Classes for header, hero, logos, features, showcase, stats, testimonials, pricing, plan, faq, cta and footer.

Parts:
- `LANDING_PAGE_SAMPLE` (constant): All the sample content in one object: logos, features, showcase, stats, testimonials, plans and faq.
- `LANDING_LOGOS` (constant): Eight fictional customer wordmarks.
- `LANDING_FEATURES` (constant): Six bento cells: insights, plans, search, security, speed and integrations.
- `LANDING_SHOWCASE` (constant): The three tour stops: Planning, Docs and Automations.
- `LANDING_STATS` (constant): Four figures: teams, faster delivery, uptime and rating.
- `LANDING_TESTIMONIALS` (constant): Eight customer quotes.
- `LANDING_PLANS` (constant): Free, Pro ($12, or $10 yearly) and Business ($24, or $20 yearly) per user per month.
- `LANDING_FAQ` (constant): Five short questions about the free plan, pricing, imports, data and cancelling.
- `DEFAULT_LANDING_PAGE_LABELS` (constant): The English strings.
- `LANDING_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "editorial", "minimal"].
- `LandingPageProps` (type): Props of LandingPage.
- `LandingPageDesign` (type): "classic" | "bold" | "editorial" | "minimal".
- `LandingPlan` (type): One plan of the pricing teaser.
- `LandingPageLabels` (type): The strings labels can override.

```tsx
// app/(marketing)/page.tsx
"use client"

import Link from "next/link"
import { LandingPage } from "@/components/templates/landing-page"

export default function HomeRoute() {
  return (
    <LandingPage
      linkComponent={Link}
      ctaTone="brand"
      onSubscribe={async (email) => {
        const response = await fetch("/api/newsletter", { method: "POST", body: JSON.stringify({ email }) })
        if (!response.ok) throw new Error("Could not subscribe")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/landing-page (Markdown: https://wingo-ui.com/templates/landing-page.md)

#### Legal Page (`legal-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add legal-page`

Terms, privacy, cookie and data processing pages in one template: a document switcher, a plain-English summary and numbered sections.

Switch between Terms, Privacy, Cookies and DPA in the pill row at the top (links to /legal/terms, /legal/privacy...; the thumb slides to the current one). Each document opens with its dates, a Download PDF and a Print action (both open the print dialog unless onDownload / onPrint are set; header, footer and navigation are hidden in print), and a short plain-English summary. On desktop the sticky On this page list follows your reading position and jumps to a section on click; arrow keys, Home and End move between its links. On phones it becomes a pill pinned under the header that shows the current section and opens a bottom sheet with every section. Every section heading has a copy button that copies its link (/legal/privacy#your-rights) and confirms with a check. Links inside the text to another document switch to it. Tables (sub-processors, retention, cookies) turn into one card per row below 768px. The page ends with a contact card: email legal@acme.com, copy the address, or read the postal address. The hero rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-header, marketing-footer, marketing-section, button, copy-button, table-of-contents, use-controllable-state, motion, navigation, tones, ui-config

Props:
- `documents?: LegalDocument[]` = "LEGAL_DOCUMENTS": The documents: { id, label, title, description, href, updated, effective, summary, sections }. A section's body is an array of simple blocks (paragraph, heading, list, definitions, table, note) or your own React content.
- `doc?: string`: The id of the document shown, controlled; pair it with onDocChange or set it per route.
- `defaultDoc?: string` = "terms": The document shown first while uncontrolled.
- `onDocChange?: (doc: string) => void`: Called when the switcher or a link in the text picks another document.
- `contact?: LegalContact` = "LEGAL_CONTACT": { email, company, address } for the contact card at the end.
- `contactEmail?: string` = "": Replaces contact.email.
- `design?: "classic" | "editorial" | "minimal"` = "classic": The whole page's look. classic: a pill switcher, raised summary, definition and table cards and a gray contact card; editorial: a centered header, a large start-aligned title over a heavy rule, underline tabs, the summary and sections divided by hairlines, open tables, italic notes on a side rule and a centered footer; minimal: a transparent header, a smaller title, a plain switcher, the summary as a quiet side rule, outlined tables, a plain table of contents, extra air and a simple footer. headerProps, footerProps and classNames still win.
- `numbered?: boolean` = true: Numbers the section headings and the table of contents.
- `showSummary?: boolean` = true: The "The short version" box above the sections.
- `showToc?: boolean` = true: The sticky table of contents (a pill and sheet on phones).
- `showActions?: boolean` = true: The Download PDF and Print buttons.
- `showContact?: boolean` = true: The contact card at the end.
- `tocVariant?: "line" | "dots" | "plain"` = "line": The look of the table of contents. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The table of contents indicator and the summary checks.
- `header?: boolean` = true: The sticky marketing header; turn it off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader (currentPath defaults to the document's href).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `onDownload?: (doc: LegalDocument) => void`: The Download PDF action; without it the print dialog opens (Save as PDF).
- `onPrint?: (doc: LegalDocument) => void`: The Print action; default window.print().
- `locale?: string` = "en-US": Intl locale for the dates.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app).
- `labels?: Partial<LegalPageLabels>`: Every visible string; English defaults in DEFAULT_LEGAL_PAGE_LABELS.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<LegalPageSlot, string>>`: Classes for hero, switcher, meta, actions, toc, article, summary, section, sectionTitle and contact.

Parts:
- `LegalBlocks` (component): Renders a section's simple blocks: paragraphs, subheadings, lists, definitions, tables (cards on phones) and notes. Takes div props.
- `LegalText` (component): Inline text with **bold**, [label](href) links and bare email addresses turned into mailto links.
- `LEGAL_DOCUMENTS` (constant): The sample Terms of Service, Privacy Policy, Cookie Policy and Data Processing Addendum for Acme.
- `LEGAL_CONTACT` (constant): The sample contact: legal@acme.com and a New York postal address.
- `LEGAL_PAGE_SAMPLE` (constant): { documents, contact } in one object.
- `DEFAULT_LEGAL_PAGE_LABELS` (constant): The English strings.
- `LEGAL_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "editorial", "minimal"].
- `LegalPageDesign` (type): "classic" | "editorial" | "minimal".
- `LegalDocument` (type): A document: id, label, title, description, href, updated, effective, summary and sections.
- `LegalSection` (type): { id, title, body }: the id is the anchor, body is LegalBlock[] or a ReactNode.
- `LegalBlock` (type): paragraph | heading | list | definitions | table | note.
- `LegalContact` (type): { email, company, address }.
- `LegalPageProps` (type): Props of LegalPage.

```tsx
// app/(marketing)/legal/[doc]/page.tsx
import Link from "next/link"
import { notFound } from "next/navigation"
import { LegalPage } from "@/components/templates/legal-page"
import { LEGAL_DOCUMENTS } from "@/components/templates/legal-page-data"

export function generateStaticParams() {
  return LEGAL_DOCUMENTS.map((doc) => ({ doc: doc.id }))
}

export default async function LegalRoute({ params }: { params: Promise<{ doc: string }> }) {
  const { doc } = await params
  if (!LEGAL_DOCUMENTS.some((item) => item.id === doc)) notFound()
  return <LegalPage linkComponent={Link} doc={doc} contactEmail="legal@acme.com" />
}
```

Docs: https://wingo-ui.com/templates/legal-page (Markdown: https://wingo-ui.com/templates/legal-page.md)

#### Press Page (`press-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add press-page`

A SaaS press room: releases, coverage, company facts and story, a brand kit with logos, colors and type, and a media contact.

The hero rises in once on mount beside a drawn press kit (logos, swatches, the typeface and the kit's folders); Download the press kit spins, then a toast names the file, and Contact the press team jumps to the media contact. Chips under the hero jump to each section (they scroll sideways on phones). The press releases filter by year with a live count, every row is one link to its post on the blog, and Show more adds the next releases and moves focus to the first new one. Coverage cards show the outlet's wordmark, the quote and the headline, each card one link to the article. The company facts sit beside the About Acme boilerplate with a copy button and a fact sheet download. The story is a timeline of milestones. The brand kit offers each logo as SVG or PNG (each button spins, then toasts), color swatches with a copy-hex button that turns into a check, the type specimens and do / don't cards with drawn examples. The media contact card has a mailto link, a copy button for the email and a tap-to-call phone number. Reduced motion keeps everything still.

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, logo-cloud, timeline-section, avatar, badge, button, copy-button, segmented-control, toast, navigation, tones, ui-config

Props:
- `design?: "classic" | "editorial" | "minimal"` = "classic": The whole page's look. classic follows the layout props; editorial: a centered solid header, a magazine hero with the first four facts under the rule, start-aligned headings, rules between sections, quotes and facts in big type under heavy rules, a vertical story and a centered footer; minimal: a transparent header, a centered hero without the visual, outlined cards, no gray bands and a simple footer. The *Props overrides still win.
- `releases?: PressRelease[]` = "PRESS_RELEASES": { slug, title, excerpt, date, category }; each links to blogHref/slug. date is an iso day.
- `coverage?: PressCoverage[]` = "PRESS_COVERAGE": { outlet, icon?, className?, quote, headline?, author?, date, href? }: the outlet's wordmark is text in its own type.
- `outlets?: PressOutlet[]` = "PRESS_OUTLETS": { name, icon?, className?, href? } wordmarks in the As featured in row.
- `facts?: PressFact[]` = "PRESS_FACTS": { label, value, detail? }; the editorial hero shows the first four.
- `boilerplate?: string` = "Acme is the workspace where small teams plan, write and ship. Founded in 2021 by Emma Carter and Liam Brooks, Acme brings roadmaps, docs and automations together for more than 12,000 teams in 94 countries, including Northwind, Globex and Umbrella Health. Acme is headquartered in New York, with studios in London and Berlin, and is backed by Northstar Ventures. Learn more at acme.com.": The About Acme paragraph with its copy button; an empty string hides the card.
- `milestones?: TimelineSectionMilestone[]` = "PRESS_MILESTONES": { year, title, description, icon?, stat?, href?, current? } for the company story.
- `logos?: PressLogoAsset[]` = "PRESS_LOGOS": { id, name, description, variant, background, foreground, tile, tileForeground, formats }; variant is full, mark, wordmark or stacked, the colors are the brand's own and do not follow the theme.
- `colors?: PressColor[]` = "PRESS_COLORS": { name, hex, ink, usage }; ink is the text color that reads on the swatch.
- `typefaces?: PressTypeface[]` = "PRESS_TYPEFACES": { name, role, family, weights: { label, value }[], sample } type specimens.
- `usage?: PressUsageRule[]` = "PRESS_USAGE": { id, kind, title, description, demo }; kind is do or dont, demo draws clearspace, contrast, stretch, recolor, effects or busy.
- `contact?: PressContact` = "PRESS_CONTACT": { name, role, email, phone?, note?, avatar? } for the media contact card.
- `kit?: PressDownload` = "PRESS_KIT": { id, name, format, size? }: the file behind every Download the press kit button.
- `brandName?: string` = "Acme": The name drawn in the logo assets.
- `brandMark?: ReactNode` = "<Mountain />": The glyph on the logo tile.
- `labels?: Partial<PressPageLabels>` = "DEFAULT_PRESS_PAGE_LABELS": Every visible string: headings, the jump chips, the hero's kit visual, buttons, toasts and accessible names.
- `heroLayout?: "split" | "centered"` = "split": The hero copy beside the drawn press kit, or centered over it. Applies to the classic design.
- `releasesLayout?: "list" | "cards"` = "list": The press releases as ruled rows in one card, or a grid of cards. Applies to the classic design.
- `storyLayout?: "vertical" | "alternating" | "horizontal"` = "horizontal": The company story: a rail, zigzag cards or a sideways scroller with arrows. Applies to the classic design.
- `releasesShown?: number` = 5: Releases shown before Show more, and how many each click adds.
- `onDownload?: (file: PressDownload) => (void | Promise<unknown>)`: Called with { id, name, format, size? } by every download button. A returned promise keeps the button loading, then a toast confirms; a rejection toasts labels.downloadFailed. Without it the button waits 900 ms and toasts.
- `toastOptions?: ToastOptions | false` = "{}": Options for the download toasts ({ toasterId, duration... }); false sends none.
- `blogHref?: string` = "/blog": Where the releases live: each links to blogHref/slug.
- `helpHref?: string` = "/help": Visit the help center, beside the media contact.
- `showJumpLinks?: boolean` = true: The row of section chips under the hero.
- `showOutlets?: boolean` = true: The As featured in row of outlet wordmarks.
- `showReleases?: boolean` = true: The press releases.
- `showCoverage?: boolean` = true: The coverage quotes.
- `showFacts?: boolean` = true: The company facts and the boilerplate.
- `showStory?: boolean` = true: The company story timeline.
- `showBrand?: boolean` = true: The brand kit: logos, colors, typography and usage.
- `showContact?: boolean` = true: The media contact (and the hero's Contact the press team).
- `alternate?: boolean` = true: Gray bands on every other visible section. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The hero glow and the kit icon, and the timeline's markers and stats.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Get started, the press kit downloads and Email the press team; brand is the marketing orange.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `heroProps?: Partial<HeroSectionProps>`: Overrides for the HeroSection (media, background, actions...).
- `outletsProps?: Partial<LogoCloudProps>`: Overrides for the outlets LogoCloud (layout, variant, columns...).
- `storyProps?: Partial<TimelineSectionProps>`: Overrides for the story TimelineSection (layout, card, marker...).
- `animateIn?: boolean` = true: The hero rises in once on mount; false keeps it still (thumbnails). Reduced motion always does.
- `locale?: string` = "en-US": Intl locale for the release and article dates.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the page (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<PressPageSlot, string>>`: Classes for header, hero, jump, outlets, releases, release, coverage, quote, facts, boilerplate, story, brand, logo, colors, swatch, typography, usage, contact, contactCard and footer.

Parts:
- `PressLogo` (component): The logo drawn in code: the glyph on a rounded tile and the name beside or under it, in fixed brand colors.
- `PRESS_PAGE_SAMPLE` (constant): All the sample content in one object.
- `PRESS_RELEASES` (constant): Eight Acme announcements from 2024 to 2026.
- `PRESS_COVERAGE` (constant): Four quotes from fictional outlets, newest first.
- `PRESS_OUTLETS` (constant): Six fictional outlet wordmarks.
- `PRESS_FACTS` (constant): Founded, headquarters, team, funding, customers and leadership.
- `PRESS_BOILERPLATE` (constant): The About Acme paragraph.
- `PRESS_MILESTONES` (constant): Five milestones from 2021 to 2026.
- `PRESS_LOGOS` (constant): The primary, reversed, mark and stacked logos.
- `PRESS_COLORS` (constant): Six brand colors with usage notes.
- `PRESS_TYPEFACES` (constant): Inter and JetBrains Mono.
- `PRESS_USAGE` (constant): Two do and four don't rules for the logo.
- `PRESS_CONTACT` (constant): Sophia Reed, Head of Communications.
- `PRESS_KIT` (constant): The press kit zip.
- `DEFAULT_PRESS_PAGE_LABELS` (constant): The English strings.
- `PRESS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "editorial", "minimal"].
- `PressPageProps` (type): Props of PressPage.
- `PressPageDesign` (type): "classic" | "editorial" | "minimal".
- `PressPageLabels` (type): The strings labels can override.
- `PressPageSlot` (type): The classNames keys: header, hero, jump, outlets, releases, release, coverage, quote and the rest.
- `PressPageHeroLayout` (type): "split" | "centered", the heroLayout values.
- `PressPageReleasesLayout` (type): "list" | "cards", the releasesLayout values.
- `PressLogoProps` (type): Props of PressLogo.
- `PressLogoVariant` (type): "full" | "mark" | "wordmark" | "stacked".
- `PressDownload` (type): { id, name, format, size? } passed to onDownload.
- `PressRelease` (type): One press release.
- `PressCoverage` (type): One coverage quote.
- `PressOutlet` (type): One outlet wordmark in the As featured in row.
- `PressFact` (type): One company fact: { label, value, detail? }.
- `PressLogoAsset` (type): One logo in the brand kit.
- `PressColor` (type): One brand color.
- `PressTypeface` (type): One type specimen.
- `PressUsageRule` (type): One do or don't card.
- `PressUsageDemo` (type): The drawn example on a usage card: clearspace, contrast, stretch, recolor, effects or busy.
- `PressContact` (type): The media contact.

```tsx
// app/(marketing)/press/page.tsx
"use client"

import Link from "next/link"
import { PressPage } from "@/components/templates/press-page"

export default function PressRoute() {
  return (
    <PressPage
      linkComponent={Link}
      onDownload={(file) => {
        window.location.href = `/press/${file.id}.${file.format.toLowerCase()}`
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/press-page (Markdown: https://wingo-ui.com/templates/press-page.md)

#### Roadmap Page (`roadmap-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add roadmap-page`

A public roadmap: Now, Next, Later and Shipped columns with upvotes, area filters, search, sorting and a suggest dialog.

Ideas sit in Now, Next, Later and Shipped columns: four side by side from 1024px, and below that one column at a time behind segmented tabs that show how many ideas each holds. Press the upvote pill on a card and the count rolls up at once and the pill fills (aria-pressed); press again to take the vote back. If saving fails the vote goes back and a short message says so. Type in the search to filter by title, description and area as you type; the area chips (a scrollable row on phones) narrow it further and show their counts; Top voted / Newest reorders the cards, which glide into place. When nothing matches, an empty state offers to clear the filters. Shipped cards link to their release notes in the changelog. Suggest a feature opens a dialog (a bottom sheet on phones) with a title, a description with a character count and an area; it checks each field, focuses the first problem, shows a spinner while sending (it cannot be closed until the answer comes back) and then a thank-you, and the new idea appears in Later with your vote and an In review badge. With a mouse the dialog opens with the title field focused; Tab moves through the fields, Enter submits and Escape closes it.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, faq-section, cta-section, animated-counter, badge, button, dialog, empty-state, input, search-input, segmented-control, select, textarea, motion, navigation, text-match, tones, ui-config

Props:
- `design?: "classic" | "minimal"` = "classic": The whole page's look. classic: tinted kanban columns with raised cards, a two-column FAQ on a gray band and a solid closing band; minimal: a transparent header, columns under a hairline with borderless outlined cards, outlined vote pills, a one-column FAQ, a plain closing section and a simple footer. headerProps, faqProps, ctaProps and footerProps still win.
- `items?: RoadmapItem[]` = "ROADMAP_ITEMS": The ideas: { id, title, description, area, status, votes, comments, updatedAt, eta?, version?, href?, voted?, review? }.
- `areas?: RoadmapArea[]` = "ROADMAP_AREAS": The product areas for the chips and the dialog: { value, label, tone? }.
- `faq?: FaqItem[]` = "ROADMAP_FAQ": The questions under the board.
- `labels?: Partial<RoadmapPageLabels>` = "DEFAULT_ROADMAP_PAGE_LABELS": Every visible string, including the dialog's fields and errors.
- `defaultSort?: "votes" | "recent"` = "votes": Top voted or Newest on load.
- `defaultArea?: string` = "all": The area chip selected on load: all or an area value.
- `defaultColumn?: "now" | "next" | "later" | "shipped"` = "now": The column the tabs open on below 1024px.
- `showSearch?: boolean` = true: The search field.
- `showSort?: boolean` = true: The Top voted / Newest switch.
- `showAreas?: boolean` = true: The area chips.
- `showDescriptions?: boolean` = true: The two or three lines under each card title.
- `showFaq?: boolean` = true: The How we use this roadmap questions.
- `showCta?: boolean` = true: The closing Missing something? section.
- `header?: boolean` = true: The sticky marketing header; turn it off when the page sits in a site layout.
- `footer?: boolean` = true: The marketing footer.
- `changelogHref?: string` = "/changelog": The See what shipped buttons, and the base of each shipped card's release link (/changelog#v3-0).
- `updatedAt?: string` = "2026-10-06": ISO date of the last review, shown under the stats as Updated October 6, 2026; empty hides it.
- `onVote?: (id: string, voted: boolean) => (void | Promise<unknown>)`: Saves a vote. The count changes at once; a rejected promise puts it back and says so.
- `onSuggest?: (suggestion: RoadmapSuggestion) => (void | Promise<unknown>)`: Sends a suggestion { title, description, area }. A returned promise keeps the submit button loading, a rejection shows an error. Without it the dialog waits 900 ms and succeeds.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Pressed vote pills, the selected area chip, the sort switch and the column tabs.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Suggest a feature buttons, the dialog's submit and the header's Get started.
- `radius?: "sm" | "md" | "lg"` = "md": Card radius 12, 16 or 24px; the columns follow with 8px more.
- `animateIn?: boolean` = true: The heading and toolbar rise in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for vote counts and the updated date; default the UIProvider's locale.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `faqProps?: Partial<FaqSectionProps>`: Passed to FaqSection, spread last.
- `ctaProps?: Partial<CtaSectionProps>`: Passed to CtaSection, spread last.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app); default the LinkProvider's.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<RoadmapPageSlot, string>>`: Classes for intro, toolbar, areas, tabs, board, column, card, vote, faq, cta and suggest (the dialog).

Parts:
- `RoadmapCard` (component): One idea: the area tag, a status badge, title, description, the upvote pill, the comment count and the target or the release link. Takes article props.
- `ROADMAP_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal"].
- `RoadmapPageDesign` (type): "classic" | "minimal".
- `ROADMAP_STATUSES` (constant): The columns in order: ["now", "next", "later", "shipped"].
- `ROADMAP_STATUS_TONES` (constant): The dot and badge tone of each column: Now info, Next warning, Later neutral, Shipped success.
- `roadmapChangelogHref` (function): roadmapChangelogHref(item, "/changelog") gives the release link of a shipped idea: its href, or /changelog#v<version>.
- `ROADMAP_ITEMS` (constant): Twenty sample Acme ideas, five per column.
- `ROADMAP_AREAS` (constant): Planning, Docs, Automations, Insights, Integrations and Mobile.
- `ROADMAP_FAQ` (constant): Four questions about how the roadmap works.
- `DEFAULT_ROADMAP_PAGE_LABELS` (constant): The English strings.
- `RoadmapItem` (type): { id, title, description, area, status, votes, comments, updatedAt, eta?, version?, href?, voted?, review? }.
- `RoadmapArea` (type): { value, label, tone? }.
- `RoadmapSuggestion` (type): { title, description, area }: what the dialog sends.
- `RoadmapStatus` (type): "now" | "next" | "later" | "shipped".
- `RoadmapPageProps` (type): Props of RoadmapPage.

```tsx
// app/(marketing)/roadmap/page.tsx
"use client"

import Link from "next/link"
import { RoadmapPage } from "@/components/templates/roadmap-page"
import { ROADMAP_ITEMS } from "@/components/templates/roadmap-page-data"

export default function RoadmapRoute() {
  return (
    <RoadmapPage
      linkComponent={Link}
      items={ROADMAP_ITEMS}
      onVote={(id, voted) =>
        fetch(`/api/roadmap/${id}/vote`, { method: voted ? "POST" : "DELETE" }).then((res) => {
          if (!res.ok) throw new Error("Vote failed")
        })
      }
      onSuggest={(suggestion) =>
        fetch("/api/roadmap/suggestions", { method: "POST", body: JSON.stringify(suggestion) })
      }
    />
  )
}
```

Docs: https://wingo-ui.com/templates/roadmap-page (Markdown: https://wingo-ui.com/templates/roadmap-page.md)

#### Security Page (`security-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add security-page`

A SaaS trust center: drawn compliance seals, security practices, uptime, subprocessors, a report request form and disclosure.

The hero rises in once on mount beside a drawn trust overview (compliance seals, passing checks, the last pen test and an audit log entry); its buttons jump to the report form and the status page. A row of chips under the hero jumps to each section (it scrolls sideways on phones). Four compliance cards carry a drawn seal and a status badge (Certified, Compliant, Ready, In progress). The uptime panel shows the average for the period and a daily bar: hover, tap or arrow through the days to read each one's uptime and note; View the status page links to /status. The subprocessor list filters by region (All, US, EU, Global) with a live count; it is a table from 768px and a stack of cards on phones. The report form checks the work email (free mail is refused, also as soon as you leave the field), the company and the NDA box, focuses the first problem, spins while onRequestReport runs, then turns into a Check your inbox panel with Request for another email. The disclosure email has a copy button with a check and an announcement. FAQ answers open one at a time. Reduced motion keeps everything still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, feature-grid, faq-section, badge, button, checkbox, copy-button, field, input, segmented-control, table, tracker, navigation, motion, tones, ui-config

Props:
- `design?: "classic" | "minimal" | "bold"` = "classic": The whole page's look. classic follows the layout props; minimal: a transparent header, a centered hero without the visual, flat cards under hairlines, a feature list, no gray bands, the form right on the page and a simple footer; bold: a pill header, a split hero on a gradient mesh with heavy type, solid jump chips, the compliance cards on an inverted band, huge uptime figures, floating cards, FAQ cards and a wordmark footer. The *Props overrides still win.
- `certifications?: SecurityCertification[]` = "SECURITY_CERTIFICATIONS": { id, name, code, sub?, shape?, status, description, detail? }; shape is circle, hexagon, stars or shield and status certified, compliant, ready or in-progress.
- `practices?: FeatureGridItem[]` = "SECURITY_PRACTICES": { icon?, title, description, href?, badge? } security practices.
- `subprocessors?: SecuritySubprocessor[]` = "SECURITY_SUBPROCESSORS": { name, purpose, data, location, region }; region is the short code the filter uses (US, EU, Global).
- `uptime?: SecurityUptimeDay[]` = "SECURITY_UPTIME": { date, status, uptime, note? } per day, oldest first; status is ok, degraded, down or maintenance.
- `uptimeFacts?: SecurityUptimeFact[]` = "SECURITY_UPTIME_FACTS": { value, label } figures under the uptime bar; an empty array hides them.
- `reportDocuments?: SecurityReportDocument[]` = "SECURITY_REPORT_DOCUMENTS": { title, description } documents listed beside the report form.
- `disclosure?: SecurityDisclosure` = "SECURITY_DISCLOSURE": { email, inScope, outOfScope, response: { value, label }[], reward? } for the disclosure section.
- `overview?: SecurityOverview` = "SECURITY_OVERVIEW": The strings of the drawn hero visual: { title, status, checks, lastTest, lastTestNote, activity: { who, what, when } }.
- `faq?: FaqItem[]` = "SECURITY_FAQ": { question, answer } pairs.
- `labels?: Partial<SecurityPageLabels>` = "DEFAULT_SECURITY_PAGE_LABELS": Every visible string: headings, the jump chips, statuses, table headers, form fields and errors, success copy.
- `heroLayout?: "split" | "centered"` = "split": The hero copy beside the drawn trust overview, or centered over it. Applies to the classic design.
- `uptimeDays?: 30 | 60 | 90` = "90": How many of the latest days the uptime bar and average cover.
- `defaultRegion?: string` = "all": The subprocessor filter on load: all or a region code from the data.
- `requireWorkEmail?: boolean` = true: The report form refuses free mail domains (gmail.com, outlook.com...).
- `onRequestReport?: (values: SecurityReportValues) => (void | Promise<unknown>)`: Called with { email, company, nda } once the form is valid. A returned promise keeps the button loading; a rejection shows labels.failed. Without it the form waits 900 ms and confirms.
- `statusHref?: string` = "/status": The hero's second button and View the status page.
- `ndaHref?: string` = "/legal/terms": Read the mutual NDA, under the report form.
- `policyHref?: string` = "/docs/security/disclosure": Read the disclosure policy.
- `showJumpLinks?: boolean` = true: The row of section chips under the hero.
- `showCertifications?: boolean` = true: The compliance cards.
- `showPractices?: boolean` = true: The security practices grid.
- `showUptime?: boolean` = true: The uptime summary.
- `showSubprocessors?: boolean` = true: The subprocessor list.
- `showReport?: boolean` = true: The security report request form.
- `showDisclosure?: boolean` = true: The responsible disclosure section.
- `showFaq?: boolean` = true: The FAQ.
- `alternate?: boolean` = true: Gray bands on every other visible section. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The seals, the hero glow and visual, icon tiles, the document icons and the NDA box.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Get started, the hero's primary button and Request the report; brand is the marketing orange.
- `radius?: "none" | "sm" | "md" | "lg" | "full"` = "md": The corners of the report form fields.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `heroProps?: Partial<HeroSectionProps>`: Overrides for the HeroSection (media, background, hrefs...).
- `practicesProps?: Partial<FeatureGridProps>`: Overrides for the practices FeatureGrid (layout, columns, card...).
- `faqProps?: Partial<FaqSectionProps>`: Overrides for the FaqSection (layout, searchable...).
- `animateIn?: boolean` = true: The hero rises in once on mount; false keeps it still (thumbnails). Reduced motion always does.
- `locale?: string` = "en-US": Intl locale for the uptime figures and the day tooltips.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the page (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<SecurityPageSlot, string>>`: Classes for header, hero, jump, certifications, certification, practices, uptime, subprocessors, report, form, success, disclosure, faq and footer.

Parts:
- `SecuritySeal` (component): A compliance badge drawn in code: a stamp in the tone with the code and a small line on top.
- `SECURITY_PAGE_SAMPLE` (constant): All the sample content in one object.
- `SECURITY_CERTIFICATIONS` (constant): SOC 2 Type II, ISO/IEC 27001, GDPR and HIPAA.
- `SECURITY_PRACTICES` (constant): Encryption, SSO and SAML, audit logs, data residency, backups and penetration testing.
- `SECURITY_SUBPROCESSORS` (constant): Eight vendors across the US, the EU and a global edge network.
- `SECURITY_UPTIME` (constant): 90 days of uptime ending Oct 8, 2026, with two slowdowns, one short outage and two maintenance windows.
- `SECURITY_UPTIME_FACTS` (constant): Three reliability figures.
- `SECURITY_REPORT_DOCUMENTS` (constant): The four documents in the security package.
- `SECURITY_DISCLOSURE` (constant): The disclosure email, scope, response times and reward.
- `SECURITY_OVERVIEW` (constant): The strings of the drawn hero visual.
- `SECURITY_FAQ` (constant): Six questions about data location, access, AI, DPA and BAA, the report and cancelling.
- `DEFAULT_SECURITY_PAGE_LABELS` (constant): The English strings.
- `SECURITY_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "minimal", "bold"].
- `SecurityPageProps` (type): Props of SecurityPage.
- `SecurityPageDesign` (type): "classic" | "minimal" | "bold".
- `SecurityPageLabels` (type): The strings labels can override.
- `SecurityReportValues` (type): { email, company, nda } passed to onRequestReport.
- `SecurityCertification` (type): One compliance card.
- `SecuritySubprocessor` (type): One subprocessor row.
- `SecurityUptimeDay` (type): One day of uptime.
- `SecurityDisclosure` (type): The disclosure section's content.

```tsx
// app/(marketing)/security/page.tsx
"use client"

import Link from "next/link"
import { SecurityPage } from "@/components/templates/security-page"

export default function SecurityRoute() {
  return (
    <SecurityPage
      linkComponent={Link}
      onRequestReport={async (values) => {
        const response = await fetch("/api/security-report", { method: "POST", body: JSON.stringify(values) })
        if (!response.ok) throw new Error("Could not send the report")
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/security-page (Markdown: https://wingo-ui.com/templates/security-page.md)

#### Solutions Page (`solutions-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add solutions-page`

A use-case page per team with a switcher that swaps the hero, drawn app screen, before and after, steps, templates, quotes and numbers.

A team switcher over the hero (Product, Engineering, Marketing, Agencies) swaps the whole page in place: the hero copy rises in again beside a new drawn Acme screen (a roadmap board, a sprint list with a burndown, a campaign calendar or a client table), and every section below follows. Arrow keys move along the switcher; on phones it scrolls sideways if the labels do not fit, and screen readers hear which team is showing. Before and after rows pair each pain point with what changes, side by side on desktop and stacked with an arrow on phones. The steps, template cards (each one link to sign up with that template), customer quotes, numbers (they roll up the first time they scroll into view) and integration tiles (each one link) belong to the chosen team, and the closing band links to sign-up and sales. Sections alternate between plain and gray bands. Reduced motion keeps everything still.

npm: lucide-react
Wingo UI dependencies: marketing-section, marketing-header, marketing-footer, hero-section, steps-section, testimonials-section, stats-section, cta-section, avatar, segmented-control, use-controllable-state, navigation, tones, ui-config

Props:
- `teams?: SolutionTeam[]` = "SOLUTION_TEAMS": One object per team: { id, label, name, icon?, path, title, description, screen, mockupLabel, painPoints, steps, templates, testimonials, stats, integrations, copy }. screen draws the hero app (kind board, list, calendar or table); copy holds the section titles that change with the team.
- `defaultTeam?: string` = "product": The team shown on load (uncontrolled).
- `team?: string`: The shown team's id (controlled); pair it with onTeamChange.
- `onTeamChange?: (id: string, team: SolutionTeam | undefined) => void`: Fires when the switcher picks a team; push team.path to the router here so the address follows.
- `labels?: Partial<SolutionsPageLabels>` = "DEFAULT_SOLUTIONS_PAGE_LABELS": Every visible string: the switcher, the section eyebrows and descriptions, the before and after headings and the CTA buttons.
- `design?: "classic" | "bold" | "editorial"` = "classic": The whole page's look. classic follows the layout props; bold: a pill header, a larger switcher, a split hero on a gradient mesh with heavy type, inverted outcome cards, step tabs with a large visual, bigger template and integration tiles, a numbers band, a quote grid, an image band and a wordmark footer; editorial: a centered header, a magazine hero with the team's numbers as key facts and no mockup, start-aligned headings with small caps eyebrows, hairlines between sections, ruled before and after rows, a step timeline, template rows without previews, one large quote at a time and a centered footer. The *Props overrides still win.
- `heroLayout?: "split" | "centered" | "stacked"` = "split": split: copy beside the drawn screen; centered: copy over it (the switcher centers too); stacked: title and copy side by side over it. Applies to the classic design.
- `stepsLayout?: "horizontal" | "vertical" | "cards" | "tabs"` = "cards": How it works as numbered tiles with drawn visuals, a numbered row, a timeline rail, or a step picker beside a large visual. Applies to the classic design.
- `ctaVariant?: "inverted" | "soft" | "split"` = "inverted": The closing band: a solid band, a gray band, or copy beside the buttons on a raised panel. Applies to the classic design.
- `showSwitcher?: boolean` = true: The team switcher over the hero; off for a page per team at its own path.
- `showPains?: boolean` = true: The before and after rows.
- `showSteps?: boolean` = true: How it works.
- `showTemplates?: boolean` = true: The team's template cards.
- `showTestimonials?: boolean` = true: The customer quotes.
- `showStats?: boolean` = true: The numbers.
- `showIntegrations?: boolean` = true: The integration tiles and the link to all of them.
- `showCta?: boolean` = true: The closing call to action.
- `alternate?: boolean` = true: Gray bands on every other visible section. Applies to the classic and bold designs.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Accents across the page: the hero glow and drawn screen, checks, step markers, template icons and previews, quote stars and numbers.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": Get started, the hero's primary button and the closing band; brand is the marketing orange.
- `header?: boolean` = true: The marketing header; off inside a site layout.
- `footer?: boolean` = true: The marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `heroProps?: Partial<HeroSectionProps>`: Overrides for the HeroSection (media, background, hrefs...).
- `stepsProps?: Partial<StepsSectionProps>`: Overrides for the StepsSection (layout, marker, showVisuals...).
- `testimonialsProps?: Partial<TestimonialsSectionProps>`: Overrides for the TestimonialsSection.
- `statsProps?: Partial<StatsSectionProps>`: Overrides for the StatsSection (variant, size...).
- `ctaProps?: Partial<CtaSectionProps>`: Overrides for the CtaSection (newsletter, checklist, hrefs...).
- `animateIn?: boolean` = true: The hero rises in on mount and after each team switch, and the numbers roll up; false keeps the page still (thumbnails). Reduced motion always does.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link on the page (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<SolutionsPageSlot, string>>`: Classes for header, switcher, hero, pains, painPoint, steps, templates, template, testimonials, stats, integrations, integration, cta and footer.

Parts:
- `SolutionMockup` (component): The drawn Acme screen in a browser frame, from a SolutionScreen; themes itself and folds with its own width.
- `SOLUTION_TEAMS` (constant): The four sample teams, in switcher order.
- `PRODUCT_SOLUTION` (constant): Acme for product teams: a roadmap board, feedback to release steps, roadmap and spec templates.
- `ENGINEERING_SOLUTION` (constant): Acme for engineering teams: a sprint list with a burndown, GitHub sync, sprint and postmortem templates.
- `MARKETING_SOLUTION` (constant): Acme for marketing teams: a campaign calendar, brief and review steps, calendar and report templates.
- `AGENCIES_SOLUTION` (constant): Acme for agencies: a client table with budgets, client portal and retainer templates.
- `DEFAULT_SOLUTIONS_PAGE_LABELS` (constant): The English strings.
- `SOLUTIONS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "editorial"].
- `SolutionsPageProps` (type): Props of SolutionsPage.
- `SolutionsPageDesign` (type): "classic" | "bold" | "editorial".
- `SolutionsPageLabels` (type): The strings labels can override.
- `SolutionsPageSlot` (type): The classNames keys: header, switcher, hero, pains, painPoint, steps, templates, template, testimonials, stats, integrations, integration, cta and footer.
- `SolutionMockupProps` (type): Props of SolutionMockup: div props plus screen, tone and label.
- `SolutionTeam` (type): Everything the page says about one team.
- `SolutionScreen` (type): The hero's drawn screen: a board, an issue list with a chart, a week calendar or a client table.
- `SolutionScreenCard` (type): { title, tag, tone, meta, progress? } one card on the drawn board.
- `SolutionTeamCopy` (type): The section titles that change with the team: pains, steps, templates, testimonials, stats and the closing band.
- `SolutionPainPoint` (type): { before, after, detail? } one row of the before and after.
- `SolutionTemplate` (type): { name, description, icon?, href, uses?, preview } one template card.
- `SolutionTemplatePreview` (type): "board" | "doc" | "list" | "calendar" | "chart" | "table" the small drawing on a template card.
- `SolutionIntegration` (type): { name, description, letter?, color, href } one integration tile.

```tsx
// app/(marketing)/solutions/[team]/page.tsx
"use client"

import Link from "next/link"
import { useParams, useRouter } from "next/navigation"
import { SolutionsPage } from "@/components/templates/solutions-page"

export default function SolutionsRoute() {
  const { team } = useParams<{ team: string }>()
  const router = useRouter()
  return (
    <SolutionsPage
      linkComponent={Link}
      ctaTone="brand"
      team={team}
      // the switcher keeps the address in step without a full reload
      onTeamChange={(id, next) => router.replace(next?.path ?? `/solutions/${id}`, { scroll: false })}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/solutions-page (Markdown: https://wingo-ui.com/templates/solutions-page.md)

#### Status Page (`status-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add status-page`

A public status page like status.acme.com: an overall banner, components with 90-day uptime bars, open incidents, maintenance and history.

The banner sums up every component: green All systems operational, amber Some systems degraded or Partial outage, red Major outage, blue Maintenance in progress (or whatever overall forces). An open incident sits inside the banner with its updates as a timeline (Investigating, Identified, Monitoring, Resolved), newest first. A scheduled maintenance card counts down to its start, then to its end while it runs, and disappears once it is over. Each component row shows its state and a bar of daily blocks: hover a block (or tap it on a phone, then drag sideways to scrub) to read the date, the uptime and what happened; with the keyboard, Tab to a bar and use the arrow keys. Desktop shows 90 days, phones the last 30, each with the average uptime. Past incidents are grouped by day for the last week; Show updates opens an incident's full timeline. Subscribe in the header opens a popover (a bottom sheet on phones) with a validated email signup that spins, then confirms, plus RSS, webhook and calendar links. Every time is shown in timeZone (UTC by default). The page rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-header, marketing-footer, marketing-section, button, countdown, popover, timeline, tracker, motion, navigation, tones, ui-config

Props:
- `simulate?: "operational" | "degraded" | "outage"` = "operational": Which sample data set fills the page when groups, incidents and maintenance are left out: everything up, one incident on Realtime sync, or an API outage.
- `groups?: StatusComponentGroup[]`: { id, name, components }; each component has id, name, description, state and a daily history (oldest first).
- `incidents?: StatusIncident[]`: { id, title, impact, components, updates }; updates newest first, open until the newest is resolved.
- `maintenance?: StatusMaintenance[]`: { id, title, description, startsAt, endsAt, components }; hidden once endsAt has passed.
- `updatedAt?: string` = "": ISO time of the last refresh, shown in the banner; the incident history counts back from its day. Empty uses the sample's.
- `overall?: "auto" | "operational" | "degraded" | "partial" | "major" | "maintenance"` = "auto": Forces the banner; auto derives it from the worst component state.
- `historyDays?: number` = 7: Days of incident history, newest first (days without incidents say so).
- `showMaintenance?: boolean` = true: The scheduled maintenance card with its countdown.
- `showHistory?: boolean` = true: The past incidents section.
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic: a soft status banner and raised cards; bold: a pill header, the status as a solid band in its color with large heavy type, taller uptime bars, big rounded cards, incidents with a colored side bar and a wordmark footer; minimal: a transparent header, the status as a dot and a title over a hairline, dense flat rows between hairlines, no cards, past incidents on a thin side rule. headerProps, footerProps and classNames still win.
- `showLegend?: boolean` = true: The color legend next to the Components heading.
- `trackerSize?: "sm" | "md"` = "sm": Height of the uptime bars: 24 or 32px. Applies to the classic and minimal designs; bold uses md.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Subscribe button and the signup button in its popover.
- `header?: boolean` = true: The minimal header: logo, Visit acme.com and Subscribe. Without it Subscribe moves into the banner.
- `footer?: boolean` = true: The simple footer, its status dot matching the banner.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader over the status defaults (no links, custom actions).
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `onSubscribe?: (email: string) => (void | Promise<unknown>)`: The email signup; a returned promise keeps the button loading, a rejection shows an error. Without it the form waits 900 ms and succeeds.
- `timeZone?: string` = "UTC": IANA zone for every time on the page (also keeps server and browser output identical).
- `locale?: string` = "en-US": Intl locale for dates, times and percentages.
- `animateIn?: boolean` = true: The page rises in once on mount; off in thumbnails.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for every link (next/link in an app).
- `labels?: Partial<StatusPageLabels>`: Every visible string; English defaults in DEFAULT_STATUS_PAGE_LABELS.
- `hrefs?: Partial<StatusPageHrefs>`: home, site, history, rss, webhooks, calendar, support, help and docs.
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<StatusPageSlot, string>>`: Classes for banner, incident, maintenance, components, group, component, history and subscribe.

Parts:
- `deriveOverall` (function): The overall state of a list of groups: the worst component state (major, partial, degraded, maintenance, operational).
- `isIncidentOpen` (function): True while an incident's newest update is not resolved.
- `STATUS_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `StatusPageDesign` (type): "classic" | "bold" | "minimal".
- `STATUS_PAGE_SCENARIOS` (constant): The three sample data sets keyed by scenario: operational, degraded and outage.
- `STATUS_PAGE_SAMPLE` (constant): The operational data set: seven components in three groups, two past incidents and one maintenance window.
- `DEFAULT_STATUS_PAGE_LABELS` (constant): The English strings.
- `StatusPageData` (type): { updatedAt, groups, incidents, maintenance }.
- `StatusComponentGroup` (type): { id, name, components }.
- `StatusComponent` (type): { id, name, description?, state, history: StatusDay[] }.
- `StatusDay` (type): { date, status: ok | degraded | down | maintenance | none, uptime, note? }.
- `StatusIncident` (type): { id, title, impact: minor | major | critical, components, updates }.
- `StatusIncidentUpdate` (type): { stage: investigating | identified | monitoring | resolved, message, at }.
- `StatusMaintenance` (type): { id, title, description, startsAt, endsAt, components }.
- `StatusPageProps` (type): Props of StatusPage.

```tsx
// app/status/page.tsx
import Link from "next/link"
import { StatusPage } from "@/components/templates/status-page"
import type { StatusPageData } from "@/components/templates/status-page-data"

export const revalidate = 60

// your monitoring backend, shaped as StatusPageData
async function getStatus(): Promise<StatusPageData> {
  const response = await fetch("https://monitor.acme.com/v1/status")
  return response.json()
}

export default async function StatusRoute() {
  const status = await getStatus()
  return (
    <StatusPage
      linkComponent={Link}
      groups={status.groups}
      incidents={status.incidents}
      maintenance={status.maintenance}
      updatedAt={status.updatedAt}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/status-page (Markdown: https://wingo-ui.com/templates/status-page.md)

#### Waitlist Page (`waitlist-page`)

block · Pro · v1.0.0 · install: `npx wingo-ui@latest add waitlist-page`

A pre-launch page: a launch countdown, an email signup with social proof, your place in line with a referral link, teasers and FAQ.

The countdown ticks down to launchAt (it shows a "live" note when the moment passes; without launchAt the page is a plain coming soon page). Pick an optional role (a bottom sheet on phones), type an email and press Join the waitlist or Enter: a bad address shows an inline error, the button spins while onJoin runs, then the form turns into your place in line ("You're #4,813") with a referral link you can copy in one tap and buttons to share it on X, LinkedIn or by email (plus the system share sheet where the browser has one). "Use a different email" goes back to the form. The FAQ is an accordion: Enter or Space opens a question, arrow keys move between them. The split layout puts a phone drawn in code next to the copy; below 1024px it moves under the copy. The header keeps only the logo and Sign in, also on phones. The hero rises in once on mount; reduced motion keeps it still.

npm: motion, lucide-react
Wingo UI dependencies: marketing-section, cta-section, marketing-header, marketing-footer, accordion, avatar, button, copy-button, countdown, select, navigation, motion, tones, ui-config

Props:
- `launchAt?: Date | number | string | null` = "WAITLIST_PAGE_SAMPLE.launchAt": The launch moment for the countdown and the pill ("Launching November 17"); null leaves a coming soon page without a date.
- `now?: Date | number`: Pins the countdown's clock (screenshots, SSR); default the live clock.
- `count?: number` = 4812: People already on the list: the social proof line and the default position (count + 1).
- `people?: string[]` = "WAITLIST_PAGE_SAMPLE.people": Names for the initials stack next to the count.
- `roles?: WaitlistRoleOption[]` = "WAITLIST_PAGE_SAMPLE.roles": { value, label } options for the optional role select; an empty list hides it.
- `features?: WaitlistFeature[]` = "WAITLIST_PAGE_SAMPLE.features": { icon?, title, description } teasers under the hero.
- `faqs?: WaitlistFaq[]` = "WAITLIST_PAGE_SAMPLE.faqs": { question, answer } pairs for the FAQ accordion.
- `socials?: MarketingFooterSocial[]` = "MARKETING_FOOTER_SOCIALS": { label, href, icon } links of the Follow the build band.
- `referralUrl?: string` = "https://acme.com/mobile?ref=": The referral link is this plus the person's code.
- `spotsPerReferral?: number` = 10: Spots a person moves up per friend who joins, shown on the success card.
- `labels?: Partial<WaitlistPageLabels>` = "DEFAULT_WAITLIST_PAGE_LABELS": Every visible string; labels.form passes strings to the email form.
- `hrefs?: Partial<WaitlistPageHrefs>`: signIn: where the header's Sign in goes (default /sign-in).
- `design?: "classic" | "bold" | "minimal"` = "classic": The whole page's look. classic follows layout and background; bold: a pill header, the split hero with the phone on a gradient mesh, heavy display type, an inverted pill, large solid countdown tiles, big feature cards with solid icon tiles on a gray band, a start-aligned FAQ, a closing signup card in place of the socials row and a wordmark footer; minimal: a transparent header, a centered hero with no glow and more air, a plain pill, small outlined countdown tiles, features without cards, no gray band, ghost social buttons and a simple footer. headerProps, footerProps and classNames still win.
- `layout?: "centered" | "split"` = "centered": centered: one column; split: copy on the left and a phone drawn in code on the right. Applies to the classic design.
- `background?: "glow" | "grid" | "plain"` = "glow": Behind the hero: a soft light from the top in the tone, faint fading grid lines, or nothing. Applies to the classic design.
- `tone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The glow, the pill's dot, the phone's accents and the success tick.
- `ctaTone?: "neutral" | "brand" | "success" | "warning" | "danger" | "info"` = "neutral": The Join the waitlist button; brand is the marketing orange.
- `showCountdown?: boolean` = true: The countdown and the launch date in the pill.
- `showRole?: boolean` = true: The optional role select above the email field.
- `showSocialProof?: boolean` = true: The initials stack and "Join 4,812 people on the waitlist".
- `showFeatures?: boolean` = true: The three teaser cards.
- `showFaq?: boolean` = true: The FAQ accordion.
- `showSocials?: boolean` = true: The Follow the build band with social links (the bold design shows a closing signup card instead).
- `header?: boolean` = true: The minimal marketing header (logo and Sign in); off inside a site layout.
- `footer?: boolean` = true: The simple marketing footer.
- `headerProps?: Partial<MarketingHeaderProps>`: Passed to MarketingHeader; items brings the full navigation back.
- `footerProps?: Partial<MarketingFooterProps>`: Passed to MarketingFooter.
- `defaultJoined?: WaitlistJoined | boolean` = false: Opens on the success state; true uses a sample email and count + 1.
- `onJoin?: (entry: WaitlistEntry) => (WaitlistJoinResult | Promise<WaitlistJoinResult>)`: Adds the person; a promise keeps the button loading and may resolve { position, referralCode }; a rejection shows an error. Without it the page waits 900 ms and lands on count + 1.
- `animateIn?: boolean` = true: The hero rises in once on mount; off in thumbnails and under reduced motion.
- `locale?: string` = "en-US": Intl locale for the count, the position and the launch date.
- `linkComponent?: (props: LinkComponentProps) => ReactNode` = "<a>": The router link for the header, footer and Sign in (next/link in an app).
- `className?: string`: Classes for the root.
- `classNames?: Partial<Record<WaitlistPageSlot, string>>`: Classes for header, hero, pill, countdown, signup, socialProof, success, phone, features, faq, socials and footer.

Parts:
- `WaitlistPhone` (component): The phone drawn in code (a mini Acme Today screen with floating cards) used by the split layout. Takes div props.
- `referralCode` (function): A short, stable referral code from an email ("emma-k3f9"), the default when onJoin does not return one.
- `WAITLIST_PAGE_SAMPLE` (constant): The sample content: launchAt, count, people, roles, features, faqs and referralUrl (from waitlist-page-data.ts).
- `DEFAULT_WAITLIST_PAGE_LABELS` (constant): The English strings.
- `WAITLIST_PAGE_DESIGNS` (constant): The design names, classic first: ["classic", "bold", "minimal"].
- `WaitlistPageDesign` (type): "classic" | "bold" | "minimal".
- `WaitlistPageProps` (type): Props of WaitlistPage.
- `WaitlistJoined` (type): { email, position, referralCode }: the success state.
- `WaitlistFeature` (type): { icon?, title, description }: a teaser card.
- `WaitlistFaq` (type): { question, answer }: an FAQ entry.

```tsx
// app/(marketing)/waitlist/page.tsx
"use client"

import Link from "next/link"
import { WaitlistPage } from "@/components/templates/waitlist-page"

export default function WaitlistRoute() {
  return (
    <WaitlistPage
      linkComponent={Link}
      launchAt="2026-11-17T17:00:00Z"
      layout="split"
      onJoin={async ({ email, role }) => {
        const response = await fetch("/api/waitlist", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ email, role }),
        })
        if (!response.ok) throw new Error("Could not join")
        return (await response.json()) as { position: number; referralCode: string }
      }}
    />
  )
}
```

Docs: https://wingo-ui.com/templates/waitlist-page (Markdown: https://wingo-ui.com/templates/waitlist-page.md)

### Hooks & Utilities

#### AI Chat (`ai-chat`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add ai-chat`

The AI kit's shared vocabulary: message, tool call and model types, token and duration formatting, live timers and a mock stream.

Press Generate to stream a fake answer through mockStream: the text arrives word by word (or letter by letter with chunk char), the token estimate grows, and the elapsed time ticks in formatDuration and formatTimer. Stop aborts the stream through its signal. Below, the capability icons and the tool-call status tones every AI component uses.

npm: lucide-react
Wingo UI dependencies: number-format, relative-time, tones

API:
- `delay?: number` = 28: mockStream(text, { delay, chunk, firstDelay = 350, signal }): an async generator that yields text in chunks every `delay` ms, like a model streaming. for await (const delta of mockStream(answer, { signal })) setText((t) => t + delta). Aborting the signal ends it.
- `chunk?: "word" | "char"` = "word": mockStream: whole words with their spaces (how models stream) or one character at a time.
- `locale?: string` = "en-US": The locale passed to formatTokens and formatDuration in the demo (every formatter takes one).
- `compact?: boolean` = true: formatTokens(count, locale?, { compact = true }): 812, "12.5K", "1.3M" in en-US; compact false writes every digit ("12,480").
- `ChatMessageData?: { id; role: ChatRole; content: string; status?: ChatStatus; createdAt?; author?: ChatPerson; model?; attachments?: ChatAttachment[]; reasoning?: ChatReasoning; toolCalls?: ToolCall[]; sources?: ChatSource[]; error?; feedback?: ChatFeedback; edited?; branch?: { index; count } }`: One message of a conversation; content is markdown. ChatRole = "user" | "assistant" | "system"; ChatStatus = "pending" | "streaming" | "complete" | "stopped" | "error"; ChatFeedback = "up" | "down" | null. ChatAttachment = { id; name; type?; size?; url?; previewUrl?; status?: "uploading" | "ready" | "error"; progress? (0..1); error? }. ChatSource = { id; title; url?; snippet?; favicon? }. ChatReasoning = { content; status?; startedAt?; endedAt?; durationMs? }. ChatPerson = { id; name; avatar? }.
- `ToolCall?: { id; name; title?; description?; status: ToolCallStatus; input?; output?; error?; startedAt?; endedAt?; durationMs?; logs?: string[]; steps?: ToolCall[] }`: One tool call or agent step. ToolCallStatus = "pending" | "running" | "complete" | "error" | "canceled" | "awaiting-approval". TOOL_CALL_STATUS_TONES maps them to tones (neutral, info, success, danger, neutral, warning) and DEFAULT_TOOL_CALL_STATUS_LABELS to English words. getToolCallTitle(call) and humanizeToolName("search_invoices") give "Search invoices"; summarizeToolCalls(calls) counts total / running / complete / error / pending / awaiting, sub-steps included; stringifyToolValue(value) prints inputs and outputs (strings as they are, the rest as indented JSON).
- `AiModel?: { id; name; provider?; description?; icon?; group?; capabilities?: AiCapability[]; contextWindow?; speed?: 1 | 2 | 3; cost?: 1 | 2 | 3; pricing?: { input; output; currency? }; badge?: { label; tone? }; recommended?; isNew?; disabled?; disabledReason?; keywords? }`: A model for pickers. AiCapability = "vision" | "tools" | "reasoning" | "web" | "files" | "code" | "image" | "voice", with AI_CAPABILITIES (the order), AI_CAPABILITY_ICONS (lucide) and DEFAULT_AI_CAPABILITY_LABELS. Pricing is per 1M tokens.
- `ChatSuggestion?: { id; label; prompt?; description?; icon?; group? }`: A suggested prompt; prompt defaults to label.
- `estimateTokens?: (text: string) => number`: A fast estimate for hints and meters: about 4 characters per token for Latin text, one per CJK character. Real counts come from the provider.
- `formatDuration?: (ms: number, { locale?, style?: "long" | "short" | "narrow" }) => string`: "2.4 sec", "42 sec", "2 min, 5 sec", "1 hr, 12 min" in en-US: tenths below 10 s, then at most two whole units, through Intl unit formatting.
- `formatTimer?: (ms: number) => string`: A stopwatch: "0:42", "12:05", "1:02:03" (recordings, an agent's run time).
- `getElapsed?: ({ startedAt?, endedAt?, durationMs? }, now?) => number | null`: ms of a reasoning block, tool call or run: durationMs if given, else end (or now while running) minus start; null when the start is unknown.
- `useTicker?: (running: boolean, interval = 1000) => number | null`: A clock for live timers that ticks only while running and shares one interval per step across components. null on the server and during hydration (show nothing or the final duration), then Date.now() rounded to the step.
- `createChatId?: (prefix = "msg") => string`: A unique id for messages, attachments and calls created in the browser. Call it in handlers, never during render.

```tsx
"use client"

import { useState } from "react"
import { estimateTokens, formatTokens, mockStream } from "@/lib/ai-chat"
import { Button } from "@/components/ui/button"

export function FakeAnswer() {
  const [text, setText] = useState("")

  const generate = async () => {
    setText("")
    for await (const delta of mockStream("You have 3 overdue invoices, $22,775.95 in total.")) setText((t) => t + delta)
  }

  return (
    <div className="flex flex-col gap-3">
      <Button onClick={generate}>Generate</Button>
      <p>{text}</p>
      <span className="text-xs text-muted-foreground">{formatTokens(estimateTokens(text), "en-US")} tokens</span>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/ai-chat (Markdown: https://wingo-ui.com/components/ai-chat.md)

#### Chart kit (`chart-kit`)

lib · Pro · v1.0.2 · install: `npx wingo-ui@latest add chart-kit`

The parts every chart is built from: palette, formatters, a measuring container, axes, crosshair, tooltip, legend and data table.

The demo is a small line chart assembled from the kit. Move the mouse over it for a crosshair and a tooltip that flips near the right edge. On a phone, tap a month to pin the readout above your finger, drag sideways to scrub (vertical drags still scroll the page), tap the same month again or anywhere outside to clear it. With the keyboard, Tab to the chart, then Left / Right walk the months, Home / End jump to the ends, PageUp / PageDown move by ten, Escape clears; a live region reads each point. Click or tap a legend entry to hide or show its series, hover or focus one to highlight it.

npm: motion, d3-scale, d3-shape
Wingo UI dependencies: use-controllable-state, use-media-query, motion, number-format, tones

API:
- `valueFormat?: "number" | "compact" | "currency" | "percent"` = "currency": ChartFormatOptions.format in the demo: how values print in the tooltip, the ticks and the table.
- `locale?: string` = "en-US": The demo's locale for numbers and dates. Charts resolve theirs with useLocale.
- `curve?: "monotone" | "linear" | "natural" | "step"` = "monotone": ChartCurve passed to getCurve for the lines and areas.
- `tooltipMode?: "auto" | "float" | "fixed"` = "auto": ChartTooltip mode: float beside the crosshair, fixed above the plot (the touch default), auto picks by pointer.
- `height?: number` = 240: ChartContainer height in px (reserved before measuring, so nothing shifts).
- `showGrid?: boolean` = true: Draws ChartGrid hairlines at the value ticks.
- `animated?: boolean` = true: ChartContainer animated: marks draw in when the chart scrolls into view.
- `loading?: boolean` = false: ChartContainer loading: a skeleton in the plot's shape (loadingShape bars | line | donut | gauge | grid).
- `empty?: boolean` = false: The demo passes no data: ChartContainer empty shows ChartEmpty with labels.empty.
- `ChartContainer?: { height?: number | string = 240; surface?: string = "var(--surface)"; animated?: boolean = true; loading?; loadingShape?; empty?; emptyState?; labels?: Partial<ChartLabels>; table?; header?; footer?; children: (size: { width; height }) => ReactNode } & div props`: The figure (role figure, aria-label from props): sets the palette vars and --chart-surface, measures its width, reserves the height before measuring, renders loading / empty in the same box, and always renders the table (so it is in the server html). useChart() inside gives { width, height, reduced, touch, revealed, animated }.
- `CHART_PALETTE / SERIES_COLORS / resolveChartColor / seriesColor / tint?: string / string[] / (color?: string, index?: number) => string`: Eight categorical slots (--series-1..8), light and dark steps, colorblind-checked in this order. resolveChartColor accepts "series-3", a tone ("success", "neutral" = the foreground ink) or any css color; without one, the slot of the series' position. Past eight series the color is --series-other (gray), never a cycled hue.
- `formatChartValue / formatChartTick / formatChartLabel / parseChartDate?: (value, { format?, currency? = "RON", decimals?, locale? }) => string`: Values ("$128,450", "12.4%" from 12.4), short ticks ("$128K", "1.3M"), x labels (iso days "Sep 24" on the axis, "Sep 24, 2026" in the tooltip; iso months "Sep" / "September 2026"). Iso dates parse as local calendar dates.
- `useChartSeries?: ({ series?, data, xKey, hiddenSeries?, defaultHiddenSeries?, onHiddenSeriesChange? }) => { all, visible, hidden, toggle, highlighted, setHighlighted }`: Resolves series (inferred from numeric keys when omitted) with colors fixed by position, hidden state (controlled or not; the last visible series cannot be hidden) and the highlighted series for legend hover.
- `chartLayout / niceScale / valueDomain / stackData / getCurve / barPath / barPathReversed?: helpers`: The plot rectangle with room for estimated y labels and the x axis; a nice linear scale with about one tick per 56px; a domain that includes zero for bars and areas; d3 stacks (none | expand | diverging); curves; bar paths with a 4px rounded data end and a square base.
- `ChartSvg / ChartGrid / ChartBaseline / ChartReferenceLine / ChartYAxis / ChartXAxis / ChartCrosshair / ChartDot / ChartGradient?: svg parts`: The aria-hidden drawing surface, hairline grid (foreground 8%), the zero line, a dashed target / average line with a label, tick labels (11px tabular, muted), x labels thinned from the newest backwards so they never collide, the snapping crosshair, a dot ringed in the surface color, and a fading fill gradient.
- `useChartInspect / ChartInspectLayer?: ({ positions, axis?, activeIndex?, defaultActiveIndex?, onActiveIndexChange?, disabled? }) => controller; <ChartInspectLayer controller label announcement hint />`: One inspector for every chart: hover (mouse), tap and scrub (touch, touch-action pan-y), arrows / Home / End / PageUp / PageDown / Escape (keyboard, after a visible focus). The layer is a focusable html element over the plot with a live region that reads the point while the keyboard drives.
- `ChartTooltip / ChartTooltipContent / ChartKey?: { x, y?, mode?: "auto" | "float" | "fixed", title?, items: ChartTooltipItem[], footer? }`: The readout: values lead (semibold, tabular), names follow (muted), keyed by a short line / square / dot. Float sits beside the crosshair and flips near the edge; fixed pins above the plot, the default on touch. Moves on springs.snappy.
- `ChartLegend?: { items: ChartLegendItem[]; shape?; align?; orientation?; onToggle?; onHighlight?; highlighted?; labels? }`: Keys for two or more series, optional trailing values, toggle buttons (aria-pressed) that hide a series, hover / focus highlight.
- `ChartDataTable / ChartLoading / ChartEmpty / DEFAULT_CHART_LABELS?: { caption, rowHeader?, columns, rows, visible? }`: The table every chart ships (screen reader only unless visible), the skeleton per shape, the empty state, and the English default strings.
- `markTransition / DRAW_TRANSITION?: (index, { step?, max?, spring? }) => Transition`: Bars and segments grow on springs.gentle with a capped stagger; lines draw with an ease-out pathLength tween.

```tsx
import {
  ChartContainer,
  ChartSvg,
  ChartTooltip,
  ChartInspectLayer,
  chartLayout,
  niceScale,
  valueDomain,
  useChartInspect,
  formatChartValue,
} from "@/lib/chart-kit"

const data = [
  { month: "Jul", revenue: 106300 },
  { month: "Aug", revenue: 97500 },
  { month: "Sep", revenue: 128450 },
]

function Bars({ width, height }: { width: number; height: number }) {
  const layout = chartLayout({ width, height, showYAxis: false })
  const { scale: y } = niceScale(valueDomain(data.map((d) => d.revenue)), [layout.bottom, layout.top])
  const step = layout.innerWidth / data.length
  const positions = data.map((_, i) => layout.left + step * (i + 0.5))
  const inspect = useChartInspect({ positions })
  const i = inspect.activeIndex
  return (
    <>
      <ChartSvg width={width} height={height}>
        {data.map((d, index) => (
          <rect key={d.month} x={positions[index] - 12} width={24} y={y(d.revenue)} height={y(0) - y(d.revenue)} rx={4} fill="var(--series-1)" />
        ))}
      </ChartSvg>
      <ChartInspectLayer controller={inspect} label="Revenue by month" />
      <ChartTooltip
        x={i == null ? null : positions[i]}
        title={i == null ? "" : data[i].month}
        items={i == null ? [] : [{ key: "v", label: "Revenue", value: formatChartValue(data[i].revenue, { format: "currency", locale: "en-US", currency: "USD" }), color: "var(--series-1)", shape: "rect" }]}
      />
    </>
  )
}

export function RevenueBars() {
  return (
    <ChartContainer aria-label="Revenue by month" height={200}>
      {(size) => <Bars {...size} />}
    </ChartContainer>
  )
}
```

Docs: https://wingo-ui.com/components/chart-kit (Markdown: https://wingo-ui.com/components/chart-kit.md)

#### Commerce (`commerce`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add commerce`

Money for shops and marketplaces: prices written like a shop writes them, discounts, unit prices, coupons and cart totals with VAT.

Change the quantities in the cart with the minus and plus buttons: the subtotal, the savings from sale prices, the coupon, the free-delivery bar, the VAT line and the total all come from one computeCartTotals call and always add up. Pick a coupon to see it apply or explain why it does not (a minimum order shows what is still missing). The strip above shows the same prices through formatPrice, a range, a discount and a price per m² in the chosen locale and currency.
Wingo UI dependencies: number-format

API:
- `locale?: string` = "en-US": The demo's locale. Every formatter takes options.locale; pass the one from useLocale so the server and the browser agree.
- `currency?: string` = "USD": options.currency: an ISO 4217 code (the lib's own default is "USD"). Printed with the narrow symbol ("$", "€", "lei"), never Intl's "US$" or "RON".
- `fractionDigits?: "auto" | number` = "auto": options.fractionDigits: auto prints whole amounts without decimals ("$1,200") and the currency's digits otherwise ("$1,284.90"); a number forces that many.
- `coupon?: string` = "none": The demo's coupon: a percent (FALL15, capped at 150), a fixed amount (SAVE50), free shipping (FREESHIP) or one with a minimum order (MIN2000).
- `freeShippingThreshold?: number | null` = 1000: computeCartTotals options.freeShippingThreshold: spend this much on items (after coupons) and delivery is free. 0 or null turns the offer off.
- `taxRate?: number` = 21: options.taxRate as a fraction (0.21, exported as RO_VAT_RATE; RO_REDUCED_VAT_RATE is 0.11); the demo shows it in percent. Lines can override it with their own taxRate (the book below is at 11%).
- `pricesIncludeTax?: boolean` = true: options.pricesIncludeTax: true (Romanian retail) reports the VAT inside the total; false adds it on top (B2B price lists).
- `formatPrice?: (amount: number | null | undefined, options?: FormatPriceOptions) => string`: The price as text: "$1,200", "$1,284.90", "1.284,90 lei" (ro-RO), "489.000 €" (de-DE); "" for null and NaN. Options: currency, locale, fractionDigits, currencyDisplay ("narrowSymbol" | "symbol" | "code" | "name" | "none"), notation ("compact" → "$489K"), signDisplay. Thin and narrow spaces become one no-break space so server and browser print the same text.
- `formatPriceParts?: (amount, options?) => { formatted; amount; sign; currency; currencyPosition: "prefix" | "suffix"; spaced } | null`: The pieces of a price for styling, in the locale's order: "$" + "1,284.90" before it in en-US, "1.284,90" + "lei" after it with a space in ro-RO.
- `formatPriceRange?: (min, max, options?) => string`: Two prices as one range joined by a spaced en dash, with the currency written once when it follows the number (ro-RO) and on both ends otherwise (en-US); a missing end prints the other alone.
- `discountPercent / formatDiscount?: (price: number, compareAtPrice?: number | null) => number / (percent: number, locale?: string) => string`: The whole-percent saving of a sale price (1199 vs 1599 → 25; 0 without a higher old price) and its label ("-25 %" in ro-RO, "-25%" in en-US).
- `unitPrice / formatUnitPrice?: (amount, quantity) => number | null / (amount, quantity, unit: string, options?) => string`: Price per unit: $489,000 for 54 m² → "$9,056/m²" (whole units from 100 up, cents below: "$4.90/kg").
- `roundMoney?: (value: number, decimals?: number) => number`: Half away from zero without float noise: roundMoney(1.005) is 1.01. Every amount the lib returns went through it.
- `couponDiscount?: (coupon: Coupon, { subtotal, shipping? }) => { valid: true; amount } | { valid: false; reason: "min-subtotal"; missing } | { valid: false; reason: "not-applicable" }`: What one coupon takes off, or why not. Coupon = { code; type: "percent" | "fixed" | "shipping"; value; minSubtotal?; maxDiscount?; label? }. Validation of the code itself (does it exist, has it expired) is the server's job; this is the math.
- `computeCartTotals?: (lines: CartLineInput[], options?: CartTotalsOptions) => CartTotals`: The summary of a cart or a checkout. Lines are { id, price, quantity, compareAtPrice?, taxRate? }; options { coupons, shipping (null = not chosen yet), freeShippingThreshold, taxRate, pricesIncludeTax }. Returns itemCount, lineCount, subtotal, compareAtSubtotal, savings, discount, discounts[], rejectedCoupons[], shipping, shippingFree, freeShippingRemaining, freeShippingProgress (0..1), taxRate, tax and total, all rounded to cents so total equals subtotal minus discount plus shipping (plus tax when it is added).
- `DEFAULT_CURRENCY / RO_VAT_RATE / RO_REDUCED_VAT_RATE?: "USD" / 0.21 / 0.11`: The default currency (USD) and Romania's VAT rates: 21% standard since 01.08.2025, 11% for food, medicines and books.

```tsx
import { computeCartTotals, formatPrice, RO_VAT_RATE } from "@/lib/commerce"

const totals = computeCartTotals(
  [
    { id: "sofa", price: 850, quantity: 1 },
    { id: "pillows", price: 49.9, quantity: 2, compareAtPrice: 69.9 },
  ],
  { shipping: 19.99, freeShippingThreshold: 1000, taxRate: RO_VAT_RATE, coupons: [{ code: "FALL15", type: "percent", value: 15 }] },
)

formatPrice(totals.total, { locale: "en-US", currency: "USD" }) // "$827.32"
formatPrice(1200, { locale: "ro-RO" }) // "1.200 lei" (RON is the default currency)
```

Docs: https://wingo-ui.com/components/commerce (Markdown: https://wingo-ui.com/components/commerce.md)

#### Date utils (`date-utils`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add date-utils`

Locale-aware date helpers: week start, month and weekday names, typed-date parsing, day matchers, month grids and presets.

Pick a locale and the month grid reorders itself: Sunday first in en-US, Monday first in en-GB and ro-RO, Saturday first in ar-EG, with the names from Intl. Type a date the way people do (9/23, 23/9/26, tomorrow, +3) and see what it parses to. The preset list shows the usual report ranges for today.

npm: date-fns

API:
- `locale?: string` = "en-US": The demo's locale. Every helper takes an optional locale; pass the one from useLocale so server and browser agree.
- `text?: string` = "": The demo's typed date, parsed with parseDate in the locale (English keywords by default, Romanian ones such as maine when the locale is ro-RO).
- `parseDate?: (text: string, options?: { locale?: string; reference?: Date; keywords?: { today?, tomorrow?, yesterday?: string[] } }) => Date | null`: A typed date or null. The locale's field order with . / - or spaces, 1 or 2 digit day and month, a 2 digit year (nearest century) or none (this year), ISO "2026-09-23" in any locale, keywords without case or diacritics, and "+3" / "-2" for days from today. 31.02 is rejected, never rolled over.
- `getWeekStartsOn / getWeekendDays / getHourCycle?: (locale?: string) => 0..6 / (locale?) => number[] / (locale?) => "h12" | "h23"`: From Intl's week info where the browser has it, from the CLDR table where it does not (Firefox). 0 is Sunday, like date-fns.
- `getMonthNames / getWeekdayNames / formatMonthYear?: (locale?, format?) => string[] / (locale?, weekStartsOn?, format?: "long" | "short" | "min" | "narrow") => string[] / (date, locale?) => string`: Capitalized names from Intl, no bundled locale data. Weekday "min" is the calendar header look ("Su Mo Tu We Th Fr Sa"), in display order from weekStartsOn.
- `getDateOrder / autoFormatDateInput?: (locale?) => { order, separator, pattern } / (text, locale?) => string`: How a locale writes a numeric date ("dd.MM.yyyy", "MM/dd/yyyy"), and separators inserted while digits are typed ("2309" becomes "23.09.").
- `formatDate / formatDateRange / formatDayLabel?: (date, locale?, options?) => string / (range, locale?, options?) => string / (date, locale?) => string`: Numeric "23.09.2026" by default; ranges through Intl formatRange (1 to 30 sept. 2026, joined the way the locale writes ranges); the long spoken form for day buttons.
- `matchesDate / isDateUnavailable?: (date, matcher | matcher[]) => boolean / (date, { min?, max?, disabled? }) => boolean`: DateMatcher is a Date, a Date[], { from, to }, { before }, { after }, { dayOfWeek: number[] } or (date) => boolean. Calendars use these for disabled and marked days.
- `getMonthWeeks / normalizeRange / isInRange / countDays?: (month, weekStartsOn?, fixedWeeks?) => Date[][] / (range) => DateRange / (date, range) => boolean / (range) => number`: The weeks of a month grid including neighbour days (6 weeks with fixedWeeks), and range helpers (countDays counts both ends).
- `getDatePresets / getRangePresets?: (reference?) => Record<today | tomorrow | yesterday | nextWeek | nextMonth, Date> / (reference?, weekStartsOn?) => Record<last7Days | thisMonth | lastQuarter | ..., { from, to }>`: The presets pickers offer, computed from a reference day. Labels are the picker's job.
- `toISODate / toISODateTime / fromISODate?: (date) => string / (date) => string / (text) => Date | null`: "2026-09-23" and "2026-09-23T14:30" in local time for hidden form inputs (never toISOString, which can land on the previous day).
- `parseTime / formatTime / getDayPeriodLabels / setTime / getTimeOfDay / timeToMinutes / minutesToTime?: (text, { hourCycle?, seconds? }?) => "HH:mm" | null / (value, locale?, { hourCycle?, seconds? }?) => string / ...`: Times as locale-free "HH:mm" strings like <input type="time">: parseTime reads "1430", "14.30", "2:30 pm", "2p"; formatTime shows "14:30" or "2:30 PM" by locale.

```tsx
import { formatDate, getWeekStartsOn, parseDate } from "@/lib/date-utils"

const date = parseDate("9/23", { locale: "en-US" })
formatDate(date, "en-US") // "9/23/2026"
getWeekStartsOn("en-US") // 0 (Sunday)
getWeekStartsOn("ro-RO") // 1 (Monday)
```

Docs: https://wingo-ui.com/components/date-utils (Markdown: https://wingo-ui.com/components/date-utils.md)

#### File export (`file-export`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-export`

Files out of the browser: download blobs, text and JSON, turn a canvas or an SVG into a PNG, copy an image and name files consistently.

The card is an SVG. Download SVG saves it as it is, Download PNG rasterizes it at the playground scale (with the background color when one is set), Copy PNG puts the image on the clipboard (paste it into a chat or a doc), and Download JSON saves the card's data. Every file is named from the title plus the local date and time, and the readout shows the last name and size.

API:
- `scale?: number` = 2: svgToImageBlob(svg, { scale }): device pixels per CSS pixel of the PNG. 2 keeps exports sharp on retina screens and in print.
- `background?: string` = "": svgToImageBlob(svg, { background }): a fill behind the image; empty keeps the PNG transparent.
- `fileName?: string` = "Certificate Emma Carter": The base passed to timestampedFileName(base, extension): diacritics and unsafe characters are removed, the local date and time are appended.
- `downloadBlob / downloadUrl?: (blob: Blob, filename: string) => void / (url: string, filename: string) => void`: Saves a blob (through a temporary object URL, released right after) or a URL under a name. Browser only, for event handlers.
- `downloadText / downloadJson?: (text: string, filename: string, options?: { type?: string; bom?: boolean }) => void / (value: unknown, filename: string, space?: number) => void`: Saves text (a log, a diff, a VTT file) or a value as pretty JSON. bom: true prefixes a UTF-8 BOM so Excel on Windows reads diacritics.
- `canvasToBlob?: (canvas: HTMLCanvasElement, type?: "image/png" | "image/jpeg" | "image/webp", quality?: number) => Promise<Blob>`: canvas.toBlob as a promise; rejects when the canvas is tainted by a cross-origin image.
- `serializeSvg / svgToBlob?: (svg: SVGSVGElement | string) => string / Blob`: Standalone SVG text (namespaces and the XML header added) or an image/svg+xml blob, so the file opens in any viewer.
- `svgToImageBlob?: (svg: SVGSVGElement | string, options?: { width?: number; height?: number; scale?: number = 2; background?: string; type?: ImageType = "image/png"; quality?: number }) => Promise<Blob>`: Draws an SVG into a canvas and returns a PNG (or JPEG / WebP): QR codes, signatures, charts. The size defaults to the SVG's width / height or viewBox.
- `loadImage?: (source: string | Blob, options?: { crossOrigin?: "anonymous" | "use-credentials" | null }) => Promise<HTMLImageElement>`: An image ready for drawImage from a URL, a data URL or a File / Blob (its object URL is released once decoded). Used by croppers and avatar uploads.
- `blobToDataUrl?: (blob: Blob) => Promise<string>`: A data: URL for previews and small uploads.
- `canCopyImages / copyImageToClipboard?: () => boolean / (image: Blob | Promise<Blob>) => Promise<boolean>`: Puts a PNG on the clipboard. Pass the promise itself from the click handler (not an awaited blob): Safari only allows the write when the ClipboardItem is created inside the gesture. Resolves false when unsupported or denied.
- `shareFile?: (file: File, options?: { title?: string; text?: string }) => Promise<boolean>`: The phone's share sheet with a file; resolves false where files can not be shared, so the caller downloads instead.
- `sanitizeFileName / timestampedFileName?: (name: string, fallback?: string) => string / (base: string, extension: string, date?: Date) => string`: "Invoice #12/2026" → "Invoice-12-2026", "Café menu" → "Cafe-menu"; ("Signature", "png") → "Signature-2026-09-24-1640.png".

```tsx
import { svgToImageBlob, downloadBlob, timestampedFileName } from "@/lib/file-export"

export function DownloadQr({ svg }: { svg: SVGSVGElement | null }) {
  return (
    <button
      type="button"
      onClick={async () => {
        if (!svg) return
        const png = await svgToImageBlob(svg, { scale: 4, background: "#ffffff" })
        downloadBlob(png, timestampedFileName("invoice-qr-code", "png"))
      }}
    >
      Download PNG
    </button>
  )
}
```

Docs: https://wingo-ui.com/components/file-export (Markdown: https://wingo-ui.com/components/file-export.md)

#### File types (`file-types`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add file-types`

What a file is from its name or mime type: kind, icon, tile colors, a short type label and a localized size.

Type any file name (or pick a sample) and see the kind, icon tile, type label and size the helpers produce. Switch the locale to compare "2.4 MB" with "2,4 MB".

npm: lucide-react
Wingo UI dependencies: number-format, tones

API:
- `name?: string` = "": The demo's file name. The extension wins over the mime type because browsers often report none.
- `locale?: string` = "en-US": The locale formatFileSize uses in the demo.
- `getFileKind?: (file: { name?: string; type?: string } | string) => "image" | "video" | "audio" | "pdf" | "document" | "spreadsheet" | "presentation" | "archive" | "code" | "design" | "other"`: From the extension first, then the mime type. Accepts a File, an UploadFile, any { name, type } or a plain name / url.
- `FILE_KIND_ICONS / FILE_KIND_CLASSES / FILE_KIND_TONES / FILE_KIND_LABELS?: Record<FileKind, LucideIcon | string | Tone | string>`: The lucide icon, the tile classes (red pdf, blue document, green sheet, amber slides and archives, neutral media: the same colors file-upload uses), the tone for badges, and English names for screen readers.
- `formatFileSize?: (bytes: number | null | undefined, locale?: string) => string`: "2.4 MB" in en-US ("2,4 MB" in de-DE), "320 KB": binary steps, one decimal below 10 from MB up, "" for invalid sizes.
- `getFileTypeLabel / getFileExtension / splitFileName / isPreviewableImage?: (file) => string / (name) => string / (name) => [base, ext] / (file) => boolean`: "PDF"; "pdf"; ["Q3 proposal", ".pdf"] so long names truncate in the middle and keep the extension; whether a browser can draw it (no heic, no tiff).

```tsx
import { FILE_KIND_CLASSES, FILE_KIND_ICONS, formatFileSize, getFileKind } from "@/lib/file-types"

export function Attachment({ name, size }: { name: string; size: number }) {
  const kind = getFileKind(name)
  const Icon = FILE_KIND_ICONS[kind]
  return (
    <div className="flex items-center gap-3">
      <span className={`flex size-10 items-center justify-center rounded-[12px] ${FILE_KIND_CLASSES[kind]}`}>
        <Icon className="size-5" />
      </span>
      <span>{name}</span>
      <span>{formatFileSize(size, "en-US")}</span>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/file-types (Markdown: https://wingo-ui.com/components/file-types.md)

#### Filters (`filters`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add filters`

The filter model of builders and saved views: typed fields, AND / OR groups, evaluation, a sentence per filter and url strings.

Pick a saved view in the playground: its conditions show as chips, the sentence under them is describeFilter in the chosen locale, and the client list below is applyFilter over the twelve Northwind CRM customers. Switch the top-level combinator between AND and OR and watch the count change. Remove a chip with its × button (or Delete while it has focus) to see removeFilterNode; the url string at the bottom is serializeFilter and reads back with parseFilter.
Wingo UI dependencies: commerce, date-utils, number-format, text-match

API:
- `view?: string` = "ny-london": The demo's saved view (a FilterView): customers in New York or London, overdue customers, large balances or invoices in the last 7 days.
- `combinator?: "and" | "or"` = "and": The root group's combinator. Nested groups keep their own.
- `locale?: string` = "en-US": describeFilter options.locale: money, numbers and dates in the sentence. The demo passes German operator labels for de-DE.
- `FilterField?: { id; label; type: "text" | "number" | "currency" | "date" | "select" | "multi-select" | "boolean"; accessor?: keyof T | (row: T) => unknown; options?: FilterFieldOption[]; operators?: FilterOperator[]; currency?; placeholder?; group? }`: A field people can filter by. The value comes from row[id] unless accessor says otherwise; options feed select fields ({ value, label, description?, avatar?, color?, keywords? }).
- `FilterCondition / FilterGroup / FilterView?: { id; field; operator; value? } / { id; combinator: "and" | "or"; conditions: (FilterCondition | FilterGroup)[] } / { id; name; filter; readOnly?; pinned? }`: Values: text a string, number and currency a number, between [min, max] with null for an open end, date "2026-09-24" (a local day) or [from, to], in-last / in-next a number of days, select a string or string[].
- `FILTER_OPERATORS / DEFAULT_FILTER_OPERATOR / DEFAULT_FILTER_OPERATOR_LABELS?: Record<FilterFieldType, FilterOperator[]> / Record<FilterFieldType, FilterOperator> / Record<FilterOperator, string>`: What each type allows (text: contains, not-contains, is, is-not, starts-with, ends-with; numbers: eq, neq, gt, gte, lt, lte, between; dates: on, before, after, between, in-last, in-next; select: is, is-not, any-of, none-of; multi-select: any-of, all-of, none-of; boolean: is-true, is-false; every type: is-empty, is-not-empty), the one a new condition starts with, and English words for them.
- `operatorsFor / operatorNeedsValue / operatorValueShape?: (field) => FilterOperator[] / (op) => boolean / (op, type) => "none" | "single" | "list" | "range" | "days"`: The operators a field offers (its operators prop intersected with its type's), whether an operator takes a value, and which value input it needs.
- `createFilterGroup / createFilterCondition / createFilterId?: (combinator?, conditions?) => FilterGroup / (field, overrides?) => FilterCondition / (prefix?) => string`: New nodes with fresh ids (call them in event handlers, not during render). A new condition gets the type's default operator and 30 days for in-last.
- `addFilterNode / updateFilterNode / removeFilterNode / findFilterNode?: (root, node, groupId?) => FilterGroup / (root, id, patch) => FilterGroup / (root, id) => FilterGroup / (root, id) => FilterNode | null`: Immutable edits anywhere in the tree; removing the last condition of a nested group removes the group.
- `isConditionComplete / flattenConditions / countActiveConditions?: (condition, field?) => boolean / (root, fields?) => FilterCondition[] / (root, fields) => number`: A condition filters only once it has every value its operator needs, so a chip being built never empties the list. The count is the "Filters · 3" badge.
- `evaluateFilter / applyFilter?: (row, filter, fields, { now? }) => boolean / (rows, filter, fields, { now? }) => T[]`: Text ignores case and diacritics ("zurich" finds Zürich), dates compare local days, select values may be strings, { value } objects or arrays of either, incomplete conditions and unknown fields are skipped and an empty group passes. The same code filters on a server.
- `describeCondition / describeFilter?: (condition, field, { locale, labels }) => { field; operator; value } / (root, fields, { locale, labels }) => string`: The three parts of a chip and one sentence for the whole filter: "City is any of New York or London and (Balance ≥ $12,000 or Last invoice in the last 7 days)". Pass labels for another language.
- `serializeFilter / parseFilter?: (root: FilterGroup) => string / (text) => FilterGroup | null`: A compact base64url string for ?filter= links and saved views, and back (null for a broken or hand-edited link).

```tsx
import { applyFilter, createFilterCondition, createFilterGroup, describeFilter, type FilterField } from "@/lib/filters"

type Client = { name: string; city: string; balance: number }
const fields: FilterField<Client>[] = [
  { id: "city", label: "City", type: "select", options: [{ value: "New York", label: "New York" }, { value: "London", label: "London" }] },
  { id: "balance", label: "Balance", type: "currency", currency: "USD" },
]

const filter = createFilterGroup("and", [
  createFilterCondition(fields[0], { value: ["New York", "London"] }),
  createFilterCondition(fields[1], { operator: "gte", value: 5000 }),
])

const rows: Client[] = [{ name: "Northwind Tech LLC", city: "New York", balance: 12480 }]
applyFilter(rows, filter, fields) // [Northwind Tech LLC]
describeFilter(filter, fields, { locale: "en-US" }) // "City is any of New York or London and Balance ≥ $5,000"
```

Docs: https://wingo-ui.com/components/filters (Markdown: https://wingo-ui.com/components/filters.md)

#### Form validation (`form-validation`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add form-validation`

Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks.

Fill the sign-up form and leave a field: its error appears under it and clears as you fix it. Submit with empty fields and every error shows at once, focus jumps to the first one. Switch the messages to the ready Romanian set, raise the password length or the minimum strength and try again. A valid form sends a pretend request and shows the result.

npm: react-hook-form, @hookform/resolvers, zod, libphonenumber-js
Wingo UI dependencies: invoicing

API:
- `messages?: "ro" | "en"` = "en": Demo only: which message set the validators use (the English defaults or VALIDATION_MESSAGES_RO).
- `minLength?: number` = 8: v.password({ minLength }): the shortest password accepted.
- `minScore?: number` = 2: v.password({ score: scorePassword, minScore }): the weakest strength accepted (0 skips the check, 4 is Strong).
- `createValidators?: (messages?: Partial<ValidationMessages>) => Validators`: Zod schemas sharing one message set: text({ required, min, max }), name(), email(), password({ minLength, score, minScore }), phone({ country }), cui(), iban(), postalCode(), url(), otp(length), accept() (a ticked checkbox), number({ min, max }). Every field rule takes { required } and accepts "" when optional. v.messages is the merged set.
- `withMatch?: (schema: ZodObject, field: string, confirmField: string, message?: string) => ZodType`: Adds "confirmField must equal field" to an object schema, reported on the confirm field (password and its confirmation).
- `useZodForm?: (schema: ZodType, options?: UseFormProps) => UseFormReturn`: useForm with the zod resolver and the library's timing: mode onTouched (an error appears once a field is left), then it updates as you type. Input and output types come from the schema.
- `fieldError?: (form: UseFormReturn, name: string) => string | undefined`: The error message of a field (dotted paths work), ready for a component's error prop: error={fieldError(form, "email")}.
- `simulateRequest?: <T>(ms?: number, options?: { fail?: string; value?: T; signal?: AbortSignal }) => Promise<T>`: A pretend request for demos and default handlers: resolves after ms (default 900), or rejects with fail as the message.
- `DEFAULT_VALIDATION_MESSAGES / VALIDATION_MESSAGES_RO?: ValidationMessages`: The English defaults and the ready Romanian set. Counted messages are functions: tooShort(min), otp(length).

```tsx
import { z } from "zod"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { createValidators, fieldError, useZodForm } from "@/lib/form-validation"

// English messages by default; pass VALIDATION_MESSAGES_RO for the Romanian set
const v = createValidators()
const schema = z.object({ email: v.email(), cui: v.cui({ required: false }) })

export function CompanyForm({ onSave }: { onSave: (values: z.output<typeof schema>) => Promise<void> }) {
  const form = useZodForm(schema, { defaultValues: { email: "", cui: "" } })
  return (
    <form onSubmit={form.handleSubmit(onSave)} noValidate className="flex flex-col gap-4">
      <Input label="Email" type="email" autoComplete="email" {...form.register("email")} error={fieldError(form, "email")} />
      <Input label="Tax ID (CUI)" {...form.register("cui")} error={fieldError(form, "cui")} />
      <Button type="submit" loading={form.formState.isSubmitting}>Save</Button>
    </form>
  )
}
```

Docs: https://wingo-ui.com/components/form-validation (Markdown: https://wingo-ui.com/components/form-validation.md)

#### Haptics (`haptics`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add haptics`

Haptic feedback for the web in one call: short vibration ticks on Android and the system tick on iPhone, silent everywhere else.

Tap a tile on a phone to feel each kind: a faint selection detent, light, medium and heavy impacts, and the success, warning and error patterns drawn as bars on the tile. Send plays the kind picked in the playground. On a desktop nothing vibrates and the readout says haptic() returned false; turn enabled off to see every call return false on a phone too.

API:
- `kind?: "selection" | "light" | "medium" | "heavy" | "success" | "warning" | "error"` = "light": haptic(kind?, options?): the feel. selection for wheel and slider detents, light for taps and toggles, medium for a snap or a crossed threshold, heavy for a committed full swipe or a drop, success / warning / error for outcomes. Returns true when a haptic was sent.
- `enabled?: boolean` = true: configureHaptics({ enabled }): the app-wide switch, e.g. a Vibrations setting. Off, haptic() does nothing unless called with { force: true }.
- `iosFallback?: boolean` = true: configureHaptics({ iosFallback }): Safari on iOS has no vibrate, but toggling a native switch input plays the system tick (iOS 17.4+). The lib keeps one hidden, aria-hidden switch at the end of <body> and clicks it; the click never bubbles into the page.
- `force?: boolean`: haptic(kind, { force: true }) plays even when haptics are turned off app-wide (a test button next to the setting).
- `HAPTIC_PATTERNS?: Record<HapticKind, number | number[]>`: The vibration patterns in ms: selection 4, light 8, medium 14, heavy 22, success [10, 60, 16], warning [16, 70, 16], error [22, 50, 22, 50, 22]. iOS repeats its one tick 1, 2 or 3 times instead.
- `supportsHaptics?: () => boolean`: True when this device can play a haptic (vibrate, or an iPhone / iPad with the fallback on). False on the server: call it in an effect or a handler.
- `getHapticsConfig?: () => HapticsConfig`: The current { enabled, iosFallback }.

```tsx
"use client"

import { haptic } from "@/lib/haptics"
import { Button } from "@/components/ui/button"

export function PayButton({ onPay }: { onPay: () => Promise<void> }) {
  return (
    <Button
      onClick={async () => {
        haptic("light")
        try {
          await onPay()
          haptic("success")
        } catch {
          haptic("error")
        }
      }}
    >
      Pay $1,850
    </Button>
  )
}
```

Docs: https://wingo-ui.com/components/haptics (Markdown: https://wingo-ui.com/components/haptics.md)

#### Invoicing (`invoicing`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add invoicing`

Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP.

Change the quantities of the invoice lines with − and +: the net per line, the VAT breakdown per rate (21% and 11%), the discounts and the total are one computeInvoiceTotals call. Turn on prices with VAT, set a document discount in percent or as an amount, and see the VAT stay exact per rate. Type any CUI, IBAN or CNP in the checker: it recognises which one it is, validates the control digit, names the bank of a Romanian IBAN and reads the birth date and county from a CNP.
Wingo UI dependencies: commerce, number-format

API:
- `pricesIncludeVat?: boolean` = false: options.pricesIncludeVat: false for B2B invoices (unit prices without VAT, VAT added), true for shops and B2C quotes (VAT inside the prices).
- `discount?: number` = 0: The demo's document discount, options.discount.value: shared across lines by value after their own discounts, so every VAT rate stays exact.
- `discountType?: "percent" | "amount"` = "amount": options.discount.type: a percent of the subtotal or a fixed amount (dollars in the demo).
- `locale?: string` = "en-US": The demo's formatting locale (formatPrice from commerce, formatVatRate).
- `code?: string` = "RO12345674": The demo's id checker: a CUI (with or without RO), an IBAN or a CNP.
- `computeInvoiceTotals?: (lines: InvoiceLineInput[], options?: InvoiceTotalsOptions) => InvoiceTotals`: Lines are { id, quantity, unitPrice, vatRate? (0.21), discount?, discountType?: "percent" | "amount" }; options { pricesIncludeVat, discount: { type, value }, defaultVatRate, categoryFor, decimals }. Returns lines (gross, discount, net, vat, total each), gross, lineDiscount, documentDiscount, discount, net, vat, total and vatBreakdown (one row per rate: rate, category, net, vat, total, lineCount). VAT is rounded once per rate on its taxable amount (EN 16931 BR-CO-17, what e-Factura validates), so per-line VAT is informative and the totals always add up.
- `computeInvoiceLine?: (line: InvoiceLineInput, options?) => InvoiceLineTotals`: One line on its own, for the row of a line editor.
- `RO_VAT_RATES / formatVatRate?: VatRateOption[] / (rate: number, locale?: string) => string`: Options for a VAT select: 21% standard, 11% reduced, and 0% exempt (E), reverse charge (AE) and intra-community (K), each { value, rate, category, label, description }. formatVatRate(0.21, "en-US") → "21%" ("21 %" in ro-RO). Romania's standard rate is 21% since 01.08.2025.
- `VatCategory?: "S" | "Z" | "E" | "AE" | "K" | "G" | "O"`: The UBL / EN 16931 VAT category codes an e-Factura line carries.
- `incrementDocumentNumber?: (current: string, step?: number) => string`: The next number of a series with its padding and prefix: "2026-0412" → "2026-0413", "CRP 099" → "CRP 100".
- `parseCui / isValidCui / formatCui?: (input) => { digits; vatPayer; valid } | null / (input) => boolean / (input, { vatPayer? }) => string`: A Romanian company code with the ANAF control digit (key 753217532); "RO" marks a VAT payer. RO12345674 is valid, RO12345678 is not.
- `isValidIban / formatIban / getIbanBank / RO_BANKS?: (input) => boolean / (input) => string / (input) => { code; name } | null / Record<string, string>`: The ISO 13616 mod-97 check with each country's length, groups of four ("RO49 AAAA 1B31 0075 9384 0000") and the bank of a Romanian IBAN (BTRL → Banca Transilvania, TREZ → Trezoreria Statului).
- `parseCnp / isValidCnp?: (input) => { valid; sex: "m" | "f" | null; birthDate; countyCode; countyName; anonymous } | null / (input) => boolean`: A personal numeric code with its control digit, birth date and county. "0000000000000" is the e-Factura placeholder for a buyer who gave no CNP (anonymous: true, valid).

```tsx
import { computeInvoiceTotals, formatVatRate, isValidCui } from "@/lib/invoicing"
import { formatPrice } from "@/lib/commerce"

const totals = computeInvoiceTotals(
  [
    { id: "l1", quantity: 3, unitPrice: 1250, vatRate: 0.21, discount: 10 },
    { id: "l2", quantity: 12, unitPrice: 64.9, vatRate: 0.11 },
  ],
  { discount: { type: "amount", value: 100 } },
)

totals.vatBreakdown.map((row) => `VAT ${formatVatRate(row.rate, "en-US")}: ${formatPrice(row.vat, { locale: "en-US", currency: "USD" })}`)
formatPrice(totals.total, { locale: "en-US", currency: "USD" }) // "$4,829.10"
isValidCui("RO12345674") // true
```

Docs: https://wingo-ui.com/components/invoicing (Markdown: https://wingo-ui.com/components/invoicing.md)

#### Motion presets (`motion`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add motion`

The shared springs, enter and exit presets, stagger helpers and reduced-motion hooks every animated component uses.

Four balls run the four springs side by side, so you can feel the difference. Pick a spring and a stagger step, then replay the list to see them drive real content. Everything turns into a short fade when the system asks for reduced motion.

npm: motion
Wingo UI dependencies: use-media-query

API:
- `spring?: "snappy" | "smooth" | "bouncy" | "gentle"` = "smooth": springs[name]: snappy (500 / 32) answers a finger, smooth (300 / 30) is the default for overlays and layout, bouncy (400 / 18) is for playful accents, gentle (120 / 20) for large surfaces.
- `stagger?: number` = 0.04: staggerChildren(step, delay?): seconds between siblings. 0.03 to 0.05 feels quick; above 0.08 reads as slow.

Parts:
- `presets` (constant): initial / animate / exit / transition bundles to spread onto a motion element inside AnimatePresence. collapse animates height to auto for accordions and collapsibles, the one sanctioned height animation. Type: Record<"overlay" | "popover" | "tooltip" | "dialog" | "sheet" | "fade" | "listItem" | "toast" | "collapse", MotionPreset>.
- `sheetFrom` (function): The sheet preset for any edge. Signature: (side: "top" | "right" | "bottom" | "left") => MotionPreset.
- `press` (constant): The shared press feedback: scale 0.97 on a snappy spring. Type: { whileTap, transition }.
- `gestures` (constant): Shared thresholds for drags, swipes and long presses, matched to vaul: a drag completes past a quarter of the surface or on a 400px/s flick. longPress is in ms, slop in px. Type: { completeFraction: 0.25, completeVelocity: 400, elastic: 0.2, longPress: 450, slop: 8 }.
- `shouldComplete` (function): Whether a drag should complete (dismiss, commit a swipe action) or spring back. Pass the offset and velocity along the drag axis, positive toward completion. Signature: (offset: number, velocity: number, size: number) => boolean.
- `rubberband` (function): iOS-style resistance past an edge: maps how far the finger is past a limit to how far the surface moves. Signature: (overflow: number, dimension: number, constant?: number) => number.
- `easings` (constant): Tween curves and durations in seconds, matching the --motion-* CSS tokens. Type: { out, inOut, sheet }.
- `durations` (constant): Tween curves and durations in seconds, matching the --motion-* CSS tokens. Type: { fast: 0.15, normal: 0.24, slow: 0.4 }.
- `staggerItem` (constant): Child variants for staggerChildren, and a capped per-index delay for items that animate on their own. Type: Variants.
- `staggerDelay` (function): Child variants for staggerChildren, and a capped per-index delay for items that animate on their own. Signature: (index: number, step?: number, max?: number) => number.
- `usePrefersReducedMotion` (hook): The reduced-motion preference, false on the server and during hydration so markup matches. Signature: () => boolean.
- `useMotionPreset` (hook): A preset that turns into a short opacity fade under reduced motion. reducePreset(preset, reduced) is the same without the hook. Signature: (preset: PresetName | MotionPreset) => MotionPreset.
- `useMotionTransition` (hook): The transition you pass, or an instant one under reduced motion. For layout animations and indicators. Signature: (transition?: Transition) => Transition.

```tsx
import { AnimatePresence, motion } from "motion/react"
import { press, springs, useMotionPreset, useMotionTransition } from "@/lib/motion"

export function SaveMenu({ open, saved }: { open: boolean; saved: boolean }) {
  const popover = useMotionPreset("popover")
  const layout = useMotionTransition(springs.smooth)

  return (
    <motion.div layout transition={{ layout }} className="flex items-center gap-2">
      <motion.button {...press}>{saved ? "Saved" : "Save"}</motion.button>
      <AnimatePresence>
        {open && <motion.div {...popover} className="rounded-2xl bg-popover p-4 shadow-floating" />}
      </AnimatePresence>
    </motion.div>
  )
}
```

Docs: https://wingo-ui.com/components/motion (Markdown: https://wingo-ui.com/components/motion.md)

#### Navigation (`navigation`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add navigation`

Router-agnostic links, active-route matching, one NavItem shape and the app shell context that every nav component shares.

Click through the mini CRM: every link goes through a pretend router given to LinkProvider, the address bar updates and the matching item lights up with aria-current. Open a customer and Customers stays active by prefix; switch match to exact and it lets go. The external link opens a new tab and the disabled one ignores clicks and Tab.

API:
- `currentPath?: string` = "": LinkProvider({ component, currentPath, onNavigate }): the current pathname (next: usePathname()). Every nav component inside finds its active item from it; a component's own currentPath or value prop wins.
- `component?: ComponentType<LinkComponentProps> | "a"` = "a": LinkProvider: the router link every NavLink renders through (next/link's Link, react-router's Link). Set it once in a client providers file; library components never import next/*.
- `onNavigate?: (href: string) => void`: LinkProvider: runs when a NavLink starts an in-app navigation (a plain left click on an internal link). useNavigateListener subscribes to the same event, which is how a route progress bar starts on its own.
- `navigate?: (href: string) => void`: LinkProvider: the router's push (next: useRouter().push). useNavigate() uses it for navigations without an anchor, like a command menu item picked with Enter; without it they fall back to a full page load.
- `match?: "prefix" | "exact"` = "prefix": matchPath(href, currentPath, match) and NavItem.match: prefix keeps /customers active on /customers/42, exact only on /customers. "/" always matches exactly.
- `NavLink?: ({ href, component?, active?, current?, disabled?, external?, ...anchorProps }) => JSX.Element`: An anchor through the router link: aria-current (current: "page" | "step" | "location") and data-active while active, a real disabled state (no href, aria-disabled, tabIndex -1), and external links (absolute urls to another origin, or external) in a new tab with rel="noopener noreferrer". data-slot="nav-link".

Parts:
- `NavItem` (type): One shape for sidebar, bottom tab bar, nav tabs, nav menu and the command menu, so an app defines its navigation once. navItemKey(item) is id, else href, else a string label. Type: { id?, label, textValue?, href?, icon?, activeIcon?, badge?, description?, disabled?, external?, match?, onSelect?, items?, keywords?, shortcut? }.
- `NavGroup` (type): One shape for sidebar, bottom tab bar, nav tabs, nav menu and the command menu, so an app defines its navigation once. navItemKey(item) is id, else href, else a string label. Type: { id?, label?, items, collapsible?, defaultOpen? }.
- `findActivePath` (function): The active item and its ancestors ([Settings, Team]): an explicit value (an item key) wins, else the most specific href match. Pass groupItems(groups) for grouped navigation. flattenNavItems, navItemText, isExternalHref and normalizePath are exported too. Signature: (items: NavItem[], { value?, currentPath? }) => NavItem[] | null.
- `useLinkComponent` (hook): For component authors: the provider's link component and path with a prop override, a subscription to in-app navigations, and a navigate function (external urls open in a new tab, in-app paths notify listeners and go through the provider's navigate). Signature: (override?) => LinkComponent.
- `useCurrentPath` (hook): For component authors: the provider's link component and path with a prop override, a subscription to in-app navigations, and a navigate function (external urls open in a new tab, in-app paths notify listeners and go through the provider's navigate). Signature: (override?) => string | undefined.
- `useNavigateListener` (hook): For component authors: the provider's link component and path with a prop override, a subscription to in-app navigations, and a navigate function (external urls open in a new tab, in-app paths notify listeners and go through the provider's navigate). Signature: (listener) => void.
- `useNavigate` (hook): For component authors: the provider's link component and path with a prop override, a subscription to in-app navigations, and a navigate function (external urls open in a new tab, in-app paths notify listeners and go through the provider's navigate). Signature: () => (href, { external? }) => void.
- `NavShellProvider` (component): What an app shell shares with the bars inside it: isMobile, collapsed and setCollapsed, mobileOpen and setMobileOpen, toggleSidebar, hasSidebar, scroll (window or content) and its labels. A top bar renders the menu button from it and a tab bar knows the shell lays it out, without importing the shell. Props: ({ value: NavShellState, children }).
- `useNavShell` (hook): What an app shell shares with the bars inside it: isMobile, collapsed and setCollapsed, mobileOpen and setMobileOpen, toggleSidebar, hasSidebar, scroll (window or content) and its labels. A top bar renders the menu button from it and a tab bar knows the shell lays it out, without importing the shell. Signature: () => NavShellState | null.

```tsx
"use client"

import type { ReactNode } from "react"
import Link from "next/link"
import { usePathname } from "next/navigation"
import { LinkProvider, matchPath, NavLink, useCurrentPath } from "@/lib/navigation"

// app/providers.tsx, rendered by the root layout around {children}
export function Providers({ children }: { children: ReactNode }) {
  return (
    <LinkProvider component={Link} currentPath={usePathname()}>
      {children}
    </LinkProvider>
  )
}

// any link inside renders through next/link and knows when it is the current page
export function ClientsLink() {
  const currentPath = useCurrentPath()
  return (
    <NavLink href="/customers" active={matchPath("/customers", currentPath)} className="data-active:font-semibold">
      Customers
    </NavLink>
  )
}
```

Docs: https://wingo-ui.com/components/navigation (Markdown: https://wingo-ui.com/components/navigation.md)

#### Number format (`number-format`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add number-format`

Locale-aware number helpers: cached Intl formatting, parsing what people type, step math and currency affixes.

Type an amount: the field groups thousands as you type in the chosen locale and the caret never jumps. A dot or a comma both work as the decimal point, like on a phone keypad. The rows below show the parsed number, the same value formatted three ways and how the locale writes the currency.

API:
- `locale?: string` = "en-US": The demo's locale. Every helper takes an optional locale; pass the one from useLocale so server and browser agree.
- `currency?: string` = "USD": An ISO 4217 code for getCurrencyParts and currency formatting.
- `maxDecimals?: number` = 2: formatEditable's maxDecimals: decimals kept while typing; extra ones are cut, not rounded.
- `parseNumber?: (text: string, locale?: string) => number | null`: What someone typed, as a number (null when empty or not a number). The locale's decimal separator wins; without it a lone "." or "," before exactly three digits groups thousands ("1.234" = 1234 in de-DE) and anything else is a decimal point ("12.5" = 12.5). Symbols, units, spaces and "%" are ignored; the unicode minus works.

Parts:
- `formatNumber` (function): Intl formatting with a cached formatter. formatNumber returns "" for null and NaN so an empty field stays empty. Signature: (value: number | null | undefined, locale?: string, options?: Intl.NumberFormatOptions) => string.
- `getNumberFormatter` (function): Intl formatting with a cached formatter. formatNumber returns "" for null and NaN so an empty field stays empty. Signature: (locale?, options?) => Intl.NumberFormat.
- `getNumberSeparators` (function): The locale's characters: en-US "," and ".", de-DE "." and ",", fr-FR a narrow space and ",". Signature: (locale?: string) => { group: string; decimal: string; minus: string }.
- `getCurrencyParts` (function): How a locale writes a currency, for a field's prefix or suffix: USD in en-US is "$" before the number, RON in ro-RO is "lei" after it with a space. display defaults to narrowSymbol ("$", "€", "lei"); Intl's own default would print "RON". Signature: (currency: string, locale?: string, display?: "symbol" | "narrowSymbol" | "code" | "name") => { symbol: string; position: "prefix" | "suffix"; spaced: boolean; fractionDigits: number }.
- `formatEditable` (function): Re-formats a field's text while someone types: groups the integer part, keeps a trailing decimal separator ("12,") and trailing zeros ("12,50"), turns a typed "." into the locale decimal on an english keypad. Signature: (text: string, locale?: string, options?: { maxDecimals?: number; grouping?: boolean; allowNegative?: boolean }) => string.
- `digitsBeforeCaret` (function): Keep the caret in place across a re-format: count the digits (and the decimal separator) before it, re-format, then put it back after the same count. Signature: (text: string, caret: number, locale?: string) => number.
- `caretAfterDigits` (function): Keep the caret in place across a re-format: count the digits (and the decimal separator) before it, re-format, then put it back after the same count. Signature: (text: string, count: number, locale?: string) => number.
- `clamp` (function): Step math without float noise: roundTo(0.1 + 0.2, 2) is 0.3, snapToStep(0.35, 0.1) is 0.4, decimalsOf(0.05) is 2 (the precision a step implies). Signature: (value, min?, max?).
- `roundTo` (function): Step math without float noise: roundTo(0.1 + 0.2, 2) is 0.3, snapToStep(0.35, 0.1) is 0.4, decimalsOf(0.05) is 2 (the precision a step implies). Signature: (value, decimals).
- `snapToStep` (function): Step math without float noise: roundTo(0.1 + 0.2, 2) is 0.3, snapToStep(0.35, 0.1) is 0.4, decimalsOf(0.05) is 2 (the precision a step implies). Signature: (value, step, origin?).
- `decimalsOf` (function): Step math without float noise: roundTo(0.1 + 0.2, 2) is 0.3, snapToStep(0.35, 0.1) is 0.4, decimalsOf(0.05) is 2 (the precision a step implies). Signature: (value) => number.

```tsx
import { formatNumber, getCurrencyParts, parseNumber } from "@/lib/number-format"

const price = parseNumber("1,234.5", "en-US") // 1234.5
parseNumber("1.234,5", "de-DE") // 1234.5
formatNumber(price, "en-US", { style: "currency", currency: "USD", currencyDisplay: "narrowSymbol" }) // "$1,234.50"
getCurrencyParts("USD", "en-US") // { symbol: "$", position: "prefix", spaced: false, fractionDigits: 2 }
getCurrencyParts("RON", "ro-RO") // { symbol: "lei", position: "suffix", spaced: true, fractionDigits: 2 }
```

Docs: https://wingo-ui.com/components/number-format (Markdown: https://wingo-ui.com/components/number-format.md)

#### Relative time (`relative-time`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add relative-time`

Hydration-safe timestamps for feeds and comments: "5 min. ago", day groups like Today / Yesterday, clocks and full dates.

The feed shows the same events with relative times that tick every minute, grouped under Today, Yesterday and weekday headings. Switch the locale, the style and the format in the playground to compare "5 min. ago" with "vor 5 Min.", clocks and full dates. Hover a time to see the full date.
Wingo UI dependencies: date-utils

API:
- `locale?: string` = "en-US": The demo's locale. Every helper takes a locale; components pass the one from useLocale.
- `style?: "long" | "short" | "narrow"` = "short": RelativeTimeOptions.style: "5 minutes ago" (long) or "5 min. ago" (short).
- `format?: "relative" | "time" | "date" | "datetime"` = "relative": TimestampOptions.format for formatTimestamp: relative text, the clock, the date or both.
- `grouped?: boolean` = true: The demo groups the feed with groupByDay.
- `formatTimestamp?: (value, options: { now: number | null; locale?: string; format?: TimestampFormat; style?; maxDays? }) => string`: One call for any row timestamp. With now null, relative falls back to "22.09.2026, 16:40".

Parts:
- `useNow` (hook): The current time rounded down to interval ms (default 60 000), re-rendering when it ticks and when the tab wakes up. null on the server and during hydration: render a date then, and relative text once it is a number. Signature: (interval?: number) => number | null.
- `formatRelativeTime` (function): "now", "5 min. ago", "3 hr. ago", "yesterday", "3 days ago", "2 wk. ago", then the date past maxDays (28). Future times read "in 5 min.", "tomorrow". Signature: (value: Date | string | number, options: { now: number; locale?: string; style?: RelativeTimeStyle; maxDays?: number; dateOptions?: Intl.DateTimeFormatOptions }) => string.
- `formatDayGroupLabel` (function): "Today", "Yesterday", "Tomorrow", a weekday within the last week ("Monday"), then the date. Signature: (value, now: number | null, locale?: string, dateOptions?) => string.
- `groupByDay` (function): Consecutive day groups { key, date, label, items }, newest first by default; items without a valid time go last under undatedLabel ("Earlier"). Signature: <T>(items: readonly T[], getTime: (item: T) => TimeInput | null | undefined, options: { now: number | null; locale?: string; order?: "desc" | "asc" | "none"; undatedLabel?: string }) => DayGroup<T>[].
- `formatClock` (function): "4:40 PM" or "16:40"; "Thursday, September 24, 2026 at 4:40 PM" for titles; the ISO string for <time dateTime>. Signature: (value, locale?) => string.
- `formatFullTimestamp` (function): "4:40 PM" or "16:40"; "Thursday, September 24, 2026 at 4:40 PM" for titles; the ISO string for <time dateTime>. Signature: (value, locale?) => string.
- `toDateTimeAttr` (function): "4:40 PM" or "16:40"; "Thursday, September 24, 2026 at 4:40 PM" for titles; the ISO string for <time dateTime>. Signature: (value, locale?) => string.
- `toTime` (function): Parsing and calendar-day math (0 today, -1 yesterday), DST safe. Constants MINUTE, HOUR, DAY. Signature: (value) => number | null.
- `startOfDayTime` (function): Parsing and calendar-day math (0 today, -1 yesterday), DST safe. Constants MINUTE, HOUR, DAY. Signature: (time) => number.
- `dayDiff` (function): Parsing and calendar-day math (0 today, -1 yesterday), DST safe. Constants MINUTE, HOUR, DAY. Signature: (time, now) => number.

```tsx
import { formatTimestamp, formatFullTimestamp, toDateTimeAttr, useNow } from "@/lib/relative-time"

export function CommentTime({ date }: { date: Date }) {
  const now = useNow()
  return (
    <time dateTime={toDateTimeAttr(date)} title={formatFullTimestamp(date, "en-US")}>
      {formatTimestamp(date, { now, locale: "en-US" })}
    </time>
  )
}
```

Docs: https://wingo-ui.com/components/relative-time (Markdown: https://wingo-ui.com/components/relative-time.md)

#### Romanian locations (`ro-locations`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add ro-locations`

Romania's counties, cities and neighbourhoods with coordinates, diacritic-free search, distances and within-radius lists.

Type a place without diacritics ("iasi", "manastur", "sector 3"): cities, neighbourhoods and counties match with the typed part highlighted, larger places first. Tap a result to make it the centre, then drag the radius in the playground: the list below shows every city within that distance, nearest first, in km for the chosen locale.
Wingo UI dependencies: text-match, number-format

API:
- `radius?: number` = 30: The demo's citiesWithin(center, radiusKm) radius in km. The centre city itself is always first, at 0 km.
- `center?: string` = "cluj-napoca": The demo's centre: a city id from RO_CITIES (citiesWithin also takes any { lat, lng }).
- `limit?: number` = 8: searchLocations options.limit: at most this many matches.
- `locale?: string` = "en-US": formatDistance's locale: "4.2 km" in en-US, "4,2 km" in ro-RO. The demo also prints the straight-line distance to a second city with one decimal.
- `searchLocations?: (query: string, options?: { limit?: number; types?: ("city" | "area" | "county")[]; county?: string }) => LocationMatch[]`: Cities, areas and counties matching a query, ignoring case and diacritics (through text-match), best match first and larger places first among equals, with ranges to highlight. An empty query returns the largest cities (the "popular" suggestions of a location field).

Parts:
- `RO_COUNTIES` (constant): The 41 counties and Bucharest, alphabetical, with the plate code ("CJ", "B") and the seat ("Cluj-Napoca"). Type: readonly { code: string; name: string; seat: string }[].
- `RO_CITIES` (constant): Every county seat and the large towns (52), largest first, with the city-centre coordinates, residents in thousands (2021 census, rounded, for ordering only) and the neighbourhoods or sectors people put in listings. Type: readonly { id: string; name: string; county: string; lat: number; lng: number; population: number; areas?: string[] }[].
- `getCounty` (function): Lookups by plate code (case-insensitive) and by city id (a slug: "targu-mures"). Signature: (code: string) => RoCounty | undefined.
- `getCity` (function): Lookups by plate code (case-insensitive) and by city id (a slug: "targu-mures"). Signature: (id: string) => RoCity | undefined.
- `citiesInCounty` (function): Lookups by plate code (case-insensitive) and by city id (a slug: "targu-mures"). Signature: (code: string) => RoCity[].
- `countyOptions` (function): Options for select, combobox and listbox: { value: "CJ", label: "Cluj", description: "Cluj-Napoca", keywords } and { value: "cluj-napoca", label: "Cluj-Napoca", description: "Cluj", keywords: its areas }, so "manastur" finds Cluj-Napoca in a combobox. Signature: () => LocationOption[].
- `cityOptions` (function): Options for select, combobox and listbox: { value: "CJ", label: "Cluj", description: "Cluj-Napoca", keywords } and { value: "cluj-napoca", label: "Cluj-Napoca", description: "Cluj", keywords: its areas }, so "manastur" finds Cluj-Napoca in a combobox. Signature: (county?: string) => LocationOption[].
- `distanceKm` (function): Great-circle distance (Cluj-Napoca to Florești ≈ 10 km), the cities inside a radius nearest first (a "+25 km" location filter), and "850 m" / "4.2 km" / "37 km". Signature: (a: GeoPoint, b: GeoPoint) => number.
- `citiesWithin` (function): Great-circle distance (Cluj-Napoca to Florești ≈ 10 km), the cities inside a radius nearest first (a "+25 km" location filter), and "850 m" / "4.2 km" / "37 km". Signature: (center: GeoPoint | string, radiusKm: number) => { city; distance }[].
- `formatDistance` (function): Great-circle distance (Cluj-Napoca to Florești ≈ 10 km), the cities inside a radius nearest first (a "+25 km" location filter), and "850 m" / "4.2 km" / "37 km". Signature: (km: number, locale?: string) => string.

```tsx
import { citiesWithin, cityOptions, formatDistance, searchLocations } from "@/lib/ro-locations"

searchLocations("manastur")[0] // { type: "area", label: "Mănăștur", description: "Cluj-Napoca, Cluj", ... }
cityOptions("CJ").map((o) => o.label) // ["Cluj-Napoca", "Florești", "Turda"]

citiesWithin("cluj-napoca", 30).map(({ city, distance }) => `${city.name} · ${formatDistance(distance, "en-US")}`)
// ["Cluj-Napoca · 0 m", "Florești · 10 km", "Turda · 26 km"]
```

Docs: https://wingo-ui.com/components/ro-locations (Markdown: https://wingo-ui.com/components/ro-locations.md)

#### Spreadsheet (`spreadsheet`)

lib · Pro · v1.0.0 · install: `npx wingo-ui@latest add spreadsheet`

Read CSV and Excel files in the browser, match their columns to your fields, and write CSV that Excel opens with diacritics intact.

Choose a CSV or an .xlsx file (or keep the sample, a ';' export from a European Excel): the demo shows the detected delimiter and encoding, the header row, how each column matched a Northwind CRM field (Company name → Company, VAT ID → Tax ID) with its score, and the first rows. Download CSV writes the parsed rows back with the delimiter from the playground, a byte order mark and formula cells neutralised.

npm: read-excel-file
Wingo UI dependencies: text-match

API:
- `delimiter?: string` = ",": toCsv options.delimiter for the download: "," or ";" (what a Romanian Excel expects, because "," is its decimal mark).
- `escapeFormulas?: boolean` = true: toCsv options.escapeFormulas: cells starting with = + - @ get a leading ' so a spreadsheet never runs them (CSV injection).
- `threshold?: number` = 0.5: matchColumns options.threshold: the lowest score that still maps a column to a field.
- `readSpreadsheet?: (file: Blob & { name?: string }, options?: { maxRows?; maxBytes?; header?: "auto" | number | false; delimiter?; columnLabel? }) => Promise<SpreadsheetWorkbook>`: A picked file as { kind: "csv" | "xlsx", sheets: { name, headers, rows, truncated }[], delimiter?, encoding? }. CSV / TSV / TXT are decoded as UTF-8, else Windows-1250 (a Romanian Excel), with the delimiter detected; .xlsx loads read-excel-file on demand. Blank and duplicate headers get names, short rows are padded, empty rows dropped. Throws SpreadsheetError with code "unsupported" (.xls, .numbers), "too-large" (default 20 MB), "empty" or "parse".

Parts:
- `parseCsv` (function): RFC 4180 parsing (quotes, doubled quotes, line breaks inside quotes, CRLF, a BOM), the delimiter among , ; tab | that splits the first lines most evenly, and the text of a file's bytes. Signature: (text, { delimiter?, maxRows? }) => { rows: string[][]; delimiter }.
- `detectDelimiter` (function): RFC 4180 parsing (quotes, doubled quotes, line breaks inside quotes, CRLF, a BOM), the delimiter among , ; tab | that splits the first lines most evenly, and the text of a file's bytes. Signature: (text) => string.
- `decodeText` (function): RFC 4180 parsing (quotes, doubled quotes, line breaks inside quotes, CRLF, a BOM), the delimiter among , ; tab | that splits the first lines most evenly, and the text of a file's bytes. Signature: (buffer: ArrayBuffer) => { text; encoding }.
- `toSheet` (function): Raw rows to a sheet with a header row, and a cell as text for previews and validators (dates as "2026-09-24"). Signature: (name, rows, options?) => SpreadsheetSheet.
- `cellToString` (function): Raw rows to a sheet with a header row, and a cell as text for previews and validators (dates as "2026-09-24"). Signature: (cell: SpreadsheetCell) => string.
- `matchColumns` (function): Pairs each field with at most one column by name, ignoring case, diacritics and punctuation ("Company name" = "company_name", "Société" = "societe"), aliases included ("VAT ID", "Tax ID"), best scores first, each column used once. The auto-match of an import wizard. Signature: (headers: string[], targets: { id; label; aliases? }[], { threshold? }) => { targetId; column: number | null; score }[].
- `toCsv` (function): CSV text with quoting where needed, a UTF-8 BOM by default so Excel keeps accented letters (é, ü, ñ), and a browser download (nothing happens on the server). Signature: (rows, { delimiter?, bom?, lineEnding?, escapeFormulas? }) => string.
- `downloadCsv` (function): CSV text with quoting where needed, a UTF-8 BOM by default so Excel keeps accented letters (é, ü, ñ), and a browser download (nothing happens on the server). Signature: (filename, rowsOrText, options?) => void.
- `SpreadsheetError` (type): What readSpreadsheet throws, so a UI can print its own message per code. Type: class extends Error { code: "unsupported" | "empty" | "too-large" | "parse" }.

```tsx
import { matchColumns, readSpreadsheet, SpreadsheetError, toCsv } from "@/lib/spreadsheet"

async function onFile(file: File) {
  try {
    const { sheets } = await readSpreadsheet(file)
    const [sheet] = sheets
    const mapping = matchColumns(sheet.headers, [
      { id: "name", label: "Company", aliases: ["Company name", "Customer"] },
      { id: "taxId", label: "Tax ID", aliases: ["VAT ID", "VAT number"] },
    ])
    return { sheet, mapping }
  } catch (error) {
    if (error instanceof SpreadsheetError && error.code === "unsupported") return null
    throw error
  }
}

toCsv([["Customer", "Balance"], ["Northwind Tech LLC", 12480]], { delimiter: ";" })
```

Docs: https://wingo-ui.com/components/spreadsheet (Markdown: https://wingo-ui.com/components/spreadsheet.md)

#### Text match (`text-match`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add text-match`

Search that ignores case and diacritics, ranks the best matches first and returns the ranges to highlight.

Type in the field: zurich finds Zürich, sao paulo finds São Paulo, and every word of the query has to match somewhere. The best matches rise to the top and the matched letters are highlighted. Turn on fuzzy to let letters in order with gaps match too (dsdf finds Düsseldorf).

API:
- `query?: string` = "": The demo's search text. Case and diacritics never matter; each word must match (in any order).
- `fuzzy?: boolean` = false: MatchOptions.fuzzy: also accept the query's letters in order with gaps, scored lowest. Good for short lists of known names; leave it off for long lists, where it lets too much through.
- `filterByText?: <T>(items: readonly T[], query: string, getText: (item: T) => string | readonly string[], options?: { fuzzy?: boolean; limit?: number }) => { item: T; score: number; ranges: MatchRange[] }[]`: The matching items, best first and stable for ties. getText returns the label, or [label, ...keywords]: keywords (a country's calling code, an English name) can match too, a little lower, and ranges always refer to the label. An empty query returns every item in order.

Parts:
- `matchText` (function): One text against a query, or null when a word is missing. Scores: exact 1, whole-text prefix 0.9, word prefix 0.75, inside a word 0.5, fuzzy 0.25, averaged over the query's words, with a small bonus for shorter texts. Signature: (text: string, query: string, options?: { fuzzy?: boolean }) => { score: number; ranges: MatchRange[] } | null.
- `splitByRanges` (function): Cuts a label into plain and matched pieces for rendering, e.g. matched pieces in font-semibold. Signature: (text: string, ranges: readonly MatchRange[]) => { text: string; match: boolean }[].
- `normalizeText` (function): Lowercase, without diacritics (é, ü, ñ, ø, the Romanian comma and cedilla s / t and friends), whitespace collapsed. Use it for keys and exact comparisons. Signature: (text: string) => string.
- `compareText` (function): A cached Intl.Collator compare for sorting labels the way the locale's dictionary does, numbers in natural order. Signature: (a: string, b: string, locale?: string) => number.

```tsx
import { filterByText, splitByRanges } from "@/lib/text-match"

const cities = ["Zürich", "São Paulo", "Kraków", "Montréal", "Düsseldorf"]

export function CityResults({ query }: { query: string }) {
  const results = filterByText(cities, query, (city) => city)
  return (
    <ul>
      {results.map(({ item, ranges }) => (
        <li key={item}>
          {splitByRanges(item, ranges).map((part, i) =>
            part.match ? <strong key={i}>{part.text}</strong> : <span key={i}>{part.text}</span>,
          )}
        </li>
      ))}
    </ul>
  )
}
```

Docs: https://wingo-ui.com/components/text-match (Markdown: https://wingo-ui.com/components/text-match.md)

#### Tones (`tones`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add tones`

One way to color a component: a tone or any CSS color becomes five CSS variables every variant paints with.

Each row is one tone painted three ways: a solid fill, a soft tint and an outline. Pick any color in the playground to see colorVars build the same set from it, with readable text on both themes.

API:
- `color?: string` = "#7C3AED": colorVars(color): any CSS color turned into the five --tone-* vars, for a component's color prop.
- `toneClasses?: Record<"neutral" | "brand" | "success" | "warning" | "danger" | "info", string>`: Classes that set --tone, --tone-foreground, --tone-soft, --tone-soft-foreground and --tone-border from the design tokens.

Parts:
- `colorVars` (function): The same vars as an inline style. The text on the fill turns black or white by lightness; soft text mixes toward the foreground. Signature: (color?: string) => CSSProperties | undefined.
- `TONES` (constant): Every tone in order, and a guard that turns an unknown string into a tone. Type: Tone[].
- `toTone` (function): Every tone in order, and a guard that turns an unknown string into a tone. Signature: (value: unknown, fallback?: Tone) => Tone.

```tsx
import { colorVars, toneClasses, type Tone } from "@/lib/tones"
import { cn } from "@/lib/utils"

export function Badge({ tone = "neutral", color, className, ...props }: React.ComponentProps<"span"> & { tone?: Tone; color?: string }) {
  return (
    <span
      data-slot="badge"
      className={cn(toneClasses[tone], "rounded-full bg-(--tone-soft) px-2 py-0.5 text-xs font-medium text-(--tone-soft-foreground)", className)}
      style={colorVars(color)}
      {...props}
    />
  )
}
```

Docs: https://wingo-ui.com/components/tones (Markdown: https://wingo-ui.com/components/tones.md)

#### UIProvider (`ui-config`)

lib · free · v1.0.0 · install: `npx wingo-ui@latest add ui-config`

App-wide configuration for Wingo UI: default props for every component, the Intl locale and the reduced-motion policy.

Wrap the app once. Every Wingo UI component reads its defaults from the provider (keyed by its data-slot name), so a whole project can switch to large, fully rounded buttons or a de-DE locale in one place. Props passed directly to a component still win.

API:
- `defaults?: Record<string, Record<string, unknown>>`: Default props per component, keyed by data-slot name, e.g. { button: { size: "lg", radius: "full" } }.
- `locale?: string`: Intl locale used by date, number and currency components (e.g. "en-GB"). Falls back to the browser locale.
- `reducedMotion?: "user" | "always" | "never"` = "user": user follows prefers-reduced-motion; always or never force it for every component.
- `inherit?: boolean` = true: Merge with an outer UIProvider instead of replacing it, so a section can override a few defaults.

Parts:
- `useDefaults` (hook): Used inside components: merges provider defaults under the received props (undefined props do not override). Signature: <P>(name: string, props: P) => P.
- `useUIConfig` (hook): Reads the merged config (defaults, locale, reducedMotion). Signature: () => UIConfig.

```tsx
import { UIProvider } from "@/lib/ui-config"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <UIProvider
      locale="en-GB"
      defaults={{
        button: { radius: "full", size: "lg" },
        input: { variant: "filled" },
      }}
    >
      {children}
    </UIProvider>
  )
}
```

Docs: https://wingo-ui.com/components/ui-config (Markdown: https://wingo-ui.com/components/ui-config.md)

#### useClipboard (`use-clipboard`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-clipboard`

Copy text to the clipboard with a copied flag that resets itself, and a fallback for pages without the Clipboard API.

Press Copy next to an IBAN, a tax ID or an invoice link: the icon turns into a check for the timeout and the last copied text shows below. Paste it anywhere to check. Set the timeout to 0 and the check stays until the next copy.

API:
- `timeout?: number` = 2000: How long copied stays true after a copy, in ms. 0 keeps it until reset() or the next copy.
- `onCopy / onError?: (text: string) => void / (error: Error) => void`: Called after each copy; the latest callbacks are always used, so there is nothing to memoize.
- `useClipboard?: (options?: { timeout?: number; onCopy?; onError? }) => { copy(source: string | (() => string | Promise<string>), options?: { html?: string }): Promise<boolean>; copied: boolean; error: Error | null; text: string | null; reset(): void }`: copy takes a string or a function read at click time (the latest form value, a link fetched on demand) and resolves true on success. Pass html to put a rich version next to the plain text.

Parts:
- `copyToClipboard` (function): The same copy without state, for event handlers: navigator.clipboard where it exists, a hidden textarea with execCommand on plain http and old webviews. Focus returns to where it was. Signature: (text: string, options?: { html?: string }) => Promise<boolean>.

```tsx
import { Check, Copy } from "lucide-react"
import { useClipboard } from "@/hooks/use-clipboard"

export function CopyIban({ iban }: { iban: string }) {
  const { copy, copied } = useClipboard()
  return (
    <button type="button" onClick={() => copy(iban)} aria-label={copied ? "Copied" : "Copy IBAN"}>
      {copied ? <Check /> : <Copy />}
    </button>
  )
}
```

Docs: https://wingo-ui.com/components/use-clipboard (Markdown: https://wingo-ui.com/components/use-clipboard.md)

#### useConsent (`use-consent`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-consent`

Cookie consent as state: which categories a visitor allowed, when and under which policy version, shared by banner, links and scripts.

Press Accept all or Reject all, or flip the categories and press Save choices: the record (method, time, choices) and the Google Consent Mode values update, and the video embed loads only once Marketing is allowed. Reset forgets the decision. Raise the policy version in the playground and the stored choice no longer counts, so the site would ask again. The choice survives a reload and, with local storage, follows you to other tabs.
Wingo UI dependencies: use-persisted-state

API:
- `version?: number` = 1: The policy version. Bump it when the categories or the policy change: records made under another version count as undecided.
- `storage?: "cookie" | "local" | "session"` = "cookie": Where the record lives. A cookie can be read on the server too (render nothing consent-dependent on the first paint when it is missing).
- `maxAgeDays?: number` = 180: How long a cookie choice is kept before the visitor is asked again.
- `storageKey?: string` = "ui-consent": Cookie / storage key. Every hook with the same key shares one record.
- `categories?: readonly string[]`: The category ids the site uses, default ["necessary", "preferences", "analytics", "marketing"]. necessary is always true.
- `useConsent?: (options?) => { record: ConsentRecord | null; decided; hydrated; choices; has(category); acceptAll(); rejectAll(); save(choices); reset() }`: record is { version, choices, decidedAt (ISO), method: accept-all | reject-all | custom } or null while undecided. hydrated is false on the server and during hydration: show the banner only once it is true and decided is false, so it never flashes for people who already chose.

Parts:
- `getConsent` (function): The same record outside React (a script loader, an analytics wrapper). Null on the server. Signature: (options?) => ConsentRecord | null.
- `hasConsent` (function): The same record outside React (a script loader, an analytics wrapper). Null on the server. Signature: (category, options?) => boolean.
- `setConsent` (function): Write a record outside React, and run code after every decision (load analytics when allowed, remove cookies when withdrawn). Signature: (record | null, options?) => void.
- `onConsentChange` (function): Write a record outside React, and run code after every decision (load analytics when allowed, remove cookies when withdrawn). Signature: (listener: (record, key) => void) => () => void.
- `openConsentSettings` (function): A "Cookie settings" link anywhere calls openConsentSettings(); the consent component listens with useConsentSettingsRequest and opens its settings. Signature: (storageKey?) => void.
- `useConsentSettingsRequest` (hook): A "Cookie settings" link anywhere calls openConsentSettings(); the consent component listens with useConsentSettingsRequest and opens its settings. Signature: (handler: () => void, storageKey?) => void.
- `toGoogleConsentMode` (function): Google Consent Mode v2 values for gtag("consent", "update", ...): analytics → analytics_storage, marketing → the three ad signals, preferences → functionality and personalization. Signature: (choices) => Record<string, "granted" | "denied">.
- `normalizeConsent` (function): Every category present with necessary forced on; the default ids and key. Signature: (choices, categories?) => ConsentChoices.
- `DEFAULT_CONSENT_CATEGORIES` (constant): Every category present with necessary forced on; the default ids and key. Type: readonly string[].
- `DEFAULT_CONSENT_KEY` (constant): Every category present with necessary forced on; the default ids and key. Type: string.

```tsx
import { useConsent } from "@/hooks/use-consent"

export function YoutubeEmbed({ id }: { id: string }) {
  const { hydrated, has, save, choices } = useConsent()
  if (!hydrated) return null
  if (!has("marketing"))
    return (
      <button type="button" onClick={() => save({ ...choices, marketing: true })}>
        Allow marketing cookies to watch the video
      </button>
    )
  return <iframe title="Northwind CRM tour" src={`https://www.youtube-nocookie.com/embed/${id}`} />
}
```

Docs: https://wingo-ui.com/components/use-consent (Markdown: https://wingo-ui.com/components/use-consent.md)

#### useControllableState (`use-controllable-state`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-controllable-state`

A state hook that is controlled when you pass a value and keeps its own state when you do not.

Both steppers run on the same hook. The first keeps its own count. The second is controlled by its parent, which caps it at 5 and can reset it, so you can see who owns the value.

API:
- `value?: T | undefined`: The controlled value. While it is defined the hook mirrors it and never stores its own; pass undefined to go uncontrolled.
- `defaultValue: T` = 2: The starting value while uncontrolled. Read once on mount, like useState.
- `onChange?: (value: T) => void`: Fires with the next value on every change, controlled or not. Skipped when the value did not change (Object.is).
- `returns?: [value: T, setValue: (next: T | ((prev: T) => T)) => void]`: The current value and a stable setter that takes a value or an updater, like useState. In controlled mode the setter only calls onChange; the parent decides.

```tsx
import { useControllableState } from "@/hooks/use-controllable-state"

type ToggleProps = {
  pressed?: boolean
  defaultPressed?: boolean
  onPressedChange?: (pressed: boolean) => void
}

export function Toggle({ pressed, defaultPressed = false, onPressedChange }: ToggleProps) {
  const [on, setOn] = useControllableState({
    value: pressed,
    defaultValue: defaultPressed,
    onChange: onPressedChange,
  })

  return (
    <button type="button" aria-pressed={on} onClick={() => setOn((prev) => !prev)}>
      {on ? "On" : "Off"}
    </button>
  )
}
```

Docs: https://wingo-ui.com/components/use-controllable-state (Markdown: https://wingo-ui.com/components/use-controllable-state.md)

#### useCooldown (`use-cooldown`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-cooldown`

A resend or retry timer: wait N seconds before a code can be sent again, exact after the tab sleeps and kept across reloads.

Press Resend code: the button locks and counts down (0:30, 0:29...) while the ring fills, then unlocks. Reload the page with a persist key and the wait continues where it was. Reset stops it at once. The label updates once a second, on the second.
Wingo UI dependencies: use-persisted-state

API:
- `seconds?: number` = 30: Length of one wait in seconds. start(seconds) overrides it for a single wait (a longer lock after 3 failed attempts).
- `autoStart?: boolean` = false: Start waiting on mount, for screens that open right after a code was sent (check your email, enter the SMS code). The server and hydration render the full wait, so the label never jumps.
- `persistKey?: string` = "": Keeps the end time in local storage under this key, so a reload does not unlock the button early. Empty keeps it in memory.
- `onEnd?: () => void`: Runs once when a wait reaches zero (not on reset).
- `useCooldown?: (options?: UseCooldownOptions) => Cooldown`: Returns { remaining (whole seconds), active, endsAt, label ("0:42"), progress (0 to 1 for a ring), start(seconds?), reset() }. It ticks with one timeout per second aligned to the end time: one re-render a second, exact after the tab sleeps.

Parts:
- `formatCooldown` (function): Minutes and zero-padded seconds: 42 is "0:42", 65 is "1:05". Signature: (seconds: number) => string.

```tsx
import { Button } from "@/components/ui/button"
import { useCooldown } from "@/hooks/use-cooldown"

export function ResendCode({ onResend }: { onResend: () => Promise<void> }) {
  const resend = useCooldown({ seconds: 30, autoStart: true, persistKey: "otp-resend" })

  return (
    <Button
      variant="link"
      disabled={resend.active}
      onClick={async () => {
        await onResend()
        resend.start()
      }}
    >
      {resend.active ? `Resend code in ${resend.label}` : "Resend code"}
    </Button>
  )
}
```

Docs: https://wingo-ui.com/components/use-cooldown (Markdown: https://wingo-ui.com/components/use-cooldown.md)

#### useDebounce (`use-debounce`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-debounce`

Debounced values and callbacks: search as you type without sending a request on every keystroke.

Type in the search field and watch the two counters: keystrokes climb on every letter, searches only fire once you pause. Press Enter to search at once (flush). Change the delay, add a leading call or a max wait in the playground and type again.

API:
- `delay?: number` = 300: Quiet time in ms before the call runs. 250 to 400 feels instant for search; 0 runs every call at once.
- `leading?: boolean` = false: Also run the first call of a burst at once (then wait for the quiet period before the next one).
- `maxWait?: number` = 0: Longest a call may wait while calls keep coming, in ms, for live previews that must update now and then. 0 means no limit.
- `useDebouncedCallback?: <A extends unknown[]>(callback: (...args: A) => void, delay?: number, options?: { leading?: boolean; maxWait?: number }) => DebouncedFunction<A>`: A stable function that runs callback with the latest arguments once calls stop for delay ms. It always calls the latest callback, so there is nothing to memoize. Pending calls are dropped on unmount.

Parts:
- `DebouncedFunction` (type): cancel drops the waiting call (clearing a field), flush runs it now (Enter in a search field), pending tells whether one is waiting. Type: ((...args: A) => void) & { cancel(): void; flush(): void; pending(): boolean }.
- `useDebouncedValue` (hook): The value, updated only after it stopped changing for delay ms. Handy as a query key: fetch when the debounced query changes. Signature: <T>(value: T, delay?: number) => T.

```tsx
import { useState } from "react"
import { useDebouncedCallback } from "@/hooks/use-debounce"

export function ListingSearch({ onSearch }: { onSearch: (query: string) => void }) {
  const [query, setQuery] = useState("")
  const search = useDebouncedCallback(onSearch, 300)

  return (
    <input
      type="search"
      value={query}
      placeholder="Search listings"
      onChange={(event) => {
        setQuery(event.target.value)
        search(event.target.value)
      }}
      onKeyDown={(event) => event.key === "Enter" && search.flush()}
    />
  )
}
```

Docs: https://wingo-ui.com/components/use-debounce (Markdown: https://wingo-ui.com/components/use-debounce.md)

#### useKeyboardInset (`use-keyboard-inset`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-keyboard-inset`

How much of the screen the phone's on-screen keyboard covers, as a motion value, so bars pinned to the bottom can ride above it.

Open the demo on a phone and tap the message field: as the keyboard slides up, the composer rides on top of it instead of hiding behind it, and the readout shows the covered height with the open flag lit. Close the keyboard and it settles back to the bottom. On a desktop there is no on-screen keyboard, so the inset stays 0px.

npm: motion

API:
- `threshold?: number` = 80: useKeyboardInset(options?): px of covered viewport below which it does not count as a keyboard (browser bars resizing, the iOS form accessory alone).
- `cssVar?: string` = "": Also writes the inset in px to this CSS variable on <html> (e.g. "--keyboard-inset"), for CSS-only consumers: bottom: var(--keyboard-inset, 0px). Removed on unmount; use one writer per variable.
- `disabled?: boolean` = false: Stops measuring and reports 0.
- `returns?: { inset: MotionValue<number>; open: boolean }`: inset: the covered height in px, updated as the keyboard animates without re-rendering; lift a bar with style={{ y: useTransform(inset, (v) => -v) }}. open: true while the keyboard is up, re-rendering only when it flips (hide a floating button, drop a tab bar). Both are 0 / false on the server, during hydration, on desktops, while pinch-zoomed and when no text field has focus.

```tsx
"use client"

import { motion, useTransform } from "motion/react"
import { useKeyboardInset } from "@/hooks/use-keyboard-inset"

export function Composer() {
  const { inset } = useKeyboardInset()
  const y = useTransform(inset, (v) => -v)

  return (
    <motion.form style={{ y }} className="fixed inset-x-0 bottom-0 z-sticky flex gap-2 bg-background p-3 pb-[max(env(safe-area-inset-bottom),12px)]">
      <input aria-label="Message" placeholder="Write a message" enterKeyHint="send" className="h-11 flex-1 rounded-full bg-foreground/5 px-4 text-base" />
    </motion.form>
  )
}
```

Docs: https://wingo-ui.com/components/use-keyboard-inset (Markdown: https://wingo-ui.com/components/use-keyboard-inset.md)

#### useLocale (`use-locale`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-locale`

The locale numbers, dates and prices are formatted with, the same on the server and in the browser.

The card formats one price, one date and one count with the resolved locale. Leave the locale empty to follow the page and the browser (after hydration), or pick one to see a component's own locale prop win. The provider example pins de-DE for everything inside it, on the server too.

API:
- `locale?: string` = "": useLocale(locale?): a component's own locale prop, which wins when set. Empty falls back to the nearest LocaleProvider, then (after hydration) <html lang> and the browser's language.
- `returns?: string`: A canonical BCP 47 tag. On the server and during hydration it is the provider's locale or DEFAULT_LOCALE ("en-US"), so both renders print the same text; the browser's language arrives right after.

Parts:
- `LocaleProvider` (component): Pins the locale for everything inside it, on the server too, so nothing swaps after hydration. Put one in the root layout of a Romanian app. Props: ({ locale: string; children }) => JSX.Element.
- `getBrowserLocale` (function): The page's lang, then navigator.language, for code outside React (event handlers). DEFAULT_LOCALE is the server fallback. Signature: () => string.
- `DEFAULT_LOCALE` (constant): The page's lang, then navigator.language, for code outside React (event handlers). DEFAULT_LOCALE is the server fallback. Type: "en-US".

```tsx
import { LocaleProvider, useLocale } from "@/hooks/use-locale"

export function Price({ value, locale }: { value: number; locale?: string }) {
  const resolved = useLocale(locale)
  return <span>{new Intl.NumberFormat(resolved, { style: "currency", currency: "USD", currencyDisplay: "narrowSymbol" }).format(value)}</span>
}

export function App({ children }: { children: React.ReactNode }) {
  // everything inside formats as en-GB, on the server and in the browser
  return <LocaleProvider locale="en-GB">{children}</LocaleProvider>
}
```

Docs: https://wingo-ui.com/components/use-locale (Markdown: https://wingo-ui.com/components/use-locale.md)

#### useLongPress (`use-long-press`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-long-press`

Press and hold on touch screens: pointer handlers that fire after a delay, cancel on scroll and swallow the click that follows.

Press and hold a message on a phone: it shrinks while you hold, then a reaction bar pops up and the phone buzzes where it can. Move your finger or scroll and nothing fires. With a mouse, right-click opens the same bar, or add mouse to pointerTypes in the playground to hold with the mouse too.
Wingo UI dependencies: motion

API:
- `onLongPress: (event: LongPressEvent<T>) => void`: useLongPress(onLongPress, options?): runs once the press has been held for delay ms. Gets the target element, the pointer position (clientX / clientY) and the pointer type.
- `delay?: number` = 450: Hold time in ms before it fires. The default is gestures.longPress from lib/motion, shared by every long press in the library.
- `slop?: number` = 8: How far in px the pointer may move before the press is cancelled, so scrolling a list never fires it (gestures.slop).
- `pointerTypes?: readonly ("touch" | "pen" | "mouse")[]` = "touch, pen": Which pointers can long press. A mouse is left out by default because right-click does the same job there.
- `haptics?: boolean` = true: A 10ms vibration when it fires, on devices that support it (Android). Silently skipped elsewhere.
- `disabled?: boolean` = false: Ignores every press.
- `onStart / onCancel / onFinish?: (event: LongPressEvent<T>) => void / () => void / () => void`: A press began (start a holding style), ended before firing (released early, moved, scrolled), or the finger lifted after it fired.
- `returns?: LongPressHandlers<T>`: onPointerDown, onPointerMove, onPointerUp, onPointerCancel, onPointerLeave, onContextMenu and onClickCapture, to spread on the element (or on a Radix trigger through asChild, which merges them). Add select-none [-webkit-touch-callout:none] to the element so iOS shows no callout.

```tsx
import { useState } from "react"
import { useLongPress } from "@/hooks/use-long-press"

export function MessageBubble({ text }: { text: string }) {
  const [menu, setMenu] = useState(false)
  const longPress = useLongPress<HTMLDivElement>(() => setMenu(true))

  return (
    <div
      {...longPress}
      onContextMenu={(event) => {
        // right-click with a mouse opens the same menu
        longPress.onContextMenu(event)
        event.preventDefault()
        setMenu(true)
      }}
      className="select-none rounded-2xl bg-foreground/5 px-3 py-2 [-webkit-touch-callout:none]"
    >
      {text}
      {menu && <span>Reactions</span>}
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/use-long-press (Markdown: https://wingo-ui.com/components/use-long-press.md)

#### useMediaControls (`use-media-controls`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-media-controls`

State and actions of an audio or video element for custom players: play, seek, volume, speed, buffering and a smooth playhead.

Press play on the podcast: the bar glides every frame while the time text changes once a second. Tap or drag on the bar to seek, change the speed and mute. With the player focused, Space or k plays and pauses, Left / Right seek by the step, j / l by twice that, Up / Down change the volume, m mutes, 0 to 9 jump to 0% to 90%, < and > change the speed. Turn exclusive on and starting one voice message pauses the other and the podcast.

npm: motion

API:
- `exclusive?: boolean` = false: Starting this player pauses every other exclusive player on the page (voice messages in a chat, a list of episodes).
- `defaultRate?: number` = 1: The playback speed applied when the element attaches (defaultVolume 0 to 1 and defaultMuted work the same way).
- `seekStep?: number` = 5: handleMediaKey(event, controls, { seekStep }): seconds for Left / Right; j / l seek twice as far.
- `defaultVolume / defaultMuted?: number / boolean` = 1: Applied when the element attaches.
- `onPlay / onPause / onEnded / onError / onTimeUpdate?: () => void / (error: MediaError | null) => void / (seconds: number) => void`: Lifecycle callbacks; onTimeUpdate fires with whole seconds (resume positions, analytics). The latest callbacks are always used.
- `useMediaControls?: (options?) => MediaControls`: Returns { ref (put it on the <audio> / <video>; destructure it, const { ref, ...media } = useMediaControls(), because the React compiler lint treats an object whose field feeds a ref prop as a ref), element, playing, waiting (buffering), ended, ready, error, duration, second (whole seconds as state, re-renders at most once a second), currentTime / progress / buffered (motion values, progress and buffered 0 to 1, updated every frame while playing), volume, muted, rate, play() (resolves false when the browser blocks it), pause(), toggle(), seek(seconds), seekBy(delta), seekToFraction(0..1), setVolume, setMuted, toggleMute, setRate }.

Parts:
- `handleMediaKey` (function): The shared keyboard map for onKeyDown on a player root. Leaves sliders, inputs, menus and listboxes alone; returns true (and prevents the default) when it handled the key. Signature: (event, controls, options?: { seekStep?: number = 5; volumeStep?: number = 0.1; rates?: number[]; volumeKeys?: boolean = true }) => boolean.
- `formatMediaTime` (function): "0:42", "12:05", "1:02:03"; unknown or live durations print "--:--". forceHours keeps the text width stable in long videos. Signature: (seconds: number, options?: { forceHours?: boolean }) => string.
- `MEDIA_RATES` (constant): 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2: the speed menu of every player. Type: readonly number[].

```tsx
import { motion } from "motion/react"
import { formatMediaTime, handleMediaKey, useMediaControls } from "@/hooks/use-media-controls"

export function VoiceNote({ src }: { src: string }) {
  // destructure ref: reading media.ref for the ref prop makes the react compiler treat all of media as a ref
  const { ref, ...media } = useMediaControls({ exclusive: true })
  return (
    <div tabIndex={0} onKeyDown={(event) => handleMediaKey(event, media)} className="flex items-center gap-3">
      <audio ref={ref} src={src} preload="metadata" />
      <button type="button" onClick={media.toggle}>{media.playing ? "Pause" : "Play"}</button>
      <div className="h-1 flex-1 overflow-hidden rounded-full bg-foreground/10">
        <motion.div className="h-full origin-left bg-foreground" style={{ scaleX: media.progress }} />
      </div>
      <span className="tabular-nums">{formatMediaTime(media.playing ? media.second : media.duration)}</span>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/use-media-controls (Markdown: https://wingo-ui.com/components/use-media-controls.md)

#### useMediaQuery (`use-media-query`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-media-query`

SSR-safe hooks for media queries, phone widths, touch screens and the current Tailwind breakpoint.

Resize the window, switch to the phone frame or change your system settings: the readout follows along live. Type any media query into the playground to test it.

API:
- `query: string` = "(min-width: 1024px)": useMediaQuery(query, serverFallback?): any CSS media query. Returns true while it matches and re-renders when that flips.
- `serverFallback?: boolean` = false: What useMediaQuery returns on the server and during hydration, before the browser can answer. Pick the value your server layout assumes.
- `constants?: MOBILE_QUERY, TOUCH_QUERY, HOVER_QUERY, REDUCED_MOTION_QUERY, DARK_SCHEME_QUERY, BREAKPOINTS`: The shared queries and breakpoint widths, so every component agrees on what mobile means.

Parts:
- `useIsMobile` (hook): True below 768px (Tailwind md). The switch point where popovers, selects and menus become bottom sheets. Signature: () => boolean.
- `useIsTouch` (hook): True when the primary pointer is coarse (a finger). Use it for 44px targets and to skip hover-only affordances. Signature: () => boolean.
- `useBreakpoint` (hook): The widest Tailwind breakpoint that matches, with one subscription for all of them. Signature: (serverFallback?: Breakpoint) => "base" | "sm" | "md" | "lg" | "xl" | "2xl".
- `matchesMedia` (function): The same check outside render, for event handlers and effects. False on the server. Signature: (query: string) => boolean.
- `useIsApple` (hook): Whether the device is a Mac, iPhone or iPad, for shortcut notation (⌘K vs Ctrl+K) and for binding mod to the meta key. The hook is false on the server and during hydration. Signature: () => boolean.
- `isApple` (function): Whether the device is a Mac, iPhone or iPad, for shortcut notation (⌘K vs Ctrl+K) and for binding mod to the meta key. The hook is false on the server and during hydration. Signature: () => boolean.

```tsx
import { useBreakpoint, useIsMobile, useIsTouch, useMediaQuery } from "@/hooks/use-media-query"

export function PhotoGrid({ photos }: { photos: string[] }) {
  const isMobile = useIsMobile()
  const isTouch = useIsTouch()
  const breakpoint = useBreakpoint()
  const landscape = useMediaQuery("(orientation: landscape)")
  const columns = isMobile ? (landscape ? 3 : 2) : breakpoint === "2xl" ? 5 : 4

  return (
    <ul className="grid gap-2" style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }}>
      {photos.map((src) => (
        // touch screens have no hover, so the caption is always visible there
        <li key={src} className="group relative">
          <img src={src} alt="" className="aspect-square w-full rounded-xl object-cover" />
          <span className={isTouch ? "absolute bottom-2 left-2" : "absolute bottom-2 left-2 opacity-0 group-hover:opacity-100"}>View</span>
        </li>
      ))}
    </ul>
  )
}
```

Docs: https://wingo-ui.com/components/use-media-query (Markdown: https://wingo-ui.com/components/use-media-query.md)

#### useOverflowItems (`use-overflow-items`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-overflow-items`

Priority+ overflow for a row of items: shows as many as fit and moves the rest into a More menu, measured live as the row resizes.

Drag the corner of the panel to make it narrower or wider: actions that no longer fit fold into the More button one by one, and come back as soon as there is room. The breadcrumb collapses from the middle, keeping the first page and the current one. Open More to reach the hidden actions with the keyboard or a tap.

API:
- `count: number`: useOverflowItems(options): how many items the row renders. Every item gets getItemProps(index) spread on its outermost element.
- `collapseOrder?: "end" | "start" | "middle" | readonly number[]` = "end": Which items fold first. end: the last one (actions, tabs). start: the first one. middle: from the second item on, keeping the first and last (breadcrumbs). Or explicit indexes, first to fold first.
- `pinned?: readonly number[]`: Indexes that never fold: the primary action, the current page of a breadcrumb.
- `minVisible?: number` = 0: Never fold below this many visible items, even if they overflow.
- `reserve?: number` = 0: Pixels of the row kept free for something you do not measure (a title that must keep its space).
- `gap?: number`: Pixels between items. Default: read from the row's computed column-gap, so gap-2 just works.
- `disabled?: boolean` = false: Show every item and stop measuring, e.g. below a breakpoint where CSS already switched to another layout.
- `returns?: { containerRef; getItemProps(index); getMoreProps(); isHidden(index); hiddenIndexes: number[]; overflowing: boolean; measured: boolean }`: containerRef goes on the row (its content width is the budget). Spread getItemProps(i) on each item and getMoreProps() on the More trigger: a folded item stays mounted but invisible, out of the flow, inert and aria-hidden, so it is measured all the time and returns the moment there is room. Render hiddenIndexes in the overflow menu. Items should be shrink-0 and whitespace-nowrap. measured is false on the server and before the first measurement: keep the row overflow-hidden until then.

```tsx
import { MoreHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { useOverflowItems } from "@/hooks/use-overflow-items"

const ACTIONS = ["Edit", "Duplicate", "Download PDF", "Send by email", "Archive"]

export function InvoiceActions() {
  const { containerRef, getItemProps, getMoreProps, hiddenIndexes } = useOverflowItems({ count: ACTIONS.length })

  return (
    <div ref={containerRef} className="relative flex min-w-0 items-center gap-2 overflow-hidden">
      {ACTIONS.map((label, i) => (
        <Button key={label} variant="outline" size="sm" className="shrink-0" {...getItemProps(i)}>
          {label}
        </Button>
      ))}
      <Button variant="ghost" size="icon-sm" aria-label={`${hiddenIndexes.length} more actions`} {...getMoreProps()}>
        <MoreHorizontal />
      </Button>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/use-overflow-items (Markdown: https://wingo-ui.com/components/use-overflow-items.md)

#### usePersistedState (`use-persisted-state`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-persisted-state`

useState that survives reloads in localStorage, sessionStorage or a cookie, syncs across components and tabs, and hydrates cleanly.

Switch the listing view in either card: the other card follows at once because both read the same key. Type a message: it is saved as you type. Press Reload to remount the demo and watch every value come back, or Delete draft to forget the draft. Open the page in a second tab and changes in local storage follow you there.
Wingo UI dependencies: use-controllable-state

API:
- `key: string | null | undefined` = "ui-lab:preferences": usePersistedState(key, defaultValue, options?): the storage key. null or an empty string turns persistence off (plain useState), so a component can take an optional persistKey prop.
- `defaultValue: T`: The value on the server, during hydration and whenever nothing is stored. The stored value replaces it right after hydration, so markup never mismatches.
- `storage?: "local" | "session" | "cookie"` = "local": Where the value lives. cookie is the one a server can read: a Next layout reads cookies().get(persistedCookieName(key)) and passes the value as defaultValue, so a collapsed sidebar is collapsed on the first paint.
- `syncTabs?: boolean` = true: Follow changes made in other tabs (local storage only). Instances on the same page always stay in sync.
- `serialize / deserialize?: (value: T) => string / (raw: string) => T`: How the value becomes a string and back. Default JSON; a stored value that fails to parse falls back to defaultValue.
- `maxAge?: number` = 31536000: Cookie lifetime in seconds (one year).
- `returns?: [value: T, setValue: (next: SetStateAction<T>) => void, meta: { hydrated: boolean; remove(): void }]`: Like useState. meta.hydrated is false on the server and during hydration, so a component can skip the animation of the restore that follows. meta.remove forgets the stored value. Storage that throws (private mode, a full quota, blocked cookies) keeps working in memory for the session.

Parts:
- `usePersistedControllableState` (hook): The controlled / uncontrolled pattern of useControllableState with the uncontrolled value persisted: collapsed / defaultCollapsed / onCollapsedChange plus persistKey in one line. A controlled value is never written to storage. Signature: ({ key, value?, defaultValue, onChange?, ...options }) => [T, setValue, meta].
- `readPersisted` (function): The raw string outside React (handlers, other stores); writes notify every hook reading the key. persistedCookieName gives the cookie name for server code. Signature: (key, storage?) => string | null.
- `writePersisted` (function): The raw string outside React (handlers, other stores); writes notify every hook reading the key. persistedCookieName gives the cookie name for server code. Signature: (key, raw | null, storage?, maxAge?) => void.
- `persistedCookieName` (function): The raw string outside React (handlers, other stores); writes notify every hook reading the key. persistedCookieName gives the cookie name for server code. Signature: (key) => string.

```tsx
import { usePersistedState } from "@/hooks/use-persisted-state"

export function ListingsView() {
  const [view, setView] = usePersistedState<"list" | "grid">("listings:view", "list")

  return (
    <div role="group" aria-label="View" className="inline-flex gap-1">
      <button type="button" aria-pressed={view === "list"} onClick={() => setView("list")}>List</button>
      <button type="button" aria-pressed={view === "grid"} onClick={() => setView("grid")}>Grid</button>
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/use-persisted-state (Markdown: https://wingo-ui.com/components/use-persisted-state.md)

#### useScrollEdges (`use-scroll-edges`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-scroll-edges`

Knows which edges of a scroll container have more content, and fades them out with a mask that eases in as you scroll.

Scroll the notification list: the top fades in as content slides under the header, a hairline appears below the title, and the bottom fade melts away as you reach the end. Swipe the category rail sideways: the edges fade the same way and the arrow buttons (on desktop) hide at each end.

API:
- `fade?: number` = 24: useScrollEdges(options?): the largest fade in px. The hook writes --fade-top, --fade-bottom, --fade-left and --fade-right on the element, each growing with the distance to its edge, so a fade eases out as you reach the end instead of popping.
- `threshold?: number` = 1: Distance in px from an edge that still counts as being at it (absorbs sub-pixel scroll positions).
- `disabled?: boolean` = false: Stops measuring; the fades stay at their last size.
- `returns?: { ref: RefCallback<T>; edges: ScrollEdges; overflow: { x: boolean; y: boolean } }`: ref goes on the scrolling element (a plain overflow div or a Radix ScrollArea viewport). edges says where more content lies ({ top, bottom, left, right }) and overflow whether it scrolls at all; both re-render only when a value flips, never per scroll frame. Handles RTL.

Parts:
- `fadeMaskStyle` (function): A mask-image style driven by the vars above. Spread it into the same element's style. It needs no background color, so it works on any surface in both themes. Signature: (axis?: "x" | "y" | "both") => CSSProperties.

```tsx
import { fadeMaskStyle, useScrollEdges } from "@/hooks/use-scroll-edges"
import { cn } from "@/lib/utils"

export function Notifications({ items }: { items: string[] }) {
  const { ref, edges } = useScrollEdges<HTMLUListElement>()

  return (
    <section className="flex max-h-80 flex-col">
      <h2 className={cn("px-4 py-3 text-[15px] font-semibold", edges.top && "border-b border-foreground/10")}>Notifications</h2>
      <ul ref={ref} style={fadeMaskStyle("y")} className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4">
        {items.map((item) => (
          <li key={item} className="py-3 text-sm">{item}</li>
        ))}
      </ul>
    </section>
  )
}
```

Docs: https://wingo-ui.com/components/use-scroll-edges (Markdown: https://wingo-ui.com/components/use-scroll-edges.md)

#### useScrollState (`use-scroll-state`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-scroll-state`

Scroll offset, progress and hide-on-scroll state for the window or any container, as motion values that move bars without re-renders.

Scroll the feed in the phone frame: the top bar slides away with your finger as you scroll down and comes back the moment you scroll up, then settles fully shown or hidden when you stop. The progress line under it fills as you read, the large title fades into the bar, and a back-to-top button appears once you pass the threshold. The readout shows direction, scrolled and hidden flipping without a render per frame.

npm: motion
Wingo UI dependencies: use-media-query, motion

API:
- `hideOnScroll?: boolean` = false: useScrollState(options?): track hideProgress and hidden for a bar that slides away while you scroll down. Off by default, so hooks that only read the offset do no extra work.
- `hideDistance?: number` = 56: Pixels of scrolling that take a bar from shown to hidden, usually the bar's own height, so it moves 1:1 with the content.
- `hideOffset?: number` = 0: The bar never hides above this offset, e.g. while a page header is still on screen. It can always come back.
- `snap?: boolean` = true: After scrolling stops, a half-hidden bar settles to shown or hidden on the snappy spring.
- `revealAtEnd?: boolean` = true: Bring the bar back at the very end of the content, where nothing is left to uncover.
- `scrolledThreshold?: number` = 1: scrolled turns true past this many pixels: 1 for a header hairline, 400 for a back-to-top button.
- `target?: HTMLElement | Window | RefObject<HTMLElement | null> | null`: What to watch. Default: the nearest ScrollContainerProvider, else the window. A ref is read after mount; pass the element itself when it can change.
- `disabled?: boolean` = false: Stops listening; the values keep their last state.
- `returns?: { offset: MotionValue<number>; progress: MotionValue<number>; hideProgress: MotionValue<number>; direction: "up" | "down" | null; scrolled: boolean; hidden: boolean; atEnd: boolean; scrollTo(top, { smooth? }): void }`: offset (px, negative during an iOS bounce), progress (0 to 1) and hideProgress (0 shown to 1 hidden, following the finger) are motion values: feed them to useTransform and style. direction, scrolled, hidden and atEnd re-render only when they flip. scrollTo is smooth unless the user prefers reduced motion; under reduced motion hideProgress only ever jumps between 0 and 1.

Parts:
- `ScrollContainerProvider` (component): Declares the element that scrolls for everything inside it (an app shell's content area, a demo box, a phone frame). Keep the element in state through a callback ref so the children update once it mounts. Props: ({ value: HTMLElement | null; children }) => JSX.Element.
- `useScrollContainer` (hook): The nearest provided scroll container, or null for the window. Scroll spies use it as their IntersectionObserver root. Signature: () => HTMLElement | null.
- `findScrollParent` (function): The nearest vertically scrolling ancestor (null for the window), and a reduced-motion-aware scrollTo that works outside React. Signature: (element) => HTMLElement | null.
- `scrollToOffset` (function): The nearest vertically scrolling ancestor (null for the window), and a reduced-motion-aware scrollTo that works outside React. Signature: (target, top, smooth?) => void.

```tsx
import { motion, useTransform } from "motion/react"
import { useScrollState } from "@/hooks/use-scroll-state"
import { cn } from "@/lib/utils"

export function AppHeader() {
  const { hideProgress, scrolled } = useScrollState({ hideOnScroll: true, hideDistance: 56 })
  const y = useTransform(hideProgress, [0, 1], [0, -56])

  return (
    <motion.header
      style={{ y }}
      className={cn(
        "sticky top-0 z-sticky flex h-14 items-center bg-background/80 px-4 backdrop-blur-xl",
        scrolled && "border-b border-foreground/10",
      )}
    >
      <h1 className="text-[17px] font-semibold">Listings in New York</h1>
    </motion.header>
  )
}
```

Docs: https://wingo-ui.com/components/use-scroll-state (Markdown: https://wingo-ui.com/components/use-scroll-state.md)

#### useSelection (`use-selection`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-selection`

Selection state for lists and grids: single or multiple, shift-click ranges, select all with an indeterminate state.

Tick customers in the list; hold Shift and tick another to select everything between them. The header checkbox shows the indeterminate state and selects or clears all (the archived customer stays unselectable). Switch to single mode to pick one at a time; clicking it again clears it.
Wingo UI dependencies: use-controllable-state

API:
- `mode?: "single" | "multiple"` = "multiple": single keeps at most one key (radio-like rows); multiple is for bulk actions.
- `allowDeselect?: boolean` = true: Single mode: selecting the selected key again clears the selection.
- `keys: readonly string[]`: Every selectable key in display order. Shift ranges walk this order; select all takes all of them.
- `value / defaultValue / onValueChange?: string[]`: Controlled or uncontrolled through useControllableState. onValueChange gets the keys in display order.
- `disabledKeys?: readonly string[]`: Keys that cannot be selected: toggle ignores them, ranges and select all skip them.
- `useSelection (result)?: { selected; isSelected(key); isDisabled(key); toggle(key, { range?, additive? }); handleSelect(key, event); select; deselect; selectRange(from, to); selectAll; clear; setSelected(keys); toggleAll; allSelected; someSelected; checkedState: boolean | "indeterminate"; count }`: handleSelect reads shiftKey from the click or key event (pass it straight from onClick / onCheckedChange's event). checkedState feeds a header Checkbox. Rendering stays yours: aria-selected / aria-checked and data-selected on the rows.

```tsx
import { useSelection } from "@/hooks/use-selection"

const clients = [
  { id: "c1", name: "Northwind Tech LLC" },
  { id: "c2", name: "Summit Logistics Inc." },
  { id: "c3", name: "Greenleaf Pharmacy" },
]

export function ClientPicker() {
  const selection = useSelection({ keys: clients.map((c) => c.id) })
  return (
    <ul>
      {clients.map((client) => (
        <li key={client.id}>
          <label>
            <input
              type="checkbox"
              checked={selection.isSelected(client.id)}
              onClick={(event) => selection.handleSelect(client.id, event)}
              readOnly
            />
            {client.name}
          </label>
        </li>
      ))}
    </ul>
  )
}
```

Docs: https://wingo-ui.com/components/use-selection (Markdown: https://wingo-ui.com/components/use-selection.md)

#### useShortcut (`use-shortcut`)

hook · free · v1.0.0 · install: `npx wingo-ui@latest add use-shortcut`

Keyboard shortcuts in mod+k notation: bind them, match events and show them as ⌘K on a Mac or Ctrl+K elsewhere.

Press the shortcuts listed in the panel: the matching row lights up and the log says what ran. Type a combo into the playground (mod+k, shift+?, alt+n) to bind it live and see how it reads on Apple devices and everywhere else. Single keys like / stay quiet while you type in the search field; combos with a modifier still work there.
Wingo UI dependencies: use-media-query

API:
- `shortcut: string | readonly string[] | null | undefined | false` = "mod+k": useShortcut(shortcut, handler, options?): the combo in mod+k notation ("shift+mod+p", "alt+n", "/", "escape"). mod is ⌘ on Apple devices and Ctrl elsewhere. Pass an array for alternatives; null, "" or false binds nothing, so a component can take a shortcut prop its caller clears.
- `handler: (event: KeyboardEvent) => void`: Runs when the shortcut is pressed. It may change on every render; the listener is not re-added.
- `enabled?: boolean` = true: Turns the binding off without unmounting, for example while a panel is closed.
- `allowInInputs?: boolean`: Fire while focus is in a text field. By default only combos with ctrl, meta, mod or alt do, so a bare / or ? never steals a keystroke from someone typing.
- `preventDefault?: boolean` = true: Calls event.preventDefault() when the shortcut fires, so mod+s does not also open the browser's save dialog.
- `repeat?: boolean` = false: Fire again while the key is held down.
- `capture?: boolean` = false: Listen in the capture phase, before handlers inside the page.

Parts:
- `useShortcutLabel` (hook): The display form for the current device: keys ["⇧", "⌘", "P"] for separate key caps, text "⇧⌘P" (Ctrl+Shift+P elsewhere) for menus, aria for aria-keyshortcuts. Renders the non-Apple form on the server, then swaps. Signature: (shortcut: string | null | undefined) => { keys: string[]; text: string; aria: string | undefined }.
- `formatShortcut` (function): The same labels outside React, for a given platform. Signature: (shortcut: string, apple: boolean) => string[].
- `formatShortcutText` (function): The same labels outside React, for a given platform. Signature: string.
- `matchesShortcut` (function): True when a keyboard event (DOM or React) is exactly this combo. Falls back to the physical key when the layout types a non-Latin character, so mod+k also works on a Romanian or Cyrillic layout and with Option held on a Mac. Signature: (event: ShortcutEvent, shortcut: string | ParsedShortcut, apple?: boolean) => boolean.
- `parseShortcut` (function): The parsed combo (cached), the value for aria-keyshortcuts, and whether focus sits in an input, textarea, select or contenteditable element. Signature: (shortcut: string) => ParsedShortcut | null.
- `ariaKeyShortcuts` (function): The parsed combo (cached), the value for aria-keyshortcuts, and whether focus sits in an input, textarea, select or contenteditable element. Signature: (shortcut, apple) => string | undefined.
- `isTypingTarget` (function): The parsed combo (cached), the value for aria-keyshortcuts, and whether focus sits in an input, textarea, select or contenteditable element. Signature: (target) => boolean.

```tsx
import { useRef } from "react"
import { useShortcut, useShortcutLabel } from "@/hooks/use-shortcut"

export function SearchField() {
  const input = useRef<HTMLInputElement>(null)
  const label = useShortcutLabel("/")

  // a bare "/" is ignored while someone types in another field
  useShortcut("/", () => input.current?.focus())
  useShortcut("mod+k", () => input.current?.focus())

  return (
    <label className="flex items-center gap-2">
      <input ref={input} placeholder="Search listings" aria-keyshortcuts={label.aria} />
      <kbd>{label.text}</kbd>
    </label>
  )
}
```

Docs: https://wingo-ui.com/components/use-shortcut (Markdown: https://wingo-ui.com/components/use-shortcut.md)

#### useStickToBottom (`use-stick-to-bottom`)

hook · Pro · v1.0.0 · install: `npx wingo-ui@latest add use-stick-to-bottom`

Keeps a chat, a log or streaming output pinned to its bottom while it grows, and lets go the moment the reader scrolls up.

The demo plays a conversation whose answers stream in word by word, and the panel follows them down. Scroll up with the wheel, a finger or the keys while an answer is still arriving: following stops at once (isFollowing turns off), the text keeps growing below and a New messages button appears. Tap it, or scroll back to the end, and it follows again. Pause stops the script.
Wingo UI dependencies: motion

API:
- `enabled?: boolean` = true: useStickToBottom(options?): follow new content while the reader is at the bottom. false never scrolls by itself (scrollToBottom still works).
- `threshold?: number` = 72: Distance in px from the bottom that still counts as at the bottom: isAtBottom, and where scrolling back down re-sticks.
- `initial?: "instant" | "smooth" | false` = "instant": How to reach the bottom when the scroller attaches (opening a conversation). false starts at the top and does not follow until the reader scrolls down.
- `resize?: "smooth" | "instant"` = "smooth": How to follow content that grows while stuck: smooth eases toward a bottom that is re-read every frame, so a streaming answer glides; instant jumps. Reduced motion always jumps.
- `returns?: { scrollRef; contentRef; isAtBottom: boolean; isFollowing: boolean; scrollToBottom(behavior?): void; stopFollowing(): void }`: scrollRef goes on the overflow-y-auto element, contentRef on the element inside it that grows (defaults to the first child). isAtBottom and isFollowing re-render only when they flip: show a jump-to-latest button while !isAtBottom. scrollToBottom scrolls down and follows again (call it after sending a message); stopFollowing lets go without scrolling.

```tsx
"use client"

import { useStickToBottom } from "@/hooks/use-stick-to-bottom"
import { Button } from "@/components/ui/button"

export function Conversation({ messages }: { messages: { id: string; text: string }[] }) {
  const { scrollRef, contentRef, isAtBottom, scrollToBottom } = useStickToBottom()

  return (
    <div className="relative h-96">
      <div ref={scrollRef} className="h-full overflow-y-auto overscroll-contain">
        <div ref={contentRef} className="flex flex-col gap-3 p-4">
          {messages.map((m) => <p key={m.id}>{m.text}</p>)}
        </div>
      </div>
      {!isAtBottom && (
        <Button size="sm" radius="full" className="absolute bottom-3 left-1/2 -translate-x-1/2" onClick={() => scrollToBottom()}>
          New messages
        </Button>
      )}
    </div>
  )
}
```

Docs: https://wingo-ui.com/components/use-stick-to-bottom (Markdown: https://wingo-ui.com/components/use-stick-to-bottom.md)

## Blog

### 100vh Mobile Fix: When to Use dvh, svh or lvh in Tailwind

> The 100vh mobile bug explained: why h-screen hides your bottom bar, when to use dvh, svh or lvh in Tailwind, and how to keep a bar above the keyboard.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind

#### TL;DR

On phones, 100vh (Tailwind's h-screen) is measured with the browser toolbars hidden, so it is taller than the visible screen and the bottom of the layout sits under the address bar. In Tailwind, use min-h-dvh or h-dvh for app shells, a cap such as max-h-[92dvh] for bottom sheets, min-h-svh for heroes that scroll away, h-lvh only for fixed backgrounds, and fixed inset-0 for overlays. No viewport unit shrinks for the on-screen keyboard by default, so a bar that must stay above it needs window.visualViewport.

You give a chat screen `h-screen`, put the composer at the bottom of a flex column, and on an iPhone the composer is gone. It sits under Safari's toolbar, and the whole page scrolls by the height of that toolbar. That is the 100vh mobile bug, and browsers behave this way on purpose. This tutorial explains what 100vh measures on a phone, when to use dvh, svh or lvh in Tailwind CSS, and how to build a full-height shell, sheets and a keyboard-aware bar that stay put when the address bar moves. The code is Next.js App Router and Tailwind v4, with the Wingo UI components that follow the same rules.

#### Why is 100vh taller than the screen on mobile?

Because `vh` is measured with the browser toolbars hidden. A mobile browser has three viewport heights: small, with the address bar and toolbars expanded; large, with them retracted; and dynamic, whichever applies right now. [MDN's length reference](https://developer.mozilla.org/en-US/docs/Web/CSS/length) is explicit: "Currently, all default viewport units (vh, vw, etc.) are equivalent to their large viewport counterparts (lvh, lvw, etc.)."

Every page loads with the toolbars showing, so 100vh starts out taller than the visible area by their height. Tailwind's `h-screen` compiles to exactly that, `100vh`, in Tailwind 4.3 as in v3.

This is the classic 100vh mobile Safari complaint. Since iOS 15, Safari puts its address bar at the bottom by default, so the strip that 100vh hides is where your primary button lives. Chrome on Android follows the same model on purpose: when Chrome 56 changed `vh`, [the Chrome team wrote](https://developer.chrome.com/blog/url-bar-resizing) that the new model "should match how Safari behaves."

On a desktop, and in a web app installed to the home screen, no toolbars come and go, so the three heights are equal and the bug never shows up.

#### What is the difference between dvh, svh and lvh?

`svh` is the height with the toolbars showing, `lvh` the height with them hidden, and `dvh` whichever is true at the moment. All three are percentages, so `100dvh` is the full dynamic height:

| Unit | dvh | svh | lvh |
| --- | --- | --- | --- |
| Measures | The visible height right now | The height with the toolbars expanded | The height with the toolbars retracted, same as vh |
| Changes while the page scrolls | Yes, as the toolbars move | No | No |
| Tailwind classes | `h-dvh`, `min-h-dvh`, `max-h-dvh` | `h-svh`, `min-h-svh`, `max-h-svh` | `h-lvh`, `min-h-lvh`, `max-h-lvh` |
| Use it for | Shells, sheets, anything that stays on screen | Heroes and first screens that scroll away | Fixed backgrounds that must never show a gap |

The dynamic unit has two catches. Browsers throttle it: [web.dev's introduction to the units](https://web.dev/blog/viewport-units) says the values "do not update at 60fps." And everything sized with it reflows when it does update. [WebKit bug 266835](https://bugs.webkit.org/show_bug.cgi?id=266835), filed against iOS 17.2.1 and titled "dvh causes scroll jank as the address bar resizes when scrolling", shows full-height dvh sections that "don't resize to the larger viewport height until after scrolling has finished," so the layout jumps once the scroll ends. As of October 2026 the report is still open.

Support is no longer a reason to wait. Safari 15.4, Firefox 101 and Chrome 108 shipped all three units, and [caniuse](https://caniuse.com/viewport-unit-variants) counts about 95% of global usage as supported as of October 2026. The Tailwind dvh, svh and lvh classes [arrived in v3.4](https://tailwindcss.com/blog/tailwindcss-v3-4), and Tailwind v4 itself [requires](https://tailwindcss.com/docs/compatibility) Safari 16.4, Chrome 111 and Firefox 128, so a v4 project needs no `vh` fallback.

#### When should you use dvh, svh or lvh?

Use dvh for what stays on screen, svh for what scrolls away, lvh only for fixed backgrounds, and no unit at all for a fixed element pinned to two opposite edges. Applied to the usual parts of an app:

- **App shell root:** `min-h-dvh` when the window scrolls, `h-dvh` when an inner column scrolls.
- **Bottom sheets, popovers, menus:** a cap such as `max-h-[92dvh]`.
- **Side panels, overlays, full-screen menus:** `fixed inset-0` or `fixed inset-y-0`. A fixed element sized by its edges follows the visible area as the toolbars move; Chrome kept that behavior when it changed `vh` in version 56.
- **Marketing hero or first screen:** `min-h-svh`. It fills the screen on load with the toolbars showing and never grows under the reader's thumb.
- **Fixed background image or canvas:** `fixed inset-x-0 top-0 h-lvh`. As tall as the screen can get, it never uncovers a gap and never resizes.

That settles 100dvh vs 100vh: we have not found a case where plain `vh` is the better choice, and when you want its behavior, `lvh` says so. No Wingo UI component uses `h-screen` or sizes a full-height layout in `vh`; the full-height ones use `min-h-dvh`, `h-dvh` and dvh caps.

If an existing codebase is full of `h-screen`, you can retarget the class in one place. In Tailwind v4, a custom utility with the name of a core utility adds its declarations after the core ones:

```css
/* app/globals.css: a stopgap that turns every h-screen into dvh */
@utility h-screen {
  height: 100dvh;
}
@utility min-h-screen {
  min-height: 100dvh;
}
```

With Tailwind 4.3.3 this compiles `h-screen` and `md:h-screen` to `height: 100vh; height: 100dvh;`, so a browser without dvh keeps the old value. It also turns every hero into a dvh hero, so follow it up: search for `h-screen` and pick a unit for each one.

#### How do you build a full-height app shell that does not jump?

Let the document scroll, give the shell `min-h-dvh`, pin the header with `sticky` and the tab bar with `fixed`. Nothing on the page then depends on the toolbar height, so nothing moves when it changes.

##### Step 1: let the page reach the screen edges

Opt into the area around the notch and the home indicator, so `env(safe-area-inset-*)` returns real values. In the App Router that is the `viewport` export of the root layout:

```tsx
// app/layout.tsx
import type { Viewport } from "next";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};
```

The [Tailwind safe area guide](https://wingo-ui.com/blog/tailwind-safe-area-insets) covers the insets in depth; here they only pad the bars.

##### Step 2: a shell that scrolls the window

```tsx
// app/(app)/layout.tsx
import type { ReactNode } from "react";

export default function AppLayout({ children }: { children: ReactNode }) {
  return (
    <div className="flex min-h-dvh flex-col bg-background">
      <header className="sticky top-0 z-40 bg-background/90 pt-[env(safe-area-inset-top)] backdrop-blur">
        <div className="flex h-14 items-center px-4 font-semibold">Inbox</div>
      </header>
      {/* room for the fixed tab bar, so the last row can scroll above it */}
      <main className="flex-1 px-4 pb-[calc(64px+env(safe-area-inset-bottom))]">{children}</main>
      <nav
        aria-label="Main"
        className="fixed inset-x-0 bottom-0 z-40 flex h-[calc(64px+env(safe-area-inset-bottom))] justify-around border-t border-border bg-background pb-[env(safe-area-inset-bottom)]"
      >
        {/* tab links */}
      </nav>
    </div>
  );
}
```

`min-h-dvh` only matters when the page is shorter than the screen, where it ends the content at the bottom of the visible area, and a page that short does not scroll, so the toolbars stay put. A taller page is taller than the minimum either way, so the toolbars come and go during a scroll without changing its height, and the fixed tab bar tracks the visible area on its own.

Window scroll is also the setup in which Safari reliably minimizes its toolbars. With an inner scroll container that behavior has changed between iOS releases: WebKit bugs [228278](https://bugs.webkit.org/show_bug.cgi?id=228278) and [231878](https://bugs.webkit.org/show_bug.cgi?id=231878), both from the iOS 15 cycle, report opposite behavior, and both were closed as intended. Do not count on the extra space there.

##### Step 3: a shell with its own scroll area

A chat or a board needs the header and the composer on screen at all times. Make the column exactly the visible height and let one child scroll:

```tsx
import type { ReactNode } from "react";

export function ChatLayout({ messages, composer }: { messages: ReactNode; composer: ReactNode }) {
  return (
    <div className="flex h-dvh flex-col overflow-hidden bg-background">
      <header className="shrink-0 border-b border-border pt-[env(safe-area-inset-top)]">
        <div className="flex h-14 items-center px-4 font-semibold">Emma Carter</div>
      </header>
      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-3">{messages}</div>
      <footer className="shrink-0 border-t border-border px-3 pt-2 pb-[max(env(safe-area-inset-bottom),12px)]">
        {composer}
      </footer>
    </div>
  );
}
```

This is the broken screen from the introduction with `h-dvh` in place of `h-screen`. `min-h-0` lets the middle child shrink, so it scrolls instead of pushing the composer down.

The [App Shell](https://wingo-ui.com/components/app-shell) builds both versions from one prop. `scroll="window"`, the default, renders the root with `min-h-dvh`; `scroll="content"` renders `h-dvh overflow-hidden`. With window scroll its desktop sidebar is `sticky top-0 h-dvh`, so the sidebar's footer stays in view on a long page. Its docs give the reason for the default: window scroll keeps "router scroll restoration, the iOS toolbar minimizing."

```tsx
// app/(app)/layout.tsx
import type { ReactNode } from "react";
import { House, Inbox, Settings, Users } from "lucide-react";
import { AppShell } from "@/components/ui/app-shell";
import type { SidebarNavGroup } from "@/components/ui/sidebar";
import { Topbar } from "@/components/ui/topbar";
import type { NavItem } from "@/lib/navigation";

const nav: SidebarNavGroup[] = [
  {
    items: [
      { label: "Home", href: "/", icon: <House /> },
      { label: "Inbox", href: "/inbox", icon: <Inbox /> },
      { label: "Clients", href: "/clients", icon: <Users /> },
      { label: "Settings", href: "/settings", icon: <Settings /> },
    ],
  },
];
const tabs: NavItem[] = nav[0].items;

export default function AppLayout({ children }: { children: ReactNode }) {
  // "content" for a chat or a board; the default "window" lets Safari minimize its toolbars
  return (
    <AppShell nav={nav} tabs={tabs} topbar={<Topbar title="Summit CRM" />} scroll="window">
      {children}
    </AppShell>
  );
}
```

#### How tall should a bottom sheet be on mobile?

At most 92dvh: tall enough for a long list, short enough to leave a strip of the dimmed page above it, and in dvh so the address bar never pushes the handle off the screen. While a modal sheet is open the page behind it is locked, so the toolbars rarely move, and if they do, a dvh cap follows them.

Side panels need no unit at all: the free [Sheet](https://wingo-ui.com/components/sheet) places them with `fixed inset-y-0` and pads the top with `env(safe-area-inset-top)`. For bottom sheets, two details decide the cap:

- **The unit.** A cap of `92vh` is 92% of the large viewport. Whenever the toolbars take more than 8% of the screen, that is taller than the visible area, and the handle and the title start above the top of the screen.
- **The 8% gap.** The strip of dimmed page above the sheet shows this is a layer, gives people somewhere to tap to dismiss it, and keeps the handle clear of the status bar.

In plain Tailwind that is `fixed inset-x-0 bottom-0 flex max-h-[92dvh] flex-col` on the panel, `min-h-0 flex-1 overflow-y-auto` on the body so a long list scrolls inside the cap, and `pb-[max(env(safe-area-inset-bottom),16px)]` on the last part. The [React bottom sheet guide](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web) builds that layout on vaul with drag and focus handling.

The free [Drawer](https://wingo-ui.com/components/drawer) is that layout on vaul, with drag to dismiss, focus handling and the safe-area padding built in. Its sheets grow with their content up to `max-h-[92dvh]`, and `height="full"` keeps them at `h-[92dvh]` even when a search shortens the list:

```tsx
import { Button } from "@/components/ui/button";
import { Drawer, DrawerClose } from "@/components/ui/drawer";

export function Filters({ results }: { results: number }) {
  return (
    <Drawer
      title="Filters"
      description="New York · 1,240 listings"
      height="full"
      trigger={<Button variant="soft">Filters</Button>}
      footer={
        <DrawerClose asChild>
          <Button size="lg" fullWidth>
            Show {results} results
          </Button>
        </DrawerClose>
      }
    >
      <p className="text-sm text-muted-foreground">Price, condition and categories</p>
    </Drawer>
  );
}
```

> Live demo (Drawer): Tap Filters: the sheet rises to 92% of the visible height and keeps it while you search the categories, leaving a strip of the dimmed page above it. Drag it down or tap that strip to close it. Try it at [Drawer](https://wingo-ui.com/components/drawer) and install it with `npx wingo-ui@latest add drawer`.

When a sheet must cover the whole screen, size it `h-dvh` and pad the top inset, which is what the Sheet does as a bottom sheet with `size="full"`. Its smaller sizes cap at 50, 70, 85 or 92 dvh.

> Live demo (Sheet): Tap Filters: this bottom sheet is size full, so it fills exactly the visible height and pads the status bar; close it with the X or press Esc. Try it at [Sheet](https://wingo-ui.com/components/sheet) and install it with `npx wingo-ui@latest add sheet`.

#### Does dvh change when the on-screen keyboard opens?

No. Safari on iOS, [Chrome for Android since version 108](https://developer.chrome.com/blog/viewport-resize-behavior) and [Firefox for Android since version 132](https://www.firefox.com/firefox/android/132.0/releasenotes/) shrink only the visual viewport when the keyboard opens. The layout viewport keeps its size, so svh, dvh and lvh keep their values, and the keyboard covers the bottom of your `h-dvh` layout.

On Android you can opt out: `interactiveWidget: "resizes-content"` in the Next.js `viewport` export (the `interactive-widget` key of the viewport meta tag) makes the keyboard shrink the layout viewport and every viewport unit with it, so the chat layout above keeps its composer above the keyboard without JavaScript. As of October 2026, [caniuse](https://caniuse.com/mdn-html_elements_meta_name_viewport_interactive-widget) lists no Safari support, so iPhones still need code.

That code reads `window.visualViewport`: while a text field has focus, the keyboard covers `innerHeight - visualViewport.height - visualViewport.offsetTop` pixels. The [useKeyboardInset hook](https://wingo-ui.com/components/use-keyboard-inset) measures that at most once per frame and returns it as a motion value, plus an `open` flag that re-renders only when it flips. For CSS-only consumers it can also write the value to a variable on `<html>`:

```tsx
"use client";

import { useKeyboardInset } from "@/hooks/use-keyboard-inset";

// mount once near the root: --keyboard-inset is the covered height in px, 0 without a keyboard
export function KeyboardInsetVar() {
  useKeyboardInset({ cssVar: "--keyboard-inset" });
  return null;
}
```

```tsx
<form className="fixed inset-x-0 bottom-0 translate-y-[calc(var(--keyboard-inset,0px)*-1)] bg-background px-3 pt-2 pb-[max(env(safe-area-inset-bottom),12px)]">
  {/* message field and send button */}
</form>
```

The bar moves with a transform, so nothing reflows as the keyboard slides. The hook reports 0 on the server, on desktops, while pinch-zoomed and whenever no text field has focus, and it ignores a covered height of 80px or less (its `threshold`), such as the iOS form accessory bar alone. Inside a bottom sheet you need none of this: the Drawer's `repositionInputs`, on by default, moves the sheet up so the focused field stays visible. The rest of a chat screen, from auto-scroll while a reply streams to Enter during IME input, is in our [React AI chat UI guide](https://wingo-ui.com/blog/react-ai-chat-ui).

> Live demo (useKeyboardInset): On a phone, tap the message field: the composer rides on top of the keyboard and the readout shows the covered height. On a desktop there is no on-screen keyboard, so the inset stays at 0px. Try it at [useKeyboardInset](https://wingo-ui.com/components/use-keyboard-inset) and install it with `npx wingo-ui@latest add use-keyboard-inset`.

#### Should you still use the --vh JavaScript hack?

No. The hack sets a `--vh` variable from `window.innerHeight` in a resize listener. Until that script runs, the server-rendered page uses the fallback, so the layout can shift on load. After that it re-measures as the toolbars move, so it jumps during a scroll just as dvh can, with a trip through the main thread on top. Every browser Tailwind v4 supports has the native units, so delete the hack, and `height: -webkit-fill-available` with it.

#### How do you test viewport heights on a real phone?

On the phone itself, with a probe on the page. Device emulation in a desktop browser has no toolbars that retract, so the three units are equal there and every bug in this post stays hidden. This client component prints the three heights, `innerHeight` and the visual viewport:

```tsx
"use client";

import { useEffect, useRef, useState } from "react";

const UNITS = ["svh", "dvh", "lvh"] as const;

export function ViewportProbe() {
  const probes = useRef<Partial<Record<(typeof UNITS)[number], HTMLDivElement | null>>>({});
  const [text, setText] = useState("");

  useEffect(() => {
    const visual = window.visualViewport;
    const read = () => {
      const units = UNITS.map((unit) => `${unit} ${probes.current[unit]?.offsetHeight ?? 0}`);
      setText([...units, `inner ${window.innerHeight}`, `visual ${Math.round(visual?.height ?? 0)}`].join(" · "));
    };
    read();
    window.addEventListener("resize", read);
    visual?.addEventListener("resize", read);
    return () => {
      window.removeEventListener("resize", read);
      visual?.removeEventListener("resize", read);
    };
  }, []);

  return (
    <>
      {UNITS.map((unit) => (
        <div
          key={unit}
          ref={(node) => {
            probes.current[unit] = node;
          }}
          aria-hidden
          className="pointer-events-none invisible fixed top-0 left-0 w-px"
          style={{ height: `100${unit}` }}
        />
      ))}
      <output className="fixed top-[env(safe-area-inset-top)] left-2 z-50 rounded-md bg-foreground px-2 py-1 font-mono text-xs text-background">
        {text}
      </output>
    </>
  );
}
```

Then, on an iPhone and on an Android phone: load the page and check that nothing important sits under the toolbar; scroll until the toolbars minimize and back, watching for content that shifts; open every sheet and find its handle and its last button; focus a text field and see what the keyboard covers; and rotate to landscape, where the screen is short and every toolbar pixel counts.

#### How do you fix 100vh in an existing app?

Search your code for `h-screen` and `100vh` and give each match the unit for its job: `min-h-dvh` or `h-dvh` for shells, `min-h-svh` for heroes, `inset-0` for fixed overlays. Then install the free Drawer and Sheet with `npx wingo-ui@latest add drawer sheet`; both cap their height in dvh and pad the safe areas. The App Shell and the useKeyboardInset hook are part of [Wingo UI Pro](https://wingo-ui.com/pricing). For the other phone rules, from bottom sheets to touch targets, read the [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) or browse [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Sheet](https://wingo-ui.com/components/sheet) (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: `npx wingo-ui@latest add sheet`
- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [App Shell](https://wingo-ui.com/components/app-shell) (Pro): The whole admin layout in one component: a collapsible, resizable sidebar, a top bar and the page; a drawer and a tab bar on phones. Install: `npx wingo-ui@latest add app-shell`
- [useKeyboardInset](https://wingo-ui.com/components/use-keyboard-inset) (Pro): How much of the screen the phone's on-screen keyboard covers, as a motion value, so bars pinned to the bottom can ride above it. Install: `npx wingo-ui@latest add use-keyboard-inset`

#### FAQ

##### Why is 100vh taller than the screen on mobile?

Every major browser computes vh against the large viewport, the size with the address bar and toolbars retracted. While they are showing, 100vh overshoots the visible area by their height, so a button at the bottom of an h-screen layout ends up under the toolbar.

##### What is the difference between 100dvh and 100vh?

100vh is fixed at the large viewport height. 100dvh follows the toolbars: it equals 100svh while they are expanded and 100lvh once they retract, so it tracks the visible height, at the cost of resizing while the page scrolls.

##### Does Tailwind CSS support dvh?

Yes. Since Tailwind CSS v3.4 it ships h-dvh, h-svh and h-lvh with min-h and max-h versions, and arbitrary values such as max-h-[92dvh] work too. h-screen still compiles to height: 100vh in Tailwind 4.3.

##### Does dvh change when the on-screen keyboard opens?

Not by default. Safari on iOS, Chrome for Android since version 108 and Firefox for Android since version 132 resize only the visual viewport for the keyboard, so viewport units keep their values. Android browsers let you opt in with interactive-widget=resizes-content; on iOS, read window.visualViewport.

##### Is dvh supported in Safari?

Yes, since Safari 15.4 on macOS and iOS. Chrome and Edge added the units in version 108 and Firefox in version 101, and Tailwind CSS v4's own baseline (Safari 16.4, Chrome 111, Firefox 128) is newer than all of them.

##### Are the Wingo UI Sheet and Drawer free?

Yes. The Sheet and the Drawer are free and already cap their height in dvh and pad the safe areas. The App Shell and the useKeyboardInset hook are Pro.

---

Source: https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind

### 14 shadcn Alternatives in 2026: Price, Mobile and MCP

> 14 shadcn alternatives checked in October 2026: free and paid UI libraries by license, price, mobile behavior and MCP support, with a pick per use case.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons)
- Reading time: 19 min
- Canonical: https://wingo-ui.com/blog/shadcn-alternatives

#### TL;DR

The best shadcn alternative depends on which part of shadcn/ui you want to replace. To keep owning the source, pick coss ui (free, on Base UI), Magic UI or Aceternity UI for animated marketing pages, or Wingo UI for mobile-first app components; to install a package instead, pick Mantine, MUI, Chakra UI or HeroUI; for a design system of your own, start from Base UI or React Aria. Most of these libraries leave the phone layout to you, so check what each one does on a 390px screen before you switch.

Picking among shadcn alternatives usually starts with how each library installs and how it looks. The questions that decide a project come later: what happens to the files you copied when upstream fixes a bug, whether the select you ship opens as something usable on a 390px phone, and whether Claude Code or Cursor can look up real props instead of guessing them. This guide answers those questions for 14 libraries, with prices, licenses and features checked in October 2026 and linked to the pages we read.

We build Wingo UI, one of the paid options below, so read this as a vendor's view with sources. It covers open source shadcn alternatives and paid ones, and it says plainly where another library is the better pick. More head to head comparisons live under [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons).

#### What is the best alternative to shadcn UI?

There is no single best alternative to shadcn UI, because shadcn/ui is three things at once: a way to distribute code (a CLI that copies source files into your project), a set of primitives underneath (Base UI, Radix or React Aria), and a visual style. Decide which of the three you want to replace and the shortlist gets short:

- **Keep the model, change the components.** coss ui for free MIT components on Base UI, Magic UI or Aceternity UI for animated landing pages, Untitled UI React for a kit that matches the Untitled UI Figma file, Wingo UI for mobile-first app components with an MCP server and updates that merge into files you edited.
- **Leave the model, install a package.** Mantine for a free set with forms, dates and charts, MUI when you need the MUI X data grid and pickers, Chakra UI for style props, HeroUI for React Aria and Tailwind CSS v4 in an npm package, Ant Design for dense enterprise back offices.
- **Keep the primitives, drop the look.** Base UI, React Aria Components or Radix Primitives, styled by you.
- **Step outside React.** daisyUI, which is a set of Tailwind CSS class names that works with any framework.

If none of those reasons applies to you, the best option may be staying where you are, which the section near the end covers.

#### What changed in shadcn/ui in 2026?

The biggest change: since July 2026, new shadcn/ui projects start on Base UI instead of Radix. The [July 2026 changelog entry](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default) made Base UI the default for `npx shadcn init` and for the docs, kept Radix fully supported behind `npx shadcn init -b radix`, and noted that projects created on shadcn/create were already picking Base UI over Radix 2 to 1. The same month, [React Aria became a third base](https://ui.shadcn.com/docs/changelog/2026-07-react-aria) (`--base aria`).

Other changes that matter when you compare:

- The [Drawer](https://ui.shadcn.com/docs/components/drawer) in Base UI projects now uses Base UI's drawer instead of Vaul. The Radix version still uses Vaul.
- June 2026 added components for chat interfaces, July 2026 a Toast built on Base UI, and September 2026 moved `cn` into [its own package](https://ui.shadcn.com/docs/changelog/2026-09-cn), so components import it from `cn` instead of `@/lib/utils`. What the new Toast means next to Sonner is in our [Sonner alternatives comparison](https://wingo-ui.com/blog/sonner-alternative-react-toast).
- On the agent side there is an [MCP server](https://ui.shadcn.com/docs/mcp) that browses, searches and installs from every registry in `components.json`, and a [skill](https://ui.shadcn.com/docs/skills) (`npx skills add shadcn/ui`) that reads your project configuration before the agent writes code.

Two consequences follow. A "Radix plus Tailwind" description of shadcn/ui is out of date, and a registry written for Radix needs care in a new Base UI project. And the copy-the-source model has become a platform: registries from other vendors install through the same `shadcn add` command, so trying an alternative no longer means learning a new tool.

#### How do the shadcn alternatives compare?

The tables below are the short answer, checked in October 2026. "Mobile" lists only what each library's docs show for phones beyond responsive layout, and "Agents" what a coding agent can use. Prices are list prices on the day we checked; several vendors showed a discount from a higher price.

##### Libraries that put the source in your project

| Library | Model and base | License | Price | Mobile | Agents |
| --- | --- | --- | --- | --- | --- |
| [shadcn/ui](https://ui.shadcn.com/docs/changelog) | CLI copies source; Base UI (default), Radix or React Aria | MIT | Free | Drawer, a Dialog plus Drawer recipe, Sidebar with its own mobile state | MCP server, skill, llms.txt |
| [coss ui](https://coss.com/ui/llms.txt) | shadcn registry (`@coss`); Base UI | MIT | Free | Drawer with swipe, snap points and nesting | llms.txt, agent skills |
| [Magic UI](https://pro.magicui.design) | shadcn registry (`@magicui`); Motion | MIT (free), paid license (Pro) | Free; Pro $199 one-time | Landing page effects; no sheet, popover or menu in the catalog | [MCP server](https://magicui.design/docs/mcp), llms.txt |
| [Aceternity UI](https://ui.aceternity.com/pricing) | shadcn registry (`@aceternity`); Motion | [Aceternity License](https://ui.aceternity.com/licence) | Free; $169 a year or $199 lifetime; Team $1,590 for 10 people | Effects and blocks; some blocks document a mobile menu | llms.txt; prompts for v0 and Lovable on paid plans |
| [Untitled UI React](https://www.untitledui.com/react) | Own CLI or npm; React Aria, Tailwind CSS v4 | MIT (free base), PRO license | Free; PRO from $349 one-time for one user | Drawers and modals are PRO | MCP server, llms.txt |
| [Wingo UI](https://wingo-ui.com/docs/installation) | Own CLI or shadcn registry (`@wingo-ui`); Radix, vaul, Motion | Per-developer license; 75 items free | Free; Pro $8 a month, $80 a year or $150 lifetime | Popover, select, menus and dialog open as bottom sheets below 768px; 44px targets on touch; table rows become cards | [MCP server](https://wingo-ui.com/docs/mcp), rules for 5 agents, llms.txt, update checks |

##### Packages and primitives

| Library | Model and base | License | Price | Mobile | Agents |
| --- | --- | --- | --- | --- | --- |
| [Mantine 9](https://mantine.dev/guides/llms/) | npm; own CSS, no Tailwind | MIT | Free | Modal goes full screen on small screens with `use-media-query` (a docs recipe) | MCP server, skills, llms.txt |
| [MUI (Material UI 9)](https://mui.com/pricing/) | npm; Emotion | MIT core | Free; MUI X Pro $299 or Premium $599 per developer a year | SwipeableDrawer; Dialog goes full screen with `useMediaQuery` (a docs recipe) | [MCP server](https://mui.com/material-ui/getting-started/mcp/), llms.txt |
| [Chakra UI 3](https://www.chakra-ui.com/docs/get-started/ai/mcp-server) | npm; Ark UI, Emotion | MIT | Free; [Chakra UI Pro](https://pro.chakra-ui.com/pricing) blocks $299 one-time | Drawer placement takes breakpoints, such as bottom on phones and end from `md` | MCP server, llms.txt |
| [HeroUI 3](https://www.heroui.com/llms.txt) | npm; React Aria, Tailwind CSS v4 | MIT | Free; [HeroUI Pro](https://heroui.pro/pricing) sold separately | Modal placement `auto` sits at the bottom on mobile and centered on desktop; a separate React Native library | MCP server, agent skills, llms.txt |
| [Ant Design 6](https://ant.design/docs/react/mcp) | npm; own design language | MIT | Free | Built for enterprise back offices; phones get a separate library, antd-mobile | MCP server (`antd mcp`), llms.txt |
| [daisyUI 5](https://daisyui.com/components/modal/) | Tailwind CSS plugin, class names only | MIT | Free; [Blueprint MCP](https://daisyui.com/blueprint/) $22 a month or $600 lifetime | `modal-bottom sm:modal-middle` puts a modal at the bottom on phones; Dock for bottom navigation | llms.txt, skill; Blueprint MCP (paid) |
| [Konsta UI 5](https://konstaui.com/) | npm for React, Vue and Svelte; Tailwind CSS | MIT | Free | Mobile only: iOS and Material sheets, tab bars and toolbars | None found |
| [Base UI 1.8](https://base-ui.com/llms.txt) | npm; unstyled | MIT | Free | Drawer with swipe to dismiss | llms.txt |
| [React Aria Components](https://react-aria.adobe.com/llms.txt) | npm; unstyled | Apache-2.0 | Free | Press and hover events normalized for touch | MCP server, agent skills, llms.txt |

Two libraries are missing from the tables on purpose. Radix Primitives is still maintained and still the base of many registries, ours included; it appears in the section on headless primitives. Tailwind Plus, from the Tailwind CSS team, sells its components, templates and the Catalyst UI kit as a [one-time purchase with lifetime access](https://tailwindcss.com/blog/tailwind-plus), but its product page sent us to a sign-in form when we checked, so we left it out rather than print prices we could not see.

#### Which alternatives keep the shadcn model?

coss ui, Magic UI, Aceternity UI, Untitled UI React and Wingo UI all put the source in your repository, and all but Untitled UI install through the shadcn CLI. They differ in what they cover and in what happens after the copy.

**coss ui** is the closest thing to shadcn/ui with a different design. Its registry components are MIT licensed, built on Base UI from the start, cover the app basics from Accordion and Dialog to Toast and Tooltip, and come with a migration guide from shadcn/ui and Radix. Its [repository](https://github.com/cosscom/coss) also keeps Origin UI, the Radix-based registry coss ui grew out of, as a legacy snapshot with limited support. If you liked shadcn/ui and want more components on the new default base for free, start here.

**Magic UI and Aceternity UI** are effect libraries for marketing pages: animated backgrounds, marquees, hero sections and full landing templates. They sit next to shadcn/ui more than they replace it, since neither covers the forms, menus and overlays an app needs. Magic UI's free components are MIT; Aceternity uses its own license, which says you cannot redistribute the source files, so read it before you publish them in a public repository.

**Untitled UI React** is the code side of the Untitled UI Figma kit, installed with its own CLI (`npx untitledui@latest add`) or from npm. The free base is MIT; the PRO tier is a one-time purchase per seat tier and adds hundreds of components, dashboards and page examples, drawers, modals and command menus included. It is a natural pick when your designers already work from the Untitled UI Figma file.

**Wingo UI** is ours. Release 1.7.0 has 326 items: 218 components, 72 blocks and page templates, 17 hooks and 19 helpers, of which 75 are free. Every component is built for apps people open on phones, as the mobile section below shows. Every visual aspect is a prop with a default, and the CLI merges new releases into files you have edited. The weak spots: it is younger and has a much smaller community than shadcn/ui, it is React only, it is built on Radix (so a Base UI project would carry two primitive libraries), and most items need a paid plan.

#### Which alternatives ship as an npm package?

Mantine, MUI, Chakra UI, HeroUI and Ant Design. You upgrade with `npm update` instead of merging files, and you customize through the library's theme and style APIs instead of editing the component source. That trade is right for many teams: someone else fixes the focus trap in the date picker, and you never see the file.

**Mantine 9** is free and MIT across the board: components, hooks, a form library, dates and charts. It does not use Tailwind CSS; its own FAQ has a page on the limits of mixing in third-party styling. Its [AI guide](https://mantine.dev/guides/llms/) documents llms.txt, skills and an MCP server whose `get_item_props` tool returns a component's props or a hook's signature.

**MUI** is where you go for heavy data screens. The core Material UI library is MIT and free; the MUI X Data Grid, date range pickers, charts and tree view add advanced features in paid plans, listed at $299 (Pro) and $599 (Premium) per developer per year in October 2026. The default look is Material Design, which is a feature or a problem depending on your product.

**Chakra UI 3** rebuilt the library on Ark UI and kept its style props. Its responsive object syntax reaches component props too: the Drawer docs show `placement={{ mdDown: "bottom", md: "end" }}`, which opens a bottom drawer on phones and a side panel from `md`. Chakra UI Pro sells blocks on top, from $299 one-time.

**HeroUI 3** is the closest npm package to the shadcn stack: React Aria Components underneath, Tailwind CSS v4 for styling, MIT. Its Modal placement defaults to `auto`, which sits at the bottom of the screen below the `sm` breakpoint and centered above it, and its [button styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css) make the default size 40px tall on phones and 36px from `md` up. A separate HeroUI Native library covers React Native, and a paid HeroUI Pro adds components such as a command palette and a data grid.

**Ant Design 6** is built for enterprise back offices: dense tables, forms and admin layouts. Phones get a separate library, antd-mobile, so an app that serves both maintains two sets of components.

#### Should you use headless primitives instead?

Only if you are building your own design system and can own every style, state and animation. Headless libraries give you behavior and accessibility; everything you see is your code.

- **Base UI** reached [v1.0.0 on December 11, 2025](https://base-ui.com/llms.txt) and is now the default base under shadcn/ui. Its Drawer handles swipe to dismiss, the job shadcn/ui used Vaul for.
- **React Aria Components** from Adobe has the most thorough interaction layer we know of. `usePress` handles mouse, touch, keyboard and screen readers through one API, and `useHover` [ignores the emulated mouse events that touch devices fire](https://react-aria.adobe.com/useHover.md), which is the cause of hover styles that stick after a tap.
- **Radix Primitives** is still maintained and still under most of the shadcn ecosystem, including Wingo UI.

Picking a headless library also picks the base for everything you add later, since a registry built for one base may not drop cleanly into another.

#### Which shadcn alternatives work best on mobile?

Most of them leave the phone to you. They give you a drawer and a media query hook, and you wire the swap from popover or dialog to sheet one component at a time. Sorted by how much of that work the library does, from least to most:

1. **Responsive CSS only.** Magic UI and Aceternity UI (effects for landing pages) and Ant Design (a separate mobile library).
2. **A recipe you copy per component.** shadcn/ui, MUI and Mantine document a pattern that reads a media query and renders a different component or a full-screen variant.
3. **A placement that changes by breakpoint.** Chakra UI's drawer placement, daisyUI's `modal-bottom sm:modal-middle` and HeroUI's `auto` placement move the panel to the bottom of the screen on phones. Whether you can drag it away depends on the component.
4. **Built into each component.** Konsta UI, for mobile-only apps with an iOS or Material look, and Wingo UI, where the [Popover](https://wingo-ui.com/components/popover), [Select](https://wingo-ui.com/components/select), Dropdown Menu, [Dialog](https://wingo-ui.com/components/dialog) and date pickers open as draggable bottom sheets below 768px through a `responsive` prop that defaults to `true`.

Level 2 looks like this. It is an abridged copy of the responsive example in the shadcn/ui Drawer docs, where the form is shared as its own component and the overlay shell is written twice:

```tsx
const isDesktop = useMediaQuery("(min-width: 768px)");

if (isDesktop) {
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* trigger, header and <ProfileForm /> */}
    </Dialog>
  );
}

return (
  <Drawer open={open} onOpenChange={setOpen}>
    {/* the same trigger and header again, then <ProfileForm /> */}
  </Drawer>
);
```

That is fine for one dialog. It becomes a project when every popover, select, dropdown and date picker needs the same treatment, each with its shell written twice and each reading a hook that returns `false` on the server. Our [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) covers why that hook value is harmless for overlays and harmful for content, along with the other rules for phones.

The level 4 version of the same idea is one component. The free [Drawer](https://wingo-ui.com/components/drawer) is a draggable bottom sheet on phones, and its `desktop` prop decides what it becomes from 768px: the same sheet (`"sheet"`, the default), a side panel (`"side"`) or a centered dialog (`"dialog"`).

```tsx
"use client";

import { SlidersHorizontal } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Drawer, DrawerClose } from "@/components/ui/drawer";

export function ListingFilters({ results }: { results: number }) {
  return (
    <Drawer
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
      title="Filters"
      description="New York · 1,240 listings"
      desktop="dialog"
      closeLabel="Close filters"
      footer={
        <DrawerClose asChild>
          <Button size="lg" fullWidth>
            Show {results} results
          </Button>
        </DrawerClose>
      }
    >
      <p className="text-sm text-muted-foreground">Price, condition and categories</p>
    </Drawer>
  );
}
```

> Live demo (Drawer): Tap Filters: on a phone the sheet slides up and you can drag it down to close; on a wide screen the same component opens a centered dialog. Try it at [Drawer](https://wingo-ui.com/components/drawer) and install it with `npx wingo-ui@latest add drawer`.

On a phone the sheet has a drag handle and no close button; in the desktop dialog a close button appears in the corner, and `closeLabel` is its accessible name.

Touch targets follow the same split. HeroUI v3 makes its buttons taller below `md`, as noted above. Wingo UI's [Button](https://wingo-ui.com/components/button) grows its medium size from 40px to 44px on coarse pointers and gives the small size a 44px hit area without changing how it looks. For the phone question alone, our [best React component library for mobile](https://wingo-ui.com/blog/best-react-component-library-for-mobile) comparison checks nine libraries at 390px, Ionic React and antd-mobile included, on sheets, touch targets, safe areas and gestures.

#### Which shadcn alternatives work best with coding agents?

In October 2026 most of them have an MCP server, so the useful question is what the server can do. We see three kinds:

- **Documentation servers** answer questions about components, props and examples, and npm still installs the package. MUI, Mantine (`search_docs`, `get_item_props`, `get_api`), Chakra UI (`list_components`, `get_component_props`, `get_theme`), Ant Design (eight tools behind `antd mcp`, `antd_changelog` among them), React Aria and HeroUI work this way.
- **Install servers** find items and put their source into your project. The shadcn MCP server does it through the shadcn CLI for any registry in `components.json`, and Untitled UI's server can browse, search and install its components. Magic UI's gives the agent direct access to its components.
- **Servers that also check for updates.** Ours answers searches and returns props with defaults, the design rules and the theme tokens without an account, and sends the source to an API key (a free account for free items, Pro for the rest). Its `check_updates` tool compares the versions in your `wingo-ui.json` with the latest release, so the agent hears about fixes before it edits a file that has one waiting.

Setting each one up takes one line:

```bash
# documentation servers: the agent reads props and examples, npm installs the package
claude mcp add mantine -- npx -y @mantine/mcp-server
claude mcp add chakra-ui -- npx -y @chakra-ui/react-mcp

# an install server for every registry in components.json
npx shadcn@latest mcp init --client claude

# the Wingo UI MCP server plus a rules file for the agent
npx wingo-ui@latest agents install claude
```

The server matters more for libraries whose source you own. With a package, an agent that guesses a prop gets a type error. With copied source, the agent can edit the component itself, so it needs the real API and the rules behind it. Our [guide to component library MCP servers](https://wingo-ui.com/blog/component-library-mcp-guide) covers the tools, the rules file and the setup for Claude Code, Cursor and Codex. If you are choosing between a hosted generator and an agent in your repository, our [v0 vs Claude Code comparison](https://wingo-ui.com/blog/v0-vs-claude-code-for-ui) weighs code ownership, design consistency and cost across sign-in, pricing and settings screens.

#### How do you update components you copied?

With a package, you run `npm update` and read the changelog. With copied source, the merge is yours, and libraries differ in how much they help.

The shadcn CLI can preview: `npx shadcn@latest add dialog --dry-run` lists what would change and `--diff` shows the difference for a file. Bringing an upstream fix into a file you have edited is then a manual merge, or a job for your agent with the shadcn skill loaded. Every registry you install through the shadcn CLI behaves the same way. Our guide to [updating shadcn components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits) turns that manual merge into a git 3-way merge.

Wingo UI's CLI records the version of everything it installs in `wingo-ui.json` and keeps the installed copy in `.wingo-ui/base/`, which lets it run a three-way merge, the same idea as `git merge`:

```bash
npx wingo-ui@latest outdated              # installed vs latest, and which files you edited
npx wingo-ui@latest diff drawer --base    # what you changed since installing
npx wingo-ui@latest update drawer         # untouched files are replaced, your edits are kept
```

When upstream and you changed the same lines, the file gets conflict markers and you choose, or you settle every conflict with `--theirs` or `--ours`. The [updates docs](https://wingo-ui.com/docs/updates) cover the details. One caveat: files you install through the shadcn CLI from our registry carry no version record, so `wingo-ui update` cannot merge into them later.

#### Which shadcn alternatives include a data table?

MUI, Ant Design and Wingo UI ship a full data table; shadcn/ui gives you a guide instead. Its [Data Table page](https://ui.shadcn.com/docs/components/data-table) explains that one data table component would lose the flexibility of headless UI, so it walks you through building your own on the Table component and TanStack Table v9. That is a good fit if your tables are all different. If you need the same admin table on twenty screens, the guide becomes code you maintain. Our [TanStack Table v9 data table tutorial](https://wingo-ui.com/blog/tanstack-table-v9-data-table) builds that code with filters, bulk actions and server pagination, and compares it with the ready-made tables.

The alternatives split three ways. MUI's X Data Grid has a free MIT version and adds its advanced features in the paid plans. Ant Design's Table has sorting, filters and pagination built in, and the other packages give you a styled table to build on. Wingo UI's [Data Table](https://wingo-ui.com/components/data-table) is a Pro component on TanStack Table v9 with search, filters, sorting, bulk actions, pinning, resizing and virtualization, and below 768px each row becomes a card instead of a table that scrolls sideways:

```tsx
"use client";

import { DataTable, createColumns } from "@/components/ui/data-table";

type Order = { id: string; customer: string; city: string; status: string; total: number };

const col = createColumns<Order>();
const columns = col([
  col.accessor("customer", { header: "Customer", filter: "text", mobile: "title" }),
  col.accessor("city", { header: "City", filter: "multi-select", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Refunded: { tone: "warning" }, Failed: { tone: "danger" } },
    filter: "multi-select",
  }),
  col.accessor("total", { header: "Total", type: "currency", footer: "sum" }),
]);

export function Orders({ orders }: { orders: Order[] }) {
  return (
    <DataTable
      data={orders}
      columns={columns}
      caption="Orders"
      locale="en-US"
      selectionMode="multiple"
      searchPlaceholder="Search orders"
      mobileLayout="cards"
    />
  );
}
```

> Live demo (Data Table): Search for a client, toggle the Overdue chip, then sort or filter from the toolbar; on a phone each row becomes a card with a Load more button. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

The `mobile` key on a column decides where its value goes on the phone card: `"title"`, `"subtitle"`, `"meta"`, `"field"` or `"hidden"`. Rows need a unique `id` (or pass `getRowId`), because selection uses it. Switch `mobileLayout` to `"scroll"` when a table has to stay a table.

#### Which shadcn UI alternative for React fits your project?

Match the library to the job. These are our picks, including the many cases where the answer is not ours:

- **Enterprise admin with heavy grids and date ranges:** MUI with MUI X, the deepest set of data components in this list.
- **Internal tools with complex forms, without Tailwind:** Mantine. Free, MIT, with forms and dates built in.
- **A design system of your own:** Base UI or React Aria Components. React Aria if touch and screen reader behavior has to be exact.
- **A free shadcn alternative on the new default base:** coss ui.
- **An npm package with the shadcn look and stack:** HeroUI 3.
- **Animated marketing pages:** Magic UI or Aceternity UI, next to whatever you use for the app.
- **Server-rendered pages with little JavaScript, or a stack beyond React:** daisyUI.
- **A mobile-only web app, or one wrapped in Capacitor, with a native iOS or Material look:** Konsta UI.
- **A product that people use on phones and desktops, built with coding agents, where you own the source and still want updates:** Wingo UI.

#### When should you stay on shadcn/ui?

Stay when your app is used mostly on desktops, your team is happy to write its own responsive wrappers, and the biggest ecosystem matters more to you than any one feature. shadcn/ui is free and MIT licensed, its [GitHub repository](https://github.com/shadcn-ui/ui) had about 125,000 stars on October 8, 2026, it supports three bases, and its CLI installs from a whole directory of community registries. Switching has a cost: every call site that uses a component's API changes, and a new library brings its own conventions for tokens, sizes and states.

You also do not have to choose. Because registries share one CLI, the realistic path for most teams is shadcn/ui as the base plus one or two registries for what it lacks.

#### How do you switch without a rewrite?

Replace one component at a time, starting with the ones that hurt most, and keep both libraries in the project while you do.

Three practical points for a move from shadcn/ui to Wingo UI, most of which apply to any registry:

1. **File names collide.** Both libraries write `components/ui/button.tsx`, `dialog.tsx` and `drawer.tsx`. Our CLI keeps an existing file that differs and tells you to rerun with `--overwrite`, so commit first and swap deliberately.
2. **Call sites change.** shadcn/ui's Button uses `variant="destructive"` and `variant="secondary"`; ours separates the role from the color, so those become `tone="danger"` and `variant="soft"`.
3. **Pick the right CLI for a Base UI project.** Free items install from their URL with `npx shadcn@latest add https://wingo-ui.com/r/button.json`, and Pro items through the `@wingo-ui` registry in `components.json`. But shadcn projects created with a Base UI style rewrite `asChild`, which our components rely on, so in those projects use `npx wingo-ui@latest add` instead, as the [installation docs](https://wingo-ui.com/docs/installation) explain.

To keep the new components close to your current look while you migrate, set app-wide defaults once instead of passing props everywhere. Our Button and Input default to `radius="md"`, which gives the medium size 10px corners; if your current controls use 8px, `"sm"` matches them:

```tsx
import { UIProvider } from "@/lib/ui-config";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider defaults={{ button: { radius: "sm" }, input: { radius: "sm" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}
```

`UIProvider` is a client component, so the root layout can stay a server component. Explicit props still win over these defaults, and the defaults win over the component's own. The Button below runs with the soft variant and a full radius set through props, so you can compare it with your current buttons in both themes.

> Live demo (Button): Press the button: it dips on a quick spring and settles back; Tab to it for the focus ring, then switch the theme to compare light and dark. Try it at [Button](https://wingo-ui.com/components/button) and install it with `npx wingo-ui@latest add button`.

#### Where should you start?

Pick the one component that hurts most on a phone and try an alternative for that component alone. If it is an overlay, install the free Drawer with `npx wingo-ui@latest add drawer` (no account needed; it brings the Button and the media query hook along), put it behind one trigger people use on phones, and open it on your own device. The Data Table and the rest of the catalog are part of [Wingo UI Pro](https://wingo-ui.com/pricing), and the [MCP server](https://wingo-ui.com/docs/mcp) answers questions about every item without an account, so your agent can read the props before you decide.

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`

#### FAQ

##### What is the best free alternative to shadcn/ui?

If you want to keep owning the source, coss ui is the closest match: MIT licensed, built on Base UI and installed through the shadcn CLI. If you would rather install a package, Mantine is MIT licensed, free and covers forms, dates and charts as well as the basic components.

##### Is shadcn/ui still built on Radix?

Not by default. Since July 2026, npx shadcn init starts new projects on Base UI, Radix stays fully supported with the -b radix flag, and React Aria is available as a third base with --base aria.

##### Which shadcn alternative works best on mobile?

Konsta UI if you want an iOS or Material look for a mobile-only web app, and Wingo UI if the same app runs on desktops and phones, because its popover, select, menus and dialog open as draggable bottom sheets below 768px by default. HeroUI, Chakra UI and daisyUI can move a modal or drawer to the bottom of the screen on phones; shadcn/ui, MUI and Mantine document a recipe you wire per component.

##### Can I use a shadcn alternative alongside shadcn/ui?

Yes. Registries such as coss ui, Magic UI, Aceternity UI and Wingo UI install through the same shadcn add command, so you can replace one component at a time. Watch for files with the same name, such as components/ui/button.tsx, and commit before each swap.

##### Do shadcn alternatives work with Claude Code and Cursor?

Most do. As of October 2026 shadcn/ui, MUI, Mantine, Chakra UI, HeroUI, Ant Design, React Aria, Magic UI, Untitled UI and Wingo UI publish MCP servers, and nearly all publish llms.txt. The servers differ: some answer documentation questions, some install source files, and Wingo UI's also checks your installed versions for updates.

---

Source: https://wingo-ui.com/blog/shadcn-alternatives

### AGENTS.md vs CLAUDE.md vs Cursor Rules for React

> AGENTS.md vs CLAUDE.md vs Cursor rules for React and Tailwind: which agent reads which file in October 2026, and a rules file that keeps agents on your tokens.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents)
- Reading time: 14 min
- Canonical: https://wingo-ui.com/blog/agents-md-vs-claude-md-react

#### TL;DR

Write your rules once in AGENTS.md, which Codex, Cursor and Claude Code all read, and add a CLAUDE.md that starts with @AGENTS.md, because by default Claude Code skips AGENTS.md whenever a CLAUDE.md exists. Use Cursor .mdc rules and Claude Code path rules only for instructions that belong to one folder. For a React and Tailwind design system, keep the file short and checkable, link long docs instead of pasting them, and put component defaults in code, where an agent cannot skip them.

You added Claude Code to a React project that already had Cursor rules, a teammate runs Codex, and now the repo has three instruction files that disagree about button sizes. AGENTS.md vs CLAUDE.md is the question underneath: which file does each agent actually read, and where should your design system rules live so that every agent follows them? This post answers it with the loading rules from each tool's documentation as of October 2026, the layout Next.js 16.3 now writes for you, and a rules file, modeled on the one in our own repo, that keeps agents on your design tokens.

We build Wingo UI, a React component library, so the examples use its [Button](https://wingo-ui.com/components/button) and [UIProvider](https://wingo-ui.com/components/ui-config). The file layout works in any React and Tailwind CSS project. More guides on agents and UI are in [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents).

#### What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is the shared, tool-neutral instruction file that Codex, Cursor and most other agents read. CLAUDE.md is Claude Code's own file, with imports, personal and organization scopes, and path-scoped rules next to it. Both hold plain Markdown instructions; what differs is who reads each file and what the loader does with it.

**AGENTS.md** is an open format stewarded by the Agentic AI Foundation under the Linux Foundation. The [agents.md site](https://agents.md/) lists Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, Zed, Windsurf and others as tools that read it, and says more than 60,000 open source projects use it. It has no required fields. Its precedence rule is short: the closest AGENTS.md to the edited file wins, and an explicit prompt in the chat overrides everything.

**CLAUDE.md** is Claude Code's own memory file. It comes in four scopes: an organization policy file, `~/.claude/CLAUDE.md` for you, `./CLAUDE.md` for the team, and `CLAUDE.local.md` for your private notes. It supports `@path` imports up to four hops deep, and it has a companion folder, `.claude/rules/`, whose files can be scoped to paths.

**Cursor rules** are `.mdc` files in `.cursor/rules` with frontmatter that decides when each one loads. Cursor reads AGENTS.md too.

#### Which file does each agent read?

Each tool reads its own file, and all three read AGENTS.md in some form. Here is how loading works, as of October 2026:

| Feature | Claude Code | Codex | Cursor |
| --- | --- | --- | --- |
| Reads | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` | `AGENTS.md`; an `AGENTS.override.md` in the same folder replaces it | `.cursor/rules/*.mdc`, `AGENTS.md`, User Rules, Team Rules |
| AGENTS.md | Since v2.1.277, only when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or above | Native | Root and subfolders, nested files combined |
| Scoped rules | `.claude/rules/*.md` with a `paths` list | One file per folder, from the Git root down to the launch directory | `.mdc` files with `globs` or a `description` |
| Imports | `@path`, up to 4 hops | None documented | `@file` mentions, read on demand, not inlined |
| Size | Under 200 lines per file | 32 KiB for all files combined | Under 500 lines per rule |

Sources, checked October 9, 2026: the [Claude Code memory docs](https://code.claude.com/docs/en/memory), the [Codex AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md), the [Cursor rules docs](https://cursor.com/docs/context/rules) and [agents.md](https://agents.md/). Gemini CLI reads `GEMINI.md` by default and reads AGENTS.md once you list it in `context.fileName` in `settings.json`, according to its [GEMINI.md docs](https://geminicli.com/docs/cli/gemini-md/).

Two details in that table decide most setups. Codex documents no import syntax and builds its chain once, when it starts, so whatever Codex should know has to be in an AGENTS.md on the path from the Git root to where you launch it, or in your global one in `~/.codex`. Cursor rules only reach the Agent: the Cursor docs say "Rules do not impact Cursor Tab or other AI features."

#### Does Claude Code read AGENTS.md now?

Yes, since v2.1.277, with one condition that catches people: by default Claude Code reads AGENTS.md only when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or any directory above it. Your `~/.claude/CLAUDE.md` and `.claude/rules/` files do not count toward that check.

The trap is `CLAUDE.local.md`. A teammate who adds one for private notes, in a repo that relies on AGENTS.md alone, turns AGENTS.md off for their own sessions. A tool that scaffolds a `CLAUDE.md` does the same for everyone. Run `/memory` to see which files loaded, or set **Project instructions** to `claude-md-and-agents-md` in `/config` if you want both files read.

Some sessions cannot read AGENTS.md directly at all: versions before v2.1.277, sessions where the built-in plugin that reads it is disabled, and in some cases the first session after an upgrade. Claude Code also never reads `AGENTS.override.md` or `AGENTS.local.md`. An import works in all of these cases, which is why we use one.

#### Which setup works for Claude Code, Codex and Cursor at once?

Make AGENTS.md the single source of truth and give Claude Code a CLAUDE.md that imports it. Codex and Cursor read AGENTS.md natively, and Claude Code reads it through the import whatever its version or settings.

```text
your-app/
├── AGENTS.md                  # every rule every agent needs
├── CLAUDE.md                  # @AGENTS.md, then Claude-only lines
├── .claude/rules/ui-kit.md    # Claude Code: loads when it reads files in components/ui
└── .cursor/rules/ui-kit.mdc   # Cursor: attaches when components/ui files are in context
```

The CLAUDE.md stays tiny. Claude reads the imported file first, then the lines below it:

```md
@AGENTS.md

## Claude Code only

- Use plan mode before you change more than one file in `components/ui`.
```

This is the layout Next.js now writes. `create-next-app` creates both files, and on Next.js 16.3 and later `next dev` adds them to an existing project when it detects a coding agent and finds no managed block. AGENTS.md gets a managed block that tells agents to read the docs bundled in `node_modules/next/dist/docs/`, and CLAUDE.md gets the single line `@AGENTS.md`. Text outside the block's markers survives updates, and `agentRules: false` in `next.config.ts` turns the generation off ([Next.js AI agents guide](https://nextjs.org/docs/app/guides/ai-agents)). Our own repository runs the same setup: CLAUDE.md is that one line, and AGENTS.md is 68 lines, the Next.js block included.

Keeping the shared rules in a file that is always loaded matters more than it looks. In [AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) (Jude Gao, Vercel, January 27, 2026), an 8 KB docs index in AGENTS.md passed 100% of a Next.js 16 eval suite, against 79% for a skill with explicit instructions to use it and 53% with no docs at all. Without those instructions, the agent never invoked the skill in 56% of the cases.

A symlink (`ln -s AGENTS.md CLAUDE.md`) also works when you have no Claude-only lines. Anthropic's docs list the catch: on Windows, Git checks a committed symlink out as a plain text file unless `core.symlinks` is enabled, which leaves that clone with a one-line CLAUDE.md. The import has no such failure.

One wrinkle with our own CLI: `npx wingo-ui@latest agents install claude codex` writes the same marked block, about 1 KB, into both CLAUDE.md and AGENTS.md, so with the import Claude reads it twice. The two copies are identical and `agents update` rewrites both, so they cannot contradict each other.

#### What should a React and Tailwind rules file say?

The things an agent cannot learn from one read of your code: where the components live and how to look them up, which tokens to use, which defaults are set in one place, which checks to run, and the few things it must never do. If you start from a CLAUDE.md for React or AGENTS.md examples you found online, strip out any component inventory or props table. That copy goes stale with the next release, and an agent reading a stale table has no reason to open the real file.

Here is an AGENTS.md for a Next.js dashboard built on Wingo UI, with the Next.js block shortened. Each section answers one of the questions above:

```md
<!-- BEGIN:nextjs-agent-rules -->
(managed by next dev: read the docs in node_modules/next/dist/docs/ before writing code)
<!-- END:nextjs-agent-rules -->

# Acme dashboard

Next.js 16 App Router, React 19, Tailwind CSS v4, TypeScript strict.

## Commands

- Dev server: `npm run dev` on http://localhost:3000. If it is already running, use it; never start a second one.
- Before you call a task done: `npx tsc --noEmit`, `npx eslint <files you changed>`, `npm run check:tokens`.

## UI components

- Components live in `components/ui` (Wingo UI, installed as source, versions in `wingo-ui.json`). Before writing UI, search them: the `wingo-ui` MCP tools, or `npx wingo-ui@latest search <words>`. Never hand-write a component that exists there.
- Install with `npx wingo-ui@latest add <slug...>`. Read a component's props before you first use it: `get_component`, or `npx wingo-ui@latest info <slug>`.
- App-wide looks are set once, in `app/layout.tsx`, with `<UIProvider defaults>`. Do not repeat `size`, `radius` or `tone` on every `<Button>`; pass a prop only where one instance differs.
- Configure components through props (`variant`, `tone`, `size`, `loading`, `leftIcon`, `classNames`) before adding classes. A busy button is `<Button loading loadingText="Saving">`, never a hand-made spinner.

## Design tokens

- Semantic classes only. Surfaces: `bg-background`, `bg-surface`, `bg-card`, `bg-popover`. Hover and soft fills: `bg-foreground/5`. Text: `text-foreground`, `text-muted-foreground`. Lines: `border-border`. Colored text: `text-success-soft-foreground` and the other tones.
- No hex, rgb or Tailwind palette colors (`bg-blue-500`) in app code. No `bg-accent` or `bg-secondary`: use `variant="soft"` or `bg-foreground/5`.
- Tone is neutral by default. `tone="brand"` is for the one main action on a screen.
- Radius: controls take it from their `radius` prop; cards and menus use `rounded-2xl`, dialogs `rounded-3xl`.

## Every screen

- Check it at 390px and 1440px wide, in light and dark mode.
- Dialogs, menus and selects turn into bottom sheets below 768px on their own. Never force a desktop popover on a phone.

## Never

- Never edit `components/ui/*` to restyle one screen; pass props or `className` from the screen.
- Never run `npx wingo-ui@latest update` or `add --overwrite` without asking first.
```

A few choices in there are deliberate:

- **It names commands and tools, never a component's props.** Props change with releases; `info` and `get_component` always return the current ones.
- **Every rule is checkable.** Anthropic's guide uses the same test: "Use 2-space indentation" instead of "Format code properly". For UI, `bg-surface` for raised panels instead of "follow the design system".
- **It explains the shadcn habits.** shadcn/ui uses `bg-accent` for highlighted menu items and `bg-secondary` for its secondary button, so an agent that has read a lot of shadcn code reaches for both. The rule names them and gives the replacement. The [Dialog](https://wingo-ui.com/components/dialog) rule works the same way: the component already switches to a sheet below 768px, so the rule tells the agent to leave that behavior alone.
- **Long docs are linked, never imported.** Our own AGENTS.md says "Read docs/DESIGN.md before building anything." That file is 614 lines and about 52 KB. An `@docs/DESIGN.md` import would load all of it into every Claude Code session, and on its own it exceeds the 32 KiB Codex allows for all instruction files together.

#### Why put component defaults in code instead of the rules file?

Because an agent can skip a rule, and it cannot skip a default. Anthropic's docs say it directly: Claude "treats them as context, not enforced configuration", and CLAUDE.md content arrives as a user message after the system prompt. A default set in code applies whether or not the agent read the rule.

In Wingo UI that place is the UIProvider. Every component reads app-wide defaults through `useDefaults` under its `data-slot` name, so one object in the root layout changes every Button. Explicit props win, then the provider, then the component's own defaults:

```tsx
// app/layout.tsx
import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider locale="en-US" defaults={{ button: { size: "lg", radius: "full" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}
```

Now the shortest code an agent can write is also the correct code:

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

export function ProfileActions({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <div className="flex gap-2">
      {/* large and fully rounded from the provider */}
      <Button variant="outline">Cancel</Button>
      <Button tone="brand" loading={saving} loadingText="Saving" onClick={onSave}>
        Save changes
      </Button>
      {/* an explicit prop still wins */}
      <Button variant="ghost" size="sm">
        Preview
      </Button>
    </div>
  );
}
```

The demo below shows the same Button twice: once with no provider, once inside a UIProvider whose defaults set the size, the radius and the tone. In the demo, the top "Save changes" is medium, neutral and softly rounded, and the pair below it, "Save changes" and an outline "Cancel", is large, pill-shaped and orange.

> Live demo (UIProvider): The top button has no provider. The pair below sits inside a UIProvider with radius full, size lg and tone brand, so the same Button markup comes out larger, rounder and orange. Try it at [UIProvider](https://wingo-ui.com/components/ui-config) and install it with `npx wingo-ui@latest add ui-config`.

The demo sets the brand tone to make the change obvious. In a real app, keep the neutral default and save brand for the one main action, as the rules file says.

The same split applies to variants. The rule "no `bg-secondary`, use `variant="soft"`" only works because the soft variant already exists, with its own tint in both themes and a loading state that keeps its width.

> Live demo (Button): Click Save draft: the soft variant shows a spinner and "Saving" in place of the label, at the same width, and ignores clicks until it settles. Try it at [Button](https://wingo-ui.com/components/button) and install it with `npx wingo-ui@latest add button`.

At rest, that demo is one soft gray "Save draft" button. The colors behind every tone come from [Tones](https://wingo-ui.com/components/tones), which is why the rules file can say "tone" and never a color.

#### How should you write Cursor rules for React and Tailwind?

Write them only for what AGENTS.md cannot do: attach rules to a glob. Cursor already reads AGENTS.md, so a rule that repeats it only doubles the text in context.

Cursor's rules docs set a few hard facts. Project rules must use the `.mdc` extension; a plain `.md` file in `.cursor/rules` is ignored. The frontmatter decides when a rule loads: `alwaysApply: true` for every chat, `globs` to attach it when a matching file is in context, a `description` alone to let the agent decide, and none of them to load it only when you @-mention it.

In a React and Tailwind project, one scoped rule is usually enough: the one for edits to the component source itself. Those files are the riskiest place for an agent to tidy up: a refactor that drops one `useDefaults` call quietly cuts that component off from the app-wide defaults.

```md
---
description: Rules for editing the Wingo UI source files in components/ui
globs: ["components/ui/**/*.tsx"]
alwaysApply: false
---

- These files are library source that `npx wingo-ui@latest update` merges into. Keep edits small, and keep `cn()`, the `className` prop, every `data-slot` attribute and any license header comment.
- Keep the `useDefaults("<slot>", props)` call at the top of each component, so `<UIProvider defaults>` keeps working.
- `ref` is a regular prop in React 19; never add `forwardRef`.
- Before changing a file, run `npx wingo-ui@latest diff <slug>` to see your local edits against upstream.
```

Claude Code's version goes in `.claude/rules/ui-kit.md`. It reads only the `paths` field from a rule's frontmatter and ignores the rest, so the header changes and the body stays the same:

```md
---
paths:
  - "components/ui/**/*.tsx"
---

(the same four bullets)
```

##### What about nested AGENTS.md files?

They behave differently in each tool, which is why we scope UI rules with globs instead. Cursor combines a nested AGENTS.md with its parents, and the more specific one wins. Codex builds its chain once at startup, from the Git root down to the launch directory, so a `components/ui/AGENTS.md` applies only when you start Codex inside that folder. Claude Code reads a subfolder's AGENTS.md when it opens a file there, but only while no CLAUDE.md is in play. With the root CLAUDE.md from the setup above, it reads CLAUDE.md files only, so you would need a `components/ui/CLAUDE.md` that imports the AGENTS.md next to it.

#### Which AGENTS.md best practices matter for UI work?

The AGENTS.md best practices that hold up across all three tools are about size, precision and enforcement:

1. **Keep it small.** Claude Code's docs target under 200 lines per file and warn at startup when a file runs long. Codex stops adding files once the combined size reaches 32 KiB by default (`project_doc_max_bytes` raises it). Cursor suggests keeping each rule under 500 lines. Ours is 68 lines and about 14 KB.
2. **Add a rule after the second mistake.** Anthropic suggests adding to CLAUDE.md when "Claude makes the same mistake a second time", and Cursor's docs say to add rules "only when you notice Agent making the same mistake repeatedly". Rules written in advance tend to cover problems the agent never has.
3. **Give the reason for surprising rules.** Our AGENTS.md says never to use `rounded-sm`, `rounded-md`, `rounded-lg` or `rounded-xl` in new code, "the legacy 6px --radius turns them into 2 / 4 / 6 / 10px". A rule with its reason is one an agent can apply to cases you did not list, and one a teammate will not delete as superstition.
4. **Remove contradictions.** If two instructions conflict, Anthropic's docs say Claude "may pick one arbitrarily". Cursor merges Team, Project and User Rules, and the earlier source wins a conflict. One shared file is the easiest way to keep them consistent.
5. **Enforce what must never break.** A rule the agent can skip needs a check it cannot skip. The color rules above fit in a short script that CI and the agent both run:

```sh
#!/usr/bin/env sh
# scripts/check-tokens.sh: fail when app code bypasses the design tokens
# components/ui, components/blocks and components/templates are library source with their own color defaults
PATTERN='#[0-9a-fA-F]{6}|-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}|bg-(accent|secondary)'
if git grep --untracked -nE "$PATTERN" -- 'app/*.tsx' 'components/*.tsx' \
  ':!components/ui' ':!components/blocks' ':!components/templates'; then
  echo "Use semantic tokens and component props instead (see AGENTS.md)."
  exit 1
fi
```

Add `"check:tokens": "sh scripts/check-tokens.sh"` to `package.json` and the rules file can name it. Two details matter here. `--untracked` makes `git grep` read the files the agent just created, which a plain `git grep` skips until they are added. And the library folders stay out of the scan because Wingo UI blocks keep hex colors as overridable prop defaults, so a project-wide grep fails the day you install one. For actions that must be blocked, such as a command that overwrites files, Claude Code's docs point to a `PreToolUse` hook or permission settings, which apply whatever the model decides.

#### Where should I start?

Create AGENTS.md from the file above, trimmed to what your project needs, add a CLAUDE.md that starts with `@AGENTS.md`, and add one scoped rule per tool only when an agent keeps getting a folder wrong. Then move every default you find yourself repeating in prose into code.

If you use Wingo UI, `npx wingo-ui@latest agents install claude codex cursor` writes a Claude Code skill, our marked block in CLAUDE.md and AGENTS.md, a Cursor rule and the MCP configs, and the [coding agents docs](https://wingo-ui.com/docs/agents) list every file it touches. The Button, the Dialog and the UIProvider from this post are free. The [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide) covers the server side of the same setup, and the [Claude Code shadcn setup](https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup) shows the CLAUDE.md block for a project that runs two registries.

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [UIProvider](https://wingo-ui.com/components/ui-config) (Free): App-wide configuration for Wingo UI: default props for every component, the Intl locale and the reduced-motion policy. Install: `npx wingo-ui@latest add ui-config`
- [Dialog](https://wingo-ui.com/components/dialog) (Free): The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body. Install: `npx wingo-ui@latest add dialog`

#### FAQ

##### Does Claude Code read AGENTS.md?

Yes, since v2.1.277, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. To cover every session, add a CLAUDE.md whose first line is @AGENTS.md.

##### Should I symlink CLAUDE.md to AGENTS.md or import it?

Import it with @AGENTS.md. The import leaves room for Claude-only lines below it and works on Windows, where Git checks a committed symlink out as a plain text file unless core.symlinks is enabled.

##### Does Cursor read AGENTS.md or CLAUDE.md?

Cursor reads AGENTS.md in the project root and in subdirectories, and combines nested files with their parents. As of October 2026 its rules docs do not mention CLAUDE.md, so keep shared rules in AGENTS.md.

##### How long should AGENTS.md be?

As short as you can make it. Anthropic targets under 200 lines per CLAUDE.md, Cursor suggests keeping each rule under 500 lines, and Codex stops adding instruction files once their combined size reaches 32 KiB by default.

##### Where do Cursor rules go and which extension do they need?

In .cursor/rules, with the .mdc extension; Cursor ignores a plain .md file in that folder. The description, globs and alwaysApply fields decide whether a rule loads in every chat, for matching files, when the agent finds it relevant, or only when you mention it.

##### Do I still need an MCP server if I have a rules file?

For a component library, you need something that supplies current facts. The rules file says what to do and rarely changes; an MCP server, or a CLI with search and info commands, returns what changes with every release, such as props, defaults and available updates.

---

Source: https://wingo-ui.com/blog/agents-md-vs-claude-md-react

### Best React Component Library for Mobile in 2026: 9 Compared

> The best React component library for mobile web apps in 2026: 9 libraries checked at 390px for bottom sheets, touch targets, safe areas and gestures.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/best-react-component-library-for-mobile

#### TL;DR

For a React web app that people use on phones and desktops, Wingo UI does the most for you: its selects, popovers, menus and dialogs open as draggable bottom sheets below 768px and its buttons grow to 44px on touch. For a mobile-only app or a Capacitor build with a native iOS or Material look, Ionic React is the stronger pick, with Framework7 and antd-mobile as alternatives. MUI, shadcn/ui, HeroUI and Mantine render fine on a 390px screen but leave most phone behavior, from sheets to safe areas, to you.

Picking the best React component library for mobile comes down to what each component does on a phone. This comparison is for React web apps: a Next.js app that people open in a phone browser, add to the home screen or ship inside Capacitor. React Native kits are out of scope. Four things decide the choice: what a select or menu opens on a 390px screen, how big the targets are under a thumb, whether fixed bars clear the notch and the home indicator, and which gestures work. We checked nine libraries on those four points on October 9, 2026.

We build Wingo UI, one of the nine, so read this as a vendor's comparison with sources, including the cases where another library is the better pick. If you arrived from a general "best React UI library 2026" list, this one is narrower: it only scores what happens on a phone. Broader head to head posts live under [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons), and our [guide to shadcn alternatives](https://wingo-ui.com/blog/shadcn-alternatives) covers prices, licenses and MCP support.

#### What is the best React component library for mobile?

Wingo UI when the same app has to work on phones and desktops, and Ionic React when the app is mobile-only and should look native. The rest of the field fits narrower cases.

- **Phones and desktops from one codebase, Tailwind CSS, source in your repository:** Wingo UI. Its overlays switch to bottom sheets below 768px and its controls grow on touch, so the phone behavior ships inside each component.
- **A mobile-only app or a Capacitor build with a native look:** Ionic React. It covers every phone pattern in this comparison and picks iOS or Material styling by platform.
- **The same idea outside Ionic's ecosystem:** Framework7 React, which brings its own app shell and router.
- **A mobile-only app in the Ant Design family:** antd-mobile.
- **Tailwind classes with an iOS or Material look, inside an Ionic or Framework7 shell:** Konsta UI.
- **A desktop-first product that must also work on phones:** MUI gives the most phone help among the general-purpose packages. shadcn/ui, HeroUI and Mantine work too, with more wiring on your side.

#### How did we test the libraries at 390px?

We opened each library's own docs demos in Chromium through Playwright at 390 by 844 pixels with touch emulation on, so `(pointer: coarse)` matched as it does on a phone. On each site we measured the default button and tapped the first Select demo to see what opens and how tall its rows are. Ionic's and Framework7's docs blocked our headless browser, so for those two and for Konsta UI the numbers come from their source code and docs on GitHub. Versions are the latest on npm on October 9, 2026.

Two limits apply. Docs demos use each site's own theme, which matters for shadcn/ui, whose button size depends on the style you pick. And emulation is not an iPhone: it has no home indicator, no on-screen keyboard and no collapsing toolbar, so we checked safe areas in each library's source instead of on screen. Our [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) lists what only a real phone shows.

#### How do the libraries compare on a phone?

The mobile-only libraries (Ionic, Framework7, antd-mobile) cover every phone pattern, the general-purpose ones leave most of them to you, and Wingo UI ships the phone patterns inside components that also work on a desktop. The table is dated October 2026. "Select at 390px" is what opened when we tapped a select, or what the source does by default.

| Library, version, license | Select at 390px | Bottom sheet |
| --- | --- | --- |
| [Wingo UI](https://wingo-ui.com/docs/installation) 1.7.0, 75 of 326 items free | Bottom sheet, 48px rows | Drawer: drag, snap points, nesting |
| [Ionic React](https://ionicframework.com/docs/api/modal) 9.0.7, MIT | Alert dialog by default; action sheet, popover or modal on request | Sheet modal with breakpoints and a handle |
| [Framework7 React](https://github.com/framework7io/framework7/blob/master/src/react/components/sheet.jsx) 9.2.0, MIT | Smart Select opens a page; popup, sheet or popover with `openIn` | Sheet with breakpoints, swipe to close and swipe to step |
| [Konsta UI](https://konstaui.com/react/sheet) 5.5.0, MIT | Native select inside a list input | Sheet without drag (prop and backdrop tap) |
| [antd-mobile](https://github.com/ant-design/ant-design-mobile) 5.43.0, MIT | Picker wheels in a bottom popup | Popup (swipe to close is opt-in), FloatingPanel with px anchors |
| [MUI](https://mui.com/material-ui/react-drawer/) 9.4.0, MIT core | Floating menu, 48px rows | SwipeableDrawer, no snap points |
| [shadcn/ui](https://ui.shadcn.com/docs/components/drawer) CLI, MIT | Floating list, 28px rows | Drawer with swipe and snap points |
| [HeroUI](https://www.heroui.com/docs/react/components/modal) 3.2.6, MIT | Floating popover, 36px rows | Modal sits at the bottom below 640px; Drawer drags from its handle, header or footer |
| [Mantine](https://mantine.dev/core/modal/) 9.7.1, MIT | Floating dropdown, 34px rows | Drawer without drag; full-screen Modal via a media query recipe |

The mobile-only libraries keep behaving like a phone app on a wide screen: Ionic's select still opens an alert dialog, and its modal becomes a 600 by 500 pixel card once the window is 768px wide and 600px tall. The general-purpose libraries look right on a desktop and leave most phone behavior to you. Wingo UI aims at the middle: one component that is a sheet on a phone and a popover or dialog on a desktop.

#### Which libraries open selects and menus as bottom sheets?

Among the general-purpose libraries, only Wingo UI opens a select as a bottom sheet by default. The mobile-only libraries get there by option or by design: Ionic's select takes `interface="action-sheet"` or `interface="modal"`, Framework7's Smart Select takes `openIn: "sheet"`, and antd-mobile's Picker always opens in a bottom popup. shadcn/ui, Mantine and HeroUI opened a floating list anchored under the field, with rows of 28, 34 and 36 pixels. MUI also opened a floating menu, but it was the one general-purpose package with finger-sized rows: its menu items grow to 48px below its `sm` breakpoint of 600px. Konsta UI uses a native `select`, which opens the phone's own picker and is a fine answer for short lists.

A floating list puts small rows next to the thumb that opened it. A sheet gives full-width rows at the bottom of the screen, where the thumb already is, and leaves room for a search row. In Wingo UI the [Select](https://wingo-ui.com/components/select) does this through its `responsive` prop, which defaults to `true`, so the call site has no media query:

```tsx
"use client";

import { useState } from "react";
import { Select, type SelectOption } from "@/components/ui/select";

const STATES: SelectOption[] = [
  { value: "CA", label: "California", keywords: ["Los Angeles"] },
  { value: "NY", label: "New York", keywords: ["New York City"] },
  { value: "TX", label: "Texas", keywords: ["Austin"] },
];

export function ShippingState() {
  const [state, setState] = useState("");
  return (
    <Select
      label="State"
      placeholder="Choose the state"
      options={STATES}
      value={state}
      onValueChange={setState}
      name="state"
      autoComplete="address-level1"
    />
  );
}
```

Below 768px the field opens a sheet titled with its label, with 48px rows and the chosen row scrolled into view. With more than 8 options a search row sits under the title, and on a touch screen it waits for a tap instead of raising the keyboard over the list. Pass `responsive={false}` to keep the floating list on phones. The Popover, Dropdown Menu, Dialog and date pickers follow the same rule, and all but the date pickers are free.

> Live demo (Select): On a phone, tap the State field: a sheet slides up with large rows and a search box; on a wide screen the same field opens a list under it. Try it at [Select](https://wingo-ui.com/components/select) and install it with `npx wingo-ui@latest add select`.

#### How big are the touch targets out of the box?

Most libraries ship a 32 to 40 pixel default button and keep that size on every device. WCAG 2.2 asks for 24 by 24 pixels at level AA and 44 by 44 at level AAA, and Apple's guidelines use 44 points. Every default button here clears AA; few reach 44 without help.

| Library | Default button | Changes on touch | How we know |
| --- | --- | --- | --- |
| Wingo UI | 40px, 44px on touch | Yes, by pointer type | Measured |
| Ionic React | About 50px (iOS mode), 36px (Material mode) | By platform mode | Source |
| Framework7 React | 34px (iOS), 40px (Material) | By platform mode | Source |
| Konsta UI | 34px (iOS), 40px (Material) | By theme | Source |
| antd-mobile | 40px | No | Measured |
| MUI | 36.5px | No | Measured |
| shadcn/ui | 32px in the docs; 28 to 40px across its eight styles | No | Measured, source |
| HeroUI | 40px, 36px from 768px | By width | Measured, source |
| Mantine | 36px | No | Measured |

Wingo UI is the only library here whose buttons change size by pointer type rather than by screen width or platform, so a touch laptop gets 44px buttons and a narrow desktop window keeps 40px. The rule is one Tailwind variant in the size map of the [Button](https://wingo-ui.com/components/button):

```tsx
// components/ui/button.tsx (excerpt)
md: "h-10 gap-2 px-4 text-sm pointer-coarse:h-11",
```

The small size keeps its 32px look and gets a 44px hit area through a pseudo-element instead. Our [touch target guide](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind) explains when `pointer: coarse` beats `any-pointer: coarse` and how to test it.

#### Which libraries handle safe areas for you?

The mobile-only libraries do, and most general-purpose ones do not. Ionic pads its toolbars, tab bar and modals with `--ion-safe-area-*` variables you can override, and Framework7 does the same with `--f7-safe-area-*`. Konsta UI ships `pb-safe` style utilities that its toolbars use. antd-mobile has a `SafeArea` component, but its tab bar's `safeArea` prop is off by default. We searched the published `@mui/material` 9.4.0 and `@heroui/styles` 3.2.6 packages and shadcn/ui's base components and styles for `safe-area-inset` and found nothing; Mantine uses the insets only in its AppShell, whose footer pads the bottom inset.

All of these read `env(safe-area-inset-*)`, which stays at 0 until the page opts in with `viewport-fit=cover`. In the Next.js App Router that is one export from the root layout:

```tsx
import type { Viewport } from "next";

export const viewport: Viewport = { viewportFit: "cover" };
```

In Wingo UI, 38 component files read the insets. The [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) pads the home indicator, keeps at least 12px under its floating variant, and publishes its height so a floating button or a sticky buy bar can sit above it. Here it is with [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) on the page behind it, as a client component your root layout can wrap around `children`:

```tsx
"use client";

import type { ReactNode } from "react";
import Link from "next/link";
import { usePathname, useRouter } from "next/navigation";
import { House, Inbox, Plus, UserRound, Users } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";
import { PullToRefresh } from "@/components/ui/pull-to-refresh";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Profile", href: "/profile", icon: <UserRound /> },
];

export function PhoneShell({ children }: { children: ReactNode }) {
  const router = useRouter();
  const pathname = usePathname();
  return (
    <>
      <PullToRefresh onRefresh={() => router.refresh()} variant="ios">
        <div className="pb-(--bottom-bar-offset)">{children}</div>
      </PullToRefresh>
      <BottomTabBar
        className="md:hidden"
        items={tabs}
        currentPath={pathname}
        linkComponent={Link}
        action={{ label: "New client", icon: <Plus />, href: "/clients/new" }}
        hideOnScroll
      />
    </>
  );
}
```

The tab bar is fixed to the viewport by default and writes its height, safe area included, to `--bottom-bar-offset` on the root element, which the `pb-(--bottom-bar-offset)` wrapper reads so the last row of the page stays above the bar. `linkComponent` and `currentPath` hand it the Next.js router, so tabs navigate without a full page load and the active pill follows the route. `hideOnScroll` slides the bar away while you scroll down and brings it back on the way up, with transforms only. The pull calls `router.refresh()` to refetch the page's server data and spins for at least 500ms (or until a promise you return settles), and a trackpad scroll past the top pulls too, so the gesture has a desktop path. The [safe area guide](https://wingo-ui.com/blog/tailwind-safe-area-insets) covers stacking a buy bar or a floating button above the tab bar.

> Live demo (Bottom Tab Bar): Tap the tabs: the pill glides to the active one; scroll the page and the bar slides away, then comes back when you scroll up. Try it at [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) and install it with `npx wingo-ui@latest add bottom-tab-bar`.

#### Which libraries ship mobile gestures?

Wingo UI, Ionic, Framework7 and antd-mobile ship all four common phone gestures. The general-purpose libraries ship a swipeable drawer at most, and Konsta UI none.

| Library | Snap points | Pull to refresh | Swipe rows | Wheel picker |
| --- | --- | --- | --- | --- |
| Wingo UI | Drawer | Pull To Refresh | List | Picker Wheel |
| Ionic React | Sheet modal | Refresher | Item Sliding | Picker |
| Framework7 React | Sheet | Page `ptr` | Swipeout | Picker |
| antd-mobile | FloatingPanel | PullToRefresh | SwipeAction | Picker |
| shadcn/ui | Drawer | No | No | No |
| MUI | No | No | No | No |
| HeroUI, Mantine, Konsta UI | No | No | No | No |

In Wingo UI the Drawer is free; Pull To Refresh, the swipe rows of the [List](https://wingo-ui.com/components/list) and the Picker Wheel are Pro.

For sheets, Ionic's API and ours read almost the same. Ionic needs a `0` breakpoint before a swipe can dismiss the sheet:

```tsx
// Ionic React: stops at half and full height, swipe down to close
// import { IonContent, IonModal } from "@ionic/react";
<IonModal trigger="open-filters" initialBreakpoint={0.5} breakpoints={[0, 0.5, 1]}>
  <IonContent className="ion-padding">Price, condition and categories</IonContent>
</IonModal>

// Wingo UI: the same stops; drag down from the first one to close
// import { Button } from "@/components/ui/button";
// import { Drawer } from "@/components/ui/drawer";
<Drawer trigger={<Button>Filters</Button>} title="Filters" snapPoints={[0.5, 1]}>
  <p className="text-sm text-muted-foreground">Price, condition and categories</p>
</Drawer>
```

The difference is what happens at 768px and up: the [Drawer](https://wingo-ui.com/components/drawer) stays a capped sheet, or becomes a side panel or a centered dialog through its `desktop` prop, while Ionic's sheet modal stays a sheet at the bottom of the screen. Our [bottom sheet guide](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web) covers snap points, nesting and the keyboard in detail.

The wheel picker is the gesture most web libraries skip. The [Picker Wheel](https://wingo-ui.com/components/picker-wheel) spins with native momentum, ticks as rows pass the center on phones that can vibrate, and works from a keyboard with arrows, Page Up and Down and type to jump. As a field it opens the wheels in a bottom sheet with Done and Cancel on phones and in a popover on a desktop:

```tsx
"use client";

import { PickerWheelField, pickerRange } from "@/components/ui/picker-wheel";

export function AppointmentTime() {
  return (
    <PickerWheelField
      label="Appointment time"
      name="time"
      defaultValue={["10", "30"]}
      columns={[
        { id: "hour", label: "h", options: pickerRange(8, 19, { pad: 2 }) },
        { id: "minute", label: "min", options: pickerRange(0, 55, { step: 5, pad: 2 }) },
      ]}
    />
  );
}
```

> Live demo (Picker Wheel): Flick a column: it spins with momentum and clicks into place on a row; with a mouse, drag it or scroll it, or Tab to it and use the arrow keys. Try it at [Picker Wheel](https://wingo-ui.com/components/picker-wheel) and install it with `npx wingo-ui@latest add picker-wheel`.

#### When are Ionic React or Framework7 the better choice?

Pick Ionic React when the app is phone-first, you want it to look native on iOS and Android, and you may ship it to the app stores with Capacitor. Its sheet modal, refresher, sliding items, picker and tab bar are mature, and the modes switch by platform with no work from you. The costs are real: its `core.css` is required, its [guide for existing React apps](https://ionicframework.com/docs/react/add-to-existing) warns that its CSS reset may conflict with your global styles, its router package needs React Router 6, and its components look like a phone app on a desktop. Framework7 React makes a similar trade with its own `App`, `View` and routes, and has Vue and Svelte versions too.

Wingo UI is the better fit when the same screens have to work as a desktop product, you style with Tailwind CSS, and you want the source in your repository. It is younger with a much smaller community, it is React only, and it has one design with iOS-style options on some parts instead of a platform mode.

#### When should you stay on MUI, shadcn/ui, HeroUI or Mantine?

Stay when most of your users are on desktops and phones are a secondary target. MUI is the strongest of the four on phones: 48px menu rows on small screens, a `SwipeableDrawer` and a responsive `DatePicker` from MUI X that opens in a modal on touch devices. shadcn/ui has a large registry ecosystem and a Drawer with snap points, and you write the [responsive dialog recipe](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile) once per overlay. If you go this way, budget for three wrappers: overlay to sheet, touch target sizing and safe-area padding on anything fixed. That checklist is what a mobile first React component library saves you, whichever one you choose.

#### Where should you start?

Start with the overlay your users open most on a phone, because a floating list under a thumb is the most visible mobile failure. Install the free Select with `npx wingo-ui@latest add select` (no account needed), put it in one form, and open that form on your own phone. The Drawer, Popover, Dialog and Dropdown Menu are free as well. The tab bar, pull to refresh, picker wheel and the other React mobile UI components in the [Mobile category](https://wingo-ui.com/components/category/mobile) are part of [Wingo UI Pro](https://wingo-ui.com/pricing), at $8 a month, $80 a year or $150 once. Whichever React mobile UI library you pick, test it at 390px with touch on before you commit.

#### Components in this post

- [Select](https://wingo-ui.com/components/select) (Free): A custom select with search, groups, icons, thousands of virtualized rows and a hidden native select for forms. Install: `npx wingo-ui@latest add select`
- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: `npx wingo-ui@latest add bottom-tab-bar`
- [Picker Wheel](https://wingo-ui.com/components/picker-wheel) (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: `npx wingo-ui@latest add picker-wheel`
- [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) (Pro): Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick. Install: `npx wingo-ui@latest add pull-to-refresh`

#### FAQ

##### Which React UI library is best for mobile web apps?

For an app that runs on phones and desktops, pick a library whose components change behavior on a phone, such as Wingo UI, where overlays become bottom sheets below 768px. For a mobile-only app with a native look, pick Ionic React, which ships sheet modals, pull to refresh, sliding list items, pickers and a tab bar that pads the safe area.

##### Does shadcn/ui work on mobile?

It renders well on phones and its Drawer is a real bottom sheet with swipe and snap points. As of October 2026 its Select, Popover and Dropdown Menu stay floating panels at every width, its default button stays 32px on touch screens, and none of its components pad the safe area, so you add those yourself.

##### Is MUI good for mobile?

Better than most general-purpose libraries: its menu rows grow to 48px below 600px, SwipeableDrawer adds swipe gestures and the MUI X date pickers open in a modal on touch devices. Dialogs need a useMediaQuery recipe to go full screen, its drawer has no snap points, and safe areas are up to you.

##### Is Ionic React still a good choice in 2026?

Yes, for mobile-only apps and Capacitor builds. Version 9.0.7 shipped on October 7, 2026 under the MIT license, with iOS and Material modes picked by platform. It brings its own CSS and router integration, so it fits less naturally into a Tailwind CSS app that also has to look like a desktop product.

##### Are these libraries for React Native?

No. Everything here is for React DOM: web apps, PWAs and web views such as Capacitor. A React Native app needs a React Native component library, since these render HTML elements.

##### Can I try Wingo UI on a phone for free?

Yes. The Drawer, Select, Popover, Dialog, Dropdown Menu and Button are free, and they already switch to bottom sheets and 44px targets on phones. The Bottom Tab Bar, Pull To Refresh, Picker Wheel and the other components of the Mobile category are part of Wingo UI Pro.

---

Source: https://wingo-ui.com/blog/best-react-component-library-for-mobile

### Claude Code shadcn Setup: MCP Server, Skill and CLAUDE.md

> Claude Code shadcn setup, tested on shadcn 4.21.4: the MCP server, the skill, a second registry in its own folder, a CLAUDE.md block and prompts that work.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup

#### TL;DR

Run npx shadcn@latest mcp init --client claude to add the shadcn MCP server to .mcp.json, install the shadcn skill with npx skills add shadcn/ui, and list every extra registry in components.json. Then add a short block to CLAUDE.md that says which registry owns which folder and which CLI installs and updates it, and name the registry in every prompt. The server finds components, the skill and the rules steer Claude, and the CLI writes the files.

Claude Code already knows shadcn/ui from its training data, and that is the problem. It writes the API it remembers, which may not match the files in your `components/ui`, and it has never seen the registries you added to `components.json` last month. A Claude Code shadcn setup that holds up has five parts: the shadcn MCP server so Claude can search real registries, the shadcn skill for project context, the registry list in `components.json`, a short rules file that says which registry owns which folder, and a CLI that writes the files. This tutorial sets up all five, adds a second registry, and ends with prompts shaped to get the right component installed.

Everything below was run in October 2026 against shadcn 4.21.4, the `skills` CLI 1.7.1 and our own registry, Wingo UI 1.7.0. What we say about Claude Code itself comes from its docs as of the same month. For the wider picture, read our [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide) first.

#### What does a Claude Code shadcn setup need?

A server that searches registries, instructions that say when to use it, a list of registries and a CLI that installs:

| Piece | Job | How you add it |
| --- | --- | --- |
| shadcn MCP server | Searches every registry in `components.json`, returns add commands | `npx shadcn@latest mcp init --client claude` |
| shadcn skill | Project config and shadcn/ui composition rules | `npx skills add shadcn/ui` |
| `components.json` | The registries to search, with auth headers | Edit by hand |
| `CLAUDE.md` block | Which registry owns which folder and which CLI installs it | Six lines by hand |
| The CLI | Writes files, installs npm packages | `npx shadcn@latest add` or a library's own |

A library's own MCP server is an optional sixth piece: the shadcn server returned no props in our tests, and a library server can. Ours joins shadcn's in the same `.mcp.json` through `npx wingo-ui@latest agents install claude`.

#### How do I add the shadcn MCP server to Claude Code?

Run one command in the project root, restart Claude Code and check `/mcp`:

```bash
npx shadcn@latest mcp init --client claude
```

It writes this entry to `.mcp.json`, then installs `shadcn` as a dev dependency:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}
```

`.mcp.json` is Claude Code's project scope: commit it and the team gets the server, after each person approves it once. For a setup only you use, `claude mcp add shadcn -- npx shadcn@latest mcp` adds it in local scope, the default, instead.

##### Which tools does the shadcn MCP server give Claude?

Once the Claude Code shadcn MCP connection is up, Claude gets seven read-only tools. This is the list the server returned in 4.21.4:

- `get_project_registries`: the registries in `components.json`.
- `list_items_in_registries` and `search_items_in_registries`: browse or fuzzy-search, with paging.
- `view_items_in_registries`: name, description, type, file count and npm dependencies.
- `get_item_examples_from_registries`: demo code, found by names like `dialog-demo`.
- `get_add_command_for_items`: the `npx shadcn@latest add` command for items.
- `get_audit_checklist`: a checklist for after generating code.

Three details shape how you prompt it. The server never writes files: it hands Claude an add command, and every install is a Bash call you can read first. The server sends no instructions, and Claude Code's tool search loads only tool names and server instructions when a session starts, so the skill and your rules file have to say when to use it. And `view_items_in_registries` returned neither props nor source for `@shadcn/button` or our dialog; examples exist only where a registry publishes `-demo` items, which shadcn/ui does and we do not yet. For a third-party item, Claude learns the API from the installed file or the library's own docs.

One bug in 4.21.4: search results print each add command as `[object Promise]`. `get_add_command_for_items` returns the real one, `npx shadcn@latest add @shadcn/button @wingo-ui/dialog` in our test.

#### How do I add a second registry, private or Pro?

Add it under `registries` in `components.json`. A public registry needs only its URL template:

```json
{
  "registries": {
    "@wingo-ui": "https://wingo-ui.com/r/{name}.json"
  }
}
```

A shadcn private registry takes headers, with the secret in an environment variable:

```json
{
  "registries": {
    "@wingo-ui": {
      "url": "https://wingo-ui.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${WINGO_UI_API_KEY}" }
    }
  }
}
```

The shadcn CLI reads that variable from the environment or from `.env.local`; we confirmed both. When the key is set, `agents install` writes our own MCP entry in `.mcp.json` with the same `${WINGO_UI_API_KEY}`, and Claude Code expands it from the environment it started in. Export the key in your shell profile and both servers see it.

Use the header form only when the variable is set. Without it, every call that touches `@wingo-ui` fails with `MISSING_ENV_VARS`: a search across `@shadcn` and `@wingo-ui` returned only that error, with no shadcn results either. Free Wingo UI items need no key, so keep the plain URL until you have one.

Then one search covers both registries. This is the real answer to `search_items_in_registries` for "login" with a limit of 4, the broken add-command lines removed:

```text
Found 173 items matching "login" in registries @shadcn, @wingo-ui:

Showing items 1-4 of 173:

- login-page (registry:block) - The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. [@wingo-ui]
- login-01 (registry:block) - A simple login form. [@shadcn]
- login-05 (registry:block) - A simple email-only login page. [@shadcn]
- login-02 (registry:block) - A two column login page with a cover image. [@shadcn]
```

173 matches for one word is fuzzy matching at work (`@shadcn` alone returned 7), so ask for a small limit.

##### What happens when two registries both write components/ui/button.tsx?

Neither CLI replaces the other's file silently, and either answer breaks something. shadcn/ui and many shadcn-style libraries install into `components/ui` with the same file names and different APIs. When we added our [Dialog](https://wingo-ui.com/components/dialog) to a project that already had the shadcn button, our CLI reported a conflict on `components/ui/button.tsx`, kept the shadcn file and still wrote the dialog and drawer next to it; the shadcn CLI asks before it overwrites. Keeping the shadcn button breaks the type-check, because our dialog and drawer render their close buttons with `radius="full"`, a prop shadcn's Button does not have. Replacing it breaks every `variant="default"`, `"secondary"` or `"destructive"` in your app, because our [Button](https://wingo-ui.com/components/button) variants are `solid`, `soft`, `outline`, `ghost` and `link` (destructive is `tone="danger"`).

Give the second library its own folder. Our CLI reads its paths from `wingo-ui.json`, so after `npx wingo-ui@latest init`, change the `ui` alias and keep the rest:

```json
{
  "aliases": {
    "ui": "@/components/wingo",
    "blocks": "@/components/blocks",
    "hooks": "@/hooks",
    "lib": "@/lib",
    "utils": "@/lib/utils"
  }
}
```

`npx wingo-ui@latest add dialog` then wrote `button.tsx`, `drawer.tsx` and `dialog.tsx` into `components/wingo` beside the untouched shadcn button and rewrote their imports to `@/components/wingo/...`. `init` had already merged our design tokens into `app/globals.css`, and `add` appended the drawer's transitions. That is the second reason to install our items with our CLI: the shadcn-format JSON at `/r/<slug>.json` carries no tokens, so in a project without them, `z-modal` and `shadow-modal` on a shadcn-installed dialog resolve to nothing.

#### Should I install the Claude Code shadcn skill too?

Yes, if your project uses shadcn/ui components; if it also uses another library, scope the skill in your rules file. The skill is the official instruction set from the shadcn/ui repository:

```bash
npx skills add shadcn/ui --agent claude-code
```

The `skills` CLI wrote two skills into `.claude/skills`, `shadcn` and `migrate-radix-to-base`, and recorded both in `skills-lock.json`. Claude Code keeps only a skill's description in context until the skill is used, so the 19.5 KB `SKILL.md` costs little until a UI task starts. Its description matches any project with a `components.json`, so expect it on most UI work.

When it loads, it runs `npx shadcn@latest info --json` and puts your framework, Tailwind version, aliases, base library and installed components in front of Claude. Its `allowed-tools` line also lets Claude run any `npx shadcn@latest` command without asking for the rest of that turn, `add --overwrite` included. Three of its rules matter before you prompt:

- **Name the registry.** Ask for "a login block" without one and the skill tells Claude to ask you which registry to use.
- **Docs first.** Claude runs `npx shadcn@latest docs <component>` before using one. That command only knows shadcn/ui: `docs dialog` returned links to the shadcn/ui and Radix Dialog docs, and `docs @wingo-ui/dialog` answered that the component was not found in the shadcn registry.
- **shadcn/ui composition.** Forms use `FieldGroup` and `Field`, icons in buttons take `data-icon`, and since shadcn's Button has no loading prop, Claude composes a `Spinner` and `disabled` by hand.

All three are right for shadcn/ui files, and the last two are wrong for other registries. Our Button has a `loading` prop that shows a spinner in place of the label, keeps the width, sets `aria-busy` and ignores clicks, so a hand-built spinner duplicates it. In the demo below, pressing "Save changes" swaps the label for a spinner and "Saving" while the button keeps its width.

> Live demo (Button): Click Save changes: the spinner takes the label's place, the width holds and the button ignores clicks until it settles. Try it at [Button](https://wingo-ui.com/components/button) and install it with `npx wingo-ui@latest add button`.

#### What should CLAUDE.md say?

Who owns which folder, which tools to search with, which CLI installs and updates, and where the shadcn skill's rules stop. Claude Code loads `CLAUDE.md` at the start of every session, so this block is always in context:

```md
## UI components

- Two registries. `components/ui` is shadcn/ui (`@shadcn` in components.json). `components/wingo` is Wingo UI (versions in wingo-ui.json); import it from `@/components/wingo/<name>`.
- Before writing UI, search: the `shadcn` MCP tools for @shadcn and other registries, the `wingo-ui` MCP tools for Wingo UI. Never hand-write a component a registry has.
- Install shadcn items with `npx shadcn@latest add @shadcn/<name>` and Wingo UI items with `npx wingo-ui@latest add <slug>`. Never install a Wingo UI item with the shadcn CLI.
- Read the API of the file you import. The shadcn skill's rules and `shadcn docs` apply to `components/ui` only; for Wingo UI items call `get_component` and configure them through their props.
- Semantic tokens only, no hex colors. Check 390px and 1440px wide, in light and dark.
- Never pass `--overwrite` without asking me. Before any update, show me the diff or the release notes.
```

The first line answers what no tool can: which folder belongs to whom. It matters twice in this layout, because our own skill, which `agents install` writes, assumes the default folder and tells Claude that imports use `@/components/ui/<name>`. The fourth line keeps shadcn/ui patterns out of files with a different API. The last repeats the skill's own `--overwrite` rule, because the skill's permission grant covers that flag. On shadcn/ui alone, keep the search, install and overwrite lines. If Codex or Cursor work in the same repository, put these lines in AGENTS.md and import it from CLAUDE.md; our [AGENTS.md vs CLAUDE.md comparison](https://wingo-ui.com/blog/agents-md-vs-claude-md-react) explains which file each agent reads.

Allow the read-only tools in `.claude/settings.json` and leave installs on ask:

```json
{
  "permissions": {
    "allow": [
      "mcp__shadcn",
      "mcp__wingo-ui",
      "Bash(npx shadcn@latest search *)",
      "Bash(npx shadcn@latest view *)",
      "Bash(npx wingo-ui@latest outdated)"
    ]
  }
}
```

#### Which prompts get Claude to install the right component?

The ones that name the registry, ask for a search before an install, and say what to check at the end. Five prompts built that way:

1. **Find before you build.** "Search @shadcn and @wingo-ui for a modal that becomes a bottom sheet on phones. List the candidates with their registry and install command, and install nothing yet." Naming both registries satisfies the skill's rule, and "install nothing yet" keeps the first step read-only.
2. **Build on one component's real API.** "Add the Wingo UI dialog and input with the Wingo CLI, read their props with get_component, then build a profile dialog in app/settings/profile-dialog.tsx with a name field, Cancel and Save, a loading state on Save and an error if saving fails." Naming the source of the API steers Claude away from the shadcn/ui Dialog it remembers.
3. **Start screens from a block.** "Build /login from the Wingo UI login-page block. Wire onSignIn and onVerifyCode to our /api/auth routes, hide the social providers, and list every on* handler you left on its simulated default." The [Login Page](https://wingo-ui.com/components/login-page) ships simulated handlers so its demo works, and each one you do not pass stays simulated: without `onVerifyCode`, the code views accept `123456`.
4. **Ask for updates as a report.** "Check my Wingo UI components and my shadcn/ui button for upstream changes. Show me the notes and the diff, and change nothing."
5. **End with a check.** "Run get_audit_checklist, then type-check and lint the files you touched." The checklist is six generic lines; the type-check is what catches a wrong prop, such as `variant="destructive"` on our Button.

For prompt 2, this is the file a good run ends with, on the real APIs of the [Dialog](https://wingo-ui.com/components/dialog), the Button and the [Input](https://wingo-ui.com/components/input). We type-checked it against release 1.7.0:

```tsx
// app/settings/profile-dialog.tsx
"use client";

import { useState } from "react";
import { Pencil } from "lucide-react";
// next to shadcn/ui these imports read @/components/wingo/...
import { Button } from "@/components/ui/button";
import { Dialog, DialogClose } from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";

type ProfileDialogProps = {
  initialName: string;
  onSave: (name: string) => Promise<void>;
};

export function ProfileDialog({ initialName, onSave }: ProfileDialogProps) {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState(initialName);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState("");

  function changeOpen(next: boolean) {
    // start from the saved name every time it opens
    if (next) {
      setName(initialName);
      setError("");
    }
    setOpen(next);
  }

  async function save() {
    setSaving(true);
    setError("");
    try {
      await onSave(name.trim());
      setOpen(false);
    } catch {
      setError("Your name was not saved. Try again.");
    } finally {
      setSaving(false);
    }
  }

  return (
    <Dialog
      open={open}
      onOpenChange={changeOpen}
      trigger={
        <Button variant="soft" leftIcon={<Pencil />}>
          Edit profile
        </Button>
      }
      title="Edit profile"
      description="Your name appears on invoices and in comments."
      icon={<Pencil />}
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Cancel</Button>
          </DialogClose>
          <Button tone="brand" loading={saving} loadingText="Saving" onClick={save}>
            Save
          </Button>
        </>
      }
    >
      <Input
        label="Full name"
        name="name"
        autoComplete="name"
        value={name}
        onValueChange={setName}
        error={error}
      />
    </Dialog>
  );
}
```

There is no media query in that file. Below 768px the same Dialog opens as a bottom sheet you can drag down to close, with the actions stacked full width at 48px and the primary on top; our [shadcn responsive dialog](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile) tutorial explains how that switch avoids a hydration flash. The demo below is a listing card for a city bike in Brooklyn at $420, and its Edit button opens the same kind of dialog.

> Live demo (Dialog): Click Edit, change the price and press Save: the button shows its loading state, then the dialog closes; on a phone the same dialog opens as a bottom sheet. Try it at [Dialog](https://wingo-ui.com/components/dialog) and install it with `npx wingo-ui@latest add dialog`.

#### How do I keep the installed components up to date?

Ask Claude for a report, then decide. The two CLIs treat edited files differently, which is why the rules file sends each folder to its own tool.

For shadcn/ui files, `npx shadcn@latest add button --diff` shows your file against the registry, and `--overwrite` replaces it, edits included. The skill tells Claude to merge by hand when a file has local changes. Our guide to [updating shadcn components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits) has a git script that runs a real 3-way merge instead.

For Wingo UI files, the CLI recorded each item's version and kept a pristine copy at install, so it merges for you:

```bash
npx wingo-ui@latest outdated        # installed items vs the latest release
npx wingo-ui@latest diff dialog     # your file vs upstream
npx wingo-ui@latest update dialog   # 3-way merge that keeps your edits
```

With our MCP server connected, `check_updates` returns the same list with release notes, so prompt 4 works inside the session.

#### Where should I start?

On shadcn/ui alone: add the MCP server, install the skill, write the three rules lines, and name `@shadcn` in every prompt. If you want a second registry built for phones, the Dialog, Button and Input from this post are free; `npx wingo-ui@latest agents install claude` adds our MCP server and skill next to shadcn's, and the [MCP server docs](https://wingo-ui.com/docs/mcp) cover the setup. The Login Page block is part of Wingo UI Pro, on the [pricing page](https://wingo-ui.com/pricing). More guides like this one live under [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents).

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Dialog](https://wingo-ui.com/components/dialog) (Free): The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body. Install: `npx wingo-ui@latest add dialog`
- [Login Page](https://wingo-ui.com/components/login-page) (Pro): The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. Install: `npx wingo-ui@latest add login-page`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`

#### FAQ

##### How do I install the shadcn MCP server in Claude Code?

Run npx shadcn@latest mcp init --client claude in the project root. It writes a shadcn entry to .mcp.json and installs shadcn as a dev dependency; restart Claude Code and run /mcp to check that the server connected.

##### What is the difference between the shadcn skill and the shadcn MCP server?

The MCP server gives Claude tools to list, search and view registry items and to get their add commands. The skill adds no tools: it injects your project config from shadcn info --json and the shadcn/ui composition rules into the session when Claude works on UI.

##### Does the shadcn MCP server install components by itself?

No. As of shadcn 4.21.4 its seven tools are read-only: it returns the npx shadcn@latest add command and Claude runs it in the terminal. That Bash call normally asks for your approval, but during a turn where the shadcn skill is active, the skill's allowed-tools line lets it run without asking.

##### Why does a shadcn MCP search fail with MISSING_ENV_VARS?

A registry in components.json uses an environment variable in its headers that is not set. The shadcn CLI then fails the whole call, other registries included. Export the variable or put it in .env.local, or use the plain URL form for public registries.

##### Can I use shadcn/ui and another registry in the same project?

Yes, but many shadcn-style libraries install into components/ui with the same file names, starting with button.tsx. Give the second library its own folder (Wingo UI reads it from aliases.ui in wingo-ui.json) so neither CLI has to overwrite the other's files.

---

Source: https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup

### Component Library MCP: Make Agents Use Real Components

> How a component library MCP server, rules files, llms.txt and a registry get Claude Code, Cursor and Codex to install real components instead of guessing.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents)
- Reading time: 25 min
- Canonical: https://wingo-ui.com/blog/component-library-mcp-guide

#### TL;DR

A component library MCP server gives coding agents tools to search the catalog, read real props and design rules, and check installed versions, so they stop guessing APIs from training data. It works best with three companions: a short rules file that tells the agent when to call those tools, llms.txt and Markdown docs for agents without MCP, and a registry plus CLI that writes the real files and records their versions.

Ask Claude Code for a settings page and it will write one in a minute. It may also invent a `<Button intent="primary">` your library never had, hardcode `#3b82f6` where a token belongs and rebuild a date picker you already own. A component library MCP server fixes that at the source: it gives the agent tools to look up what exists, read the real props and install the real files. This guide covers how a React component library exposes itself to Claude Code, Cursor and Codex, the four pieces that make it work (an MCP server, a rules file, llms.txt and a registry), and the setup our CLI writes for you.

We build Wingo UI, so the examples use our server, CLI and registry, with output copied from release 1.7.0. The approach applies to any library, an internal design system included, and where another tool fits better, we say so. Shorter guides on agents and UI live under [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents): [AGENTS.md vs CLAUDE.md vs Cursor rules](https://wingo-ui.com/blog/agents-md-vs-claude-md-react) for the rules file, a [Claude Code shadcn setup](https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup) for the shadcn MCP server next to a second registry, and a [React AI chat UI guide](https://wingo-ui.com/blog/react-ai-chat-ui) for when the screen you are building is the chat itself.

#### What is a component library MCP server?

A component library MCP server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that turns a UI library into tools an agent can call: search the catalog, read one component's props and usage, fetch the design rules, and compare installed versions with the latest release. The agent asks instead of remembering.

The client (Claude Code, Cursor, Codex, Gemini CLI) lists a server's tools and lets the model decide when to call them. A server runs as a local process over stdio or as a remote endpoint over Streamable HTTP. Remote servers are easier to keep current, because every client sees a new release the moment you deploy it.

The React component library MCP servers we checked come in three shapes. Here is how they compare, as of October 2026:

| Server | Runs as | What the agent gets | Writes files into your project |
| --- | --- | --- | --- |
| shadcn MCP | `npx shadcn@latest mcp` (local) | Browse, search and install items from every registry in `components.json`, private ones included | Yes, through the shadcn CLI |
| MUI MCP | `npx -y @mui/mcp@latest` (local, stdio) | Official Material UI docs and code examples, with links to real pages | No, Material UI is an npm package |
| React Suite MCP | `npx -y @rsuite/mcp@latest` (local) | `get_component_props`, `list_components`, `list_hooks`, `search_components` | No, React Suite is an npm package |
| Wingo UI MCP | `https://wingo-ui.com/mcp` (remote, Streamable HTTP) or `npx -y wingo-ui@latest mcp` (local) | Search, props with defaults, usage, blocks, design rules, theme tokens, update checks, changelog | Yes, through the Wingo UI CLI |

Sources, checked in October 2026: the [shadcn MCP docs](https://ui.shadcn.com/docs/mcp), the [Material UI MCP guide](https://mui.com/material-ui/getting-started/mcp/), the [React Suite MCP guide](https://rsuitejs.com/guide/mcp-server/) and our [MCP server docs](https://wingo-ui.com/docs/mcp).

The first shape is a docs lookup. MUI and React Suite ship npm packages, so the agent needs correct props and working links; it never needs source files. If your app runs on Material UI, MUI's own server is the right choice.

The second shape is a registry installer. The shadcn docs describe listing, searching and installing from any shadcn-compatible registry in `components.json`; they do not mention design rules or update checks. If you pull from several registries, one shadcn server covers them all, which is a real advantage.

The third shape is what a source-copy library needs: docs, install and maintenance in one server. When components live in your repository as code you can edit, the agent has to know what the library offers, which version your project has and how the library expects to be used. That last part is the one a props table alone does not carry.

#### Why do coding agents invent components?

Because the model writes from training data, and training data predates your library version and leans toward the most common APIs. Without a way to check, the agent fills every gap with the likeliest guess: shadcn's API on a library that is not shadcn, a prop that was renamed two majors ago, a hex color where a semantic token belongs.

The monday.com engineering team described the same failure in [How We Use AI to Turn Figma Designs into Production Code](https://engineering.monday.com/how-we-use-ai-to-turn-figma-designs-into-production-code/) (Rivka Ungar, February 2, 2026). Their first attempt, a Figma link pasted into Cursor with the Figma MCP, produced code that hardcoded colors and skipped their design system components. Their diagnosis: "the model had no understanding of what the design system actually was." They then built an MCP server for the design system and found it was still not enough on its own: "the MCP only provided knowledge; it didn't decide how or when that knowledge should be applied across a full UI."

A server full of correct facts does nothing if the agent never calls it, calls it after writing the code, or reads the props and then restyles everything with utility classes. So the server is one of four pieces.

#### What does an agent need besides the MCP server?

It needs a rules file that says when to call which tool, docs it can read without MCP, and a registry plus CLI that writes the files. Each piece answers a different question and changes at a different speed:

| Piece | What it answers | How often it changes | In Wingo UI |
| --- | --- | --- | --- |
| MCP server | What exists, its props and usage, the design rules, which versions are current | Every release | `https://wingo-ui.com/mcp`, 10 tools and 1 prompt |
| Rules file | When to call which tool, how to install, what never to do | Rarely | A marked block in `CLAUDE.md`, `AGENTS.md` or `GEMINI.md`, a Cursor rule, a Claude Code skill |
| llms.txt and Markdown docs | The same facts as plain text for agents without MCP | Every release | `/llms.txt`, a file per category, a `.md` twin of every docs page |
| Registry and CLI | The actual files, their dependencies and a version record | Every release | `/r/<slug>.json` in the shadcn format, `npx wingo-ui@latest add` |

The split that matters: the rules file stays short and stable, and everything that changes lives behind the server. Prop tables pasted into a rules file go stale with the next release, and an agent tends to trust the copy already in its context over a tool it would have to call. Our rules file names tools and commands. It never lists a component's props.

#### Which tools should a component library MCP server expose?

A few read-only tools, shaped around what an agent does when it builds UI: find, read, follow the rules, install, stay current. Ours has ten:

- `search_components`: find components, blocks, hooks and helpers by keywords.
- `list_categories`: browse the categories with item counts.
- `get_component`: props, parts, usage, dependencies, the install command and the source.
- `get_block`: a full screen or section and the components it composes.
- `get_design_rules`: tokens, sizes, motion, forms, overlays and mobile rules.
- `get_theme_tokens`: the CSS variables for light and dark mode.
- `get_install_instructions`: project setup for Next.js or Vite.
- `check_updates`: compare installed items with the latest release.
- `get_changelog`: recent releases and their notes.
- `get_account_status`: whether the key has Pro, with the links to upgrade.

There is also one prompt, `build_screen`, that walks the agent through search, rules, install and composition. Every tool is marked read-only and idempotent in its annotations, and none of them writes to your disk. Writing files is the CLI's job.

##### Search should return slugs and one line each

A search result is a short list the agent can scan in one glance. This is the real answer from our server to `search_components` with the query "orders table with filters" and `limit: 5`, trimmed to the first three hits:

```text
5 results for "orders table with filters":

- **Data Table** `data-table` (component, pro, v1.1.0): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones.
- **Audit Log** `audit-log` (component, pro, v1.0.0): Who did what, when and to which record: a filterable activity log with day groups, before / after diffs and a CSV export.
- **Rule Builder** `rule-builder` (component, pro, v1.0.0): An if-this-then-that editor for automations: a trigger, conditions and ordered actions as sentence cards, read back as one sentence.

Next: get_component (or get_block for blocks) with a slug for props, usage and the install command.
```

Every hit carries its slug, kind, access tier and version, and the last line names the next tool, so the agent never has to guess which call turns a slug into props. The third hit is a weak match. That is fine: one line of description lets the agent skip it without spending a `get_component` call to find out.

##### Props need their defaults

`get_component` returns the props table the docs page shows, with types and defaults, plus parts, a usage example, the npm and registry dependencies, and the install command. Defaults are what keep generated code short. An agent that knows the [Button](https://wingo-ui.com/components/button) defaults to `type="button"`, `tone="neutral"` and `size="md"` writes `<Button>Cancel</Button>` instead of spelling out props it guessed. One that knows `loading` keeps the width and sets `aria-busy` does not wrap the button in its own spinner logic.

Below is that Button with the brand tone and a loading label set through props.

> Live demo (Button): Click Pay now: the spinner takes the label's place, the width holds and the button ignores clicks until it settles. Try it at [Button](https://wingo-ui.com/components/button) and install it with `npx wingo-ui@latest add button`.

Without JavaScript, the demo is one solid "Pay now" button in the brand color; pressing it shows a spinner and "Paying" in the same width.

##### Keep tool output small

Large answers run into hard limits in the clients. As of October 2026, [Claude Code's MCP docs](https://code.claude.com/docs/en/mcp) say it warns when a tool result passes 10,000 tokens, caps results at 25,000 tokens by default (`MAX_MCP_OUTPUT_TOKENS` raises it) and saves text results over 50,000 characters to a file instead of putting them in context.

Our [Data Table](https://wingo-ui.com/components/data-table) is one file of 3,940 lines, about 150 KB of TypeScript. Its docs without source come back as about 18,000 characters, roughly 4,500 tokens. With the source attached (a Pro key), the same call grows past 160,000 characters and passes every one of those limits. So the rule for agents, and for anyone designing one of these servers, is: docs through MCP, files through the CLI. Call `get_component` with `includeSource: false` for large items and let `npx wingo-ui@latest add` write the code.

The same goes for rules. `get_design_rules` with the topic `all` returns about 45,000 characters, roughly 11,000 tokens at the usual four characters per token, which is already past Claude Code's warning line. The `mobile` topic alone is about 1,900 characters and `forms` about 4,200. Ask for the topic the task needs.

##### Errors should say what to do next

A tool error is a prompt the agent reads, so write it like one. An unknown slug answers with the closest matches and points back to `search_components`. A Pro item requested without a Pro key answers with the docs and this, word for word from our server (links trimmed, lines wrapped):

```text
Login Page is part of Wingo UI Pro; the source is not included for this caller
(no API key; a free account at https://wingo-ui.com/sign-in unlocks the free items).
Do not re-create it from the docs.
Tell the user it needs Pro (https://wingo-ui.com/pricing); with a Pro key
(Authorization: Bearer wui_...) this tool returns the files and
`npx wingo-ui@latest add login-page` works after `npx wingo-ui@latest login`.
Free alternatives to look at: otp-input.
```

"Do not re-create it from the docs" is the most important sentence on the server. An agent that has just read a complete props table and a long interaction description has everything it needs to attempt a rewrite, and the result is a half copy that matches the docs on paper and nothing else: no version record, no updates, none of the edge cases the description summarizes in one line.

##### Server instructions are the first thing the agent reads

Claude Code turns on tool search by default, so only tool names and each server's instructions load at the start of a session; full tool definitions load when the model looks for them. The same docs say Claude Code cuts each tool description and each server's instructions at 2,048 characters by default. The instructions are your server's pitch to the model: what tasks it handles, when to search for its tools, and the rules that must survive truncation. Put "search before you write UI" in the first lines.

We learned the cost of that limit on our own server. Its instructions run 2,235 characters in release 1.7.0, so Claude Code drops the last sentence, the one that says never to re-create a component without the right key. The rule still reaches the agent because every refusal and the rules file repeat it. Count your characters, and repeat any rule that matters somewhere the model cannot miss.

#### How do I connect Claude Code, Cursor and Codex?

One CLI command writes both the MCP config and the rules for your agent. With `WINGO_UI_API_KEY` set it writes the HTTP configs below, which read the key from the environment so it never lands in your repository; without the variable it writes the local stdio proxy. You can also add the server by hand.

```bash
npx wingo-ui@latest login                     # once per computer
npx wingo-ui@latest agents install claude     # or codex, gemini, grok, cursor, all
```

Running it again changes nothing, and it keeps the other servers in your MCP configs. Where each agent's files go:

| Agent | MCP config | Rules |
| --- | --- | --- |
| Claude Code | `.mcp.json` | `.claude/skills/wingo-ui/SKILL.md` and a marked block in `CLAUDE.md` |
| Codex | `~/.codex/config.toml` | A marked block in `AGENTS.md` |
| Gemini CLI | `.gemini/settings.json` | A marked block in `GEMINI.md` |
| Grok | `.mcp.json` | A marked block in `AGENTS.md` |
| Cursor | `.cursor/mcp.json` | `.cursor/rules/wingo-ui.mdc` |

Access works in three tiers. Without a key, search, docs, props, design rules and tokens all answer, with no source. A key from a free account (email only, no card) adds the source of the 75 free items. A Pro key adds the source of all 326. Create the key in your account and export it in your shell profile as `WINGO_UI_API_KEY`.

##### Claude Code

Claude Code stores MCP servers in three scopes: local (the default, private to you in `~/.claude.json`), project (`.mcp.json` at the repository root, committed for the whole team) and user (all your projects). For a library the team shares, use project scope; `.mcp.json` expands `${VAR}` from the environment, so the file is safe to commit:

```json
{
  "mcpServers": {
    "wingo-ui": {
      "type": "http",
      "url": "https://wingo-ui.com/mcp",
      "headers": {
        "Authorization": "Bearer ${WINGO_UI_API_KEY}"
      }
    }
  }
}
```

For a quick personal setup, the one-liner adds it in local scope:

```bash
claude mcp add --transport http wingo-ui https://wingo-ui.com/mcp --header "Authorization: Bearer $WINGO_UI_API_KEY"
```

Run `/mcp` inside a session to see whether the server connected. If you already run other Claude Code MCP servers, this one sits next to them in the same file, and `agents install` keeps the entries it did not write. Our [Claude Code shadcn tutorial](https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup) walks through the shadcn MCP server, its skill and a second registry in the same project.

##### Cursor

Cursor reads `.cursor/mcp.json` in the project and `~/.cursor/mcp.json` for every project. It uses its own variable syntax, `${env:NAME}`, documented in [Cursor's MCP docs](https://cursor.com/docs/context/mcp):

```json
{
  "mcpServers": {
    "wingo-ui": {
      "url": "https://wingo-ui.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WINGO_UI_API_KEY}"
      }
    }
  }
}
```

##### Codex

Codex reads MCP servers from `~/.codex/config.toml` (or a trusted project's `.codex/config.toml`). For a remote server, `bearer_token_env_var` names the variable that holds the token, as the [Codex MCP docs](https://developers.openai.com/codex/mcp) describe. Restart Codex after adding it so it picks up the server.

```toml
[mcp_servers.wingo-ui]
url = "https://wingo-ui.com/mcp"
bearer_token_env_var = "WINGO_UI_API_KEY"
```

##### Any other client

Clients that cannot send a header to a remote server can run the local proxy. It reads the key saved by `wingo-ui login` and mirrors the remote tools, so new tools appear without updating anything:

```json
{
  "mcpServers": {
    "wingo-ui": { "command": "npx", "args": ["-y", "wingo-ui@latest", "mcp"] }
  }
}
```

#### What goes in the rules file?

When to call which tool, how to install, and what never to do, in as few lines as you can manage. This is the whole block we put in `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`:

```md
<!-- wingo-ui:start v=2 -->
## Wingo UI

This project builds its UI with Wingo UI (React 19 + Tailwind CSS v4 components installed as source, see `wingo-ui.json`).

- Before writing UI, use the `wingo-ui` MCP tools: `search_components` to find what exists (blocks for whole screens), `get_component` / `get_block` for props and usage, `get_design_rules` for tokens, sizes, motion and mobile rules. Never recreate a component the library has.
- Install with `npx wingo-ui@latest add <slug...>`. At the start of UI work run `check_updates` (or `npx wingo-ui@latest outdated`) and mention updates; update with `npx wingo-ui@latest update`.
- Semantic tokens only (`bg-background`, `bg-surface`, `text-muted-foreground`, `border-border`), configure components through props, keep `cn()`, `data-slot` and license headers in copied files. Check 390px and 1440px, light and dark.
- No MCP tools available? The CLI has `search`, `info`, `add`, `outdated`, `update`; the docs for models are at https://wingo-ui.com/llms.txt.
<!-- wingo-ui:end -->
```

A few choices in there are deliberate. Every bullet tells the agent what to do or when to do it. It names tools and commands but lists no component's props, because props change and tool names do not. It has a fallback for sessions without the MCP server, so the agent degrades to the CLI instead of guessing. And it carries a version marker: `npx wingo-ui@latest agents status` tells you whether your copy is current, and `agents update` rewrites only the text between the markers.

Claude Code also gets a skill with the longer workflow, and Cursor gets a project rule scoped to `.tsx`, `.jsx` and `.css` files. The full setup is on the [coding agents docs page](https://wingo-ui.com/docs/agents).

For an internal library, copy the structure: one line on what the library is, one on which tools to call before writing UI, one on how to install, one on styling, one fallback. Five lines that an agent follows beat fifty that it skims. Which of these files each agent reads, and how one AGENTS.md can serve Claude Code, Codex and Cursor at once, is in our [AGENTS.md vs CLAUDE.md comparison](https://wingo-ui.com/blog/agents-md-vs-claude-md-react).

#### Where do llms.txt and Markdown docs fit?

They serve assistants that can read a URL but have no MCP connection, and they back up the server when it is not configured. The [llms.txt proposal](https://llmstxt.org/), published by Jeremy Howard in September 2024, puts a Markdown file at the site root: an H1 with the name, a short summary, then sections of links. It also recommends a clean Markdown version of each page at the same URL with `.md` added, and its current version (updated August 2026) describes a `rel="alternate"` link of type `text/markdown` that points to it.

Our version follows that layout:

- [/llms.txt](https://wingo-ui.com/llms.txt) is the map: what the library is, the counts, pricing, the docs pages, the install commands, a link per category and one line per item with its Markdown link.
- `/llms/<category>.txt` holds the item docs for one category, for example every table or every overlay.
- Every docs page has a Markdown twin, like [/components/button.md](https://wingo-ui.com/components/button.md), linked from the HTML head.
- [/llms-full.txt](https://wingo-ui.com/llms-full.txt) has everything in one file, about 3.3 MB as of October 2026 (the docs of release 1.7.0 plus the blog posts).

That last file is the trap. A model handed 3.3 MB of docs either truncates it or spends its context on components it will never use. Treat llms.txt as a map and point the agent at the one category file or `.md` page the task needs. For a chat assistant that can fetch URLs, "read https://wingo-ui.com/components/data-table.md, then write an orders table with it" puts the real props in front of the model with one fetch.

What llms.txt cannot do is act. It cannot tell the agent which version your project has, whether your key covers an item, or write files with their dependencies. That is why it is the fallback in our rules and the MCP server is the default.

#### Why install through a registry instead of pasting code?

Because the registry and CLI write the exact files with their dependencies and record what they installed, and that record is the only way later releases can reach code you have edited. An agent that copies source out of a tool result skips all three steps.

Take the [Login Page](https://wingo-ui.com/components/login-page) block. `npx wingo-ui@latest add login-page` writes three files into `components/blocks`, then pulls in the 16 registry items the block depends on (Alert, Avatar, Button, Checkbox, Input, OTP Input, Password Input, Separator, Toast and seven hooks and helpers), plus whatever those depend on, and installs its npm packages: `motion`, `lucide-react`, `react-hook-form` and `zod`. It records each item's version and content hash in `wingo-ui.json` and keeps a pristine copy under `.wingo-ui/base/`. When a release changes the block, `npx wingo-ui@latest update` runs a three-way merge between that pristine copy, your edited file and the new version, the way git merges branches.

An agent pasting code from `get_block` can miss a dependency, records nothing, and leaves you with files no tool can update. That is why every answer carries the install command and the rules say "install with the CLI" before anything about styling.

The registry also speaks the shadcn format. Free items install straight from their URL, for example `npx shadcn@latest add https://wingo-ui.com/r/button.json`, and Pro items install by name once the `@wingo-ui` registry with your key is in `components.json`, which also lets the shadcn MCP server install them. The trade-off is on our [installation page](https://wingo-ui.com/docs/installation): the shadcn CLI does not record versions, so `wingo-ui update` cannot merge later changes into files installed that way.

#### What does a full agent session look like?

Take a Next.js app that already has a `wingo-ui.json` and a plain prompt: "Build a sign-in page with two-step codes and an orders page with filters, using Wingo UI." With the server connected and the rules in place, the rules and server instructions lay out this path, and the prompt never names a tool:

1. `check_updates` with the items from `wingo-ui.json`, and a one-line report of what changed upstream.
2. `search_components` with "sign in page" and the kind `block`. On our server the first hit is `login-page`.
3. `get_block` for `login-page`: the props, the components it composes and the install command.
4. `search_components` with "orders table with filters", then `get_component` for `data-table` with `includeSource: false`.
5. `get_design_rules` for the `forms` and `mobile` topics.
6. One install for everything: `npx wingo-ui@latest add login-page data-table` (Button, Input and the rest come along as dependencies).
7. Two pages built from the installed components, configured through their props.

Step 2 is the one a setup without the server skips. With nothing to search, an agent writes a sign-in form from scratch: two fields, a button, perhaps a "forgot password" link that leads nowhere. The block the search returns covers password, email link or code sign-in, Google, Apple and Microsoft buttons, two-step codes that lock for a minute after three wrong tries, and the whole password recovery flow. The page code is short because the block does the work:

```tsx
// app/(auth)/login/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { LoginPage } from "@/components/blocks/login-page";

// a non-2xx answer becomes the message the block shows above the form
async function post(url: string, body: unknown, error: string) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!response.ok) throw new Error(error);
}

export default function Page() {
  const router = useRouter();
  return (
    <LoginPage
      methods={["password"]}
      showProviders={false}
      twoFactor
      onSignIn={(values) => post("/api/login", values, "The email or the password is not correct")}
      onVerifyCode={(code, { backup }) => post("/api/login/verify", { code, backup }, "That code is not correct")}
      onForgot={(email) => post("/api/password/forgot", { email }, "We could not send the email. Try again.")}
      onSuccess={() => router.push("/orders")}
    />
  );
}
```

A rejected promise from `onSignIn` shows its message in an alert above the form, and `twoFactor` sends a correct password to the code step. Three wrong codes lock the input for a minute whatever your handler does.

The pitfall is in the handlers the code leaves out. The block ships simulated ones so its demo works, and every `on*` prop you skip keeps its simulation. Without `onVerifyCode`, the two-step view accepts `123456`. Without `showProviders={false}` or your own `onProvider`, the Google, Apple and Microsoft buttons spin for 1.2 seconds and then call `onSuccess`. An agent that wires `onSignIn` and stops ships a login page where a click on Google goes straight to `/orders` without signing anyone in. The `get_block` props table documents every one of these defaults, so the fix is the same as everywhere else: read the props, then wire each handler or turn the feature off.

The demo below runs on those simulated handlers, with the default methods and providers.

> Live demo (Login Page): Sign in with any email and a password shorter than 8 characters to see the error alert, then choose "Email me a sign-in link" and send it to see the resend countdown. Try it at [Login Page](https://wingo-ui.com/components/login-page) and install it with `npx wingo-ui@latest add login-page`.

Without JavaScript, the demo shows the sign-in form: email and password fields, a "Remember me for 30 days" checkbox, the sign-in button, the emailed link option and buttons for Google, Apple and Microsoft.

The orders page follows the same pattern. The Data Table props the agent read decide most of the code: typed columns from `createColumns`, a badge column with a tone per status, a currency column with a footer sum, filters per column and quick filter chips.

```tsx
// app/orders/orders-table.tsx
"use client";

import { useRouter } from "next/navigation";
import { Eye, Plus } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

export type Order = {
  id: string;
  customer: string;
  city: string;
  status: "Paid" | "Pending" | "Refunded";
  total: number;
  placedAt: string;
};

const col = createColumns<Order>();
const columns = col([
  col.accessor("customer", { header: "Customer", filter: "text", mobile: "title" }),
  col.accessor("id", { header: "Order", mobile: "subtitle" }),
  col.accessor("city", { header: "City", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Pending: { tone: "warning" }, Refunded: { tone: "neutral" } },
    filter: "multi-select",
  }),
  col.accessor("total", { header: "Total", type: "currency", footer: "sum", filter: "number-range" }),
  col.accessor("placedAt", { header: "Placed", type: "date", filter: "date-range" }),
]);

export function OrdersTable({ orders }: { orders: Order[] }) {
  const router = useRouter();
  return (
    <DataTable
      data={orders}
      columns={columns}
      getRowId={(order) => order.id}
      caption="Orders"
      locale="en-US"
      searchPlaceholder="Search orders"
      quickFilters={[{ id: "pending", label: "Pending", columnFilter: { id: "status", value: ["Pending"] } }]}
      toolbarActions={[{ label: "New order", icon: <Plus />, primary: true, onSelect: () => router.push("/orders/new") }]}
      rowActions={(order) => [{ label: "View", icon: <Eye />, onSelect: () => router.push(`/orders/${order.id}`) }]}
      persistKey="orders"
    />
  );
}
```

The page itself stays a server component that loads the rows and passes them down:

```tsx
// app/orders/page.tsx
import { OrdersTable, type Order } from "./orders-table";

async function getOrders(): Promise<Order[]> {
  // your database query goes here
  return [{ id: "ORD-1042", customer: "Emma Carter", city: "New York", status: "Paid", total: 129, placedAt: "2026-10-02" }];
}

export default async function Page() {
  const orders = await getOrders();
  return (
    <main className="mx-auto flex max-w-6xl flex-col gap-4 p-4 sm:p-8">
      <h1 className="text-xl font-semibold text-foreground">Orders</h1>
      <OrdersTable orders={orders} />
    </main>
  );
}
```

The split is deliberate. `getRowId`, `rowActions` and `onSelect` are functions (so is any custom `cell` renderer in the columns), and the App Router cannot pass functions from a server component to a client one. An agent that renders `<DataTable>` with inline callbacks straight from a server `page.tsx` gets that error at render time. Keeping the columns and callbacks in a client file and passing only plain rows avoids it.

Two more details come straight from the docs `get_component` returns. The `mobile` roles pick each card's title and subtitle below 768px, where the table becomes cards by default (`mobileLayout="cards"`). And `persistKey` remembers column visibility, order, widths, density and page size in local storage.

> Live demo (Data Table): Search for a client, toggle the Overdue chip, then sort or filter from the toolbar; on a phone the rows become cards with a Load more button. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

Without JavaScript, the demo is a client table (client, city, status, owner, balance, last invoice) with a search field, quick filter chips such as Active and Overdue, and export and new client actions.

One more case to plan for: the Login Page and the Data Table are both Pro. Without a Pro key, steps 3 and 4 return the docs plus the refusal quoted earlier, and an agent that follows the rules reports the gap instead of rebuilding them from their props tables.

#### How do agent-installed components stay up to date?

The agent checks, you decide. At the start of UI work the rules ask for `check_updates` with the items in `wingo-ui.json`. The answer lists each update with its semver bump and the notes of every library release that touched the item, then the items that are current. Here is the real output for a project with an older Data Table and a current Button:

```text
Latest Wingo UI release: 1.7.0.

1 update:
- **data-table**: 1.0.0 → 1.1.0 (minor)
  - 1.2.0: with no rows to show the empty state stands alone and compact, without column headers spread over nothing; `showHeaderWhenEmpty` keeps them.
  - 1.0.1: sticky header cells no longer drop down over the first row when the header is pinned while scrolling.

Update with `npx wingo-ui@latest update <slug...>` (a 3-way merge that keeps local edits); read breaking notes first.

Up to date: button
```

The numbers in front of the notes are library releases; the item itself goes from 1.0.0 to 1.1.0.

The Claude Code skill tells the agent to mention updates and run them only when you agree. An update is a code change in files you own, and it deserves the same review as any other diff. From the terminal the loop is three commands:

```bash
npx wingo-ui@latest outdated        # installed items vs the latest release
npx wingo-ui@latest diff data-table # your file vs upstream
npx wingo-ui@latest update          # 3-way merge, with the release notes
```

The rules have their own version: `agents status` reports an old copy and `agents update` refreshes it. To keep your own edits to a managed file, delete its `wingo-ui:managed` line. The [updates docs](https://wingo-ui.com/docs/updates) cover conflicts and the `--theirs` flag, and our guide to [updating shadcn components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits) shows the same 3-way merge done by hand with git.

#### How do I check what the agent built?

Review it like a pull request from a fast junior developer who has read the docs. The server gets the first draft onto the right components; it does not replace looking at the result. Our checklist:

- **Hardcoded colors and radii.** Search the diff for hex values, `rgb(` and arbitrary `rounded-[...]` classes. The rules ask for semantic tokens, and a stray hex color is easy to miss.
- **Rebuilt components.** A new file under `components/` that looks like a library item means the agent skipped search.
- **Restyling instead of props.** A long class list on a Button often stands in for a `variant`, `tone` or `size` the agent did not read.
- **Simulated handlers.** Blocks ship demo handlers for every `on*` prop. Compare the handlers the agent wired with the features left on screen, as in the login example above.
- **Phone width and both themes.** At 390px tables should become cards and menus should open as bottom sheets (our [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) has the full list); light and dark should both hold up.
- **Library files.** `npx wingo-ui@latest diff <slug>` shows whether the agent edited one. Edits are allowed, but they become merge work on the next update.

#### Should you build an MCP server for your own design system?

If several people or agents build UI on an internal library, yes. A UI component library MCP server is a smaller project than it sounds: ours is one file of about 220 lines on the TypeScript SDK (`@modelcontextprotocol/server`) plus four small tool modules, and most of the effort went into the data behind it. The protocol part was the easy bit. What we would tell a design system team, from building ours:

- **Start from metadata you already keep.** Our tools read the same registry metadata that renders the docs pages. If your props live only in TypeScript types, extract them once into data the docs and the server share, or the two will drift.
- **Keep every tool read-only.** Let the agent read; let your CLI or package manager write.
- **Return structured content and text.** The model reads the text; scripts and future clients parse the structure.
- **Make outputs small and name the next step.** Slugs in search, the source behind a flag, the next tool at the end.
- **Write errors as instructions.** "Did you mean ..." and "do not re-create it" put the fix in front of the model at the moment it needs it.
- **Keep server instructions under 2,048 characters**, with the "when to use this server" sentence first. Ours are 187 characters over in 1.7.0, and the sentence that falls off is one we care about.
- **Serve the release you deployed.** One fresh server per request, backed by that deploy's registry, means agents never see stale props.
- **Offer HTTP and stdio.** Remote HTTP for clients that send headers, a local proxy for the rest.

The [MCP server for UI components](https://wingo-ui.com/docs/mcp) we run answers without an account, so you can point any client at it and see these choices from the agent's side before you design your own.

#### Where should I start?

To try it, connect the server with `npx wingo-ui@latest agents install claude` (or your agent's name) and ask for a screen in plain words. A free account adds the source of the 75 free items to MCP answers, including the [Button](https://wingo-ui.com/components/button) and the [OTP Input](https://wingo-ui.com/components/otp-input); the CLI installs those without an account. The [Login Page](https://wingo-ui.com/components/login-page) and [Data Table](https://wingo-ui.com/components/data-table) are part of Pro, which covers all 326 items: $8 a month, $80 a year or $150 once, on the [pricing page](https://wingo-ui.com/pricing). The [MCP server docs](https://wingo-ui.com/docs/mcp) have the per-client setup and troubleshooting.

If you maintain your own library, an MCP server is the cheapest way we know to make agents use it correctly. Pair it with five lines of rules and an installer that records versions, and the agent stops inventing your components and starts installing them.

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Login Page](https://wingo-ui.com/components/login-page) (Pro): The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. Install: `npx wingo-ui@latest add login-page`
- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`

#### FAQ

##### What is a component library MCP server?

It is a Model Context Protocol server that exposes a UI library to coding agents as tools: search the catalog, read one component's props with defaults and usage, fetch the design rules and check installed items for updates. The agent calls these tools instead of guessing an API from its training data.

##### Do I still need a rules file if I connect an MCP server?

Yes. The server supplies facts, but an agent does not always reach for a tool on its own. A few lines in CLAUDE.md, AGENTS.md or a Cursor rule tell it to search before it writes UI, to install with the CLI and never to rebuild a component the library has.

##### Is llms.txt enough without an MCP server?

It helps assistants that can only read URLs, but it cannot act on anything. It cannot install files, compare your installed versions with the latest release or tell the agent which items your plan includes.

##### Does the Wingo UI MCP server work without an account?

Yes for docs: search, props, usage, design rules and theme tokens answer without a key. A key from a free account (email only) adds the source of the 75 free items, and a Pro key adds the source of everything else.

##### Can I use the shadcn MCP server with Wingo UI?

Yes. Add the @wingo-ui registry to components.json, with your API key for Pro items, and the shadcn MCP server can search and install from it. It does not serve our design rules or update checks, and the shadcn CLI does not record versions, so wingo-ui update cannot merge later releases into files installed that way.

##### Which coding agents can connect to the Wingo UI MCP server?

npx wingo-ui@latest agents install writes ready configs and rules for Claude Code, Codex, Gemini CLI, Grok and Cursor. Any other client that runs local commands can use the stdio proxy, npx -y wingo-ui@latest mcp.

---

Source: https://wingo-ui.com/blog/component-library-mcp-guide

### dnd kit Mobile: Touch Drag That Lets the Page Scroll

> Fix dnd kit mobile drag: a TouchSensor long press that still lets the page scroll, touch-action per element, the iOS Safari resize cancel and a tap path.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/dnd-kit-mobile-touch-drag

#### TL;DR

To make dnd kit mobile drag work without blocking the page scroll, replace the default sensors with a pointer sensor that ignores touch, a TouchSensor with a 250ms delay and 5 to 8px of tolerance, and a KeyboardSensor, then set touch-action: manipulation on long-press surfaces and touch-action: none only on drag handles. Keep the drag inside its own scroll container, because @dnd-kit/core cancels a drag on window resize and iOS Safari resizes the window when its toolbar collapses. Add a tap path, such as a Move to menu or up and down buttons, because keyboard drag alone does not meet WCAG 2.5.7.

You built a sortable list or a kanban board with dnd kit, it works with a mouse, and on a phone it falls apart: the page scrolls while the card stays put, or the card grabs every swipe and the list never scrolls. This tutorial fixes dnd kit mobile drag step by step: which sensors to register, the activation delay versus scroll trade-off, where `touch-action` goes, why iOS Safari cancels drags, and the keyboard and tap paths that make drag and drop accessible. The sensor setup is the one in the Wingo UI [Kanban](https://wingo-ui.com/components/kanban), which the [Deal Pipeline](https://wingo-ui.com/components/deal-pipeline) builds on; the [List](https://wingo-ui.com/components/list) shows the drag handle variant.

As of October 2026, the latest `@dnd-kit/core` is still 6.3.1 from December 2024, and the [legacy docs](https://dndkit.com/legacy/introduction/installation/) recommend the new version of dnd kit (`@dnd-kit/react` for React), which is at 0.5.0, before 1.0. This post targets `@dnd-kit/core` 6.3.1 and `@dnd-kit/sortable` 10.0.0.

#### Why is dnd kit not working on mobile?

Because `DndContext` uses the PointerSensor and the KeyboardSensor by default, and pointer events cannot stop a scroll. When a finger moves on an element that allows panning, the browser starts scrolling and fires `pointercancel`, which ends the drag, and calling `preventDefault()` in `pointermove` changes nothing. The [dnd kit Pointer sensor docs](https://dndkit.com/legacy/api-documentation/sensors/pointer) say it plainly: "Using `touch-action: none;` is the only way to reliably prevent scrolling for pointer events."

That leaves two tools, each with a cost:

- **`touch-action: none` on the draggable.** The drag works, and a swipe that starts on that element can never scroll the page. Fine for a small grip, bad for a list of full-width rows: when every row is `none`, no swipe on the list scrolls it. The docs suggest `none` on a drag handle only, for this reason.
- **The TouchSensor.** Touch events can be canceled in `touchmove`, so a drag can wait for a long press and still let a swipe scroll. The same docs page recommends the Mouse and Touch sensors whenever `none` does not fit your layout.

The problem is old: [issue #435](https://github.com/clauderic/dnd-kit/issues/435), "Dragging with PointerSensor does not work well on touch devices", dates from August 2021. When the rows themselves must scroll, React drag and drop on touch screen devices needs the TouchSensor, next to a sensor for the mouse.

#### Which dnd kit sensors work on a touch screen?

Three: a pointer sensor that ignores fingers, the dnd kit touch sensor with a delay, and the keyboard sensor. The trap is registering the stock PointerSensor next to the TouchSensor. A touch fires `pointerdown` before `touchstart`, and `DndContext` ignores a sensor's activator while another sensor is pending; the check in the 6.3.1 source is commented "Another sensor is already instantiating". So the PointerSensor takes every finger and the TouchSensor's delay never runs.

We tested it with `@dnd-kit/core` 6.3.1 in headless Chromium with emulated touch: one draggable on a page taller than the screen, an 8px distance on the pointer sensor, 250ms and 8px on the touch sensor, and a finger moving 60px either at once or after a 400ms hold.

| Sensors | `touch-action` | Swipe at once | Hold 400ms, then move |
| --- | --- | --- | --- |
| PointerSensor + TouchSensor | `manipulation` | drag starts, then cancels as the page scrolls | the same: no long press ever lifts it |
| PointerSensor + TouchSensor | `none` | drag starts after 8px, the page cannot scroll | drag starts after 8px |
| pointer sensor that skips touch + TouchSensor | `manipulation` | the page scrolls, no drag | drag starts at 250ms, the page stays put |

A common workaround picks one sensor by device type, which breaks on touch screen laptops, where one person uses both the trackpad and the screen. The last row is the cleaner fix: a PointerSensor subclass whose activator skips touch pointers, so the mouse and pen take the pointer path and fingers take the touch path. Our Kanban runs the same pointer and touch sensors. Save this as `components/use-drag-sensors.ts`; the full example at the end imports it:

```ts
"use client";

import { KeyboardSensor, PointerSensor, TouchSensor, useSensor, useSensors } from "@dnd-kit/core";
import { sortableKeyboardCoordinates } from "@dnd-kit/sortable";

// PointerSensor for mouse and pen only: fingers are left to the TouchSensor
export class MousePointerSensor extends PointerSensor {
  static activators = [
    {
      eventName: "onPointerDown" as const,
      handler: ({ nativeEvent: event }: { nativeEvent: PointerEvent }) =>
        event.isPrimary && event.button === 0 && event.pointerType !== "touch",
    },
  ];
}

export function useDragSensors() {
  return useSensors(
    // mouse and pen: 8px of travel, so a click is still a click
    useSensor(MousePointerSensor, { activationConstraint: { distance: 8 } }),
    // touch: a 250ms press, so a swipe still scrolls
    useSensor(TouchSensor, { activationConstraint: { delay: 250, tolerance: 8 } }),
    // keyboard: Space or Enter lifts, arrows move, Space or Enter drops, Escape cancels
    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
  );
}
```

The stock `MouseSensor` plus `TouchSensor` pairing from the docs works too.

#### What delay and tolerance should the TouchSensor use?

250ms with 5 to 8px of tolerance. The delay is how long a finger must rest before the card lifts; the tolerance is how far it may drift in that time before dnd kit gives up and lets the browser scroll. Those two numbers are the whole dnd kit mobile scroll trade-off:

| Setting | Too low | Too high |
| --- | --- | --- |
| `delay` | a slow swipe lifts a card instead of scrolling | the drag feels broken, and it collides with the system long press (text selection, the iOS callout) |
| `tolerance` | a resting finger drifts a pixel and the drag never starts | a slow scroll can turn into a drag halfway through |

Never use a tolerance of zero. The [Touch sensor docs](https://dndkit.com/legacy/api-documentation/sensors/touch) say that with zero, any movement during the delay aborts the drag, and a finger resting on glass always moves a little. [Issue #1955](https://github.com/clauderic/dnd-kit/issues/1955), opened in March 2026 against the rewrite, reported drags that never started on some Android phones, mostly Samsung; in July 2026 the reporter traced it to a `tolerance: 0` and fixed it with 5. The rewrite's PointerSensor gives touch [a 250ms delay with 5px tolerance](https://dndkit.com/extend/sensors/pointer-sensor) by default; our Kanban and Deal Pipeline use 250ms and 8px.

A long press needs feedback at the moment it fires, or people let go too early. The Kanban calls `navigator.vibrate(10)` in `onDragStart` when the activator event is a `TouchEvent`, and lifts the card with a small scale and a 2 degree tilt on a spring. The tick does nothing on an iPhone, because Safari on iOS has no Vibration API ([caniuse](https://caniuse.com/vibration), checked in October 2026; the [web vibration API guide](https://wingo-ui.com/blog/web-vibration-api-haptic-feedback) covers what an iPhone can do instead).

#### Where does touch-action go?

On the element that receives the listeners, with a value that depends on which sensor owns the finger. The docs recommend `manipulation` for the TouchSensor and `none` for the PointerSensor, and the browser reads the value when the touch starts: changing it after `pointerdown` or `touchstart` is ignored. Put it in the CSS, never in a drag start handler.

| Drag surface | Sensor that owns the finger | `touch-action` | Tailwind v4 |
| --- | --- | --- | --- |
| The whole card or row, long press | TouchSensor | `manipulation` | `touch-manipulation` |
| A grip button | either | `none` | `touch-none` |
| The scroll container | no sensor | leave it `auto` | nothing |

`manipulation` keeps panning and pinch zoom and drops double-tap zoom; once the drag is active, the TouchSensor cancels `touchmove` itself. A long-press surface needs two more classes: `select-none`, so the press does not select the card's text, and `[-webkit-touch-callout:none]`, so iOS does not open its callout. dnd kit already cancels `contextmenu` on the window while a touch is pending or dragging.

The Wingo UI List takes the grip route: a 32px button with `touch-none` whose hit area grows to 44px on coarse pointers ([why 44px](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind)), so a swipe on the row still scrolls the page or opens its swipe actions.

#### Why does a drag cancel on iPhone when the page scrolls?

Because `@dnd-kit/core` cancels any pointer or touch drag on a window `resize`, and Safari on iOS fires `resize` when its toolbar collapses or expands as the document scrolls. [Issue #686](https://github.com/clauderic/dnd-kit/issues/686) traced it on iOS 15 in March 2022. It was closed in February 2026 as filed against the old version, not fixed: the `resize` listener is still in the 6.3.1 sensors, so the cancel still happens.

The fix is layout: keep the drag inside its own scroll container so the document does not move. Give the board or list a real height (`h-dvh`, or `flex-1 min-h-0` in a full-height layout; see [100vh on mobile](https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind)), `overflow-y-auto` for a list or `overflow-x-auto` for a board, and `overscroll-contain` so reaching the end does not hand the scroll to the page.

The container also decides what auto-scroll moves. dnd kit scrolls the item's scrollable ancestors, meaning elements with `overflow` set to `auto` or `scroll`, plus the document, when the pointer comes within 20% of their edge. A wrapper with `overflow: hidden` does not count, so a board clipped that way cannot auto-scroll to its hidden columns; the page scrolls instead, if it can. If a phone board uses scroll snap, pause it during the drag: the Kanban board is `snap-x snap-mandatory` with `data-dragging:snap-none`, so the auto-scroll can glide to the next column.

Try it at phone width (or in device mode): the Kanban shows one column at a time with the next one peeking, a swipe scrolls it, and a 250ms press lifts a card you can carry to the edge to reach the next column.

> Live demo (Kanban): Long press a card to lift it, then carry it to the board's edge to reach the next column; a quick swipe still scrolls. With a mouse it lifts after 8px. Tab to a card and press Space to move it with the arrow keys. Try it at [Kanban](https://wingo-ui.com/components/kanban) and install it with `npx wingo-ui@latest add kanban`.

#### How do you make drag and drop accessible?

With two separate paths, and dnd kit gives you one of them. The KeyboardSensor covers keyboard users: by default Space or Enter lifts, the arrow keys move, Space, Enter or Tab drops and Escape cancels, while `DndContext` reads instructions and live announcements to screen readers. Write your own `announcements`, because the defaults read raw ids ("Picked up draggable item d02."). The Kanban passes `keyboardCodes: { start: ["Space"], cancel: ["Escape"], end: ["Space", "Enter"] }`, since Enter opens a card, and its own `coordinateGetter` sends Left and Right to the nearest card in the next column that accepts it.

The second path is for people who can tap but not drag, because of a tremor, a trackball or a head pointer. WCAG 2.2 success criterion [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) (level AA) requires that dragging "can be achieved by a single pointer without dragging", and the W3C's explanation says keyboard equivalence alone does not meet it. One of its examples is the pattern a list needs: after a tap on an item, controls next to it move it up or down. For a board, the same idea is a menu that names the target column. The Kanban puts Move to first in every card's ⋯ menu, which opens as a bottom sheet on phones.

#### How do you build a sortable list that works on phones?

Combine everything above in one component: the `useDragSensors` hook, long-press rows, a list with its own scroller, named announcements and up and down buttons for the tap path. It also passes `id={useId()}` to `DndContext`. Without it, dnd kit numbers its `aria-describedby` ids with a module-level counter, the server and the browser can count differently, and React reports a hydration mismatch in Next.js.

Install the packages with `npm i @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities lucide-react` and the free [Button](https://wingo-ui.com/components/button) with `npx wingo-ui@latest add button`, then save this as `components/sortable-tasks.tsx`, next to `use-drag-sensors.ts`:

```tsx
"use client";

import { useId, useState } from "react";
import { DndContext, closestCenter, type Announcements, type DragEndEvent, type UniqueIdentifier } from "@dnd-kit/core";
import { SortableContext, arrayMove, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
import { CSS } from "@dnd-kit/utilities";
import { ArrowDown, ArrowUp } from "lucide-react";
import { Button } from "@/components/ui/button";
import { useDragSensors } from "./use-drag-sensors";

type Task = { id: string; title: string };

export function SortableTasks({ initial }: { initial: Task[] }) {
  const [tasks, setTasks] = useState(initial);
  const sensors = useDragSensors();
  // a stable id: dnd kit's own counter differs between the server and the browser
  const dndId = useId();

  const name = (id: UniqueIdentifier) => tasks.find((task) => task.id === id)?.title ?? "Task";
  const place = (id: UniqueIdentifier) => `position ${tasks.findIndex((task) => task.id === id) + 1} of ${tasks.length}`;
  const announcements: Announcements = {
    onDragStart: ({ active }) => `Picked up ${name(active.id)}.`,
    onDragOver: ({ active, over }) => (over ? `${name(active.id)} is at ${place(over.id)}.` : undefined),
    onDragEnd: ({ active, over }) => (over ? `Dropped ${name(active.id)} at ${place(over.id)}.` : `${name(active.id)} is back in place.`),
    onDragCancel: ({ active }) => `Canceled. ${name(active.id)} is back in place.`,
  };

  const move = (from: number, to: number) => {
    if (to < 0 || to >= tasks.length || from === to) return;
    setTasks((current) => arrayMove(current, from, to));
  };

  const onDragEnd = ({ active, over }: DragEndEvent) => {
    if (!over) return;
    move(tasks.findIndex((task) => task.id === active.id), tasks.findIndex((task) => task.id === over.id));
  };

  return (
    <DndContext
      id={dndId}
      sensors={sensors}
      collisionDetection={closestCenter}
      onDragEnd={onDragEnd}
      accessibility={{
        announcements,
        screenReaderInstructions: {
          draggable: "Press Space to pick up a task. Arrow keys move it, Space drops it, Escape cancels.",
        },
      }}
    >
      <SortableContext items={tasks} strategy={verticalListSortingStrategy}>
        {/* its own scroller: the drag scrolls this list, not the document, so Safari's toolbar stays put */}
        <ul className="flex max-h-[70dvh] flex-col gap-2 overflow-y-auto overscroll-contain p-1">
          {tasks.map((task, index) => (
            <TaskRow key={task.id} task={task} index={index} last={index === tasks.length - 1} onMove={move} />
          ))}
        </ul>
      </SortableContext>
    </DndContext>
  );
}

type TaskRowProps = { task: Task; index: number; last: boolean; onMove: (from: number, to: number) => void };

function TaskRow({ task, index, last, onMove }: TaskRowProps) {
  const { attributes, listeners, setNodeRef, setActivatorNodeRef, transform, transition, isDragging } = useSortable({
    id: task.id,
  });

  return (
    <li
      ref={setNodeRef}
      style={{ transform: CSS.Transform.toString(transform), transition }}
      data-dragging={isDragging || undefined}
      className="flex items-center gap-1 rounded-2xl bg-card ps-4 pe-1 shadow-raised data-dragging:relative data-dragging:z-10 data-dragging:shadow-floating"
    >
      {/* the label is the drag surface: a swipe scrolls the list, a 250ms press lifts the row */}
      <div
        ref={setActivatorNodeRef}
        {...attributes}
        {...listeners}
        className="flex min-h-12 flex-1 cursor-grab touch-manipulation select-none items-center text-sm outline-hidden [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-ring"
      >
        {task.title}
      </div>
      {/* the same move with single taps (WCAG 2.5.7) */}
      <Button variant="ghost" size="icon" radius="full" aria-label={`Move ${task.title} up`} disabled={index === 0} onClick={() => onMove(index, index - 1)}>
        <ArrowUp />
      </Button>
      <Button variant="ghost" size="icon" radius="full" aria-label={`Move ${task.title} down`} disabled={last} onClick={() => onMove(index, index + 1)}>
        <ArrowDown />
      </Button>
    </li>
  );
}
```

A server page, such as `app/tasks/page.tsx`, can render it with plain data:

```tsx
import { SortableTasks } from "@/components/sortable-tasks";

const tasks = [
  { id: "t1", title: "Send the New York lease to Emma Carter" },
  { id: "t2", title: "Book the photographer for Friday" },
  { id: "t3", title: "Review the Q4 budget" },
];

export default function TasksPage() {
  return <SortableTasks initial={tasks} />;
}
```

Then test on a real phone: device mode does not show the Safari toolbar, a real finger's drift or the system long press. Try every path with a screen reader on, too.

If you would rather not own this code for a plain list, the List has sortable rows built in: turn on `sortable`, then drag a row by its grip, or Tab to a grip and use Space and the arrow keys; Alt with Up or Down moves a focused row one step. It has no tap path for reordering, so for 2.5.7 add Move up and Move down entries to each row's `actions` menu (its ⋯ button is always visible on touch) and reorder your `items` in their handlers.

> Live demo (List): Drag a row by its grip to reorder the inbox; a swipe on the row still scrolls. Tab to a grip and press Space, then the arrow keys, or press Alt with Up or Down on a focused row. Try it at [List](https://wingo-ui.com/components/list) and install it with `npx wingo-ui@latest add list`.

#### Is there a React kanban board that already works on phones?

Yes: the Wingo UI Kanban ships the touch, mouse and keyboard setup from this post, the Move to menu and the phone layout. `npx wingo-ui@latest add kanban` copies it and everything it imports into your project and installs its npm packages. The Kanban, List and Deal Pipeline are Pro components ([pricing](https://wingo-ui.com/pricing)). For the other phone gestures, such as swipe actions and drag to dismiss, read the [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components). The [React form components guide](https://wingo-ui.com/blog/react-form-components-guide) applies the same touch, keyboard and screen reader rules to every form control, and more tutorials like this one are in the [component guides category](https://wingo-ui.com/blog/category/components).

#### Components in this post

- [Kanban](https://wingo-ui.com/components/kanban) (Pro): A board of columns and cards for pipelines, orders and tasks: drag with mouse, touch or keyboard, WIP limits, inline add and a phone layout. Install: `npx wingo-ui@latest add kanban`
- [List](https://wingo-ui.com/components/list) (Pro): Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder. Install: `npx wingo-ui@latest add list`
- [Deal Pipeline](https://wingo-ui.com/components/deal-pipeline) (Pro): The sales pipeline: stages with weighted totals, a forecast summary, drag between stages with a lost reason, and a list view. Install: `npx wingo-ui@latest add deal-pipeline`

#### FAQ

##### Why is dnd kit not working on mobile?

DndContext uses the PointerSensor by default, and pointer events cannot stop the browser from scrolling, so a touch drag is canceled as soon as the page starts to pan. Either set touch-action: none on a drag handle, or let a TouchSensor with a 250ms delay own the finger, next to a pointer sensor that skips touch, so a long press lifts the item and a swipe still scrolls.

##### Can I use PointerSensor and TouchSensor together in dnd kit?

Not the stock PointerSensor. A touch fires pointerdown before touchstart, so the PointerSensor claims the finger and the TouchSensor's delay never runs; subclass PointerSensor with an activator that skips pointerType touch, or pair MouseSensor with TouchSensor.

##### What delay and tolerance should the dnd kit TouchSensor use?

Start with a 250ms delay and 5 to 8px of tolerance; the dnd kit rewrite uses 250ms and 5px as its touch default. Never set the tolerance to 0, because the docs say any movement during the delay then aborts the drag, and a resting finger always drifts a little.

##### Why does dnd kit cancel my drag on iPhone?

@dnd-kit/core cancels pointer and touch drags on a window resize, and Safari on iOS fires resize when its toolbar collapses or expands as the page scrolls. Keep the drag inside its own scroll container so the document never scrolls during a drag.

##### Is keyboard drag and drop enough for accessibility?

It covers keyboard users but not WCAG 2.2 success criterion 2.5.7 Dragging Movements, which asks for a way to do the same thing with single taps or clicks. Add a Move to menu or up and down buttons next to the drag.

##### Should I switch to @dnd-kit/react for mobile drag?

Not for touch alone. The legacy docs point to the new version, and its PointerSensor gives touch a 250ms delay with 5px tolerance by default, but as of October 2026 @dnd-kit/react is at 0.5.0, before 1.0, with a different API. On @dnd-kit/core 6.3.1, the sensor setup in this post fixes touch drag.

---

Source: https://wingo-ui.com/blog/dnd-kit-mobile-touch-drag

### E-Factura VAT Calculation in TypeScript and React

> E-Factura VAT calculation in TypeScript: Romania's 21% and 11% rates, VAT rounded once per rate, the totals ANAF checks to the cent and a React line editor.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Build it: screens and apps](https://wingo-ui.com/blog/category/build)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/e-factura-vat-calculation-javascript

#### TL;DR

An e-Factura VAT calculation groups the invoice lines by VAT category and rate, adds their net amounts, and rounds base times rate once per group to two decimals; per-line VAT is informative only. Every document total then has to come from those same rounded numbers, because ANAF's validation checks the sums to the cent even though it lets the VAT of a rate drift by less than 1 leu. Romania's rates since August 1, 2025 are 21% standard and 11% reduced.

Your invoice editor shows a VAT figure, the PDF matches it, and the XML you upload to ANAF still has to follow one rule that line-by-line code misses: an e-Factura VAT calculation groups the lines by VAT rate, adds their net amounts, and rounds the VAT once per group. Every total in the file then has to come from those rounded numbers, to the cent. This tutorial builds that in TypeScript: Romania's VAT rates with their dates, VAT per rate in integer cents, the validation rules that compare totals, and an invoice line editor in React. The UI is [Invoice Line Items](https://wingo-ui.com/components/invoice-line-items) from Wingo UI, the library we build, so we are not neutral. The per-rate math is plain TypeScript you can paste anywhere.

#### What are the Romanian VAT rates in 2026?

Two rates, both in force since August 1, 2025: 21% standard and 11% reduced. Law 141/2025 raised the standard rate from 19% and replaced the old 9% and 5% reduced rates with a single 11% rate, apart from a transitional 9% for some housing bought under contracts signed by August 1, 2025, which Law 161/2026 extended from July 31 to September 30, 2026 ([Contzilla, August 2026](https://www.contzilla.ro/oficial-legea-161-2026-extinde-aplicarea-cotei-de-9-la-unele-locuinte-intre-7-august-si-30-septembrie-2026/)); [ANAF's before-and-after table of the Fiscal Code](https://static.anaf.ro/static/10/Brasov/Brasov/tva_2025.pdf) shows both versions of article 291. As of October 2026, [ANAF's consolidated Fiscal Code](https://static.anaf.ro/static/10/Anaf/legislatie/Cod_fiscal_norme_2023.htm), last updated by Law 170/2026, still reads 21% and 11%.

| Rate | Code | Use it for |
|---|---|---|
| 21% | S | everything that is not exempt or reduced (19% until Jul 31, 2025) |
| 11% | S | the list in art. 291 (2), including medicines for human use, most food, water and sewerage, books and press, hotel stays, restaurant and catering |
| 0% | E | exempt operations, with an exemption reason |
| 0% | AE | reverse charge, with the buyer's VAT id |
| 0% | K | intra-community supplies, with the buyer's VAT id |

The code is the VAT category an e-Factura line carries (BT-151): S for standard rated, which covers the reduced rate too, E for exempt, AE for reverse charge and K for intra-community supplies.

Two details matter for code. The 11% list has exceptions inside it: alcoholic drinks, non-alcoholic drinks under NC code 2202, food with added sugar and at least 10 g of sugar per 100 g, and food supplements stay at 21%. So store the rate on each product. And the rate depends on a date: article 291 (4) applies the rate in force when the chargeable event happens, usually the delivery. A correction you issue today for a July 2025 delivery carries 19%, so keep dated rates and let the VAT select offer the old one when a correction needs it:

```ts
import { RO_VAT_RATES, type VatRateOption } from "@/lib/invoicing";

// the standard rate by the date of the chargeable event (Fiscal Code art. 291 (4))
const RO_STANDARD_RATE = [
  { from: "2017-01-01", rate: 0.19 },
  { from: "2025-08-01", rate: 0.21 },
];

export const standardRateOn = (isoDate: string) =>
  RO_STANDARD_RATE.findLast((entry) => entry.from <= isoDate)?.rate;

// the VAT select for corrections of supplies made before August 1, 2025
export const RATES_FOR_CORRECTIONS: VatRateOption[] = [
  ...RO_VAT_RATES,
  { value: "19", rate: 0.19, category: "S", label: "19%", description: "Standard rate until Jul 31, 2025" },
];
```

`RO_VAT_RATES` from the [invoicing](https://wingo-ui.com/components/invoicing) lib holds the current five rows of the table above, and the line editor takes any list through its `vatRates` prop.

#### Why is e-Factura VAT computed per rate instead of per line?

Because the standard defines it that way. Rule BR-CO-17 of EN 16931, which e-Factura applies, reads: the VAT category tax amount (BT-117) equals the VAT category taxable amount (BT-116) times the rate (BT-119), rounded to two decimals. The Fiscal Code asks for the same on paper: article 319 (20) requires the taxable base for each rate and the VAT amount in lei for each rate. Adding up rounded line VAT gives a different invoice VAT per rate whenever several lines round in the same direction.

Three 21% lines and one 11% line show it:

| Line | Net | VAT | Rounded |
|---|---|---|---|
| Courier delivery, 21% | 22.50 | 4.725 | 4.73 |
| Packaging, 21% | 7.50 | 1.575 | 1.58 |
| Label printing, 21% | 4.50 | 0.945 | 0.95 |
| Sum of the 21% lines | 34.50 | | 7.26 |
| 21% computed once on 34.50 | 34.50 | 7.245 | 7.25 |
| Books, 3 x 14.50, 11% | 43.50 | 4.785 | 4.79 |

Each line rounds its half cent up, three times over; the rate rounds once. 7.25 is the VAT for 21% on this invoice, and the line figures can stay on the PDF as information.

#### How do I compute VAT per rate in TypeScript without float errors?

Keep money in integer cents and divide integers. `Math.round(22.5 * 0.21 * 100) / 100` returns 4.72, because 22.5 x 0.21 is stored as 4.7249999999999996. We ran every base from 0.01 to 1,000.00 lei: 1,000 of them have a 21% VAT ending in exactly half a cent, and the float formula rounds 188 of those the wrong way, while `toFixed(2)` gets 718 wrong. When the numerator is an integer, a half cent is exactly .5:

```ts
// lib/vat-per-rate.ts
export type VatLine = {
  quantity: number; // up to 3 decimals: 1.5 hours
  unitPrice: number; // without VAT, in lei, up to 2 decimals
  vatRate: number; // a percent: 21, 11 or 0
};

export type VatRow = { rate: number; netCents: number; vatCents: number };

// an integer divided by a power of 10: half a cent is exactly .5 and rounds away from zero
export const divRound = (numerator: number, denominator: number) =>
  Math.sign(numerator) * Math.round(Math.abs(numerator) / denominator);

export const lineNetCents = (line: VatLine) =>
  divRound(Math.round(line.quantity * 1000) * Math.round(line.unitPrice * 100), 1000);

// 21% of 3450 cents: 3450 x 2100 / 10000 = 724.5, so 725
export const vatCents = (netCents: number, rate: number) =>
  divRound(netCents * Math.round(rate * 100), 10_000);

export function vatPerRate(lines: VatLine[]): VatRow[] {
  const nets = new Map<number, number>();
  for (const line of lines) nets.set(line.vatRate, (nets.get(line.vatRate) ?? 0) + lineNetCents(line));
  return [...nets]
    .map(([rate, netCents]) => ({ rate, netCents, vatCents: vatCents(netCents, rate) }))
    .sort((a, b) => b.rate - a.rate);
}
```

```ts
vatPerRate([
  { quantity: 1, unitPrice: 22.5, vatRate: 21 },
  { quantity: 1, unitPrice: 7.5, vatRate: 21 },
  { quantity: 1, unitPrice: 4.5, vatRate: 21 },
  { quantity: 3, unitPrice: 14.5, vatRate: 11 },
]);
// [{ rate: 21, netCents: 3450, vatCents: 725 }, { rate: 11, netCents: 4350, vatCents: 479 }]
```

A reversal (storno) line carries negative amounts. Rounding the absolute value keeps -7.245 at -7.25, the same magnitude the validator computes, since BR-CO-17 compares absolute values.

#### Which e-Factura validation errors check the totals?

BR-CO-10, BR-CO-11, BR-CO-13, BR-CO-14 and BR-CO-15 compare the document totals to the cent, and only BR-S-08, BR-CO-17 and BR-S-09 allow any slack: less than one unit of the invoice currency. We read the rules in the CIUS-RO validation package the Ministry of Finance publishes for e-Factura, [ro16931-ubl 1.0.9](https://mfinante.gov.ro/static/10/eFactura/ro16931-ubl-1.0.9.zip), which embeds the EN 16931 rules from the [European Commission's validation artefacts](https://github.com/ConnectingEurope/eInvoicing-EN16931/tree/validation-1.3.8/ubl/schematron) (version 1.3.8; we rechecked the tolerances below in that release in October 2026):

| Rule | What it checks | Slack |
|---|---|---|
| BR-CO-10 | sum of line nets (BT-106) = the line net amounts (BT-131) added up | none |
| BR-CO-11 | document allowances (BT-107) = the allowance amounts (BT-92) added up | none |
| BR-CO-13 | total without VAT (BT-109) = BT-106 - BT-107 + charges | none |
| BR-CO-14 | VAT total (BT-110) = the VAT of each rate (BT-117) added up | none |
| BR-CO-15 | total with VAT (BT-112) = BT-109 + BT-110 | none |
| BR-S-08 | each rate's base (BT-116) = its lines - its allowances + its charges | under 1 unit |
| BR-CO-17 | each rate's VAT = base x rate, rounded to 2 decimals | under 1 unit |
| BR-S-09 | the same, for standard rated rows | under 1 unit |
| BR-E-08 | the base of the exempt row | none |
| BR-AE-08 | the base of the reverse charge row | none |
| UBL-DT-01 | every amount has at most 2 decimals; unit prices are excluded | none |

BR-CO-17 accepts a VAT that is less than 1 leu (one unit of the invoice currency) away from base times rate. Summing rounded line VAT therefore passes it on most invoices: each line drifts by half a cent at most, so it takes about 200 lines rounding the same way to reach 1 leu. The e-Factura validation errors come from mixing the two paths: BT-117 from the per-rate breakdown while BT-110 is the sum of line VAT, or BT-112 as the sum of line totals with VAT. Those sums have no tolerance, every rule above is flagged fatal, and one cent apart means an error message comes back instead of a validated invoice. Do not build on the slack either. Your PDF, your database and the buyer's books should all show 7.25.

#### How do I turn the totals into e-Factura fields?

Derive every field from the same integers, in one order: line nets, the document discount per rate, the base and VAT of each rate, then the document totals. A discount on the whole invoice is the step that breaks mixed-rate invoices. BR-S-08 counts only the allowances that carry the same category and rate as the row, so a 100 lei discount on an invoice with 21% and 11% lines becomes two allowances, one per rate.

`computeInvoiceTotals` from the invoicing lib already shares a document discount across the lines by value, and the last line takes the remainder so the cents add up. The function below keeps each line's own discount inside BT-131, reads the document share back out per rate, and recomputes the VAT of each rate in cents:

```ts
// lib/efactura-totals.ts
import { computeInvoiceTotals, type VatCategory } from "@/lib/invoicing";
import type { InvoiceDocumentDiscount, InvoiceLine } from "@/components/ui/invoice-line-items";
import { vatCents } from "@/lib/vat-per-rate";

type Group = { rate: number; category: VatCategory };

// every amount in cents; rate is the percent the XML carries (BT-119)
export type EFacturaTotals = {
  lines: (Group & { id: string; net: number })[]; // BT-131
  allowances: (Group & { amount: number })[]; // BG-20, one per rate
  breakdown: (Group & { taxable: number; vat: number })[]; // BG-23: BT-116, BT-117
  lineNet: number; // BT-106
  allowanceTotal: number; // BT-107
  taxExclusive: number; // BT-109
  vat: number; // BT-110
  taxInclusive: number; // BT-112
};

const cents = (amount: number) => Math.round(amount * 100);
const percent = (rate: number) => Number((rate * 100).toFixed(2));
const sum = (values: number[]) => values.reduce((a, b) => a + b, 0);
const categoryOf = (rate: number, line: InvoiceLine): VatCategory =>
  line.vatCategory ?? (rate > 0 ? "S" : "E");

// B2B: unit prices without VAT
export function toEFacturaTotals(lines: InvoiceLine[], discount: InvoiceDocumentDiscount | null): EFacturaTotals {
  const totals = computeInvoiceTotals(lines, {
    discount,
    categoryFor: (rate, line) => categoryOf(rate, line as InvoiceLine),
  });
  const groups = new Map<string, Group & { taxable: number; allowance: number }>();

  const outLines = totals.lines.map((line, i) => {
    const group = { rate: percent(line.vatRate), category: categoryOf(line.vatRate, lines[i]) };
    // BT-131 keeps the line's own discount; its share of the document discount becomes an allowance
    const net = cents(line.gross) - cents(line.discount);
    const key = `${group.rate}|${group.category}`;
    const entry = groups.get(key) ?? { ...group, taxable: 0, allowance: 0 };
    entry.taxable += cents(line.net);
    entry.allowance += net - cents(line.net);
    groups.set(key, entry);
    return { ...group, id: line.id, net };
  });

  const breakdown = [...groups.values()].map(({ rate, category, taxable }) => ({
    rate,
    category,
    taxable,
    vat: category === "S" ? vatCents(taxable, rate) : 0,
  }));
  const allowances = [...groups.values()]
    .filter((group) => group.allowance > 0)
    .map(({ rate, category, allowance }) => ({ rate, category, amount: allowance }));

  const lineNet = sum(outLines.map((line) => line.net));
  const allowanceTotal = sum(allowances.map((allowance) => allowance.amount));
  const vat = sum(breakdown.map((row) => row.vat));
  const taxExclusive = lineNet - allowanceTotal;
  return { lines: outLines, allowances, breakdown, lineNet, allowanceTotal, taxExclusive, vat, taxInclusive: taxExclusive + vat };
}
```

Take the sample invoice from the editor demo further down: 25 licenses at 250 lei with 10% off, 6 hours of training at 320 lei and an e-Factura integration at 1,500 lei, all at 21%, plus 12 printed guides at 64.90 lei at 11%. With a 100 lei document discount, the function returns allowances of 92.07 lei at 21% and 7.93 lei at 11%, bases of 8,952.93 and 770.87, VAT of 1,880.12 and 84.80, and 11,688.72 lei in total.

> Live demo (Invoicing): A $100 document discount is already set: press + or − on a quantity and the 21% and 11% rows each recompute their VAT from their own base (this demo prices in dollars). Try it at [Invoicing](https://wingo-ui.com/components/invoicing) and install it with `npx wingo-ui@latest add invoicing`.

Then check the numbers the XML will carry, whatever produced them: an old system, a stored draft, a hand edit. The check runs on the server right before you build the file and answers with the rule ids ANAF's validator uses:

```ts
// lib/efactura-preflight.ts
import type { EFacturaTotals } from "@/lib/efactura-totals";
import { vatCents } from "@/lib/vat-per-rate";

const sum = (values: number[]) => values.reduce((a, b) => a + b, 0);

export function preflight(t: EFacturaTotals): string[] {
  const problems: string[] = [];
  if (t.lineNet !== sum(t.lines.map((l) => l.net))) problems.push("BR-CO-10");
  if (t.allowanceTotal !== sum(t.allowances.map((a) => a.amount))) problems.push("BR-CO-11");
  if (t.taxExclusive !== t.lineNet - t.allowanceTotal) problems.push("BR-CO-13");
  if (t.vat !== sum(t.breakdown.map((r) => r.vat))) problems.push("BR-CO-14");
  if (t.taxInclusive !== t.taxExclusive + t.vat) problems.push("BR-CO-15");
  for (const row of t.breakdown) {
    const same = (x: { rate: number; category: string }) => x.rate === row.rate && x.category === row.category;
    const base = sum(t.lines.filter(same).map((l) => l.net)) - sum(t.allowances.filter(same).map((a) => a.amount));
    // intra-community rules are named IC, the others after their category code
    if (row.taxable !== base) problems.push(`BR-${row.category === "K" ? "IC" : row.category}-08 at ${row.rate}%`);
    // ANAF lets this drift by less than 1 leu; we accept 0
    if (row.category === "S" && row.vat !== vatCents(row.taxable, row.rate)) problems.push(`BR-CO-17 at ${row.rate}%`);
  }
  return problems;
}
```

#### How do I build the editable invoice lines in React?

Give the editor the lines and read the totals it computes, then recompute on the server. [Invoice Line Items](https://wingo-ui.com/components/invoice-line-items) edits the lines like a small spreadsheet: a product search that fills unit, price and VAT, a VAT select that defaults to `RO_VAT_RATES`, a discount per line with a % / lei switch, and drag to reorder. The price cells are a [Currency Input](https://wingo-ui.com/components/currency-input), so 1234.5 becomes 1,234.5 as you type and 1,234.50 on blur. Under the lines, the totals show the taxable base, one VAT row per rate and the grand total, all from one `computeInvoiceTotals` call on every keystroke, and `onValueChange(lines, totals)` hands you the same numbers. When the editor is narrower than 768px, every line becomes a card: tap it to edit the line in a bottom sheet on phones (a dialog on larger screens), and the totals fold into a Total row that opens the breakdown.

> Live demo (Invoice line items): Tap a line, change its VAT from 21% to 11% and save it, then open the breakdown under Total: the base and VAT of each rate follow every edit. Try it at [Invoice line items](https://wingo-ui.com/components/invoice-line-items) and install it with `npx wingo-ui@latest add invoice-line-items`.

In a form, the editor's `name` prop writes the lines as JSON into a hidden input, so a server action receives them with the rest of the form:

```tsx
// app/invoices/new/invoice-form.tsx
"use client";

import { useActionState, useState } from "react";
import { Alert } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import {
  InvoiceLineItems,
  type InvoiceDocumentDiscount,
  type InvoiceProduct,
} from "@/components/ui/invoice-line-items";
import { issueInvoice } from "./actions";

export function InvoiceForm({ products }: { products: InvoiceProduct[] }) {
  const [discount, setDiscount] = useState<InvoiceDocumentDiscount | null>(null);
  const [state, formAction, pending] = useActionState(issueInvoice, { problems: [] });

  return (
    <form action={formAction} className="flex flex-col gap-4">
      <InvoiceLineItems
        name="lines"
        products={products}
        documentDiscount={discount}
        onDocumentDiscountChange={setDiscount}
        currency="RON"
        locale="en-US"
      />
      <input type="hidden" name="discount" value={JSON.stringify(discount)} />
      {state.problems.length > 0 && (
        <Alert tone="danger" title="These totals would fail e-Factura" description={state.problems.join(", ")} />
      )}
      <Button type="submit" loading={pending} className="self-end">
        Issue invoice
      </Button>
    </form>
  );
}
```

```ts
// app/invoices/new/actions.ts
"use server";

import type { InvoiceLine } from "@/components/ui/invoice-line-items";
import { preflight } from "@/lib/efactura-preflight";
import { toEFacturaTotals } from "@/lib/efactura-totals";

export async function issueInvoice(_previous: { problems: string[] }, form: FormData) {
  // parse with zod in a real app; totals from the browser are for display only
  const lines = JSON.parse(String(form.get("lines") ?? "[]")) as InvoiceLine[];
  const discount = JSON.parse(String(form.get("discount") || "null"));
  const totals = toEFacturaTotals(lines, discount);
  const problems = preflight(totals);
  if (problems.length > 0) return { problems };
  // build the UBL from `totals`, store it with the invoice number, then upload it to SPV
  return { problems: [] };
}
```

The whole screen around it, with a client picker and CUI lookup, the series and number, due dates, an A4 preview and the e-Factura switch, is the [Invoice Page](https://wingo-ui.com/components/invoice-page) block. Its `onIssue` receives the document with `lines` and `documentDiscount`, the two inputs `toEFacturaTotals` needs.

#### What changes for EUR invoices and 0% lines?

The invoice can be in euros; its VAT must also exist in lei. Article 319 (23) of the Fiscal Code lets the amounts use any currency as long as the VAT is expressed in lei at the exchange rate of article 290. In the XML, rule BR-RO-030 sets the VAT accounting currency (BT-6) to RON on any non-RON invoice, and BR-53 then requires the VAT total in that currency (BT-111). The Invoice Page shows the RON equivalent of a EUR total at the BNR rate; compute BT-111 on the server from the same per-rate VAT.

The 0% rows need more than a zero:

- **Exempt (E)**: an exemption reason code or text on the breakdown row (BR-E-10), and a VAT of 0 (BR-E-09).
- **Reverse charge (AE)**: the reason "Reverse charge" (BR-AE-10), a VAT of 0 (BR-AE-09), the seller's VAT id and the buyer's VAT id or registration number (BR-AE-02).
- **Intra-community (K)**: the reason "Intra-community supply" (BR-IC-10) and the VAT ids of the seller and the buyer (BR-IC-02).

The ids those rules ask for have their own guides: [Romanian CUI validation](https://wingo-ui.com/blog/romanian-cui-validation-javascript) for a company's tax and VAT id, the [Romanian CNP validator](https://wingo-ui.com/blog/romanian-cnp-validator-javascript) for B2C buyers (e-Factura accepts 13 zeros when the buyer gives none), and [IBAN validation in JavaScript](https://wingo-ui.com/blog/iban-validation-javascript) for the account you print under payment terms.

#### Should I copy this code or install the components?

Copy the math. `vat-per-rate.ts` has no imports and the preflight needs only its `vatCents` and one type, so both paste into any TypeScript project; `efactura-totals.ts` builds on `computeInvoiceTotals` from the invoicing lib and two types from the line editor. If you want React invoice line items that already show VAT per rate, the editor above installs with `npx wingo-ui@latest add invoice-line-items` and brings the invoicing lib and Currency Input with it. All three, and the Invoice Page, are part of [Wingo UI Pro](https://wingo-ui.com/pricing).

For the rest of an admin app around this form, the [Next.js admin dashboard tutorial](https://wingo-ui.com/blog/nextjs-admin-dashboard-tutorial) builds the shell, tables and settings, and more [step-by-step React builds](https://wingo-ui.com/blog/category/build) live in the Build it category.

#### Components in this post

- [Invoice line items](https://wingo-ui.com/components/invoice-line-items) (Pro): The lines of an invoice, quote or order edited like a small spreadsheet, with VAT per rate computed the way e-Factura checks it. Install: `npx wingo-ui@latest add invoice-line-items`
- [Invoicing](https://wingo-ui.com/components/invoicing) (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: `npx wingo-ui@latest add invoicing`
- [Invoice Page](https://wingo-ui.com/components/invoice-page) (Pro): An invoice editor and viewer for Romanian B2B: client, series, dates, VAT lines, totals, an A4 preview, sending and e-Factura status. Install: `npx wingo-ui@latest add invoice-page`
- [Currency Input](https://wingo-ui.com/components/currency-input) (Pro): A money field formatted per locale as you type, with the symbol on the right side, an optional currency selector and quick amounts. Install: `npx wingo-ui@latest add currency-input`

#### FAQ

##### What are the VAT rates in Romania in 2026?

21% standard and 11% reduced, both in force since August 1, 2025 under Law 141/2025 and article 291 of the Fiscal Code. Before that date the standard rate was 19% and the reduced rates were 9% and 5%; a transitional 9% for some housing, extended by Law 161/2026, ended with deliveries on September 30, 2026. Exempt, reverse charge and intra-community lines go on an e-Factura invoice at 0% with the category codes E, AE and K.

##### Is e-Factura VAT calculated per line or per rate?

Per rate. Rule BR-CO-17 defines the VAT of each rate as the rate's taxable amount times the rate, rounded to two decimals, and article 319 (20) of the Fiscal Code asks for the VAT amount in lei for each rate. VAT shown on a line is informative and never feeds the totals.

##### Why does ANAF reject my e-Factura with BR-CO-14 or BR-CO-15?

Both rules compare sums to the cent. BR-CO-14 needs the invoice VAT total to equal the sum of the VAT per rate, and BR-CO-15 needs the total with VAT to equal the total without VAT plus that VAT. They fail when one total comes from rounded line amounts and another from the per-rate breakdown.

##### Does e-Factura accept a one-cent difference in VAT?

For the VAT of a rate, yes: in the ro16931-ubl 1.0.9 validation package, BR-CO-17 accepts a value less than one currency unit away from base times rate. The rules that add amounts up (BR-CO-10, BR-CO-11, BR-CO-13, BR-CO-14 and BR-CO-15) have no tolerance at all.

##### Which VAT rate applies when a July 2025 delivery is invoiced in August 2025?

Generally the rate in force when the chargeable event happened, which for a delivery is the delivery date, per article 291 (4) of the Fiscal Code. That makes it 19% for a July 2025 delivery, with exceptions for advances and invoices issued before the delivery.

---

Source: https://wingo-ui.com/blog/e-factura-vat-calculation-javascript

### How to Update shadcn Components Without Losing Edits

> Update shadcn components without losing edits: what shadcn diff and add --diff show, why a 2-way diff hides whose change is whose, and how a 3-way merge works.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 10 min
- Canonical: https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits

#### TL;DR

The shadcn CLI has no merge: add --diff lists every difference between your copy and the registry without saying which side made it, and add --overwrite replaces the file, edits included. To keep your edits, run a 3-way merge on each file (the copy as installed, your copy and the new upstream) with git merge-file, keeping the installed copies on a git branch. The Wingo UI CLI saves the installed copy itself, so npx wingo-ui@latest update runs that merge and stops only where both sides changed the same or adjacent lines.

You installed a shadcn/ui button a few months ago, gave it a brand variant and a taller default size, and now upstream has changes you want. When you try to update shadcn components that you have edited, the CLI gives you two tools: `add --overwrite`, which replaces the file and your edits with it, and `add --diff`, which lists every difference between your copy and the registry without saying who made each one. This tutorial covers why copies drift, what shadcn diff can and cannot tell you, and how a 3-way merge pulls upstream fixes into files you already changed: first with a git script for stock shadcn/ui, then with a CLI that does it for you.

#### Why do copied components drift from upstream?

Because the copy stops changing the moment the CLI writes it, and upstream keeps going. A shadcn component is a file in your repo with no version attached. As of October 2026 (shadcn 4.21.4), `components.json` stores settings such as your style, Tailwind, aliases, icon library and registries, and nothing about which components you installed or when. Meanwhile upstream ships changes like these:

- **September 2026:** "Every shadcn component now imports `cn` from the `cn` package" ([shadcn changelog](https://ui.shadcn.com/docs/changelog)). The import line changed in every component.
- **March 2025:** new dark mode colors. The [Tailwind v4 page](https://ui.shadcn.com/docs/tailwind-v4) tells existing projects to run `add --all --overwrite`, then "Review and re-apply any changes you made to your components."
- **Bug fixes**, which land the same way. The Wingo UI [Data Table](https://wingo-ui.com/components/data-table) 1.0.1 fixed header cells that dropped over the first row while the header was pinned. The fix was one `className` in a file of almost 4,000 lines.

#### What does shadcn diff show, and what does it miss?

It shows a 2-way diff: your file against the registry's current version, after the CLI applies your aliases and icon library. The standalone command is deprecated; in shadcn 4.21.4 its help reads "[DEPRECATED] Use `add [component] --diff` instead." The flag arrived with [shadcn CLI v4](https://ui.shadcn.com/docs/changelog/2026-03-cli-v4) in March 2026, together with `--dry-run` and `--view`, and without a path it shows the first 5 files.

We tested it in a scratch Next.js project: the shadcn button as published in March 2026, plus two local edits, a `brand` variant and a 40px default size. This is the trimmed output of `npx shadcn@4.21.4 add button --diff`:

```diff
@@ -1,9 +1,8 @@
 import * as React from "react"
 import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "cn"
 import { Slot } from "radix-ui"

-import { cn } from "@/lib/utils"
-
@@ -19,10 +18,9 @@
         link: "text-primary underline-offset-4 hover:underline",
-        brand: "bg-orange-600 text-white hover:bg-orange-600/90",
       },
       size: {
-        default: "h-10 px-4 py-2 has-[>svg]:px-3",
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
```

The first hunk is upstream's change. The other two are our edits, shown as lines `--overwrite` would undo. Nothing in the output tells them apart, because a 2-way diff only knows two files. To know which side changed a line, you need a third: the component as it was installed, which shadcn does not keep. In the same project, the deprecated `npx shadcn@4.21.4 diff button` printed "No updates found for button.", so stick with the flag.

For edited files, shadcn points you to your coding agent. The CLI v4 post suggests asking it to "check for updates from @shadcn and merge with my local changes", and the [official skill](https://github.com/shadcn-ui/ui/blob/main/skills/shadcn/SKILL.md) tells the agent to "read the local file, analyze the diff, and apply upstream updates while preserving local modifications." The agent sees the same 2-way diff, so unless it digs the installed copy out of git history, it has to guess which side made each change. The script below gets that copy from git, for you or for the agent.

#### How do you update all shadcn components at once?

Re-add them with `--overwrite`, which is safe only for files you never edited. shadcn 4.21.4 has no `update` command, so "shadcn update all components" comes down to `npx shadcn@latest add --all --overwrite`. It re-adds every component in the registry, including ones you never installed, and replaces your files. Re-running `init --reinstall` first offers to overwrite `components.json`, then reinstalls the components you already have, with a warning that they "will be re-installed and overwritten". Find the files you never touched first:

```bash
for f in components/ui/*.tsx; do
  first=$(git log --diff-filter=A --format=%H -- "$f" | tail -1)
  git diff --quiet "$first" -- "$f" && echo "untouched: $f"
done
```

A file that still matches the commit that added it is safe to overwrite, so pass only those names to `npx shadcn@latest add <name...> --overwrite`. Merge the rest.

#### How do you update shadcn components you have edited?

Merge three versions of each file: the copy the CLI installed (the base), your copy, and the new upstream. Where only one side changed a region, the merge takes that side; where both changed the same lines, it writes conflict markers. This is the step shadcn's own docs skip when you upgrade shadcn components: they stop at re-applying your changes by hand or asking an agent. `git merge-file` does the merge; the work is getting the base and the upstream into files, and a branch that holds only pristine CLI output does both.

##### 1. Create a branch with the files as installed

Run this once. It rebuilds each component from the commit that first added it, which is the copy the CLI wrote if you committed before editing:

```bash
git switch -c shadcn-upstream
for f in components/ui/*.tsx; do
  first=$(git log --diff-filter=A --format=%H -- "$f" | tail -1)
  git show "$first:$f" > "$f"
done
git commit -am "shadcn: components as installed"
git switch -
```

##### 2. Write the new upstream on that branch and merge it

Run this for every update. List the components you have, since `--all` would also install the ones you don't:

```bash
git switch shadcn-upstream
npx shadcn@latest add button dialog --overwrite --yes
git add -A && git commit -m "shadcn: upstream $(date +%F)"
git switch -

for f in $(git diff --name-only shadcn-upstream~1 shadcn-upstream -- components/ui); do
  # a file upstream added: take it as is
  if [ ! -f "$f" ]; then git show "shadcn-upstream:$f" > "$f"; continue; fi
  git show "shadcn-upstream~1:$f" > /tmp/base.tsx
  git show "shadcn-upstream:$f" > /tmp/upstream.tsx
  git merge-file -L yours -L installed -L upstream "$f" /tmp/base.tsx /tmp/upstream.tsx \
    || echo "resolve conflicts in $f"
done
```

`git merge-file` writes the result into your file and exits with the number of conflicts, so the loop names every file that needs a look. If the commit on the upstream branch reports nothing to commit, upstream has not changed and there is nothing to merge. Otherwise the branch now holds the upstream you just merged, so the next update uses it as the base.

If your components import hooks (the sidebar's `use-mobile.ts`), add `hooks/*.ts` to the step 1 loop and `hooks` to the `git diff` in step 2. And when you add a component later, run the same `add` on the `shadcn-upstream` branch and commit it there too; without that, the loop finds no base for the file and every line that differs from upstream becomes a conflict.

##### 3. Check what changed outside the components

The loop only touches `components/ui`. On the upstream branch the CLI may also have added npm packages and CSS variables:

```bash
git diff shadcn-upstream~1 shadcn-upstream -- package.json app/globals.css
```

##### What happened when we ran it

We ran the script with shadcn 4.21.4 on the scratch project above. Both edits stayed, the button picked up `import { cn } from "cn"`, and the untouched dialog was replaced. Step 3 showed `"cn": "^0.4.0"` added to `package.json`; until `cn` is in your branch's `package.json`, the merged button fails on a clean install. For that particular change, also run `npx shadcn@latest migrate cn`. In a test project it installed `cn` and turned `lib/utils.ts` into `export { cn } from "cn"`, so every `@/lib/utils` import in your own code keeps working.

Two caveats. If you edited a component before its first commit, step 1 records your edit as the installed copy, and the first merge silently reverts it, so read `git diff` after every merge. And if a formatter rewrote a component, run it on the base and upstream files too before merging. On a Prettier-reformatted copy of the Data Table, the merge stopped with one conflict exactly where upstream had changed the file; with all three files formatted the same way, it merged clean.

#### Can a CLI run the 3-way merge for you?

Yes, if it keeps the base itself. When `npx wingo-ui@latest add` installs a component, it records the version and a hash per file in `wingo-ui.json` and saves the pristine copy under `.wingo-ui/base/`. Commit both. From then on, as of CLI 1.0.3:

```bash
npx wingo-ui@latest outdated               # installed vs latest, the bump, local edits
npx wingo-ui@latest diff data-table --base # only your edits since install
npx wingo-ui@latest update --dry-run       # what would merge, nothing written
npx wingo-ui@latest update                 # 3-way merge into every installed item
```

For each file, `update` compares your copy, the base and the new release. An untouched file is replaced. An edited file gets the upstream changes merged in, and its base moves to the new version for next time. It prints the release notes of every version you skipped, installs new dependencies, and reports files a release no longer ships without deleting them.

We replayed the real Data Table 1.0.1 fix through the CLI's merge code, with `defaultPageSize` changed from 25 to 50 in our copy. The merge was clean: the fix landed and the 50 stayed. Then we also added `select-none` to the header cell's classes, on the exact line the fix rewrote, and got one conflict:

```tsx
<<<<<<< local
      className={cn("group/head relative select-none", reorder && "cursor-grab active:cursor-grabbing", isDragging && "opacity-40", className)}
=======
      className={cn(
        // a sticky header cell is already a containing block; a plain "relative" would win over "sticky" in cn and
        // leave the sticky top offset on a relative cell, pushing the header down over the first row
        "group/head [&:not(.sticky)]:relative",
        reorder && "cursor-grab active:cursor-grabbing",
        isDragging && "opacity-40",
        className,
      )}
>>>>>>> wingo-ui 1.0.1
```

Keep upstream's block, add `select-none` to its first string, delete the markers. Or settle every conflict at once with `update --theirs` (take the release) or `--ours` (keep yours); both also clear markers an earlier run left behind. `git merge-file` produced the same merge in both cases, apart from the marker label. In both tools an edit on the line right next to an upstream change also conflicts, while one untouched line between them was enough for a clean merge.

The table below has `maxHeight` set, so it scrolls inside its own box, which is the case the fix repaired.

> Live demo (Data Table): Scroll inside the table: the header row stays pinned at the top of the box while the rows move under it. Below 768px the rows turn into cards. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

We also ran the published CLI end to end on the free [Field](https://wingo-ui.com/components/field), whose 1.0.1 fix keeps focus in an input when its error clears, after changing its `optionalLabel` default. `update` printed `merged components/ui/field.tsx` with the release note, and the edit stayed. Two guard rails: without a base copy (say `.wingo-ui/` was never committed and a teammate runs the update) the CLI does not guess and asks for `--theirs` or `--ours`, and while conflicts remain it exits with code 1, so a CI step fails instead of shipping markers. Agents can run the same version check through the [MCP server](https://wingo-ui.com/docs/mcp)'s `check_updates` tool, which compares `wingo-ui.json` with the latest release and lists the release notes. The full reference is in the [updates docs](https://wingo-ui.com/docs/updates).

#### How do you keep the next update conflict-free?

Own fewer lines of each component. Conflicts only happen where you and upstream change the same or adjacent lines.

- **Set defaults from outside.** Every Wingo UI component reads app-wide defaults through [UIProvider](https://wingo-ui.com/components/ui-config), so a radius, a page size or the phone layout of a dialog needs no edit to the file. Explicit props win, then the provider, then the component's own defaults.
- **Wrap for behavior.** A `SubmitButton` that composes the [Button](https://wingo-ui.com/components/button) lives in your code and never conflicts.
- **Keep your formatter off copied files.** Add `components/ui` to `.prettierignore`, or each upstream change near a reformatted line turns into a conflict.
- **Update a release or two at a time**, so each merge stays small enough to review.

The 25 to 50 page size from the test above, a pill-shaped button and a [Dialog](https://wingo-ui.com/components/dialog) that stays a centered card on phones, all without touching a component file:

```tsx
// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <UIProvider
      defaults={{
        button: { radius: "full" },
        dialog: { responsive: false },
        "data-table": { defaultPageSize: 50 },
      }}
    >
      {children}
    </UIProvider>
  );
}
```

Wrap `{children}` in `app/layout.tsx` with `<Providers>`, and every Button, Dialog and Data Table under it starts from these defaults. The demo shows the same mechanism on two buttons:

> Live demo (UIProvider): The first button uses its built-in defaults; the two below get radius full, size lg and tone brand from a UIProvider, and the outline one keeps the variant it passes itself. Try it at [UIProvider](https://wingo-ui.com/components/ui-config) and install it with `npx wingo-ui@latest add ui-config`.

For one component at a time, see the [component guides](https://wingo-ui.com/blog/category/components), starting with the [React form components guide](https://wingo-ui.com/blog/react-form-components-guide).

#### What should you do next?

On stock shadcn/ui, create the `shadcn-upstream` branch now, while your history still shows what the CLI wrote. If you want the merge built in, install the free Button and Dialog with `npx wingo-ui@latest add button dialog`, commit `wingo-ui.json` and `.wingo-ui/`, and run `npx wingo-ui@latest update --dry-run` after the next release. The Data Table is part of [Wingo UI Pro](https://wingo-ui.com/pricing). The [shadcn alternatives](https://wingo-ui.com/blog/shadcn-alternatives) post compares how other libraries handle updates.

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Dialog](https://wingo-ui.com/components/dialog) (Free): The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body. Install: `npx wingo-ui@latest add dialog`
- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`
- [Field](https://wingo-ui.com/components/field) (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: `npx wingo-ui@latest add field`
- [UIProvider](https://wingo-ui.com/components/ui-config) (Free): App-wide configuration for Wingo UI: default props for every component, the Intl locale and the reduced-motion policy. Install: `npx wingo-ui@latest add ui-config`

#### FAQ

##### How do you update shadcn components?

Run npx shadcn@latest add <name> --diff to see how your file differs from the registry, then npx shadcn@latest add <name> --overwrite to replace it. Overwrite drops your edits, so for files you changed, merge three versions (as installed, yours and upstream) with git merge-file instead.

##### Is the shadcn diff command deprecated?

Yes. As of shadcn 4.21.4 (October 2026) its help text says to use add <component> --diff instead. The flag arrived with shadcn CLI v4 in March 2026, along with --dry-run and --view.

##### How do I update all shadcn components at once?

npx shadcn@latest add --all --overwrite re-adds every component in the registry and replaces your files, edits included. Overwrite only the files that still match the commit that added them, and merge the ones you changed.

##### Why does a 3-way merge keep my edits when a diff cannot?

A diff compares two files, so your edits and upstream's changes look the same. A 3-way merge also reads the file as it was installed, so it knows which side changed each line and only stops where both sides changed the same or adjacent lines.

##### Can the Wingo UI CLI update components I installed with shadcn?

No. wingo-ui update only merges items it installed itself, because it needs the base copy it saved in .wingo-ui/base at install time. For stock shadcn/ui files, use the git merge-file script from this post.

---

Source: https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits

### IBAN Validation JavaScript: Mod 97, Regex and a React Field

> IBAN validation JavaScript that catches typos: mod 97 in TypeScript, why a regex is not enough, a React field that formats as you type and Romanian banks.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/iban-validation-javascript

#### TL;DR

To validate an IBAN in JavaScript, remove the spaces, uppercase it, check the length for its country, move the first four characters to the end, turn each letter into two digits (A is 10, Z is 35) and check that the whole number mod 97 equals 1. Carry the remainder one character at a time, because the number is longer than a JavaScript Number can hold exactly. A passing IBAN is well formed, which does not prove that the account exists.

Your payout settings, supplier form or invoice template asks for a bank account, and people paste IBANs in every shape: lowercase, grouped by four, with dashes, with the non-breaking spaces a PDF adds, sometimes with "IBAN:" in front. Many IBAN validation JavaScript snippets stop at a regex, which accepts a mistyped digit, or call `parseInt`, which rejects valid accounts. This tutorial writes the mod 97 check in TypeScript, wires it into a zod rule and a React field that formats as you type, reads the bank out of Romanian IBANs and displays the result with a copy button. The UI uses [Masked Input](https://wingo-ui.com/components/masked-input) (Pro), [Input](https://wingo-ui.com/components/input) and [Copy Button](https://wingo-ui.com/components/copy-button) (both free) from Wingo UI, the library we build, so we are not neutral. The validator is plain TypeScript you can paste anywhere.

#### Why is a regex not enough to validate an IBAN?

A regex checks the shape, and a typo keeps the shape. The usual IBAN validation regex, run after you remove the spaces and uppercase, is this:

```ts
const IBAN_SHAPE = /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/;
```

Two letters for the country, two check digits, then 11 to 30 letters or digits, because IBANs run from 15 characters (Norway) to a maximum of 34. A country pattern is stricter: Romania's is `^RO\d{2}[A-Z]{4}[A-Z0-9]{16}$`. Both accept `RO49AAAA1B31007593840001`, which is the sample Romanian IBAN from the IBAN registry with its last digit changed.

The two check digits exist to catch exactly that. Any string in the Romanian shape passes the regex, while only about 1 in 97 random ones passes mod 97: in a run of 200,000 random strings, about 1% did. Keep the regex anyway, as the first of three checks, so your message can say "this is not an IBAN" before it says "this IBAN has a typo".

#### How does the IBAN mod 97 check work?

Move the first four characters to the end, replace each letter with two digits (A is 10, B is 11, up to Z at 35), read the result as one integer and divide it by 97. A valid IBAN leaves a remainder of 1. The [IBAN article on Wikipedia](https://en.wikipedia.org/wiki/International_Bank_Account_Number) describes these steps from ISO 13616. Whoever issues the IBAN computes the check digits as 98 minus the remainder of the same number with `00` in their place, which is why a valid IBAN lands on 1.

Here is the UK sample IBAN worked by hand:

| Step | Value |
|---|---|
| Remove the spaces | GB29NWBK60161331926819 |
| Move the first four characters to the end | NWBK60161331926819GB29 |
| Letters to numbers (N 23, W 32, B 11, K 20, G 16) | 2332112060161331926819161129 |
| Remainder mod 97 | 1 |

That integer has 28 digits, and a JavaScript `Number` is exact only up to 2^53, which has 16 digits. `Number(digits) % 97` and `parseInt(digits, 10) % 97` both return 5 for this IBAN, so they reject a valid account. `BigInt(digits) % 97n` works. Carrying the remainder one character at a time works too, and it skips the conversion to a digit string.

Wikipedia says the check detects all single substitution errors and all or nearly all swaps of neighboring characters. We tested that. On 2,000 random German IBANs, which are all digits after the country code, every single-digit change and every swap of two neighbors failed the check. Letters weaken it: on 2,000 random Romanian-style IBANs with letters in the account part, about 0.35% of single-character changes and of neighbor swaps still passed, roughly 1 in 300, because a letter becomes two digits. Swap the `1B` in the registry sample to `B1` and both read `111`, so `RO49AAAAB131007593840000` passes.

#### How do I validate an IBAN in TypeScript?

To validate IBAN numbers, normalize the input, then run three checks in order: the shape, the length for the country, and mod 97. Returning which check failed lets the form explain the problem instead of saying "invalid":

```ts
// lib/iban.ts
// the 42 IBAN country codes in the SEPA schemes (EPC, August 2026), with their
// lengths from SWIFT's IBAN Registry as ibantools 4.5.4 ships them
const LENGTHS: Record<string, number> = Object.fromEntries(
  (
    "AD24 AL28 AT20 BE16 BG22 CH21 CY28 CZ24 DE22 DK18 EE20 ES24 FI18 FR27 " +
    "GB22 GI23 GR27 HR21 HU28 IE22 IS26 IT27 LI21 LT20 LU20 LV21 MC27 MD24 " +
    "ME22 MK19 MT31 NL18 NO15 PL28 PT25 RO24 RS22 SE24 SI19 SK24 SM27 VA22"
  )
    .split(" ")
    .map((entry) => [entry.slice(0, 2), Number(entry.slice(2))]),
);

export type IbanProblem = "format" | "country" | "length" | "checksum";

export const ibanLength = (country: string) => LENGTHS[country.toUpperCase()];

// " iban: ro49 aaaa-1b31 ..." -> "RO49AAAA1B31..."; \s also covers the non-breaking spaces PDFs paste
export function electronicIban(input: string): string {
  return input.trim().toUpperCase().replace(/^IBAN:?/, "").replace(/[\s.-]/g, "");
}

// the remainder of the rearranged IBAN, one character at a time, so the number never outgrows a float
function mod97(iban: string): number {
  const rearranged = iban.slice(4) + iban.slice(0, 4);
  let remainder = 0;
  for (const char of rearranged) {
    // A is 10 ... Z is 35: a letter adds two digits, so shift by 100
    const value = char >= "A" ? char.charCodeAt(0) - 55 : Number(char);
    remainder = (remainder * (value > 9 ? 100 : 10) + value) % 97;
  }
  return remainder;
}

export function checkIban(input: string): { iban: string; problem: IbanProblem | null } {
  const iban = electronicIban(input);
  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban)) return { iban, problem: "format" };
  const length = ibanLength(iban.slice(0, 2));
  if (!length) return { iban, problem: "country" };
  if (iban.length !== length) return { iban, problem: "length" };
  return { iban, problem: mod97(iban) === 1 ? null : "checksum" };
}

export const isValidIban = (input: string) => checkIban(input).problem === null;

// "RO49AAAA1B31007593840000" -> "RO49 AAAA 1B31 0075 9384 0000"
export const formatIban = (input: string) => electronicIban(input).replace(/(.{4})(?=.)/g, "$1 ");

// check digits for test data: ibanCheckDigits("GB", "NWBK60161331926819") -> "29"
export function ibanCheckDigits(country: string, bban: string): string {
  return String(98 - mod97(`${country}00${bban}`)).padStart(2, "0");
}
```

```ts
checkIban("gb29-nwbk-6016-1331-9268-19"); // { iban: "GB29NWBK60161331926819", problem: null }
checkIban("IBAN: RO49 AAAA 1B31 0075 9384 0001"); // problem: "checksum"
checkIban("US12345678901234567"); // problem: "country"
formatIban("ro49aaaa1b31007593840000"); // "RO49 AAAA 1B31 0075 9384 0000"
ibanCheckDigits("RO", "BTRL0123456789ABCDEF"); // "17", so RO17BTRL0123456789ABCDEF passes
```

Four decisions in that file are worth copying even if you rewrite the rest:

- **Uppercase first.** `"n".charCodeAt(0) - 55` is 55, where `"N"` gives 23, so a lowercase IBAN fails without it.
- **Strip every kind of space.** `\s` in a JavaScript regex also matches the non-breaking and narrow spaces that PDFs and bank apps put between the groups.
- **Reject countries you do not pay.** The table holds the 42 IBAN country codes in the [EPC's August 2026 overview of SEPA scheme participants](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2026-08/EPC196-26%20v1.0%20Overview%20scheme%20adherence%202026-08-07.pdf), Albania, Moldova, Montenegro, North Macedonia and Serbia included, so anything else gets `"country"`, the honest answer for a SEPA payout form. If you accept IBANs from every country, use a library (see the last section).
- **Generate test data.** `ibanCheckDigits` builds a valid IBAN from any country and account part, so your fixtures never hold a real person's account.

#### What is the Romanian IBAN format?

A Romanian IBAN has 24 characters: `RO`, two check digits, four letters for the bank, and 16 letters or digits for the branch and the account. The four bank letters are the first four characters of the bank's BIC, its SWIFT code, so `BTRL` is Banca Transilvania (BIC `BTRLRO22`). Wikipedia's [IBAN formats by country](https://en.wikipedia.org/wiki/International_Bank_Account_Number#IBAN_formats_by_country) table writes it as `RO kk bbbb cccc cccc cccc cccc`.

| Positions | Registry sample | Meaning |
|---|---|---|
| 1 to 2 | RO | Country |
| 3 to 4 | 49 | Check digits |
| 5 to 8 | AAAA | Bank, the first four characters of its BIC |
| 9 to 24 | 1B31 0075 9384 0000 | Branch and account, letters allowed |

Two rules follow. A "digits only after the bank code" rule rejects real Romanian accounts, since the account part may hold letters: Banca Transilvania IBANs, for one, carry letters such as `RONCRT` right after the bank code. And the bank is one lookup away:

```ts
// lib/iban.ts (continued)
// the four letters after the check digits are the start of the bank's BIC
const RO_BANKS: Record<string, string> = {
  BTRL: "Banca Transilvania",
  RNCB: "BCR",
  BRDE: "BRD",
  INGB: "ING Bank",
  RZBR: "Raiffeisen Bank",
  BACX: "UniCredit Bank",
  CECE: "CEC Bank",
  TREZ: "State Treasury",
};

export function romanianBank(input: string): string | null {
  const iban = electronicIban(input);
  return iban.startsWith("RO") ? (RO_BANKS[iban.slice(4, 8)] ?? null) : null;
}
```

```ts
romanianBank("RO17 BTRL 0123 4567 89AB CDEF"); // "Banca Transilvania"
romanianBank("GB29 NWBK 6016 1331 9268 19"); // null
```

Show the name as a hint the person can recognize. It proves nothing about the account, and the map is a snapshot of banks that merge: when OTP Bank Romania merged into Banca Transilvania in early 2025, its customers received new BTRL IBANs, and [Banca Transilvania sent employers the new IBANs for salaries paid from March 2025](https://intreb.bancatransilvania.ro/en/cum-voi-incasa-salariul-alocatia-pensia-orice-alt-venit-virat-baza-unei-conventii-banca-transilvania-va-lua-legatura-cu-institutiile-care-vireaza-aceste-sume-si-ii-va-informa-cu-privire-la-noile-iban-uri-mod-centralizat/). An old OTP IBAN still passes mod 97.

#### How do I build an IBAN field that formats as you type?

Use a masked field that keeps the raw value apart from what it displays. The `iban` preset of Masked Input uppercases as you type, groups by four, keeps the caret right after the character you typed and cleans separators out of a paste. Once the IBAN is complete it runs mod 97 and pops in a check or an alert icon; the red ring and `aria-invalid` wait until you leave the field. On phones it keeps the text keyboard with `autoCapitalize="characters"`, because a numeric keypad has no letters for the country code.

> Live demo (Masked Input): Type or paste gb29-nwbk-6016-1331-9268-19: the field uppercases it, groups it by four and shows a check. Change the last digit and the check turns into an alert. Try it at [Masked Input](https://wingo-ui.com/components/masked-input) and install it with `npx wingo-ui@latest add masked-input`.

The preset ships lengths for nine countries: Romania, Moldova, Germany, the UK, France, Italy, Spain, Bulgaria and Hungary. For any other country it still groups by four but waits for 34 characters before it checks, so a Dutch IBAN never gets its icon. Pass a mask sized from the same table as your validator. The preset keeps its uppercasing and its keyboard settings:

```ts
// lib/iban-mask.ts
import { ibanLength } from "@/lib/iban";

// "AA99 **** **** ..." sized to the country, so the field knows when the IBAN is complete
export function ibanMask(raw: string): string {
  const length = ibanLength(raw.slice(0, 2)) ?? 34;
  let mask = "AA99";
  for (let i = 4; i < length; i++) mask += (i % 4 === 0 ? " " : "") + "*";
  return mask;
}
```

The zod rule turns each failed check into its own message and hands your database the electronic format, without spaces:

```ts
// lib/iban-schema.ts
import { z } from "zod";
import { checkIban, electronicIban, type IbanProblem } from "@/lib/iban";

const MESSAGES: Record<IbanProblem, string> = {
  format: "Enter the full IBAN, starting with the country code, like GB29 NWBK 6016 1331 9268 19",
  country: "We can only pay out to banks in SEPA countries",
  length: "This IBAN is too short or too long for its country",
  checksum: "This IBAN has a typo: the check digits do not match",
};

export const iban = z
  .string()
  .trim()
  .min(1, { error: "Enter your IBAN", abort: true })
  .check((ctx) => {
    const { problem } = checkIban(ctx.value);
    if (problem) ctx.issues.push({ code: "custom", message: MESSAGES[problem], input: ctx.value });
  })
  .transform(electronicIban);
```

Wire it with React Hook Form's `Controller`, because the input element holds the masked text and `onValueChange` hands you the raw value. Passing `validate={isValidIban}` makes the field's icon and the zod rule agree on every IBAN:

```tsx
"use client";

import { Controller, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { MaskedInput } from "@/components/ui/masked-input";
import { electronicIban, isValidIban, romanianBank } from "@/lib/iban";
import { ibanMask } from "@/lib/iban-mask";
import { iban } from "@/lib/iban-schema";

const schema = z.object({
  holder: z.string().trim().min(1, { error: "Enter the account holder's name" }),
  iban,
});

type Values = z.output<typeof schema>;

export function PayoutForm({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { holder: "", iban: "" },
  });
  const { errors, isSubmitting } = form.formState;

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Input label="Account holder" autoComplete="name" {...form.register("holder")} error={errors.holder?.message} />
      <Controller
        control={form.control}
        name="iban"
        render={({ field, fieldState }) => (
          <MaskedInput
            preset="iban"
            mask={ibanMask}
            validate={isValidIban}
            label="IBAN"
            placeholder="GB29 NWBK 6016 1331 9268 19"
            ref={field.ref}
            value={field.value}
            onValueChange={(raw) => field.onChange(raw)}
            onBlur={field.onBlur}
            // the mask keeps letters, so a pasted "IBAN:" label would become the country code
            onPaste={(event) => {
              const text = event.clipboardData.getData("text");
              if (!/^\s*iban\b/i.test(text)) return;
              event.preventDefault();
              field.onChange(electronicIban(text));
            }}
            // a romanian IBAN names its bank as soon as the bank code is in
            description={romanianBank(field.value) ?? "Paste it with or without spaces."}
            error={fieldState.error?.message}
          />
        )}
      />
      <Button type="submit" loading={isSubmitting}>
        Save payout details
      </Button>
    </form>
  );
}
```

The description reads "Banca Transilvania" as soon as someone types `RO17BTRL`, a quick way for them to confirm they copied the account they meant. The `onPaste` handler covers the one paste the mask cannot clean up. The field drops every separator but keeps letters, so "IBAN: RO17 BTRL ..." copied from a statement would turn into `IB17 BTRL ...` and fail with the country message. The handler strips the label with `electronicIban` before the mask sees it.

If you would rather not write the rule, the Pro [form-validation](https://wingo-ui.com/components/form-validation) lib has `createValidators().iban()`, with one message for any failure and no country limit.

#### How do I show an IBAN so people can copy it?

Display it in groups of four and copy it without spaces. The groups help people read it aloud or compare it with a paper invoice. The clipboard should get the electronic format, because a 34-character IBAN grows to 42 characters with spaces, and a bank form with `maxLength={34}` cuts the end off on paste.

```tsx
import { CopyButton } from "@/components/ui/copy-button";
import { electronicIban, formatIban, romanianBank } from "@/lib/iban";

export function PayoutAccount({ iban }: { iban: string }) {
  const bank = romanianBank(iban);
  return (
    <div className="flex items-center justify-between gap-3 rounded-2xl bg-surface p-4">
      <div className="min-w-0">
        <p className="font-mono text-sm">{formatIban(iban)}</p>
        {bank && <p className="text-xs text-muted-foreground">{bank}</p>}
      </div>
      <CopyButton value={electronicIban(iban)} copyLabel="Copy IBAN" />
    </div>
  );
}
```

Copy Button renders an icon button labeled "Copy IBAN". On desktop its tooltip switches to "Copied"; on a phone the check, a short vibration and a screen reader announcement carry the feedback, and the small size keeps a 44px hit area on touch. The grouped IBAN wraps at its spaces, so it never pushes the row wider than a 360px screen.

#### Does a valid IBAN mean the account exists?

No. The check digits prove that the IBAN is well formed. A closed account, an account at a bank that has since merged and the wrong person's account all pass. The account holder's name is what catches the last case. Under the EU Instant Payments Regulation, banks must offer Verification of Payee, which compares the payee's name with the account before a credit transfer and returns a result such as match, close match or no match. The [ECB's overview of the regulation](https://www.ecb.europa.eu/paym/retail/instant_payments/html/instant_payments_regulation.en.html) lists October 9, 2025 for the euro area and July 9, 2027 for the non-euro member states, Romania among them.

That check runs at the payer's bank when the money leaves, long after your form was submitted. So check the digits while people type, and ask for the account holder's name next to the IBAN, as the form above does, so the bank has a name to compare.

#### Should I use a library like ibantools instead?

Use one when you accept IBANs from every country. As of October 2026, [ibantools](https://www.npmjs.com/package/ibantools) 4.5.4 (published April 2026, MIT or MPL-2.0) ships the length and account pattern of each registry country, `validateIBAN` returns error codes you can map to messages, and `isValidBIC` checks SWIFT codes. It also runs the national check digits some countries add inside the account part, such as Belgium, Spain and France, which the file above skips. One catch for a SEPA form: its `isSEPACountry` in 4.5.4 still returns false for Albania, Moldova, Montenegro, North Macedonia and Serbia. The [iban](https://www.npmjs.com/package/iban) package, the other common answer, was last published in February 2020. For a SEPA-only form, the file above covers the shape, the length and mod 97 without a dependency, and you can read every line of it.

#### Should I copy this code or install it?

Copy it when you need one plain field: `lib/iban.ts`, the zod rule and the free Input cover it. In Wingo UI Pro, Masked Input is the field from the demo, and the [invoicing](https://wingo-ui.com/components/invoicing) lib exports `isValidIban` (lengths for 19 countries, while any other country gets the shape and mod 97), `formatIban`, `getIbanBank` and a `RO_BANKS` map of 19 Romanian bank codes, next to the checks from our [Romanian CUI validation guide](https://wingo-ui.com/blog/romanian-cui-validation-javascript) and our [Romanian CNP validator](https://wingo-ui.com/blog/romanian-cnp-validator-javascript). The plans are on the [pricing page](https://wingo-ui.com/pricing). Install the field and the free copy button with `npx wingo-ui@latest add masked-input copy-button`. For the rest of the form anatomy, read [React form components: accessible fields, zod and mobile](https://wingo-ui.com/blog/react-form-components-guide), or browse more [component guides](https://wingo-ui.com/blog/category/components).

#### Components in this post

- [Masked Input](https://wingo-ui.com/components/masked-input) (Pro): A text field that formats itself as you type or paste: card number, expiry, CVC, IBAN, CNP, postal code or a custom mask. Install: `npx wingo-ui@latest add masked-input`
- [Invoicing](https://wingo-ui.com/components/invoicing) (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: `npx wingo-ui@latest add invoicing`
- [Copy Button](https://wingo-ui.com/components/copy-button) (Free): Copy an IBAN, a tax ID, a link or an API key with one tap: an icon button with a tooltip, a labelled button, and CopyText for inline values. Install: `npx wingo-ui@latest add copy-button`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`
- [Form validation](https://wingo-ui.com/components/form-validation) (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: `npx wingo-ui@latest add form-validation`

#### FAQ

##### How do I validate an IBAN in JavaScript?

Remove spaces and dashes, uppercase the string and check its length for the country. Then move the first four characters to the end, replace each letter with its number (A is 10, Z is 35) and compute the remainder mod 97 one digit at a time; the IBAN is valid when the remainder is 1.

##### What is the regex for an IBAN?

After you remove the spaces and uppercase, /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/ matches the shape of any IBAN, and a country pattern such as ^RO\d{2}[A-Z]{4}[A-Z0-9]{16}$ adds the length. Neither one tests the check digits, so run mod 97 after the regex.

##### How many characters is a Romanian IBAN?

24: RO, two check digits, four letters for the bank (the first four characters of its BIC) and 16 letters or digits for the branch and the account, for example RO49 AAAA 1B31 0075 9384 0000.

##### Does a valid IBAN mean the bank account exists?

No. The check digits only prove that the IBAN is well formed, so a closed account or the wrong person's account still passes. In the EU, Verification of Payee at the payer's bank compares the payee's name with the account before a transfer, from October 9, 2025 in the euro area and from July 9, 2027 in Romania and the other non-euro member states.

##### Why does my IBAN check reject valid IBANs?

Often it is Number or parseInt: the rearranged IBAN has more digits than a JavaScript Number holds exactly, so the remainder comes out wrong. Lowercase letters, non-breaking spaces pasted from a PDF and an IBAN: label in front are the other usual suspects.

##### How do I find the bank from a Romanian IBAN?

Read characters 5 to 8. They are the first four characters of the bank's BIC, so BTRL is Banca Transilvania and RNCB is BCR. Keep your map current, because merged banks leave old codes behind.

---

Source: https://wingo-ui.com/blog/iban-validation-javascript

### Minimum Touch Target Size: WCAG, iOS, Android and Tailwind

> Minimum touch target size per WCAG 2.2 (24 and 44px), iOS (44pt) and Android (48dp), and how to get 44px taps in React and Tailwind without desktop bloat.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind

#### TL;DR

The minimum touch target size is 24 by 24 CSS pixels for WCAG 2.2 level AA, 44 by 44 for level AAA and for Apple's default iOS control, and 48 by 48 dp in Material and Android guidance. For a React web app, aim for 44px under the pointer: coarse media query and keep compact sizes for a mouse. In Tailwind CSS v4.1 and later that means pointer-coarse:h-11 on controls with room to grow and an invisible ::after hit area on icons and checkboxes that must stay small.

Ask what the minimum touch target size is and you get four numbers: 24, 28, 44 and 48. They come from different documents, in different units, and two of them are floors that nobody should design to. This tutorial sorts out what WCAG 2.2, Apple and Android ask for, picks one number for a React web app, and builds it in Tailwind CSS v4.1: buttons, icon buttons and checkboxes that take 44px taps on a phone while the desktop keeps its 32px and 40px controls. It ends with a Playwright test that fails when a target shrinks.

#### What is the minimum touch target size?

The minimum touch target size is 24 by 24 CSS pixels for WCAG 2.2 level AA, 44 by 44 for WCAG level AAA and for Apple's default iOS control, and 48 by 48 dp for Material and Android. The rest of each document is about exceptions and spacing:

| Source (as of October 2026) | Target size | Spacing | Status |
| --- | --- | --- | --- |
| [WCAG 2.2, SC 2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) | 24 by 24 CSS px | smaller targets pass when spaced out | Level AA |
| [WCAG 2.2, SC 2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) | 44 by 44 CSS px | none | Level AAA |
| [Apple HIG, iOS and iPadOS](https://developer.apple.com/design/human-interface-guidelines/accessibility) | 44 by 44 pt default, 28 by 28 pt minimum | about 12 pt around bezeled controls, 24 pt around borderless ones | Guideline |
| [Apple HIG, macOS](https://developer.apple.com/design/human-interface-guidelines/accessibility) | 28 by 28 pt default, 20 by 20 pt minimum | same | Guideline |
| [Android accessibility help](https://support.google.com/accessibility/android/answer/7101858) | 48 by 48 dp, about 9 mm | 8 dp or more | Recommendation |

The units are closer than they look. With the `width=device-width` viewport, which the Next.js App Router adds by default, one CSS pixel is one point on an iPhone and one dp on Android. So 44px in your CSS is Apple's 44 pt, and 48px is Material's 48 dp.

Two details matter more than the numbers. WCAG measures the area that accepts the tap, which it defines as the "region of the display that will accept a pointer action", so padding counts and a small icon can still pass. And WCAG covers every pointer, mouse included, so the 24px floor applies to your desktop layout too.

#### What does WCAG 2.2 require for touch targets?

The minimum touch target size WCAG 2.2 sets at level AA is 24 by 24 CSS pixels, unless one of five exceptions applies. [The spec](https://www.w3.org/TR/WCAG22/#target-size-minimum) lists them:

- **Spacing.** An undersized target passes if a 24px circle centered on its bounding box does not intersect another target or the circle of another undersized target. In practice: undersized targets need their centers at least 24px apart, and at least 12px from the edge of any other target.
- **Equivalent.** Another control on the same page does the same thing and meets the size.
- **Inline.** The target sits in a sentence, like a link in a paragraph.
- **User agent control.** The browser sizes the control and you did not restyle it.
- **Essential.** That presentation is essential or legally required.

Level AAA (2.5.5) asks for 44 by 44 with the same exceptions minus spacing. WCAG's definition of a target adds a note that matters for the techniques below: where targets overlap, the overlapping area does not count toward their size, unless they perform the same action or open the same page.

Treat AA as an audit floor. It lets a 24px icon pass, and Apple and Google ask for about twice that on touch.

#### What is the minimum touch target size iOS and Android recommend?

Apple lists 44 by 44 points as the default control size on iOS and iPadOS and 28 by 28 points as the minimum. Google's Android guidance asks for 48 by 48 dp with at least 8 dp between targets, which it puts at about 9 mm.

Apple also says to "consider spacing between controls as important as size" and suggests about 12 points of padding around controls with a bezel and about 24 around controls without one. Native Android does part of the work for you: the [Compose reference](https://kotlinlang.org/api/compose-multiplatform/material3/androidx.compose.material3/minimum-interactive-component-size.html) calls 48 dp "the Material recommended minimum size" and says the system expands touch targets at the input layer. On the web, build that area yourself, in CSS.

#### Which size should a React web app use?

Use 44px on coarse pointers, keep 8px between neighboring targets, never go below 24px for any pointer, and give the main action of a phone screen 48px. A 44px touch target meets WCAG AAA and Apple's default in one number. If your analytics say most of your users are on Android, swap 44 for 48: `pointer-coarse:h-12` on buttons and 48px in the `hit-area` utility below.

The desktop is where teams overcorrect. Apple's own default for a macOS control is 28 points, and 44px controls everywhere make a settings form or a table toolbar look like a kiosk. Size by input device instead of by screen width.

#### How do you hit 44px on touch without bloating the desktop UI?

Switch sizes on the pointer coarse media query, `@media (pointer: coarse)`, which matches when the primary pointer is a finger. Tailwind CSS v4.1 added it as the [`pointer-coarse` variant](https://tailwindcss.com/docs/hover-focus-and-other-states). A width breakpoint gets this wrong twice: an iPad in landscape is wider than `lg` and gets mouse-sized controls, and a narrow desktop window gets thumb-sized ones.

There are three techniques, in order of preference.

##### Grow the control when the layout has room

A text button can afford 4 extra pixels of height. This is the size map of the [Button](https://wingo-ui.com/components/button) in Wingo UI:

```tsx
// components/ui/button.tsx (excerpt): 32 / 40 / 48px
const SIZES: Record<ButtonSize, string> = {
  sm: "h-8 gap-1.5 px-3 text-[13px] pointer-coarse:after:absolute pointer-coarse:after:inset-x-0 pointer-coarse:after:-inset-y-1.5",
  md: "h-10 gap-2 px-4 text-sm pointer-coarse:h-11",
  lg: "h-12 gap-2 px-5 text-[15px]",
  "icon-sm": "size-8 pointer-coarse:after:absolute pointer-coarse:after:-inset-1.5",
  icon: "size-10 pointer-coarse:size-11",
  "icon-lg": "size-12",
};
```

The default `md` is 40px with a mouse and 44px under a finger, and so is the square `icon` size. `lg` is 48px everywhere, which suits a full-width submit button at the bottom of a phone screen. Since the class is a media query, the server-rendered HTML is already right on the first paint.

##### Add an invisible hit area when the control must look small

A 32px icon in a toolbar should stay 32px. Give it a pseudo-element that extends past its edges on touch: (44 - 32) / 2 = 6px on each side, which is `-inset-1.5`. That is what `sm` and `icon-sm` do above; `sm` only extends vertically, because a text button is usually wider than 44px already. In Tailwind v4 the `after:` variant sets `content` for you and the button is already `relative` (its `::before` holds the hover tint).

For your own components, one utility can do the math for any size:

```css
/* app/globals.css */
/* a 44px hit area around any smaller control; the control needs a position */
@utility hit-area {
  &::after {
    content: "";
    position: absolute;
    inset-block: min(0px, calc((100% - 44px) / 2));
    inset-inline: min(0px, calc((100% - 44px) / 2));
  }
}
```

```tsx
import { X } from "lucide-react";

export function DismissButton({ onDismiss }: { onDismiss: () => void }) {
  return (
    <button
      type="button"
      aria-label="Dismiss"
      onClick={onDismiss}
      className="relative grid size-7 touch-manipulation place-items-center rounded-full [-webkit-tap-highlight-color:transparent] pointer-coarse:hit-area"
    >
      <X className="size-4" />
    </button>
  );
}
```

The percentages resolve against the control itself, and `min(0px, ...)` never shrinks a control that is already big enough. We measured it in Chromium: a 16px and a 32px button both take taps on exactly 44 by 44, an 80 by 32 button on 80 by 44, and a 60px button keeps its 60px.

Hit areas fail in three ways, all invisible until someone misses a tap:

1. **Clipping.** `overflow-hidden` on the control cuts its own `::after`, and an ancestor with `overflow-hidden` cuts it at the ancestor's edge. Put clipping on an inner layer instead. The [Haptic Button](https://wingo-ui.com/components/haptic-button) clips its ripple and hold fill on an inner layer, so the button itself keeps its 44px area.
2. **Overlap.** Two 32px icons 4px apart have 44px areas that overlap by 8px. The later one in the DOM wins every tap in the overlap, and WCAG does not count it. Keep centers 44px apart on touch: `gap-1 pointer-coarse:gap-3` for 32px icons.
3. **No position.** Without `relative` on the control, the `::after` sizes itself against the nearest positioned ancestor, and that whole ancestor becomes an invisible target for this one control.

##### Make the label the target

For checkboxes, radios and switches, the box can stay 16 to 20px when the whole row takes the tap. The [Checkbox](https://wingo-ui.com/components/checkbox) renders the row as one `<label>`. On a coarse pointer the row is at least 44px tall (`pointer-coarse:min-h-11`) and full width, and in a group the gap between rows drops to zero while the padding moves inside each row, so a tap between two options always lands on one of them. A box without a label, in a table cell for example, gets the `::after` treatment instead: the Checkbox adds 14px on each side of its 16px and 18px boxes and 12px around the 20px one.

> Live demo (Checkbox): Tap the empty space to the right of a label on a phone: the whole row toggles the box. With a mouse, the rows shrink back to the box and its text. Try it at [Checkbox](https://wingo-ui.com/components/checkbox) and install it with `npx wingo-ui@latest add checkbox`.

The same idea works with a native input. `min-h-6` keeps the row at the 24px floor for a mouse:

```tsx
export function ReleaseEmails() {
  return (
    <label className="flex min-h-6 w-fit cursor-pointer touch-manipulation items-center gap-3 text-sm pointer-coarse:min-h-11 pointer-coarse:w-full">
      <input type="checkbox" name="releases" className="size-4" />
      Email me when a new version ships
    </label>
  );
}
```

#### Should you use pointer: coarse or any-pointer: coarse?

Use `pointer: coarse` for sizes in most apps. It describes the primary input, so a phone or tablet matches and a laptop does not. [`any-pointer: coarse`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/any-pointer) matches when at least one connected input is coarse, and MDN notes that more than one value can match at once. A laptop with a touchscreen usually has a fine primary pointer, so it matches `any-pointer: coarse` and not `pointer: coarse`.

Pick `any-pointer` when touch is a common second input, as on convertible laptops and touchscreen all-in-one desktops; the cost is larger controls while someone uses the trackpad. To keep that decision in one place, give it a name:

```css
/* app/globals.css: every touch:* class follows this one line */
@custom-variant touch (@media (pointer: coarse));
/* include touchscreen laptops instead: */
/* @custom-variant touch (@media (any-pointer: coarse)); */
```

Then write `touch:h-11` and `touch:hit-area`, and switch the definition in one line later. Wingo UI uses `pointer: coarse`; the [useMediaQuery hook](https://wingo-ui.com/components/use-media-query) exports it as `TOUCH_QUERY`, so components and app code agree on what touch means.

> Live demo (useMediaQuery): Your device answers live: useIsTouch() is pointer: coarse, the hover card needs a mouse or trackpad, and the last card runs any-pointer: coarse. Try it at [useMediaQuery](https://wingo-ui.com/components/use-media-query) and install it with `npx wingo-ui@latest add use-media-query`.

#### When should you detect touch devices in React?

Detect touch in React only for behavior, never for size. The server cannot know the pointer, so `useIsTouch()` returns false on the server and during hydration. A size picked by the hook renders desktop controls first and jumps on phones; the CSS variant is right from the first paint. The [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) covers the same split for layout, and the [SSR-safe React use mobile hook tutorial](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) explains why these hooks return false on the server.

Use it in effects and event handlers. Autofocus is the classic case, because focusing an input on a phone opens the keyboard over half the screen. This snippet uses the free hook, installed with `npx wingo-ui@latest add use-media-query`:

```tsx
"use client";

import { useEffect, useRef } from "react";
import { matchesMedia, TOUCH_QUERY } from "@/hooks/use-media-query";

export function ClientSearch() {
  const ref = useRef<HTMLInputElement>(null);

  // on touch, focus would open the keyboard before anyone asked for it
  useEffect(() => {
    if (!matchesMedia(TOUCH_QUERY)) ref.current?.focus();
  }, []);

  return (
    <input
      ref={ref}
      type="search"
      name="q"
      placeholder="Search clients"
      className="h-10 w-full rounded-[10px] border border-border bg-transparent px-3 text-base pointer-coarse:h-11 sm:text-sm"
    />
  );
}
```

For decisions per interaction, read `event.pointerType` instead of a media query, because a touchscreen laptop can send both kinds of events. The Haptic Button plays its haptic tick only for touch and pen presses; a mouse click never vibrates.

#### How do you test touch targets?

Run axe for the 24px floor and a hit test at 44px with touch emulation, then try the screen with your thumb on a real phone.

axe-core's `target-size` rule checks WCAG 2.5.8. In axe-core 4.13 it is off by default and runs when you ask for the `wcag22aa` tag, for example `new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])` with `@axe-core/playwright`. It tests the AA floor, so a 32px icon button with no hit area passes it.

For 44px, check what the browser actually hits. In Chromium, Playwright's `hasTouch: true` makes `(pointer: coarse)` match and `(hover: hover)` stop matching, so your `pointer-coarse:` classes apply. `document.elementFromPoint` at the corners of a 44px square around each control then catches all three failures above, because hit testing includes `::after`, respects overflow clipping and returns the topmost of two overlapping targets:

```ts
// e2e/touch-targets.spec.ts
import { expect, test } from "@playwright/test";

const MIN = 44;
const CONTROLS =
  'button, a[href], input:not([type="hidden"]), select, textarea, summary, [role="button"], [role="checkbox"], [role="switch"], [role="tab"]';

// hasTouch makes (pointer: coarse) match, so pointer-coarse: styles apply
test.use({ viewport: { width: 390, height: 844 }, hasTouch: true, isMobile: true });

test("every control takes 44px taps on touch", async ({ page }) => {
  // any page of your app; a relative URL needs baseURL in playwright.config.ts
  await page.goto("/settings");
  const misses = await page.evaluate(
    ({ selector, min }) => {
      const half = min / 2 - 1;
      const found: string[] = [];
      for (const el of document.querySelectorAll<HTMLElement>(selector)) {
        // links inside running text are exempt (the inline exception)
        if (el.matches("a") && el.closest("p, label")) continue;
        if (el.closest("[aria-hidden='true'], [inert]")) continue;
        // a control inside a <label> is as big as the label
        const target = el.closest("label") ?? el;
        target.scrollIntoView({ block: "center" });
        const box = target.getBoundingClientRect();
        if (!box.width || !box.height) continue;
        const x = box.left + box.width / 2;
        const y = box.top + box.height / 2;
        const corners = [[-half, -half], [half, -half], [-half, half], [half, half]];
        // hit testing sees ::after hit areas, overflow clipping and overlapping neighbors
        const ok = corners.every(([dx, dy]) => target.contains(document.elementFromPoint(x + dx, y + dy)));
        if (!ok) found.push(`${Math.round(box.width)}x${Math.round(box.height)} ${el.outerHTML.slice(0, 80)}`);
      }
      return found;
    },
    { selector: CONTROLS, min: MIN },
  );
  expect(misses).toEqual([]);
});
```

With Playwright 1.63 the Checkbox demo and the `icon-sm` Button pass it, while a bare 32px button and one inside an `overflow-hidden` wrapper are both reported.

Emulation proves the CSS. It does not prove the layout works one-handed, so finish on a phone: reach for the top corners with the hand that holds it, and tap the controls you placed close together.

#### Where should you start?

Install the free Button with `npx wingo-ui@latest add button` and open your app on a phone: every `md` button is 44px there and 40px with a mouse, and the small sizes carry their own hit area. Add the Checkbox for forms, and copy the `hit-area` utility for anything you built yourself. The Haptic Button, with the same size map plus press feedback and hold to confirm, is part of [Wingo UI Pro](https://wingo-ui.com/pricing). For the rest of the phone rules, from bottom sheets to safe areas, see [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Checkbox](https://wingo-ui.com/components/checkbox) (Free): A box that is on, off or mixed with a check that draws itself, a label row that is the whole target, cards, and groups with select all. Install: `npx wingo-ui@latest add checkbox`
- [Haptic Button](https://wingo-ui.com/components/haptic-button) (Pro): A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode. Install: `npx wingo-ui@latest add haptic-button`
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) (Free): SSR-safe hooks for media queries, phone widths, touch screens and the current Tailwind breakpoint. Install: `npx wingo-ui@latest add use-media-query`

#### FAQ

##### What is the minimum touch target size in WCAG 2.2?

Level AA (SC 2.5.8) asks for 24 by 24 CSS pixels, with exceptions for small targets that are spaced far enough apart, links inside a sentence, unstyled browser controls, controls with an equivalent elsewhere on the page and essential presentations. Level AAA (SC 2.5.5) asks for 44 by 44 CSS pixels.

##### What is the minimum touch target size on iOS?

As of October 2026, Apple's Human Interface Guidelines list 44 by 44 points as the default control size on iOS and iPadOS and 28 by 28 points as the minimum. In a mobile browser with a width=device-width viewport, one CSS pixel is one point, so 44px in CSS matches Apple's 44 pt.

##### Is a 44px touch target enough for Android?

It meets WCAG AAA and Apple's default, and it is 4px short of Android's recommendation. Google's Android accessibility guidance asks for 48 by 48 dp with 8 dp between targets, and one dp is one CSS pixel in a mobile browser. If most of your users are on Android, use 48px on coarse pointers.

##### Does an invisible hit area count toward the target size?

Yes. WCAG measures the region that accepts pointer input, so padding or a pseudo-element hit area counts. It stops counting where an overflow-hidden ancestor clips it or where it overlaps a neighbor that does something else.

##### What is the pointer coarse media query?

@media (pointer: coarse) matches when the primary pointing device has limited accuracy, such as a finger on a touchscreen. Tailwind CSS v4.1 and later ship it as the pointer-coarse variant; any-pointer: coarse matches when any connected input is coarse, which includes a laptop with a touchscreen.

##### Do Wingo UI components meet 44px on touch screens?

The Button, Checkbox and Haptic Button do. Medium buttons grow from 40 to 44px under pointer: coarse, small ones keep their look and gain a 44px hit area, and checkbox rows are at least 44px tall with the whole row as the target. The Button and Checkbox are free; the Haptic Button is Pro.

---

Source: https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind

### Mobile-First React Components: 9 Rules With Code

> Mobile-first React components, rule by rule: bottom sheets instead of popovers, 44px touch targets, safe areas, dvh, keyboard-aware bars and tables as cards.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 20 min
- Canonical: https://wingo-ui.com/blog/mobile-first-react-components

#### TL;DR

Mobile-first React components are designed for a thumb on a 390px screen first and enhanced for a mouse after. The nine rules: open popovers, selects, menus and dialogs as bottom sheets below 768px; make targets 44px on coarse pointers; never hide a control behind hover; pad fixed bars with the safe-area insets; size full-height layouts in dvh, not vh; keep bottom bars out of the on-screen keyboard; turn table rows into cards; give every gesture a visible alternative; and switch layout with CSS breakpoints. Keep media query hooks for behavior only, because the server does not know the screen width.

Open a typical React app on a phone and the cracks show in the same places: a dropdown menu hanging off the edge of the screen, a 32px icon button you have to aim for, a checkout bar hidden behind the home indicator, a data table you scroll sideways to read one row. Mobile-first React components fix those problems once, inside the component, so every screen that uses them gets them right without a media query in the page. This is the rulebook we follow in Wingo UI, with the reason and the code for each rule. We build Wingo UI, so we are not neutral; outside facts link to their sources and are dated.

#### What makes a React component mobile-first?

A mobile-first component is designed for a thumb on a 360 to 390px screen with an on-screen keyboard, and then enhanced for a mouse and a wide window. Beyond reflowing its layout, the component changes how it behaves: which overlay it opens, how big its hit area is, what replaces hover, and where it sits relative to the notch and the keyboard.

The nine rules in one table, then a section for each:

| Rule | On a phone | Why |
| --- | --- | --- |
| Overlays | Popovers, selects, menus and dialogs open as bottom sheets below 768px | An anchored panel has no room and sits under the thumb |
| Touch targets | 44px on coarse pointers, 8px apart | A finger is less precise than a cursor |
| Hover | Nothing is hover-only | Touch screens have no hover |
| Safe areas | Fixed bars pad `env(safe-area-inset-*)` | The notch and the home indicator cover content |
| Height | `dvh` or `svh`, never `vh` | `100vh` is taller than the visible screen |
| Keyboard | Bottom bars hide or ride above it, inputs use 16px text | Fixed bars end up behind the keyboard |
| Tables | Rows become cards | Sideways scrolling hides most of every row |
| Gestures | Every gesture has a visible alternative | Gestures are invisible, and not everyone can perform them |
| Layout and behavior | CSS breakpoints for layout, a hook for behavior | The server does not know the screen width |

If you are building a React mobile first UI from scratch, apply each rule in every component before adding the next one: people learn an interface from its most common pattern.

#### Why should a popover become a bottom sheet on a phone?

A popover anchored to a small trigger has nowhere good to go on a 390px screen, while a bottom sheet opens where the thumb already is. The finger that tapped the trigger covers it, the panel gets clipped or flipped above the trigger, and a tap that lands just outside it closes it. A sheet takes the full width, has room for 48px rows, can be dragged away, and keeps its actions in the bottom part of the screen, the part a thumb reaches without changing grip.

We render a bottom sheet below 768px for the popover, select, dropdown menu, context menu and dialog, by default. The exceptions matter as much as the rule:

- Tooltips never become sheets. Nothing hovers on a touch screen, so the text goes inline or behind a long press.
- Alert dialogs stay centered at every width. A short question that must be answered reads like an iOS alert.
- Suggestions under a text field stay attached to it, because a sheet would cover what you type, as in the [Mention Input](https://wingo-ui.com/components/mention-input). The [Combobox](https://wingo-ui.com/components/combobox) takes the other route: a full-height sheet with its own search box.

In Wingo UI the switch is a `responsive` prop that defaults to `true` on the [Popover](https://wingo-ui.com/components/popover), [Select](https://wingo-ui.com/components/select), [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu), [Dialog](https://wingo-ui.com/components/dialog) and the date pickers. You write the component once:

```tsx
"use client";

import { ChevronDown } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Popover, PopoverClose } from "@/components/ui/popover";

export function PriceFilter({ onApply }: { onApply: () => void }) {
  return (
    <Popover
      trigger={
        <Button variant="soft" rightIcon={<ChevronDown />}>
          Price
        </Button>
      }
      title="Price"
      description="Pick a range or type your own."
      footer={
        <PopoverClose asChild>
          <Button size="sm" onClick={onApply}>
            Apply
          </Button>
        </PopoverClose>
      }
    >
      <p className="text-muted-foreground">Between $500 and $1,500</p>
    </Popover>
  );
}
```

On a desktop that is a floating panel with a right-aligned Apply button. Below 768px the same JSX opens a bottom sheet with a handle and a full-width 48px Apply button. Pass `responsive={false}` when a panel has to stay anchored to a field.

The sheet underneath is the free [Drawer](https://wingo-ui.com/components/drawer), built on vaul. It follows your finger, closes when you let go past a quarter of its height or flick it, stops at snap points, and lets a long list scroll first and drag the sheet only once the list is back at the top. Opening it moves focus to the sheet itself instead of the first field, so the keyboard does not jump up over half the content. From 768px it stays a centered sheet, or becomes a side panel or a dialog, depending on the `desktop` prop.

> Live demo (Drawer): Tap Filters: on a phone the sheet slides up and you can drag it down to close; on a wide screen this one opens as a side panel. Try it at [Drawer](https://wingo-ui.com/components/drawer) and install it with `npx wingo-ui@latest add drawer`.

The demo is a listings page: Filters opens a draggable bottom sheet below 768px and a panel from the right edge on wider screens, with the result count on a pinned button in both.

Two posts go deeper on this rule. The [React bottom sheet guide](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web) covers snap points, drag to dismiss, nested sheets and the keyboard, and the [shadcn responsive dialog tutorial](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile) builds the same card-to-sheet switch on stock shadcn/ui.

#### How do you switch between a sheet and a dialog without a hydration flash?

Use CSS breakpoints for anything visible on the first paint, and a media query hook only for behavior that starts after an interaction, such as which overlay opens. The server has no screen, so any hook that reads `matchMedia` has to return a guess during server rendering and hydration. When that guess drives visible layout, phones see the desktop layout first and then a jump.

The `use-mobile` hook that ships with shadcn/ui's sidebar [starts as `undefined`, returns `false`, and flips in an effect](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/hooks/use-mobile.ts) (as of October 2026). Our free [useMediaQuery](https://wingo-ui.com/components/use-media-query) uses the same 768px breakpoint, reads it through `useSyncExternalStore` and makes the server value a parameter. This is the core of it:

```ts
import { useCallback, useSyncExternalStore } from "react";

export function useMediaQuery(query: string, serverFallback = false) {
  const subscribe = useCallback(
    (onChange: () => void) => {
      const list = window.matchMedia(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query],
  );
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    // the server and the hydration render
    () => serverFallback,
  );
}

export const useIsMobile = () => useMediaQuery("(max-width: 767.98px)");
```

Both hooks say `false` on the server. That is harmless for overlays, because an overlay is closed during server rendering: by the time someone taps the trigger, the hook holds the real value. It is harmful for content:

```tsx
// wrong: the server renders the table, phones swap to cards after hydration
const isMobile = useIsMobile();
return isMobile ? <InvoiceCards rows={rows} /> : <InvoiceTable rows={rows} />;

// right: both are in the HTML and CSS picks one before the first paint
return (
  <>
    <InvoiceTable rows={rows} className="hidden md:table" />
    <InvoiceCards rows={rows} className="md:hidden" />
  </>
);
```

This is the part of mobile first design React apps get wrong without noticing, because the wrong version looks fine when you drag a desktop window narrow after the page has loaded. The jump only shows when a phone loads the server-rendered page. Our [guide to an SSR-safe React use mobile hook](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) tests three common versions of the hook through hydration and sorts which jobs belong to CSS.

#### How big should touch targets be?

Make every target 44 by 44 CSS pixels on touch screens and keep at least 8px between neighbors. The standards disagree on the exact number; 44px meets the strictest web criterion (WCAG level AAA) and Apple's default control size:

| Source (as of October 2026) | Size | Status |
| --- | --- | --- |
| [WCAG 2.2, 2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) | 24 by 24 CSS px, or enough spacing | Level AA |
| [WCAG 2.2, 2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) | 44 by 44 CSS px | Level AAA |
| [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility) | 44 by 44 pt default on iOS, 28 by 28 pt minimum | Guideline |
| [Android accessibility guide](https://developer.android.com/guide/topics/ui/accessibility/apps) | 48 by 48 dp | Recommendation |

The catch is the desktop. A 44px button everywhere makes a toolbar or a settings page look bloated next to a mouse pointer. Tailwind CSS v4 has a [`pointer-coarse` variant](https://tailwindcss.com/docs/hover-focus-and-other-states) that compiles to `@media (pointer: coarse)`, so the size can follow the input device instead of the screen width. A tablet and a phone both get the bigger targets; a laptop with a trackpad does not.

For a text button the size is `h-10 pointer-coarse:h-11`: 40px with a mouse, 44px under a finger. An icon button that must stay small gets an invisible hit area instead:

```tsx
import { Ellipsis } from "lucide-react";

// looks 32px, takes 44px taps on touch
export function MoreButton() {
  return (
    <button
      type="button"
      aria-label="More actions"
      className="relative grid size-8 touch-manipulation place-items-center [-webkit-tap-highlight-color:transparent] pointer-coarse:after:absolute pointer-coarse:after:-inset-1.5"
    >
      <Ellipsis className="size-4" />
    </button>
  );
}
```

The `::after` trick adds 6px on every side of the 32px button without moving anything. `touch-manipulation` turns off double-tap zoom on the control, so taps register without the browser waiting for a second one, and the transparent tap highlight removes the gray box mobile browsers paint on a tapped element. Both live on the component itself, because a component copied into another project does not bring your global stylesheet along. The [Button](https://wingo-ui.com/components/button) in Wingo UI is built this way: `md` is 40px with a mouse and 44px on touch, `sm` and `icon-sm` stay 32px and get the invisible hit area, and `lg` is 48px everywhere. The [minimum touch target size guide](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind) compares what WCAG, Apple and Android require and shows how to test the hit areas.

#### Why do hover effects break on phones?

Touch screens have no hover, so anything that only appears on hover does not exist on a phone. In Tailwind CSS v4 the `hover:` variant [only applies when the primary input can hover](https://tailwindcss.com/docs/upgrade-guide) (`@media (hover: hover)`). That fixes the old sticky hover state after a tap, and it also means a hover-only control never shows up on touch at all.

The classic case is a row action that fades in when the pointer is over the row. The fix is a focus variant and a coarse-pointer variant:

```tsx
import { Ellipsis } from "lucide-react";

export function ClientRow({ name }: { name: string }) {
  return (
    <li className="group/row flex h-12 items-center justify-between gap-3 px-4">
      {name}
      <button
        type="button"
        aria-label={`Actions for ${name}`}
        className="grid size-8 place-items-center opacity-0 transition-opacity group-hover/row:opacity-100 group-focus-within/row:opacity-100 pointer-coarse:opacity-100"
      >
        <Ellipsis className="size-4" />
      </button>
    </li>
  );
}
```

Hover reveals it for a mouse, focus reveals it for a keyboard, and on a coarse pointer it is always there. The [Data Table](https://wingo-ui.com/components/data-table) puts the same classes on the wrapper of its row menu trigger, plus `has-[[data-state=open]]:opacity-100`: without it, the trigger fades out while its menu is open, as soon as the pointer moves from the row into the menu. The other two replacements for hover are a tap and a long press: a hover card opens as a sheet on the first tap, a tooltip shows on a long press, and a context menu opens as an action sheet when you hold a row.

#### How do you keep fixed bars clear of the notch and the home indicator?

Set `viewport-fit=cover`, then pad every element pinned to a screen edge with `env(safe-area-inset-*)`, with a minimum for devices that report zero. `cover` scales the viewport to fill the whole display, notch and home indicator included, and [MDN highly recommends](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport) the safe area inset variables with it so important content stays visible.

In the Next.js App Router the viewport meta tag comes from a `viewport` export in the root layout:

```tsx
// app/layout.tsx
import type { Viewport } from "next";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};
```

Then pad with an arbitrary value: `pb-[max(env(safe-area-inset-bottom),12px)]`. A plain `pb-[env(safe-area-inset-bottom)]` leaves buttons touching the screen edge on devices without a home indicator, where the inset is 0; `max()` keeps a little air.

The harder problem is two bars at once. A product page on a phone often has a tab bar at the bottom and a buy bar above it, and both want the safe area. The [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) pads the home indicator and writes its height to a `--bottom-bar-offset` CSS variable. The [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) sits at `bottom: var(--bottom-bar-offset)` and pads only the part of the safe area the tab bar does not already cover, so there is no double gap:

```tsx
"use client";

import { House, Search, ShoppingBag, UserRound } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";
import { StickyCtaBar } from "@/components/ui/sticky-cta-bar";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Search", href: "/search", icon: <Search /> },
  { label: "Cart", href: "/cart", icon: <ShoppingBag />, badge: 2 },
  { label: "Account", href: "/account", icon: <UserRound /> },
];

export function ProductChrome({ onAddToCart }: { onAddToCart: () => Promise<void> }) {
  return (
    <>
      <StickyCtaBar
        price={349}
        compareAtPrice={449}
        locale="en-US"
        actionLabel="Add to cart"
        tone="brand"
        hideFrom="md"
        onAction={onAddToCart}
      />
      <BottomTabBar items={tabs} className="md:hidden" hideOnScroll />
    </>
  );
}
```

The tab bar takes 3 to 5 tabs, each far larger than 44px. With `hideOnScroll` it follows your finger out of view on the way down and comes back on the way up, moved by a motion value so nothing re-renders per frame. The buy bar shows a spinner while the `onAction` promise runs without changing its width. The [Tailwind safe area insets tutorial](https://wingo-ui.com/blog/tailwind-safe-area-insets) covers the utilities, a FAB stacked above the tab bar and where toasts go, and the [React bottom navigation bar guide](https://wingo-ui.com/blog/react-bottom-navigation-bar) covers badges, the center action and when a sidebar fits better.

> Live demo (Bottom Tab Bar): Tap the tabs, then tap the active one again to jump back to the top; the raised Add button opens a sheet. Try it at [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) and install it with `npx wingo-ui@latest add bottom-tab-bar`.

The demo is a small CRM with four tabs, an unread count on Inbox and a raised Add action. Open a client, then tap Clients again: the tab goes back to its first screen, the way iOS tab bars do.

#### Should you use 100vh, dvh or svh on mobile?

Use `dvh` for app shells and sheets, `svh` for blocks that must not change height while scrolling, and never `vh`. [MDN defines](https://developer.mozilla.org/en-US/docs/Web/CSS/length) `vh` as equal to `lvh`, the large viewport measured with the browser toolbars retracted. While the address bar is showing, `100vh` (Tailwind's `h-screen`) is taller than the visible area, and the bottom of your layout, often the button that matters, sits under the toolbar.

`dvh` follows the toolbars as they expand and retract, which is what a full-height shell wants. MDN also warns that dynamic units can resize content while the user scrolls, so a hero section sized in `dvh` may twitch; `svh` is the stable choice there. Tailwind CSS v4 ships `h-dvh`, `min-h-dvh`, `h-svh` and `h-lvh`. In Wingo UI the [App Shell](https://wingo-ui.com/components/app-shell) uses `min-h-dvh` and bottom sheets cap at `max-h-[92dvh]`, so a tall sheet keeps a strip of the page visible above it whatever the toolbars do. The [100vh mobile fix](https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind) compares the three units in detail and builds both kinds of full-height shell.

#### What happens to bottom bars when the on-screen keyboard opens?

They end up behind the keyboard unless you move them. Since [Chrome 108 on Android](https://developer.chrome.com/blog/viewport-resize-behavior), the keyboard resizes only the visual viewport, which the Chrome team describes as matching Safari on iOS. An element with `position: fixed; bottom: 0` is placed against the layout viewport, which still reaches the bottom of the screen, behind the keyboard.

There are two good answers. Hide the bar while a field has focus, which suits a checkout bar with a coupon field (the Sticky CTA Bar's default, `keyboard="hide"`). Or lift it by the height the keyboard covers, which suits a chat composer (`keyboard="lift"`). The lift comes from the visual viewport: the covered height is `innerHeight - visualViewport.height - visualViewport.offsetTop` while a text field has focus. The [useKeyboardInset](https://wingo-ui.com/components/use-keyboard-inset) hook (Pro) measures it at most once per frame and exposes it as a motion value, so the bar moves without a re-render:

```tsx
"use client";

import { motion, useTransform } from "motion/react";
import { useKeyboardInset } from "@/hooks/use-keyboard-inset";

export function Composer() {
  const { inset } = useKeyboardInset();
  const y = useTransform(inset, (value) => -value);
  return (
    <motion.form style={{ y }} className="fixed inset-x-0 bottom-0 bg-background px-4 pt-2 pb-[max(env(safe-area-inset-bottom),12px)]">
      <input
        aria-label="Message"
        inputMode="text"
        enterKeyHint="send"
        autoComplete="off"
        className="h-11 w-full rounded-full bg-foreground/5 px-4 text-base md:text-sm"
      />
    </motion.form>
  );
}
```

Two more keyboard rules. Give text inputs 16px text on phones (`text-base md:text-sm`): iOS Safari zooms the page into any focused field with smaller text and does not zoom back out. And set `inputMode`, `enterKeyHint` and `autoComplete` on every field, so the phone shows the right keyboard, the right return key label and the right autofill.

#### How should a data table work on a phone?

Below 768px, turn every row into a card: the primary field as the title, a status badge or an amount in the corner, two to four secondary fields as label and value pairs, and the row actions in a menu that opens as a sheet. Horizontal scrolling is acceptable only when the job is comparing columns, like a spreadsheet or a pricing matrix. For a list of invoices or clients it hides most of every row and makes people scroll in two directions to read one record.

The [Data Table](https://wingo-ui.com/components/data-table) does this by default (`mobileLayout="cards"`). Each column can say where it goes on the card with a `mobile` role, and the table guesses sensibly when you do not (the first column is the title, the first badge or else the last number is the meta):

```tsx
"use client";

import { Pencil } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

type Invoice = { id: string; client: string; city: string; status: string; amount: number };

const col = createColumns<Invoice>();
const columns = col([
  col.accessor("client", { header: "Client", mobile: "title" }),
  col.accessor("city", { header: "City", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Overdue: { tone: "danger" }, Draft: { tone: "neutral" } },
    mobile: "meta",
  }),
  col.accessor("amount", { header: "Amount", type: "currency" }),
  col.accessor("id", { header: "Invoice", mobile: "hidden" }),
]);

export function Invoices({ invoices }: { invoices: Invoice[] }) {
  return (
    <DataTable
      data={invoices}
      columns={columns}
      caption="Invoices"
      locale="en-US"
      selectionMode="multiple"
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
    />
  );
}
```

On a phone you long press a card to start selecting, tap to add more, and the bulk actions float at the bottom. Sorting, filters and the row menu open as bottom sheets, and Load more appends rows instead of a pager with tiny page numbers. The table and the cards are both in the server HTML, hidden and shown with breakpoints, so a phone never sees the table first. The [TanStack Table v9 data table tutorial](https://wingo-ui.com/blog/tanstack-table-v9-data-table) builds filters, bulk actions and server pagination on TanStack directly, along with the phone layout.

> Live demo (Data Table): On a phone every row is a card you can long press to select; on a wide screen you get the full table with sorting and column menus. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

The demo is a client list with search, quick filters, status badges and balances. Below 768px each row becomes a card with the client name as the title and the status in the corner. Which columns make it onto a card, and how sorting and bulk actions work without headers, are in the [responsive table mobile guide](https://wingo-ui.com/blog/responsive-table-mobile-cards).

#### Which gestures belong in a mobile web app?

Drag to dismiss, pull to refresh, swipe actions on rows and hold to confirm all belong, as long as each has a visible alternative and leaves native scrolling alone. Gestures are invisible until someone shows you, and people using a keyboard, a switch or a screen reader cannot perform them at all.

- **Always a button path.** Sheets close with Escape, a tap outside or a close button. Pull to refresh pairs with a refresh button. Swipe actions on a row also live in its menu.
- **`touch-action` on draggable surfaces.** `touch-pan-y` on something you swipe sideways keeps vertical scrolling native; `touch-none` is for surfaces you drag freely, like a signature pad or a slider thumb.
- **`overscroll-behavior: contain` on scroll containers.** It stops a scroll inside a sheet from chaining into the page, and keeps the browser's own pull to refresh from fighting yours.
- **Motion values, not state.** A drag that calls `setState` on every pointer move re-renders on every frame. Write the offset to a motion value and only commit state when the gesture ends.

Sortable lists and boards are where these rules collide with native scrolling; the [dnd kit mobile tutorial](https://wingo-ui.com/blog/dnd-kit-mobile-touch-drag) sets up touch sensors that let a swipe still scroll the page.

The [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) shows where the rules bend. It sets `overscroll-behavior-y: contain` on its scroller and moves the content with a motion value under rubberband resistance. It cannot use `touch-action`, because the list it wraps must keep scrolling natively, so it listens to `touchmove` with `passive: false` and cancels the scroll only for a downward pull at the very top. It ticks when the pull arms, spins until your promise settles (500ms at least, so it never flashes), and exposes the same refresh as an API for a button (the [React pull to refresh guide](https://wingo-ui.com/blog/react-pull-to-refresh) covers the indicator styles, accessibility and long virtualized lists):

```tsx
"use client";

import { useState, type ReactNode } from "react";
import { RotateCw } from "lucide-react";
import { Button } from "@/components/ui/button";
import { PullToRefresh, type PullToRefreshApi } from "@/components/ui/pull-to-refresh";

export function Feed({ reload, children }: { reload: () => Promise<void>; children: ReactNode }) {
  const [api, setApi] = useState<PullToRefreshApi>();
  return (
    <div className="flex h-dvh flex-col">
      <header className="flex h-14 items-center justify-end px-4">
        <Button variant="ghost" size="icon" radius="full" aria-label="Reload" onClick={() => api?.refresh()}>
          <RotateCw />
        </Button>
      </header>
      <PullToRefresh scroll="self" className="min-h-0 flex-1" setApi={setApi} onRefresh={reload}>
        {children}
      </PullToRefresh>
    </div>
  );
}
```

Hold to confirm is the gesture for actions that deserve more than a tap and less than a dialog, like deleting a client. The [Haptic Button](https://wingo-ui.com/components/haptic-button) in `mode="hold"` fills while you hold a finger, the mouse button, Space or Enter, and runs `onConfirm` when the fill completes. Screen readers and voice control, which activate with a plain click and cannot hold, get a two-step path instead: the first activation announces "Activate again to confirm" and a second one within 4 seconds confirms.

```tsx
"use client";

import { Trash2 } from "lucide-react";
import { HapticButton } from "@/components/ui/haptic-button";

export function DeleteClient({ onDelete }: { onDelete: () => Promise<void> }) {
  return (
    <HapticButton tone="danger" variant="soft" mode="hold" fullWidth leftIcon={<Trash2 />} onConfirm={onDelete}>
      Hold to delete
    </HapticButton>
  );
}
```

On Android the tick uses `navigator.vibrate`. Safari on iPhone has no Vibration API, so the haptics helper falls back to clicking a hidden native switch (`<input type="checkbox" switch>`). That played the system tick up to iOS 26.4; from iOS 26.5 WebKit ticks only for the user's own tap on the switch, so on a current iPhone the fill carries the feedback on its own. Desktops and mouse clicks stay silent. The [Web Vibration API guide](https://wingo-ui.com/blog/web-vibration-api-haptic-feedback) covers what still ticks on an iPhone and how to let people turn haptics off.

#### Does shadcn/ui handle mobile?

Partly. As of October 2026 the shadcn mobile story is one component and one pattern. The [Drawer docs](https://ui.shadcn.com/docs/components/drawer) come in a Base UI version, which now uses Base UI's drawer instead of Vaul, and a Radix version, which is still [built on Vaul](https://ui.shadcn.com/docs/components/radix/drawer). Both include a Responsive section that renders a `Dialog` on desktop and a `Drawer` on mobile; the example decides with `useMediaQuery("(min-width: 768px)")` and shares one form between both branches. The [Popover docs](https://ui.shadcn.com/docs/components/popover) describe no mobile behavior, and Select and Dropdown Menu stay floating panels at every width unless you write a wrapper for each.

That suits a library meant as a minimal, unopinionated starting point. shadcn/ui is free and MIT licensed, its GitHub repository shows about 125k stars (as of October 2026), and its docs let you choose between Base UI, Radix and React Aria primitives. If your app is used mostly on desktops, or you want to write and own every responsive wrapper yourself, it is the better choice. Our [comparison of the best React component libraries for mobile](https://wingo-ui.com/blog/best-react-component-library-for-mobile) checks shadcn/ui and eight others at 390px.

If most of your users arrive on phones, the wrappers add up: every overlay needs the swap, every control needs the coarse-pointer size, every fixed bar needs the safe area, and every one of them has to avoid the hydration flash. Wingo UI makes those decisions inside each component, so the defaults are already mobile-first and you opt out per instance.

#### Which components does a React mobile web app need?

A React mobile web app usually needs overlays that become sheets, a tab bar for the primary navigation, a bottom action bar on product and checkout pages, lists with swipe actions, and a table that becomes cards. Here is the set in Wingo UI (registry 1.7.0, 326 items as of October 2026), with what each one does on a phone:

| Component | Job on a phone | Access |
| --- | --- | --- |
| [Drawer](https://wingo-ui.com/components/drawer) | The bottom sheet: drag to dismiss, snap points, nesting | Free |
| Popover, Select, Dropdown Menu, Dialog | Open as bottom sheets below 768px | Free |
| [Segmented Control](https://wingo-ui.com/components/segmented-control) | A few options on a thumb you can drag | Free |
| [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) | 3 to 5 primary destinations at the thumb | Pro |
| [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) | Price and the main action, above the tab bar | Pro |
| [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) | Reload a list with a pull, or a button | Pro |
| [List](https://wingo-ui.com/components/list) | Grouped rows with swipe actions and drag to reorder | Pro |
| [Data Table](https://wingo-ui.com/components/data-table) | Rows as cards, long press to select | Pro |
| [Haptic Button](https://wingo-ui.com/components/haptic-button) | Press feedback, haptics and hold to confirm | Pro |
| [Large Title Header](https://wingo-ui.com/components/large-title-header) | An iOS large title that collapses into a bar | Pro |
| [Action Sheet](https://wingo-ui.com/components/action-sheet) | A short list of actions about one thing | Pro |
| [Picker Wheel](https://wingo-ui.com/components/picker-wheel) | iOS wheels for times and dates | Pro |

The whole [Mobile category](https://wingo-ui.com/components/category/mobile) has 15 components, all built to these rules, with reduced motion support and designed light and dark themes.

#### How do you test mobile-first React components?

Test at 390 by 844 and 360 by 780 with touch enabled, then on a real iPhone for the parts emulators get wrong. Chrome's device mode switches the pointer to coarse, which is enough to see `pointer-coarse` styles and the sheets. It does not reproduce the iOS keyboard, the focus zoom, the home indicator or the toolbar resizing, so those need a phone.

For automated checks, Playwright can emulate a touch phone per test file:

```ts
import { expect, test } from "@playwright/test";

test.use({ viewport: { width: 390, height: 844 }, hasTouch: true, isMobile: true });

test("filters open as a bottom sheet on a phone", async ({ page }) => {
  await page.goto("/listings");
  await page.getByRole("button", { name: "Filters" }).tap();
  await expect(page.getByRole("dialog", { name: "Filters" })).toBeVisible();
});
```

Run the same pass in light and dark and with reduced motion turned on. A sheet handle or a hairline drawn at a low opacity can be clear in one theme and vanish in the other, and under reduced motion every overlay still has to open and close, only with a shorter slide or a fade.

#### Which guides go deeper on each rule?

Each of these posts in [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui) takes one rule or one component further:

- [Shadcn responsive dialog](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile): a centered card on desktop and a bottom sheet on phones, with the content written once.
- [React bottom sheet for the web](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web): snap points, drag to dismiss, nested sheets and the keyboard on vaul.
- [Minimum touch target size](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind): the WCAG, iOS and Android numbers, and 44px on touch in Tailwind without a bloated desktop.
- [Tailwind safe area insets](https://wingo-ui.com/blog/tailwind-safe-area-insets): bottom bars, FABs and toasts clear of the notch and the home indicator.
- [100vh on mobile](https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind): when to use dvh, svh or lvh, and full-height shells that do not jump.
- [React bottom navigation bar](https://wingo-ui.com/blog/react-bottom-navigation-bar): a tab bar with badges, a center action and hide on scroll.
- [React pull to refresh](https://wingo-ui.com/blog/react-pull-to-refresh): a custom refresh in a PWA that does not fight the browser's own.
- [Web Vibration API](https://wingo-ui.com/blog/web-vibration-api-haptic-feedback): the haptic feedback a page can trigger on Android and iPhone.
- [React PWA install prompt](https://wingo-ui.com/blog/react-pwa-install-prompt): an install prompt for Chrome, Edge and iPhone, and when not to ask.
- [Responsive tables on mobile](https://wingo-ui.com/blog/responsive-table-mobile-cards): when rows become cards, which columns survive, and sorting and bulk actions without headers.
- [React segmented control](https://wingo-ui.com/blog/react-segmented-control): the iOS thumb you can drag, radio semantics, and when tabs or a toggle group fit better.
- [React wheel picker](https://wingo-ui.com/blog/react-wheel-picker): iOS wheels for times and dates on a native snapping scroller, with a typed field on desktop.

#### Where should you start?

Start with the overlays, because they are the most visible mobile failure and the cheapest to fix. Install the free Popover with `npx wingo-ui@latest add popover` (it brings the Drawer, the Button and the media query hook along), swap it in for one panel that people open on phones, and try it on your own device. The tab bar, sticky CTA bar, pull to refresh, haptic button and data table are part of [Wingo UI Pro](https://wingo-ui.com/pricing).

#### Components in this post

- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [Popover](https://wingo-ui.com/components/popover) (Free): Rich floating content anchored to a trigger, like a quick filter, form or share panel, that becomes a bottom sheet on phones. Install: `npx wingo-ui@latest add popover`
- [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: `npx wingo-ui@latest add bottom-tab-bar`
- [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) (Pro): Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick. Install: `npx wingo-ui@latest add pull-to-refresh`
- [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) (Pro): The bottom action bar of product, listing and checkout pages on phones: the price on one side, the main action on the other. Install: `npx wingo-ui@latest add sticky-cta-bar`
- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`
- [Haptic Button](https://wingo-ui.com/components/haptic-button) (Pro): A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode. Install: `npx wingo-ui@latest add haptic-button`

#### FAQ

##### What is a mobile-first React component?

A component designed for touch, a narrow screen and an on-screen keyboard first, then enhanced for a mouse and a wide window. On a phone it changes its behavior as well as its layout: it opens a bottom sheet instead of a popover, keeps 44px hit areas and has no hover-only controls.

##### How big should buttons be in a mobile web app?

WCAG 2.2 asks for 24 by 24 CSS pixels at level AA and 44 by 44 at level AAA. Apple's guidelines use 44 by 44 points as the default iOS control size and Android recommends 48 by 48 dp. A practical rule for the web is 44px on coarse pointers with 8px between targets.

##### Should I use a useIsMobile hook or CSS media queries?

Use CSS breakpoints for anything visible on the first paint, because the server cannot know the screen width and a hook returns a guess there. Use the hook for behavior that starts after an interaction, such as opening a bottom sheet instead of a popover.

##### Does shadcn/ui have a bottom sheet for mobile?

Yes, the Drawer. As of October 2026 its Base UI version is built on Base UI's drawer and its Radix version on Vaul, and the docs show a responsive example that renders a Dialog on desktop and a Drawer on mobile. Popover, Select and Dropdown Menu do not switch to a sheet on their own.

##### Why do hover effects not work on phones?

Touch screens have no hover, and in Tailwind CSS v4 the hover variant only applies when the primary input can hover, so a control that only appears on hover never shows up on a phone. Reveal it on focus and on coarse pointers as well, or replace the hover with a tap or a long press.

##### Which Wingo UI mobile components are free?

The Drawer, Sheet, Popover, Dialog, Select, Dropdown Menu, Segmented Control, Button and the useMediaQuery hook are free, and the Popover, Dialog, Select and Dropdown Menu open as bottom sheets below 768px by default. The 15 components of the Mobile category (tab bar, sticky CTA bar, pull to refresh, haptic button and more) and the Data Table are Pro.

---

Source: https://wingo-ui.com/blog/mobile-first-react-components

### Nextjs Admin Dashboard Tutorial: 5 Screens, Phone-Ready

> A nextjs admin dashboard tutorial for the App Router: app shell, KPI home, server-side data tables, settings and team pages, each one usable on a phone.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Build it: screens and apps](https://wingo-ui.com/blog/category/build)
- Reading time: 19 min
- Canonical: https://wingo-ui.com/blog/nextjs-admin-dashboard-tutorial

#### TL;DR

Build a Next.js admin dashboard as five screens in one App Router route group: an app shell layout, a home page with KPIs, list pages with a server-side data table whose state lives in the URL, a settings page and a team page with roles. Pages fetch through a server-only data access layer, and every change goes through a Server Action that checks the session itself. On phones the sidebar becomes a drawer with a bottom tab bar, table rows become cards and menus open as bottom sheets.

Most admin dashboard tutorials stop at a sidebar, four stat cards, a chart and a table that scrolls sideways on a phone. A back office needs more: list pages that filter on the server, a settings page that keeps what someone typed when a save fails, a team page with roles, loading and error states on every route, and a layout that works when the person approving an invoice is on a phone. This nextjs admin dashboard tutorial builds all of it on the Next.js App Router with React 19 and Tailwind CSS v4, screen by screen, with the code. We build Wingo UI and the examples use our blocks, so we are not neutral; the App Router patterns work with any component library, and the last section compares the free starters.

#### What does a Next.js admin dashboard need?

Five screens and two states: a shell around a home page, list pages, a settings page and a team page, each with a loading and an error state. The React admin dashboard components we use for each, and their phone behavior:

| Screen | Its job | Built with | On a phone |
| --- | --- | --- | --- |
| Shell | Navigation, search, the account | [App Shell](https://wingo-ui.com/components/app-shell) with [Sidebar](https://wingo-ui.com/components/sidebar) | The sidebar moves into a drawer, a tab bar takes the bottom edge |
| Home | What changed, what needs attention | [Admin Dashboard Page](https://wingo-ui.com/components/admin-dashboard-page) or [KPI Dashboard](https://wingo-ui.com/components/kpi-dashboard) | KPIs two per row, panels in one column |
| Lists | Find, filter and act on records | [Data Table](https://wingo-ui.com/components/data-table) in server mode | Rows become cards, menus become bottom sheets |
| Settings | Profile, account, billing, security | [Settings Page](https://wingo-ui.com/components/settings-page) | A list that pushes each section in, like iOS Settings |
| Team | Members, roles, audit log | [Users Admin Page](https://wingo-ui.com/components/users-admin-page) | Member cards, one role at a time in the matrix |
| Loading and errors | Every route | `loading.tsx`, `error.tsx` and each block's `loading` prop | Skeletons in the phone layout |

#### How should you structure the App Router for an admin dashboard?

Put every admin route in one route group with its own layout. A folder in parentheses [does not appear in the URL](https://nextjs.org/docs/app/api-reference/file-conventions/route-groups), so `app/(admin)/clients/page.tsx` serves `/clients` while the group's `layout.tsx` wraps it in the shell. Sign-in lives in its own group and never sees the sidebar.

```text
app/
  layout.tsx                 root: html, body, <Providers>
  providers.tsx              LinkProvider (next/link) and the Toaster
  (auth)/
    sign-in/page.tsx         no shell
  (admin)/
    layout.tsx               the shell: AppShell, Sidebar, Topbar
    nav.tsx                  sidebar groups and phone tabs
    error.tsx                the admin error boundary
    page.tsx                 /: the home with KPIs
    dashboard-home.tsx
    actions.ts               order actions for the home
    clients/
      page.tsx               reads the URL, fetches one page
      clients-table.tsx
      query.ts
      loading.tsx
      [id]/page.tsx          one client
    settings/
      page.tsx
      settings-view.tsx
      actions.ts
    team/
      page.tsx
      team-view.tsx
      actions.ts
server/
  dal.ts                     "server-only": verifySession, getUser, requireAdmin
```

Three rules hold it together:

1. **Pages fetch, views render.** Each `page.tsx` is a server component that loads data. The blocks are client components, so function props (a save handler, a router call) live in a small `*-view.tsx` next to the page.
2. **Auth lives in the data access layer.** [Layouts do not re-render on navigation](https://nextjs.org/docs/app/guides/authentication#layouts-and-auth-checks), so a layout check misses route changes. Call `verifySession()` from a `server-only` module in every page and every Server Action; the [data security guide](https://nextjs.org/docs/app/guides/data-security) says to treat each Server Action as reachable by a direct POST request.
3. **The URL holds the view.** Period, filters, page, open tab: if it changes what the screen shows, it goes in the search params, so a link reproduces the screen.

#### How do you build the app shell for a Next.js admin dashboard?

Render one `AppShell` in the group's layout with a `Sidebar` and a `Topbar`, and read the sidebar's cookie on the server so the first paint is right. The shell shows the sidebar beside the page on desktop, and a drawer plus a bottom tab bar on phones. It switches with CSS, so the server HTML is already right.

First, the router wiring: the Wingo UI navigation links render through `LinkProvider`, so one client provider turns them all into `next/link`:

```tsx
// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import Link from "next/link";
import { usePathname, useRouter } from "next/navigation";
import { Toaster } from "@/components/ui/toast";
import { LinkProvider } from "@/lib/navigation";

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter();
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      {children}
      {/* phones have a tab bar at the bottom, so toasts drop from the top */}
      <Toaster mobilePosition="top" />
    </LinkProvider>
  );
}
```

The sidebar and the tab bar share the `NavItem` shape, so one file feeds both:

```tsx
// app/(admin)/nav.tsx
import { House, Settings, ShieldCheck, Users } from "lucide-react";
import type { SidebarNavGroup } from "@/components/ui/sidebar";
import type { NavItem } from "@/lib/navigation";

export const nav: SidebarNavGroup[] = [
  { items: [{ label: "Home", href: "/", icon: <House /> }] },
  { label: "Sales", items: [{ label: "Clients", href: "/clients", icon: <Users />, badge: 3 }] },
  {
    label: "Workspace",
    items: [
      { label: "Team", href: "/team", icon: <ShieldCheck /> },
      { label: "Settings", href: "/settings", icon: <Settings /> },
    ],
  },
];

export const tabs: NavItem[] = [
  { label: "Home", href: "/", icon: <House />, match: "exact" },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Team", href: "/team", icon: <ShieldCheck /> },
  { label: "Settings", href: "/settings", icon: <Settings /> },
];
```

And the layout, a server component:

```tsx
// app/(admin)/layout.tsx
import type { ReactNode } from "react";
import { cookies } from "next/headers";
import { AppShell } from "@/components/ui/app-shell";
import { Sidebar } from "@/components/ui/sidebar";
import { Topbar } from "@/components/ui/topbar";
import { getUser } from "@/server/dal";
import { nav, tabs } from "./nav";

export default async function AdminLayout({ children }: { children: ReactNode }) {
  const [store, user] = await Promise.all([cookies(), getUser()]);
  // the shell writes `${persistKey}-collapsed` ("app-shell" by default) as "true" or "false"
  const collapsed = store.get("app-shell-collapsed")?.value === "true";
  return (
    <AppShell
      defaultCollapsed={collapsed}
      mobileBreakpoint="lg"
      sidebar={<Sidebar groups={nav} filter user={{ name: user.name, email: user.email, avatar: user.avatarUrl }} />}
      topbar={<Topbar title="Northwind" />}
      tabs={tabs}
    >
      {children}
    </AppShell>
  );
}
```

Mod+B (Cmd on a Mac, Ctrl elsewhere) folds the sidebar into a 64px icon rail and stores that in the `app-shell-collapsed` cookie. Without the server read, a user who collapsed it sees it expanded on every first paint and then snap to the rail after hydration. Use the literal cookie name on the server: the `persistedCookieName` helper lives in a hook file that imports client-only React hooks, which a server layout cannot import. Below the breakpoint the sidebar becomes a drawer that closes on navigation, Escape, a tap outside or a swipe back, and focus returns to the menu button. A "Skip to content" link is the first Tab stop.

We pass `mobileBreakpoint="lg"` (1024px) on purpose. At `md` (768px), an 820px tablet in portrait keeps a 256px sidebar and 564px for the page, too little for a table. At `lg` it gets the phone layout and the full width.

Keep the awaits in this layout cheap: a slow `await` here [holds every page behind it](https://nextjs.org/docs/app/guides/authentication#auth-and-streaming). A cookie read and a cached session lookup are fine; a dashboard query is not.

For comparison, the shadcn/ui Sidebar (as of October 2026) [stores its open state](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/sidebar.tsx) in a `sidebar_state` cookie for seven days and renders a Sheet when its `useIsMobile` hook reports a phone. It has no bottom tab bar, so on a phone every destination is two taps away.

For the whole back office layout in one block, the [Admin Shell](https://wingo-ui.com/components/admin-shell) adds a workspace switcher, a global search on `/`, notifications, a command menu on Mod+K and a five-tab bar whose More tab opens the drawer. Our [React command palette guide](https://wingo-ui.com/blog/react-command-palette) covers that menu's shortcuts, nested pages and phone sheet.

#### How do you build the dashboard home with KPIs?

Fetch the numbers in the page for the period in the URL, and pass them to a dashboard block as props. The [Admin Dashboard Page](https://wingo-ui.com/components/admin-dashboard-page) is the home of an orders business (four KPIs, revenue against the previous period, recent orders, what needs attention, team activity); the [KPI Dashboard](https://wingo-ui.com/components/kpi-dashboard) suits a B2B or analytics app.

The page reads the period, defaults to the last 30 days and fetches:

```tsx
// app/(admin)/page.tsx
import { isValid, parseISO, startOfDay, subDays } from "date-fns";
import { getDashboard } from "@/server/dashboard";
import { getUser } from "@/server/dal";
import { DashboardHome } from "./dashboard-home";

function readPeriod(from?: string, to?: string) {
  const today = startOfDay(new Date());
  const end = to ? parseISO(to) : today;
  const start = from ? parseISO(from) : subDays(end, 29);
  return isValid(start) && isValid(end) ? { from: start, to: end } : { from: subDays(today, 29), to: today };
}

export default async function HomePage({ searchParams }: { searchParams: Promise<{ from?: string; to?: string }> }) {
  const { from, to } = await searchParams;
  const period = readPeriod(from, to);
  // { kpis, revenue, orders, tasks, activity, topProducts } for the period
  const [user, data] = await Promise.all([getUser(), getDashboard(period)]);
  return <DashboardHome firstName={user.firstName} period={period} data={data} />;
}
```

The view writes a new period back to the URL and sends order actions to Server Actions:

```tsx
// app/(admin)/dashboard-home.tsx
"use client";

import { useRouter } from "next/navigation";
import { format } from "date-fns";
import { AdminDashboardPage } from "@/components/blocks/admin-dashboard-page";
import type { DashboardData } from "@/components/blocks/admin-dashboard-page-data";
import type { DateRange } from "@/components/ui/date-range-picker";
import { runOrderAction } from "./actions";

type Props = { firstName: string; period: DateRange; data: DashboardData };

export function DashboardHome({ firstName, period, data }: Props) {
  const router = useRouter();
  return (
    <AdminDashboardPage
      {...data}
      userName={firstName}
      defaultPeriod={period}
      onPeriodChange={({ from, to }) => {
        if (!from || !to) return;
        const params = new URLSearchParams({ from: format(from, "yyyy-MM-dd"), to: format(to, "yyyy-MM-dd") });
        router.replace(`/?${params}`, { scroll: false });
      }}
      onOrderAction={async (action, order) => {
        const { error } = await runOrderAction(action, order.id);
        if (error) throw new Error(error);
      }}
    />
  );
}
```

The period is uncontrolled on purpose (`defaultPeriod`): the date field updates the moment someone applies a range, and the panels follow when the server answers. `onOrderAction` is optimistic: the status changes at once, the row shows a spinner while the promise runs, and a rejection rolls it back with an error toast, which is why the handler throws on an error. One catch: after a cancel, the toast's Undo restores the row on screen only and calls none of your code, so the next server render shows the order as cancelled again. Rewrite `labels.cancelDescription` so users know a cancel is final; its default text promises an email and a refund, which only your server can keep.

> Live demo (Admin Dashboard Page): Pick another period in the date field, then click an order in Recent orders to open its sheet. This frame is narrower than 1024px, so you see the phone layout: the sidebar sits behind the menu button and the tab bar holds the bottom edge. Try it at [Admin Dashboard Page](https://wingo-ui.com/components/admin-dashboard-page) and install it with `npx wingo-ui@latest add admin-dashboard-page`.

On a phone the KPIs sit two by two, recent orders become cards with Load more, and the date field and the order details open as bottom sheets you drag down to close.

##### When should you use the KPI Dashboard instead?

When the home is about analytics more than orders: revenue over time, sales by source, a conversion funnel, top salespeople and invoices. It takes one `data` object and hides a widget whose data is missing, so it fits a company with no funnel. It has the controls an analytics page needs: `onRefresh` (a promise spins the button and announces the update), `onExport` with CSV and PDF, a `widgets` list to pick and order panels, and `widgetErrors` with `onWidgetRetry` to show an error and a Try again button inside the one widget whose query failed, so the rest of the page stays up.

Its grid uses container queries: one column, two from 672px and three from 1152px of its own width. Inside a shell that matters, because a 1280px window with a 256px sidebar leaves about 1000px, and viewport breakpoints would lay the grid out for space it does not have. The `DashboardWidget` and `KpiDashboardGrid` parts are exported for your own panels.

##### Can you render KPI cards from a server component?

Yes, as long as every prop is data. The [Stat Card](https://wingo-ui.com/components/stat-card) takes numbers, strings and icons, so a server component can render a row directly:

```tsx
// app/(admin)/reports/page.tsx
import { FileText, Timer, UserPlus, Wallet } from "lucide-react";
import { StatCard, StatGroup } from "@/components/ui/stat-card";
import { getKpis } from "@/server/reports";

export default async function ReportsPage() {
  const k = await getKpis();
  return (
    <StatGroup variant="joined">
      <StatCard label="Revenue" icon={<Wallet />} value={k.revenue} format="currency" delta={k.revenueChange} deltaLabel="vs. last month" sparkline={k.dailyRevenue} goal={k.revenueGoal} locale="en-US" />
      <StatCard label="Invoices issued" icon={<FileText />} value={k.invoices} delta={k.invoicesChange} deltaFormat="number" locale="en-US" />
      <StatCard label="New clients" icon={<UserPlus />} value={k.newClients} delta={k.newClientsChange} locale="en-US" />
      <StatCard label="Time to payment" icon={<Timer />} value={k.secondsToPay} format="duration" delta={k.timeToPayChange} invertTrend locale="en-US" />
    </StatGroup>
  );
}
```

The server HTML holds the final numbers, the count-up runs on the client when a card scrolls into view, and screen readers hear one sentence with the final value and the change. `invertTrend` makes a drop in time to payment green. Two limits: a function prop such as `formatDelta` needs a client file, and `href` renders a plain anchor (a full page load in Next.js), so linked tiles need a client wrapper whose `onClick` calls `event.preventDefault()` and then `router.push`.

#### How do you build list pages with a server-side data table?

Run the [Data Table](https://wingo-ui.com/components/data-table) in server mode, keep its query in the URL, and let the page fetch one page at a time. In `mode="server"` the table does no sorting, filtering or paging itself: `data` is the current page, `rowCount` the total, and every change arrives in `onQueryChange` as one object (`page`, `pageSize`, `sorting`, `globalFilter`, `columnFilters`). One module translates it to and from the search params:

```ts
// app/(admin)/clients/query.ts
import type { DataTableQuery } from "@/components/ui/data-table";

type Params = Record<string, string | string[] | undefined>;
const one = (value: string | string[] | undefined) => (Array.isArray(value) ? value[0] : value) ?? "";

export function readQuery(params: Params): DataTableQuery {
  const [sortId, dir] = one(params.sort).split(".");
  const status = one(params.status);
  const size = Number(one(params.size));
  return {
    page: Math.max(1, Number(one(params.page)) || 1),
    pageSize: [10, 25, 50, 100].includes(size) ? size : 25,
    sorting: sortId ? [{ id: sortId, desc: dir === "desc" }] : [],
    globalFilter: one(params.q),
    columnFilters: status ? [{ id: "status", value: status.split(",") }] : [],
  };
}

export function writeQuery(query: DataTableQuery): string {
  const params = new URLSearchParams();
  if (query.page > 1) params.set("page", String(query.page));
  if (query.pageSize !== 25) params.set("size", String(query.pageSize));
  if (query.globalFilter) params.set("q", query.globalFilter);
  const sort = query.sorting[0];
  if (sort) params.set("sort", `${sort.id}.${sort.desc ? "desc" : "asc"}`);
  const status = query.columnFilters.find((filter) => filter.id === "status")?.value;
  if (Array.isArray(status) && status.length) params.set("status", status.join(","));
  return params.toString();
}
```

The page parses the URL and queries one page:

```tsx
// app/(admin)/clients/page.tsx
import { listClients } from "@/server/clients";
import { ClientsTable } from "./clients-table";
import { readQuery } from "./query";

type Search = Promise<Record<string, string | string[] | undefined>>;

export default async function ClientsPage({ searchParams }: { searchParams: Search }) {
  const query = readQuery(await searchParams);
  // checks the session, whitelists sort ids and filter values before building SQL
  const { rows, total } = await listClients(query);
  return <ClientsTable rows={rows} total={total} initial={query} />;
}
```

The view starts from the URL and writes changes back in a transition, so `isPending` drives the refreshing bar:

```tsx
// app/(admin)/clients/clients-table.tsx
"use client";

import { useTransition } from "react";
import { useRouter } from "next/navigation";
import { DataTable, createColumns, type DataTableQuery } from "@/components/ui/data-table";
import { writeQuery } from "./query";

export type ClientRow = { id: string; name: string; city: string; status: string; balance: number; lastInvoice: string | null };

const STATUSES = ["Active", "Overdue", "Prospect"];

const col = createColumns<ClientRow>();
const columns = col([
  col.accessor("name", { header: "Client", mobile: "title" }),
  col.accessor("city", { header: "City", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" }, Prospect: { tone: "info" } },
    filter: "multi-select",
    // server mode only sees one page, so list every option yourself
    filterOptions: STATUSES.map((status) => ({ value: status, label: status })),
    mobile: "meta",
  }),
  col.accessor("balance", { header: "Balance", type: "currency" }),
  col.accessor("lastInvoice", { header: "Last invoice", type: "relative" }),
]);

type Props = { rows: ClientRow[]; total: number; initial: DataTableQuery; loading?: boolean };

export function ClientsTable({ rows, total, initial, loading }: Props) {
  const router = useRouter();
  const [pending, startTransition] = useTransition();
  return (
    <DataTable
      data={rows}
      columns={columns}
      mode="server"
      rowCount={total}
      defaultPage={initial.page}
      defaultPageSize={initial.pageSize}
      defaultSorting={initial.sorting}
      defaultGlobalFilter={initial.globalFilter}
      defaultColumnFilters={initial.columnFilters}
      onQueryChange={(query) => {
        const search = writeQuery(query);
        startTransition(() => router.replace(search ? `/clients?${search}` : "/clients", { scroll: false }));
      }}
      refreshing={pending}
      loading={loading}
      quickFilters={[{ id: "overdue", label: "Overdue", columnFilter: { id: "status", value: ["Overdue"] } }]}
      onRowClick={(row) => router.push(`/clients/${row.id}`)}
      caption="Clients"
      locale="en-US"
    />
  );
}
```

Details that save debugging time: `onQueryChange` does not fire on the first render (the server already sent that page), the search arrives debounced (300ms), and the page resets to 1 when the search, a filter or the sort changes. The table is uncontrolled (`default*` props), so the search box never lags behind a server round trip. The trade-off: the back button changes the data while the toolbar keeps the last query. If your users live on the back button, control `page`, `sorting`, `globalFilter` and `columnFilters` from the URL instead.

> Live demo (Data Table): Search, sort or click the Overdue chip: in server mode the table hands your code one query object, printed under the pager. Below 768px every row is a card you can long press to select. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

On a phone the columns become cards: `mobile: "title"` is the heading, `subtitle` the line under it, `meta` the badge in the corner. Sorting, filters and the row menu open as bottom sheets, and with `selectionMode` on, a long press starts selection. Server mode keeps a compact pager on phones; client mode uses Load more.

Server mode is not always the right call. When one request can load every row a user may see, client mode filters instantly and needs no query API. We switch to server mode past a few thousand rows, or when permissions decide which rows exist for a user. To build the table yourself on TanStack Table instead, with the same server pagination, follow our [TanStack Table v9 data table tutorial](https://wingo-ui.com/blog/tanstack-table-v9-data-table).

#### How do you build a settings page that never loses input?

Let one block own the drafts, and save through Server Actions that return their errors. The [Settings Page](https://wingo-ui.com/components/settings-page) has six sections (profile, account, notifications, billing, security, danger zone). A text change slides up a save bar with Discard and Save (or Mod+S), switches save on their own, a failed save keeps the draft and shows the message, and leaving a section with unsaved changes asks first.

Next.js recommends [modeling expected errors as return values](https://nextjs.org/docs/app/getting-started/error-handling#handling-expected-errors) in Server Functions, and in production the client does not get the original message of a server error, so a thrown "This workspace address is taken" would arrive as a generic error:

```ts
// app/(admin)/settings/actions.ts
"use server";

import { verifySession } from "@/server/dal";
import { saveSettings } from "@/server/settings";

export type ActionResult = { error?: string };

export async function saveSection(section: string, values: unknown): Promise<ActionResult> {
  const { userId } = await verifySession();
  // validates with zod and returns { error } for anything the user can fix
  return saveSettings(userId, section, values);
}

// savePreference(preference, value) has the same shape. verifyEmailCode(email, code),
// verifyTwoFactorCode(code) and checkWorkspaceAddress(slug) check the session too
// and resolve to a boolean (true: the code is right, the address is free)
```

The view turns a returned error into the rejection the block listens for, and replaces the block's demo checks with real ones:

```tsx
// app/(admin)/settings/settings-view.tsx
"use client";

import { SettingsPage, type SettingsPageProps } from "@/components/blocks/settings-page";
import {
  checkWorkspaceAddress,
  savePreference,
  saveSection,
  verifyEmailCode,
  verifyTwoFactorCode,
  type ActionResult,
} from "./actions";

type Props = Pick<
  SettingsPageProps,
  | "profile"
  | "account"
  | "notifications"
  | "billing"
  | "plans"
  | "sessions"
  | "passwordChangedAt"
  | "defaultTwoFactorEnabled"
  | "twoFactorSecret"
  | "twoFactorUri"
  | "backupCodes"
>;

const LABELS = { codeHint: "Enter the 6-digit code." };

async function check(result: Promise<ActionResult>) {
  const { error } = await result;
  if (error) throw new Error(error);
}

export function SettingsView(props: Props) {
  return (
    <SettingsPage
      {...props}
      onSave={(section, values) => check(saveSection(section, values))}
      onPreferenceChange={(preference, value) => check(savePreference(preference, value))}
      verifyEmailCode={verifyEmailCode}
      verifyTwoFactorCode={verifyTwoFactorCode}
      checkWorkspaceAddress={checkWorkspaceAddress}
      labels={LABELS}
    />
  );
}
```

Pass every data prop from the page: anything you leave out falls back to the block's sample data. The security defaults are demo values on purpose. Without `verifyEmailCode` and `verifyTwoFactorCode`, the code 123456 passes; without `twoFactorSecret`, `twoFactorUri` and `backupCodes`, the setup dialog shows sample ones; and the default `codeHint` label reads "In this demo, the code is 123456." Generate the secret and backup codes on the server for the signed-in user.

The dialogs take handlers with the same promise contract (`onEmailChange`, `onPasswordChange`, `onTwoFactorChange`, `onSessionRevoke`, `onPlanChange`, `onDeleteAccount`). One naming detail: the section ids are internal (`profil`, `cont`, `notificari`, `facturare`, `securitate`, `pericol`), so map them to your own segments if each section gets a URL through `onSectionChange`.

> Live demo (Settings Page): Open Profile, edit the full name and press Save. This demo drops the first save on purpose: the bar shows the error and your edit stays, and the next Save goes through. In a frame this narrow the sections are a list that pushes each one in. Try it at [Settings Page](https://wingo-ui.com/components/settings-page) and install it with `npx wingo-ui@latest add settings-page`.

From 768px the sections are a column on the left (or tabs with `nav="tabs"`). On a phone each section pushes in with a back button and a swipe back, dialogs open as bottom sheets, and the save bar is pinned above the tab bar. The block validates each form before it calls `onSave`: invalid fields turn red and the first one takes focus, the pattern our [React form components guide](https://wingo-ui.com/blog/react-form-components-guide) covers field by field.

#### How do you build the team and roles page?

Treat every control on it as a request the server can refuse. The [Users Admin Page](https://wingo-ui.com/components/users-admin-page) has three tabs: Members (the team and pending invitations against your seats, a role picker per row), Roles and permissions (a matrix with a save bar) and Audit log (a filterable history with CSV export). The server decides who may manage and enforces the rules the interface shows:

```ts
// app/(admin)/team/actions.ts
"use server";

import { requireAdmin } from "@/server/dal";
import { changeMemberRole } from "@/server/team";

export async function changeRole(memberId: string, role: string): Promise<{ error?: string }> {
  const admin = await requireAdmin();
  // refuses to demote the last administrator, the same rule the picker shows
  return changeMemberRole(admin.workspaceId, memberId, role);
}
// invite, removeMember and savePermissions follow the same shape
```

```tsx
// app/(admin)/team/team-view.tsx
"use client";

import { UsersAdminPage, type UsersAdminPageProps } from "@/components/blocks/users-admin-page";
import { changeRole, invite, removeMember, savePermissions } from "./actions";

type Props = Pick<
  UsersAdminPageProps,
  "companyName" | "members" | "invites" | "roles" | "permissionRoles" | "permissionGroups" | "defaultPermissions" | "auditEvents" | "seats" | "canManage"
>;

async function check(result: Promise<{ error?: string }>) {
  const { error } = await result;
  if (error) throw new Error(error);
}

export function TeamView(props: Props) {
  return (
    <UsersAdminPage
      {...props}
      onInvite={(input) => check(invite(input))}
      onRoleChange={(member, role) => check(changeRole(member.id, role))}
      onRemove={(member) => check(removeMember(member.id))}
      onPermissionsSave={(value) => check(savePermissions(value))}
    />
  );
}
```

The page computes `canManage` from the session and passes it with the data. With `canManage={false}` the block turns read-only and says why, which beats hiding the page from people who only need to see who has access.

The interface guards the obvious mistakes: the last administrator cannot be demoted, nobody removes themselves or the owner, and invitations hold a seat. Those guards are for the person clicking; your actions enforce them again, because a Server Action cannot tell which button sent the request. Likewise the block adds this page's changes to the top of the audit log as feedback, but the real audit rows are the ones your server writes in the same transaction.

On a phone, members become cards with the role picker inside, the invite dialog is a bottom sheet, and the matrix shows one role at a time with chips, because five role columns do not fit 390px. The parts also ship alone: [Members Table](https://wingo-ui.com/components/members-table), [Permissions Matrix](https://wingo-ui.com/components/permissions-matrix) and [Audit Log](https://wingo-ui.com/components/audit-log).

#### How do you handle loading and error states in the admin?

Give every route a `loading.tsx` that renders the same component with its `loading` prop, and the group one `error.tsx`. [`loading.js`](https://nextjs.org/docs/app/api-reference/file-conventions/loading) shows its fallback immediately on navigation while the shell stays interactive, and a skeleton in the real layout means nothing jumps when the data arrives:

```tsx
// app/(admin)/clients/loading.tsx
import { ClientsTable } from "./clients-table";
import { readQuery } from "./query";

export default function Loading() {
  return <ClientsTable rows={[]} total={0} initial={readQuery({})} loading />;
}
```

The Data Table draws skeleton rows in its column layout (cards on phones), and the dashboard, settings and team blocks have the same prop. A route without its own `loading.tsx` falls back to the nearest parent's, so one group-level skeleton would flash the same layout before every page.

For errors, Next.js 16.3 made the [`retry` prop of `error.js`](https://nextjs.org/docs/app/api-reference/file-conventions/error) stable; it re-fetches and re-renders the segment:

```tsx
// app/(admin)/error.tsx
"use client";

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

export default function AdminError({ error, retry }: { error: Error & { digest?: string }; retry: () => void }) {
  return (
    <div role="alert" className="mx-auto flex max-w-md flex-col items-center gap-3 px-4 py-16 text-center">
      <h2 className="text-lg font-semibold">This page did not load</h2>
      <p className="text-sm text-muted-foreground">If it keeps failing, send us this reference: {error.digest ?? "none"}</p>
      <Button onClick={retry}>Try again</Button>
    </div>
  );
}
```

Empty states belong in the components: the Data Table's `emptyState` for a list with no rows yet and `noResultsState` when filters match nothing, so "No clients yet" and "Nothing matches" never get mixed up.

#### How do you make every admin screen usable on a phone?

Change behavior as well as layout, and check each screen at 390px on a real phone. People open a back office on phones to approve an expense, check an order or answer a client. The checklist we hold every admin screen to:

- **Navigation:** everything in a drawer behind the menu button, plus a tab bar for the three to five daily destinations; tablets in portrait get the phone layout.
- **One bar on the bottom edge:** the tab bar pads the home indicator and publishes its height as `--bottom-bar-offset`, and the settings and team save bars read it to sit above the tab bar.
- **Numbers:** KPIs two per row, with values that shrink to fit 360px instead of wrapping.
- **Tables:** rows become cards (title, subtitle, badge, up to four fields); nobody should scroll sideways to read one record.
- **Overlays:** menus, filters, date pickers and detail views open as bottom sheets you can drag down; confirmations stay centered.
- **Container queries:** inside a shell, measure the container (as the KPI grid does), so a sidebar never squeezes a layout built for the viewport.
- **Touch:** 44px targets on coarse pointers, no hover-only actions, and every gesture backed by a visible button.

Our [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) covers the bottom sheets, touch targets, safe areas and phone tables in depth, with code, and the [React bottom navigation bar guide](https://wingo-ui.com/blog/react-bottom-navigation-bar) covers the tab bar and when the sidebar alone is enough.

#### Should you start from a Next.js admin template or build it yourself?

Start from a free starter to learn the App Router or when you already use its stack; build from blocks when settings, roles and phone layouts must work on day one. Before you pick a "nextjs admin template" or a "shadcn admin dashboard", compare these free starting points with the blocks in this guide (as of October 2026):

| Option | Price and license | What you get | What is left to you |
| --- | --- | --- | --- |
| [Next.js Learn dashboard course](https://nextjs.org/learn/dashboard-app) | Free | A financial dashboard with Postgres, Server Actions, search and pagination in the URL, NextAuth.js and Proxy; its invoices table turns into cards on phones | Settings, team and roles; it teaches the patterns and leaves the screens to you |
| [shadcn/ui dashboard-01 block](https://ui.shadcn.com/blocks) | Free, [MIT](https://github.com/shadcn-ui/ui) | Inset sidebar, summary cards, an interactive area chart and a TanStack data table (`npx shadcn add dashboard-01`) | Settings, team pages, auth; the table keeps its rows on a phone and scrolls sideways |
| [next-shadcn-dashboard-starter](https://github.com/Kiranism/next-shadcn-dashboard-starter) | Free, MIT | Next.js 16, shadcn/ui on Base UI, Clerk auth, product and user tables with URL state, team, billing and profile pages | Team, roles and billing come from Clerk's prebuilt components, so they need Clerk |
| Wingo UI blocks (this guide) | Pro: $8 a month, $80 a year or $150 lifetime | App Shell, Admin Shell, the two dashboards, Data Table, Settings Page and Users Admin Page, all with phone layouts | Your data layer and auth; the blocks are UI only |

Where the free options win: to learn, take the Next.js course, which teaches the data and auth side this guide skips. If you run shadcn/ui and need a dashboard tonight, dashboard-01 is one command and you own the code, which makes it the shortest path if you searched for "nextjs admin dashboard shadcn"; for desk-only internal tools a sideways-scrolling table is acceptable. If you already use Clerk, the Kiranism starter wires organizations, team management and billing through Clerk's prebuilt components. Wingo UI earns its price when phone users matter and you do not want to build the settings, team and table behaviors yourself. For libraries in general, our [shadcn alternatives comparison](https://wingo-ui.com/blog/shadcn-alternatives) covers fourteen with dated prices.

#### What should you build first?

Build the shell first, then one list page, then the home. The shell sets the navigation and phone layout every screen inherits, a list page exercises the server path (URL, query, Server Actions) that settings and team reuse, and the home is easiest once real data exists.

The admin blocks in this guide are part of [Wingo UI Pro](https://wingo-ui.com/pricing). With it, start with `npx wingo-ui@latest add app-shell` (it brings the Sidebar, Topbar, Bottom Tab Bar and the hooks along) and drop it into `app/(admin)/layout.tsx` as above. The free basics they build on, such as the Button, Card, Badge, Dialog and Toast, install without an account. For back offices that bill Romanian customers, two tutorials go deeper: [e-Factura VAT calculation](https://wingo-ui.com/blog/e-factura-vat-calculation-javascript) computes VAT per rate the way ANAF validates it, with an editable invoice, and the [Romanian address format](https://wingo-ui.com/blog/romanian-address-format-react-form) guide builds a delivery address form with county, locality and postal code checks. More screen-by-screen tutorials live in [Build it: screens and apps](https://wingo-ui.com/blog/category/build).

#### Components in this post

- [App Shell](https://wingo-ui.com/components/app-shell) (Pro): The whole admin layout in one component: a collapsible, resizable sidebar, a top bar and the page; a drawer and a tab bar on phones. Install: `npx wingo-ui@latest add app-shell`
- [Admin Dashboard Page](https://wingo-ui.com/components/admin-dashboard-page) (Pro): The home of a back office: greeting and period, four KPIs, revenue against the previous period, recent orders, alerts and team activity. Install: `npx wingo-ui@latest add admin-dashboard-page`
- [KPI Dashboard](https://wingo-ui.com/components/kpi-dashboard) (Pro): The first screen of a back office: KPI tiles with deltas, revenue against the last period, sources, funnel, top sellers, invoices, activity. Install: `npx wingo-ui@latest add kpi-dashboard`
- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`
- [Sidebar](https://wingo-ui.com/components/sidebar) (Pro): The admin sidebar: grouped links with icons, nested sections, badges, a sliding active pill, an icon rail with flyouts and a filter. Install: `npx wingo-ui@latest add sidebar`
- [Stat Card](https://wingo-ui.com/components/stat-card) (Pro): The KPI tile of a dashboard: a label, a big number that counts up, a delta pill that knows good from bad, a sparkline and a goal bar. Install: `npx wingo-ui@latest add stat-card`
- [Settings Page](https://wingo-ui.com/components/settings-page) (Pro): The account settings of a back office: profile, account, notifications, billing, security and a danger zone, with a save bar. Install: `npx wingo-ui@latest add settings-page`
- [Users Admin Page](https://wingo-ui.com/components/users-admin-page) (Pro): The team page of a back office: members and invitations with seats, roles with a permissions matrix and a save bar, and the audit log. Install: `npx wingo-ui@latest add users-admin-page`

#### FAQ

##### How should I structure a Next.js App Router project for an admin dashboard?

Put every admin route in a route group such as app/(admin) whose layout renders the shell, and keep sign-in in a separate group without it. Pages are server components that fetch through a server-only data access layer, and each route gets its own loading.tsx.

##### Is there a free shadcn admin dashboard for Next.js?

Yes. As of October 2026 shadcn/ui ships a free dashboard-01 block (npx shadcn add dashboard-01) with a sidebar, summary cards, a chart and a data table, but settings, roles and a phone layout for the table are left to you. The MIT next-shadcn-dashboard-starter adds Clerk auth, product and user tables, and team, billing and profile pages built on Clerk's prebuilt components.

##### Should an admin data table filter on the server or in the browser?

Filter in the browser when one request can load every row the user may see; it is instant and needs no query API. Filter on the server when the data grows past a few thousand rows or permissions decide which rows a user sees, and keep the page, sort, search and filters in the URL.

##### Where do auth checks go in a Next.js admin dashboard?

In a server-only data access layer that every page and every Server Action calls. A check in the layout or in proxy.ts alone is too weak: layouts do not re-render on client navigation, and Server Actions can be called with a direct POST request.

##### How do I make an admin dashboard usable on a phone?

Move the sidebar into a drawer with a bottom tab bar, show KPIs two per row, turn table rows into cards, open menus and detail views as bottom sheets, and keep a single bar on the bottom edge above the safe area. Test at 390px on a real phone, because a narrowed desktop window has no touch and no on-screen keyboard.

##### Which Wingo UI admin components are free?

None of the admin blocks in this guide: the App Shell, Sidebar, Data Table, Stat Card, KPI Dashboard, Admin Dashboard Page, Settings Page and Users Admin Page are Pro. The free basics, such as Button, Card, Badge, Dialog, Select, Tabs and Toast, install with the CLI without an account.

---

Source: https://wingo-ui.com/blog/nextjs-admin-dashboard-tutorial

### React 19 forwardRef Migration: ref as a Prop in TypeScript

> React 19 forwardRef migration in TypeScript: take ref as a regular prop, type it with ComponentProps, merge refs with cleanups and keep asChild working.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Next.js and Tailwind CSS](https://wingo-ui.com/blog/category/nextjs-tailwind)
- Reading time: 9 min
- Canonical: https://wingo-ui.com/blog/react-19-forwardref-ref-as-prop

#### TL;DR

In React 19, function components receive ref as a regular prop, so you delete forwardRef, read ref from props (or let it travel in ...props) and type it with ComponentProps or Ref<HTMLInputElement>. forwardRef still works in React 19.3 and logs no warning, but React plans to deprecate it, and a library that supports React 18 has to keep it. The parts that need care are merged refs, which should pass on cleanup functions, and asChild, where the ref belongs on the child element.

Your components are full of `forwardRef` wrappers, `displayName` lines and `ComponentPropsWithoutRef` types, and React 19 says you no longer need them. The React 19 forwardRef change is small on paper: function components now receive `ref` as a regular prop. The work is at the edges. Props types that strip the ref, components that need the DOM node themselves, and `asChild` wrappers that hand the ref to a child all behave a little differently once the wrapper is gone. This tutorial migrates an input and a button, checked against React 19.3 and TypeScript 5.9, and shows the patterns we use in Wingo UI, whose source does not call `forwardRef` once.

#### What changed about forwardRef in React 19?

Function components get `ref` in their props, so the wrapper has nothing left to do. The [React 19 release post](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop) says new function components "will no longer need `forwardRef`" and that React will "deprecate and remove `forwardRef`" in future versions. The [forwardRef reference](https://react.dev/reference/react/forwardRef) says the same: no longer necessary, deprecated in a future release.

So the React 19 forwardRef replacement is the `ref` prop itself. Four facts decide how you migrate:

- **forwardRef still works and stays quiet.** We searched the development builds of `react` and `react-dom` 19.3.0 for a deprecation message and found none. Old components keep running while you migrate.
- **Class components did not change.** A ref passed to a class still points to the instance and never shows up in its props.
- **`element.ref` is on its way out.** React 19 still fills it, but reading it in development logs "Accessing element.ref was removed in React 19. ref is now a regular prop." Read `element.props.ref` instead.
- **React 18 strips `ref` from props.** A library that still lists React 18 as a peer dependency has to keep `forwardRef`. Radix does: `@radix-ui/react-slot` 1.3.3 wraps its `Slot` in `React.forwardRef` and accepts React 16.8 through 19. Wingo UI [requires React 19](https://wingo-ui.com/docs/installation), so its components take `ref` as a plain prop.

#### How do you migrate a component from forwardRef to ref as a prop?

Delete the wrapper, type the props with `ComponentProps`, and let the ref travel in `...props`. Here is the classic shadcn-style input before:

```tsx
// components/ui/input.tsx (React 18)
import * as React from "react";
import { cn } from "@/lib/utils";

const Input = React.forwardRef<HTMLInputElement, React.ComponentPropsWithoutRef<"input">>(
  ({ className, type = "text", ...props }, ref) => (
    <input ref={ref} type={type} className={cn("h-10 w-full rounded-[10px] px-3", className)} {...props} />
  ),
);
Input.displayName = "Input";

export { Input };
```

And after:

```tsx
// components/ui/input.tsx (React 19)
import type { ComponentProps } from "react";
import { cn } from "@/lib/utils";

export function Input({ className, type = "text", ...props }: ComponentProps<"input">) {
  return (
    <input
      data-slot="input"
      type={type}
      className={cn("h-10 w-full rounded-[10px] px-3", className)}
      {...props}
    />
  );
}
```

`ComponentProps<"input">` already contains `ref?: Ref<HTMLInputElement>`, so the spread hands it to the `<input>` and `<Input ref={inputRef} />` works without one ref-specific line. A named function gives React DevTools its name, so `displayName` goes too.

For a whole folder, start with the official codemod from [reactjs/react-codemod](https://github.com/reactjs/react-codemod#remove-forward-ref), on a clean branch so you can read the diff:

```bash
npx codemod react/19/remove-forward-ref --target components/ui
```

shadcn/ui made the same move when it switched to React 19. The [shadcn Tailwind v4 guide](https://ui.shadcn.com/docs/tailwind-v4) lists the manual steps: replace `React.forwardRef<...>` with `React.ComponentProps<...>`, remove `ref={ref}`, add a `data-slot` attribute, convert to a named function and drop `displayName`. Their current Button types its props as `React.ComponentProps<"button">` plus its variants and `asChild`. If your project still has the older shadcn forwardRef components with local edits, [updating shadcn components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits) covers the merge.

To keep `forwardRef` from coming back, add a lint rule. As of October 2026, [eslint-react's no-forward-ref](https://eslint-react.xyz/docs/rules/no-forward-ref) is in its recommended presets, and [Biome's noReactForwardRef](https://biomejs.dev/linter/rules/no-react-forward-ref/) (since Biome 2.2.5) is opt-in with an unsafe fix. Leave them off in packages that still support React 18.

#### How do you type ref as a prop in React 19 with TypeScript?

Most of the time you type nothing, because `ComponentProps<"button">` includes `ref`. You add `ref?: Ref<HTMLButtonElement>` only when you write the props type yourself. The other type changes are deletions and renames:

| React 18 pattern | React 19 replacement |
|---|---|
| `forwardRef<HTMLInputElement, Props>(...)` | `ref?: Ref<HTMLInputElement>` in `Props`, or `ComponentProps<"input">` |
| `ComponentPropsWithoutRef<"input">` for a wrapper | `ComponentProps<"input">` (the old type strips the ref you now pass on) |
| `ComponentPropsWithoutRef<typeof Root>` plus `ElementRef<typeof Root>` | `ComponentProps<typeof Root>`, and `ComponentRef<typeof Root>` when you need the node type (`ElementRef` is deprecated) |
| `child.ref` on a React element | `child.props.ref` |
| `useRef<HTMLInputElement>()` | `useRef<HTMLInputElement>(null)` (an argument is now required) |
| `ref={(node) => (el = node)}` | `ref={(node) => { el = node; }}` (a returned value now reads as a cleanup) |

The last row trips people up the day they upgrade `@types/react`. Ref callbacks may return a cleanup function now, so an arrow function that implicitly returns the node fails with `Type 'HTMLDivElement | null' is not assignable to type 'void | (() => VoidOrUndefinedOnly)'`. Add braces and it compiles.

When the props are your own, declare the ref like any other prop:

```tsx
import type { ReactNode, Ref } from "react";

type IconButtonProps = {
  label: string;
  icon: ReactNode;
  onPress?: () => void;
  ref?: Ref<HTMLButtonElement>;
};

export function IconButton({ label, icon, onPress, ref }: IconButtonProps) {
  return (
    <button ref={ref} type="button" aria-label={label} onClick={onPress}>
      {icon}
    </button>
  );
}
```

##### Generic components get their type parameter back

Generic components gain the most from ref as a prop in React 19. `forwardRef` returns a component that is not generic, so a typed list needed a cast to get its `<T>` back:

```tsx
// React 18: forwardRef drops <T>, so the signature is cast back on
export const List = forwardRef(ListInner) as <T>(
  props: ListProps<T> & { ref?: Ref<HTMLUListElement> },
) => ReturnType<typeof ListInner>;
```

Now it is a plain generic function, and `T` is inferred at the call site with the ref still typed:

```tsx
import type { ComponentProps, ReactNode } from "react";

type ListProps<T> = Omit<ComponentProps<"ul">, "children"> & {
  items: T[];
  getKey: (item: T) => string;
  renderItem: (item: T) => ReactNode;
};

export function List<T>({ items, getKey, renderItem, ...props }: ListProps<T>) {
  return (
    <ul {...props}>
      {items.map((item) => (
        <li key={getKey(item)}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

// <List ref={listRef} items={customers} getKey={(c) => c.id} renderItem={(c) => c.name} />
```

##### Wrapper layers pass the ref without extra code

In our [Button](https://wingo-ui.com/components/button) the ref never appears by name. `ButtonProps` is `Omit<ComponentProps<"button">, "color" | ...>` plus our props. The component reads them through `useDefaults("button", buttonProps)`, which layers app-wide defaults from [UIProvider](https://wingo-ui.com/components/ui-config) under the props passed in, and spreads the rest onto `motion.button`. With `forwardRef` the ref would arrive as a second argument, and every layer between the caller and the element would need its own way to carry it. As a prop, it is one more key.

#### How do you merge refs in React 19?

Merge the two refs in a memoized callback ref that returns a cleanup. You need this when the component uses the DOM node itself and the caller wants it too. Our [Input](https://wingo-ui.com/components/input) is the real case. It needs the node to clear the text with a real input event, put focus back after clearing and hear form resets, and your code needs the same node to focus the field after a failed submit. This is the pattern from `components/ui/input.tsx`, trimmed to a search field:

```tsx
"use client";

import { useCallback, useRef, type ComponentProps, type Ref } from "react";

// hands the node to the caller's ref and returns the matching cleanup
function attachRef<T>(ref: Ref<T> | undefined, node: T) {
  if (typeof ref === "function") {
    const cleanup = ref(node);
    return () => (typeof cleanup === "function" ? cleanup() : ref(null));
  }
  if (ref) {
    const object = ref;
    object.current = node;
    return () => {
      object.current = null;
    };
  }
  return undefined;
}

// writes through the prototype setter so React sees the change, then fires the event onChange listens to
function clearValue(input: HTMLInputElement) {
  Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(input, "");
  input.dispatchEvent(new Event("input", { bubbles: true }));
}

export function SearchField({ ref, ...props }: ComponentProps<"input">) {
  const inputRef = useRef<HTMLInputElement | null>(null);

  const setRef = useCallback(
    (node: HTMLInputElement | null) => {
      inputRef.current = node;
      const detach = attachRef(ref, node);
      return () => {
        inputRef.current = null;
        detach?.();
      };
    },
    [ref],
  );

  return (
    <div className="flex items-center gap-2">
      <input ref={setRef} type="search" {...props} />
      <button
        type="button"
        onClick={() => {
          if (!inputRef.current) return;
          clearValue(inputRef.current);
          inputRef.current.focus();
        }}
      >
        Clear
      </button>
    </div>
  );
}
```

Three details matter:

- **Cleanups.** When the node goes away, React 19 calls the cleanup a ref callback returned, instead of calling the callback again with `null`. So `attachRef` runs the caller's cleanup if they returned one and falls back to `ref(null)` if they did not.
- **A stable callback.** `useCallback` keeps `setRef` the same between renders. A new callback ref on every render makes React detach and reattach it each time. In a StrictMode test, an inline ref callback logged its cleanup and a fresh attach after a plain re-render, while the memoized one stayed attached.
- **A clear React can hear.** `clearValue` goes through the native value setter and fires an `input` event, so the caller's `onChange` runs with an empty value, like after a keystroke. Assigning `input.value = ""` empties the field without telling React or a form library.

[Textarea](https://wingo-ui.com/components/textarea) merges refs the same way, so it can measure its own node and grow with its content.

Using it from the outside is a normal ref:

```tsx
"use client";

import { useRef } from "react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";

export function SignupForm() {
  const emailRef = useRef<HTMLInputElement>(null);

  return (
    <form
      noValidate
      onSubmit={(event) => {
        event.preventDefault();
        const email = emailRef.current?.value.trim() ?? "";
        if (!email.includes("@")) emailRef.current?.focus();
      }}
      className="flex flex-col gap-3"
    >
      <Input ref={emailRef} type="email" label="Email" placeholder="emma.carter@example.com" clearable />
      <Button type="submit">Create account</Button>
    </form>
  );
}
```

React Hook Form's `register` passes a ref the same way, so `{...register("email")}` reaches the `<input>` with no adapter. The [React form components guide](https://wingo-ui.com/blog/react-form-components-guide) covers which fields need `Controller` instead.

> Live demo (Input): Press Continue with a short title: the demo's own ref moves focus back to the field. Then type and press Escape or tap the clear button: the Input's internal ref empties it and keeps focus. Try it at [Input](https://wingo-ui.com/components/input) and install it with `npx wingo-ui@latest add input`.

When you expose methods instead of a node, `useImperativeHandle(ref, ...)` works exactly as before, with `ref` from props. Our Pro [Schema Builder](https://wingo-ui.com/components/schema-builder) hands out `validate()` and `getJsonSchema()` that way; see [pricing](https://wingo-ui.com/pricing) for what Pro includes.

#### How does ref as a prop work with asChild and Slot?

Spread the props, ref included, onto `Slot`, and put the ref on the child when you need the child's type. Radix `Slot` composes the ref it receives with the child's own ref. In React 19 it reads the child's ref from `element.props.ref`, so neither one is lost and no warning fires.

The trap is TypeScript. A button component types its ref for `<button>`, so passing a link ref to the wrapper fails:

```tsx
import Link from "next/link";
import { useRef } from "react";
import { Button } from "@/components/ui/button";

export function UpgradeLink() {
  const linkRef = useRef<HTMLAnchorElement>(null);

  // error: Type 'RefObject<HTMLAnchorElement | null>' is not assignable to type 'Ref<HTMLButtonElement> | undefined'
  return (
    <Button asChild ref={linkRef}>
      <Link href="/pricing">See plans</Link>
    </Button>
  );
}
```

Put the ref on the child. Slot merges it with its own, and the type is right:

```tsx
"use client";

import Link from "next/link";
import { useEffect, useRef } from "react";
import { Button } from "@/components/ui/button";

export function UpgradeLink({ highlight }: { highlight: boolean }) {
  const linkRef = useRef<HTMLAnchorElement>(null);

  useEffect(() => {
    if (highlight) linkRef.current?.focus();
  }, [highlight]);

  return (
    <Button asChild variant="outline">
      <Link ref={linkRef} href="/pricing">
        See plans
      </Link>
    </Button>
  );
}
```

Our Button renders `asChild` through `motion.create(Slot)`, so two refs want the same node: motion's, for the press spring, and yours. Slot composes both. We mounted this Button in Chromium under StrictMode with a plain anchor as the child: the child's ref received the `<a>`, and the console stayed empty.

> Live demo (Button): This Button has asChild on, so it renders a link: press it for the same spring dip, and Tab to it for the same focus ring. Try it at [Button](https://wingo-ui.com/components/button) and install it with `npx wingo-ui@latest add button`.

Two more things break `asChild` after a migration:

- **A child component that drops the ref.** Slot passes `ref`, `className` and event handlers to the child, and a component that does not spread its props loses all three. Radix tooltips and popovers find their trigger through that ref, so the content has no element to position against.
- **A homemade Slot that reads `child.ref`.** It still works at runtime, but logs the `element.ref` error in development, and `@types/react` 19 no longer declares `ref` on `ReactElement`, so TypeScript rejects it too. Read it from props, with a type argument because element props default to `unknown` in React 19:

```tsx
import { isValidElement, type ReactNode, type Ref } from "react";

type WithRef = { ref?: Ref<HTMLElement> };

// React 18 code read children.ref, which logs an error in React 19 development builds
export function getChildRef(children: ReactNode) {
  return isValidElement<WithRef>(children) ? children.props.ref : undefined;
}
```

#### What should you try next?

Install the two free components from this post and read how they handle refs in your own project:

```bash
npx wingo-ui@latest add button input
```

Both land in `components/ui` as source you own, along with the field, spinner and helpers they import, and none of those files use `forwardRef`. For the other half of the stack they target, browse the [Next.js and Tailwind CSS guides](https://wingo-ui.com/blog/category/nextjs-tailwind), starting with [Tailwind v4 design tokens](https://wingo-ui.com/blog/tailwind-v4-design-tokens).

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`

#### FAQ

##### Is forwardRef deprecated in React 19?

Not formally. The React docs say forwardRef is no longer necessary in React 19 and will be deprecated in a future release. As of React 19.3 it still works and logs no warning, but new function components should take ref as a prop.

##### How do I type the ref prop in React 19 with TypeScript?

When you wrap one element, use `ComponentProps<'button'>`, which already includes ref. When you write the props type yourself, add `ref?: Ref<HTMLButtonElement>`. Stop using `ComponentPropsWithoutRef` for wrappers, and replace `ElementRef` with `ComponentRef`.

##### Do I still need forwardRef if my library supports React 18?

Yes. React 18 removes ref from props before your component runs, so only forwardRef gives you the ref there. Keep it until React 18 leaves your peer dependencies; forwardRef components still work in React 19.

##### Does asChild still work without forwardRef?

Yes. Radix Slot reads the child's ref from its props in React 19 and composes it with the ref the Slot receives. Put the ref on the child when you want its real type, such as HTMLAnchorElement for a link rendered through a button component.

##### Is there a codemod to remove forwardRef?

Yes. The reactjs/react-codemod project ships remove-forward-ref: run `npx codemod react/19/remove-forward-ref --target components/ui` on a clean branch, then review the diff, especially generic components and props types that still use `ComponentPropsWithoutRef`.

##### Do class components get ref as a prop in React 19?

No. A ref passed to a class component still points to the component instance and is not passed in its props.

---

Source: https://wingo-ui.com/blog/react-19-forwardref-ref-as-prop

### React AI Chat UI: Streaming, Auto-Scroll and Mobile

> How a production React AI chat UI handles streaming, auto-scroll, IME input and the phone keyboard, part by part, with code for the Next.js App Router.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents)
- Reading time: 10 min
- Canonical: https://wingo-ui.com/blog/react-ai-chat-ui

#### TL;DR

A production React AI chat UI has five parts that share one message type: a thread, the messages, a composer, a reasoning row and a model picker. The work is in their behavior: follow the stream only while the reader is at the bottom, re-render only the message that changed, repair half-written markdown, ignore Enter during IME composition and keep the composer above the phone keyboard. Stream each delta into a new object for that one message, and abort with an AbortSignal so Stop keeps the partial answer.

A React AI chat UI looks finished after an afternoon: a list of bubbles, a textarea and a fetch that streams text. Real use finds the gaps. The thread drags the reader back down while they reread an earlier answer, a half-written code fence turns the rest of the reply into code, someone typing with a Japanese IME sends half a sentence with Enter, and on an iPhone the composer slides behind the keyboard. This guide covers the five parts of a production chat, what each must handle, and the code that connects them to your model. The examples use the AI components of Wingo UI, the library we build, so we are not neutral; outside facts link to their sources.

#### What are the parts of a React AI chat UI?

Five parts that share one message type. Each React AI chat UI component owns one job, and each has a failure that shows up first:

| Part | Job | What breaks first | Wingo UI component |
|---|---|---|---|
| Thread | scrolls the conversation, pins the composer | following the stream while the reader scrolls up | [Chat Thread](https://wingo-ui.com/components/chat-thread) |
| Message | one turn: markdown, files, sources, actions | every message re-rendering on every token | [Chat Message](https://wingo-ui.com/components/chat-message) |
| Composer | text, files, tools, send and stop | Enter during IME composition, the phone keyboard | [Prompt Input](https://wingo-ui.com/components/prompt-input) |
| Reasoning | the model's thinking, folded away | a wall of thought pushing the answer off screen | [Reasoning Indicator](https://wingo-ui.com/components/reasoning-indicator) |
| Model picker | switching models | a cramped popover on a phone | [Model Picker](https://wingo-ui.com/components/model-picker) |

The shared type is `ChatMessageData` from `lib/ai-chat`: an `id`, a `role`, `content` as markdown and a `status` of `pending`, `streaming`, `complete`, `stopped` or `error`, plus optional `reasoning`, `toolCalls`, `attachments` and `sources`. The status drives most of the screen: typing dots, the caret, the actions and what a screen reader hears.

```bash
npx wingo-ui@latest add chat-thread prompt-input
```

The CLI pulls in Chat Message, Reasoning Indicator, Model Picker and Markdown as dependencies. Coding agents can install the same items through our MCP server; the [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide) shows the setup.

#### How should a chat thread scroll while a reply streams?

Follow new text only while the reader sits at the bottom, let go the moment they scroll up, and come back when they send or tap a jump button. The shadcn [Message Scroller docs](https://ui.shadcn.com/docs/components/radix/message-scroller) state the rule: "If they scroll away, leave them there."

What makes it hold up:

- **Read intent before position.** At the very bottom, a wheel turn upward has not moved `scrollTop` yet when the next chunk lands. The thread's [useStickToBottom](https://wingo-ui.com/components/use-stick-to-bottom) hook lets go on the wheel event itself, so a streaming answer never pulls the reader back.
- **Follow outside React.** Following writes `scrollTop` in a `requestAnimationFrame` loop that re-reads the target every frame. React state changes only when "at the bottom" or "following" flips.
- **Sending returns to the bottom**, even after the reader scrolled up.
- **Loading history keeps the eye in place.** Before a prepend, the thread records the first visible message and its offset, and restores it afterward.
- **The jump pill counts.** While scrolled up, a pill above the composer shows how many replies arrived. Tapping it glides down and moves focus to the newest message.

> Live demo (Chat Thread): Pick a follow-up or type a question, then scroll up while the answer streams: the thread lets go at once and a pill counts the new reply. Tap the pill to glide back down. Try it at [Chat Thread](https://wingo-ui.com/components/chat-thread) and install it with `npx wingo-ui@latest add chat-thread`.

The whole loop against your own route:

```tsx
"use client";

import { useRef, useState } from "react";
import { ChatThread, type ChatMessageData } from "@/components/ui/chat-thread";
import { PromptInput, type PromptInputMessage } from "@/components/ui/prompt-input";
import { createChatId } from "@/lib/ai-chat";

export function Assistant() {
  const [messages, setMessages] = useState<ChatMessageData[]>([]);
  const [streaming, setStreaming] = useState(false);
  const abort = useRef<AbortController | null>(null);

  const patch = (id: string, change: Partial<ChatMessageData>) =>
    setMessages((list) => list.map((m) => (m.id === id ? { ...m, ...change } : m)));

  async function send({ text }: PromptInputMessage) {
    const question: ChatMessageData = { id: createChatId("u"), role: "user", content: text, createdAt: Date.now() };
    const history = [...messages, question].map(({ role, content }) => ({ role, content }));
    const id = createChatId("a");
    setMessages((list) => [...list, question, { id, role: "assistant", content: "", status: "pending", createdAt: Date.now() }]);
    const controller = new AbortController();
    abort.current = controller;
    setStreaming(true);
    let content = "";
    try {
      const response = await fetch("/api/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ messages: history }),
        signal: controller.signal,
      });
      if (!response.ok || !response.body) throw new Error("The assistant is unavailable.");
      const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
      while (true) {
        const { value, done } = await reader.read();
        if (done) break;
        content += value;
        patch(id, { content, status: "streaming" });
      }
      patch(id, { status: "complete" });
    } catch {
      patch(id, { status: controller.signal.aborted ? "stopped" : "error" });
    } finally {
      setStreaming(false);
    }
  }

  return (
    <div className="h-dvh">
      <ChatThread
        messages={messages}
        composer={
          <PromptInput
            status={streaming ? "streaming" : "idle"}
            onSubmit={send}
            onStop={() => abort.current?.abort()}
            stopShortcut="escape"
          />
        }
      />
    </div>
  );
}
```

`/api/chat` is your route handler. It only has to return the answer as a plain text stream; with the AI SDK, [`streamText(...).toTextStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) returns one. The pending message shows typing dots until the first chunk, and Stop keeps the text that already arrived.

#### How do you stream tokens without re-rendering every message?

Give only the changed message a new object, memoize the message component, and render markdown block by block so each chunk re-parses only the last block.

- **Memoized messages.** Chat Message is wrapped in `memo`, and Chat Thread binds each message's handlers through a ref, so a finished message renders again only when its own object changes. Keep `messageProps` a module constant or wrap it in `useMemo`, so its labels and class names keep their identity between chunks.
- **Markdown repair.** The [Markdown](https://wingo-ui.com/components/markdown) renderer splits the answer into top-level blocks. While it streams, it repairs the tail before parsing: it closes an open code fence and unmatched `**`, `~~` or backticks, drops a half-typed link target and holds a table back until its separator row arrives. Without that, a reply flips between raw and formatted text on every chunk. If you stay on react-markdown, [Streamdown](https://github.com/vercel/streamdown) calls itself a drop-in replacement built for AI streaming, and its [unterminated block parsing](https://streamdown.ai/docs/termination) closes open bold, inline code and links.
- **One announcement per reply.** The thread is never a live region, because a screen reader that reads every streamed word is unusable. A separate polite status region says when a reply starts and when it is ready, and the streaming message carries `aria-busy`.

#### What does the composer need to handle?

Enter sends and Shift+Enter adds a line on a hardware keyboard, Enter never sends while an IME is composing, touch keyboards get new lines, and the send button turns into Stop while the answer streams.

IME first, because it fails for whole languages. Japanese, Chinese and Korean input methods use Enter to confirm a conversion. MDN's [keydown reference](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event) notes that `isComposing` can be false on the keydown that closes the IME while `keyCode` is still 229, so the guard checks both. This is the first line of Prompt Input's key handler:

```tsx
if (event.nativeEvent.isComposing || event.key === "Process" || event.keyCode === 229) return;
```

The rest:

- **Touch keyboards.** They have no Shift+Enter, so plain Enter inserts a new line on a phone and the round button sends without closing the keyboard. The text is 16px on phones, so iOS Safari does not zoom into the field.
- **Failed sends.** The box clears the moment you send. If `onSubmit` returns a promise that rejects, the text and files come back unless the person has typed again.
- **Stop.** With `status="streaming"` the button becomes Stop, and `stopShortcut="escape"` works while focus is in the composer, so a page dialog keeps its own Escape.
- **The keyboard covering the box.** Since Chrome 108, Chrome on Android resizes only the visual viewport when the keyboard opens, matching Safari on iOS ([Chrome's announcement](https://developer.chrome.com/blog/viewport-resize-behavior)). A composer fixed to the bottom ends up behind it. With `position="fixed"`, Prompt Input reads `visualViewport` and lifts itself by the covered height through a motion value, without re-rendering. Inside Chat Thread you do not need it; the thread pins the composer with safe-area padding. Background: [100vh on mobile](https://wingo-ui.com/blog/100vh-mobile-dvh-tailwind) and [Tailwind safe area insets](https://wingo-ui.com/blog/tailwind-safe-area-insets).

#### How should reasoning appear in an AI chat?

Folded. While the model thinks, show a shimmering label, a live timer and the last two lines of the thought. When it is done, settle on "Thought for 12 sec" that opens on a tap. Reasoning can run longer than the answer, and nobody should scroll past it to find the reply.

Put `reasoning: { content, status, startedAt, endedAt }` on the message, or use Reasoning Indicator on its own with `content`, `streaming` and `startedAt`. With `autoCollapse` (on by default), a row that was open when thinking started closes when it ends, while a row the person opened stays open. On a phone the open body stops at 40% of the screen height and the row keeps a 44px hit area.

> Live demo (Reasoning Indicator): Watch the label shimmer while the timer counts and the last lines of the thought slide up. When it settles, tap the row to read the full reasoning. Try it at [Reasoning Indicator](https://wingo-ui.com/components/reasoning-indicator) and install it with `npx wingo-ui@latest add reasoning-indicator`.

Chat Message folds tool calls the same way, into a one-line summary that expands.

#### Where does the model picker go on a phone?

Inside the composer, opening as a bottom sheet. On a 390px screen, a 320px popover anchored to a small toolbar button leaves little room for names and descriptions. Below 768px, Model Picker switches to a sheet with 64px rows and two-line descriptions (`responsive`, on by default). Pass `models` to Prompt Input and the picker joins its toolbar:

```tsx
// app/assistant/models.ts
import type { AiModel } from "@/components/ui/model-picker";

export const MODELS: AiModel[] = [
  { id: "standard", name: "Northwind Standard", description: "Balanced, for everyday work", recommended: true },
  { id: "pro", name: "Northwind Pro", description: "Deep reasoning for reports", disabled: true, disabledReason: "Available on the Business plan" },
];
```

With `<PromptInput models={MODELS} defaultModel="standard" />`, `onSubmit` receives the chosen id as `message.model`. Locked models stay in the list, dimmed, with `disabledReason` in place of their description, so people see what a higher plan adds instead of wondering where a model went. Above 8 models a search row appears, and `modelPickerProps={{ shortcut: "mod+." }}` toggles the list from anywhere, text fields included.

#### How do you wire a full AI chat page to your model?

Use the [AI Chat Page](https://wingo-ui.com/components/ai-chat-page) block and pass `onSend`: an async generator that yields text deltas, with a `signal` that aborts on Stop, on a conversation switch and on unmount. Stop keeps what arrived and marks the message as stopped.

```tsx
// app/assistant/page.tsx
"use client";

import { AiChatPage, type AiChatSendHandler } from "@/components/blocks/ai-chat-page";
import { MODELS } from "./models";

const onSend: AiChatSendHandler = async function* (message, { model, messages, signal }) {
  const response = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ model, messages: messages.map(({ role, content }) => ({ role, content })) }),
    signal,
  });
  if (!response.ok || !response.body) throw new Error("The assistant is unavailable.");
  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) return;
    yield value;
  }
};

export default function AssistantPage() {
  return (
    <AiChatPage
      onSend={onSend}
      defaultConversationId={null}
      defaultConversations={[]}
      models={MODELS}
      defaultModel="standard"
      tools={[]}
      suggestions={[]}
      usage={[]}
      plan={null}
      user={{ id: "emma", name: "Emma Carter" }}
      assistantName="Northwind Assistant"
    />
  );
}
```

The props after `onSend` matter. Without them the block shows its sample content: a history of ten conversations, sample models and tools, a usage ring, a plan upsell and a sample user. That is useful in the playground and wrong in production, so pass your own data or empty values. `messages` in the context already includes the new question.

A thrown error shows on the message with a Retry button. Without `onSend`, the block runs a scripted mock with reasoning, tool calls and streamed markdown, so you can build the screen before the backend exists. For a React AI chatbot UI in a support panel, use Chat Thread on its own with `variant="bubbles"` and `size="sm"`.

> Live demo (AI Chat Page): In a frame this narrow you get the phone layout: the history sits behind the menu button and the model picker moves into the composer. Send a question, then press Stop while it streams. Try it at [AI Chat Page](https://wingo-ui.com/components/ai-chat-page) and install it with `npx wingo-ui@latest add ai-chat-page`.

#### When is AI Elements or assistant-ui the better choice?

When your app already runs on the AI SDK, or when you want the library to own chat state. Both are free and open source; Wingo UI's AI components are paid and leave state and transport to you. Here is how the three AI chat UI kits compare, as of October 2026:

| | AI Elements | assistant-ui | Wingo UI AI components |
|---|---|---|---|
| License and price | Apache 2.0, free | MIT, free; Assistant Cloud for hosted threads is optional | Pro: $8 a month, $80 a year or $150 lifetime |
| Built on | shadcn/ui | Primitives you style; a CLI starter in Base UI or Radix with a shadcn/ui theme | Tailwind CSS v4 and Motion, installed as source |
| Chat state | The AI SDK (`useChat`) | Its own runtimes for the AI SDK, LangGraph and custom backends | Yours: you pass `messages` and a `status` |
| Best when | Your app already uses the AI SDK | You want threads, streaming and tool calls managed for you | You own the transport and want scroll rules, phone layouts and announcements built in |

Sources: the [AI Elements docs](https://elements.ai-sdk.dev/components/conversation) and [repository](https://github.com/vercel/ai-elements), the [assistant-ui primitives](https://www.assistant-ui.com/docs/primitives), [runtime guide](https://www.assistant-ui.com/docs/runtimes/pick-a-runtime) and [repository](https://github.com/assistant-ui/assistant-ui), and our [pricing page](https://wingo-ui.com/pricing).

If your app is on the AI SDK and you want a free shadcn chat UI, start with AI Elements. If you want a library to manage the conversation state, assistant-ui does that. Wingo UI fits when the backend is already yours and the screen is the part you do not want to build.

#### What should you try next?

Open the [AI Chat Page](https://wingo-ui.com/components/ai-chat-page) docs, try its props in the playground, then install it with `npx wingo-ui@latest add ai-chat-page`. It and the five components in this guide are part of Wingo UI Pro. More guides on building with coding agents are in [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents).

#### Components in this post

- [Chat Thread](https://wingo-ui.com/components/chat-thread) (Pro): The scrolling conversation of an AI chat: pinned to the newest message while it streams, with day pills, follow-ups and a pinned composer. Install: `npx wingo-ui@latest add chat-thread`
- [Chat Message](https://wingo-ui.com/components/chat-message) (Pro): One message of an AI conversation: the question in a bubble, the answer with its thinking, tools, markdown, sources and actions. Install: `npx wingo-ui@latest add chat-message`
- [Prompt Input](https://wingo-ui.com/components/prompt-input) (Pro): The AI chat composer: a growing text box with attachments, tool chips, a model picker, dictation and one round send / stop button. Install: `npx wingo-ui@latest add prompt-input`
- [Reasoning Indicator](https://wingo-ui.com/components/reasoning-indicator) (Pro): The model's thinking, kept out of the way: a shimmering live timer while it thinks, then a quiet "Thought for 12 s" to expand. Install: `npx wingo-ui@latest add reasoning-indicator`
- [Model Picker](https://wingo-ui.com/components/model-picker) (Pro): A model switcher for AI chats: a quiet trigger that opens a short grouped list of models, each with its name and one line on what it is for. Install: `npx wingo-ui@latest add model-picker`
- [AI Chat Page](https://wingo-ui.com/components/ai-chat-page) (Pro): A full AI assistant screen: the conversation history, a streaming thread with reasoning and tools, a composer and the plan's usage. Install: `npx wingo-ui@latest add ai-chat-page`

#### FAQ

##### How do I auto-scroll a React chat while the AI response streams?

Follow new content only while the reader is near the bottom, stop following on the first wheel or touch movement upward, and scroll back down when they send a message or press a jump button. Write scrollTop in a requestAnimationFrame loop instead of React state, so streaming does not re-render the list.

##### Why does my chat input send the message when I press Enter in a Japanese IME?

The Enter that confirms the conversion reaches your keydown handler. Return early when event.nativeEvent.isComposing is true or event.keyCode is 229, because MDN notes that isComposing can be false on the last keydown of a composition.

##### How do I render streaming markdown in React without flicker?

Repair the unfinished tail before parsing: close an open code fence and unmatched emphasis, drop a half-typed link and hold a table back until its separator row arrives. Render the answer block by block, so finished blocks keep their DOM and only the last one re-parses.

##### Is there a shadcn chat UI component?

shadcn/ui has a Message Scroller for the transcript, and Vercel's AI Elements is a free component library built on shadcn/ui for apps that use the AI SDK. Wingo UI's Chat Thread, Prompt Input and the other AI components also install as source files you own, and they are part of Wingo UI Pro.

##### Are the Wingo UI AI chat components free?

No. Chat Thread, Chat Message, Prompt Input, Reasoning Indicator, Model Picker and the AI Chat Page block are part of Wingo UI Pro. The 75 free items include basics they build on, such as Button, Textarea and Tooltip.

---

Source: https://wingo-ui.com/blog/react-ai-chat-ui

### React Bottom Navigation Bar in Next.js: Safe Areas, Badges

> Build a React bottom navigation bar in Next.js: 3 to 5 link tabs, safe areas, badges screen readers announce, hide on scroll, and when a sidebar fits better.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 8 min
- Canonical: https://wingo-ui.com/blog/react-bottom-navigation-bar

#### TL;DR

A React bottom navigation bar is a fixed nav of 3 to 5 links at the bottom of the screen, with aria-current="page" on the active link, padding for env(safe-area-inset-bottom) under viewport-fit=cover, and bottom padding on the page equal to the bar's height so the last row stays visible. Keep the labels visible, put badge counts in each link's accessible name, and only hide the bar on scroll if it follows the finger and comes back on scroll up. Use it below 768px with a sidebar above that, and with more than five destinations keep the four most used in the bar and the rest in a drawer.

A React bottom navigation bar is the tab bar that native apps have trained everyone to expect: three to five destinations on the bottom edge, where the thumb already is. On the web it takes more than a fixed `<div>` of icons. The bar has to clear the iPhone home indicator, keep the last row of the page visible, tell a screen reader that Inbox has 4 unread messages, follow the router, and decide what a big center button and a long scroll should do. This guide covers each with the Wingo UI [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar), then the cases where a [Sidebar](https://wingo-ui.com/components/sidebar) is the better choice.

#### When does a web app need a bottom navigation bar?

When people use it on phones and move between three to five top-level sections many times a session. Android's [navigation bar guidance](https://developer.android.com/develop/ui/compose/components/navigation-bar) lists the conditions: "Three to five destinations of equal importance", "Compact window sizes" and "Consistent destinations across app screens". A CRM with Home, Clients, Inbox and Profile fits. A marketing site, a docs site or a checkout does not, because nobody hops between their sections.

The bottom edge is the reason to bother. In Steven Hoober's [2013 field study](https://www.uxmatters.com/mt/archives/2013/02/how-do-users-really-hold-mobile-devices.php) (1,333 observations of people using mobile devices), 49% of those touching the screen held the phone in one hand. A hamburger menu in a top corner sits far from that thumb and hides every destination behind an extra tap. In a bottom tab bar web app, every destination stays visible and one tap away, and the active tab tells people where they are.

#### What does a bottom tab bar need to work in a browser?

Five jobs that a native tab bar gets from the platform and a web page has to do itself:

| Concern | What to do | In the Bottom Tab Bar |
| --- | --- | --- |
| Semantics | A `<nav>` of links, `aria-current="page"` on the active one | `aria-label="Primary"`; tabs without `href` render as buttons |
| Routing | The active tab follows the URL, nested routes included | `currentPath` picks the longest matching `href`; `linkComponent` takes `next/link` |
| Home indicator | `viewport-fit=cover`, then pad the inside with `env(safe-area-inset-bottom)` | `safeArea`, on by default |
| Covered content | Pad the page by the bar's real height | Writes `--bottom-bar-offset` on `<html>` |
| Touch | Targets of 44px or more | Each tab fills its slot, 56 or 64px tall |

Build the tabs from links. The [ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) describes "layered sections of content, known as tab panels, that display one panel of content at a time". A tab bar loads another page, so `role="tablist"` would announce a widget that is not there.

Here is a React mobile bottom navigation for the Next.js App Router, in two files:

```tsx
// app/(app)/mobile-nav.tsx
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { House, Inbox, Plus, UserRound, Users } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House />, activeIcon: <House className="fill-current/20" /> },
  { label: "Clients", href: "/clients", icon: <Users />, activeIcon: <Users className="fill-current/20" /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Profile", href: "/profile", icon: <UserRound />, dot: true },
];

export function MobileNav() {
  return (
    <BottomTabBar
      className="md:hidden"
      items={tabs}
      currentPath={usePathname()}
      linkComponent={Link}
      action={{ label: "New client", icon: <Plus />, href: "/clients/new" }}
    />
  );
}
```

```tsx
// app/(app)/layout.tsx
import type { ReactNode } from "react";
import type { Viewport } from "next";
import { MobileNav } from "./mobile-nav";

// without cover, iOS keeps the page inside the safe area and env() reports 0
export const viewport: Viewport = { width: "device-width", initialScale: 1, viewportFit: "cover" };

export default function AppLayout({ children }: { children: ReactNode }) {
  return (
    <>
      <main className="pb-(--bottom-bar-offset)">{children}</main>
      <MobileNav />
    </>
  );
}
```

The bar is fixed to the viewport and measures itself, safe area included, so the padding on `<main>` is always exact; hidden by `md:hidden` on a desktop, it measures 0. A guessed `pb-16` is wrong as soon as the inset or the size changes. The [safe area guide](https://wingo-ui.com/blog/tailwind-safe-area-insets) explains the CSS underneath. Render the bar in the server HTML and hide it with CSS: deciding with a `useIsMobile()` hook renders nothing on the server, and the bar pops in after hydration, as the [useMobile hook guide](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) shows.

> Live demo (Bottom Tab Bar): Tap Clients, open a client, then tap Clients again: the tab goes back to its list, and one more tap scrolls to the top. The raised Add button opens a sheet instead of switching tabs. Try it at [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) and install it with `npx wingo-ui@latest add bottom-tab-bar`.

#### How should tab bar badges and labels behave?

A count for things that need action, a dot for something new, both read as part of the tab's name. `badge: 4` renders a count (99+ above 99) and `dot: true` an 8px dot, red by default (`badgeTone="danger"`) because people read a red count as unread. The visible badge is `aria-hidden`, and the link is named "Inbox, 4 unread" (`badgeLabel`) or "Profile, new" (`dotLabel`), so a screen reader never reads a stray number. Apple's [tab bar guidelines](https://developer.apple.com/design/human-interface-guidelines/tab-bars) (updated June 2026) say "Reserve badges for critical information so you don't dilute their impact and meaning": unread messages and pending approvals, not a new feature.

Keep `showLabels="always"`. The same guidelines say "Include tab labels to help with navigation" and "Use single words whenever possible". `"active"` and `"never"` exist for icon-heavy consumer apps; with `"never"`, labels stay in the DOM for screen readers and become `title` tooltips. `activeIcon` swaps in a second glyph while the tab is active, such as a filled version of the outline icon. Apple goes further and asks you to "Prefer filled symbols or icons for consistency with the platform" on every tab.

#### Should the center button be a tab, an action or a FAB?

An action, never a tab, and only when one creation action dominates the app. Apple is strict here: "Use a tab bar to support navigation, not to provide actions." We still ship the raised center button, because in an app built around one verb (Post, Sell, Scan) that verb has earned the most reachable spot. The `action` prop renders it in the middle (with four tabs: two, the action, two), filled with the `tone` and named by its `label`. It never takes the active pill, so nobody mistakes it for where they are.

When the app has several things to create, or you follow Apple's rule, leave the bar to navigation and use a [FAB](https://wingo-ui.com/components/fab). It reads `--bottom-bar-offset`, so it floats 16px above the tab bar and the home indicator without counting the inset twice:

```tsx
import { FileText, UserPlus } from "lucide-react";
import { Fab, type FabAction } from "@/components/ui/fab";

const actions: FabAction[] = [
  { id: "client", label: "New client", icon: <UserPlus />, href: "/clients/new" },
  { id: "invoice", label: "New invoice", icon: <FileText />, href: "/invoices/new" },
];

export function CreateFab() {
  return <Fab className="md:hidden" label="Add" actions={actions} />;
}
```

> Live demo (FAB): Tap Add: the page dims and the create actions rise from the button. Scroll the list and the label folds down to the plus. Try it at [FAB](https://wingo-ui.com/components/fab) and install it with `npx wingo-ui@latest add fab`.

#### Should a bottom navigation bar hide on scroll?

Only on long feeds and reading screens, and only if it comes back the moment the user might need it. Apple warns that "If you hide the tab bar, people can forget which area of the app they're in". Its iOS guidance describes minimizing a tab bar that carries an accessory, such as the MiniPlayer in Music, while people scroll down; tapping a tab or scrolling to the top brings it back.

If you hide it, `hideOnScroll` shows the behavior to copy:

- **It follows the finger.** The bar moves pixel for pixel with the scroll until it has traveled its own height plus the safe area, and snaps to shown or hidden once scrolling stops. A boolean that flips on direction makes the bar jump on a 2px scroll.
- **It comes back** on scroll up, at the top, at the end of the content and whenever keyboard focus is inside it.
- **It moves a transform only.** The progress lives in a motion value, so scrolling never re-renders the bar or the page. A version that calls `setState` in the scroll handler renders on every scroll event.
- **Reduced motion** turns the slide into a flip after a full bar height of scrolling.

> Live demo (Bottom Tab Bar): Scroll the page: the floating bar follows your finger out of view and comes back as soon as you scroll up. Try it at [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) and install it with `npx wingo-ui@latest add bottom-tab-bar`.

#### When is a sidebar the better choice?

When there are more than five top-level destinations, when they nest, or when most sessions happen on a laptop. Apple suggests "a sidebar or a tab bar that adapts to a sidebar as an alternative for an app with a complex information structure" and asks you to "Avoid overflow tabs"; Android recommends the bar for compact windows.

| Your app | On a phone | From 768px |
| --- | --- | --- |
| 3 to 5 sections, used daily on phones | Bottom tab bar | Sidebar or top navigation |
| 6 or more sections, or nested ones | The 4 most used in the bar, everything in a drawer | Sidebar |
| Admin tool used mostly at a desk | Drawer, optional tab bar | Sidebar with an icon rail |
| Content or docs site | Top bar and a menu | Top navigation |

Most apps need both, so the [App Shell](https://wingo-ui.com/components/app-shell) renders the Sidebar beside the page from 768px and, below it, the same sidebar in a drawer plus a tab bar for the daily destinations:

```tsx
// app/(app)/layout.tsx with the App Shell
import type { ReactNode } from "react";
import { AppShell } from "@/components/ui/app-shell";
import { Sidebar } from "@/components/ui/sidebar";
import { Topbar } from "@/components/ui/topbar";
import { nav, tabs } from "./nav";

export default function AppLayout({ children }: { children: ReactNode }) {
  return (
    <AppShell sidebar={<Sidebar groups={nav} filter />} topbar={<Topbar title="Summit CRM" />} tabs={tabs}>
      {children}
    </AppShell>
  );
}
```

`nav` holds every destination in groups and `tabs` the four people open every day. The shell renders the tab bar itself and reads the route from a `LinkProvider` (`component={Link}`, `currentPath={usePathname()}`) set once in a client provider; the [Next.js admin dashboard tutorial](https://wingo-ui.com/blog/nextjs-admin-dashboard-tutorial) builds that provider and the whole layout. The [Admin Shell](https://wingo-ui.com/components/admin-shell) adds a More tab that opens the drawer.

If you came looking for a shadcn mobile bottom navigation: as of October 2026, the shadcn/ui [component list](https://ui.shadcn.com/docs/components) has none, and its [Sidebar](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/sidebar.tsx) becomes an 18rem Sheet below 768px, two taps from any destination. Material UI's [Bottom Navigation](https://mui.com/material-ui/react-bottom-navigation/) is a fine react bottom navigation component, and the better pick if your app already runs on Material UI. As of October 2026 its docs cover labels, fixed positioning and router links, and leave badges, safe areas and hide on scroll to you.

#### What breaks a bottom navigation bar in production?

- **Home is active on every page.** A hand-rolled `pathname.startsWith(href)` matches `/` everywhere. The bar matches `/` only exactly and picks the longest matching `href`, so `/clients/northwind-tech` keeps Clients active.
- **Tapping the active tab does nothing.** People expect it to scroll to the top or go back to the tab's first screen. `scrollToTopOnReselect` does both, and `onReselect` can refresh a feed.
- **A sixth tab.** The bar warns in development above five items. Move the rest into a More tab or the drawer.
- **Safari's floating toolbar.** Since iOS 26, Safari's toolbar floats over the bottom of the page in the Compact tab layout, and a [September 2025 forum report](https://developer.apple.com/forums/thread/800798) says Safari would not render fixed content below those controls. Test on a real iPhone in the Compact, Bottom and Top tab layouts.
- **Two bars, two insets.** A buy bar above the tab bar must not pad the home indicator again; the [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) guide shows the stacking.

#### What should you install?

`npx wingo-ui@latest add bottom-tab-bar` copies the component into `components/ui/` with the Badge, the navigation and motion helpers and the scroll hooks it imports. The Bottom Tab Bar, FAB, Sidebar and App Shell are part of [Wingo UI Pro](https://wingo-ui.com/pricing); the Badge is free. More guides like this one live in [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: `npx wingo-ui@latest add bottom-tab-bar`
- [FAB](https://wingo-ui.com/components/fab) (Pro): The floating action button for a phone screen's main action, with a labelled or radial speed dial and a label that folds while you scroll. Install: `npx wingo-ui@latest add fab`
- [Sidebar](https://wingo-ui.com/components/sidebar) (Pro): The admin sidebar: grouped links with icons, nested sections, badges, a sliding active pill, an icon rail with flyouts and a filter. Install: `npx wingo-ui@latest add sidebar`
- [App Shell](https://wingo-ui.com/components/app-shell) (Pro): The whole admin layout in one component: a collapsible, resizable sidebar, a top bar and the page; a drawer and a tab bar on phones. Install: `npx wingo-ui@latest add app-shell`

#### FAQ

##### How many items should a bottom navigation bar have?

Three to five. Android's guidance lists three to five destinations of equal importance, and Apple's tab bar guidelines ask you to avoid overflow tabs. With more sections, keep the four most used in the bar and put everything in a drawer or a sidebar.

##### Does shadcn/ui have a bottom navigation component?

Not as of October 2026: its component list has no bottom navigation or tab bar, and its Sidebar turns into an 18rem Sheet below 768px. Wingo UI's Bottom Tab Bar, a Pro component, installs the same way, as source code in your project, with npx wingo-ui@latest add bottom-tab-bar.

##### Should a bottom navigation bar use role="tablist"?

No. The ARIA tabs pattern is for panels that switch inside one page. A bar that changes the page is navigation: a nav element with links, and aria-current="page" on the active one.

##### Should a bottom navigation bar hide on scroll?

Only on long feeds and reading screens, because a hidden bar also hides where people are in the app. If it hides, it should follow the finger, move with a transform only, and come back on scroll up, at the top and end of the page, and while keyboard focus is inside it.

##### Is the Wingo UI Bottom Tab Bar free?

No. The Wingo UI Bottom Tab Bar is a Pro component, like the FAB, the Sidebar and the App Shell; the Badge it uses for counts is free.

---

Source: https://wingo-ui.com/blog/react-bottom-navigation-bar

### React Bottom Sheet for the Web: Snap Points, Drag, Keyboard

> Build a React bottom sheet for the web on vaul: snap points, drag to dismiss, nested sheets, the on-screen keyboard and the home indicator, with working code.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 9 min
- Canonical: https://wingo-ui.com/blog/react-bottom-sheet-for-the-web

#### TL;DR

A React bottom sheet for the web is a draggable dialog pinned to the bottom of the screen, so build it on a DOM dialog primitive: Base UI's Drawer (maintained) or vaul (unmaintained per its README, still the most complete option on Radix). Pass snap points as fractions from 0 to 1 in a stable array, let the body scroll only at the last point, raise the sheet above the on-screen keyboard with the visualViewport API, and pad the part that touches the bottom edge with env(safe-area-inset-bottom). The free Wingo UI Drawer does all of this on top of vaul 1.1.2.

Search for a React bottom sheet and many of the top results are React Native packages such as @gorhom/bottom-sheet, which reach the browser only through React Native Web. This guide is about the React bottom sheet web apps need: a real dialog in the DOM, pointer events, `position: fixed`, an on-screen keyboard that covers half the screen and a home indicator under your Save button. It covers the five parts that decide whether a sheet feels native on a phone (snap points, drag to dismiss, nested sheets, the keyboard and the safe area), with code for vaul and for the free Wingo UI [Drawer](https://wingo-ui.com/components/drawer), which is built on it.

#### Which React bottom sheet library works on the web?

For apps that render to the DOM, vaul and Base UI's Drawer are the two serious choices, because both sit on a dialog primitive: focus trapping, Escape and the accessible title come with them. As of October 2026, from the npm registry and each project's docs:

| Library | Built on | Snap points | Nested sheets | Latest release |
| --- | --- | --- | --- | --- |
| [vaul](https://github.com/emilkowalski/vaul) | Radix Dialog | Fractions or px strings | `Drawer.NestedRoot` | 1.1.2, Dec 14, 2024 |
| [Base UI Drawer](https://base-ui.com/react/components/drawer) | Base UI Dialog | Fractions, px or rem | Yes, styled with CSS variables | @base-ui/react 1.8.0, Sep 4, 2026 |
| [react-modal-sheet](https://github.com/temzasse/react-modal-sheet) | Motion | Fractions or px, including 0 (closed) and 1 | Not documented | 5.6.0, Mar 27, 2026 |
| [react-spring-bottom-sheet](https://github.com/stipsan/react-spring-bottom-sheet) | react-spring, react-use-gesture | A function of the content's min and max height | Not documented | 3.4.1, Jun 1, 2022 |

Three facts the table cannot show change the decision. Vaul's README says "This repo is unmaintained", and no release has shipped since December 2024; its peer range still includes React 19, and the Wingo UI Drawer runs on it with React 19.3. react-spring-bottom-sheet's peer range stops at React 18. react-modal-sheet's README says it "doesn't include any built-in accessibility properties", so focus trapping and dialog semantics are yours to add.

If your project already uses Base UI, the default for new shadcn/ui projects since [July 2026](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default), use its Drawer: it is maintained and covers snap points, nesting and the keyboard (`Drawer.VirtualKeyboardProvider`). On Radix, vaul is still the most complete option, and the rest of this guide is about the gaps you cover around it.

#### How do vaul drawer snap points work?

Vaul drawer snap points are stops on the way up, listed from least to most visible: a number is a fraction of the screen height (`0.45` is 45%), a string is pixels (`"320px"`). The sheet renders at full height and is translated down to the active point. Three details trip people up in vaul 1.1.2:

1. **Fractions from 0 to 1.** The type comment says "Array of numbers from 0 to 100", but the code multiplies each number by the window height, so `50` means fifty screens. Write `0.5`.
2. **Pixels only.** A string goes through `parseInt`, so `"30rem"` becomes 30 pixels.
3. **Hoist the array.** Vaul re-runs its snap effect whenever `snapPoints` changes identity, so an inline literal re-snaps the sheet on every parent render.

Then decide what scrolls. Below the last point the body should stay still, so an upward swipe drags the sheet instead of scrolling a list the user can only half see. `fadeFromIndex` picks the point where the overlay starts to dim; it defaults to the last one, so a half-open sheet leaves the page bright.

Make the React bottom sheet modal when it holds a task. Pass `modal={false}` when the page behind must stay usable, like a results list over a map:

```tsx
"use client";

import { useState } from "react";
import { Drawer, type DrawerSnapPoint } from "@/components/ui/drawer";

// fractions of the screen height, least visible first; one array for the app's lifetime
const SNAP_POINTS: DrawerSnapPoint[] = [0.45, 1];

type Apartment = { id: string; title: string; rent: string };

export function MapResults({ apartments }: { apartments: Apartment[] }) {
  const [snap, setSnap] = useState<DrawerSnapPoint | null>(SNAP_POINTS[0]);
  return (
    <Drawer
      defaultOpen
      modal={false}
      dismissible={false}
      snapPoints={SNAP_POINTS}
      activeSnapPoint={snap}
      onActiveSnapPointChange={setSnap}
      title="Apartments in Chicago"
      description={`${apartments.length} results in the map area`}
    >
      <ul className="flex flex-col gap-3">
        {apartments.map((a) => (
          <li key={a.id} className="flex justify-between gap-3 text-[15px]">
            <span className="truncate">{a.title}</span>
            <span className="font-semibold tabular-nums">{a.rent}</span>
          </li>
        ))}
      </ul>
    </Drawer>
  );
}
```

With snap points, `dismissible={false}` stops the sheet at its first point, so the list can never be dragged away behind the map. The Drawer keeps one array per distinct list of points even when you pass a literal, lets the body scroll only at the last point, and steps to the next point on a tap on the handle.

#### How does drag to dismiss decide when to close?

By distance or speed, measured when the finger lifts. Without snap points, vaul closes the sheet when you let go past 25% of its height (`closeThreshold`, default 0.25) or flick it faster than 0.4 pixels per millisecond; anything less eases back over 500ms on `cubic-bezier(0.32, 0.72, 0, 1)`. With snap points it settles on the nearest point, a flick moves one point in its direction, and a flick faster than 2 pixels per millisecond closes the sheet or opens it fully. The harder part is when a drag should not start at all. Vaul 1.1.2 refuses one:

- from inside a scrollable element that is not at its top, so a long list scrolls first;
- for a moment after the content scrolled (`scrollLockTimeout`: 100ms in the code, although the type comment says 500ms);
- while text is selected, from a native `<select>`, or from anything inside `[data-vaul-no-drag]`;
- in the first 500ms after opening.

Left and right drawers skip the scroll and timing checks. For content with its own horizontal gestures (a carousel, a map, a range slider) set `handleOnly`, so only the handle drags. And give every drag a visible alternative: Escape, a tap on the dimmed page and a close button. The Wingo UI Drawer leaves the close button off bottom sheets by default, so pass `showClose` (panels and dialogs always have one).

The demo below is a listings page. Filters opens a sheet with price, condition and category filters and a pinned button with the result count.

> Live demo (Drawer): Tap Filters, then drag the sheet down: let go past a quarter of its height or flick it and it closes, a shorter drag settles back. Scroll the categories first: the sheet only drags once the list is back at the top. Try it at [Drawer](https://wingo-ui.com/components/drawer) and install it with `npx wingo-ui@latest add drawer`.

#### How do you nest bottom sheets?

Open the second sheet from inside the first and push the first one back, like iOS. In vaul that is `Drawer.NestedRoot`, rendered inside the parent's `Drawer.Content`; it throws when it has no parent drawer, and as the child opens it shrinks the parent 16px narrower, lifts it 16px and follows the child's drag. It moves the parent only from its own `onOpenChange`, so a child opened by setting `open` from state leaves the parent flat.

The Wingo UI Drawer detects nesting from context. A drawer rendered inside another drawer's content uses the nested root on its own and pushes the parent for controlled opens too:

```tsx
"use client";

import type { ReactNode } from "react";
import { Button } from "@/components/ui/button";
import { Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerFooter, DrawerHeader, DrawerRoot, DrawerTrigger } from "@/components/ui/drawer";

export function DeliveryAddress({ addresses, newAddressForm }: { addresses: ReactNode; newAddressForm: ReactNode }) {
  return (
    <DrawerRoot>
      <DrawerTrigger asChild>
        <Button variant="soft" size="sm">Change</Button>
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader title="Delivery address" description="Arrives in 1-2 business days" />
        <DrawerBody>
          {addresses}
          {/* inside the first sheet's content, so it nests and pushes the first one back */}
          <Drawer
            title="New address"
            trigger={<Button variant="ghost" fullWidth>Add a new address</Button>}
            footer={
              <DrawerClose asChild>
                <Button size="lg" fullWidth>Save address</Button>
              </DrawerClose>
            }
          >
            {newAddressForm}
          </Drawer>
        </DrawerBody>
        <DrawerFooter>
          <DrawerClose asChild>
            <Button size="lg" fullWidth>Deliver here</Button>
          </DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </DrawerRoot>
  );
}
```

Stop at two levels. On a 390px screen a third sheet is a page, so navigate to one.

#### What happens when the keyboard opens inside a bottom sheet?

The keyboard covers the sheet unless something moves it. On Safari for iOS, and on Chrome for Android since version 108, the keyboard resizes only the visual viewport ([Chrome's announcement](https://developer.chrome.com/blog/viewport-resize-behavior)), so an element at `position: fixed; bottom: 0` stays behind it. Vaul's `repositionInputs`, on by default, listens to `visualViewport` resize events: while a field has focus it raises the sheet by the height the keyboard covers and shrinks it when it no longer fits above the keyboard.

Two rules make that work in practice:

- **Do not focus a field on open.** The Wingo UI Drawer focuses the sheet itself, so the keyboard does not cover half the sheet before anyone has read it; Tab moves on to the first control. When typing is the whole task, such as renaming a list, pass `onOpenAutoFocus`, call `event.preventDefault()` and focus the field yourself.
- **Use 16px text in inputs** (`text-base md:text-sm`). iOS Safari zooms into a focused field with smaller text.

Turn `repositionInputs` off when the sheet handles the keyboard itself, for example a chat composer that follows the keyboard with the Pro [useKeyboardInset](https://wingo-ui.com/components/use-keyboard-inset) hook.

#### How do you keep a bottom sheet clear of the home indicator?

Let the page reach the screen edges with `viewport-fit=cover` (in Next.js, `viewportFit: "cover"` in the root layout's `viewport` export), then pad the part of the sheet that touches the bottom edge with `max(env(safe-area-inset-bottom), 16px)`. The `max()` keeps 16px of air on devices that report an inset of 0. Pad only the last part: the footer when there is one, otherwise the scrolling body, so its last row can scroll above the indicator. Cap the height at `92dvh` so a strip of the page stays visible to tap. On a plain vaul drawer:

```tsx
"use client";

import type { ReactNode } from "react";
import { Drawer } from "vaul";

type SheetProps = { trigger: ReactNode; title: string; children: ReactNode; actions: ReactNode };

export function BottomSheet({ trigger, title, children, actions }: SheetProps) {
  return (
    <Drawer.Root>
      <Drawer.Trigger asChild>{trigger}</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Overlay className="fixed inset-0 z-40 bg-black/40" />
        <Drawer.Content
          aria-describedby={undefined}
          className="fixed inset-x-0 bottom-0 z-50 flex max-h-[92dvh] flex-col rounded-t-[28px] bg-popover outline-none"
        >
          <Drawer.Handle className="mt-2.5" />
          <Drawer.Title className="px-5 pt-3 pb-2 text-[17px] font-semibold">{title}</Drawer.Title>
          <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-5">{children}</div>
          {/* the part that touches the bottom edge pads the home indicator */}
          <div className="flex flex-col gap-2 px-5 pt-3 pb-[max(env(safe-area-inset-bottom),16px)]">{actions}</div>
        </Drawer.Content>
      </Drawer.Portal>
    </Drawer.Root>
  );
}
```

The Wingo UI Drawer pads whichever part comes last. Its `variant="floating"` instead sits 8px above the safe area with every corner rounded, the look the [Action Sheet](https://wingo-ui.com/components/action-sheet) uses for its iOS variant. The same insets for tab bars, FABs and toasts are in our [Tailwind safe area insets tutorial](https://wingo-ui.com/blog/tailwind-safe-area-insets).

#### Which bottom sheet should you use for each job?

There is no single bottom sheet UI React apps should use for everything. Pick by the job:

| Component | Use it for | Built on | Access |
| --- | --- | --- | --- |
| [Drawer](https://wingo-ui.com/components/drawer) | Forms, filters, pickers, results over a map; a side panel or a dialog from 768px (`desktop`) | vaul | Free |
| [Action Sheet](https://wingo-ui.com/components/action-sheet) | A short list of actions about one thing, with a separate Cancel and `await show()` | Drawer | Pro |
| [Family Drawer](https://wingo-ui.com/components/family-drawer) | A floating sheet that morphs between views, such as a menu and a confirmation | vaul | Free |
| [Sheet](https://wingo-ui.com/components/sheet) | A side panel on desktop that becomes a bottom sheet on phones (`mobileSide="bottom"`) | Radix Dialog and motion | Free |

The Action Sheet also works imperatively: mount an `ActionSheetProvider` once, take `const actionSheet = useActionSheet()` in a component, and in a click handler `await actionSheet.show({ actions })` resolves with the chosen action's id, or `null` on Cancel or a dismiss. An action whose `onSelect` returns a promise keeps the sheet open with a spinner in its row; the sheet closes when the promise resolves, and the row shakes and stays ready to retry when it rejects.

> Live demo (Action Sheet): Tap the ⋯ button on the listing: the iOS sheet floats above the home indicator with Cancel in its own card. Delete listing shows a spinner in its row until its promise resolves. Try it at [Action Sheet](https://wingo-ui.com/components/action-sheet) and install it with `npx wingo-ui@latest add action-sheet`.

The Family Drawer keeps one floating sheet and animates its height between views, which suits a short flow like a menu that leads to a confirmation.

> Live demo (Family Drawer): Tap Try it out and pick an option: the floating sheet morphs to the height of the new view. Drag it down or tap outside to close it. Try it at [Family Drawer](https://wingo-ui.com/components/family-drawer) and install it with `npx wingo-ui@latest add family-drawer`.

In the registry (release 1.7.0), 39 other items import the Drawer, including the Popover, Select, Dropdown Menu and Dialog, which open as bottom sheets below 768px. Every sheet in an app drags, snaps and pads the same way.

#### What should you do next?

Install the free Drawer with `npx wingo-ui@latest add drawer`, open your app at 390px and drag a sheet closed with its list scrolled halfway. For the switch between a centered card and a sheet, read the [shadcn responsive dialog tutorial](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile); for touch targets, safe areas and the rest of the phone rules, the [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components) and the [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui) category. The Action Sheet is part of [Wingo UI Pro](https://wingo-ui.com/pricing).

#### Components in this post

- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [Family Drawer](https://wingo-ui.com/components/family-drawer) (Free): A floating bottom drawer that morphs smoothly between stacked views, inspired by the Family app. Install: `npx wingo-ui@latest add family-drawer`
- [Action Sheet](https://wingo-ui.com/components/action-sheet) (Pro): The iOS action sheet: a short list of actions about one thing, with a title, red destructive rows and a separate Cancel, plus await show(). Install: `npx wingo-ui@latest add action-sheet`
- [Sheet](https://wingo-ui.com/components/sheet) (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: `npx wingo-ui@latest add sheet`

#### FAQ

##### Can I use @gorhom/bottom-sheet in a React web app?

Only through React Native Web: it is a React Native library that needs Reanimated and Gesture Handler. In a Next.js or Vite app that renders to the DOM, use vaul or Base UI's Drawer, which are built on accessible dialog primitives.

##### Is vaul still maintained?

No. As of October 2026 its README says the repo is unmaintained, and the last release is 1.1.2 from December 14, 2024. It still declares React 19 support; Base UI's Drawer is the maintained alternative.

##### Why do my vaul snap points not work with values like 50?

Vaul multiplies each number by the screen height, so numbers must be fractions from 0 to 1 (0.5 for half the screen), even though a type comment says 0 to 100. Strings are read as pixels, so write "320px", never rem.

##### How do I stop a vaul drawer from dragging when I swipe a carousel inside it?

Set handleOnly so only the handle drags the sheet, or add the data-vaul-no-drag attribute to the carousel's root element. Vaul already ignores drags that start on a native select or while text is selected.

##### Is the Wingo UI Drawer free?

Yes. The Drawer, Family Drawer and Sheet are free and the Action Sheet is Pro. npx wingo-ui@latest add drawer copies the component into your project with the Button, hooks and helpers it imports.

---

Source: https://wingo-ui.com/blog/react-bottom-sheet-for-the-web

### React Command Palette: Cmd+K, Nested Pages and Mobile

> Build a React command palette that binds Cmd+K on a Mac and Ctrl+K elsewhere, with nested pages, async results, recents and a full-height sheet on phones.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 9 min
- Canonical: https://wingo-ui.com/blog/react-command-palette

#### TL;DR

A React command palette should bind one mod+K shortcut that reads ⌘K on Apple devices and Ctrl+K elsewhere, keep nested pages as a stack that Backspace and Escape pop, debounce and abort server searches, and store recents by item id. Phones have no Cmd key, so it also needs a visible search button that opens a full-height sheet with the keyboard already up and 16px input text. Wingo UI's Command Menu (Pro) does all of this on top of cmdk; the Kbd and useShortcut pieces it uses are free.

A React command palette is a search box in a dialog that lets people jump to a page, run an action or find a client without reaching for the mouse. With cmdk the first version is short. The details take longer: the hint has to read ⌘K on a Mac and Ctrl+K on Windows, "Theme…" should open a second page that Backspace closes, server results should arrive without flicker, recent picks should come first, and on a phone the whole thing should become a full-height sheet with the keyboard up. A basic cmd k search React example, shadcn's included, ends at the filtered list. This guide covers the rest with the [Command Menu](https://wingo-ui.com/components/command-menu) from Wingo UI, the library we build, so we are not neutral; outside facts link to their sources.

#### What does a React command menu need?

It needs a device-aware shortcut, forgiving ranking, nested pages, async results, recents and a phone layout. Our checklist for a React command menu:

- **One shortcut, two notations.** `mod+k` binds ⌘K on Apple devices and Ctrl+K elsewhere, and the hint shows the right one.
- **Groups and ranking.** Matching ignores case and diacritics, so "cafe" finds "Café", and the matched letters turn bold.
- **Nested pages.** An item with a chevron opens a page; Backspace on an empty input or Escape goes back.
- **Async results** under the static ones, debounced, the previous request aborted.
- **Recents** by item id while the query is empty.
- **Phones**: a full-height sheet, 48px rows, a Cancel button, no key hints.

```bash
npx wingo-ui@latest add command-menu
```

> Live demo (Command Menu): Press ⌘J or Ctrl+J (the site keeps ⌘K) or click the search field, an icon on phones. Type "boston" for server results, pick "Theme…" to open a page, then press Backspace to go back. Try it at [Command Menu](https://wingo-ui.com/components/command-menu) and install it with `npx wingo-ui@latest add command-menu`.

#### How do I bind Cmd+K on a Mac and Ctrl+K on Windows?

Write the shortcut once as `mod+k`, resolve `mod` to Meta on Apple devices and Control elsewhere, compare the physical key when the layout types another character, and render the label for the device. The [shadcn command palette example](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/examples/command-dialog.tsx) toggles on this check and prints a fixed ⌘J hint:

```tsx
if (e.key === "j" && (e.metaKey || e.ctrlKey)) {
  e.preventDefault()
  setOpen((open) => !open)
}
```

Three things are off. Ctrl+J also fires on a Mac. Windows users see a ⌘ key they do not have. And `event.key` is the character the layout types, which on a Cyrillic layout can be a Cyrillic letter; [`event.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) names the physical key and "isn't altered by keyboard layout". The free [useShortcut hook](https://wingo-ui.com/components/use-shortcut) handles all three, and the free [Kbd](https://wingo-ui.com/components/kbd) prints the label:

```tsx
"use client";

import { Kbd } from "@/components/ui/kbd";
import { useShortcut, useShortcutLabel } from "@/hooks/use-shortcut";

export function SearchButton({ onOpen }: { onOpen: () => void }) {
  const label = useShortcutLabel("mod+k");
  // meta on apple devices, ctrl elsewhere; the physical key on non-latin layouts
  useShortcut("mod+k", onOpen);
  return (
    <button type="button" onClick={onOpen} aria-keyshortcuts={label.aria}>
      Search <Kbd shortcut="mod+k" hideOnTouch />
    </button>
  );
}
```

- **The label renders as Ctrl+K on the server** and switches to ⌘K after hydration, because the server cannot know the platform. Same trap as an [SSR-safe useIsMobile hook](https://wingo-ui.com/blog/react-use-mobile-hook-ssr).
- **[`aria-keyshortcuts`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts)** announces the shortcut; MDN notes it "has no effect on the functionality of the page", so the listener still does the work.
- **Bare keys** such as `/` stay quiet while focus is in a text field. Combos with a modifier fire anywhere.

Ctrl+K is taken: as of October 2026, [Chrome's shortcut list](https://support.google.com/chrome/answer/157179) uses Ctrl+K on Windows and Linux to "Search from anywhere on the page". The listener calls `preventDefault()`, so the palette wins while the page has focus. [MDN advises](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts#dont_override_browser_assistive_technology_or_operating_system_shortcuts) against taking a browser shortcut "unless they are used for the same thing", and a search palette is close to that.

One cmdk React detail bites on Windows: the [`vimBindings`](https://github.com/dip/cmdk/blob/main/cmdk/src/index.tsx) prop defaults to true, so Ctrl+J and Ctrl+K inside the list move the highlight and call `preventDefault()`. A listener that skips handled events, like useShortcut, then ignores the second Ctrl+K and the palette stays open. Pass `vimBindings={false}` if you want a toggle. The Command Menu keeps cmdk's default as of October 2026, so on Windows and Linux a second Ctrl+K moves the highlight up and Escape is the key that closes it.

> Live demo (useShortcut): Press Alt+K, or Option+K on a Mac where that key types ˚: the last row still lights up, and the line under it spells the combo for both platforms. Try it at [useShortcut](https://wingo-ui.com/components/use-shortcut) and install it with `npx wingo-ui@latest add use-shortcut`.

#### How do nested pages work in a command palette?

Pages are a stack. An item with `page: "theme"` pushes that page and clears the query; Backspace on an empty input or Escape pops it; Escape on the first page closes the menu. Going back restores the query you had and highlights the row that opened the page, which [cmdk's own pages pattern](https://github.com/dip/cmdk) leaves to you. A page brings its own `groups`, or a `loadItems` that also runs for the empty query (the projects page in the full example below).

#### How do I load async results without flicker?

Debounce the query, abort the request it replaces, and render server results under the local ones instead of swapping the list. The Command Menu calls `loadItems(query, { signal, page })` 200ms after the last keystroke (`debounce`), aborts the previous call through `signal`, shows a spinner in the input, keeps the static matches on screen, and turns a rejected promise into a "Could not load results" row with Try again. Pass `signal` to `fetch` so a stale request stops.

On raw cmdk, set `shouldFilter={false}` when you filter yourself or the server already did; otherwise cmdk filters and sorts the server's answer again. The Command Menu sets it too and ranks with its own text matcher. cmdk's README also says it has no virtualization, with "Good performance up to 2,000-3,000 items", so large data sets belong on the server.

#### How should recents work in a command palette?

Store item ids, never labels, and only for things the person ran. Picks go to local storage under `recentKey` (`"command-menu:recent"`), and the last `maxRecent` (5) show in a Recent group while the query is empty. Page openers are not recorded. Server results stay in recents for the current session only, since a reload cannot rebuild them from the static groups. Prefix server ids (`client:42`) so they never collide with static ones: when two items share an id, only the first one renders, and development builds warn about duplicates inside `groups` and `pages`.

#### What should a command palette do on a phone?

Open a full-height sheet with the keyboard already up. A phone has no ⌘ key, so the palette needs a visible trigger: `CommandMenuTrigger` reads "Search or jump to… ⌘K" on desktop and folds into an icon button below 768px. Below 768px the menu opens as a [bottom sheet](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web): an iOS-style search field, 48px rows, a Cancel button, swipe down to close, and no shortcut hints or footer on touch screens.

On iOS, a `focus()` call that does not come from the tap focuses the input and leaves the keyboard down. That is deliberate: in [WebKit bug 195884](https://bugs.webkit.org/show_bug.cgi?id=195884) an Apple engineer wrote in 2019 that Apple does "not want programmatic focus to bring up the keyboard", and the bug is still open in October 2026. The sheet's input does not exist yet when the tap lands, so the trigger focuses a hidden input inside the tap handler and hands focus to the real one once the sheet mounts.

Keep the input at 16px. Safari on iOS zooms into a focused input whose text is 15px or smaller ([CSS-Tricks](https://css-tricks.com/16px-or-larger-text-prevents-ios-form-zoom/)), and shadcn's [`CommandInput`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/command.tsx) uses `text-sm` (14px) as of October 2026.

> Live demo (Command Menu): This copy always opens as the phone sheet. Click the field or press Alt+P (Option+P on a Mac), type "inv", then press Cancel or drag the sheet down. Try it at [Command Menu](https://wingo-ui.com/components/command-menu) and install it with `npx wingo-ui@latest add command-menu`.

#### Is a cmdk command palette accessible?

Yes for the core widget. cmdk renders the input as a `combobox` that controls a `listbox` and sets `aria-activedescendant` to the highlighted option, so screen readers follow the highlighted row while focus stays in the input, and its README says labeling and ARIA attributes were "tested with Voice Over and Chrome DevTools". The Command Menu adds a hidden dialog title, `aria-keyshortcuts` on rows with a shortcut, and a polite live region that announces the result count after typing pauses. For translation, the input text comes from `placeholder`, `emptyText` and `loadingText`, and every other visible or spoken string from `labels`.

#### Should you use the shadcn command palette, cmdk or a ready-made menu?

Use shadcn's Command when you want free MIT code and will write the shortcut, pages, async loading and phone layout yourself. Use cmdk directly for an unstyled base. Use the Command Menu when you want those as props. As of October 2026, from the [cmdk README](https://github.com/dip/cmdk) and the [shadcn/ui Command docs](https://ui.shadcn.com/docs/components/command):

| | cmdk 1.1.1 | shadcn/ui Command | Wingo UI Command Menu |
| --- | --- | --- | --- |
| What you get | Unstyled primitives, `Command.Dialog` on Radix | cmdk with Tailwind styles in a Dialog | One component configured by props |
| Price | Free, MIT | Free, MIT | Wingo UI Pro |
| Shortcut | You write it | Docs example checks Meta or Ctrl + J | `shortcut="mod+k"`, label per device |
| Nested pages | A pattern in the README | You build it | `pages`, breadcrumb, Back restores the row |
| Async results | `Command.Loading`; you fetch | You build it | `loadItems`: debounce, abort, retry |
| Recents | Not included | Not included | Persisted by id |
| Phones | No layout | Centered dialog | Full-height sheet below 768px |

If people mostly search records (clients, invoices) with scopes and "See all" links, a header field fits better: [Global Search](https://wingo-ui.com/components/global-search) binds `/`, groups results by type and opens full screen on phones. It works next to a palette: `/` to search, ⌘K for commands.

#### How do I add a React command palette to a Next.js app?

Install it, hand the library your router once, and mount the menu in your app shell. `LinkProvider` lets link rows render through `next/link` (so Cmd+click opens a new tab) and lets Enter navigate with `router.push`:

```tsx
"use client";

import Link from "next/link";
import { usePathname, useRouter } from "next/navigation";
import type { ReactNode } from "react";
import { LinkProvider } from "@/lib/navigation";

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter();
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      {children}
    </LinkProvider>
  );
}
```

The menu, with navigation, actions, two pages and server search:

```tsx
"use client";

import { FolderOpen, Moon, Sun, SunMoon, UserPlus } from "lucide-react";
import { useTheme } from "next-themes";
import { CommandMenu, CommandMenuTrigger, commandItemsFromNav, type CommandGroup, type CommandPage } from "@/components/ui/command-menu";
import type { NavItem } from "@/lib/navigation";

const nav: NavItem[] = [
  { label: "Clients", href: "/clients" },
  { label: "Invoices", href: "/invoices", items: [{ label: "Overdue", href: "/invoices/overdue" }] },
];

async function search<T>(url: string, signal: AbortSignal): Promise<T[]> {
  const res = await fetch(url, { signal });
  if (!res.ok) throw new Error(`search failed: ${res.status}`);
  return res.json();
}

export function AppCommandMenu() {
  const { setTheme } = useTheme();

  const groups: CommandGroup[] = [
    { label: "Go to", items: commandItemsFromNav(nav) },
    {
      label: "Actions",
      items: [
        { id: "new-client", label: "New client", icon: <UserPlus />, shortcut: "alt+n", href: "/clients/new" },
        { id: "open-project", label: "Open project…", icon: <FolderOpen />, page: "projects" },
        { id: "theme", label: "Theme…", icon: <SunMoon />, page: "theme" },
      ],
    },
  ];

  const pages: CommandPage[] = [
    {
      id: "theme",
      title: "Theme",
      groups: [
        {
          items: [
            { id: "light", label: "Light", icon: <Sun />, onSelect: () => setTheme("light") },
            { id: "dark", label: "Dark", icon: <Moon />, onSelect: () => setTheme("dark") },
          ],
        },
      ],
    },
    {
      id: "projects",
      title: "Projects",
      placeholder: "Find a project…",
      // a page loader also runs for the empty query, so the page opens with a list
      loadItems: async (query, { signal }) => {
        const projects = await search<{ id: string; name: string }>(`/api/projects?q=${encodeURIComponent(query)}`, signal);
        return [{ items: projects.map((p) => ({ id: `project:${p.id}`, label: p.name, href: `/projects/${p.id}` })) }];
      },
    },
  ];

  return (
    <CommandMenu
      groups={groups}
      pages={pages}
      loadItems={async (query, { signal }) => {
        const clients = await search<{ id: string; name: string; city: string }>(`/api/clients?q=${encodeURIComponent(query)}`, signal);
        return [{ label: "Clients", items: clients.map((c) => ({ id: `client:${c.id}`, label: c.name, description: c.city, href: `/clients/${c.id}` })) }];
      }}
      trigger={<CommandMenuTrigger />}
    />
  );
}
```

`commandItemsFromNav` turns your sidebar items into "Go to" rows, and nested ones read "Invoices › Overdue". An `onSelect` that returns a promise keeps the menu open with a spinner on that row until it settles. Render `<AppCommandMenu />` in your app header, inside `Providers` and the next-themes `ThemeProvider`, so link rows reach the router and the Theme page can switch themes.

The Command Menu and Global Search are part of Wingo UI Pro, $8 a month, $80 a year or $150 once as of October 2026 ([pricing](https://wingo-ui.com/pricing)). Kbd and useShortcut are free: `npx wingo-ui@latest add kbd use-shortcut`. More in the [component guides](https://wingo-ui.com/blog/category/components), starting with the [React form components guide](https://wingo-ui.com/blog/react-form-components-guide).

#### Components in this post

- [Command Menu](https://wingo-ui.com/components/command-menu) (Pro): The ⌘K palette: search and run anything with groups, shortcuts, nested pages, async results and recents, and a full-height sheet on phones. Install: `npx wingo-ui@latest add command-menu`
- [useShortcut](https://wingo-ui.com/components/use-shortcut) (Free): Keyboard shortcuts in mod+k notation: bind them, match events and show them as ⌘K on a Mac or Ctrl+K elsewhere. Install: `npx wingo-ui@latest add use-shortcut`
- [Kbd](https://wingo-ui.com/components/kbd) (Free): Keyboard keys and combos in the notation of the device: ⌘K on a Mac, Ctrl+K everywhere else. Install: `npx wingo-ui@latest add kbd`
- [Global Search](https://wingo-ui.com/components/global-search) (Pro): The search field of an app header: grouped results from every entity as you type, scopes, recents and suggestions, full-screen on phones. Install: `npx wingo-ui@latest add global-search`

#### FAQ

##### How do I open a command palette with Cmd+K in React?

Listen for keydown on window and toggle the palette when Meta and K are pressed on Apple devices, or Control and K elsewhere, then call preventDefault so the browser's own Ctrl+K search does not run. Wingo UI's free useShortcut hook, called as useShortcut("mod+k", toggle), does the platform check and also matches the physical K key on non-Latin layouts.

##### Does cmdk filter async results?

Yes, by default cmdk filters and sorts every rendered item, server results included. Set shouldFilter={false} on Command when you filter yourself or the server already returns matches, and render Command.Loading while the request runs.

##### How many items can cmdk handle?

The cmdk README says it has no virtualization and performs well up to 2,000 to 3,000 items. Past that, search on the server and return the top matches.

##### Why does a second Ctrl+K not close my cmdk palette on Windows?

cmdk's vimBindings prop defaults to true, so Ctrl+J and Ctrl+K inside the palette move the highlight and call preventDefault. A shortcut listener that skips handled events then ignores the press; pass vimBindings={false} if you want Ctrl+K to toggle.

##### How should a command palette work on mobile?

Give it a visible search button, since phones have no Cmd key, and open it as a full-height sheet with the input focused inside the tap so iOS raises the keyboard. Use 16px input text so Safari does not zoom, and rows at least 44px tall.

##### Is the Wingo UI command menu free?

No. The Command Menu and Global Search are part of Wingo UI Pro. The Kbd component and the useShortcut hook are free and install with npx wingo-ui@latest add kbd use-shortcut.

---

Source: https://wingo-ui.com/blog/react-command-palette

### React Form Components: Accessible Fields, Zod and Mobile

> React form components that share one anatomy (label, hint, error, counter), plug into react-hook-form and zod, and behave right on a phone, with full code.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 21 min
- Canonical: https://wingo-ui.com/blog/react-form-components-guide

#### TL;DR

Good React form components share one anatomy: a label tied to the control, one message row that shows the hint or the error, and a counter when there is a limit, with the ids and aria attributes wired for you. Connect them to react-hook-form with register for native inputs and Controller for everything else, and validate with one zod schema once a field has been left. On phones, every control needs 16px text, the right keypad, 44px targets and a bottom sheet instead of a popover.

Every product ships the same handful of forms: sign up, checkout, settings, a filter panel, a support request. The controls differ, the bugs repeat. A label that is not tied to its input, an error that shows up only as a red border, a date picker that opens a small popover under your thumb, a custom select that the browser's autofill skips. This guide treats React form components as one set: which controls a product needs, the anatomy they should share, how to wire them to react-hook-form and zod, and what each one should do on a phone. The examples use Wingo UI, the library we build, so we are not neutral; outside facts link to their sources and are dated.

#### Which form controls does a product actually need?

The fifteen kinds of input in the table below cover the forms most products ship. Pick each one by what the person is entering, then check what it does on a phone. Most React input components look alike on a desktop. They split apart at 390px, where a popover has no room and a 32px target is too small for a thumb.

| What people enter | Component | On a phone |
| --- | --- | --- |
| Short text, email, URL | [Input](https://wingo-ui.com/components/input) (Free) | 16px text, keypad from the `type`, 44px box |
| Long text | [Textarea](https://wingo-ui.com/components/textarea) (Free) | Grows line by line, return makes a new line |
| One of 2 to 5 visible options | [Radio Group](https://wingo-ui.com/components/radio-group), [Segmented Control](https://wingo-ui.com/components/segmented-control) (Free) | 44px targets, a radio's whole row is one |
| One of a known list | [Select](https://wingo-ui.com/components/select) (Free) | Bottom sheet with 48px rows |
| One of thousands, or from a server | [Combobox](https://wingo-ui.com/components/combobox) (Pro) | Full-height sheet with its own search box |
| Several of a list | [Multi-select](https://wingo-ui.com/components/multi-select) (Pro) | Sheet with a "Done (3)" footer |
| Consent to terms | [Checkbox](https://wingo-ui.com/components/checkbox) (Free) | The whole row is a 44px target |
| A setting that applies at once | [Switch](https://wingo-ui.com/components/switch) (Free) | Drags like the iOS switch |
| A number or an amount | [Number Input](https://wingo-ui.com/components/number-input), [Currency Input](https://wingo-ui.com/components/currency-input) (Pro) | Numeric or decimal keypad, 44px steppers or amount chips |
| A date | [Date Picker](https://wingo-ui.com/components/date-picker) (Pro) | No keyboard: a sheet with 44px days |
| A time of day | [Time Picker](https://wingo-ui.com/components/time-picker) (Pro) | Wheels in a sheet |
| A phone number | [Phone Input](https://wingo-ui.com/components/phone-input) (Pro) | Phone keypad, country list in a sheet |
| A one-time code | [OTP Input](https://wingo-ui.com/components/otp-input) (Free) | Numeric keypad, code autofill |
| A password | [Password Input](https://wingo-ui.com/components/password-input) (Pro) | 44px reveal button |
| Files and photos | [File Upload](https://wingo-ui.com/components/file-upload) (Pro) | "Tap to choose files", an optional camera button |

In the catalog these sit in two categories, [Inputs](https://wingo-ui.com/components/category/inputs) with 36 items and [Forms](https://wingo-ui.com/components/category/forms) with 8, as of release 1.7.0. Two choices in this table are easy to get wrong, so here is where we land.

Choosing one option is three different controls. If people should compare the options at a glance (shipping speed, plan, size), show them all with a radio group or a segmented control; a select hides the choice behind a tap and saves nothing at four options. A select fits a known list that people can scan: states, categories, a few hundred time zones. A combobox fits when typing is faster than scrolling, the list comes from a server, or a free text answer is allowed.

Numbers are the other trap. A native `type="number"` field ignores `maxLength` ([MDN lists the attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#attributes) only for text, search, url, tel, email and password inputs), accepts exponent input such as `1e5`, and in some desktop browsers a scroll over the focused field changes its value. Our Input renders `type="number"` as a text field with a decimal keypad, so `maxLength` works and a scroll never changes the value.

#### What anatomy should every form field share?

Every field should have the same three parts in the same order: a label above the control, the control's box, and one message row under it. The message row shows either the hint or the error, never both, and a counter at its end when the field has a limit. In accessible form fields, the parts people forget are the ones nobody sees: the ids, the live region and what a screen reader hears.

- **Label.** A real `<label>` with `htmlFor` pointing at the control's id, so clicking it focuses the field and screen readers name the control. The required mark after it is hidden from screen readers, because the control itself carries `required`. When most fields are required, mark the few optional ones instead.
- **Hint.** Helper text under the box, linked with `aria-describedby`, so it is read after the label.
- **Error.** It replaces the hint. The control's `aria-describedby` switches to the error's id, `aria-invalid` turns on, and the box gets a red ring plus an icon and the text. [WCAG 2.2 success criterion 3.3.1](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (Level A) requires that an automatically detected error is identified and "described to the user in text", so a red border alone fails.
- **Counter.** "12 / 70" at the end of the message row, amber from 90% and red at the limit. The visible counter is hidden from screen readers, which instead hear "7 characters left" once 10% or less remains, half a second after typing stops. Reading the count on every keystroke is noise.

Swapping the hint for the error, instead of stacking the error under it, means a field with a hint barely changes height when the error appears. The row opens and closes with a short collapse animation and the hint crossfades into the error, so the fields under it glide instead of jumping. The row stays mounted as a polite live region, which means a new error is announced once, without stealing focus.

In Wingo UI the anatomy is the free [Field](https://wingo-ui.com/components/field). You can wrap any native control in it, and your own components can join it with one hook:

```tsx
"use client";

import type { ComponentProps } from "react";
import { FIELD_INPUT, Field, FieldAddon, FieldBox, FieldControl, useFieldControl } from "@/components/ui/field";

// any native control: Field draws the label and messages, FieldControl wires the ids and aria onto the input
export function PriceField({ error }: { error?: string }) {
  return (
    <Field label="Price" description="The final price, tax included." error={error} required>
      <FieldBox>
        <FieldControl>
          <input name="price" inputMode="decimal" placeholder="0" autoComplete="off" className={FIELD_INPUT} />
        </FieldControl>
        <FieldAddon>USD</FieldAddon>
      </FieldBox>
    </Field>
  );
}

type PlainInputProps = ComponentProps<"input"> & { label?: string; description?: string; error?: string };

// your own control: one hook, and it works alone or inside a <Field>
export function PlainInput({ id, label, description, error, required, disabled, readOnly, ...props }: PlainInputProps) {
  // the flags go through the hook: controlProps sets id, required, disabled and readOnly on the input
  const field = useFieldControl({ id, label, description, error, required, disabled, readOnly });
  return field.wrap(
    <FieldBox invalid={field.invalid} disabled={field.disabled} readOnly={field.readOnly}>
      <input {...props} {...field.controlProps} className={FIELD_INPUT} />
    </FieldBox>,
  );
}
```

`FieldControl` puts the Field's id, `aria-describedby`, `aria-invalid` and `aria-required` on its child, and the child's own props win. `useFieldControl` returns the same ids and flags for a custom control, plus `wrap()`, which draws the label and message row around the control when it has its own label or error, and does nothing when a parent Field already does. Pass `required`, `disabled` and `readOnly` through the hook, not straight onto the input: `controlProps` always carries those keys, so spreading it after your own props would reset them to `undefined`.

> Live demo (Field): Press Continue with a title under 10 characters: the error replaces the hint and the fields below glide down; type and it slides away again. Try it at [Field](https://wingo-ui.com/components/field) and install it with `npx wingo-ui@latest add field`.

The demo is a listing form with a 70 character title, a required price with a USD suffix and a city. The counter turns amber near the limit and the Continue button moves focus to the first field that needs fixing.

Libraries differ in how much of this wiring they do for you. As of October 2026, the [shadcn/ui Field](https://ui.shadcn.com/docs/components/field) is a set of layout parts: you connect `FieldLabel htmlFor` to the input's id yourself, put `data-invalid` on the Field and `aria-invalid` on the control, and pass messages to `FieldError`, which also accepts an `errors` array from react-hook-form. [React Aria's useField](https://react-aria.adobe.com/useField) goes the other way and "takes care of creating ids for each element and associating them with the correct ARIA attributes." Our Field sits closer to React Aria: the control reads the ids and flags from context. The explicit shadcn approach has one real advantage: there is no hidden context to debug, and if your team already lives in shadcn/ui it is a fine choice. We chose context because 31 of our controls take the same `error` prop and have to produce the same markup every time.

#### Why should every control take label, description and error props?

Because a form then reads as a flat list of fields, and swapping one control for another never changes the wiring. In Wingo UI, 31 controls as of release 1.7.0 (Input, Textarea, Select, Combobox, Phone Input, the date pickers, Checkbox, Switch, Radio Group, Slider and the rest) take `label`, `description` and `error` directly, most of them also `required`, `invalid`, `disabled` and `readOnly`, and render the Field anatomy themselves:

```tsx
"use client";

import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";
import { Input } from "@/components/ui/input";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select } from "@/components/ui/select";

const STATES = [
  { value: "CA", label: "California" },
  { value: "NY", label: "New York" },
  { value: "TX", label: "Texas" },
];

export function SameAnatomy() {
  const [title, setTitle] = useState("");
  return (
    <div className="flex flex-col gap-4">
      <Input
        label="Listing title"
        description="Brand, model and condition."
        value={title}
        onValueChange={setTitle}
        error={title && title.length < 10 ? "The title needs at least 10 characters." : undefined}
        showCount
        maxLength={70}
        required
      />
      <Select label="State" options={STATES} description="We ship to these states only." required />
      <PhoneInput label="Phone" defaultCountry="US" description="Only for delivery updates." />
      <DatePicker label="Delivery date" locale="en-US" error="We do not deliver on Sundays." />
    </div>
  );
}
```

Four different controls, one shape. Anything the Field takes beyond those props (an optional mark, a label action such as "Forgot your password?", a horizontal layout with a label column) goes through `fieldProps`, which Input, Select, Phone Input, Date Picker and most other controls accept. Sections of a form go in a `FieldGroup`, which is a real `<fieldset>` with a `<legend>`, so a screen reader announces "Shipping address" before the first field of the group. A disabled FieldGroup disables every field inside it, and its `columns` prop gives one column on phones and two from 640px.

Two details in this anatomy save real bugs. A click on a Select's label focuses the trigger without clicking it, so the word "State" never pops a list open. And the `name` prop on each of these four controls submits a value through a native or hidden input, which matters more than it sounds; there is a section on it below.

#### How do you wire react-hook-form and zod to these components?

Use `register` for controls that render a native input and pass the native `onChange`, `onBlur` and `ref` through, and `Controller` for everything else. Validate with one zod schema whose rules share one message set, and show errors once a field has been left. There is no special set of React Hook Form components to install: if a component forwards those three things to its focusable element, RHF can drive it.

The [form-validation](https://wingo-ui.com/components/form-validation) lib packages the form glue our blocks share: `createValidators()` returns zod rules with one set of messages (`text`, `name`, `email`, `password`, `phone`, `url`, `otp`, `accept` for a ticked checkbox, `number`, plus Romanian `cui`, `iban` and `postalCode`), `useZodForm(schema)` is `useForm` with the zod resolver and our timing, and `fieldError(form, "email")` turns a field's error into the string a component's `error` prop takes. Here is a delivery request form with seven fields:

```tsx
"use client";

import { Controller } from "react-hook-form";
import { z } from "zod";
import { addDays, startOfToday } from "date-fns";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { DatePicker } from "@/components/ui/date-picker";
import { Input } from "@/components/ui/input";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select, type SelectOption } from "@/components/ui/select";
import { Textarea } from "@/components/ui/textarea";
import { createValidators, fieldError, useZodForm } from "@/lib/form-validation";

const v = createValidators();

const STATES: SelectOption[] = [
  { value: "CA", label: "California", keywords: ["CA"] },
  { value: "NY", label: "New York", keywords: ["NY"] },
  { value: "TX", label: "Texas", keywords: ["TX"] },
  { value: "WA", label: "Washington", keywords: ["WA"] },
];

const schema = z.object({
  name: v.name(),
  email: v.email(),
  phone: v.phone({ country: "US" }),
  state: v.text(),
  deliveryDate: z.date({ error: v.messages.required }),
  notes: v.text({ required: false, max: 200 }),
  terms: v.accept(),
});

export type DeliveryRequest = z.output<typeof schema>;

export function DeliveryForm({ onSave }: { onSave: (values: DeliveryRequest) => Promise<void> }) {
  const form = useZodForm(schema, {
    defaultValues: { name: "", email: "", phone: "", state: "", notes: "", terms: false },
  });

  return (
    <form onSubmit={form.handleSubmit(onSave)} noValidate className="flex flex-col gap-4">
      {/* native inputs inside: register is enough */}
      <Input label="Full name" autoComplete="name" required {...form.register("name")} error={fieldError(form, "name")} />
      <Input
        label="Email"
        type="email"
        autoComplete="email"
        required
        {...form.register("email")}
        error={fieldError(form, "email")}
      />

      {/* everything else: Controller, with the ref so a failed submit can focus it */}
      <Controller
        control={form.control}
        name="phone"
        render={({ field }) => (
          <PhoneInput
            label="Phone"
            defaultCountry="US"
            preferredCountries={["US", "CA"]}
            required
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={(e164) => field.onChange(e164)}
            onBlur={field.onBlur}
            error={fieldError(form, "phone")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="state"
        render={({ field }) => (
          <Select
            label="State"
            placeholder="Choose the state"
            options={STATES}
            required
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={field.onChange}
            onBlur={field.onBlur}
            error={fieldError(form, "state")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="deliveryDate"
        render={({ field }) => (
          <DatePicker
            label="Delivery date"
            locale="en-US"
            min={addDays(startOfToday(), 1)}
            disabled={{ dayOfWeek: [0] }}
            required
            ref={field.ref}
            name={field.name}
            value={field.value ?? null}
            onValueChange={(date) => field.onChange(date ?? undefined)}
            onBlur={field.onBlur}
            error={fieldError(form, "deliveryDate")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="notes"
        render={({ field }) => (
          <Textarea
            label="Notes for the driver"
            maxLength={200}
            showCount
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={field.onChange}
            onBlur={field.onBlur}
            error={fieldError(form, "notes")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="terms"
        render={({ field }) => (
          <Checkbox
            label="I accept the delivery terms"
            ref={field.ref}
            name={field.name}
            checked={field.value === true}
            onCheckedChange={(checked) => field.onChange(checked === true)}
            onBlur={field.onBlur}
            error={fieldError(form, "terms")}
          />
        )}
      />
      <Button type="submit" size="lg" fullWidth loading={form.formState.isSubmitting}>
        Request delivery
      </Button>
    </form>
  );
}
```

Install the pieces with one command; the CLI brings react-hook-form, `@hookform/resolvers`, zod, libphonenumber-js and date-fns along:

```bash
npx wingo-ui@latest add form-validation input select phone-input date-picker textarea checkbox
```

The phone input, the date picker and the form-validation lib are Pro: run `npx wingo-ui@latest login` once with a Pro account, or the CLI stops and tells you to sign in. The code uses zod 4 and react-hook-form 7. A few lines in it carry more weight than they look.

##### Why validate once a field is left?

`useZodForm` sets `mode: "onTouched"` and `reValidateMode: "onChange"`. The [React Hook Form docs](https://react-hook-form.com/docs/useform) describe onTouched as validation that "is initially triggered on the first blur event. After that, it is triggered on every change event." So nobody hears that their email is invalid after typing one letter, and once an error shows, it clears on the keystroke that fixes it. The same docs warn that `mode: "onChange"` "often comes with a significant impact on performance", which is a second reason to avoid it on long forms.

##### Why pass field.ref to every Controller?

`shouldFocusError` is on by default, so a failed submit moves focus to the first field with an error, but only if RHF holds a ref to something focusable. The [Controller docs](https://react-hook-form.com/docs/usecontroller/controller) say to assign `field.ref` "to allow hook form to focus the error input". In these components `ref` is a plain prop (React 19, no `forwardRef`) and it lands on the element a person would focus: the Select's trigger button, the Phone Input's number input, the Date Picker's text input, the Checkbox's button. Our [React 19 forwardRef migration guide](https://wingo-ui.com/blog/react-19-forwardref-ref-as-prop) shows how to move your own fields to that pattern.

##### When is register not enough?

When the value is anything other than the string in a native input: an E.164 phone number, a `Date`, a boolean, a value picked from a list. Also when a text field shows a counter. Input and Textarea keep their length in their own state. They pick up a native form reset, but a value that RHF writes straight into the DOM with `setValue()` or `reset(values)` reaches the counter only when the field gets focus again. The notes field above goes through `Controller` for that reason, even though a native textarea sits inside it.

##### What about the date and the phone number?

The date picker reports `null` when cleared, so the form stores `undefined` instead and `z.date({ error })` fails with the required message. A typed date reaches the form only once it is complete and allowed, so a typed Sunday never does. The phone input reports an E.164 string such as `+12015550123` once the number is possible and an empty string before that. `v.phone({ country: "US" })` checks it with libphonenumber-js. The country only matters for values without a calling code, such as a number typed into a plain Input, and it defaults to `RO`, so set it on a US form.

`noValidate` on the form turns off the browser's own bubbles, so the zod messages are the only ones people see. Without it, an empty field with `required` makes the browser block the submit with its own tooltip, and `handleSubmit` never runs to show your messages.

> Live demo (Form validation): Submit the empty form: every error shows at once and focus jumps to the first one; fix a field and its error clears as you type. Try it at [Form validation](https://wingo-ui.com/components/form-validation) and install it with `npx wingo-ui@latest add form-validation`.

The demo is a sign-up form built on the same lib: name, email, phone, an optional company tax ID, a password with a strength rule and a terms checkbox.

##### Should the server validate the same schema?

Yes, always: the client schema is a convenience for people, and anything that reaches your server action or API route has to be checked again. The Next.js [forms guide](https://nextjs.org/docs/app/guides/forms) suggests parsing the submitted values with a schema library such as zod inside the Server Action. One catch with our lib today: `lib/form-validation.ts` starts with `"use client"` because it holds the `useZodForm` hook, so server code cannot call `createValidators()` from it. Write the server schema with zod directly, or, since the file is your source after install, move the rules into a module without the directive.

#### Do you need react-hook-form at all?

Not for a short form. If every control submits through a real input with a `name`, the browser's `FormData` already holds clean values, required fields block the submit natively, a form reset restores the defaults and autofill works. That is why the controls in this guide render something native when you pass `name`:

- **Select** renders a hidden native `<select>`, so `FormData`, `required`, form reset and browser autofill work. [MDN notes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) that browsers may require a `name` or `id` and an owning form before they offer autofill, which is exactly what a select built from divs lacks. Pass `autoComplete="address-level1"` (the state, in a US address) and the browser can fill it from a saved address.
- **Phone Input** renders a hidden input with the E.164 number, while the visible input shows the formatted national digits.
- **Date Picker** renders a hidden input with the local ISO date (`2026-10-23`, or `2026-10-23T14:30` with a time), never shifted to UTC, which avoids the off by one day bug that `toISOString()` causes east of UTC.
- **Checkbox** submits its `value` through Radix's hidden input while checked; **Input** and **Textarea** are native elements.

```tsx
"use client";

import type { FormEvent } from "react";
import { Button } from "@/components/ui/button";
import { DatePicker } from "@/components/ui/date-picker";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select } from "@/components/ui/select";

const STATES = [
  { value: "CA", label: "California" },
  { value: "NY", label: "New York" },
  { value: "TX", label: "Texas" },
];

export function QuoteForm({ onQuote }: { onQuote: (values: Record<string, FormDataEntryValue>) => void }) {
  const submit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    // { phone: "+12015550123", state: "NY", pickup: "2026-10-23" }
    onQuote(Object.fromEntries(new FormData(event.currentTarget)));
  };

  return (
    <form onSubmit={submit} className="flex flex-col gap-4">
      <PhoneInput name="phone" label="Phone" defaultCountry="US" required />
      <Select name="state" label="State" options={STATES} autoComplete="address-level1" required />
      <DatePicker name="pickup" label="Pickup date" locale="en-US" />
      <Button type="submit">Get a quote</Button>
    </form>
  );
}
```

The same hidden inputs are what a Server Action receives when you pass it to `<form action>`, because the action is called with the form's `FormData`. Our rule of thumb: plain `FormData` for forms of up to five or six fields with simple rules; react-hook-form once you need cross-field rules (a password and its confirmation, which `withMatch` in the lib handles), errors that update while typing, dirty tracking for a "You have unsaved changes" prompt, or lists of fields people add and remove.

#### How should each control behave on a phone?

Fields you type into get 16px text, the right keypad and the right Enter key. Fields you choose from open a bottom sheet instead of a popover. Nothing you tap has a hit area under 44px. The broader rulebook is in our guide to [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components); here is how it applies control by control.

##### Text fields: 16px, the keypad and the Enter key

Safari on iOS zooms the page when you focus a field whose text is smaller than 16px, and it does not zoom back out on blur ([Rick Strahl's write-up](https://weblog.west-wind.com/posts/2023/Apr/17/Preventing-iOS-Textbox-Auto-Zooming-and-ViewPort-Sizing) has the details). The fix is the font size. Avoid `maximum-scale=1` in the viewport meta tag: the same write-up notes that Android honors it and blocks pinch zoom, which hurts the people who rely on zooming. Every Wingo UI field box starts at `text-base` (16px) and switches to its desktop size from 768px up: `text-base md:text-sm` gives the md box 14px there.

The keypad follows `type` and `inputMode`: `email` adds the @ key, `tel` shows the phone pad, `decimal` shows digits and a separator. `autoComplete` with the right token (`name`, `email`, `tel-national`, `new-password`, `postal-code`) lets the browser fill the field, and `enterKeyHint="next"` on every field but the last (`"done"` there) labels the Enter key with what it will do. The md box is 40px with a mouse and 44px on touch screens through Tailwind's `pointer-coarse` variant, and the clear button keeps a 44px hit area even though it looks small.

##### Select and combobox: a sheet, and a keyboard that waits

Below 768px the Select opens a bottom sheet titled with the field's label, with 48px rows and the chosen row scrolled into view. A tap picks and closes. Lists of more than eight options get a search row at the top, but on a touch screen it waits for a tap before it takes focus, so the keyboard does not cover half the list you were about to scroll. The Combobox does the opposite on purpose: a tap opens a full-height sheet with the keyboard already up, because typing is the whole point of a combobox. Pass `responsive={false}` to keep the popover on phones, for example inside a sheet that is already full screen.

##### Dates and times: no keyboard

On a desktop, typing a date is faster than clicking one. The Date Picker reads "09232026" as 09/23/2026, "+3" as three days from today and "tomorrow" as tomorrow, and it formats the text the way the locale writes it. On a phone the field never raises the keyboard. A tap opens a sheet with one month of 44px days you can swipe between, plus a row of chips when you turn on `presets` (Today, Tomorrow, Next week, or your own). With `withTime`, the time field in the sheet opens its own wheel sheet. The Time Picker uses the same wheels, which snap like the iOS picker and give a short vibration tick per row where the browser supports the Vibration API.

##### Phone numbers: one clean value

The Phone Input raises the phone keypad, formats the number as the country writes it and keeps the caret after the digit you typed. Pasting or autofilling a number that starts with `+44` or `0044` switches the country by itself. The flag button opens the country list, which is a bottom sheet with search on phones, and you can search by country name, ISO code or calling code. Whatever the person types, your form receives one E.164 string.

> Live demo (Phone Input): Type a US number, then type or paste one that starts with +44: the flag switches to the United Kingdom, and the readout shows the clean value the form submits. Try it at [Phone Input](https://wingo-ui.com/components/phone-input) and install it with `npx wingo-ui@latest add phone-input`.

##### One-time codes: autofill first

The [OTP Input](https://wingo-ui.com/components/otp-input) puts `autocomplete="one-time-code"` on its first slot, which [MDN describes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) as the token for "a one-time password (OTP) for verifying user identity", so the browser can offer a code it received by text message. Slots raise the numeric keypad, a pasted code fills every slot at once, and Backspace clears a slot before it steps back.

It is also the one control in this guide that does not join the Field anatomy: it renders a row of single-character inputs, each named "Digit 1 of 6" and so on, and its error state is a red ring and a shake. Give the row a group name and put the error in text under it with `FieldMessage`, which works outside a Field:

```tsx
"use client";

import { useState } from "react";
import { FieldMessage } from "@/components/ui/field";
import OtpInput, { type OtpStatus } from "@/components/ui/otp-input";

export function VerifyPhone({ phone, verify }: { phone: string; verify: (code: string) => Promise<boolean> }) {
  const [status, setStatus] = useState<OtpStatus>("idle");

  return (
    <div className="flex flex-col gap-3">
      <p id="otp-title" className="text-sm text-muted-foreground">
        Enter the 6 digit code we sent to {phone}.
      </p>
      <OtpInput
        role="group"
        aria-labelledby="otp-title"
        length={6}
        status={status}
        autoFocus
        onChange={() => setStatus("idle")}
        onComplete={async (code) => setStatus((await verify(code)) ? "success" : "error")}
      />
      <FieldMessage error={status === "error" ? "That code is not right. Check the latest text message." : undefined} />
    </div>
  );
}
```

We skip react-hook-form here. A code screen has one value and one rule, and the answer comes from the server, so `onComplete` and a status are all the state it needs. When you do need it, our [React OTP input guide](https://wingo-ui.com/blog/react-otp-input) wires the code into react-hook-form and zod, explains why SMS autofill fails silently and adds a resend timer.

##### Numbers and money

The Number Input and the Currency Input read numbers the way the locale writes them: 1,234.5 in English, 1.234,5 in Romanian. The Number Input raises the numeric keypad, or the decimal one when `step` or `decimals` allows decimals, refuses keystrokes that can never become a valid number (a minus when `min` is 0 or more), and has steppers with a 44px hit area on touch. The Currency Input pads the cents on blur ("1.234,5" becomes "1.234,50") and shows quick amounts as chips through `presets`, which beat typing for tips and donations.

Test negative numbers on a real phone: [MDN notes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) that with the `numeric` and `decimal` input modes, "devices may or may not show a minus key". If yours does not, pass `inputMode="text"` to the Number Input or rely on the steppers.

#### When should a form show its errors?

Show an error after the person leaves the field, update it live while they fix it, and on submit show every error at once and move focus to the first. That is the `onTouched` timing from above, and it fits almost every form. A few rules around it:

- **Never on load.** An empty required field is not an error until someone has had a chance to fill it.
- **Keep the submit button enabled.** A disabled button gives no reason, and Tab skips it, so keyboard users cannot even reach it. Let the submit fail and show the errors.
- **Check slow things without blocking.** An Input with `loading` shows a spinner at the end of the box (in place of the trailing icon, if it has one), sets `aria-busy` and stays editable, so a username check runs while the person keeps typing.
- **Write errors as instructions.** "Enter a valid email address" tells people what to do; "Invalid input" makes them guess. Most of the lib's English messages follow that pattern, and `createValidators(VALIDATION_MESSAGES_RO)` swaps in the Romanian set in one line.

#### What should a React form components library give you?

A React form components library earns its place when it removes the wiring you would otherwise repeat in every field, and lets you change what it got wrong. Our checklist, which you can apply to any library, ours included (for prices and licenses, see our [shadcn/ui alternatives comparison](https://wingo-ui.com/blog/shadcn-alternatives)):

1. **One anatomy for every control**, with the label, hint, error and counter ids wired for you, and a hook to bring your own controls into it.
2. **Native form participation.** A `name` that ends up in `FormData`, `required` that blocks the submit, a form reset that restores defaults, and autofill that reaches custom selects.
3. **Controlled and uncontrolled modes**, and a `ref` that lands on the element a person would focus, so a form library can focus the first error.
4. **Phone behavior built into the same component**: 16px text, keypads, 44px targets, bottom sheets below 768px. A separate mobile component doubles every form.
5. **Source you own.** Wingo UI copies the files into your project, like shadcn/ui, so you can change a label, a timing or a schema rule without waiting for a release, and `npx wingo-ui@latest update` merges our later fixes into the files you edited. The same 3-way merge done by hand with git, for files from the shadcn CLI, is in our guide to [updating shadcn components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits).

Field, Input, Textarea, Select, Checkbox, Switch, Radio Group, Segmented Control and the OTP input are free. The phone input, the date and time pickers, Combobox, Multi-select, the number and currency inputs and the form-validation lib are part of Pro, which costs $8 a month, $80 a year or $150 once as of October 2026 (see [Wingo UI Pro pricing](https://wingo-ui.com/pricing)).

#### Which component guides go deeper?

These posts in the [component guides category](https://wingo-ui.com/blog/category/components) take one field, one rule or one component further:

- [React OTP input](https://wingo-ui.com/blog/react-otp-input): paste, SMS autofill, react-hook-form with zod and a resend timer.
- [Romanian CUI validation](https://wingo-ui.com/blog/romanian-cui-validation-javascript): the company tax ID check digit, a zod rule and a lookup that proves the company exists.
- [IBAN validation in JavaScript](https://wingo-ui.com/blog/iban-validation-javascript): the mod 97 check, why a regex is not enough and a field that formats as you type.
- [Romanian CNP validator](https://wingo-ui.com/blog/romanian-cnp-validator-javascript): decoding and validating a personal numeric code, and whether to store it at all.
- [TanStack Table v9 data table](https://wingo-ui.com/blog/tanstack-table-v9-data-table): filters, bulk actions, pinning and server pagination, with cards on phones.
- [React command palette](https://wingo-ui.com/blog/react-command-palette): Cmd+K with nested pages, async results and a full-height sheet on phones.
- [dnd kit on mobile](https://wingo-ui.com/blog/dnd-kit-mobile-touch-drag): touch drag that still lets the page scroll, and a tap path for people who cannot drag.
- [Updating shadcn components](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits): pulling upstream fixes into files you already edited.

#### Where should you start?

Install the free anatomy and the controls most forms need, then build one real form with them:

```bash
npx wingo-ui@latest add field input textarea select checkbox
```

The command copies the source files into your project, installs the npm packages they import and records the versions, so later updates can merge into your edits. In a project without a `wingo-ui.json`, run `npx wingo-ui@latest init` first. Open the [Field docs](https://wingo-ui.com/components/field) for the playground and every prop, and add the phone, date and validation pieces when your forms need them.

#### Components in this post

- [Field](https://wingo-ui.com/components/field) (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: `npx wingo-ui@latest add field`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`
- [Select](https://wingo-ui.com/components/select) (Free): A custom select with search, groups, icons, thousands of virtualized rows and a hidden native select for forms. Install: `npx wingo-ui@latest add select`
- [OTP Input](https://wingo-ui.com/components/otp-input) (Free): A one-time-code input whose characters roll into place behind a caret that slides from slot to slot. Install: `npx wingo-ui@latest add otp-input`
- [Phone Input](https://wingo-ui.com/components/phone-input) (Pro): A phone number field with a searchable country picker, formatting as you type, validation and one clean E.164 value out. Install: `npx wingo-ui@latest add phone-input`
- [Date Picker](https://wingo-ui.com/components/date-picker) (Pro): A date field to type in your locale or pick from a calendar popover, with presets, limits and an optional time; a sheet on phones. Install: `npx wingo-ui@latest add date-picker`
- [Form validation](https://wingo-ui.com/components/form-validation) (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: `npx wingo-ui@latest add form-validation`
- [Textarea](https://wingo-ui.com/components/textarea) (Free): Multi-line text that grows with what you write, with a counter, an optional resize handle, a toolbar slot and mod+enter to submit. Install: `npx wingo-ui@latest add textarea`
- [Checkbox](https://wingo-ui.com/components/checkbox) (Free): A box that is on, off or mixed with a check that draws itself, a label row that is the whole target, cards, and groups with select all. Install: `npx wingo-ui@latest add checkbox`

#### FAQ

##### Do I need react-hook-form to build forms in React?

No. A short form works with native inputs, name attributes and FormData, and Wingo UI's Input, Textarea, Select, Checkbox, Phone Input and Date Picker all submit their value through a native or hidden input once they have a name. React Hook Form pays off once you need per-field validation timing, cross-field rules, dirty state or field arrays.

##### How do I use react-hook-form with custom components?

Use register when the component renders a native input and passes onChange, onBlur and ref through to it, like a text input. Use Controller for anything whose value is not a string in a native input (a select, a date, a phone number, a checkbox), and pass field.ref so a failed submit can focus it.

##### How do I make form fields accessible in React?

Tie every label to its control with htmlFor and id, point aria-describedby at the hint or, while it shows, the error, and set aria-invalid on the invalid control. Describe each error in text instead of color alone, announce it through a polite live region, and move focus to the first invalid field when a submit fails.

##### Why does my iPhone zoom in when I tap an input?

Safari on iOS zooms the page when the focused field's text is smaller than 16px. Give inputs 16px text on phones and go smaller from a wider breakpoint if you want, instead of turning off pinch zoom in the viewport meta tag.

##### Should I use a select, a radio group or a combobox?

Use a radio group or a segmented control for two to five options people should compare at a glance, a select for a known list up to a few hundred options, and a combobox when the list is huge, comes from a server or accepts free text.

##### Which Wingo UI form components are free?

Field, Input, Textarea, Select, Checkbox, Switch, Radio Group, Segmented Control, Search Input, Listbox and the OTP input are free. The phone input, the date and time pickers, Combobox, Multi-select, the number, currency, password and email inputs, File Upload and the form-validation lib are Pro.

---

Source: https://wingo-ui.com/blog/react-form-components-guide

### React OTP Input: Paste, SMS Autofill and a Resend Timer

> How to build a React OTP input that takes paste and SMS autofill, why autocomplete one-time-code fails silently, and how to add zod checks and a resend timer.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/react-otp-input

#### TL;DR

A React OTP input should put autocomplete="one-time-code" on the slot that receives the code, leave out maxLength={1}, spread a pasted or autofilled code across every slot, and clear a slot before Backspace steps back; the free Wingo UI OTP Input does all of that. Android needs one more piece, the WebOTP API, because Chrome documents SMS codes for the web through that API instead of the attribute. For the resend timer, lock the button for a fixed wait after each send, store when the wait ends, and enforce the same wait on the server.

A verification code screen looks like an afternoon of work: six boxes, focus jumps forward, done. The bugs show up later, on real phones. Six inputs capped at one character each turn the code the iPhone offers above the keyboard, or a pasted one, into a single digit. Backspace on an empty box does nothing, and the resend link fires as fast as someone can tap it. This guide covers what a React OTP input has to handle, why SMS autofill fails without an error, and a complete verify form with react-hook-form, zod and a resend timer. The examples use the free [OTP Input](https://wingo-ui.com/components/otp-input) from Wingo UI, the library we build, so we are not neutral; outside facts link to their sources.

#### What should a React OTP input handle?

It has to accept a code four ways (typing, paste, the keyboard's suggestion from a text message and, on Android, the WebOTP API) and still edit like one field. Our checklist, and a fair test for any library:

- **Typing** moves to the next slot, arrows move between slots, and a tap past the first empty slot lands on that slot, so typing never skips one.
- **Paste** fills the slots at once and keeps only the characters they accept, so "123 456" and "Your code is 123456" both fill six digits.
- **SMS autofill** needs `autocomplete="one-time-code"` on the slot that receives the code, and no one-character limit on it.
- **Backspace** clears the slot you are in. The next press steps back and clears the one before.
- **The right keyboard**: `inputMode="numeric"` for digits, a full keyboard with capitals for `type="letters"` or `"both"`.
- **Feedback**: `status="error"` rings the slots red and shakes the row once, `"success"` traces a green ring around each slot, and reduced motion turns the motion off.
- **Names**: each slot reads as "Digit 1 of 6" (`slotLabel` translates it), the row needs a group label, and the error needs words next to the red ring.

Install it and drop it into a client component:

```bash
npx wingo-ui@latest add otp-input
```

```tsx
"use client";

import { useState } from "react";
import OtpInput, { type OtpStatus } from "@/components/ui/otp-input";

export function CodeStep({ check }: { check: (code: string) => Promise<boolean> }) {
  const [status, setStatus] = useState<OtpStatus>("idle");

  return (
    <OtpInput
      role="group"
      aria-label="Verification code"
      length={6}
      autoFocus
      status={status}
      onChange={() => setStatus("idle")}
      onComplete={async (code) => setStatus((await check(code)) ? "success" : "error")}
    />
  );
}
```

`length` sets the slot count (4 for a PIN), `type` the accepted characters, `mask` hides them like a password field, and `size` picks 40, 48 or 56px slots. The `sm` size grows to 44px on touch screens, and in a container narrower than the row the slots shrink evenly and stay square, so eight slots still fit a 360px phone. More on sizing for thumbs in [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components).

> Live demo (OTP Input): Type 123456 to see the success ring, or any other code to see the error shake. Then clear it and paste a code with a space in it, like 123 456. Try it at [OTP Input](https://wingo-ui.com/components/otp-input) and install it with `npx wingo-ui@latest add otp-input`.

#### How does autocomplete one-time-code autofill work?

The `autocomplete="one-time-code"` attribute is a hint to the browser. The operating system spots a code in an incoming text message, and when the focused field carries that token, the keyboard offers the code; one tap inserts the whole code into that field at once. [MDN defines the token](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) as "a one-time password (OTP) for verifying user identity that is used as an additional factor in a sign-in flow."

Support for autocomplete one-time-code depends on the platform. [web.dev's SMS OTP form guide](https://web.dev/articles/sms-otp-form) (last updated December 2020, still the current version when we checked in October 2026) says the attribute works in Safari 12 and later on iOS, iPadOS and macOS, while Chrome, Opera and Vivaldi on Android support origin-bound codes through the WebOTP API, "though not through `autocomplete="one-time-code"`."

Since iOS 14 and macOS Big Sur, Apple also lets you bind a code to your domain. Per [Apple's documentation on domain-bound codes](https://developer.apple.com/documentation/security/enabling-autofill-for-domain-bound-sms-codes), the last line of the message carries your domain after an `@` and the code after a `#`, separated by a space, and AutoFill only suggests a domain-bound code when the site open in Safari matches that domain:

```text
Your Example code is 123456.

@example.com #123456
```

Chrome's WebOTP API reads the same last line, so one message format serves both platforms.

The OTP Input puts the token on its first slot and sets the others to `off`. Its slots have no `maxLength`, so an inserted code arrives in one change event, which the component treats like a paste and spreads across the slots. A tap on an empty row always lands on the first slot, so an autofilled code starts where it should.

#### Why does React OTP input autofill fail silently?

Autofill fails silently because a missed condition is not an error: the keyboard shows no suggestion and nothing reaches the console. The cause sits in the markup, the message or the test setup. The ones we check, in order:

1. **Each slot has `maxLength={1}`.** The limit caps whatever a person inserts, a tap on the suggested code included, so only the first digit lands. Drop the limit and filter in the change handler.
2. **The token is missing or overridden.** A wrapper that does not forward `autoComplete`, or an `autocomplete="off"` someone added to stop a different autofill. MDN describes `off` as "the browser is not permitted to automatically enter or select a value for this field."
3. **The message is bound to another domain.** A code that ends in `@example.com #123456` will not be offered on a preview deployment or a staging host on another domain. Make the domain in the message a per-environment setting.
4. **You are testing on Android with the attribute alone.** Chrome documents the WebOTP API for this; see the next section.
5. **The listener started late, or the page is on plain HTTP.** [Chrome's WebOTP guide](https://developer.chrome.com/docs/identity/web-apis/web-otp) says the message "must be sent after `navigator.credentials.get()` is called", so show the code step as soon as the send request starts, not after a redirect. The API also exists only in secure contexts, so opening your dev server from a phone at `http://192.168.1.20:3000` turns the feature check false. Use an HTTPS tunnel.
6. **The code does not fit the slots.** An 8 character code sent to a 6 slot input loses its last two characters, and a code with letters loses its letters when `type` is `"numbers"`. Match `length` and `type` to what your server sends.
7. **You tested in an emulator or a headless browser.** The [input-otp README](https://github.com/guilhermerodz/input-otp) notes that SMS autofill "cannot be covered headlessly". Test on a real phone with a real message.

#### How do I read the code with the WebOTP API on Android?

Call `navigator.credentials.get({ otp: { transport: ["sms"] } })` when the code screen mounts, abort it on unmount, and write the code into the input's value. When a matching message arrives, Chrome asks the person to confirm in a bottom sheet, then resolves the promise with the code. Feature-detect it: MDN marks the API as experimental and not Baseline, and Safari relies on the attribute instead. Save this as `hooks/use-web-otp.ts`:

```tsx
import { useEffect, useEffectEvent } from "react";

type OtpCredential = Credential & { code: string };

// android chrome: waits for an sms whose last line is "@your-domain #123456" and hands over the code.
// mount it before the message goes out; bump `attempt` to listen again after a resend
export function useWebOtp(onCode: (code: string) => void, attempt = 0) {
  const receive = useEffectEvent(onCode);

  useEffect(() => {
    if (!("OTPCredential" in window)) return;
    const controller = new AbortController();
    navigator.credentials
      .get({ otp: { transport: ["sms"] }, signal: controller.signal } as CredentialRequestOptions)
      .then((credential) => {
        const code = (credential as OtpCredential | null)?.code;
        if (code) receive(code);
      })
      .catch(() => {
        // aborted, dismissed or no message: typing still works
      });
    return () => controller.abort();
  }, [attempt]);
}
```

The cast is there because TypeScript's DOM types lack the `otp` option, and `useEffectEvent` needs React 19.2, which the Next.js 16 App Router uses. Each `get()` call resolves once, so `attempt` restarts the listener after a resend. Inside a cross-origin iframe the API also needs the `otp-credentials` permission, per [MDN's WebOTP page](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API).

#### How do I validate an OTP input with React Hook Form and zod?

Wrap it in `Controller` and validate the joined string with zod. A React Hook Form OTP input needs `Controller` because `register` reads and resets native inputs through a `ref`, while the OTP Input is a row of inputs with one string value. For the label, hint and error, put it in a [Field](https://wingo-ui.com/components/field) with `labelAs="span"` and let `FieldControl` pass the ids to the row: the group gets `aria-labelledby` and `aria-describedby`, and a click on the label focuses the first slot.

The full verify step uses the WebOTP hook above, a resend timer and a [Button](https://wingo-ui.com/components/button) for each action. Install what it imports (useCooldown is a Pro item):

```bash
npm install react-hook-form @hookform/resolvers zod
npx wingo-ui@latest add otp-input field button use-cooldown
```

The component takes `verify` and `resend` as props, so a Next.js page can pass two Server Actions:

```tsx
"use client";

import { useState } from "react";
import { Controller, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { Field, FieldControl } from "@/components/ui/field";
import OtpInput, { type OtpStatus } from "@/components/ui/otp-input";
import { useCooldown } from "@/hooks/use-cooldown";
import { useWebOtp } from "@/hooks/use-web-otp";

const schema = z.object({
  code: z.string().regex(/^\d{6}$/, "Enter the 6 digit code."),
});

type Props = {
  phone: string;
  verify: (code: string) => Promise<boolean>;
  resend: () => Promise<void>;
};

export function VerifyCode({ phone, verify, resend }: Props) {
  const [status, setStatus] = useState<OtpStatus>("idle");
  const [sent, setSent] = useState(0);
  const cooldown = useCooldown({ seconds: 30, autoStart: true, persistKey: "verify-resend" });
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { code: "" },
    reValidateMode: "onSubmit",
  });

  const submit = form.handleSubmit(async ({ code }) => {
    if (await verify(code)) {
      setStatus("success");
      return;
    }
    setStatus("error");
    form.setValue("code", "");
    form.setError("code", { message: "That code did not work. Check the latest text message." });
    document.querySelector<HTMLInputElement>("#verify-code input")?.focus();
  });

  // android chrome: the code arrives through WebOTP, fills the slots and submits
  useWebOtp((code) => {
    form.setValue("code", code);
    void submit();
  }, sent);

  return (
    <form noValidate onSubmit={submit} className="flex flex-col gap-4">
      <Controller
        control={form.control}
        name="code"
        render={({ field, fieldState }) => (
          <Field
            id="verify-code"
            label="Verification code"
            labelAs="span"
            description={`We sent a 6 digit code to ${phone}.`}
            error={fieldState.error?.message}
          >
            <FieldControl>
              <OtpInput
                role="group"
                autoFocus
                value={field.value}
                status={status}
                onChange={(code) => {
                  field.onChange(code);
                  setStatus("idle");
                  form.clearErrors("code");
                }}
                // the last digit submits, whether it was typed, pasted or autofilled
                onComplete={() => {
                  if (!form.formState.isSubmitting) void submit();
                }}
              />
            </FieldControl>
          </Field>
        )}
      />
      <Button type="submit" fullWidth loading={form.formState.isSubmitting}>
        Verify
      </Button>
      <Button
        type="button"
        variant="ghost"
        fullWidth
        disabled={cooldown.active}
        onClick={() => {
          // the wait starts before the request, so a double tap cannot send two messages
          cooldown.start();
          setSent((count) => count + 1);
          void resend();
        }}
      >
        <span className="tabular-nums">
          {cooldown.active ? `Resend code in ${cooldown.label}` : "Resend code"}
        </span>
      </Button>
    </form>
  );
}
```

Three details worth copying:

- **`reValidateMode: "onSubmit"`** stops "Enter the 6 digit code." from flashing during a retype, and `clearErrors` in `onChange` hides the old message on the first keystroke.
- **A wrong code clears the slots and focuses the first one.** `field.ref` would land on the row's wrapper `div`, which cannot take focus, so the example finds the first slot by the Field's id.
- **Without React Hook Form**, in a form that posts to a Server Action, render `<input type="hidden" name="code" value={code} />` next to the row. The slots have no `name`, so `FormData` would not see them.

#### How do I add a resend timer to an OTP screen?

Lock the resend button for a fixed wait after every send, and store when the wait ends instead of counting a number down. A `setInterval` counter drifts when the phone locks or the tab sleeps, and a reload hands out a fresh button. The [useCooldown hook](https://wingo-ui.com/components/use-cooldown) keeps the end time, ticks once a second aligned to it, survives a reload with `persistKey`, and with `autoStart` opens the screen already waiting, since the first code was just sent.

> Live demo (useCooldown): Press Resend code: the button locks and counts down from 0:30 while the ring fills, then turns back on by itself. Try it at [useCooldown](https://wingo-ui.com/components/use-cooldown) and install it with `npx wingo-ui@latest add use-cooldown`.

The hook returns `remaining`, `active`, `progress` for a ring and a `label` such as "0:42" for the button. The button only protects honest users: anyone can call your send endpoint directly, so enforce the same wait and a daily cap on the server, per phone number and IP address. useCooldown is part of Wingo UI Pro; if you write your own, keep the end timestamp in state and compute the seconds left from `Date.now()` on each tick.

#### Should you use the shadcn OTP input instead?

Use the [shadcn OTP input](https://ui.shadcn.com/docs/components/input-otp) when you already use shadcn/ui, want a separator between two groups of three, or want the code in one real input. Use Wingo UI's OTP Input for built-in success and error states, touch sizing and a single element configured by props. The shadcn version is built on input-otp, which renders one text input, makes it invisible and draws the slots from its state; ours renders one input per slot. Both handle paste and SMS autofill. As of October 2026:

| | shadcn/ui Input OTP | Wingo UI OTP Input |
| --- | --- | --- |
| Under the hood | input-otp, one invisible input | One input per slot |
| API | Composed: `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator` | One element with props (`length`, `type`, `size`, `status`, `mask`, colors) |
| Accepted characters | `pattern` regex, such as `REGEXP_ONLY_DIGITS` | `type`: numbers, letters or both |
| Separator between groups | Yes, `InputOTPSeparator` | No |
| Form value | One input with a `name`, so `FormData` sees the code | No `name` on the slots; add a hidden input |
| Feedback states | Error styling through `aria-invalid` on the slots | Red ring and a shake for errors, a green ring for success, reduced motion respected |
| Install | `npx shadcn@latest add input-otp` | `npx wingo-ui@latest add otp-input` |

The [input-otp README](https://github.com/guilhermerodz/input-otp) also lists what a single input keeps from a native text field: undo, select-all, a partial paste into the middle of a half-filled code, and room for password manager badges. Our slots handle paste, Backspace and the arrow keys in code, but undo and select-all stop at a single slot.

#### How do I add the OTP input to a Next.js project?

Run the add command in a Next.js project with Tailwind CSS v4. The CLI copies the source files into your project and installs the npm packages they import:

```bash
npx wingo-ui@latest add otp-input field button
```

The [OTP Input docs](https://wingo-ui.com/components/otp-input) have the playground and every prop. To start from a finished screen instead, the [Login Page](https://wingo-ui.com/components/login-page) block ships this flow inside a sign-in page: a code view, a resend timer and a 60 second lock after three wrong codes. The Login Page and useCooldown are part of Wingo UI Pro, which costs $8 a month, $80 a year or $150 once as of October 2026 ([Wingo UI pricing](https://wingo-ui.com/pricing)). For the rest of a form, read the [React form components guide](https://wingo-ui.com/blog/react-form-components-guide); more guides live in the [component guides category](https://wingo-ui.com/blog/category/components).

#### Components in this post

- [OTP Input](https://wingo-ui.com/components/otp-input) (Free): A one-time-code input whose characters roll into place behind a caret that slides from slot to slot. Install: `npx wingo-ui@latest add otp-input`
- [useCooldown](https://wingo-ui.com/components/use-cooldown) (Pro): A resend or retry timer: wait N seconds before a code can be sent again, exact after the tab sleeps and kept across reloads. Install: `npx wingo-ui@latest add use-cooldown`
- [Field](https://wingo-ui.com/components/field) (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: `npx wingo-ui@latest add field`

#### FAQ

##### How do I autofill an OTP from SMS in React?

Put autocomplete="one-time-code" on the input that receives the code, leave out maxLength={1}, and end the text message with a line like "@example.com #123456". On Android, also call the WebOTP API, because Chrome documents origin-bound codes through that API instead of the attribute.

##### Why does OTP autofill only fill the first box?

Each box has a maxLength of 1, so the browser cuts the inserted code to one character before your change handler runs. Remove the limit, filter the characters yourself and spread a change of several characters across the boxes, the same way you handle a paste.

##### Does autocomplete one-time-code work in Chrome on Android?

Do not count on it. web.dev lists the attribute for Safari on iOS, iPadOS and macOS, and lists Chrome, Opera and Vivaldi on Android under the WebOTP API instead. Keep the attribute for Safari and add a navigator.credentials.get call with the sms transport for Android.

##### How do I use an OTP input with react-hook-form?

Wrap it in Controller, pass field.value and field.onChange, and call handleSubmit from onComplete so the last digit submits the form. Validate with a zod rule such as a six-digit regex, and clear the error as soon as the person types again.

##### Is the Wingo UI OTP input free?

Yes. The OTP Input, Field and Button are free and install with npx wingo-ui@latest add otp-input field button. The useCooldown hook and the Login Page block are part of Wingo UI Pro.

---

Source: https://wingo-ui.com/blog/react-otp-input

### React Pull to Refresh in a PWA Without Fighting the Browser

> Build a React pull to refresh for a PWA: overscroll-behavior, rubberband resistance, iOS spokes or a Material ring, a haptic tick and a refresh button.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/react-pull-to-refresh

#### TL;DR

A React pull to refresh that holds up in a PWA needs four things: overscroll-behavior-y: contain on the scroller so Chrome does not reload the page, a touchmove listener added with { passive: false } because React's onTouchMove is passive and Safari on iOS ignores overscroll-behavior for its own refresh, a rubberband curve instead of a linear drag, and a refresh button for people who cannot drag. Pick an indicator that matches the platform (iOS spokes that move the list down, or a Material ring that floats over it) and fire one haptic tick at the threshold as an extra, never as the only signal. The Pro Wingo UI Pull To Refresh does all of this in one component.

A React pull to refresh looks like forty lines of touch handlers until it runs in a phone browser. Chrome on Android and Safari on iOS have their own pull to refresh that reloads the page, React registers `onTouchMove` as passive so `preventDefault()` does nothing, and a list that follows the finger one to one feels wrong on a phone. This guide fixes each one for a PWA, with the raw pattern and the Wingo UI [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) that packages it.

#### Why does a PWA need its own pull to refresh?

Because the browser's version reloads the document, and once the app is installed it may not exist at all. A reload runs every script again and drops all in-memory state: fetched data, an open sheet, the scroll position of a nested list. A data refresh only refetches the list. And a web app added to the iPhone home screen opens in standalone mode, without Safari's toolbar or its pull to refresh (our [React PWA install prompt tutorial](https://wingo-ui.com/blog/react-pwa-install-prompt) covers how people get it there). Discourse shipped a theme component to add one back; its [December 2024 announcement](https://meta.discourse.org/t/ios-pwa-app-pull-to-refresh/343262) opens with "Pull to refresh is a huge gap in iOS PWA."

Ready-made packages are thin. As of October 2026, a search for pull to refresh react pwa still puts [@patlux/react-pull-to-refresh](https://www.npmjs.com/package/@patlux/react-pull-to-refresh) (last published November 2018) and [react-js-pull-to-refresh](https://www.npmjs.com/package/react-js-pull-to-refresh) (last published August 2022) near the top, next to React Native packages that do not run in a browser. Android calls the gesture swipe to refresh, so a React swipe to refresh component is the same thing under another name.

#### How do you stop the browser's own pull to refresh?

Set `overscroll-behavior-y: contain` on the element that scrolls: `html` when the window scrolls, the container otherwise. That one line is the whole overscroll-behavior pull to refresh fix in Chrome, which has supported the property since [Chrome 63](https://developer.chrome.com/blog/overscroll-behavior); `contain` keeps the overscroll glow and `none` removes it too. Per [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior), `contain` "disables native browser navigation, including the vertical pull-to-refresh gesture".

Safari is the exception. It has supported the property since Safari 16 ([caniuse](https://caniuse.com/css-overscroll-behavior)), but [WebKit bug 275947](https://bugs.webkit.org/show_bug.cgi?id=275947), filed in June 2024 and still open when we checked in October 2026, reports that neither `none` nor `contain` turns off Safari's pull to refresh on iOS. What works there is JavaScript: once a touch at the top moves down, call `preventDefault()` on its `touchmove`, so the page does not scroll, bounce or start Safari's refresh under the finger.

That is where React gets in the way. The [React 17 changelog](https://legacy.reactjs.org/blog/2020/10/20/react-v17.html) lists "Keep `onTouchStart`, `onTouchMove`, and `onWheel` passive." A passive listener cannot cancel the event, so `onTouchMove={(e) => e.preventDefault()}` is silently ignored. Attach the listener yourself, on the scroller:

```ts
// React registers onTouchMove as a passive listener, so preventDefault() inside it is ignored.
// attach it yourself, on the scroller (on document, every scroll on the page would wait for this handler)
export function attachPull(scroller: HTMLElement, onPull: (dy: number) => void, onRelease: () => void) {
  let startY: number | null = null;
  let pulling = false;

  const start = (event: TouchEvent) => {
    pulling = false;
    startY = event.touches.length === 1 && scroller.scrollTop <= 0 ? event.touches[0].clientY : null;
  };
  const move = (event: TouchEvent) => {
    if (startY === null) return;
    const dy = event.touches[0].clientY - startY;
    if (!pulling && dy < 0) {
      // the finger went up first: a normal scroll, hand it back
      startY = null;
      return;
    }
    pulling = true;
    event.preventDefault(); // allowed because the listener is not passive
    onPull(Math.max(0, dy));
  };
  const end = () => {
    if (pulling) onRelease();
    startY = null;
    pulling = false;
  };

  const previous = scroller.style.overscrollBehaviorY;
  scroller.style.overscrollBehaviorY = "contain";
  scroller.addEventListener("touchstart", start, { passive: true });
  scroller.addEventListener("touchmove", move, { passive: false });
  scroller.addEventListener("touchend", end);
  scroller.addEventListener("touchcancel", end);
  return () => {
    scroller.style.overscrollBehaviorY = previous;
    scroller.removeEventListener("touchstart", start);
    scroller.removeEventListener("touchmove", move);
    scroller.removeEventListener("touchend", end);
    scroller.removeEventListener("touchcancel", end);
  };
}
```

Call it from a `useEffect` and return its cleanup. Write `dy` to a motion value or a ref, not to state, or every `touchmove` re-renders the list. It is a skeleton. The Wingo UI component adds what it misses: it waits 8px before deciding whether a touch is a pull, drops gestures that are more sideways than down, cancels on a second finger (a pinch is never a pull), and never starts in an input, inside `[data-no-pull]`, in a horizontal scroller or in a nested list that is not at its own top.

#### How much resistance should a pull to refresh have?

Resistance that grows the further the finger goes, so the list slows down smoothly instead of following one to one into a hard stop. [react-simple-pull-to-refresh](https://www.npmjs.com/package/react-simple-pull-to-refresh), the most recently released web package we looked at (1.3.4, January 5, 2026, MIT, React 16.10 to 19), divides the finger travel by a `resistance` prop (default 1) and clamps it at `maxPullDownDistance` (default 95px): a linear pull into a wall. With no dependencies, it is a fair pick for a prototype.

A native list follows a curve. The `rubberband` helper in Wingo UI's `lib/motion` uses an iOS-style one, `(1 - 1 / (x * 0.55 / d + 1)) * d`, where `x` is the finger travel past the 8px slop and `d` the scroller height (480px at least, so a short box resists like a phone-sized one). On a 480px scroller with the defaults, 100px of finger travel moves the list 49px, 200px moves it 89px, the refresh arms at 72px (`threshold`) after about 154px, and the list never passes `maxPull` (128px). The pull lives in a motion value, so a `touchmove` never re-renders your list; React state changes only when the phase does (pulling, armed, refreshing, done).

A release before the threshold springs back with the finger's velocity. A release past it parks the list at the threshold while `onRefresh` runs (500ms at least, so the spinner never flashes), then shows a check, or an alert when the promise rejects, for `doneDuration` (600ms) before the list glides back. Under reduced motion the list jumps to each resting point instead of springing.

#### Arrow, iOS spokes or a Material ring: which indicator should you use?

Match the platform most of your users hold, and decide whether the content should move. The three variants of the component:

| `variant` | The list | While pulling | While refreshing | Good fit |
| --- | --- | --- | --- | --- |
| `arrow` (default) | moves down | an arrow that turns at the threshold | a spinner | neutral apps on both platforms |
| `ios` | moves down | 12 spokes that draw one by one | the spokes spin in 12 steps, like UIRefreshControl | iPhone-first apps |
| `material` | stays put | a floating circle whose ring fills | a spinning ring in the circle | Android-first apps, image grids, virtual lists |

`size` sets the glyph to 20, 24 or 28px (the Material circle to 36, 40 or 44px), `tone` colors it (neutral by default), and `showLabel` adds a line that reads Pull to refresh, Release to refresh, Refreshing…, then Updated. Under reduced motion the spokes spin at half speed.

> Live demo (Pull To Refresh): Pull the inbox down with a finger, or scroll up past the top on a trackpad: the spokes draw as you pull, the label flips to Release to refresh at the threshold, and new messages land on top. Try it at [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) and install it with `npx wingo-ui@latest add pull-to-refresh`.

Here is a full inbox screen with the iOS variant around the [List](https://wingo-ui.com/components/list). `scroll="self"` makes the component the scroll container, with `overscroll-behavior-y: contain` on itself. With the default `scroll="parent"` it watches the scroller you pass or provide, else the nearest scrolling ancestor, else the window, and sets the property there while it is mounted and enabled.

```tsx
"use client";

import { useState } from "react";
import { RotateCw } from "lucide-react";
import { Button } from "@/components/ui/button";
import { List, type ListItemData } from "@/components/ui/list";
import { PullToRefresh, type PullToRefreshApi } from "@/components/ui/pull-to-refresh";

type InboxProps = { initial: ListItemData[]; load: () => Promise<ListItemData[]> };

export function Inbox({ initial, load }: InboxProps) {
  const [items, setItems] = useState(initial);
  const [api, setApi] = useState<PullToRefreshApi>();

  return (
    <div className="flex h-dvh flex-col">
      <header className="flex h-14 shrink-0 items-center justify-between px-4">
        <h1 className="text-lg font-semibold">Inbox</h1>
        {/* the same refresh for keyboards, switch access and mouse users */}
        <Button variant="ghost" size="icon" radius="full" aria-label="Reload" onClick={() => void api?.refresh()}>
          <RotateCw />
        </Button>
      </header>
      <PullToRefresh
        scroll="self"
        variant="ios"
        shortcut="shift+r"
        className="min-h-0 flex-1"
        setApi={setApi}
        onRefresh={async () => setItems(await load())}
        labels={{ refreshing: "Checking for mail…", done: "Up to date", error: "Could not check for mail" }}
      >
        <List variant="plain" items={items} />
      </PullToRefresh>
    </div>
  );
}
```

The indicator spins until the `onRefresh` promise settles; a rejection shows the error state. Pass `refreshing` when the app starts a reload on its own, and `disabled` while the user edits or filters: turning it on mid-pull springs the list back without refreshing.

#### How do you add a haptic tick to a pull to refresh?

Fire one short tick when the pull crosses the threshold, the moment letting go starts to mean refresh; never on every frame or on release. The component calls `haptic("medium")` from the [haptics helper](https://wingo-ui.com/components/haptics) when the pull arms and `haptic("error")` when a pulled refresh fails. `haptics={false}` turns both off, and `configureHaptics({ enabled })` is the app-wide switch.

Treat the tick as a bonus, because support is uneven. As of October 2026, [caniuse](https://caniuse.com/vibration) lists `navigator.vibrate` in Chrome for Android and Samsung Internet, removed from Firefox in version 129 and never in Safari. On iPhone the helper clicks a hidden `<input type="checkbox" switch>` from script to play the system tick; the switch arrived in [Safari 17.4](https://webkit.org/blog/15054/an-html-switch-control/), and WebKit's announcement does not mention a haptic, so nothing promises it will last. [ios-haptics](https://www.npmjs.com/package/ios-haptics), built on the same trick, said in its June 2026 README (version 3.1.1) that it "only works on ios 17.4 to 26.4, as apple patched it in ios 26.5". Its September 2026 release (3.2.0) forwards the user's own tap to the switch as a trusted click instead, which suggests a click from script no longer plays. A pull never produces a tap, so expect the tick to stay silent on iOS 26.5 and later, and never put information in it that the indicator does not show.

Vibration also needs [sticky user activation](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/User_activation), and `touchmove` is not an activation event (`touchend`, a finger's `pointerup`, `mousedown` and `keydown` are). If a pull is the first thing someone does on a fresh page, that tick is silent; `haptic()` returns `false` instead of letting Chrome log a blocked call. Our [Web Vibration API guide](https://wingo-ui.com/blog/web-vibration-api-haptic-feedback) covers the rest of the platform gap and a setting that turns haptics off.

#### How do you make a custom pull to refresh accessible?

Give the same refresh a button, a key and an announcement, because a pull is a dragging movement. [WCAG 2.2 success criterion 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) (level AA) exempts the browser's own drag to refresh, since the user agent provides it, but applies once your content implements its own, so you need a single-pointer alternative. Android's [swipe to refresh guide](https://developer.android.com/develop/ui/views/touch-and-input/swipe/add-swipe-interface) asks the same of native apps: a refresh action in the app bar's overflow menu, for people who use a keyboard or a D-pad.

The component has a path for each input. `setApi` hands you `{ refresh() }`, which runs exactly what a pull runs (indicator, promise, done state), so a header button and a pull never drift apart; a call during a running refresh returns the running promise. `shortcut` binds a key such as `shift+r`. A polite live region announces Refreshing…, then Updated or the error, and the root carries `aria-busy` meanwhile. On a laptop, scrolling up once more at the very top with a trackpad or wheel pulls (`wheel`, on by default; momentum that carries a scroll to the top never does), and `pullWithMouse` lets a mouse drag pull, for kiosks. The header button in the inbox example uses the Button's `size="icon"`, which is 40px with a mouse and 44px on touch screens, the size the [minimum touch target guide](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind) recommends.

> Live demo (Pull To Refresh): With a mouse, drag the list down (pullWithMouse is on in this demo); on a phone, pull it. The ring fills while the rows stay put, and the Reload button in the header runs the same refresh without a gesture. Try it at [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) and install it with `npx wingo-ui@latest add pull-to-refresh`.

#### How do you use pull to refresh with a long virtualized list?

Let one element scroll and share it, so both components watch the same scroll position. The [Virtual List](https://wingo-ui.com/components/virtual-list) with `scroll="window"` follows the nearest `ScrollContainerProvider`, and Pull To Refresh with its default `scroll="parent"` does too:

```tsx
"use client";

import { useState } from "react";
import { ListItem } from "@/components/ui/list";
import { PullToRefresh } from "@/components/ui/pull-to-refresh";
import { VirtualList } from "@/components/ui/virtual-list";
import { ScrollContainerProvider } from "@/hooks/use-scroll-state";

type Order = { id: string; customer: string; city: string; total: string };

type OrdersProps = {
  orders: Order[];
  hasMore: boolean;
  reload: () => Promise<void>;
  loadPage: () => Promise<void>;
};

export function Orders({ orders, hasMore, reload, loadPage }: OrdersProps) {
  // one element scrolls, and both components follow it through the provider
  const [scroller, setScroller] = useState<HTMLDivElement | null>(null);

  return (
    <div ref={setScroller} className="h-dvh overflow-y-auto">
      <ScrollContainerProvider value={scroller}>
        <PullToRefresh variant="material" onRefresh={reload}>
          <VirtualList
            aria-label="Orders"
            scroll="window"
            items={orders}
            renderItem={(order) => <ListItem id={order.id} title={order.customer} description={order.city} value={order.total} />}
            hasMore={hasMore}
            onLoadMore={loadPage}
          />
        </PullToRefresh>
      </ScrollContainerProvider>
    </div>
  );
}
```

Use the material variant here. The Virtual List measures where it starts inside the scroller with `getBoundingClientRect()`, which counts transforms, and it measures again when its size changes. The arrow and ios variants hold the rows 72px down with a transform while `onRefresh` runs, which is exactly when new rows arrive. The material ring floats over rows that never move. For the other end, `loadMode="pull"` on the Virtual List loads the next page when the user pulls past the last row and lets go.

#### Which pull to refresh pitfalls show up in production?

Check these five before you ship, whether you use our component or your own React pull to refresh component:

- **A sticky or translucent header over the list.** The indicator hides under it. `indicatorOffset` moves its resting line down by the header's height.
- **A pull during the bounce at the top.** On iOS the scroll position goes negative while the list bounces past the top, so a strict `scrollTop === 0` check refuses pulls that start then. Treat anything at or below 0 as the top.
- **A fixed bar inside the pulled content.** The arrow and ios variants move the content with a transform, and a transformed element becomes the containing block of its `position: fixed` children, so a tab bar or floating button rendered inside rides down with the pull. Render fixed bars outside the component.
- **Nested pull to refresh areas,** such as a feed inside a tab of a page that refreshes. The inner one should win; the component makes the outer one ignore the gesture.
- **A refresh that never ends.** If `onRefresh` hangs, so does the spinner. Put the timeout on the request, for example `fetch(url, { signal: AbortSignal.timeout(10_000) })`, not on the indicator: the rejection then shows the error state and the indicator tells the truth.

For the rest of the mobile layer (bottom sheets, safe areas, dvh, tab bars), read the guide to [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) or browse [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### What should you install next?

If your list already exists, wrap it. `npx wingo-ui@latest add pull-to-refresh` copies the component into your project with the Spinner and the hooks and helpers it imports (haptics, motion, scroll state, shortcuts), and installs `motion` and `lucide-react`. Pull To Refresh, List and Virtual List are part of [Wingo UI Pro](https://wingo-ui.com/pricing), so sign in first with `npx wingo-ui@latest login`; the Spinner it uses is free.

#### Components in this post

- [Pull To Refresh](https://wingo-ui.com/components/pull-to-refresh) (Pro): Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick. Install: `npx wingo-ui@latest add pull-to-refresh`
- [List](https://wingo-ui.com/components/list) (Pro): Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder. Install: `npx wingo-ui@latest add list`
- [Virtual List](https://wingo-ui.com/components/virtual-list) (Pro): Long and endless lists at 60fps: thousands of list rows virtualized, sticky group headers, infinite loading and scroll restoration. Install: `npx wingo-ui@latest add virtual-list`
- [Haptics](https://wingo-ui.com/components/haptics) (Pro): Haptic feedback for the web in one call: short vibration ticks on Android and the system tick on iPhone, silent everywhere else. Install: `npx wingo-ui@latest add haptics`

#### FAQ

##### How do I disable the browser's pull to refresh in Chrome?

Set overscroll-behavior-y: contain on the element that scrolls, which is the html element when the window scrolls. Use none instead to remove the overscroll glow as well. Chrome has supported the property since version 63.

##### Does overscroll-behavior stop pull to refresh in Safari on iOS?

Not reliably. Safari has supported the property since version 16, but WebKit bug 275947, open since June 2024, reports that it does not turn off Safari's own pull to refresh. Call preventDefault in a non-passive touchmove listener once the gesture is a pull.

##### Why does preventDefault not work in onTouchMove in React?

Since React 17, onTouchStart, onTouchMove and onWheel are registered as passive listeners, and browsers ignore preventDefault in a passive listener. Attach the listener yourself with addEventListener and { passive: false } in an effect, on the scrolling element.

##### Is a custom pull to refresh accessible?

Only with an alternative. WCAG 2.2 success criterion 2.5.7 Dragging Movements (level AA) exempts the browser's own drag to refresh but covers one you build, so add a refresh button or shortcut that runs the same reload and announce the result in a live region.

##### Is the Wingo UI Pull To Refresh free?

No. It is a Pro component, like the List, the Virtual List and the haptics helper it pairs with; the Spinner it uses is free. With a Pro account signed in through npx wingo-ui@latest login, npx wingo-ui@latest add pull-to-refresh copies the component and everything it imports into your project.

---

Source: https://wingo-ui.com/blog/react-pull-to-refresh

### React PWA Install Prompt for Chrome, Edge and iPhone

> Build a React PWA install prompt in Next.js: catch beforeinstallprompt in Chrome and Edge, show Add to Home Screen steps on iPhone, and know when not to ask.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 9 min
- Canonical: https://wingo-ui.com/blog/react-pwa-install-prompt

#### TL;DR

A React PWA install prompt needs two paths. In Chrome, Edge and Samsung Internet, catch beforeinstallprompt in a client component the root layout renders, call preventDefault, save the event and call its prompt() from your own Install button; on iPhone and iPad no browser fires that event, so show the Share, then Add to Home Screen steps instead. Ask only after people get value, never inside the installed app, an in-app browser or a sign-up flow, and remember a Not now for a couple of weeks.

A React PWA install prompt has to cover two kinds of browsers. Chrome, Edge and Samsung Internet fire `beforeinstallprompt`, so your own button can open the browser's install dialog. No browser on iPhone or iPad fires it, so the only way in is Share, then Add to Home Screen, and your app has to show people where that is. The usual bugs are a listener in a component that mounts too late and a banner that asks on the first page view. This tutorial builds both paths in Next.js, then covers when not to ask at all.

#### Which browsers let a page open the install dialog?

Only Chromium browsers. Everywhere else people install from a browser menu, if at all, and the page can only explain where. As of October 2026, per [caniuse](https://caniuse.com/mdn-api_beforeinstallpromptevent), MDN's [installability guide](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable) and the [Firefox 143 release notes](https://www.firefox.com/en-US/firefox/143.0/releasenotes/):

| Browser | `beforeinstallprompt` | How people install | What your UI should do |
| --- | --- | --- | --- |
| Chrome and Edge on desktop | yes | your button calls `prompt()`, or the address bar icon | an Install button |
| Chrome and Samsung Internet on Android | yes | your button, or the browser menu | an Install button |
| Safari on iPhone and iPad, plus Chrome, Edge, Firefox and Orion there since iOS 16.4 | no | Share, then Add to Home Screen | show the steps |
| Safari 17+ on macOS Sonoma or later | no | File, then Add to Dock | show the steps |
| Firefox on Android | no | a home screen shortcut that opens in the browser | nothing |
| Firefox on desktop | no | none from a manifest; on Windows, Firefox 143+ can pin a site to the taskbar | nothing |
| In-app browsers (Instagram, TikTok, Facebook) | no | none until the page opens in a real browser | nothing |

On iPhone, no beforeinstallprompt iOS polyfill can help, because no iOS browser has an install dialog a page can open, and WebKit closed the 2019 request for `BeforeInstallPromptEvent` ([bug 193959](https://bugs.webkit.org/show_bug.cgi?id=193959)) as WONTFIX. On the Chromium side, the [Chrome 157 release notes](https://chromestatus.com/release-notes/157) list a [Web Install API](https://chromestatus.com/feature/5183481574850560) (`navigator.install()`, desktop first) and an `<install>` element, and [Chromium Dash](https://chromiumdash.appspot.com/schedule) schedules Chrome 157 for stable on November 3, 2026. WebKit's [standards position](https://github.com/WebKit/standards-positions/issues/463) on that API is oppose, so it changes nothing on iPhone. Build on `beforeinstallprompt` today.

#### What does Chrome need before it fires beforeinstallprompt?

A manifest, HTTPS and some engagement. web.dev's [install criteria](https://web.dev/articles/install-criteria) require an app that is not installed yet, served over HTTPS, with a manifest that has `name` or `short_name`, a 192px and a 512px icon, `start_url`, and a `display` of `standalone`, `fullscreen`, `minimal-ui` or `window-controls-overlay`. The person must also have clicked or tapped the page once and spent 30 seconds on it, at any time. That is why your PWA install button can stay hidden on a first visit even with a perfect manifest. In Chrome DevTools, Application, then Manifest lists the installability errors.

A service worker is optional for installability, per MDN. Chrome's post [Revisiting Chrome's installability criteria](https://developer.chrome.com/blog/update-install-criteria) (last updated December 2023) dropped the `fetch()` handler requirement for the menu install (Chrome 108 on mobile, 112 on desktop) but said the automatic install prompt still depended on one. If you depend on the event, register a service worker with a fetch handler anyway; offline support needs one too.

In the App Router the manifest is a file convention:

```ts
// app/manifest.ts
import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
  return {
    id: "/",
    name: "Northwind CRM",
    short_name: "Northwind",
    start_url: "/",
    display: "standalone",
    background_color: "#ffffff",
    theme_color: "#ffffff",
    icons: [
      { src: "/icon-192.png", sizes: "192x192", type: "image/png" },
      { src: "/icon-512.png", sizes: "512x512", type: "image/png" },
      { src: "/icon-maskable-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
    ],
  };
}
```

#### How do you capture beforeinstallprompt in React?

In a module-level store that starts listening when the root layout mounts, not in a component's state. The browser fires the event as soon as the page qualifies, often right after load, and an event that fired before your listener existed is gone, so a listener in a settings page that mounts later never hears it. Call `preventDefault()` to keep Chrome's own mini-infobar away, store the event, and call `prompt()` from a click: the [web.dev codelab](https://web.dev/articles/codelab-make-installable) calls it in the button's click handler because it must come from a user gesture, and resets the saved event because `prompt()` works once. The event type is not in `lib.dom.d.ts`, because it is Chromium-only and non-standard ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/BeforeInstallPromptEvent)).

```ts
// hooks/use-before-install-prompt.ts
import { useSyncExternalStore } from "react";

type BeforeInstallPromptEvent = Event & {
  prompt: () => Promise<void>;
  userChoice: Promise<{ outcome: "accepted" | "dismissed"; platform: string }>;
};

let deferred: BeforeInstallPromptEvent | null = null;
let listening = false;
const listeners = new Set<() => void>();
const notify = () => listeners.forEach((listener) => listener());

function subscribe(listener: () => void) {
  // attached on the first subscribe, in the browser, and kept for the life of the page
  if (!listening) {
    listening = true;
    window.addEventListener("beforeinstallprompt", (event) => {
      event.preventDefault(); // no mini-infobar: the app decides when to ask
      deferred = event as BeforeInstallPromptEvent;
      notify();
    });
    window.addEventListener("appinstalled", () => {
      deferred = null;
      notify();
    });
  }
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

export function useBeforeInstallPrompt() {
  const event = useSyncExternalStore(subscribe, () => deferred, () => null);

  // call it from a click handler
  async function install() {
    const current = deferred;
    if (!current) return "unavailable" as const;
    deferred = null; // prompt() works once per event
    notify();
    await current.prompt();
    const { outcome } = await current.userChoice;
    return outcome;
  }

  return { canInstall: event !== null, install };
}
```

Call the hook in a client component that the root layout renders, and show your button only while `canInstall` is true. `useSyncExternalStore` returns `null` on the server and during hydration, so the button never causes a hydration mismatch. `userChoice` reports what happened in the dialog your button opened; `appinstalled` fires for every install, including one from the address bar. Per [web.dev](https://web.dev/articles/customize-install), after a dismissal the browser usually fires a fresh event right after `userChoice` resolves, which the store picks up.

#### How do you guide Add to Home Screen on iOS?

Detect iPhone and iPad, skip it inside the installed app and in in-app browsers, and show the steps with the icons people will look for. iPadOS reports a Mac user agent, so check touch points too. The [PWA guide in the Next.js docs](https://nextjs.org/docs/app/guides/progressive-web-apps) tests `/iPad|iPhone|iPod/` only, which misses current iPads, and its Add to Home Screen button has no handler.

```ts
// call it in an effect or a store snapshot, never during the server render
export function getInstallContext() {
  const ua = navigator.userAgent;
  const ios = /iPhone|iPod|iPad/.test(ua) || (/Macintosh/.test(ua) && navigator.maxTouchPoints > 1);
  // Instagram, Facebook, TikTok and Android WebViews have no install path
  const inApp = /FBAN|FBAV|Instagram|musical_ly|TikTok|; wv\)/i.test(ua);
  const standalone =
    window.matchMedia("(display-mode: standalone)").matches ||
    (navigator as Navigator & { standalone?: boolean }).standalone === true;
  return { ios, inApp, standalone };
}
```

iOS 26 changed two things. WebKit's [Safari 26 beta announcement](https://webkit.org/blog/16993/news-from-wwdc25-web-technology-coming-this-fall-in-safari-26-beta/) says every website added to the Home Screen now opens as a web app by default, with an Open as Web App switch people can turn off. And in Safari's default Compact tab layout, Share sits behind the More (⋯) button, so older Add to Home Screen iOS instructions miss a tap. App builders flagged it in [a Glide community thread](https://community.glideapps.com/t/ios-26-add-to-home-screen-workflow-change/84599) in September 2025, and [iPhone Life's iOS 26.4 walkthrough](https://iphonelife.com/content/tip-day-turn-your-favorite-website-home-screen-icon) adds a View More tap before Add to Home Screen. The Bottom and Top layouts keep Share on the toolbar, so write steps that work in all three.

#### How does the Wingo UI Install Prompt handle both?

It is one component for both paths. [Install Prompt](https://wingo-ui.com/components/install-prompt) keeps the event in a page-wide store, like the hook above, and adds what the hook skips: platform detection for Chromium, iPhone, iPad and Safari on a Mac, the standalone and in-app checks, a remembered Not now, and the UI. It renders nothing where there is no install path.

> Live demo (Install Prompt): Wait a second for the banner, then tap Install: on an iPhone there is no browser dialog, so a sheet lists the three steps with the icons to look for. The × hides it for 14 days; Show again brings it back. Try it at [Install Prompt](https://wingo-ui.com/components/install-prompt) and install it with `npx wingo-ui@latest add install-prompt`.

The demo forces `platform="ios"`; in your app the default `auto` detects it. The banner shows `delay` milliseconds (3000 by default) after an install becomes possible, never takes focus, and sits above a [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) and the home indicator through `--bottom-bar-offset` and the [safe area insets](https://wingo-ui.com/blog/tailwind-safe-area-insets). On iPhone, Install opens a [Drawer](https://wingo-ui.com/components/drawer) with numbered steps and an arrow toward Safari's share button; from 768px up it becomes a centered dialog. On a Mac, Safari gets the File, then Add to Dock steps inline.

> Live demo (Install Prompt): Tap Install: the demo plays Chrome's install dialog, so the button spins, then reads Installed with a check and the banner leaves. Show again replays it. Try it at [Install Prompt](https://wingo-ui.com/components/install-prompt) and install it with `npx wingo-ui@latest add install-prompt`.

Mount it once, high in the tree. This wrapper also keeps it off the screens where it would interrupt a task, and rewrites the iPhone steps for iOS 26:

```tsx
// components/app-install-prompt.tsx, rendered by app/layout.tsx after {children}
"use client";

import { usePathname } from "next/navigation";
import { InstallPrompt, useInstallPrompt } from "@/components/ui/install-prompt";

// screens where a banner would interrupt a task
const BUSY = /^\/(welcome|signup|checkout)(\/|$)/;

export function AppInstallPrompt() {
  // starts the beforeinstallprompt listener even when the first page people open is a busy one
  useInstallPrompt();
  const pathname = usePathname();
  if (BUSY.test(pathname)) return null;

  return (
    <InstallPrompt
      appName="Northwind CRM"
      appIcon="/icon-192.png"
      description="Open it right from your home screen, even offline."
      delay={5000}
      dismissDays={30}
      labels={{
        iosSteps: ["Tap Share, or ⋯ and then Share", "Choose Add to Home Screen (under View More if needed)", "Tap Add"],
      }}
    />
  );
}
```

For a settings page, `variant="card"` places the same prompt inline. For a menu item, `useInstallPrompt()` returns `platform`, `canInstall`, `isStandalone` and `promptInstall()`, which resolves `accepted`, `dismissed` or `unavailable`.

#### When should you not ask people to install?

Ask after people have gotten value, and stay quiet everywhere else. web.dev's [install promotion patterns](https://web.dev/articles/promote-install) say disruptive promotions hurt usability and engagement, that a sign-up form should not be interrupted, and that a turned-down promotion should stay hidden until something changes, such as a sign-in or a purchase. Skip it:

- **On arrival.** Chrome already waits for a tap and 30 seconds; iPhone has no such gate, so your `delay` is the only one.
- **Inside a task.** Sign-up, checkout and onboarding are on the `BUSY` list above. For a multi-step flow, wait until the last step is done.
- **Inside the installed app.** Check `display-mode: standalone` and `navigator.standalone`. The component also treats `minimal-ui` and `window-controls-overlay` as installed.
- **In an in-app browser.** A link opened from Instagram or TikTok has no install path, and the Install Prompt renders nothing there. If much of your traffic arrives that way, the MIT-licensed [pwa-install](https://github.com/khmyznikov/pwa-install) web component added in-app browser detection with guided steps, such as opening the link in Safari, in [0.7.0](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0) (September 2026). Ours does not do that.
- **On top of another banner.** One floating message at a time. Fixed install banners queue behind each other, but a cookie banner is yours to sequence.
- **Again right after Not now.** The × stores a timestamp in localStorage under `storageKey` and hides the prompt for `dismissDays` (14 by default; `0` means this session only).

#### How do you pair the install prompt with onboarding?

Ask for install after onboarding, and on iPhone ask for notifications inside the installed app. WebKit's [iOS 16.4 announcement](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/) added Web Push for Home Screen web apps, with the permission request tied to a direct user interaction. The [Onboarding Flow](https://wingo-ui.com/components/onboarding-flow) asks for notifications and location on its own step, so drop the notification card in a Safari tab:

> Live demo (Onboarding Flow): Tap Allow on each card: this demo answers as a browser that granted it. Continue stays enabled, so both permissions are optional. Try it at [Onboarding Flow](https://wingo-ui.com/components/onboarding-flow) and install it with `npx wingo-ui@latest add onboarding-flow`.

```tsx
// app/welcome/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { OnboardingFlow, type OnboardingPermission } from "@/components/blocks/onboarding-flow";
import { useInstallPrompt } from "@/components/ui/install-prompt";

export default function WelcomePage() {
  const router = useRouter();
  const { platform, isStandalone } = useInstallPrompt();
  // web push on iPhone and iPad works in the Home Screen app, so a Safari tab skips that card
  const permissions: OnboardingPermission[] =
    platform === "ios" && !isStandalone ? ["location"] : ["notifications", "location"];

  return (
    <OnboardingFlow
      persistKey="onboarding"
      permissions={permissions}
      onComplete={async (result) => {
        await fetch("/api/onboarding", { method: "POST", body: JSON.stringify(result) });
        // /welcome is on the BUSY list, so the install banner waits for the home route
        router.push("/");
      }}
    />
  );
}
```

The block's slides, interests, sample user and labels default to its Acme Market demo content, so pass `slides`, `interests`, `user` and `labels` for your own app before you ship it. Once people finish, the banner shows after its `delay` on the home route: they have just set the app up, and no form is competing for the screen. For the rest of the mobile layer, read [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components), add [pull to refresh to the PWA](https://wingo-ui.com/blog/react-pull-to-refresh), or browse [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### What should you install next?

Add the component, then the manifest and the root layout wrapper above. `npx wingo-ui@latest add install-prompt` copies it with the Button, Drawer and hooks it imports, and installs the npm packages they use (`motion`, `lucide-react`, `vaul` and three Radix primitives). Install Prompt and Onboarding Flow are part of [Wingo UI Pro](https://wingo-ui.com/pricing), so sign in first with `npx wingo-ui@latest login`; the Button and Drawer underneath are free.

#### Components in this post

- [Install Prompt](https://wingo-ui.com/components/install-prompt) (Pro): Invites people to install the web app: the browser's install dialog in Chrome and Edge, an Add to Home Screen guide on iPhone and Mac. Install: `npx wingo-ui@latest add install-prompt`
- [Onboarding Flow](https://wingo-ui.com/components/onboarding-flow) (Pro): A marketplace app's first run: welcome slides, a calm ask for notifications and location, a short profile, preferences and a finish. Install: `npx wingo-ui@latest add onboarding-flow`

#### FAQ

##### Does beforeinstallprompt work on iOS?

No. No browser on iPhone or iPad fires it, and WebKit closed the 2019 request to add BeforeInstallPromptEvent (bug 193959) as WONTFIX. People install from the Share menu, in Safari or, since iOS 16.4, in other browsers that added the option such as Chrome and Edge, so the best a page can do is show those steps.

##### Why is beforeinstallprompt not firing?

Chrome fires it only for an app that is not installed yet, served over HTTPS, with a manifest that has a name, 192px and 512px icons, a start_url and a standalone-like display, and only after the person has tapped the page once and spent 30 seconds on it at some point. It often fires right after load, so a listener that mounts later on another route misses it; Application, then Manifest in Chrome DevTools lists what is missing.

##### How do I know if my PWA is already installed?

Inside the installed app, matchMedia('(display-mode: standalone)') matches, and on iOS navigator.standalone is true as well. In Chromium, the appinstalled event fires on the page at the moment of the install, whichever button started it.

##### Can I show the install prompt again after people dismiss it?

Each beforeinstallprompt event can call prompt() once; after a dismissal you wait for the browser to fire a new event, which web.dev says usually comes right after userChoice resolves. Your own banner should also remember Not now for a while; the Wingo UI Install Prompt hides it for 14 days by default.

##### Is the Wingo UI Install Prompt free?

No. The Install Prompt and the Onboarding Flow block are Pro items, while the Button and the Drawer the prompt builds on are free. With a Pro account signed in through npx wingo-ui@latest login, npx wingo-ui@latest add install-prompt copies it and everything it imports into your project.

---

Source: https://wingo-ui.com/blog/react-pwa-install-prompt

### React Segmented Control: iOS Thumb, Drag and When to Use It

> A React segmented control with the iOS raised thumb you can drag, 44px touch targets and radio semantics, plus when to use tabs, a toggle group or radio cards.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 8 min
- Canonical: https://wingo-ui.com/blog/react-segmented-control

#### TL;DR

A React segmented control is a radio group drawn as a row of 2 to 5 segments with a raised thumb on the selected one: one tab stop, arrow keys that move and select, and a 44px height on touch screens. Use it when the choice changes the content already on screen (a time range, a view, units); use Tabs when it swaps in a different panel, a Toggle Group when several options can be on, and radio cards when each option needs a description. The free Wingo UI Segmented Control adds the iOS details: a spring thumb you can drag sideways with a finger, while a vertical swipe still scrolls the page.

A React segmented control is the row of two to five options with a raised thumb under the selected one, the control iOS uses to pick the time range of the charts in the Health app. Search for an iOS segmented control web component and most results are React Native packages, and shadcn/ui ships none as of October 2026. This guide covers what the web version has to get right (the thumb, touch, keyboard and radio semantics), then the decision that matters more: when Tabs, a Toggle Group or radio cards are the better control. The examples use the free [Segmented Control](https://wingo-ui.com/components/segmented-control) from Wingo UI, the library we build, so we are not neutral; outside facts link to their sources.

#### What is a segmented control, in web terms?

It is a radio group with a different look. Each segment is one option, exactly one is selected, and selecting one applies at once without a submit button. Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/segmented-controls) describe it as a way to offer "closely related choices that affect an object, state, or view." Material Design 3 has a close relative, the [segmented button](https://m3.material.io/components/segmented-buttons/overview), so you also see the control searched as a React segmented button.

That framing settles the implementation: the markup should be a `radiogroup` with `radio` items, the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) defines the keyboard, and a `name` should make it submit like native radios. The thumb, the spring and the drag sit on top of that.

#### How do you add a segmented control in React?

Install it, pass `options`, and either let it hold its own value or control it:

```bash
npx wingo-ui@latest add segmented-control
```

```tsx
"use client";

import { useState } from "react";
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";

const periods: SegmentedControlOption[] = [
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
];

export function SalesPeriod() {
  const [period, setPeriod] = useState("week");

  return (
    <SegmentedControl
      aria-label="Period"
      options={periods}
      value={period}
      onValueChange={setPeriod}
      fullWidth
    />
  );
}
```

Each option takes `value`, `label`, and optionally `icon`, `badge` (a number renders a count that hides at 0), `tooltip` and `disabled`. The props that change the look are `size` (`sm`, `md` or `lg`, a 32, 40 or 48px track), `radius`, `tone` (default `neutral`, a white thumb like iOS that turns a lifted gray in dark mode) or any CSS `color`, and `dividers`, the hairlines between unselected segments. Leave `defaultValue` out and it starts on the first enabled option.

> Live demo (Segmented Control): Tap or click Month, then press the thumb and slide it sideways: the value follows your finger and the sales total updates. With the keyboard, Tab in and use the arrow keys. Try it at [Segmented Control](https://wingo-ui.com/components/segmented-control) and install it with `npx wingo-ui@latest add segmented-control`.

If you came for a React segmented control Tailwind recipe, the whole look is Tailwind v4 utilities on design tokens, and every inner part takes classes through `classNames` (`item`, `thumb`, `icon`, `label`, `badge`, `divider`). App-wide defaults go through the free [UIProvider](https://wingo-ui.com/components/ui-config): `<UIProvider defaults={{ "segmented-control": { radius: "full" } }}>` rounds every segmented control in the app.

#### What makes it feel like the iOS control?

Three details: the thumb moves on a spring instead of a linear tween, it follows the finger, and it never steals a scroll.

**The thumb animates transform only.** It is rendered inside the selected segment, so CSS sizes it at rest. When the value changes, it measures the box it is leaving, jumps there as a transform and springs back to zero offset using the `snappy` spring from `lib/motion` (stiffness 500, damping 32). Animating `left` and `width` would recalculate layout on every frame; a transform stays on the compositor. Its corner radius is divided by the current scale, so a thumb stretching between a short and a long label keeps round corners. A change mid-flight starts from where the thumb is on screen and keeps its speed.

**It answers the finger.** Pressing the thumb dips it to 96%. Keep holding and slide sideways and the value follows the segment under your finger, then settles where you let go. The hairlines next to the thumb fade out, like on iOS.

**A vertical swipe still scrolls the page.** The track sets `touch-action: pan-y`, so the browser keeps vertical scrolling, and the code waits for 8px of movement before deciding what the gesture is. This is the part to copy if you build your own, trimmed from the component:

```tsx
// track: className="touch-pan-y"; drag.current is recorded on pointerdown over the thumb, SLOP is 8
function handlePointerMove(event: React.PointerEvent<HTMLDivElement>) {
  const state = drag.current;
  if (!state || state.id !== event.pointerId) return;
  if (!state.active) {
    const dx = Math.abs(event.clientX - state.x);
    const dy = Math.abs(event.clientY - state.y);
    // vertical first: a page scroll, let the browser have it
    if (dy > SLOP && dy > dx) return endPress();
    if (dx <= SLOP) return;
    state.active = true;
    event.currentTarget.setPointerCapture(event.pointerId);
  }
  // pick the segment under clientX from rects measured on pointerdown
}
```

`touch-action: none` on the track would make the drag simpler and trap anyone who starts a scroll on the control. After a drag, the click that follows lands on the segment where the drag began, so the component swallows it; otherwise the value snaps back.

With reduced motion turned on, the thumb jumps to its new place and the press dip is off.

#### Is a segmented control accessible?

It is when the semantics are a radio group, and that comes almost free from Radix. The Segmented Control is built on `@radix-ui/react-radio-group`, so the track is a `radiogroup`, each segment a `radio` with `aria-checked`, and the whole control is a single tab stop. Left and Right (Up and Down too) move focus and select, which matches the APG rule for a radio group outside a toolbar. We added Home and End, disabled segments are skipped, and `loop={false}` stops the arrows at the ends. Mantine takes the same route: its [SegmentedControl docs](https://mantine.dev/core/segmented-control/) (v9.7.1, October 2026) say it "uses radio inputs under the hood."

Four things are on you:

- **A name.** Pass `aria-label`, or `aria-labelledby` pointing at a visible heading; both land on the radiogroup.
- **Text for icons.** Give icon options a `label` anyway. With `iconOnly`, it becomes the segment's `aria-label` and its tooltip, shown on hover, on keyboard focus and on a long press on touch.
- **A form name.** Pass `name` and, inside a `<form>`, the selected value submits like native radios.
- **A non-drag path.** [WCAG 2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) (level AA) asks that anything done by dragging also work with a single pointer without dragging. Tapping a segment is that path, so keep it. Never make the drag the only way.

One trap if you build on Radix yourself: Radix checks the next radio only if the arrow key is still down when its deferred focus lands, so a very quick press (a screen reader, a remote, automation) can move focus without checking anything. The component selects on any focus that follows an arrow key, so a fast press still changes the value.

#### How should a segmented control behave on a phone?

It should be 44px tall on touch, share the width, and never flash gray on tap. The `md` size is a 40px track with a mouse and grows to 44px on coarse pointers (`pointer-coarse:h-11`). The `sm` size keeps its 32px look and gets an invisible hit area that reaches 44px; `lg` is 48px everywhere. The reasoning behind 44px, and the Tailwind variants that apply it only on touch, are in [minimum touch target size for React and Tailwind](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind).

`fullWidth` gives each segment an equal share of the container, the usual layout under a phone header. A segment with a long label keeps its natural width instead of truncating, and the others share what is left. Every segment carries `touch-manipulation` and a transparent `-webkit-tap-highlight-color`, so a quick second tap never zooms the page and iOS shows no gray flash. Set `dir="rtl"` and the layout, the arrow keys and the drag mirror.

The rest of the rules (sheets instead of popovers, safe areas, hover alternatives) are in the pillar on [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components), and the [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui) category collects every guide on the topic.

#### Segmented control vs tabs, a toggle group or radio cards: which one?

Pick by what the choice changes. The look tells you little, since Wingo UI's Tabs have a `segmented` variant with the same raised thumb. What differs is the semantics, and with them what a screen reader user expects to happen next.

| The choice | Use | What assistive tech gets | Wingo UI |
|---|---|---|---|
| Changes the content already on screen: a time range, a view, units; 2 to 5 short options | [Segmented Control](https://wingo-ui.com/components/segmented-control) | `radiogroup` of `radio`; arrows move and select | Free |
| Swaps in a different panel of content | [Tabs](https://wingo-ui.com/components/tabs), `variant="segmented"` for this look | `tablist`, `tab`, `tabpanel` linked by `aria-controls` | Free |
| Changes the URL | [Nav Tabs](https://wingo-ui.com/components/nav-tabs) | links in a `nav`, the current one with `aria-current="page"` | Pro |
| Several options can be on at once (bold and italic, amenities) | [Toggle Group](https://wingo-ui.com/components/toggle-group) `type="multiple"` | buttons with `aria-pressed` | Pro |
| Each option needs a description or a price | [Radio Group](https://wingo-ui.com/components/radio-group) `variant="card"` | `radiogroup` of `radio` | Free |
| More than five options, or long labels | [Select](https://wingo-ui.com/components/select) | a `combobox` that opens a `listbox` (a bottom sheet on phones) | Free |

Apple draws a similar line on iOS: "For switching between completely separate sections of an app, use a tab bar instead." Here are the same segments as Tabs, each with its own panel:

```tsx
import { Tabs } from "@/components/ui/tabs";
// ProfileForm and BillingForm are your own components

export function AccountTabs() {
  return (
    <Tabs
      variant="segmented"
      fullWidth
      aria-label="Account"
      options={[
        { value: "profile", label: "Profile", content: <ProfileForm /> },
        { value: "billing", label: "Billing", content: <BillingForm /> },
      ]}
    />
  );
}
```

> Live demo (Tabs): The same thumb as the segmented control, but each segment opens its own panel: switch from Active to Sold and the list slides in from the side you moved toward. Try it at [Tabs](https://wingo-ui.com/components/tabs) and install it with `npx wingo-ui@latest add tabs`.

The Toggle Group needs one more note. In single mode Radix also renders it as a `radiogroup`, but its arrow keys only move focus and Space or Enter presses the item. That is the APG rule for a radio group inside a toolbar, where "the button that is checked does not change" while you arrow through. So an alignment switch in an editor toolbar is a single Toggle Group, and a stand-alone time range is a segmented control. When several can be on, the Toggle Group in `multiple` mode is the only one of the four that fits:

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

export function AmenityFilter() {
  return (
    <ToggleGroup
      type="multiple"
      variant="outline"
      aria-label="Amenities"
      defaultValue={["parking"]}
      options={[
        { value: "parking", label: "Parking" },
        { value: "pets", label: "Pets allowed" },
        { value: "laundry", label: "In-unit laundry" },
      ]}
    />
  );
}
```

> Live demo (Toggle Group): Bold starts on. Press Italic and both stay on, because the formatting group is type multiple; the alignment group next to it is single, so pressing one releases the other. Try it at [Toggle Group](https://wingo-ui.com/components/toggle-group) and install it with `npx wingo-ui@latest add toggle-group`.

Radio cards win when the options are not self-explanatory. "Courier, Locker, Pickup" fits in a segmented control; "Home delivery, FedEx, 1-2 days, $9.99" does not, and squeezing it into a segment hides the price that decides the choice. The [React form components guide](https://wingo-ui.com/blog/react-form-components-guide) covers the wider choice between a radio group, a select and a combobox in a form.

#### What goes wrong with segmented controls?

Four things: too many segments, icons mixed with text, a value outside the options, and a missing name.

- **Too many segments.** Apple says "no more than about five segments on iPhone", and [Flutter's SegmentedButton docs](https://api.flutter.dev/flutter/material/SegmentedButton-class.html) say they are "typically used in cases where there are only 2-5 options." Six or more labels on a 360px screen get cramped or cut off; switch to a select or scrolling tabs.
- **Mixing icons and text.** Apple's guidelines prefer one or the other in a single control. Pick text, or `iconOnly` with labels as names.
- **A controlled value that is not in `options`.** The control shows no thumb, which looks broken. This usually happens when options load after the value.
- **No name.** A radiogroup without `aria-label` reads as an unnamed group of radios.

#### What does a complete example look like?

An orders screen that filters one list by status. The choice changes the content on screen and there are four short options, so this is the segmented control's job. Counts ride on badges, and a status line tells screen readers how many orders are visible:

```tsx
"use client";

import { useState } from "react";
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";

type Order = { id: string; customer: string; total: number; status: "open" | "shipped" | "returned" };

const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

export function OrdersPanel({ orders }: { orders: Order[] }) {
  const [status, setStatus] = useState("all");
  const count = (value: Order["status"]) => orders.filter((order) => order.status === value).length;

  const options: SegmentedControlOption[] = [
    { value: "all", label: "All" },
    { value: "open", label: "Open", badge: count("open") },
    { value: "shipped", label: "Shipped" },
    { value: "returned", label: "Returned", badge: count("returned") },
  ];

  const visible = status === "all" ? orders : orders.filter((order) => order.status === status);

  return (
    <section className="flex flex-col gap-4">
      <SegmentedControl
        aria-label="Order status"
        options={options}
        value={status}
        onValueChange={setStatus}
        fullWidth
        className="sm:max-w-md"
      />
      <p role="status" className="text-sm text-muted-foreground">
        {visible.length} {visible.length === 1 ? "order" : "orders"}
      </p>
      <ul className="flex flex-col divide-y divide-border">
        {visible.map((order) => (
          <li key={order.id} className="flex justify-between gap-4 py-3 text-sm">
            <span className="truncate">{order.customer}</span>
            <span className="tabular-nums">{usd.format(order.total)}</span>
          </li>
        ))}
      </ul>
    </section>
  );
}
```

In a form, drop the state and give it a `name`. A server action then reads it like any radio:

```tsx
<form action={saveDelivery}>
  <SegmentedControl
    name="delivery"
    aria-label="Delivery"
    defaultValue="locker"
    fullWidth
    options={[
      { value: "courier", label: "Courier" },
      { value: "locker", label: "Locker" },
      { value: "pickup", label: "Pickup" },
    ]}
  />
  {/* in saveDelivery: formData.get("delivery") */}
</form>
```

#### Where should you start?

Install the free control and drop it where a time range, a view switch or a unit toggle lives today:

```bash
npx wingo-ui@latest add segmented-control
```

Tabs and Radio Group are free too. The Toggle Group and Nav Tabs from the table above are part of [Wingo UI Pro](https://wingo-ui.com/pricing).

#### Components in this post

- [Segmented Control](https://wingo-ui.com/components/segmented-control) (Free): The iOS segmented control: pick one of a few options on a raised thumb that slides, and on touch drags along with your finger. Install: `npx wingo-ui@latest add segmented-control`
- [Tabs](https://wingo-ui.com/components/tabs) (Free): Switch between views of the same page with a sliding indicator: underline for sections, pill for filters, segmented for a compact switch. Install: `npx wingo-ui@latest add tabs`
- [Toggle Group](https://wingo-ui.com/components/toggle-group) (Pro): A row of toggles where one or several stay pressed, for text formatting, alignment, view switches and quick filters. Install: `npx wingo-ui@latest add toggle-group`
- [Radio Group](https://wingo-ui.com/components/radio-group) (Free): Pick exactly one of a few visible options: rows with a dot that springs in, or cards with icons, prices and a selection ring that slides. Install: `npx wingo-ui@latest add radio-group`

#### FAQ

##### Does shadcn/ui have a segmented control?

Not as of October 2026. Its component list has Tabs, Toggle Group, Radio Group and Button Group, so building one on shadcn/ui means restyling one of those. Pick the base by what the choice does: Tabs for panels, a radio group for a value.

##### What is the difference between a segmented control and tabs?

Tabs swap in a different panel and expose tablist, tab and tabpanel roles linked by aria-controls. A segmented control picks a value that changes the content already on screen, such as a time range, and is a radiogroup. Apple's guidelines send switching between separate sections of an app to a tab bar.

##### How many options should a segmented control have?

Two to five. Apple's Human Interface Guidelines say no more than about five segments on iPhone, and Flutter's Material SegmentedButton docs say segmented buttons are typically used with 2 to 5 options. Past five, use a select or a scrolling row of tabs.

##### Is a segmented control accessible to screen readers?

It is when it is built as a radiogroup of radio items with a name: one tab stop, arrow keys that move and check, and aria-checked on the selected segment. Icon-only segments also need a text name, which Wingo UI's iconOnly mode takes from each option's label.

##### Can a segmented control submit with a form?

Yes. Give Wingo UI's Segmented Control a name and, inside a form, it submits the selected value like a radio group, so FormData and server actions read it with formData.get.

##### Is the Wingo UI Segmented Control free?

Yes. The Segmented Control, Tabs, Radio Group and Select are free and install with npx wingo-ui@latest add. The Toggle Group and Nav Tabs are part of Wingo UI Pro.

---

Source: https://wingo-ui.com/blog/react-segmented-control

### React Use Mobile Hook: SSR-Safe, No Hydration Mismatch

> Why a React use mobile hook is false on the server, when CSS breakpoints beat it, and an SSR-safe useSyncExternalStore version with no hydration mismatch.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Next.js and Tailwind CSS](https://wingo-ui.com/blog/category/nextjs-tailwind)
- Reading time: 9 min
- Canonical: https://wingo-ui.com/blog/react-use-mobile-hook-ssr

#### TL;DR

A React use mobile hook returns false on the server because the server has no screen: it renders the HTML before any browser reports a width, and hydration has to repeat that guess. Switch visible layout with CSS breakpoints, which apply at first paint, and keep the hook for behavior after an interaction, such as opening a bottom sheet instead of a dialog. Build the hook on useSyncExternalStore with a server snapshot, so hydration matches and every later mount reads the real value on its first render.

Sooner or later, a Next.js app that has to work on phones grows a React use mobile hook: a `useIsMobile()` that returns true below 768px, copied from a starter or from shadcn/ui. It works in the browser, then surprises you three ways: it returns false on the server, a careless version throws a hydration error, and a phone can briefly see the desktop version of whatever the hook controls. This tutorial explains where each one comes from, which jobs belong to CSS breakpoints, and how to write an SSR-safe media query hook on `useSyncExternalStore` that hydrates cleanly.

#### Why is useIsMobile false on the server?

Because the server has no screen. React renders the HTML before any browser has reported a width, so a hook that reads `matchMedia` has nothing to read and must return a fixed guess. In the Next.js App Router the gap is wider still: a page that uses no request-time APIs is prerendered once at build time, with no request and no visitor at all.

The guess itself is harmless. The trouble is hydration: the first client render has to produce the same markup as the server, so the browser repeats the guess, and the value may only change after hydration. On a phone, the server's answer stays on screen from the first paint until the JavaScript has downloaded, parsed and hydrated, and on a slow connection that takes a while. Anything visible that depends on the hook is wrong for that whole window.

So the useful question is which jobs can live with a guess for that window.

#### Why does a useIsMobile hook cause a hydration mismatch?

Only when it reads `window` during render: the browser's first render then disagrees with the server's HTML. Search for a React is mobile hook and you find three shapes, and only the first one does that. We server-rendered each one with `renderToString` from React 19.3, hydrated it with `hydrateRoot` in Chromium at 390px through Playwright, and mounted a second copy 300ms later, the way a dialog, a lazy panel or a client-side route mounts after hydration:

| Pattern | Hydration at 390px | First render of a later mount |
| --- | --- | --- |
| `typeof window` check in render | Text: an error, the tree is rebuilt on the client. A class: no error, the server's class stays | `true` |
| `useState` + `useEffect` | No error: `false`, then `true` after the effect | `false`, then `true` |
| `useSyncExternalStore` with a server snapshot | No error: `false`, then `true` right after hydration | `true` |

The first shape is the obvious one:

```tsx
// wrong: the server says false, a phone says true during hydration
const isMobile = typeof window !== "undefined" && matchMedia("(max-width: 767.98px)").matches;
```

When the hook changes text, React 19 reports "Hydration failed because the server rendered text didn't match the client" and rebuilds that tree on the client, which throws away the work SSR did. The [Next.js hydration error page](https://nextjs.org/docs/messages/react-hydration-error) lists this exact check as a common cause.

When the hook only picks a `className`, nothing fails, and that is worse. In development React 19 logs "A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up." A production build logs nothing. In our test the phone kept `class="desktop"` after hydration in both builds, and nothing corrects it while the value stays the same.

The second shape is the shadcn use-mobile hook that ships with the shadcn/ui Sidebar. As of October 2026 [its source](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/hooks/use-mobile.ts) keeps `undefined` in state, measures in an effect and returns `!!isMobile`:

```ts
const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)

React.useEffect(() => {
  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
  // ...subscribes to mql, then:
  setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
}, [])

return !!isMobile
```

It never mismatches, because every first render returns `false`. The catch is the word every: a component that mounts long after hydration also renders as a desktop once, then corrects itself in the effect. An `autoFocus={!isMobile}` on a field in that component is true on the first commit, and React focuses the field during that commit, so a phone can still get the keyboard you meant to avoid.

The [shadcn Sidebar](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/sidebar.tsx) gets away with the false start for a good reason. The desktop markup it renders on the server carries `hidden md:block`, so a phone never sees it, and on a phone the correction swaps in a Sheet that stays closed until someone opens it. That is the pattern to copy, and the next section spells it out.

#### When should you use CSS breakpoints instead of a hook?

For everything visible before the first interaction. CSS media queries apply at first paint, before any JavaScript runs, so they are already right in the server's HTML. Render both versions and let a breakpoint hide one:

```tsx
// app/orders/page.tsx: a server component, no hook to correct
import { getOrders } from "@/lib/orders";
import { OrderCard } from "./order-card";
import { OrderRow } from "./order-row";

export default async function OrdersPage() {
  const orders = await getOrders();
  return (
    <>
      <ul className="flex flex-col gap-2 md:hidden">
        {orders.map((order) => (
          <OrderCard key={order.id} order={order} />
        ))}
      </ul>
      <table className="hidden w-full md:table">
        <tbody>
          {orders.map((order) => (
            <OrderRow key={order.id} order={order} />
          ))}
        </tbody>
      </table>
    </>
  );
}
```

Both trees are in the DOM, which costs little for a nav or a page of 20 rows. When the switch depends on the space a component gets rather than the window, Tailwind v4's `@container` and `@md:` variants do it in CSS with no hook at all.

Keep the hook for decisions that start after the person does something, or that never show on the first paint:

- which overlay opens: a bottom sheet below 768px, a popover or a dialog above it
- the edge a panel slides in from
- whether a field takes focus when a panel opens, since focusing it on a phone pops the keyboard over the content
- where a click goes: a full page on a phone, a side panel next to the list on desktop

A closed overlay renders only its trigger, and the trigger is usually the same button in both modes, so the hook can switch the overlay freely. The [shadcn responsive dialog](https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile) tutorial builds that switch for a dialog, and the [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) guide applies the same rule across a whole component library.

#### How do you write an SSR-safe useMediaQuery hook?

Read the query through `useSyncExternalStore`, React's API for values that live outside React, and give it a server snapshot. That is the whole fix for useMediaQuery SSR problems:

```ts
// hooks/use-media-query.ts
import { useCallback, useSyncExternalStore } from "react";

// the complement of Tailwind's md: variant, in the same unit
export const MOBILE_QUERY = "(width < 48rem)";

const lists = new Map<string, MediaQueryList>();

function getList(query: string) {
  let list = lists.get(query);
  if (!list) {
    list = window.matchMedia(query);
    lists.set(query, list);
  }
  return list;
}

export function useMediaQuery(query: string, serverFallback = false) {
  // stable per query, or React unsubscribes and subscribes again on every render
  const subscribe = useCallback(
    (onChange: () => void) => {
      const list = getList(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query],
  );
  return useSyncExternalStore(
    subscribe,
    () => getList(query).matches,
    // the server and the hydration render
    () => serverFallback,
  );
}

export function useIsMobile() {
  return useMediaQuery(MOBILE_QUERY);
}

// the same check in event handlers and effects; false on the server
export function matchesMedia(query: string) {
  return typeof window !== "undefined" && getList(query).matches;
}
```

Here is what React does with it:

- **Server and hydration.** React calls the third function, so the server HTML and the hydration render agree. Leave it out and the [React docs](https://react.dev/reference/react/useSyncExternalStore) are blunt: "rendering the component on the server will throw an error."
- **Right after hydration.** Once the effects run, React compares the server snapshot with the browser's answer and, when they differ, re-renders synchronously. That is the `false`, then `true` in the table above.
- **Every later mount.** React calls the second function during the first render, so a sheet that opens on a phone renders as a phone from its first frame.
- **Updates.** A `MediaQueryList` fires `change` only when the query flips, so dragging the window edge costs no renders until it crosses the breakpoint, unlike a `resize` listener. The lists are cached per query because `matches` is read on every render.

If the shadcn Sidebar added `hooks/use-mobile.ts` to your project, point that file at the new hook. The Sidebar keeps its import, and its `hidden md:block` desktop markup now flips at the same width as the hook:

```ts
// hooks/use-mobile.ts
import { MOBILE_QUERY, useMediaQuery } from "@/hooks/use-media-query";

export const useIsMobile = () => useMediaQuery(MOBILE_QUERY);
```

Event handlers do not need the hook at all. Read the query at the moment of the click:

```tsx
// app/orders/use-open-order.ts
"use client";

import { useRouter } from "next/navigation";
import { useState } from "react";
import { MOBILE_QUERY, matchesMedia } from "@/hooks/use-media-query";

export function useOpenOrder() {
  const router = useRouter();
  const [selected, setSelected] = useState<string | null>(null);

  function openOrder(id: string) {
    // phones get a full page, desktops a panel next to the list
    if (matchesMedia(MOBILE_QUERY)) router.push(`/orders/${id}`);
    else setSelected(id);
  }

  return { selected, openOrder };
}
```

##### Which serverFallback should you pass?

The answer whose mistake costs least during the hydration window. For `useIsMobile`, `false` is usually right, because the decisions it drives start after a tap and by then the real value is in. For a query that changes something visible, pick the answer that works on every device. With `(hover: hover)` that is `false`: the server renders the always-visible version of a control, and a mouse user gets the hover polish a moment later.

##### Should the query use px or rem?

Use the unit of your CSS breakpoints. Tailwind v4 defines `--breakpoint-md: 48rem`, and our build compiles `md:` to `@media (min-width: 48rem)`. [Media Queries Level 4](https://www.w3.org/TR/mediaqueries-4/#units) says relative units in media queries are "based on the initial value", so 48rem follows the default font size set in the visitor's browser and ignores your `html { font-size }`. A hook written in px does not move with it.

We checked this in Chromium through Playwright, with a 900px window and the default font size set to 20px. `(min-width: 48rem)` stopped matching, so Tailwind showed the phone layout, while `(max-width: 767.98px)` did not match either, so a px hook still reported a desktop. `(width < 48rem)` matched, in step with the CSS. Range syntax also retires the `.98px` trick that [Bootstrap's docs](https://getbootstrap.com/docs/5.3/layout/breakpoints/) explain with "viewports with fractional widths". As of October 2026, [MDN's compatibility data](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media) lists range syntax from Chrome 104, Firefox 102 and Safari 16.4.

Breakpoints are tokens like colors and radii, so keep them in one place: the [Tailwind v4 design tokens](https://wingo-ui.com/blog/tailwind-v4-design-tokens) guide shows how to layer them. A caveat about our own code: as of October 2026 the `MOBILE_QUERY` in Wingo UI is still `(max-width: 767.98px)`, so it has the gap described above. With a 20px default font size, `md:` classes switch at 960px while the Drawer and the Sheet, which call `useIsMobile()`, switch at 768px. In your own components, call `useMediaQuery("(width < 48rem)")` where the hook and your classes have to agree.

#### Can Next.js detect mobile on the server?

It can guess from request headers, and only on routes rendered per request. Most ways to make React detect mobile or desktop on the server read the User-Agent header. Next.js parses it with [`userAgent()`](https://nextjs.org/docs/app/api-reference/functions/userAgent) from `next/server`, whose `device.type` is `"mobile"`, `"tablet"` and a few others, or `undefined` for desktop browsers. Pass the guess down as the server snapshot and hydration still matches, because the prop travels with the page:

```tsx
// app/orders/page.tsx
import { headers } from "next/headers";
import { userAgent } from "next/server";
import { OrdersScreen } from "./orders-screen";

export default async function OrdersPage() {
  const { device } = userAgent({ headers: await headers() });
  return <OrdersScreen phoneGuess={device.type === "mobile"} />;
}
```

```tsx
// app/orders/orders-screen.tsx
"use client";

import { MOBILE_QUERY, useMediaQuery } from "@/hooks/use-media-query";

export function OrdersScreen({ phoneGuess }: { phoneGuess: boolean }) {
  // the server and the hydration render both use the guess, then the real value takes over
  const isMobile = useMediaQuery(MOBILE_QUERY, phoneGuess);
  return <p>{isMobile ? "Tap an order to open it" : "Select an order to see it on the right"}</p>;
}
```

Know the cost before you add it:

- **Dynamic rendering.** [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers) is a request-time API, so the page renders on every request instead of once at build time, and any shared cache has to vary by user agent. With Cache Components turned on, the read also has to sit inside a `<Suspense>` boundary, or `next build` fails.
- **It names a device.** The header stays the same for a desktop browser narrowed to 600px, a tablet app in split screen and a phone turned to landscape, so it cannot tell you the window width. Since Safari 13, [Safari on iPad sends the same user agent as Safari on macOS](https://webkit.org/blog/9674/new-webkit-features-in-safari-13/) by default, so most iPads read as desktops.
- **Client hints cover Chromium only.** `Sec-CH-UA-Mobile` arrives without opting in, but as of October 2026 [MDN's compatibility data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Mobile) lists it in Chrome and Edge and not in Firefox or Safari.

It pays off on app pages that are dynamic anyway, such as a signed-in dashboard, and rarely on marketing pages you want served from a CDN.

#### How do the Wingo UI Sheet and Drawer use the hook?

Only for behavior, and their closed state renders the same markup at every width. The free [useMediaQuery](https://wingo-ui.com/components/use-media-query) hook is built the same way, with the same `serverFallback` parameter, plus `useIsMobile`, `useIsTouch` for `(pointer: coarse)`, `useBreakpoint` and `matchesMedia`. Resize this window across 768px, or open the page on a phone:

> Live demo (useMediaQuery): Resize the window across 768px: the useIsMobile() card and the (width < 48rem) card flip together at the default font size, and the ruler moves to the widest Tailwind breakpoint that matches. Try it at [useMediaQuery](https://wingo-ui.com/components/use-media-query) and install it with `npx wingo-ui@latest add use-media-query`.

The [Drawer](https://wingo-ui.com/components/drawer) calls `useIsMobile()` in its root. Phones always get the draggable sheet; from 768px the `desktop` prop picks a centered sheet, a side panel or a dialog. Its trigger is the same Radix Dialog trigger in every mode, so the server's guess changes nothing on screen, and the open state lives in the root, so a tablet rotated across 768px keeps the drawer open.

> Live demo (Drawer): Tap Filters: below 768px the drawer slides up as a sheet you can drag down to close; on a wider screen the same component opens a centered dialog. Try it at [Drawer](https://wingo-ui.com/components/drawer) and install it with `npx wingo-ui@latest add drawer`.

The [Sheet](https://wingo-ui.com/components/sheet) does the same for side panels. `mobileSide="bottom"` turns a filter panel from the right into a bottom sheet on phones, and the side only matters once the sheet is open:

```tsx
import { SlidersHorizontal } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Sheet } from "@/components/ui/sheet";

export function OrderFilters() {
  return (
    <Sheet
      side="right"
      mobileSide="bottom"
      title="Filters"
      description="Status, date and amount"
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
    >
      <p className="text-sm text-muted-foreground">Pick the orders you want to see.</p>
    </Sheet>
  );
}
```

#### What should you do next?

Paste the hook above into `hooks/use-media-query.ts`, or install ours with `npx wingo-ui@latest add use-media-query`. Then search your codebase for `useIsMobile` and sort every call: visible layout moves to `md:` classes, behavior stays on the hook. More posts on the same stack live in [Next.js and Tailwind CSS](https://wingo-ui.com/blog/category/nextjs-tailwind).

#### Components in this post

- [useMediaQuery](https://wingo-ui.com/components/use-media-query) (Free): SSR-safe hooks for media queries, phone widths, touch screens and the current Tailwind breakpoint. Install: `npx wingo-ui@latest add use-media-query`
- [Sheet](https://wingo-ui.com/components/sheet) (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: `npx wingo-ui@latest add sheet`
- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`

#### FAQ

##### Why does useIsMobile return false on the server?

The server renders the HTML before any browser reports a screen width, so the hook has nothing to measure and returns a fixed guess. Hydration has to repeat that guess, and the real value arrives right after it.

##### Does the shadcn useIsMobile hook cause a hydration mismatch?

No. The shadcn use-mobile hook keeps undefined in state and measures the screen in an effect, so its first render returns false on the server and in the browser alike. The cost is that a component mounted after hydration also renders as a desktop once, until the effect corrects it.

##### How do I fix a hydration mismatch caused by useMediaQuery?

Stop reading window during render and read the query through useSyncExternalStore, with a getServerSnapshot that returns the same value on the server and during hydration. React then corrects the value right after hydration, with no mismatch.

##### Can Next.js detect a mobile device on the server?

It can guess from the User-Agent header with userAgent() from next/server, which makes the route render per request. The header names a device and says nothing about the viewport width, so use the guess as the server snapshot only and keep layout in CSS.

##### Why does my useIsMobile hook disagree with Tailwind's md breakpoint?

Tailwind v4 breakpoints are in rem (md is 48rem), and media queries resolve rem from the browser's default font size, while many hooks, shadcn's included, hard-code 768px. When a visitor raises that font size the two disagree; write the hook's query as (width < 48rem) and both flip at the same width.

##### Is the Wingo UI useMediaQuery hook free?

Yes. useMediaQuery, useIsMobile and the rest of the hook file are free, and so are the Sheet and the Drawer that use it. Install the hook with npx wingo-ui@latest add use-media-query.

---

Source: https://wingo-ui.com/blog/react-use-mobile-hook-ssr

### React Wheel Picker: iOS Wheels for Times and Dates

> Build a React wheel picker on a native snapping scroller: iOS momentum, rows on a 3D cylinder, a sheet on phones, a typed field on desktop, keyboard support.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 8 min
- Canonical: https://wingo-ui.com/blog/react-wheel-picker

#### TL;DR

A React wheel picker that feels native lets the browser do the scrolling: a scroll-snap list brings the phone's own momentum and rubber band, each row is turned on a 3D cylinder from scrollTop in one animation frame, and the value commits once, when the wheel comes to rest. Use wheels for times, durations and birth dates on phones, keep a typed field on desktop, and give mouse drag, the scroll wheel and the keyboard their own paths. Wingo UI's Pro Picker Wheel and Time Picker ship all of this, with a bottom sheet below 768px.

You want a React wheel picker because a phone user should not type 14:30 on a keyboard that covers half the form, and paging a calendar back 36 years to a birth date is worse. The hard part is the feel: the React wheel packages we checked replace the browser's scrolling with their own touch physics. This guide builds the wheel on a native snapping scroller with rows turned on a 3D cylinder, then covers mouse and keyboard paths, the time and date fields built on it, and the pitfalls. How wheel pickers compare across libraries is in our [best React component library for mobile](https://wingo-ui.com/blog/best-react-component-library-for-mobile) comparison.

#### When is a wheel picker the right control?

When the list is medium to long, ordered, and the user can guess what is hidden: hours, minutes, durations, quantities, a birth year. Apple's [Human Interface Guidelines for pickers](https://developer.apple.com/design/human-interface-guidelines/pickers) say to "consider using a picker to offer medium-to-long lists of items", to prefer a pull-down button for "a fairly short list of choices", and a list or table for "a very large set of items". It also suggests minute steps that divide 60 evenly, such as quarter hours.

On the web that gives four rules:

- Two to five options: a [Segmented Control](https://wingo-ui.com/components/segmented-control), so every option is visible.
- 12 hours, 60 minutes, 1 to 99 items, the years since 1920: a wheel.
- Hundreds of unordered names (countries, products): a searchable [Select](https://wingo-ui.com/components/select). A wheel only jumps to a typed prefix.
- A date near today (a delivery, a booking): a calendar, because the weekday matters.

#### Why build a wheel on a native snapping scroller?

Because then the finger, the momentum and the rubber band at the ends are the phone's own, and a trackpad or a mouse wheel turns it with no extra code. A search for "ios picker web" in October 2026 mixed a Mendix widget, React Native packages and Flutter's CupertinoPicker in with the web answers. The two React DOM packages we found both run their own physics:

| Package (as of October 2026) | License, last release | How it moves |
| --- | --- | --- |
| [@ncdai/react-wheel-picker](https://react-wheel-picker.chanhdai.com/docs/getting-started) 1.2.3 | MIT, August 23, 2026 | own touch, mouse and wheel handlers; rows on a 3D cylinder with CSS transforms |
| [react-mobile-picker](https://www.npmjs.com/package/react-mobile-picker) 1.2.0 | MIT, August 3, 2025 | own `touchmove` handler and `translate3d`; mouse wheel off by default |

Both work. @ncdai/react-wheel-picker, which also handles arrows, Home / End and type-ahead, is the better pick if you want a free, unstyled wheel and will build the field yourself. Its feel is tuned through `dragSensitivity` and `scrollSensitivity`; a native scroller decelerates like every other list on that phone.

The native recipe has three parts. The list scrolls with `scroll-snap-type: y mandatory`, every row snaps to the center, and two rows of padding let the first and last rows reach it. One `requestAnimationFrame` per scroll reads `scrollTop` and writes `rotateX` and opacity straight to the rows, never through React state. And the value commits once, at rest: on `scrollend`, which [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollend_event) lists from Chrome 114, Firefox 109 and Safari 26.2, with a 120ms idle timer for older Safari.

```tsx
"use client";

import { useEffect, useRef } from "react";

const ROW = 44; // five rows in a 220px window

export function MiniWheel({ options, onSettle }: { options: string[]; onSettle: (value: string) => void }) {
  const listRef = useRef<HTMLDivElement>(null);
  const settleRef = useRef(onSettle);
  useEffect(() => {
    settleRef.current = onSettle;
  });

  useEffect(() => {
    const list = listRef.current;
    if (!list) return;
    const rows = Array.from(list.firstElementChild?.children ?? []) as HTMLElement[];
    let frame = 0;
    let idle: ReturnType<typeof setTimeout> | undefined;
    let last = "";

    // the turn and the fade go straight to the rows, never through React state
    const paint = () => {
      frame = 0;
      const pos = list.scrollTop / ROW;
      rows.forEach((row, i) => {
        const d = i - pos;
        row.style.transform = `perspective(400px) rotateX(${Math.max(-55, Math.min(55, -d * 20))}deg)`;
        row.style.opacity = String(Math.max(0.35, 1 - Math.min(Math.abs(d), 3) * 0.22));
      });
    };
    // one commit when the wheel is at rest, never one per row passed
    const settle = () => {
      clearTimeout(idle);
      const value = options[Math.round(list.scrollTop / ROW)];
      if (value !== undefined && value !== last) settleRef.current((last = value));
    };
    const onScroll = () => {
      if (!frame) frame = requestAnimationFrame(paint);
      clearTimeout(idle);
      idle = setTimeout(settle, 120); // Safari before 26.2 has no scrollend
    };

    paint();
    list.addEventListener("scroll", onScroll, { passive: true });
    list.addEventListener("scrollend", settle);
    return () => {
      list.removeEventListener("scroll", onScroll);
      list.removeEventListener("scrollend", settle);
      cancelAnimationFrame(frame);
      clearTimeout(idle);
    };
  }, [options]);

  return (
    <div ref={listRef} className="h-[220px] snap-y snap-mandatory overflow-y-scroll overscroll-contain [scrollbar-width:none]">
      <div className="py-[88px]">
        {options.map((option) => (
          <div key={option} className="flex h-11 snap-center items-center justify-center text-xl tabular-nums">
            {option}
          </div>
        ))}
      </div>
    </div>
  );
}
```

That is the core of the Wingo UI [Picker Wheel](https://wingo-ui.com/components/picker-wheel). The sketch misses a starting value, disabled rows, looping, every input that is not a finger, and wheels mounted while hidden.

#### How do mouse and keyboard users turn the wheel?

A mouse wheel and a trackpad scroll it natively; dragging and keys need their own code. In the Picker Wheel only a mouse goes through pointer events: past 8 pixels of movement, snapping turns off and `scrollTop` follows the pointer. On release, a `motion` inertia animation continues from the measured velocity, and its `modifyTarget` rounds the landing point to a row. A click on a visible row glides it to the center.

Each column is one Tab stop with `role="listbox"`. ArrowUp and ArrowDown move a row, PageUp and PageDown five, Home and End jump to the ends, typing jumps to the next option that starts with the text ("19", then "199" on a year wheel), and ArrowLeft and ArrowRight change column. `aria-activedescendant` points at the centered option, which carries `aria-selected`. The focus ring hugs the center row, where the edge fade cannot hide it.

#### What props does the Picker Wheel need?

`columns` (or `options` for a single wheel), a value and `onValueChange`. Everything else has a default:

```tsx
"use client";

import { useState } from "react";
import { PickerWheel, pickerRange } from "@/components/ui/picker-wheel";

const hours = pickerRange(0, 12);
const minutes = pickerRange(0, 59, { pad: 2 });

export function CallDuration() {
  const [duration, setDuration] = useState(["1", "25"]);
  return (
    <PickerWheel
      aria-label="Call duration"
      value={duration}
      // once per settle, with every column's value and the id of the column that moved
      onValueChange={(value) => setDuration(value)}
      columns={[
        { id: "hours", label: "h", options: hours, align: "end" },
        { id: "minutes", label: "min", options: minutes, align: "start", loop: true },
      ]}
    />
  );
}
```

The props worth knowing:

- `onValueChange` fires once per settle, never per row passed, so it is safe to save from it.
- `loop` (on the wheel or per column) wraps 59 back to 00: the column renders extra copies and jumps silently to the middle one at rest. Only the middle copy has `role="option"`.
- `size` sets 36, 44 or 52px rows; `visibleRows` (odd, default 5) makes the wheel 220px tall at `md`; `perspective` tilts rows 20, 10 or 0 degrees each (`ios`, `subtle`, `flat`).
- A disabled option is struck through, and a wheel that lands on one glides on to the nearest enabled row: `pickerRange(36, 46, { disabled: (n) => n === 38 })` for a sold-out shoe size.
- `haptics` plays a selection tick each time a finger, a mouse drag or the scroll wheel brings a new row to the center, never for keys. It works on Chrome for Android; why a scroll cannot tick on an iPhone is in our [web vibration API guide](https://wingo-ui.com/blog/web-vibration-api-haptic-feedback).

`PickerWheelField` puts the same wheels in a form field: a bottom sheet with Done and Cancel below 768px, a popover that applies live on desktop.

#### How do you build a React time picker wheel that still types on desktop?

Use the [Time Picker](https://wingo-ui.com/components/time-picker), which switches by width. Below 768px the field is read-only with `inputMode="none"`, so no keyboard opens, and a tap opens a bottom sheet with hour and minute wheels. From 768px up it is a text input that reads "1430", "2:30pm" or "2p", steps minutes with ArrowUp and ArrowDown, and opens a panel of columns on click. The value is always "HH:mm" in 24 hours:

```tsx
"use client";

import { useState } from "react";
import { TimePicker } from "@/components/ui/time-picker";

const lunchBreak = (time: string) => time >= "13:00" && time < "14:00";

export function PickupTime() {
  const [time, setTime] = useState("11:30");
  return (
    <TimePicker
      label="Pickup time"
      name="pickup"
      locale="en-US"
      min="09:00"
      max="18:00"
      minuteStep={15}
      disabledTimes={lunchBreak}
      value={time}
      onValueChange={setTime}
    />
  );
}
```

> Live demo (Time Picker): Type 2:30pm or 1430 and press Enter, or click the field for the columns; at phone width a tap opens the wheels in a bottom sheet, and the lunch hour stays blocked either way. Try it at [Time Picker](https://wingo-ui.com/components/time-picker) and install it with `npx wingo-ui@latest add time-picker`.

The sheet edits a draft: Done commits it, and dragging the sheet away keeps the old time. Times outside `min` and `max` or blocked by `disabledTimes` are disabled rows on the wheels too.

#### Should a date be a wheel or a calendar?

A wheel for a date the user knows by heart and that sits far from today, like a birth date: three flicks instead of paging through years. A calendar for dates near today, where the weekday matters. That is why the [Date Picker](https://wingo-ui.com/components/date-picker) opens a calendar, in a bottom sheet on phones.

For the birth date, `useDateWheel` is a React date wheel picker in one hook: day, month and year columns in the locale's order (month, day, year for en-US), month names in that language, days that follow the month (February 29 only in leap years) and years between `min` and `max`. Values are ISO dates such as "1990-05-17".

> Live demo (Picker Wheel): Flick the month, the day or the year, drag them with a mouse, or Tab to the year and type 1985: the date and the age under the wheel update when it comes to rest. Try it at [Picker Wheel](https://wingo-ui.com/components/picker-wheel) and install it with `npx wingo-ui@latest add picker-wheel`.

For the wheel on phones and a typed field on desktop, render both and switch with CSS, so the server HTML matches the first paint (the [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) guide explains why a `useIsMobile` check would flash). One ISO string feeds both:

```tsx
"use client";

import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";
import { PickerWheelField, useDateWheel } from "@/components/ui/picker-wheel";
import { formatDate, fromISODate, toISODate } from "@/lib/date-utils";

export function BirthdayField({ initial }: { initial: string }) {
  const [birthday, setBirthday] = useState(initial); // "1990-05-17"
  const [today] = useState(() => new Date());
  const wheel = useDateWheel({ value: birthday, onValueChange: setBirthday, locale: "en-US", min: "1920-01-01", max: toISODate(today) });

  return (
    <>
      {/* phones: three wheels in a bottom sheet, Done to commit */}
      <div className="md:hidden">
        <PickerWheelField
          label="Date of birth"
          {...wheel}
          formatValue={() => formatDate(fromISODate(birthday), "en-US", { dateStyle: "long" })}
        />
      </div>
      {/* 768px and up: type 05171990, or open the calendar */}
      <div className="hidden md:block">
        <DatePicker
          label="Date of birth"
          locale="en-US"
          max={today}
          clearable={false}
          value={fromISODate(birthday)}
          onValueChange={(date) => date && setBirthday(toISODate(date))}
        />
      </div>
      <input type="hidden" name="birthday" value={birthday} />
    </>
  );
}
```

One catch: `useDateWheel` always holds a date (today when you pass none), so the field is never empty. That suits editing a profile; a required date that starts blank belongs in the Date Picker.

#### What goes wrong with a wheel picker on a phone?

Most bugs come from the wheel's surroundings. The Picker Wheel handles these, and you will meet them if you build your own:

- **The sheet steals the drag.** A wheel at its first row hands a downward drag to the drawer. The columns carry `data-vaul-no-drag`, and `overscroll-behavior: contain` keeps a hard flick from scrolling the page.
- **A wheel mounted while hidden.** Inside a closed sheet the list has no height, so setting `scrollTop` does nothing. A `ResizeObserver` scrolls to the value once the list has a size.
- **Committing per row.** Saving on every row that passes floods your API and fires validation mid-spin.
- **Reduced motion.** With `prefers-reduced-motion` the rows stay flat and programmatic moves jump instead of gliding.
- **Feedback only in the tick.** Desktop and iPhone users feel nothing, so the centered row and the field text must carry the value.

#### Where should you start?

Open this page on your phone and flick the two demos above. The Picker Wheel, Time Picker and Date Picker are part of [Wingo UI Pro](https://wingo-ui.com/pricing); with a Pro account signed in through `npx wingo-ui@latest login`, `npx wingo-ui@latest add picker-wheel` copies the component and everything it imports into your project. A React wheel picker component is one piece of a phone-friendly form; the other patterns are in [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Picker Wheel](https://wingo-ui.com/components/picker-wheel) (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: `npx wingo-ui@latest add picker-wheel`
- [Time Picker](https://wingo-ui.com/components/time-picker) (Pro): A time-of-day field to type into or pick from columns, with 12 / 24 hours by locale, minute steps, limits and iOS wheels on phones. Install: `npx wingo-ui@latest add time-picker`
- [Date Picker](https://wingo-ui.com/components/date-picker) (Pro): A date field to type in your locale or pick from a calendar popover, with presets, limits and an optional time; a sheet on phones. Install: `npx wingo-ui@latest add date-picker`

#### FAQ

##### Is there an iOS-style wheel picker for React web apps?

Yes. As of October 2026 the open source options are @ncdai/react-wheel-picker (1.2.3, MIT) and react-mobile-picker (1.2.0, MIT), which both run their own touch physics. Wingo UI's Picker Wheel (Pro) scrolls natively and adds a form field that opens a bottom sheet on phones, a date hook and haptic ticks.

##### Should I use input type=time instead of a wheel picker?

Use the native input when its look and behavior are good enough, because it costs nothing and is accessible by default. You cannot style the picker it opens, it differs between browsers and OS versions, and it cannot show blocked times such as a lunch break, which is when a custom wheel earns its code.

##### How do I make a wheel picker loop around in React?

Render the options several times and jump back to the middle copy whenever the wheel comes to rest, which looks identical. In the Wingo UI Picker Wheel, loop on the wheel or on one column does this, with at least 40 rows on each side of the middle copy so a hard flick never reaches the end.

##### Does a web wheel picker vibrate on iPhone?

No. Safari has no Vibration API, and the iPhone's one web haptic, the tick of a native switch, plays only for a tap, never for a scroll. On Chrome for Android the Picker Wheel ticks each time a new row reaches the center.

##### Is the Wingo UI Picker Wheel free?

No. The Picker Wheel, Time Picker and Date Picker are Pro components; the Drawer and Field they build on are free. Pro costs $8 a month, $80 a year or $150 once.

---

Source: https://wingo-ui.com/blog/react-wheel-picker

### Responsive Table Mobile Layout: Rows to Cards in React

> A responsive table mobile guide: when rows should become cards below 768px, which columns survive, and how sorting and bulk actions work without headers.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/responsive-table-mobile-cards

#### TL;DR

For a responsive table on mobile, render each row as a card below 768px: the main field as the title, one status or amount in the corner, two to four label and value pairs, and the row actions in a menu. Keep horizontal scrolling only for grids people compare column by column, like a timesheet or a pricing matrix. Switch the layouts with CSS breakpoints so the server HTML is already right, and give sorting, selection and bulk actions their own phone controls, because the headers and checkbox column are gone.

You ship an admin page with a seven-column table, open it on a phone, and see the client name, half a city and a horizontal scrollbar. The column headers have scrolled away by the time you reach the amount, and nobody can tell which number belongs to which row. A good responsive table mobile view is a different layout for most tables, not a narrower version of the same one. This tutorial shows when to turn rows into cards, which columns make it onto the card, how to build the switch on a plain shadcn/ui table without a hydration flash, and how sorting, selection and bulk actions keep working once the headers and the checkbox column are gone.

The short version of this rule is one of nine in [Mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components). This post is the detailed version.

#### When should a table become cards on a phone?

When people read one record at a time. A list of clients, orders, invoices or tickets is a list of records: on a phone you scan for the one you want, then open it. A card per row shows everything that matters about that record in one glance, with no sideways scrolling and no header to remember.

Keep the table when the job is comparing values across rows and columns. A timesheet, a pricing matrix, a monthly revenue grid or a feature comparison only makes sense when the columns line up, and cards destroy that. For those, let the table scroll sideways inside its own box and pin the first column so every row keeps its name.

| What the table holds | Phone layout | Why |
|---|---|---|
| Records you open (clients, orders, tickets) | Cards | One record per glance, actions in reach |
| Lines of one document (invoice lines, a receipt) | Stacked label and value lines | Reads like the printed document |
| A grid you compare (months x cities, plans x features) | Horizontal scroll, first column pinned | The columns are the point |
| One record's details | A description list, not a table | There is only one row |

The last row catches a common mistake: a "table" with two columns, Label and Value, describing one client. That is a description list. The [Description List](https://wingo-ui.com/components/description-list) stacks label above value on phones and switches to one to three columns based on its container width, so it fits a narrow sidebar card as well as a full page.

#### Why does horizontal scrolling fail for records?

A 390px screen shows two or three columns of an admin table at once. To read one record, people scroll right, lose the name column, scroll back, and repeat for every row. The header usually scrolls out of view vertically too, so the numbers they reach have no labels. Every row costs two scroll directions.

Horizontal scrolling is also what you get by default. Out of the box, shadcn table mobile responsive behavior means a scroll: the shadcn/ui `Table` wraps the `<table>` in a `div` with `relative w-full overflow-x-auto`, so a wide table never breaks the page layout, it just scrolls inside that box. That is the right fallback, and the right layout for comparison grids, but for a client list it means the phone gets the desktop table at a third of the width.

#### Which columns survive on a card?

Five or six of them, each in a defined slot. Go through your columns and give each one a role:

- **Title**: the field people recognize the record by. The client name, the order number, the ticket subject. One per card.
- **Subtitle**: the line that tells two similar titles apart, like the city or the email. Optional.
- **Meta**: one value in the top corner that people scan the list for. A status badge or an amount, not both.
- **Fields**: two to four label and value pairs under the title. Pick the ones people use to decide whether to open the record.
- **Hidden**: everything else. Internal ids, created-at dates, columns that only exist for sorting on desktop.

For a client list with Name, Tax ID, City, Status, Balance, Last invoice, Owner and Created, that gives: Name as the title, City as the subtitle, Status as the meta, Balance, Last invoice and Owner as fields, and Tax ID and Created hidden. The record is still one tap away for the hidden columns.

Actions move into a "⋯" menu in the card's corner that opens as a bottom sheet. Inline icon buttons in a row are fine with a mouse; on a card they compete with the title for a 44px [touch target](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind).

#### How do you turn a shadcn table into cards on mobile?

Render the table and a list of cards from the same data, and let CSS pick one. Here is the full component on top of the stock shadcn/ui table (`npx shadcn@latest add table`), with a plain span for the status so it needs nothing else:

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

type Client = { id: string; name: string; city: string; status: "Active" | "Overdue"; balance: number; owner: string };

const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

function Status({ value }: { value: Client["status"] }) {
  const tone = value === "Overdue" ? "bg-destructive/10 text-destructive" : "bg-muted text-muted-foreground";
  return <span className={`shrink-0 rounded-full px-2 py-0.5 text-xs font-medium ${tone}`}>{value}</span>;
}

export function ClientsTable({ clients }: { clients: Client[] }) {
  return (
    <>
      {/* desktop and tablets: the real table */}
      <div className="hidden md:block">
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Client</TableHead>
              <TableHead>City</TableHead>
              <TableHead>Status</TableHead>
              <TableHead>Owner</TableHead>
              <TableHead className="text-right">Balance</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {clients.map((c) => (
              <TableRow key={c.id}>
                <TableCell className="font-medium">{c.name}</TableCell>
                <TableCell>{c.city}</TableCell>
                <TableCell>
                  <Status value={c.status} />
                </TableCell>
                <TableCell>{c.owner}</TableCell>
                <TableCell className="text-right tabular-nums">{usd.format(c.balance)}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>

      {/* phones: one card per row */}
      <ul aria-label="Clients" className="flex flex-col gap-2 md:hidden">
        {clients.map((c) => (
          <li key={c.id} className="rounded-2xl border p-4">
            <div className="flex items-start justify-between gap-3">
              <div className="min-w-0">
                <p className="font-semibold">{c.name}</p>
                <p className="truncate text-sm text-muted-foreground">{c.city}</p>
              </div>
              <Status value={c.status} />
            </div>
            <dl className="mt-3 grid grid-cols-2 gap-x-4 gap-y-2 text-sm">
              <div>
                <dt className="text-xs text-muted-foreground">Balance</dt>
                <dd className="tabular-nums">{usd.format(c.balance)}</dd>
              </div>
              <div>
                <dt className="text-xs text-muted-foreground">Owner</dt>
                <dd>{c.owner}</dd>
              </div>
            </dl>
          </li>
        ))}
      </ul>
    </>
  );
}
```

That is the whole table to cards on mobile pattern. Three details matter more than the styling.

The switch is a CSS breakpoint. `hidden md:block` and `md:hidden` are both in the server HTML, so a phone paints the cards on first load. If you switch with a `useIsMobile()` hook instead, the server renders the table (the hook is `false` there), the phone shows it, and the cards replace it after hydration. The [use mobile hook guide](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) covers why that happens and where a hook is still the right tool.

The cards are a real list. `<ul>` with an `aria-label` tells a screen reader how many records there are, and `<dt>` / `<dd>` pairs keep each value attached to its label. Hiding the table with `display: none` also removes it from the accessibility tree, so screen reader users on a phone get the same cards as everyone else, not a hidden table.

Both copies render, so the DOM holds every row twice. For 25 rows a page that is nothing. For hundreds, paginate or virtualize, or render the hidden layout lazily. Past 200 rows, the Wingo UI Data Table virtualizes the visible layout and renders only a first screen of 30 rows in the hidden one.

##### What about the CSS-only data-label trick?

The popular alternative keeps one `<table>`, sets `display: block` on rows and cells below a breakpoint, and prints each header through `td::before { content: attr(data-label) }`. It saves the second copy of the markup, but it has two costs. Changing `display` on table elements used to strip their table semantics: Adrian Roselli's long-running test post records that Safari dropped them for every display value until Safari 17 fixed it, and as of his October 2023 update `display: contents` is the one value that may still cause issues ([Tables, CSS Display Properties, and ARIA](https://adrianroselli.com/2018/02/tables-css-display-properties-and-aria.html)). And a screen reader still announces a table with seven columns while the screen shows a stack of cards, with the labels living in CSS.

If you use it, test with VoiceOver on an iPhone and TalkBack on Android. If you cannot test, the two-layout version above is the safer default.

#### How do sorting and bulk actions work without headers?

They need their own controls, because the things people pressed on desktop are gone. Plan each one:

- **Sort**: a row of "Sort by" chips above the cards, one per sortable column, tap to cycle the direction. Or, with many sortable columns, a Sort button that opens a bottom sheet listing "Balance, descending", "Client, ascending" and so on.
- **Filters**: the same filter UI as desktop, opened in a bottom sheet instead of a popover.
- **Selection**: no checkbox column. Long press a card to start selecting (the way Gmail and Photos do it on Android), then each tap toggles a card, and a checkbox appears on every card while selection mode is on.
- **Bulk actions**: a bar that floats at the bottom of the screen while rows are selected, padded for the home indicator, instead of a toolbar band at the top that has scrolled away.
- **Paging**: Load more at the end of the list. Numbered pages with 32px page buttons are hard to hit and break the scroll flow.

Long press is invisible, so it cannot be the only way in. Keep the "⋯" menu visible on every card, and if selection matters, add a visible Select action to the toolbar or the row menu as well.

#### How do you get the same layout from Wingo UI?

Use the [Table](https://wingo-ui.com/components/table) for small read-only tables and the [Data Table](https://wingo-ui.com/components/data-table) for admin lists. Both make a React table mobile responsive without a second markup branch: they render the desktop table and the phone layout in the server HTML and switch at 768px with CSS, and both assign card roles from your columns: the first column is the title, the last numeric column (in the Data Table, the first badge column before that) is the meta, and the rest are fields until you say otherwise with `mobile`.

Here is an orders table with the roles spelled out:

```tsx
// components/recent-orders.tsx
"use client";

import { Table, type TableColumn } from "@/components/ui/table";

type Order = { id: string; customer: string; city: string; placed: string; items: number; total: number };

const columns: TableColumn<Order>[] = [
  { key: "customer", header: "Customer", sortable: true, mobile: "title" },
  { key: "city", header: "City", mobile: "subtitle" },
  { key: "id", header: "Order", mobile: "hidden" },
  { key: "placed", header: "Placed", type: "date", sortable: true },
  { key: "items", header: "Items", type: "number" },
  { key: "total", header: "Total", type: "currency", sortable: true, mobile: "meta" },
];

export function RecentOrders({ orders }: { orders: Order[] }) {
  return <Table caption="Recent orders" columns={columns} data={orders} locale="en-US" onRowClick={(order) => console.log(order.id)} />;
}
```

On a phone each order is a card with the customer as the title, the city under it, the total in the corner, and Placed and Items as fields. The order number stays on desktop only. Columns past the fourth field move behind a "Show more" toggle on the card. Because `customer`, `placed` and `total` are sortable, a row of Sort by chips appears above the cards, and `onRowClick` makes each card a single button that keyboard users reach with Tab.

> Live demo (Table): Below 768px each invoice line becomes a card with the amount in the corner and Sort by chips above; on a wide screen it is a regular table with sortable headers and a totals row. Try it at [Table](https://wingo-ui.com/components/table) and install it with `npx wingo-ui@latest add table`.

The demo is an invoice with five lines and totals. Narrow your window, or open the page on a phone, to see the cards and the separate totals card. For a receipt-like look, `mobileLayout="stack"` lists label and value lines without card chrome, and `mobileLayout="scroll"` keeps the table scrolling sideways with the first column pinned, for comparison grids.

##### How does the Data Table handle selection on a phone?

The way the previous section describes. With `selectionMode="multiple"`, a long press of about 450ms selects a card, then taps add or remove cards, and the bulk actions you return from `bulkActions` float at the bottom. The sort button in the toolbar opens a bottom sheet of "Balance, descending" style options, filters and the row menu open as bottom sheets too, and `mobilePagination="load-more"` (the default) appends rows.

```tsx
// components/clients.tsx
"use client";

import { Archive, Mail, Pencil } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

type Client = { id: string; name: string; city: string; status: string; balance: number; owner: string; taxId: string };

const col = createColumns<Client>();
const columns = col([
  col.accessor("name", { header: "Client" }),
  col.accessor("city", { header: "City", mobile: "subtitle", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" } },
    filter: "multi-select",
  }),
  col.accessor("balance", { header: "Balance", type: "currency" }),
  col.accessor("owner", { header: "Owner" }),
  col.accessor("taxId", { header: "Tax ID", mobile: "hidden" }),
]);

export function Clients({ clients }: { clients: Client[] }) {
  return (
    <DataTable
      data={clients}
      columns={columns}
      caption="Clients"
      locale="en-US"
      selectionMode="multiple"
      bulkActions={(rows) => [
        { label: "Send email", icon: <Mail />, onSelect: () => console.log(rows.length) },
        { label: "Archive", icon: <Archive /> },
      ]}
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
    />
  );
}
```

Here the defaults do the rest: Client becomes the title because it is first, and Status becomes the meta because it is the first badge column. Balance and Owner are the fields. The Data Table shows at most four fields and drops the others from the card, so put the important ones first or mark the rest `hidden` on purpose.

> Live demo (Data Table): On a phone, long press a client card to start selecting, then tap more cards: the bulk bar floats at the bottom. On a wide screen it is the full table. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

When the column mapping is not enough, both components take a `renderCard` function for a card of your own, and `mobileLayout="scroll"` opts a single table out of cards.

#### What if the rows are simpler than a table?

Then skip the table on every screen size. A list of team members, notifications or settings with a name, a line of detail and one value is a list, and the [List](https://wingo-ui.com/components/list) gives it rows with an avatar or icon, a trailing value, a row menu, and swipe actions on touch (swipe left to archive or delete, with a long press sheet as the visible alternative). It reads well at 390px and at 1440px without a breakpoint.

#### How do you test a responsive table on mobile?

Check the one thing that breaks most: the page should never scroll sideways at phone width. A Playwright test catches it in CI:

```ts
// e2e/no-horizontal-scroll.spec.ts
import { test, expect } from "@playwright/test";

test.use({ viewport: { width: 390, height: 844 } });

test("the clients page fits a phone", async ({ page }) => {
  await page.goto("/clients");
  const overflow = await page.evaluate(() => document.documentElement.scrollWidth - window.innerWidth);
  expect(overflow).toBeLessThanOrEqual(0);
  await expect(page.getByRole("list", { name: "Clients" })).toBeVisible();
  await expect(page.getByRole("table")).toBeHidden();
});
```

Add a 360px case for small Android phones, and run it in light and dark. Then do one pass on a real phone: long press a card, open the row menu and the sort control, and check that the bulk bar clears the home indicator.

#### Where should you start?

Take your busiest admin table, give each column a role on paper, and build the card layout next to the table with `md:hidden`. If you would rather start from components that already do the mapping, the sort chips, the long press selection and the floating bulk bar, the Table and the Data Table are part of [Wingo UI Pro](https://wingo-ui.com/pricing); add one with `npx wingo-ui@latest add data-table`. For the step by step build of filters and server pagination on TanStack, read the [TanStack Table v9 data table tutorial](https://wingo-ui.com/blog/tanstack-table-v9-data-table), and find more phone layouts in [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`
- [Table](https://wingo-ui.com/components/table) (Pro): The library's one table look: semantic table parts plus a props API for small read-only tables that turn into cards on phones. Install: `npx wingo-ui@latest add table`
- [List](https://wingo-ui.com/components/list) (Pro): Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder. Install: `npx wingo-ui@latest add list`
- [Description List](https://wingo-ui.com/components/description-list) (Pro): The key-value grid of every detail page: client details, invoice summaries and profiles, with copy buttons, skeletons and iOS rows. Install: `npx wingo-ui@latest add description-list`

#### FAQ

##### How do I make a table responsive on mobile?

Decide first whether people read records or compare columns. For records, render a card per row below 768px with the main field as the title and two to four labeled fields; for comparison grids, keep the table and let it scroll sideways inside its box with the first column pinned.

##### Is the shadcn table responsive on mobile?

It scrolls. The shadcn/ui Table wraps the table in a div with overflow-x-auto, so a wide table scrolls sideways inside its container. Turning rows into cards is up to you, usually with a second markup branch hidden and shown with md: classes.

##### Should I use display: block on table rows to make cards?

It works visually and keeps one copy of the markup, but changing display on table elements removed table semantics in Safari until Safari 17 (Adrian Roselli, October 2023), and display: contents can still cause problems. A separate list of cards with real dt and dd labels is easier to get right for screen readers.

##### How do users sort a table on a phone without column headers?

Give them a control that does what the headers did: a row of Sort by chips above the cards, or a Sort button that opens a bottom sheet listing each column ascending and descending.

##### Should I use useIsMobile to switch between the table and the cards?

No. A media query hook is false on the server, so phones render the table first and swap to cards after hydration. Render both and hide one with md:hidden and hidden md:block, which is correct in the first paint.

---

Source: https://wingo-ui.com/blog/responsive-table-mobile-cards

### Romanian Address Format: The Rules and a React Form

> The Romanian address format part by part: county or Bucharest sector, locality, street, bl. sc. et. ap., the 6-digit postal code, and a React form for it.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Build it: screens and apps](https://wingo-ui.com/blog/category/build)
- Reading time: 10 min
- Canonical: https://wingo-ui.com/blog/romanian-address-format-react-form

#### TL;DR

The Romanian address format starts with the street line (type, name, number, then bl., sc., et. and ap. for block, staircase, floor and apartment), adds the sector in Bucharest, and ends with the 6-digit postal code, the locality and, in domestic use, the county as jud. Cluj. The first two digits of the postal code identify the county, so a form can flag a code from the wrong one. In React, build it as a county select, a locality search that ignores diacritics, street and number, an optional block row and a numeric postal code.

Search for an address form React example and you get a US layout: street, city, state, ZIP. Ship that to customers in Romania and they have nowhere to put the block, the staircase or the Bucharest sector, so the courier calls to ask. This tutorial covers the Romanian address format part by part, checked against the Universal Postal Union's sheet for Romania, with English labels and Romanian data. Then it builds the form in React on [Address Input](https://wingo-ui.com/components/address-input), a component from Wingo UI, the library we build, so we are not neutral.

#### What is the Romanian address format?

A Romanian address runs from the most specific line to the broadest: the street line with the building details, the sector in Bucharest, then the postal code and the locality. The [UPU addressing sheet for Romania](https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/rouEn.pdf) (dated October 2007) gives four rules:

1. The street type comes before the name: Str. (strada), Bd. (bulevardul), Calea, Aleea, Șos. (șoseaua).
2. The number usually ends the street line.
3. Building details can go at the end of the same line: block, staircase, floor, apartment.
4. In Bucharest, the sector can sit on its own line between the street and the locality.

The 6-digit postal code goes to the left of the locality. Here is a Romania address format example from the sheet for an apartment in Bucharest, and one for an office in Craiova:

```text
ASTRA
Drumul Taberei nr. 35, bl. F5, sc. 2, parter, ap. 23
Sector 6
061357 BUCHAREST
ROMANIA

SC PASAJ SA
Str. Bariera Valcii, nr. 215
200716 CRAIOVA
ROMANIA
```

The sheet writes Valcii for Vâlcii, which matters for search later. Both stop at the locality, since the postal code implies the county. In domestic mail, invoices and courier forms, people add the county (județ) after the locality as jud. Cluj, which also tells apart villages that share a name. Here is the Romanian postal address format as form fields, with English labels:

| Form label | Romanian | Written as |
|---|---|---|
| County | județ | jud. Cluj |
| Sector | sector (București only) | Sector 6 |
| City or village | municipiu, oraș, comună, sat | Cluj-Napoca, sat Vâlcele |
| Street | stradă, bulevard, calea, aleea | Str. Memorandumului |
| No. | număr | nr. 28 |
| Block | bloc | bl. A2 |
| Entrance | scară | sc. 1 |
| Floor | etaj | et. 3, or parter for the ground floor |
| Apt. | apartament | ap. 12 |
| Postal code | cod poștal | 400114 |

The labels are Address Input's English defaults. We label the scară "Entrance" because each staircase of a block has its own door, which is what a courier looks for.

#### How do you write a Bucharest or village address?

In Bucharest the sector takes the place of the county, and in the countryside a village usually needs its commune as well. București is a municipality with the rank of a county, split into six sectors. Written on one line, as a courier form or an invoice prints it, a Bucharest address ends with "Sector 6, 061357 București" and has no jud. part.

Villages add a level. Counties contain municipalities (municipii), towns (orașe) and communes (comune), and a commune groups several villages (sate). The National Institute of Statistics keeps the official list as SIRUTA, a register on those three levels that it publishes as a [CSV on data.gov.ro](https://data.gov.ro/dataset/siruta-2024). A village address names the village and usually its commune, as in "sat Vâlcele, com. Feleacu, jud. Cluj": [Feleacu](https://en.wikipedia.org/wiki/Feleacu) is a commune of five villages, one of them Vâlcele. In [many rural communities](https://www.endereco.de/en/general_news/shipping-to-romania-how-to-address-correctly/) there are no street names at all.

`RoAddress`, the value type, has no commune field. Keep the village in `locality` and its SIRUTA code in `localityId`: the register links every village to its commune, so you can print the commune when a courier needs it.

#### How do Romanian postal codes relate to counties?

The first two digits of a Romanian postal code identify the county, or the sector in Bucharest. Romania moved to 6-digit codes on May 1, 2003, and the UPU sheet reads them as a postal region, a district of that region (or a sector in Bucharest), then the delivery area. Per [Wikipedia's article on postal codes in Romania](https://en.wikipedia.org/wiki/Postal_codes_in_Romania), cities of more than 50,000 people get a code per street or small group of addresses, a smaller town has one code for the whole town, and village codes have a 7 as their third digit, like Feleacu's 407270. Poșta Română's [postal code search](https://www.posta-romana.ro/cauta-cod-postal.html) finds the full code for an address.

Here is the Romanian counties list with the [ISO 3166-2:RO](https://en.wikipedia.org/wiki/ISO_3166-2:RO) code (the letters on license plates) and the postal prefix. Address Input stores the county as this code, and the prefixes match its `RO_POSTAL_PREFIXES`:

| County | Code | Postal prefix |
|---|---|---|
| Alba | AB | 51 |
| Arad | AR | 31 |
| Argeș | AG | 11 |
| Bacău | BC | 60 |
| Bihor | BH | 41 |
| Bistrița-Năsăud | BN | 42 |
| Botoșani | BT | 71 |
| Brașov | BV | 50 |
| Brăila | BR | 81 |
| București | B | 01 to 06 (Sector 1 to 6) |
| Buzău | BZ | 12 |
| Caraș-Severin | CS | 32 |
| Călărași | CL | 91 |
| Cluj | CJ | 40 |
| Constanța | CT | 90 |
| Covasna | CV | 52 |
| Dâmbovița | DB | 13 |
| Dolj | DJ | 20 |
| Galați | GL | 80 |
| Giurgiu | GR | 08 |
| Gorj | GJ | 21 |
| Harghita | HR | 53 |
| Hunedoara | HD | 33 |
| Ialomița | IL | 92 |
| Iași | IS | 70 |
| Ilfov | IF | 07 |
| Maramureș | MM | 43 |
| Mehedinți | MH | 22 |
| Mureș | MS | 54 |
| Neamț | NT | 61 |
| Olt | OT | 23 |
| Prahova | PH | 10 |
| Satu Mare | SM | 44 |
| Sălaj | SJ | 45 |
| Sibiu | SB | 55 |
| Suceava | SV | 72 |
| Teleorman | TR | 14 |
| Timiș | TM | 30 |
| Tulcea | TL | 82 |
| Vaslui | VS | 73 |
| Vâlcea | VL | 24 |
| Vrancea | VN | 62 |

That gives a cheap check. If someone picks Iași and types a code that starts with 40, one of the two is wrong: `postalCodeMatchesCounty("400114", "IS")` returns `false`. In Bucharest a chosen sector narrows it to one prefix, so `postalCodeMatchesCounty("061357", "B", "6")` is `true` and the same code with sector `"3"` is `false`.

Address Input shows a mismatch as an amber warning under the postal code once the field loses focus, and the form stays valid. We chose a warning on purpose: the check only knows prefixes, and a person who knows their own code should never be stuck at checkout.

#### How do I build a Romanian address form in React?

Split it into a county select, a locality search, street and number, an optional block row and a six-digit postal code, then validate on submit and again on the server. Address Input ships those parts. It is a Pro component, so sign in once with `npx wingo-ui@latest login` on a Pro account, then run `npx wingo-ui@latest add address-input`. The CLI adds what it builds on, including ro-locations, text-match, the select and the combobox. The component renders the county, the locality, street and number, a collapsed row for block, staircase, floor and apartment, the postal code and a details field for the intercom or a landmark. Its labels follow the locale (the `locale` prop, then the provider, then the page language): English, or Romanian for `ro`.

A checkout step that validates on submit and saves through the Server Action shown further down:

```tsx
// app/checkout/shipping-step.tsx
"use client";

import { useState } from "react";
import {
  AddressInput,
  EMPTY_RO_ADDRESS,
  validateRoAddress,
  type AddressErrors,
  type RoAddress,
} from "@/components/ui/address-input";
import { Button } from "@/components/ui/button";
import { saveShipping } from "./actions";

export function ShippingStep({ onDone }: { onDone: () => void }) {
  const [address, setAddress] = useState<RoAddress>(EMPTY_RO_ADDRESS);
  const [errors, setErrors] = useState<AddressErrors>();

  return (
    <form
      noValidate
      className="flex flex-col gap-4"
      onSubmit={async (event) => {
        event.preventDefault();
        // the submit already made AddressInput show every error
        if (!validateRoAddress(address).valid) return;
        const result = await saveShipping(address);
        if (result.ok) onDone();
        else setErrors(result.errors);
      }}
    >
      <AddressInput
        label="Delivery address"
        value={address}
        errors={errors}
        onValueChange={(next) => {
          setAddress(next);
          setErrors(undefined);
        }}
        showSummary
      />
      <Button type="submit">Continue to payment</Button>
    </form>
  );
}
```

`showSummary` prints `formatRoAddress` under the form, the way the courier will read it: `Str. Memorandumului 28, bl. A2, sc. 1, et. 3, ap. 12, 400114 Cluj-Napoca, jud. Cluj`.

The parts a hand-rolled form usually misses:

- **Phones.** The county and locality lists open as bottom sheets below 768px, the postal code takes six digits with the numeric keypad, and Enter moves to the next part.
- **Autofill.** The county uses `address-level1`, the locality `address-level2`, the street `address-line1` and the code `postal-code`, so a saved browser address fills the parts.
- **Paste.** "Str. Memorandumului nr. 28, bl. A2" pasted into the street fills the street, number and block.
- **County changes.** Picking București swaps the locality for a sector select. Changing the county clears the locality and a postal code from another county, and keeps the street and number.

> Live demo (Address Input): Clear the postal code, type six digits that start with 70, the prefix of Iași, and press Tab: the county is Cluj, so a warning appears while the readout still says valid. Then pick București as the county to get the sector select. Try it at [Address Input](https://wingo-ui.com/components/address-input) and install it with `npx wingo-ui@latest add address-input`.

#### How do I search localities without diacritics?

Fold both strings before you compare them: lowercase, decompose with NFD and drop the combining marks. `"Iași".includes("iasi")` is false, and folded, both sides read `iasi`. Ș and ț with a comma below only arrived in Unicode 3.0 in 1999, and older encodings had only the [cedilla forms ş and ţ](https://en.wikipedia.org/wiki/S-comma), which still turn up in imported data. Both decompose to a base letter plus a combining mark, so NFD folding treats Ștefănești, Ştefăneşti and stefanesti as one name.

[text-match](https://wingo-ui.com/components/text-match) does that folding, ranks matches (exact, prefix, word prefix, inside a word) and returns the ranges to highlight, in about 200 lines with no dependencies. [ro-locations](https://wingo-ui.com/components/ro-locations) builds its `searchLocations` on it, and Address Input's locality [combobox](https://wingo-ui.com/components/combobox) filters with it.

> Live demo (Romanian locations): Type iasi, manastur or sector 3 without diacritics: each finds its place, with the matched letters highlighted. Try it at [Romanian locations](https://wingo-ui.com/components/ro-locations) and install it with `npx wingo-ui@latest add ro-locations`.

Folding does not cover abbreviations or old spellings. People type "Tg. Mureș" for Târgu Mureș, and records from before the 1993 spelling rule write î inside words (Tîrgu). `filterByText` takes keywords next to the label, so aliases handle both:

```ts
// lib/locality-search.ts
import { filterByText } from "@/lib/text-match";

// county is the plate code ("CJ"), the code Address Input stores and passes to loadLocalities
export type Locality = { id: string; name: string; county: string; commune?: string };

// how people also write a name: "Tg. Mures", and "Tirgu" from before the 1993 spelling rule
function aliases(name: string) {
  return [name.replace(/^Târgu /, "Tg. "), name.replace(/(?<=\p{L})â(?=\p{L})/gu, "î")];
}

export function searchLocalities(list: readonly Locality[], county: string, query: string) {
  return filterByText(
    list.filter((locality) => locality.county === county),
    query,
    (locality) => [locality.name, ...aliases(locality.name)],
    { limit: 20 },
  );
}
```

Now "tg mures" and "tirgu mures" both find Târgu Mureș, ranked a little below a direct hit on the name.

#### How do I load every village from SIRUTA?

Serve the SIRUTA list from your own route and give Address Input a `loadLocalities` function that queries it. Without one, the component searches a built-in list of 332 cities, towns and large communes and accepts any other locality as typed, with a quiet note under the field. text-match has no `"use client"` directive, so the same search runs in a route handler:

```ts
// app/api/localities/route.ts
import type { NextRequest } from "next/server";
import { LOCALITIES } from "@/data/localities"; // built from the SIRUTA CSV
import { searchLocalities } from "@/lib/locality-search";

export function GET(request: NextRequest) {
  const params = request.nextUrl.searchParams;
  const results = searchLocalities(LOCALITIES, params.get("county") ?? "", params.get("q") ?? "");
  return Response.json(
    results.map(({ item }) => ({
      value: item.id,
      label: item.name,
      // tells apart villages with the same name
      description: item.commune && `com. ${item.commune}`,
    })),
  );
}
```

```tsx
<AddressInput
  label="Delivery address"
  loadLocalities={async (county, query, { signal }) => {
    const params = new URLSearchParams({ county, q: query });
    const response = await fetch(`/api/localities?${params}`, { signal });
    return response.ok ? response.json() : [];
  }}
/>
```

The `value` you return becomes `localityId`, so the SIRUTA code is saved with the address.

#### How do I validate the address on the server?

Check it again in the Server Action, with a zod 4 schema (`npm install zod`) in a file that has no `"use client"`. Copied component code has a trap here: `address-input.tsx` starts with `"use client"`, so on the server every export is a client reference. Calling `validateRoAddress` or `formatRoAddress` in a Server Component or a Server Action throws "Attempted to call formatRoAddress() from the server but formatRoAddress is on the client". Type imports are fine, and ro-locations has no directive, so the schema can use its county lookup:

```ts
// lib/ro-address-schema.ts
import { z } from "zod";
import { getCounty } from "@/lib/ro-locations";

const text = z.string().trim();

export const roAddressSchema = z
  .object({
    county: text.refine((code) => Boolean(getCounty(code)), { error: "Choose a county from the list" }),
    locality: text,
    localityId: text.optional(),
    sector: z.enum(["1", "2", "3", "4", "5", "6"]).optional(),
    street: text.min(1, { error: "Enter the street" }),
    number: text.min(1, { error: "Enter the number" }),
    building: text.optional(),
    entrance: text.optional(),
    floor: text.optional(),
    apartment: text.optional(),
    postalCode: z.union([z.literal(""), z.string().regex(/^\d{6}$/, { error: "A postal code has 6 digits" })]).optional(),
    details: text.optional(),
  })
  // bucharest has sectors where other counties have localities
  .refine((a) => a.county.toUpperCase() !== "B" || Boolean(a.sector), { error: "Choose a sector", path: ["sector"] })
  .refine((a) => a.county.toUpperCase() === "B" || a.locality.length > 0, {
    error: "Enter the city or village",
    path: ["locality"],
  });
```

```ts
// app/checkout/actions.ts
"use server";

import type { AddressErrors } from "@/components/ui/address-input";
import { roAddressSchema } from "@/lib/ro-address-schema";

export async function saveShipping(input: unknown): Promise<{ ok: true } | { ok: false; errors: AddressErrors }> {
  const parsed = roAddressSchema.safeParse(input);
  if (!parsed.success) {
    // the first message per field, the shape of AddressInput's errors prop
    const errors: AddressErrors = {};
    for (const issue of parsed.error.issues) errors[issue.path[0] as keyof AddressErrors] ??= issue.message;
    return { ok: false, errors };
  }
  // save parsed.data with the order
  return { ok: true };
}
```

Errors from the action land on the matching part through the `errors` prop and win over the component's own. To format an address on the server for an order email, move `formatRoAddress` and its helpers into a module without the directive. You own the source.

#### What should I build next?

Try the postal code check in the demo above, then add the form to your checkout with `npx wingo-ui@latest add address-input`. Address Input and ro-locations are part of [Wingo UI Pro](https://wingo-ui.com/pricing) ($8 a month, $80 a year or $150 once as of October 2026), and text-match is free. If the same checkout takes company details, [Romanian CUI validation](https://wingo-ui.com/blog/romanian-cui-validation-javascript) covers tax IDs and the [IBAN validation guide](https://wingo-ui.com/blog/iban-validation-javascript) covers bank accounts, while [React form components](https://wingo-ui.com/blog/react-form-components-guide) explains the label, hint and error anatomy every part of this form shares. More [step-by-step React builds](https://wingo-ui.com/blog/category/build) live in the Build it category.

#### Components in this post

- [Address Input](https://wingo-ui.com/components/address-input) (Pro): A Romanian address form: county, locality search, street, number, block and apartment, postal code checked against the county. Install: `npx wingo-ui@latest add address-input`
- [Romanian locations](https://wingo-ui.com/components/ro-locations) (Pro): Romania's counties, cities and neighbourhoods with coordinates, diacritic-free search, distances and within-radius lists. Install: `npx wingo-ui@latest add ro-locations`
- [Text match](https://wingo-ui.com/components/text-match) (Free): Search that ignores case and diacritics, ranks the best matches first and returns the ranges to highlight. Install: `npx wingo-ui@latest add text-match`

#### FAQ

##### How do you write an address in Romania?

Write the street type, name and number first (Str. Memorandumului 28), then the block, staircase, floor and apartment on the same line (bl. A2, sc. 1, et. 3, ap. 12). The next line holds the 6-digit postal code and the locality (400114 Cluj-Napoca), followed in domestic use by the county as jud. Cluj, and in Bucharest a Sector line goes above the postal code. Mail from abroad ends with ROMANIA on its own line.

##### How many digits does a Romanian postal code have?

Six. Six-digit codes replaced the four-digit ones on May 1, 2003. The first two digits identify the county, and in Bucharest they identify the sector, from 01 for Sector 1 to 06 for Sector 6.

##### What do bl., sc., et. and ap. mean in a Romanian address?

They abbreviate bloc (the apartment building), scară (the staircase, which has its own entrance), etaj (the floor) and apartament (the apartment). The ground floor is written parter.

##### How many counties does Romania have?

Romania has 41 counties (județe) plus the municipality of Bucharest, which is divided into six sectors. Their ISO 3166-2:RO codes, such as RO-CJ for Cluj and RO-B for Bucharest, use the same letters as Romanian license plates.

##### Should a Romanian address form require diacritics?

No. Accept what people type and match it without diacritics: the UPU's own sample addresses for Romania are written without them, and older data uses the cedilla forms ş and ţ. Store the official spelling from your locality list once the person picks a match.

##### Are Address Input and the Romanian locations data free?

Address Input and ro-locations are part of Wingo UI Pro. text-match, the diacritic-insensitive search both of them use, is free and installs with npx wingo-ui@latest add text-match.

---

Source: https://wingo-ui.com/blog/romanian-address-format-react-form

### Romanian CNP Validator in TypeScript, Zod and React

> Build a Romanian CNP validator in TypeScript: the weighted check digit, real birth dates, the new county code 70, a zod rule, a React field and safe storage.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 13 min
- Canonical: https://wingo-ui.com/blog/romanian-cnp-validator-javascript

#### TL;DR

A Romanian CNP validator checks five things: 13 digits, a first digit from 1 to 9, a birth date that exists and is not in the future, a county code (01 to 48, 51, 52, or 70, which the new civil status system has used since May 2024) and the check digit. The check digit is the sum of the first 12 digits multiplied by the matching digits of 279146358279, mod 11, with a remainder of 10 written as 1. Store a valid CNP encrypted, with a keyed hash for lookups, because a plain SHA-256 of one can be brute forced in about half an hour on one CPU core.

Your checkout, payroll or rental contract form asks for a Romanian personal numeric code (CNP), and a 13-digit regex accepts every typo. A Romanian CNP validator has to check more than the length: a digit for sex and century, a birth date that exists, a county code and a weighted check digit. This tutorial writes that check in TypeScript, decodes the parts, turns it into a zod rule and a React field that validates as you type, and ends with what to do before you store a single CNP. The field is [Masked Input](https://wingo-ui.com/components/masked-input) from Wingo UI, the library we build, so we are not neutral. The validator is plain TypeScript you can paste anywhere.

#### What is the cod numeric personal format?

Thirteen digits in seven parts, written S AA LL ZZ JJ NNN C. The [Romanian Wikipedia article on the CNP](https://ro.wikipedia.org/wiki/Cod_numeric_personal_(Rom%C3%A2nia)) documents each one. Here they are on `1960523123457`, the sample code from the demo further down:

| Digits | Part | Meaning | In the sample |
|---|---|---|---|
| 1 | S | Sex and century of birth | 1: male, born 1900 to 1999 |
| 2 to 3 | AA | Year of birth | 96 |
| 4 to 5 | LL | Month of birth | 05 |
| 6 to 7 | ZZ | Day of birth | 23 |
| 8 to 9 | JJ | County code | 12: Cluj |
| 10 to 12 | NNN | Serial number, 001 to 999 | 345 |
| 13 | C | Check digit | 7 |

From 1 to 8, the first digit is odd for men and even for women. 1 and 2 mean born in the 1900s, 3 and 4 in the 1800s, 5 and 6 in the 2000s. 7 and 8 are foreign residents, and for them the century is not encoded. English Wikipedia also lists 9 for foreign citizens; the Romanian article stops at 8, so treat 9 as rare and accept it.

The county codes are 01 to 39 for the counties in alphabetical order (Alba to Vrancea), 40 for Bucharest, 41 to 46 for its six sectors, 47 and 48 for the former sectors 7 and 8, which only appear on old codes, and 51 and 52 for Călărași and Giurgiu. There is no 49 or 50.

And since May 2024 there is 70. Codes generated by Romania's new civil status IT system carry 70 in place of the county for every registration, wherever the person was born. The [Ministry of Internal Affairs said in May 2024](https://www.bugetul.ro/mai-schimba-procesul-prin-care-sunt-generate-cnp-urile-ce-se-intampla-cu-codurile-deja-existente/) that this started with births registered from May 8 in Ilfov county and seven cities, plus the birth records of people who had just become citizens, and that existing codes do not change. The Romanian Wikipedia article now lists 70 as well. Two consequences for your code: a range check of 01 to 52 rejects every code the new system issues, and you can no longer read a county from a new code.

#### How does the CNP checksum algorithm work?

The CNP check digit is a weighted sum mod 11. Multiply each of the first 12 digits by the digit in the same position of the key `279146358279`, add the products and divide by 11. The remainder is the check digit, except that a remainder of 10 becomes 1. Here is the sample worked by hand:

| Position | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Digit | 1 | 9 | 6 | 0 | 5 | 2 | 3 | 1 | 2 | 3 | 4 | 5 |
| Key | 2 | 7 | 9 | 1 | 4 | 6 | 3 | 5 | 8 | 2 | 7 | 9 |
| Product | 2 | 63 | 54 | 0 | 20 | 12 | 9 | 5 | 16 | 6 | 28 | 45 |

The products add up to 260, and 260 mod 11 is 7, the last digit of `1960523123457`.

The fold of 10 into 1 is where the check gets weaker. Remainders 1 and 10 both produce a 1, so about 2 codes in 11 end in 1, and a typo that moves the sum from one to the other passes. `1960523120031` is valid; change its twelfth digit and `1960523120021` passes too.

We measured it with the `checkCnp` function below. Over 20,000 random valid codes, we tried every single-digit change and every swap of two neighboring digits. The checksum alone missed 1.7% of the changes, every one of them through the fold, and 1.9% of the swaps. Checking the date and the county as well brought both down to about 1.2%. Of a million random 13-digit strings, 10% passed the checksum and 0.14% passed every check. So about 1 typo in 80 passes every check, which is why the form below also reads the code back to the person.

#### How do I validate a CNP in JavaScript or TypeScript?

Run the checks in order and say which one failed, so the form can explain the problem instead of printing "invalid". Return the decoded parts from the same pass, so nothing parses the code twice. The code is TypeScript with no dependency; drop the types and it runs as plain JavaScript:

```ts
// lib/cnp.ts
export type CnpProblem = "format" | "sex" | "date" | "county" | "checksum";

export type CnpInfo = {
  cnp: string;
  sex: "male" | "female" | null;
  // "1996-05-23"; null for 7 to 9, whose century is not encoded
  birthDate: string | null;
  // "12"; "70" for codes issued by the civil status system since May 2024
  county: string;
  countyName: string | null;
  serial: string;
};

export type CnpCheck = { problem: CnpProblem; info: null } | { problem: null; info: CnpInfo };

const WEIGHTS = [2, 7, 9, 1, 4, 6, 3, 5, 8, 2, 7, 9];

// 01 to 39 in alphabetical order, then Bucharest and its sectors (7 and 8 no longer exist)
const COUNTIES: Record<string, string> = Object.fromEntries(
  [
    "Alba", "Arad", "Argeș", "Bacău", "Bihor", "Bistrița-Năsăud", "Botoșani", "Brașov", "Brăila", "Buzău",
    "Caraș-Severin", "Cluj", "Constanța", "Covasna", "Dâmbovița", "Dolj", "Galați", "Gorj", "Harghita", "Hunedoara",
    "Ialomița", "Iași", "Ilfov", "Maramureș", "Mehedinți", "Mureș", "Neamț", "Olt", "Prahova", "Satu Mare",
    "Sălaj", "Sibiu", "Suceava", "Teleorman", "Timiș", "Tulcea", "Vaslui", "Vâlcea", "Vrancea", "București",
    "București, Sector 1", "București, Sector 2", "București, Sector 3", "București, Sector 4",
    "București, Sector 5", "București, Sector 6", "București, Sector 7", "București, Sector 8",
  ].map((name, i) => [String(i + 1).padStart(2, "0"), name]),
);
COUNTIES["51"] = "Călărași";
COUNTIES["52"] = "Giurgiu";

const CENTURY: Record<string, number> = { "1": 1900, "2": 1900, "3": 1800, "4": 1800, "5": 2000, "6": 2000 };

export function cnpCheckDigit(first12: string): number {
  let sum = 0;
  for (let i = 0; i < 12; i++) sum += Number(first12[i]) * WEIGHTS[i];
  // a remainder of 10 does not fit in one digit, so it becomes 1
  return sum % 11 === 10 ? 1 : sum % 11;
}

// "1996-05-23", or null when that day does not exist
function isoDate(year: number, month: number, day: number): string | null {
  const date = new Date(Date.UTC(year, month - 1, day));
  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
  return date.toISOString().slice(0, 10);
}

// the calendar day in Romania, where the codes are issued
export const todayInRomania = () => new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Bucharest" }).format(new Date());

export function checkCnp(input: string, today = todayInRomania()): CnpCheck {
  const cnp = input.replace(/[\s.-]/g, "");
  const fail = (problem: CnpProblem): CnpCheck => ({ problem, info: null });
  if (!/^\d{13}$/.test(cnp)) return fail("format");

  const s = cnp[0];
  if (s === "0") return fail("sex");

  const [yy, mm, dd] = [cnp.slice(1, 3), cnp.slice(3, 5), cnp.slice(5, 7)].map(Number);
  let birthDate: string | null = null;
  if (CENTURY[s]) {
    birthDate = isoDate(CENTURY[s] + yy, mm, dd);
    if (!birthDate || birthDate > today) return fail("date");
  } else {
    // 7 to 9: the day has to exist in one of the two centuries it could be from
    const candidates = [2000 + yy, 1900 + yy].map((year) => isoDate(year, mm, dd));
    if (!candidates.some((date) => date && date <= today)) return fail("date");
  }

  const county = cnp.slice(7, 9);
  if (county !== "70" && !COUNTIES[county]) return fail("county");

  if (cnpCheckDigit(cnp) !== Number(cnp[12])) return fail("checksum");

  return {
    problem: null,
    info: {
      cnp,
      sex: s === "9" ? null : Number(s) % 2 === 1 ? "male" : "female",
      birthDate,
      county,
      countyName: COUNTIES[county] ?? null,
      serial: cnp.slice(9, 12),
    },
  };
}

export const isValidCnp = (input: string) => checkCnp(input).problem === null;
```

```ts
checkCnp("1960 523 123 457");
// { problem: null, info: { cnp: "1960523123457", sex: "male", birthDate: "1996-05-23", county: "12", countyName: "Cluj", serial: "345" } }
checkCnp("1960523123458"); // { problem: "checksum", info: null }
checkCnp("1000229123456"); // { problem: "date", info: null }, 1900 was not a leap year
checkCnp("1960523491239"); // { problem: "county", info: null }, there is no county 49
isValidCnp("5240601701230"); // true, county 70
```

Four details that CNP validation in JavaScript often gets wrong:

- **The century comes from the first digit.** `new Date(24, 5, 1)` is June 1, 1924, because JavaScript maps two-digit years to the 1900s. Build the full year first, and check that the day survived the round trip, or February 29, 1900 slips through.
- **A birth date cannot be in the future.** `5300101123456` decodes to January 1, 2030. Compare against today in Romania, not in UTC or in the server's zone.
- **The county list has gaps and a new member.** 49 and 50 do not exist, and 70 does.
- **Codes starting with 7 to 9 have no century.** We accept the day if it exists in either century and return `birthDate: null` instead of guessing, because a wrong guess turns an 11-year-old resident into a 111-year-old.

#### How do I read the birth date, age and county from a CNP?

Take them from `info`, and turn them into a sentence the person can compare with their ID card. Reading a valid code back catches the mistake no checksum can: someone typing a valid code that belongs to their spouse.

```ts
// lib/cnp.ts (continued)
// "Male, born May 23, 1996, Cluj"
export function describeCnp(info: CnpInfo, locale = "en-US"): string {
  const sex = info.sex === "male" ? "Male" : info.sex === "female" ? "Female" : "Foreign national";
  const born = info.birthDate
    ? `born ${new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone: "UTC" }).format(new Date(info.birthDate))}`
    : "resident";
  return [sex, born, info.countyName].filter(Boolean).join(", ");
}

// full years on a given day: ageOn("2008-10-10", "2026-10-09") is 17
export function ageOn(birthDate: string, today = todayInRomania()): number {
  const [by, bm, bd] = birthDate.split("-").map(Number);
  const [ty, tm, td] = today.split("-").map(Number);
  return ty - by - (tm < bm || (tm === bm && td < bd) ? 1 : 0);
}
```

A code with county 70 reads "Male, born June 1, 2024", without a county, which is the truth.

#### How do I write a zod rule for a CNP?

Wrap `checkCnp` in a check that maps each problem to its own message, then strip the separators so the database gets the 13 digits. The schema uses zod 4 (`.check()` and the `error` param):

```ts
// lib/cnp-schema.ts
import { z } from "zod";
import { ageOn, checkCnp, type CnpProblem } from "@/lib/cnp";

const MESSAGES: Record<CnpProblem, string> = {
  format: "A CNP has 13 digits",
  sex: "A CNP starts with a digit from 1 to 9",
  date: "Digits 2 to 7 are not a real birth date",
  county: "Digits 8 and 9 are not a county code",
  checksum: "The last digit does not match. Check for a typo",
};

export const cnp = z
  .string()
  .trim()
  .min(1, { error: "Enter your CNP", abort: true })
  .check((ctx) => {
    const { problem } = checkCnp(ctx.value);
    if (problem) ctx.issues.push({ code: "custom", message: MESSAGES[problem], input: ctx.value });
  })
  .transform((value) => value.replace(/[\s.-]/g, ""));

// for contracts that need an adult; 7 to 9 have no birth date, so ask for one separately
export const adultCnp = cnp.refine(
  (value) => {
    const { info } = checkCnp(value);
    return !info?.birthDate || ageOn(info.birthDate) >= 18;
  },
  { error: "You need to be 18 or older" },
);
```

"Digits 2 to 7 are not a real birth date" tells the person where to look, which "Invalid CNP" never does. If you use the [form-validation lib](https://wingo-ui.com/components/form-validation) from Wingo UI Pro, it has rules for CUI and IBAN but none for CNP, so this rule sits next to them: with `const v = createValidators()`, write `z.object({ email: v.email(), iban: v.iban(), cnp })`.

#### How do I build a CNP field that checks as you type?

Use a masked field with a numeric keypad, and show the verdict the moment the 13th digit lands. The `cnp` preset of Masked Input sets `inputMode="numeric"` and `autoComplete="off"`, keeps the value to 13 digits, drops spaces, dots and dashes from a paste, and pops in a check or an alert icon once the code is complete. The red ring and `aria-invalid` wait until the person leaves the field. The preset's own check accepts any county from 01 to 52, so it lets 49 and 50 through and rejects 70. Pass `validate={isValidCnp}` and the field agrees with the zod rule on every code.

> Live demo (Masked Input): Type 1960523123457: a check appears once the 13th digit is in. Change the last digit and it turns into an alert; press Save to see the error message. Try it at [Masked Input](https://wingo-ui.com/components/masked-input) and install it with `npx wingo-ui@latest add masked-input`.

Wire it with React Hook Form's `Controller` (`npm install react-hook-form @hookform/resolvers zod`). Use `Controller`, not `register`: the input element holds the masked text, and the raw digits come through `onValueChange`:

```tsx
"use client";

import { Controller, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { MaskedInput } from "@/components/ui/masked-input";
import { checkCnp, describeCnp, isValidCnp } from "@/lib/cnp";
import { cnp } from "@/lib/cnp-schema";

const schema = z.object({ cnp });
type Values = z.output<typeof schema>;

export function IdentityStep({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { cnp: "" },
  });

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Controller
        control={form.control}
        name="cnp"
        render={({ field, fieldState }) => {
          const { info } = checkCnp(field.value);
          return (
            <MaskedInput
              preset="cnp"
              // the same check as the zod rule, so the icon and the error never disagree
              validate={isValidCnp}
              label="CNP (personal numeric code)"
              placeholder="13 digits"
              showMask="focus"
              placeholderChar="·"
              ref={field.ref}
              value={field.value}
              onValueChange={(raw) => field.onChange(raw)}
              onBlur={field.onBlur}
              // read back, so a valid code that is not theirs stands out
              description={info ? describeCnp(info) : "The 13 digits on your ID card."}
              error={fieldState.error?.message}
              enterKeyHint="done"
            />
          );
        }}
      />
      <Button type="submit" loading={form.formState.isSubmitting}>
        Continue
      </Button>
    </form>
  );
}
```

The field uses 16px text on phones, so iOS does not zoom into it, and grows to 44px on touch screens. Its `error` replaces the description, sets `aria-invalid` and links the message with `aria-describedby`. For `onSave`, pass a Server Action that stores the code with the vault in the next section; the CNP then travels in a POST body, never in a URL.

#### Should I collect and store CNPs at all?

Only when a law or a contract needs one. A CNP gives away a birth date and a sex, and on codes issued before 2024 a county, so a leak of it is worse than a leak of an email address. If you only need an age, ask for the birth date. If you send B2C invoices through e-Factura, you do not need it either: since OUG 138/2024 a business may use `0000000000000` when a private buyer gives no tax code, and it is [not required to collect CNPs](https://contabilul.manager.ro/a/29150/e-factura-b2c-noutati-in-2025-sanctiuni-si-studii-de-caz.html). Accept those 13 zeros before you call `checkCnp` if the field feeds an invoice.

> Live demo (Invoicing): The check under the invoice reads 0000000000000 as a buyer who gave no CNP, the placeholder e-Factura accepts on B2C invoices. Try it at [Invoicing](https://wingo-ui.com/components/invoicing) and install it with `npx wingo-ui@latest add invoicing`.

When you do collect it, [Romanian Law 190/2018](https://legislatie.just.ro/Public/DetaliiDocument/203151) applies on top of GDPR. Its article 2 lists the CNP as a national identification number, and article 4 sets the rules for processing one. Processing it needs a GDPR legal basis, and when that basis is legitimate interest the law requires four safeguards: technical and organizational measures for data minimization and security, a data protection officer, storage periods with deadlines for deletion, and regular training for the people who handle it. This is not legal advice; your DPO decides what applies to you.

What engineering can do is keep the code out of every place it does not need to be. Start with the storage, because a hash is not anonymization. The space of valid codes is small. Everyone born in the 1900s fits in about 3.6 billion candidates: 36,524 days, 2 sex digits, 50 county codes and 999 serials, with the check digit computed. On one core of our dev server, Node's `createHash` hashed about 2 million codes a second, so walking the whole century takes about half an hour. Knowing the birth date leaves 99,900 candidates, about 50 milliseconds of hashing.

So store two things: the code encrypted, and a keyed hash for lookups and unique indexes. The key never lives in the database:

```ts
// lib/cnp-vault.ts
import "server-only";
import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";

// two 32 byte keys, base64, from your secret manager: openssl rand -base64 32
// read on use, not at import, so next build works on a machine without the secrets
function key(name: "CNP_ENCRYPTION_KEY" | "CNP_LOOKUP_KEY"): Buffer {
  const value = Buffer.from(process.env[name] ?? "", "base64");
  if (value.length !== 32) throw new Error(`${name} must be 32 bytes, base64`);
  return value;
}

// same CNP, same value: for unique indexes and "is this person already a customer"
export function cnpLookupHash(cnp: string): string {
  return createHmac("sha256", key("CNP_LOOKUP_KEY")).update(cnp).digest("base64url");
}

// iv + auth tag + ciphertext in one string; a new iv every time, so equal CNPs never look equal
export function encryptCnp(cnp: string): string {
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", key("CNP_ENCRYPTION_KEY"), iv);
  const data = Buffer.concat([cipher.update(cnp, "utf8"), cipher.final()]);
  return Buffer.concat([iv, cipher.getAuthTag(), data]).toString("base64");
}

export function decryptCnp(stored: string): string {
  const raw = Buffer.from(stored, "base64");
  const decipher = createDecipheriv("aes-256-gcm", key("CNP_ENCRYPTION_KEY"), raw.subarray(0, 12));
  decipher.setAuthTag(raw.subarray(12, 28));
  return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString("utf8");
}

// what support screens and receipts show: "•••••••••3457"
export const maskCnp = (cnp: string) => "•".repeat(9) + cnp.slice(-4);
```

The masked form keeps the serial and the check digit and hides the sex, the birth date and the county. The rest is a checklist:

- **Never in a URL.** Send the code in a POST body. Query strings end up in access logs, browser history and analytics.
- **Never in logs or error reports.** Redact `cnp` in your logger and in your error tracker's event filter, and check that session replay masks the input.
- **Never back to the browser.** After the save, the client gets `maskCnp`, and only a server route that needs the full code calls `decryptCnp`.
- **A deletion date.** Decide when each stored code is deleted, and run the job that deletes it.

#### Should I use a CNP validator package instead?

Only after you read its county table. Code 70 is recent, and a package that misses it rejects real codes. As of October 2026, the most downloaded CNP package on npm, [romanian-personal-identity-code-validator](https://www.npmjs.com/package/romanian-personal-identity-code-validator), is at 1.1.4 (published May 19, 2024, MIT, 667 downloads from October 1 to 7, 2026). It decodes the birth date, sex, birthplace and age, depends on Moment.js, and its county table has no 70, so it rejects every code the new system issues. It does list 80, as a code obtained abroad. [python-stdnum's ro.cnp module](https://github.com/arthurdejong/python-stdnum/blob/master/stdnum/ro/cnp.py) accepts 70, and also 80 to 83, labeled "Unknown". We found no official source for 80 to 83, so the code above leaves them out. If a real customer's code fails on one of them, add it.

`lib/cnp.ts` is about 100 lines with no dependency, and you can read every rule in it. When the format changes again, you edit one table instead of waiting for a maintainer.

#### Should I copy this code or install it?

Copy it when you need one field: `lib/cnp.ts`, the zod rule and the free [Input](https://wingo-ui.com/components/input) with `inputMode="numeric"` cover a contract or payroll form. Masked Input, the field from the demo, is part of [Wingo UI Pro](https://wingo-ui.com/pricing), and so is the [invoicing lib](https://wingo-ui.com/components/invoicing), whose `parseCnp` and `isValidCnp` decode the sex, birth date and county, accept 70 and treat `0000000000000` as a buyer without a CNP. They skip the future-date check, so keep `checkCnp` for the form. Install the field with `npx wingo-ui@latest add masked-input`.

The other Romanian ids have their own guides: [Romanian CUI validation](https://wingo-ui.com/blog/romanian-cui-validation-javascript) for companies and [IBAN validation in JavaScript](https://wingo-ui.com/blog/iban-validation-javascript) for bank accounts. For the rest of the form anatomy, read [React form components: accessible fields, zod and mobile](https://wingo-ui.com/blog/react-form-components-guide), or browse more [component guides](https://wingo-ui.com/blog/category/components).

#### Components in this post

- [Masked Input](https://wingo-ui.com/components/masked-input) (Pro): A text field that formats itself as you type or paste: card number, expiry, CVC, IBAN, CNP, postal code or a custom mask. Install: `npx wingo-ui@latest add masked-input`
- [Invoicing](https://wingo-ui.com/components/invoicing) (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: `npx wingo-ui@latest add invoicing`
- [Form validation](https://wingo-ui.com/components/form-validation) (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: `npx wingo-ui@latest add form-validation`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`

#### FAQ

##### How do I validate a Romanian CNP?

Check that it has 13 digits, that the first digit is 1 to 9, that digits 2 to 7 form a real birth date that is not in the future, and that digits 8 and 9 are a county code (01 to 48, 51, 52 or 70). Then multiply the first 12 digits by 2, 7, 9, 1, 4, 6, 3, 5, 8, 2, 7, 9, add the products and take the sum mod 11, turning 10 into 1; the result must equal the last digit.

##### What does county code 70 mean in a CNP?

Since May 2024, the codes generated by Romania's new civil status IT system carry 70 in place of the county, whatever the place of birth. Codes issued before keep their county, so a validator that only accepts 01 to 52 rejects every code the new system issues.

##### Why does the CNP check digit use 1 when the remainder is 10?

The check digit has room for one digit, so a remainder of 10 is written as 1. The cost is that remainders 1 and 10 look the same, so a typo that moves the sum between them still passes; in our test that was 1.7% of single-digit typos.

##### Can I get someone's age from their CNP?

For codes starting with 1 to 6, yes: the first digit gives the century and digits 2 to 7 the year, month and day. Codes for foreign residents and foreign citizens start with 7, 8 or 9 and do not encode the century, so ask for the birth date when the age matters.

##### Is it legal to store a CNP in my database?

Romanian Law 190/2018 lists the CNP as a national identification number: you need a GDPR legal basis, and if that basis is legitimate interest you also need data minimization and security measures, a data protection officer, retention periods and staff training. Collect it only when a law or a contract needs it, and ask your DPO before you do.

##### Do I need the customer's CNP for an e-Factura B2C invoice?

No. Since OUG 138/2024, a business may use 0000000000000, thirteen zeros, when a private buyer gives no tax identification code, and it is not required to collect the CNP.

---

Source: https://wingo-ui.com/blog/romanian-cnp-validator-javascript

### Romanian CUI Validation in TypeScript, Zod and React

> Romanian CUI validation in TypeScript: the 753217532 check digit step by step, the RO prefix, a zod rule, a React field and a company lookup at ANAF.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/romanian-cui-validation-javascript

#### TL;DR

Romanian CUI validation is a weighted checksum: strip the optional RO prefix, right-align the digits before the last one against the key 753217532, multiply and add, then take the sum times 10 mod 11, where 10 becomes 0. The result must equal the last digit. A valid check digit only proves the number is well formed, so confirm that the company exists, is still registered and pays VAT with ANAF's public web service.

Your sign-up or invoice form has a field for a Romanian company's tax ID, and a regex for "RO plus digits" accepts every mistyped digit. Romanian CUI validation needs three things: a parser that accepts the many ways people write the number, the weighted check digit, and, when it matters, a lookup that proves the company is real. This tutorial builds all three in TypeScript, then wires them into a zod rule, a React field that validates as you type and a sign-up step that looks the company up at ANAF. The UI uses [Input](https://wingo-ui.com/components/input) and [Field](https://wingo-ui.com/components/field) from Wingo UI, the library we build, so we are not neutral. The checksum code is plain TypeScript you can paste anywhere.

#### What is a CUI, and how does it relate to the CIF and the VAT number?

They are one number with three names. The CUI (Codul Unic de Înregistrare) is the code a Romanian company gets when it registers: 2 to 10 digits, the last of which is a check digit. The CIF (cod de identificare fiscală) is the tax ID, and for a company it is the same digits. When the company is registered for VAT, the [Romanian Wikipedia article on the CIF](https://ro.wikipedia.org/wiki/Cod_de_identificare_fiscal%C4%83) describes the CUI becoming a CIF with the "RO" prefix.

So the Romanian VAT number format is RO followed by the same 2 to 10 digits, as the [VAT identification number table on Wikipedia](https://en.wikipedia.org/wiki/VAT_identification_number) lists it. In a real form you will receive `RO12345674`, `ro 12345674`, `12 345 674` and `RO-12345674`, and all four are the same company.

Two rules follow from that:

- **Store the digits and a VAT flag**, never the string as typed. Print `RO` + digits when you need the VAT number.
- **The prefix someone typed is not proof of VAT status.** People add RO out of habit. The VAT flag should come from ANAF, as we do further down.

#### How does the CUI check digit work?

The last digit is computed from the others with a fixed key, 753217532. The Romanian Wikipedia article above describes the validare CUI algorithm, and the [source of python-stdnum's stdnum.ro.cui](https://github.com/arthurdejong/python-stdnum/blob/master/stdnum/ro/cui.py) implements the same five steps:

1. Remove the RO prefix and any spaces, dots or dashes. What is left must be 2 to 10 digits.
2. Set the last digit aside. That is the check digit.
3. Pad the remaining digits with zeros on the left until there are nine, so they line up with the right end of the key. (Wikipedia reverses both strings instead, which gives the same pairs.)
4. Multiply each digit by the key digit in the same position and add the products.
5. Multiply the sum by 10, take the remainder of dividing by 11, and turn a remainder of 10 into 0. The CUI is valid when this equals the check digit.

Here is `12345674` worked by hand. The body is `1234567`, padded to `001234567`:

| Position | Digit | Key | Product |
|---|---|---|---|
| 1 | 0 | 7 | 0 |
| 2 | 0 | 5 | 0 |
| 3 | 1 | 3 | 3 |
| 4 | 2 | 2 | 4 |
| 5 | 3 | 1 | 3 |
| 6 | 4 | 7 | 28 |
| 7 | 5 | 5 | 25 |
| 8 | 6 | 3 | 18 |
| 9 | 7 | 2 | 14 |

The sum is 95. 950 mod 11 is 4, which matches the last digit, so `RO12345674` is valid and `RO12345678` is not.

The case that breaks hand-written validators is the remainder of 10. For `18547290` the products add up to 111, and 1110 mod 11 is 10, so the check digit is 0. A validator that skips the fold rejects every company whose check digit lands there.

#### How do I validate a CUI in TypeScript?

Parse first, then validate. A parser that returns the digits, the prefix and the verdict gives the form, the zod rule and the lookup the same source of truth:

```ts
// lib/cui.ts
export type CuiInfo = {
  // the digits without RO: "12345674"
  digits: string;
  // written with RO, the way a VAT payer quotes it
  vatPayer: boolean;
  valid: boolean;
};

// the test key 753217532, one weight per digit before the check digit
const KEY = [7, 5, 3, 2, 1, 7, 5, 3, 2];

export function parseCui(input: string): CuiInfo | null {
  const clean = input.replace(/[\s.\-/]/g, "").toUpperCase();
  const match = /^(RO)?(\d{2,10})$/.exec(clean);
  if (!match) return null;

  const digits = match[2];
  // right-align the body against the key: "1234567" -> "001234567"
  const body = digits.slice(0, -1).padStart(9, "0");
  let sum = 0;
  for (let i = 0; i < 9; i++) sum += Number(body[i]) * KEY[i];
  // times 10, mod 11, and a remainder of 10 becomes 0
  const control = ((sum * 10) % 11) % 10;

  return {
    digits,
    vatPayer: match[1] === "RO",
    valid: control === Number(digits[digits.length - 1]),
  };
}

export function isValidCui(input: string): boolean {
  return parseCui(input)?.valid ?? false;
}

// "ro 1234 5674" -> "RO12345674"; vatPayer adds or drops the prefix
export function formatCui(input: string, options: { vatPayer?: boolean } = {}): string {
  const info = parseCui(input);
  if (!info) return input;
  return `${(options.vatPayer ?? info.vatPayer) ? "RO" : ""}${info.digits}`;
}
```

```ts
parseCui("RO12345674"); // { digits: "12345674", vatPayer: true, valid: true }
isValidCui("12345678"); // false, the check digit should be 4
isValidCui("RO 185 472 90"); // true, remainder 10 becomes 0
formatCui("ro 1234 5674"); // "RO12345674"
formatCui("RO12345674", { vatPayer: false }); // "12345674"
```

Check four things before you trust a CIF checksum JavaScript snippet from a forum:

- It uppercases before it strips `RO`, or `ro12345674` fails.
- It turns a remainder of 10 into 0.
- It lines the digits up from the right. Left alignment only works for 10 digit codes.
- It rejects 11 digits.

python-stdnum also rejects a code that starts with 0. `parseCui` accepts one, so write the digit group as `([1-9]\d{1,9})` if you want the same rule.

We ran every single-digit change and every swap of two neighboring digits over a large sample of valid 8-digit codes: the check caught about 98% of both, and every missed single-digit typo came from folding 10 into 0. A random 8-digit number passes one time in ten, so a valid check digit never means the company exists.

#### How do I write a zod rule for a CUI?

Chain three checks and a transform, so the person sees one message at a time and your database always receives the same shape:

```ts
// lib/cui-schema.ts
import { z } from "zod";
import { formatCui, isValidCui, parseCui } from "@/lib/cui";

export const cui = z
  .string()
  .trim()
  .min(1, { error: "Enter the company's tax ID", abort: true })
  .refine((value) => parseCui(value) !== null, {
    error: "Use 2 to 10 digits, with or without RO",
    abort: true,
  })
  .refine(isValidCui, { error: "This tax ID fails its check digit" })
  .transform((value) => formatCui(value));

// for a form where the tax ID is optional
export const optionalCui = z.union([z.literal(""), cui]);
```

`abort: true` (zod 4) stops at the first failing check, so "abc" says what format is expected instead of also blaming the check digit. The transform turns `" ro 1234 5674 "` into `RO12345674` on submit, so you never have to rewrite the text while someone is typing.

In Wingo UI Pro, the [form-validation](https://wingo-ui.com/components/form-validation) lib ships a CUI rule as `createValidators().cui()`, with one message for any invalid code in English, or in Romanian with `VALIDATION_MESSAGES_RO`. It does not transform, so normalize with `formatCui` from the [invoicing](https://wingo-ui.com/components/invoicing) lib before saving; that lib exports the same three functions as the code above, plus IBAN and CNP checks.

#### How do I build a CUI field that validates as you type?

Show the error after the person leaves the field, then re-check on every keystroke so it clears the moment the number is right. Show the check mark as soon as the number is valid, since it interrupts no one. React Hook Form's `onTouched` mode gives the error that timing, and `useWatch` drives the check mark:

```tsx
"use client";

import { useForm, useWatch } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { CircleCheck } from "lucide-react";
import { z } from "zod";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { isValidCui } from "@/lib/cui";
import { cui } from "@/lib/cui-schema";

const schema = z.object({
  company: z.string().trim().min(1, { error: "Enter the company name" }),
  cui,
});

type Values = z.output<typeof schema>;

export function BillingForm({ onSave }: { onSave: (values: Values) => Promise<void> }) {
  const form = useForm<z.input<typeof schema>, unknown, Values>({
    resolver: zodResolver(schema),
    // the first error waits for blur, then the field re-checks on every keystroke
    mode: "onTouched",
    defaultValues: { company: "", cui: "" },
  });
  const typed = useWatch({ control: form.control, name: "cui" });
  const { errors, isSubmitting } = form.formState;

  return (
    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-col gap-4">
      <Input
        label="Company name"
        autoComplete="organization"
        {...form.register("company")}
        error={errors.company?.message}
      />
      <Input
        label="Tax ID (CUI)"
        description="With or without RO, for example RO12345674."
        placeholder="RO12345674"
        autoComplete="off"
        autoCapitalize="characters"
        spellCheck={false}
        {...form.register("cui")}
        error={errors.cui?.message}
        rightIcon={isValidCui(typed) ? <CircleCheck className="text-success-soft-foreground" /> : undefined}
      />
      <Button type="submit" loading={isSubmitting}>
        Save
      </Button>
    </form>
  );
}
```

The field keeps the text keyboard, because a numeric keypad has no R and no O. `autoCapitalize="characters"` turns "ro" into "RO" on phones, and spell check stays off so the browser does not underline a number. The Input uses 16px text on phones, so iOS does not zoom, and its `error` replaces the hint, sets `aria-invalid` and links the message with `aria-describedby`, the anatomy that [Field](https://wingo-ui.com/components/field) gives every control. Both are free: `npx wingo-ui@latest add input field`.

> Live demo (Form validation): Type RO12345678 in Company tax ID and press Tab: the check digit error appears. Change the last digit to 4 and it clears while you type. Try it at [Form validation](https://wingo-ui.com/components/form-validation) and install it with `npx wingo-ui@latest add form-validation`.

#### How do I check that the company exists and pays VAT?

Ask ANAF. Its public PlatitorTvaRest web service answers, for a list of CUIs and a date, whether each company is found, its name and address, and whether it was registered for VAT on that date. As of October 2026, the [v9 documentation](https://static.anaf.ro/static/10/Anaf/Informatii_R/Servicii_web/doc_WS_V9.txt) gives these rules: a POST to `https://webservicesp.anaf.ro/api/PlatitorTvaRest/v9/tva` with a JSON array of `{ "cui": number, "data": "YYYY-MM-DD" }`, at most 100 CUIs per request and at most one request per second per client. The answer has a `found` list and a `notFound` list.

We called it on October 8, 2026, and two results surprised us. A number with a wrong check digit lands in `notFound` without an error, so validating first saves a request against that limit. And our own demo number, `RO12345674`, came back found: a company struck off the register in 2006, with `stare_inregistrare` set to "RADIERE din data 29.06.2006", `scpTVA` false and the inactive flag `statusInactivi` also false. `18547290`, the example from python-stdnum, came back the same way, struck off in 2016. Found does not mean active, and in both records the inactive flag stayed false, so read `stare_inregistrare`. An active company reads "INREGISTRAT din data" followed by a date.

Keep the call on your server. The field names are Romanian and the version sits in the path (the [v5 documentation](https://static.anaf.ro/static/10/Anaf/Informatii_R/doc_WS_V5.txt) used `/PlatitorTvaRest/api/v5/ws/tva`), so one route handler is the only file that changes when ANAF moves. It reads the CUI from the query string, which arrives decoded, and turns a timeout or an error page into one 502:

```ts
// app/api/company/route.ts
import type { NextRequest } from "next/server";
import { parseCui } from "@/lib/cui";

const ANAF = "https://webservicesp.anaf.ro/api/PlatitorTvaRest/v9/tva";

type AnafCompany = {
  date_generale: { denumire: string; adresa: string; stare_inregistrare: string };
  inregistrare_scop_Tva: { scpTVA: boolean };
  stare_inactiv: { statusInactivi: boolean };
};

export async function GET(request: NextRequest) {
  const info = parseCui(request.nextUrl.searchParams.get("cui") ?? "");
  // a typo never costs a request against the one-per-second limit
  if (!info?.valid) return Response.json({ error: "invalid-cui" }, { status: 400 });

  // ANAF answers for a calendar day in Romania, not in UTC
  const today = new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Bucharest" }).format(new Date());
  let found: AnafCompany[];
  try {
    const response = await fetch(ANAF, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify([{ cui: Number(info.digits), data: today }]),
      signal: AbortSignal.timeout(8000),
    });
    if (!response.ok) throw new Error(`ANAF answered ${response.status}`);
    ({ found } = (await response.json()) as { found: AnafCompany[]; notFound: number[] });
  } catch {
    // a timeout, an error status or a page that is not JSON
    return Response.json({ error: "anaf-unavailable" }, { status: 502 });
  }

  const company = found[0];
  if (!company) return Response.json({ error: "not-found" }, { status: 404 });

  return Response.json({
    name: company.date_generale.denumire,
    address: company.date_generale.adresa,
    vatPayer: company.inregistrare_scop_Tva.scpTVA,
    // "INREGISTRAT din data ..." while active, "RADIERE din data ..." once struck off
    struckOff: company.date_generale.stare_inregistrare.startsWith("RADIERE"),
    inactive: company.stare_inactiv.statusInactivi,
  });
}
```

To ANAF, your server is the client, so every sign-up shares that one request per second. Cache answers by CUI, and for imports batch up to 100 CUIs per request.

ANAF tells you about Romanian VAT registration. For a Romanian VAT ID check on a cross-border invoice inside the EU, use VIES. The [European Commission's VIES page](https://europa.eu/youreurope/business/taxation/vat/check-vat-number-vies/index_en.htm) lists three reasons for an invalid answer: the number does not exist, it has not been activated for intra-EU transactions, or the registration is not finalized yet. A company can be a valid Romanian VAT payer and still be invalid in VIES.

#### What does a real sign-up step with a CUI lookup look like?

The [Register Page](https://wingo-ui.com/components/register-page) block has an optional company step built on these pieces. Its CUI field validates with `v.cui()` and looks up only on Enter or the Search button: since one random number in ten passes the check, a lookup on every valid keystroke would also fire on half-typed numbers. An invalid check digit shows the error and never calls the lookup. A valid number goes through `formatCui` to your `onLookupCui`. A match fades in the name, the address and a VAT badge, and the field is rewritten with `formatCui(cui, { vatPayer })`, so the prefix comes from ANAF instead of habit. Editing the number clears the result, and a late answer for an older number is ignored.

Plugging in the route handler from the previous section takes one prop. The account, code and company saves stay simulated until you pass `onRegister`, `onVerify` and `onCompany`:

```tsx
"use client";

import { RegisterPage } from "@/components/blocks/register-page";

export default function SignUpPage() {
  return (
    <RegisterPage
      onLookupCui={async (cui) => {
        const response = await fetch(`/api/company?cui=${encodeURIComponent(cui)}`);
        if (response.status === 404) return null;
        if (!response.ok) throw new Error("Lookup failed");
        const company = await response.json();
        // treat a struck-off company like an unknown one
        if (company.struckOff) return null;
        return { name: company.name, address: company.address, vatPayer: company.vatPayer };
      }}
    />
  );
}
```

Returning `null` opens the manual fields with a note, and throwing offers "Try again" and "Fill in by hand". The demo below answers from a sample table instead of ANAF, so its companies are made up.

> Live demo (Register Page): Type RO12345678 and press Enter: the check digit error appears and no lookup runs. Fix the last digit to 4 and press Enter again: the sample register fills in the company and its VAT badge. Try it at [Register Page](https://wingo-ui.com/components/register-page) and install it with `npx wingo-ui@latest add register-page`.

The step after it asks for the 6 digit code from the sign-up email; our [React OTP input guide](https://wingo-ui.com/blog/react-otp-input) covers what that field has to handle.

#### Should I copy the CUI code or install it?

Copy it when you need one field: `lib/cui.ts`, the zod rule and the free Input cover a billing or sign-up form. The ready Romanian kit (CUI, IBAN, CNP and VAT math in `invoicing`, shared messages in `form-validation`) and the whole sign-up flow are part of [Wingo UI Pro](https://wingo-ui.com/pricing). The other two ids have their own guides: [IBAN validation in JavaScript](https://wingo-ui.com/blog/iban-validation-javascript) for bank accounts and the [Romanian CNP validator](https://wingo-ui.com/blog/romanian-cnp-validator-javascript) for people. For the rest of the form anatomy, read [React form components: accessible fields, zod and mobile](https://wingo-ui.com/blog/react-form-components-guide), or browse more [component guides](https://wingo-ui.com/blog/category/components).

#### Components in this post

- [Invoicing](https://wingo-ui.com/components/invoicing) (Pro): Invoice math and the ids an invoice carries: VAT per rate the way e-Factura checks it, Romanian VAT rates, CUI, IBAN with its bank, CNP. Install: `npx wingo-ui@latest add invoicing`
- [Form validation](https://wingo-ui.com/components/form-validation) (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: `npx wingo-ui@latest add form-validation`
- [Input](https://wingo-ui.com/components/input) (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: `npx wingo-ui@latest add input`
- [Field](https://wingo-ui.com/components/field) (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: `npx wingo-ui@latest add field`
- [Register Page](https://wingo-ui.com/components/register-page) (Pro): The sign-up screen of a CRM: account with password rules, company details from the CUI, email code and a welcome step. Install: `npx wingo-ui@latest add register-page`

#### FAQ

##### What is the difference between a CUI and a CIF?

For a company they are the same digits. The CUI is the registration code the company receives, and the CIF is its tax identification code, written with the RO prefix when the company is registered for VAT. People are identified by their 13 digit CNP, which has its own check digit.

##### Is RO part of the CUI?

No. RO marks a company registered for VAT and takes no part in the checksum. Strip it before you validate, store the digits, and add RO back when you print the VAT number of a company that ANAF lists as a VAT payer.

##### How is the CUI check digit calculated?

Pad the digits before the last one to nine digits on the left, multiply them by 7, 5, 3, 2, 1, 7, 5, 3, 2 and add the products. Multiply the sum by 10 and take the remainder mod 11; a remainder of 10 becomes 0, and the result must equal the last digit.

##### Does a valid CUI mean the company exists?

No. About one random number in ten passes the check. Query ANAF's PlatitorTvaRest web service to see whether the company exists, whether it is still registered and whether it pays VAT on a given date.

##### How do I check a Romanian VAT number for an EU cross-border invoice?

Search it in VIES, the European Commission's VAT number search. An invalid answer can mean the number does not exist, or that it has not been activated for intra-EU transactions.

---

Source: https://wingo-ui.com/blog/romanian-cui-validation-javascript

### Shadcn Responsive Dialog: Card on Desktop, Sheet on Phones

> Build a shadcn responsive dialog once: a centered card above 768px, a draggable bottom sheet below it, one copy of the content and no hydration flash.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 10 min
- Canonical: https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile

#### TL;DR

A shadcn responsive dialog renders the Dialog above 768px and the Drawer, a bottom sheet you can drag down, below it. Put that switch inside one root component whose parts read the mode from context, so the content is written once and the open state survives a resize. Read the breakpoint with useSyncExternalStore so the server and the hydration render agree, and keep everything visible before the first tap identical in both modes, so nothing can flash.

The shadcn responsive dialog is the pattern from the shadcn/ui Drawer docs: a centered Dialog on desktop and a Drawer, a bottom sheet you can drag down, on phones. The recipe works, but it has you write the trigger and the header twice and pick the branch with a hook that guesses on the first render. Both cause bugs once you make a shadcn dialog mobile friendly this way: the copies drift apart, and the branch flips after mount. This tutorial builds one dialog API that renders a card above 768px and a draggable sheet below it, with the content written once and nothing to flash during hydration.

#### What does the shadcn responsive dialog recipe do?

It renders two complete trees and picks one with a media query. As of October 2026 the [shadcn Drawer docs](https://ui.shadcn.com/docs/components/radix/drawer) say "You can combine the Dialog and Drawer components to create a responsive dialog", and the [drawer-dialog example](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/examples/drawer-dialog.tsx) is shaped like this:

```tsx
const [open, setOpen] = React.useState(false)
const isDesktop = useMediaQuery("(min-width: 768px)")

if (isDesktop) {
  return <Dialog open={open} onOpenChange={setOpen}>{/* trigger, header, form */}</Dialog>
}
return <Drawer open={open} onOpenChange={setOpen}>{/* trigger, header, form, footer */}</Drawer>
```

Keeping `open` above the branch is right: a resize across 768px keeps the dialog open. Three things cost you later:

1. **Two copies.** The trigger, title and description appear in both branches, and the Cancel footer exists only in the Drawer. Every copy change has to land twice.
2. **A guess on every mount.** The example's [`useMediaQuery`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/hooks/use-media-query.tsx) starts with `useState(false)` and reads `matchMedia` in an effect. That is false on the server, which is fine, and also on the first client render of every later mount. On a desktop each mount renders the Drawer tree first and swaps after the effect, so a dialog that mounts already open (from a `?edit=1` URL, say) starts as the wrong component.
3. **A remount on every flip.** Dialog and Drawer are different component types, so a flip unmounts one tree and mounts the other, along with any state inside.

Ready-made wrappers fix the first point. As of October 2026, [Credenza](https://github.com/redpangilinan/credenza) (MIT) and [Dice UI's Responsive Dialog](https://diceui.com/docs/components/radix/responsive-dialog) wrap a dialog and a Vaul drawer in one set of parts. Credenza switches at 768px, and its `useIsMobile` also starts as `false` and flips in an effect, so it keeps the second problem. If you want to stay on stock shadcn/ui, use one of them or the wrapper below, and check what its hook returns before the first effect runs.

#### Where should the switch between dialog and drawer live?

In the root, once. The root reads the breakpoint, owns the open state and tells every part which mode it is in; each part renders the Dialog piece or the Drawer piece. This works because Vaul's `Trigger`, `Close`, `Title` and `Description` are Radix Dialog's own parts, so the trigger is the same button in both modes.

Here is that responsive dialog drawer wrapper on top of the stock shadcn/ui Dialog and Drawer (Radix versions, type-checked against their source as of October 2026):

```tsx
"use client";

import { createContext, useContext, useState, type ComponentType, type ReactNode } from "react";
import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger } from "@/components/ui/drawer";
import { useIsMobile } from "@/hooks/use-is-mobile";
import { cn } from "@/lib/utils";

const SheetMode = createContext(false);

export function ResponsiveDialog({ children }: { children: ReactNode }) {
  const sheet = useIsMobile();
  // one open state above both trees, so crossing 768px keeps it open
  const [open, setOpen] = useState(false);
  return (
    <SheetMode.Provider value={sheet}>
      {sheet ? (
        <Drawer open={open} onOpenChange={setOpen}>{children}</Drawer>
      ) : (
        <Dialog open={open} onOpenChange={setOpen}>{children}</Dialog>
      )}
    </SheetMode.Provider>
  );
}

type PartProps = { asChild?: boolean; className?: string; children?: ReactNode };

// each part renders the dialog piece or the drawer piece, plus the classes the drawer needs
function part(Card: ComponentType<PartProps>, Sheet: ComponentType<PartProps>, sheetClass = "") {
  return function ResponsivePart({ className, ...props }: PartProps) {
    const sheet = useContext(SheetMode);
    const Part = sheet ? Sheet : Card;
    return <Part className={cn(sheet && sheetClass, className)} {...props} />;
  };
}

const Div = ({ className, children }: PartProps) => <div className={className}>{children}</div>;

export const ResponsiveDialogTrigger = part(DialogTrigger, DrawerTrigger);
export const ResponsiveDialogClose = part(DialogClose, DrawerClose);
export const ResponsiveDialogContent = part(DialogContent, DrawerContent);
export const ResponsiveDialogHeader = part(DialogHeader, DrawerHeader);
export const ResponsiveDialogTitle = part(DialogTitle, DrawerTitle);
export const ResponsiveDialogDescription = part(DialogDescription, DrawerDescription);
// the drawer has no body padding and stacks its footer top down
export const ResponsiveDialogBody = part(Div, Div, "px-4");
export const ResponsiveDialogFooter = part(DialogFooter, DrawerFooter, "flex-col-reverse");
```

The two extra classes matter. `DrawerContent` has no padding of its own, so the body needs `px-4` in sheet mode. `DrawerFooter` stacks its buttons top down, so without `flex-col-reverse` the sheet would show Cancel above Save. With it, you write Cancel first and Save last, and Save lands on the right of the card and on top of the sheet. Leave the header alone: the drawer centers it with a `group-data-[vaul-drawer-direction=bottom]` selector, which outranks a plain `text-left`. That is also why the `className="text-left"` in the shadcn example changes nothing.

#### How do you avoid a hydration flash with useMediaQuery?

Make the server's answer and the first client answer the same, and keep everything visible before the first tap identical in both modes. A closed dialog renders only its trigger, and that trigger is the same Radix button in both trees, so the server can render it without knowing the screen width. The hook just has to agree with the server during hydration and be right on every render after it, which is what `useSyncExternalStore` does:

```ts
// hooks/use-is-mobile.ts
import { useSyncExternalStore } from "react";

const QUERY = "(max-width: 767.98px)";

function subscribe(onChange: () => void) {
  const list = window.matchMedia(QUERY);
  list.addEventListener("change", onChange);
  return () => list.removeEventListener("change", onChange);
}

export function useIsMobile() {
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(QUERY).matches,
    // the server and the hydration render assume a desktop
    () => false,
  );
}
```

React calls the third function on the server and during hydration, so the two match and there is no mismatch warning. Every render after that, including the first render of a dialog that mounts later, calls the second function and gets the real answer, with no effect in between. Phones correct the guess right after hydration: the root swaps Dialog for Drawer under a closed trigger, which changes nothing on screen. If you installed the shadcn Sidebar, `hooks/use-mobile.ts` already exports a `useIsMobile` built on `useState` and an effect; give it this body and the sidebar gets the same fix.

We checked the "mounts later" case on the Wingo UI Dialog, which is built this way. Its playground loads the demo after hydration, so we set the dialog to open on load and sampled the page on every animation frame in Chromium through Playwright at 390px. From the first frame the dialog existed it was the sheet, never the centered card, and the console stayed empty.

What still flashes is visible markup that branches on the hook, such as a form inline on desktop and behind a button on phones. Switch that with CSS breakpoints instead; the [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) guide has the right and wrong versions side by side. The free [useMediaQuery](https://wingo-ui.com/components/use-media-query) hook is this snippet generalized to any query with a `serverFallback` parameter, and it exports the same `useIsMobile`. Our [SSR-safe React use mobile hook tutorial](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) compares it with the `useState` and `typeof window` versions through a real hydration.

#### How do you build it with the Wingo UI Dialog?

Install the free [Dialog](https://wingo-ui.com/components/dialog) and write it once: it does the switch itself through a `responsive` prop that defaults to `true`. The root reads the breakpoint through `useSyncExternalStore`, as above, and renders a Radix dialog from 768px or the [Drawer](https://wingo-ui.com/components/drawer)'s bottom sheet below it, and every part (header, title, description, body, footer) renders the matching piece.

##### 1. Install the dialog

```bash
npx wingo-ui@latest add dialog
```

The CLI copies `components/ui/dialog.tsx` and what it imports, such as the Drawer, the media query hook, the Button and the motion helpers. All of them are free.

##### 2. Write the content once

```tsx
"use client";

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Dialog, DialogClose } from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";

type Profile = { name: string; email: string };

export function EditProfileDialog({ profile, onSave }: { profile: Profile; onSave: (next: Profile) => Promise<void> }) {
  const [open, setOpen] = useState(false);
  // the draft lives above the dialog, so crossing 768px while it is open keeps what was typed
  const [draft, setDraft] = useState(profile);
  const [saving, setSaving] = useState(false);

  async function save() {
    setSaving(true);
    try {
      await onSave(draft);
      setOpen(false);
    } finally {
      setSaving(false);
    }
  }

  return (
    <Dialog
      open={open}
      onOpenChange={setOpen}
      trigger={
        <Button variant="soft" onClick={() => setDraft(profile)}>
          Edit profile
        </Button>
      }
      title="Edit profile"
      description="Your name and email show on every invoice."
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Cancel</Button>
          </DialogClose>
          <Button loading={saving} loadingText="Saving" onClick={save}>
            Save
          </Button>
        </>
      }
    >
      <div className="flex flex-col gap-4">
        <Input label="Name" autoComplete="name" value={draft.name} onValueChange={(name) => setDraft({ ...draft, name })} />
        <Input label="Email" type="email" autoComplete="email" value={draft.email} onValueChange={(email) => setDraft({ ...draft, email })} />
      </div>
    </Dialog>
  );
}
```

The primary action goes last in the footer. On desktop it lands on the right; on the phone sheet the buttons stack full width at 48px with Save on top.

##### 3. Open it at both widths

Try the playground below on a laptop, then on a phone or with the window narrowed under 768px before you tap.

> Live demo (Dialog): Tap Edit: on a wide screen the card scales in and focuses the first field; below 768px the same dialog opens as a bottom sheet you can drag down to close. Try it at [Dialog](https://wingo-ui.com/components/dialog) and install it with `npx wingo-ui@latest add dialog`.

Below 768px the same JSX changes behavior as well as layout:

- **Dismissal.** A handle appears, the sheet follows your finger, and letting go past a quarter of its height or flicking it closes it.
- **Focus.** The desktop card focuses the first field. The sheet focuses itself, so the keyboard does not cover half the sheet before the person picks a field; Tab moves on from the top.
- **Scrolling.** A long body scrolls first and only drags the sheet once it is back at the top, and the bottom pads the home indicator.
- **Size.** `size="full"` is a 92% tall sheet on phones and a card 16px from every edge on desktop.

`classNames` apply in both modes, and the sheet's parts keep the `data-slot="dialog-*"` names, so CSS or tests that target `[data-slot=dialog-footer]` match the card and the sheet alike.

##### 4. Keep form state above the dialog

Crossing 768px keeps the dialog open but remounts its content, so state that lives inside it resets. We typed into the playground's title field at 1024px and resized the window to 390px: the sheet was open and the field was back to its original value. The shadcn example and the wrapper above behave the same way, because the root changes component type. The real case is a tablet rotated across the breakpoint, such as an iPad mini, which is 744px wide in portrait and 1133px in landscape. The fix is the one in step 2: keep the draft in the component that renders the dialog. Inside the dialog, `useDialog()` returns `{ open, setOpen, sheet }` if a part needs a different layout on the sheet.

##### 5. Opt out where a sheet is wrong

Pass `responsive={false}` to keep a centered card on phones, or set it for the whole app with `<UIProvider defaults={{ dialog: { responsive: false } }}>`. The [Alert Dialog](https://wingo-ui.com/components/alert-dialog) never becomes a sheet: on a phone a destructive question stays a centered card with its buttons stacked full width. It is part of [Wingo UI Pro](https://wingo-ui.com/pricing).

#### Shadcn drawer vs sheet: which one should you use?

The Drawer is a bottom sheet with a drag gesture; the Sheet is a panel that slides in from an edge on a CSS animation, with nothing to drag. Both can open from any edge, the Drawer from the bottom by default and the Sheet from the right. Use the Drawer, or a responsive dialog, for tasks and choices on phones, and the Sheet for content that sits beside the page on desktop, such as navigation, filters or a cart. As of October 2026:

| Component | Built on | Drag to close | From 768px |
| --- | --- | --- | --- |
| [shadcn Drawer](https://ui.shadcn.com/docs/components/radix/drawer) (Radix) | Vaul | Yes | The same drawer |
| [shadcn Sheet](https://ui.shadcn.com/docs/components/radix/sheet) | Radix Dialog | No | A side panel |
| Wingo UI [Dialog](https://wingo-ui.com/components/dialog) | Radix Dialog + Drawer | On phones | A centered card |
| Wingo UI [Drawer](https://wingo-ui.com/components/drawer) | Vaul | Yes | Sheet, side panel or dialog |
| Wingo UI [Sheet](https://wingo-ui.com/components/sheet) | Radix Dialog + motion | On touch screens | A side panel |

On the same date, [Vaul's README](https://github.com/emilkowalski/vaul) says "This repo is unmaintained", and the [Base UI docs of the shadcn Drawer](https://ui.shadcn.com/docs/components/drawer) say it "now uses Base UI instead of Vaul". The Wingo UI Drawer, and with it the Dialog's phone mode, still runs on Vaul 1.1.2. Snap points, nested sheets and the keyboard inside a sheet are covered in our [React bottom sheet guide](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web).

The Sheet covers the other common case: a filter panel from the right on desktop that becomes a bottom sheet on phones, through `mobileSide="bottom"`.

> Live demo (Sheet): Tap Filters: on a wide screen the panel slides in from the right; below 768px it rises from the bottom, and on a touch screen you drag its handle down to close it. Try it at [Sheet](https://wingo-ui.com/components/sheet) and install it with `npx wingo-ui@latest add sheet`.

#### Modal vs bottom sheet: when should a phone still get a centered card?

Use a bottom sheet for tasks and choices someone finishes and returns from, and keep a centered card for a short question that must be answered. Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/sheets) describe a sheet as "useful for requesting specific information from people or presenting a simple task that they can complete before returning to the parent view", and add: "For complex or prolonged user flows, consider alternatives to sheets." The rules we follow:

- **Forms, pickers, filters and share options:** a bottom sheet. It opens where the thumb already is and closes with the same motion.
- **Destructive confirmations** such as "Delete 3 invoices?": a centered alert dialog. A sheet's drag to dismiss makes a question that needs an answer too easy to wave away.
- **Long editors and multi-step flows:** a full-height sheet (`size="full"`) or a page of its own.

More patterns like these live in the [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui) category.

#### What should you do next?

Install the free Dialog with `npx wingo-ui@latest add dialog`, open your app at 390px and drag a sheet closed. If you stay on stock shadcn/ui, copy the wrapper and the `useSyncExternalStore` hook above into your project.

#### Components in this post

- [Dialog](https://wingo-ui.com/components/dialog) (Free): The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body. Install: `npx wingo-ui@latest add dialog`
- [Drawer](https://wingo-ui.com/components/drawer) (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: `npx wingo-ui@latest add drawer`
- [Sheet](https://wingo-ui.com/components/sheet) (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: `npx wingo-ui@latest add sheet`
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) (Free): SSR-safe hooks for media queries, phone widths, touch screens and the current Tailwind breakpoint. Install: `npx wingo-ui@latest add use-media-query`

#### FAQ

##### How do I make a shadcn dialog responsive on mobile?

Render the Drawer below 768px and the Dialog above it, from one root that owns the open state and parts that pick the matching Drawer or Dialog piece. The shadcn docs show a two-branch version; a context-based wrapper, Credenza, Dice UI or the Wingo UI Dialog keep the content in one place.

##### What is the difference between the shadcn Drawer and Sheet?

The Drawer is a bottom sheet you can drag to close, built on Vaul in the Radix version and on Base UI in the Base UI version. The Sheet extends the Dialog to slide a panel in from any edge; the Radix version animates with CSS and has no drag gesture.

##### Why does my responsive dialog show the wrong component for a moment?

Many media query hooks, including the one in the shadcn example, start as false and correct themselves in an effect, so the first render of every mount uses a guess. Read the query with useSyncExternalStore and never branch on it for anything visible before the dialog opens.

##### At what width should a dialog become a bottom sheet?

768px, Tailwind's md breakpoint, is the usual choice: the shadcn example, Credenza and Wingo UI all switch there. Below it a centered card leaves little room above the on-screen keyboard and puts its buttons far from the thumb.

##### Is the Wingo UI Dialog free?

Yes. The Dialog, Drawer, Sheet and the useMediaQuery hook are free, and npx wingo-ui@latest add dialog also installs the Drawer it uses below 768px. The Alert Dialog, which stays a centered card on phones, is Pro.

---

Source: https://wingo-ui.com/blog/shadcn-responsive-dialog-on-mobile

### Sonner Alternative for React: 4 Toast Libraries Compared

> Need a Sonner alternative? react-hot-toast, React-Toastify and a source-owned React toast compared on API, swipe, accessibility and bundle size in 2026.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/sonner-alternative-react-toast

#### TL;DR

The right Sonner alternative depends on what Sonner does not do for you, and if nothing is wrong, keep it: it is by far the most downloaded of the four toast libraries compared here and has a stack, swipe and promise toasts built in. Pick react-hot-toast for the smallest bundle (4.8 kB gzip) and a headless hook, or React-Toastify for progress bars, a queue limit and a notification history. Pick a source-owned toast, such as the free Wingo UI Toast, when you need to change how the stack behaves on phones, for screen readers or in your design system.

You go looking for a Sonner alternative when something about the toast stops fitting: the bundle, a design system that fights its stylesheet, an accessibility review, or action buttons that are hard to hit on a phone. Sonner is still the default React toast for good reasons, so leaving it should fix a specific problem. This comparison puts Sonner next to react-hot-toast, React-Toastify and a source-owned toast on the API, the stack, swipe, screen readers, phones and bundle size, checked in October 2026 against each package's published code and docs.

We build Wingo UI, whose free Toast is the source-owned option here, so read this as a vendor's comparison with sources; it says where each of the others is the better pick. More head to head comparisons live under [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons), and the [guide to shadcn alternatives](https://wingo-ui.com/blog/shadcn-alternatives) compares whole component libraries.

#### What is the best Sonner alternative for React?

The best Sonner alternative depends on what you are leaving for:

- **A smaller bundle and your own markup:** react-hot-toast. It measured 4.8 kB gzip in our build, half of Sonner, and its `useToaster` hook lets you render every toast yourself.
- **More features built in:** React-Toastify. Progress bars, a queue `limit`, `toast.update`, a stacked mode, RTL and a notification history add-on, with no extra packages.
- **Behavior you can change:** a toast whose source lives in your repository, such as the free Wingo UI [Toast](https://wingo-ui.com/components/toast). It keeps a Sonner-style `toast()` API, and the stack, the timers and the phone layout are code you can edit.
- **No problem to fix:** stay on Sonner. It is the most downloaded React toast notification library of the four by a wide margin, and shadcn/ui installs it for Radix and React Aria projects.

#### How do Sonner, react-hot-toast and React-Toastify compare?

The table reads the latest version of each package on npm as of October 9, 2026. Sizes are our own measurement: each library's toaster component and `toast` function bundled with esbuild 0.28, minified, React left external, then gzipped. Sonner and React-Toastify inject their CSS from JavaScript, so their numbers include the styles. Downloads are npm's count for October 1 to 7, 2026.

| | [Sonner](https://github.com/emilkowalski/sonner) | [react-hot-toast](https://react-hot-toast.com/docs) | [React-Toastify](https://fkhadra.github.io/react-toastify/introduction/) | [Wingo UI Toast](https://wingo-ui.com/components/toast) |
| --- | --- | --- | --- | --- |
| Version | 2.0.8, Aug 9, 2026 | 2.6.1, Sep 16, 2026 | 11.1.0, Apr 19, 2026 | Toast 1.0.0 in registry 1.7.0, Oct 8, 2026 |
| License | MIT | MIT | MIT | Free item, [Wingo UI license](https://wingo-ui.com/legal/license) |
| Weekly npm downloads | 50.8 million | 3.7 million | 2.9 million | Not on npm, copied by the CLI |
| Size, min + gzip | 9.6 kB | 4.8 kB | 9.8 kB | 12.2 kB, plus motion if you lack it |
| Default position and time | bottom-right, 4 s | top-center, 2 s for success, 4 s for others | top-right, 5 s | bottom-right, 4 s |
| Stack | Collapsed, fans out on hover, 3 visible | A list | A list, or collapsed with `stacked` | Collapsed, fans out on hover or tap, 3 visible |
| Swipe to dismiss | 45px or a flick | None | Touch only, 80% of the width | Touch and mouse, a quarter of the toast or a flick |
| Keyboard | Alt+T focuses the list, Esc collapses it | None | Alt+T focuses a toast and pauses, Esc resumes | Alt+T focuses the newest toast, Esc dismisses it |
| Screen reader | One polite region for all toasts | Each toast polite `status` | Each toast `role="alert"` | Each toast polite `status`, errors `alert` |
| Phone layout | Full width below 600px | None built in | Full width below 480px, safe areas | Full width below 768px, safe areas |
| Reduced motion | Transitions off | Fades instead of sliding | No rule in the package | Fades instead of sliding |
| Your own markup | `unstyled`, `toast.custom` | `react-hot-toast/headless` | `react-toastify/unstyled` | Edit `components/ui/toast.tsx` |

The Wingo UI size needs a footnote: in most apps it is the heaviest of the four, because it animates with motion. In a shadcn-style project that already ships tailwind-merge, lucide-react and Radix, it adds 57.6 kB, motion included. If that app already uses motion too, it adds only its own 12.2 kB, and with nothing shared it is 69 kB, seven times Sonner. Its styles are Tailwind classes that compile into your app's stylesheet, so they are not in these numbers.

#### Sonner vs react hot toast: which one should you use?

Use Sonner if you want a stack, swipe and action buttons without writing them. Use react-hot-toast if you want the smallest package and plan to render toasts your own way. The two look alike at the call site until you need a button:

```tsx
// sonner: action and cancel are options
import { toast } from "sonner";

export function onDelete(restore: () => void) {
  toast("Listing deleted", {
    description: "City bike, Trek FX 2",
    action: { label: "Undo", onClick: restore },
  });
}
```

```tsx
// react-hot-toast: no action option, so the button is your markup
import toast from "react-hot-toast";

export function onDelete(restore: () => void) {
  toast((t) => (
    <span>
      Listing deleted
      <button
        onClick={() => {
          restore();
          toast.dismiss(t.id);
        }}
      >
        Undo
      </button>
    </span>
  ));
}
```

Beyond buttons, react-hot-toast lists toasts instead of stacking them, has no swipe and no keyboard handling, and pauses its timers only on mouse enter and leave, not for keyboard focus or a background tab. Success toasts default to 2 seconds, which is short for an Undo. Its strength is the headless entry: `useToaster` from `react-hot-toast/headless` hands you the toasts plus `startPause`, `endPause` and `calculateOffset`, the right shape if you want full control of the markup and will write the gestures yourself.

Sonner gives you polished defaults: a 356px stack, swipe in the directions its position allows, `toast.promise`, `richColors` and a close button, with timers that pause while you hover, while you swipe and while the tab is in the background. Its look comes from its own stylesheet, so matching a design system means CSS variables and `classNames`, or `unstyled` and your own markup.

#### When is React-Toastify the better pick?

Pick React-Toastify when you need features the others leave out: a progress bar on every toast, on by default, and a controlled `progress` value for uploads. `limit` holds extra toasts in a waiting queue, `toast.update(id, options)` changes a toast in place, `stacked` collapses the list, and the `useNotificationCenter` add-on keeps a history of toasts for an inbox. It handles RTL and positions its container with `env(safe-area-inset-*)` on phones.

Its defaults are the loudest of the four: a close button and a progress bar on every toast, 5 seconds on screen, and `role="alert"` on each toast, so screen readers interrupt the user for a "Saved" message unless you pass `role="status"`. We found no `prefers-reduced-motion` rule in the 11.1.0 package, so the default Bounce transition plays for everyone; pass `transition={Slide}` or your own `cssTransition` if that matters to you.

If those defaults or the styling are why you want a React Toastify alternative, Sonner is the closest swap for the call sites (`toast.success`, `toast.error`, `toast.promise`). The main rename is the promise's loading message: React-Toastify calls it `pending` and Sonner calls it `loading`. A history with read state is an inbox, a different job: Wingo UI keeps it in a separate [Notification Center](https://wingo-ui.com/components/notification-center) with a bell and an unread count.

#### What does "shadcn toast" mean in 2026?

It depends on the project's base. Since July 2026 new shadcn/ui projects start on Base UI, and for those `npx shadcn@latest add toast` installs a Toast [built on Base UI primitives](https://ui.shadcn.com/docs/changelog/2026-07-toast), called with `toast.add({ title, description })` and `toast.promise`. In Radix and React Aria projects, the old Toast is marked deprecated and the docs point to [Sonner](https://ui.shadcn.com/docs/components/radix/sonner): `npx shadcn@latest add sonner` writes a `components/ui/sonner.tsx` that wraps the package, maps its colors to your `--popover` and `--border` tokens and reads the theme from `next-themes`.

So the shadcn toast in a Radix project is Sonner with your colors: you own a short wrapper, and the stack, timers and swipe stay in `node_modules/sonner`. The Base UI version hands you more of the markup, with behavior from Base UI's `Toast` parts. Per the [Base UI docs](https://base-ui.com/react/components/toast), that means a 5 second default timeout, a limit of 3, swipe down or right, a `priority: "high"` option for urgent announcements, and F6 to move focus into the toast region.

#### What changes on a phone?

The phone is where these libraries differ most, on four points:

- **Width.** Sonner spans the screen below 600px with 16px gutters (`mobileOffset`). React-Toastify spans it below 480px with square corners. react-hot-toast has no phone layout: its toasts cap at 350px and sit 16px from the edges.
- **Buttons.** Sonner's default action and cancel buttons are 24px tall, exactly WCAG 2.2's minimum target size, and its close button is 20px, under it. All of them are far from the 44pt Apple recommends for iOS controls; our [guide to minimum touch target size](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind) has the numbers.
- **Safe areas.** React-Toastify positions its container with the safe area insets. Sonner and react-hot-toast do not, so with `viewport-fit=cover` a bottom stack can sit on the iPhone home indicator until you add the inset to the offset yourself. [Tailwind safe area insets](https://wingo-ui.com/blog/tailwind-safe-area-insets) shows the pattern.
- **Swipe.** Sonner dismisses after 45px of travel or a quick flick. React-Toastify swipes on touch only by default and wants 80% of the toast's width. react-hot-toast has no swipe.

We built the Wingo UI Toast around that list. Below 768px toasts span the width with 16px gutters, each edge uses `max(env(safe-area-inset-*), 16px)`, and `mobilePosition="top"` moves them clear of a bottom tab bar. Action and close buttons look 32px tall and keep a 44px hit area on touch screens. With no hover on a phone, a tap fans out the stack.

> Live demo (Toast): Hover the stack to fan it out (tap it on a phone), then swipe the front toast toward the edge. Press Failed payment, then Retry: the same toast turns into a loading state and then a success. Try it at [Toast](https://wingo-ui.com/components/toast) and install it with `npx wingo-ui@latest add toast`.

#### How do the toasts sound to a screen reader?

All four announce through ARIA live regions; the difference is what gets interrupted. A polite announcement waits until the screen reader finishes speaking. An assertive one, which `role="alert"` implies, cuts in.

- **Sonner** wraps every toast in one `<section aria-live="polite">` labeled "Notifications alt+T". A failed payment is announced as politely as "Copied".
- **react-hot-toast** gives each toast `role="status"` and `aria-live="polite"`, and you can switch a single toast to `alert` through its `ariaProps` option.
- **React-Toastify** gives each toast `role="alert"`, so every toast interrupts unless you change the role.
- **Wingo UI** makes each toast its own polite `status` and switches errors, and any toast sent with `important: true`, to `role="alert"`.

For the keyboard, Sonner's Alt+T focuses the list and Escape collapses it, React-Toastify's focuses a toast and pauses every timer until Escape, and react-hot-toast has none. In the Wingo UI Toast, Alt+T (Option+T on a Mac) focuses the newest toast, Tab walks through its buttons, Escape dismisses the focused toast, and timers pause while keyboard focus is inside, so there is time to reach Undo.

#### When should you skip the toast and use an inline alert?

Skip it when the message has to be read or acted on. A declined card, a form that failed to save, or a session about to expire need a message that stays next to the problem. Toasts time out, sit far from the field that caused them, and on a phone they can cover the submit button. Use an inline alert for those and keep toasts for confirmations, progress and quick undos. The free [Alert](https://wingo-ui.com/components/alert) follows the same split for screen readers: danger and warning tones use `role="alert"`, the others `role="status"`.

> Live demo (Alert): A declined card belongs next to the Pay button: press Try again and the alert collapses, then press Pay to see it expand back in. Try it at [Alert](https://wingo-ui.com/components/alert) and install it with `npx wingo-ui@latest add alert`.

#### What does a source-owned toast give you?

A source-owned toast puts the whole component in your repository: the store, the stack, the gesture and the markup. You review it like the rest of your code, and nothing changes under you on `npm update`. The cost is that upstream fixes reach you only when you pull them. The Wingo UI Toast is free; install it with the CLI:

```bash
npx wingo-ui@latest add toast
```

That writes `components/ui/toast.tsx` plus the button, the spinner and the hooks and helpers it uses. Mount the Toaster once, next to the app:

```tsx
// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { Toaster } from "@/components/ui/toast";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <Toaster richColors mobilePosition="top" />
    </>
  );
}
```

Then call `toast` from anywhere, even outside React or before the Toaster mounts:

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

export function onDelete(restore: () => void) {
  toast("Listing deleted", {
    description: "City bike, Trek FX 2",
    action: { label: "Undo", onClick: restore },
  });
}

export async function publishListing(publish: () => Promise<{ price: string }>) {
  // returns the original promise: await gives you the data or throws the error
  return toast.promise(publish, {
    loading: "Publishing the listing…",
    success: (data) => `Published for ${data.price}`,
    error: "Could not publish the listing",
  });
}
```

Beyond those call sites, the file gives you:

- **Updates by id.** Calling `toast.loading("Uploading 3 photos… 2/3", { id: "upload" })` again updates the toast in place. A new type with the same id, such as `toast.success`, starts it over, so the loading toast's `Infinity` duration never sticks to the success.
- **Your tokens.** The surface uses `bg-popover` and your theme's status tones, so dark mode needs no `theme` prop. Visual props such as `radius`, `width` and `richColors` can also be set app-wide through `UIProvider` defaults.
- **Updates that keep your edits.** `npx wingo-ui@latest update` merges a new release into the file you changed, as [the updates docs](https://wingo-ui.com/docs/updates) describe.

The trade-offs, stated plainly. It is younger than the three packages, and Sonner has years of bug reports behind it. It costs more bytes than any of them, even in an app that already uses motion. In a shadcn project created with a Base UI style, install it with the Wingo UI CLI instead of `shadcn add`, because that style rewrites `asChild`, which the button relies on. The Notification Center is part of [Wingo UI Pro](https://wingo-ui.com/pricing); the Toast and the Alert are free.

#### How do you move from Sonner to the Wingo UI Toast?

Most call sites only change the import. The API follows Sonner's: `toast`, `toast.success`, `error`, `warning`, `info` and `loading`, `toast.promise`, `toast.custom`, `toast.dismiss`, the `action`, `cancel` and `toasterId` options, and the `position`, `expand`, `visibleToasts`, `duration`, `richColors` and `closeButton` props keep their names and defaults. The differences:

| Sonner | Wingo UI Toast |
| --- | --- |
| `import { toast } from "sonner"` | `import { toast } from "@/components/ui/toast"` |
| `hotkey={["altKey", "KeyT"]}` | `hotkey="alt+t"` |
| `<Toaster id="editor" />` for a second toaster | `<Toaster toasterId="editor" />` |
| `toast.promise(...).unwrap()` for the result | `toast.promise(...)` returns the original promise |
| `theme` prop, or `next-themes` in the shadcn wrapper | None; the surface uses your tokens |
| `event.preventDefault()` in an action keeps the toast open | The same, or `keepOpen: true` on the action |
| `mobileOffset` below 600px | `mobileOffset` below 768px, plus `mobilePosition` |
| `toast.message`, `toast.getHistory` | Not available; `useToasts()` returns the toasts on screen |

If you used the shadcn wrapper, delete `components/ui/sonner.tsx`, point the `Toaster` import at `@/components/ui/toast`, and replace `from "sonner"` in the files that call `toast`. Then drop any `theme` prop from the Toaster and the `.unwrap()` after promise toasts, which TypeScript flags.

#### Where should you start?

If Sonner works and nobody has complained, keep it. If the complaint is about phones, screen readers or a design system that will not bend, try a source-owned toast: run `npx wingo-ui@latest add toast`, which is free and needs no account, swap the import on a few call sites, and open the app on your own phone.

#### Components in this post

- [Toast](https://wingo-ui.com/components/toast) (Free): Toast notifications: a Toaster mounted once and a toast() you call from anywhere, stacked, swipeable and paused while you read. Install: `npx wingo-ui@latest add toast`
- [Alert](https://wingo-ui.com/components/alert) (Free): An inline message about a page or a section, from a failed payment to a maintenance banner, in three variants and six tones. Install: `npx wingo-ui@latest add alert`

#### FAQ

##### What is the best Sonner alternative for React?

It depends on why you are leaving. react-hot-toast is the smallest and has a headless hook, React-Toastify has the most built-in features, and a source-owned toast like the free Wingo UI Toast keeps a Sonner-style API while every behavior lives in a file you can edit.

##### Is Sonner better than react-hot-toast?

Sonner does more out of the box: a collapsed stack, swipe to dismiss, action and cancel buttons, a promise toast and an Alt+T shortcut. react-hot-toast is about half the size at 4.8 kB gzip in our build and ships a headless useToaster hook, but it has no swipe, no keyboard shortcut and no built-in action buttons.

##### Does shadcn/ui still use Sonner for toasts?

It depends on the project's base. In Radix and React Aria projects the old Toast is deprecated and npx shadcn@latest add sonner installs a short wrapper around the sonner package. In Base UI projects, the default for new projects since July 2026, npx shadcn@latest add toast installs a Toast built on Base UI with a toast.add() API.

##### Which React toast library is the smallest?

react-hot-toast, at 4.8 kB minified and gzipped in our esbuild measurement in October 2026. Sonner came to 9.6 kB and React-Toastify to 9.8 kB, both including the CSS they inject from JavaScript.

##### Are toast notifications accessible to screen readers?

They are announced through ARIA live regions, but the libraries differ in urgency: Sonner announces everything politely, React-Toastify marks every toast role="alert" by default, and react-hot-toast and the Wingo UI Toast let single toasts interrupt. Anything the user must act on belongs in an inline alert, because toasts time out.

---

Source: https://wingo-ui.com/blog/sonner-alternative-react-toast

### Tailwind Safe Area Insets: Bottom Bars, FABs and Toasts

> A Tailwind safe area guide for v4: opt in with viewport-fit=cover, pad bars with env(safe-area-inset-bottom) and keep FABs and toasts off the home indicator.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/tailwind-safe-area-insets

#### TL;DR

Tailwind CSS v4 has no safe area utilities, so you set viewport-fit=cover and pad every element pinned to a screen edge with env(safe-area-inset-*), either as arbitrary values like pb-[max(env(safe-area-inset-bottom),12px)] or as a few @utility classes. Keep bottom bars at bottom-0 and pad them on the inside, so their background runs under the home indicator. Place a floating button at the larger of the bar height and the inset, plus a gap, and let a second bar pad only the part of the inset the first one leaves uncovered, so the gap is never doubled.

You let the page fill the screen with `viewport-fit=cover`, pin a tab bar to `bottom-0`, open it on an iPhone, and the home indicator sits on top of your labels. Turn the phone sideways and the notch clips the start of every row. In Tailwind CSS v4, Tailwind safe area handling is up to you, because core ships no classes for it: everything pinned to an edge has to pad itself with `env(safe-area-inset-*)`. This tutorial builds the bottom of a phone screen, with a tab bar, a buy bar, a floating action button and toasts, so that none of them hides under the notch or the home indicator and none of them doubles the gap when they stack.

Safe areas are one of the nine rules in [Mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components). This post is the step by step version, with the arithmetic for bars that sit on top of each other.

#### What does viewport-fit cover change?

It tells the browser that your page handles the screen's cutouts itself. With the default, `viewport-fit=auto`, Safari on an iPhone insets the page so nothing lands under the notch or the rounded corners, and fills the leftover strips with the background color of `<html>` or `<body>` ([WebKit, 2017](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)). With `cover`, the viewport fills the whole display, and [MDN's viewport reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport) says it is "highly recommended" to use the safe area inset variables so that important content stays visible.

Android joined in 2025. From [Chrome 135](https://developer.chrome.com/docs/css-ui/edge-to-edge), Chrome on Android phones draws edge to edge. By default it shows a "chin" over the gesture bar that slides away as you scroll, and a `position: fixed; bottom: 0` bar ends up behind the navigation bar once the chin is gone. A page that sets `viewport-fit=cover` goes edge to edge on load and never shows the chin. Either way, the insets now matter on Android too.

In the Next.js App Router the meta tag comes from a `viewport` export in the root layout, which has to be a Server Component:

```tsx
// app/layout.tsx
import type { Viewport } from "next";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};
```

Next.js renders it as `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`. Outside Next.js, write that tag yourself. Treat `cover` as a promise: from now on, every element you pin to an edge pads itself.

#### Why does env safe-area-inset-bottom return 0?

Usually because the page has no `viewport-fit=cover`, or because nothing covers that edge on the device you are testing. Without `cover`, Safari keeps the page inside the safe area itself, so on an iPhone there is no inset left to report. Desktop browsers report 0 as well ([MDN on env()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/env)), so a layout that looks right in a narrow desktop window proves nothing. An iPhone with a Home button, like the iPhone SE, has no home indicator and reports 0 at the bottom, which is why every rule below pairs the inset with a minimum instead of trusting it alone.

Check the rendered page, not your source: open the head in the inspector and make sure there is exactly one viewport tag and that it carries `viewport-fit=cover`. A second tag added by a plugin or a hand-written `<head>` can override the first. Variable names are case-sensitive too, so `env(SAFE-AREA-INSET-BOTTOM)` silently falls back.

#### How do you write a Tailwind safe area inset bottom utility?

Use an arbitrary value for a one-off, and define a few `@utility` classes once it shows up in more than two places. Tailwind CSS v4 has no safe area utilities in core: as of version 4.3.3, the only `-safe` classes are alignment ones like `justify-center-safe`, which map to the CSS `safe` overflow keyword and have nothing to do with the notch.

The arbitrary value works anywhere: `pb-[max(env(safe-area-inset-bottom),12px)]`. For a project, put a small set in your stylesheet:

```css
/* app/globals.css */
@import "tailwindcss";

@utility pt-safe {
  padding-top: env(safe-area-inset-top, 0px);
}

@utility pb-safe {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

/* the inset, but never less than a spacing step: pb-safe-or-3 */
@utility pb-safe-or-* {
  padding-bottom: max(env(safe-area-inset-bottom, 0px), --spacing(--value(integer)));
}

/* landscape: the notch side gets the inset, the other side keeps the gutter: px-safe-or-4 */
@utility px-safe-or-* {
  padding-left: max(env(safe-area-inset-left, 0px), --spacing(--value(integer)));
  padding-right: max(env(safe-area-inset-right, 0px), --spacing(--value(integer)));
}

/* a gap on top of the inset, for floating elements: bottom-safe-offset-4 */
@utility bottom-safe-offset-* {
  bottom: calc(env(safe-area-inset-bottom, 0px) + --spacing(--value(integer)));
}
```

The `-*` at the end of a name makes a utility functional, and `--value(integer)` reads the number after it, so `pb-safe-or-3` compiles to `padding-bottom: max(env(safe-area-inset-bottom, 0px), calc(var(--spacing) * 3))`, and variants like `md:pb-safe` work as they do for any other class. If you would rather install the whole set (margins, scroll padding, `h-dvh-safe`, and `-offset-` and `-or-` forms for each), the [tailwindcss-safe-area](https://www.npmjs.com/package/tailwindcss-safe-area) package adds it with `@import "tailwindcss-safe-area";` (version 1.3.0, MIT license, as of October 2026).

The two functions do different jobs. Use `max()` when the inset replaces your normal spacing, like a bar's bottom padding or a toast's gutter: on a phone with a home indicator the inset wins, and on a laptop your 12px does. Use `calc()` when you need a gap on top of the inset, like a button that floats 16px above the indicator. WebKit's original post uses the `max()` form for side padding for the same reason.

#### How do you pad a fixed bottom bar?

Pad the inside of the bar and leave the bar itself at `bottom-0`. Its background then runs under the home indicator, and the padding lifts the tappable row above it. The iPhone home indicator CSS fix is one class on the bar, `pb-safe`:

```tsx
// components/tab-bar.tsx
import Link from "next/link";
import { House, Search, ShoppingBag, UserRound } from "lucide-react";

const tabs = [
  { href: "/", label: "Home", icon: House },
  { href: "/search", label: "Search", icon: Search },
  { href: "/cart", label: "Cart", icon: ShoppingBag },
  { href: "/account", label: "Account", icon: UserRound },
];

export function TabBar() {
  return (
    <nav
      aria-label="Primary"
      className="fixed inset-x-0 bottom-0 z-40 border-t border-border bg-background/90 pb-safe px-safe-or-2 backdrop-blur md:hidden"
    >
      <ul className="flex h-16">
        {tabs.map(({ href, label, icon: Icon }) => (
          <li key={href} className="flex-1">
            <Link
              href={href}
              className="flex h-full flex-col items-center justify-center gap-1 text-[11px] font-medium touch-manipulation"
            >
              <Icon aria-hidden className="size-6" />
              {label}
            </Link>
          </li>
        ))}
      </ul>
    </nav>
  );
}
```

The row stays 64px tall everywhere. On a phone with a home indicator the bar grows by the inset; on a desktop the inset is 0 and nothing changes. `px-safe-or-2` keeps the first and last tab clear of the notch in landscape. Each tab is a quarter of the screen wide and 64px tall, comfortably above the [minimum touch target size](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind).

Moving the bar up with `bottom-[env(safe-area-inset-bottom)]` looks similar in a screenshot, but the page then scrolls through a visible strip under the bar. Chrome's guide shows the same effect on Android.

The content behind the bar needs the same space, or the last row of a list never scrolls into view:

```tsx
<main className="pb-[calc(4rem+env(safe-area-inset-bottom))] md:pb-0">{children}</main>
```

##### What about Chrome's warning against padding with the inset?

It applies to pages that keep the chin. Chrome's guide says not to set `padding-bottom` to `env(safe-area-inset-bottom)`, because without `cover` the inset changes while the chin slides away, the padding forces a layout on every step, and Chrome stops sliding the chin away when it detects that pattern. With `viewport-fit=cover` there is no chin to slide.

If you cannot opt in, use Chrome's alternative: reserve the largest inset up front and move the bar with `bottom`, a `calc(env(safe-area-inset-bottom, ...) - ...)` pattern that Chrome has a fast path for. Tailwind's preflight sets `box-sizing: border-box`, so the height has to include the padding:

```tsx
<nav className="fixed inset-x-0 [--safe-max-b:env(safe-area-max-inset-bottom,36px)] h-[calc(4rem+var(--safe-max-b))] pb-(--safe-max-b) bottom-[calc(env(safe-area-inset-bottom,0px)-var(--safe-max-b))]">
  {/* tabs */}
</nav>
```

`safe-area-max-inset-bottom` arrived in Chrome 135. The 36px fallback is the value Chrome's guide uses for browsers without it.

#### How do you stack a FAB above a tab bar without doubling the gap?

Put the bar's full height, inset included, in a CSS variable, then place the button at the larger of that variable and the inset, plus your gap. Adding them double-counts: the bar's height already contains the inset, so `bar + inset + 16px` floats the button a whole home indicator strip too high.

For the static bar above, the variable can be pure CSS. Set it on a wrapper so the button inherits it, and reset it where the bar is hidden:

```tsx
// components/mobile-shell.tsx
import type { ReactNode } from "react";
import { Plus } from "lucide-react";
import { TabBar } from "@/components/tab-bar";

export function MobileShell({ children }: { children: ReactNode }) {
  return (
    <div className="[--bottom-bar-offset:calc(4rem+env(safe-area-inset-bottom,0px))] md:[--bottom-bar-offset:0px]">
      <main className="pb-[calc(var(--bottom-bar-offset)+1rem)]">{children}</main>
      <button
        type="button"
        aria-label="New listing"
        className="fixed right-[calc(1rem+env(safe-area-inset-right,0px))] bottom-[calc(max(var(--bottom-bar-offset),env(safe-area-inset-bottom,0px))+1rem)] z-40 grid size-14 place-items-center rounded-full bg-foreground text-background shadow-lg touch-manipulation"
      >
        <Plus aria-hidden className="size-6" />
      </button>
      <TabBar />
    </div>
  );
}
```

From `md` up the variable is `0px`, so `max()` falls back to the inset and the button floats 16px above the bottom edge, or above the inset where the device has one. The same wrapper gives `main` its bottom padding, so the variable is the only place the bar's height is written down.

When the height is not known up front (a bar with a different size per page, a buy bar that slides in after you scroll), measure it instead: a `ResizeObserver` on the bar writes its height to the variable on `<html>`. The Wingo UI [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) writes `--bottom-bar-offset` that way when it is fixed, and its value drops to 0 while `md:hidden` hides the bar. The [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) writes `--cta-bar-offset`, its visible height, which falls to 0 while it is hidden. The [FAB](https://wingo-ui.com/components/fab) reads both:

```css
bottom: calc(max(var(--bottom-bar-offset, 0px) + var(--cta-bar-offset, 0px), env(safe-area-inset-bottom, 0px)) + 16px);
```

So the components need no props to cooperate. Render them side by side and the button stays above whichever bars are on screen:

```tsx
"use client";

import { FileText, House, Inbox, UserPlus, UserRound, Users } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";
import { Fab, type FabAction } from "@/components/ui/fab";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Profile", href: "/profile", icon: <UserRound /> },
];

const actions: FabAction[] = [
  { id: "client", label: "New client", icon: <UserPlus />, href: "/clients/new" },
  { id: "invoice", label: "New invoice", icon: <FileText />, href: "/invoices/new" },
];

export function MobileChrome() {
  return (
    <>
      <Fab label="Add" actions={actions} hideOnScroll />
      <BottomTabBar items={tabs} className="md:hidden" hideOnScroll />
    </>
  );
}
```

One catch in Next.js: without a `LinkProvider` the tabs render plain `<a>` elements, so every tap reloads the page and the bar only knows its active tab from its own state. Wrap the app once in `<LinkProvider component={Link} currentPath={usePathname()}>` from `@/lib/navigation`, inside a client component, and the tabs navigate through `next/link` and highlight the current route.

> Live demo (FAB): Tap Add to open the speed dial, then scroll the client list: the label folds into the icon on the way down and comes back on the way up. Try it at [FAB](https://wingo-ui.com/components/fab) and install it with `npx wingo-ui@latest add fab`.

The demo has no tab bar, and on a desktop the inset is 0, so the button sits 16px above the bottom of the frame. We emulated a 34px bottom inset in Chromium with the test at the end of this post: the FAB's rule computed to `bottom: 50px` (34 + 16), and the Bottom Tab Bar's bottom padding to 34px.

#### How do you put a buy bar on top of a tab bar?

Position it at `bottom: var(--bottom-bar-offset)` and pad only the part of the inset the tab bar does not already cover. The Sticky CTA Bar uses this class for its bottom padding:

```text
pb-[max(0px,calc(env(safe-area-inset-bottom,0px)-var(--bottom-bar-offset,0px)))]
```

With a tab bar below, the subtraction goes negative and `max()` clamps it to 0, so the buy bar adds no gap of its own. On a product page without a tab bar the variable is 0 and the buy bar pads the whole inset itself. Its sides use `pl-[max(1rem,env(safe-area-inset-left,0px))]` and the matching right class, so a landscape phone keeps the price clear of the notch.

```tsx
// components/buy-bar.tsx
import { StickyCtaBar } from "@/components/ui/sticky-cta-bar";

export function BuyBar({ onAddToCart }: { onAddToCart: () => Promise<void> }) {
  return (
    <StickyCtaBar
      price={349}
      compareAtPrice={449}
      locale="en-US"
      actionLabel="Add to cart"
      tone="brand"
      hideFrom="md"
      onAction={onAddToCart}
    />
  );
}
```

Render it next to the `BottomTabBar` from the previous section and it sits on top of the tab bar; render it alone and it sits on the bottom edge. While the promise from `onAction` is pending, the button shows a spinner.

> Live demo (Sticky CTA Bar): Scroll the listing: the bar stays pinned to the bottom with the agent on the left and Call on the right. Press Call and the button shows a spinner without changing its width. Try it at [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) and install it with `npx wingo-ui@latest add sticky-cta-bar`.

The demo pins the bar inside a phone frame with `position="sticky"`, because `fixed` would pin it to your browser window. The safe area padding is the same in both modes, and `hideFrom="md"` hides the bar with CSS on wide screens, where the page shows its own buy button.

#### Where should toasts go on a phone with a home indicator?

Pin the stack to the larger of the inset and your gutter, and if the app has a bottom tab bar, show toasts at the top on phones. The Wingo UI [Toast](https://wingo-ui.com/components/toast) does the first part for you. Below 768px toasts span the width with 16px gutters (`mobileOffset`), and each edge uses `max(env(safe-area-inset-*), 16px)`, so a bottom stack clears the home indicator and a top stack clears the notch and the status bar. Our [Sonner alternatives comparison](https://wingo-ui.com/blog/sonner-alternative-react-toast) shows which other toast libraries pad the safe area for you.

The Toaster does not read `--bottom-bar-offset`, so on a phone a bottom stack would cover a tab bar. In an app with one, move phone toasts to the top. With the viewport export from the first section, the root layout ends up like this:

```tsx
// app/layout.tsx
import type { ReactNode } from "react";
import type { Viewport } from "next";
import { Toaster } from "@/components/ui/toast";
import "./globals.css";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster mobilePosition="top" />
      </body>
    </html>
  );
}
```

> Live demo (Toast): Press Save, then Failed payment: on a wide screen the toasts stack in the bottom right corner, and below 768px they span the width at the top. Swipe one away to dismiss it. Try it at [Toast](https://wingo-ui.com/components/toast) and install it with `npx wingo-ui@latest add toast`.

Desktop placement keeps its own `position` and `offset` props, so the corner stack on a laptop stays where it was.

#### How do you test safe areas without an iPhone?

On a Mac, Xcode's iOS Simulator runs Safari with each simulated device's real insets. In CI, Chromium can fake them: the Chrome DevTools Protocol has an experimental `Emulation.setSafeAreaInsetsOverride` command that overrides the `env(safe-area-inset-*)` and `env(safe-area-max-inset-*)` values, and Playwright can send it through a CDP session:

```ts
// e2e/safe-area.spec.ts
import { test, expect } from "@playwright/test";

test.use({ viewport: { width: 390, height: 844 } });

test("the tab bar pads the home indicator", async ({ page, context, browserName }) => {
  test.skip(browserName !== "chromium", "the override is a Chrome DevTools Protocol command");
  const cdp = await context.newCDPSession(page);
  await cdp.send("Emulation.setSafeAreaInsetsOverride", {
    insets: { top: 47, bottom: 34, left: 0, right: 0 },
  });
  await page.goto("/"); // baseURL comes from playwright.config.ts
  const nav = page.getByRole("navigation", { name: "Primary" });
  await expect(nav).toHaveCSS("padding-bottom", "34px");
});
```

We ran this pattern against the Bottom Tab Bar, FAB and Sticky CTA Bar previews with Playwright 1.63 and its bundled Chromium in October 2026. Pick the inset values of the devices you care about, and add a second case with `bottom: 0` to catch bars that lose their minimum padding on phones without a home indicator. The command is marked experimental, so pin your Playwright version.

#### Where should you start?

Add `viewportFit: "cover"` and the five utilities above, then fix the bars from the bottom up: the tab bar first, then everything that floats above it. Safe areas reach past bars, too: in Wingo UI 1.7.0, 38 component files read `env(safe-area-inset-*)`, from sheets and dialogs to the cookie consent banner and the image lightbox. The [bottom sheet guide](https://wingo-ui.com/blog/react-bottom-sheet-for-the-web) covers how a sheet's footer handles the home indicator.

If you want the toast placement from this post without writing it, the Toast is free: run `npx wingo-ui@latest add toast` and mount the Toaster once in your root layout. The Bottom Tab Bar, Sticky CTA Bar and FAB are part of [Wingo UI Pro](https://wingo-ui.com/pricing). More guides like this one live in [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui).

#### Components in this post

- [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) (Pro): The bottom action bar of product, listing and checkout pages on phones: the price on one side, the main action on the other. Install: `npx wingo-ui@latest add sticky-cta-bar`
- [Bottom Tab Bar](https://wingo-ui.com/components/bottom-tab-bar) (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: `npx wingo-ui@latest add bottom-tab-bar`
- [FAB](https://wingo-ui.com/components/fab) (Pro): The floating action button for a phone screen's main action, with a labelled or radial speed dial and a label that folds while you scroll. Install: `npx wingo-ui@latest add fab`
- [Toast](https://wingo-ui.com/components/toast) (Free): Toast notifications: a Toaster mounted once and a toast() you call from anywhere, stacked, swipeable and paused while you read. Install: `npx wingo-ui@latest add toast`

#### FAQ

##### Does Tailwind CSS have safe area utilities?

Not in core. As of Tailwind CSS 4.3.3 (October 2026) there is no pb-safe class, so you use arbitrary values like pb-[max(env(safe-area-inset-bottom),12px)], define a few classes with @utility, or install the tailwindcss-safe-area package.

##### Why is env(safe-area-inset-bottom) always 0?

On an iPhone the usual cause is a page without viewport-fit=cover, so Safari keeps the page inside the safe area itself and has no inset to report. Desktop browsers and iPhones with a Home button also report 0 at the bottom, so pair the inset with a minimum through max().

##### Do I need viewport-fit=cover on Android?

Not to go edge to edge: since Chrome 135, Chrome on Android phones draws edge to edge anyway, with a chin over the gesture bar that slides away as you scroll. With viewport-fit=cover the page reaches the bottom edge from the start and the chin never shows, so fixed bottom bars need the safe area inset on Android just as on an iPhone.

##### Should a bottom bar use padding or bottom: env(safe-area-inset-bottom)?

Padding, on a page that sets viewport-fit=cover. The bar stays on the bottom edge with its background under the home indicator, while bottom: env() leaves a strip where the page shows through. Pages that keep Chrome's chin should use Chrome's pattern with safe-area-max-inset-bottom instead.

##### How do I test safe area insets without an iPhone?

Use Xcode's iOS Simulator on a Mac, or emulate the insets in Chromium with the experimental DevTools Protocol command Emulation.setSafeAreaInsetsOverride, which Playwright can send through a CDP session.

---

Source: https://wingo-ui.com/blog/tailwind-safe-area-insets

### Tailwind v4 Design Tokens: Colors, Dark Mode and Contrast

> Tailwind v4 design tokens from a production React library: @theme inline, semantic surfaces, status colors, dark mode and a contrast check you can run in CI.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Next.js and Tailwind CSS](https://wingo-ui.com/blog/category/nextjs-tailwind)
- Reading time: 19 min
- Canonical: https://wingo-ui.com/blog/tailwind-v4-design-tokens

#### TL;DR

Tailwind v4 design tokens are CSS variables: keep the values that change between light and dark in :root and .dark, then map them to utilities with @theme inline, so bg-surface or text-muted-foreground follow the theme with no dark: prefix. A complete set names roles instead of colors: surfaces in the order they stack, text levels, tones split into a solid fill and a readable text color, plus radius, elevation, z-index and motion scales. Check every text and surface pair for 4.5:1 contrast in both themes with a script, because a color that passes on white often fails on a dark popover.

Tailwind CSS v4 moved configuration out of `tailwind.config.js` and into CSS, and many guides stop at the first step: put a few brand colors in `@theme` and call them tokens. A component library needs more than a palette. It needs Tailwind v4 design tokens for every decision a component makes: which surface sits in front of which, how muted secondary text can get, what a warning uses as a fill and as text, how round a 32px button is next to a 48px one, how a popover casts a shadow on a black page, and which layer a select opens on inside a dialog. This guide is the token system we use in Wingo UI, a React 19 and Tailwind CSS v4 component library, with the real CSS and the contrast numbers behind each choice. We build Wingo UI, so we are not neutral; outside facts link to their sources and are dated.

#### What are design tokens in Tailwind v4?

Design tokens in Tailwind v4 are CSS custom properties. Tailwind v4 theme variables, the ones you declare inside an `@theme` block, do two jobs at once: they are CSS variables you can read with `var()`, and their namespace decides which utilities Tailwind generates. `--color-surface` creates `bg-surface`, `text-surface` and `border-surface`; `--shadow-raised` creates `shadow-raised`. Tailwind CSS v4.0 shipped this CSS-first configuration on January 22, 2025 ([release post](https://tailwindcss.com/blog/tailwindcss-v4)), and the [theme variables docs](https://tailwindcss.com/docs/theme) list the namespaces. We run Tailwind 4.3.3 as of October 2026.

The namespaces a component library uses most:

| Namespace | Utilities it creates | What we keep there |
| --- | --- | --- |
| `--color-*` | `bg-*`, `text-*`, `border-*`, `ring-*`, `fill-*` | surfaces, text levels, tones, borders, the focus ring |
| `--shadow-*` | `shadow-*` | three elevation levels |
| `--radius-*` | `rounded-*` | a legacy scale that new code avoids (see the radius section) |
| `--z-index-*` | `z-*` | seven stacking layers |
| `--ease-*`, `--transition-duration-*` | `ease-*`, `duration-*` | motion curves and durations |
| `--font-*` | `font-*` | font families |
| `--spacing` | `p-*`, `m-*`, `gap-*`, `w-*`, `h-*` | the 4px grid (`0.25rem`) |

`--z-index-*` and `--transition-duration-*` are not in the docs table as of October 2026, but Tailwind 4.3 compiles them: our CSS has `.z-modal { z-index: var(--z-modal) }`.

#### How should you layer Tailwind v4 design tokens?

Use three layers. Raw values that change between themes go in `:root` and `.dark`. A mapping in `@theme inline` turns them into utilities. Components then paint through a few runtime variables that a prop sets, so a `tone` or a custom `color` never needs its own class.

Here is a trimmed but working excerpt of our `app/globals.css`, with the real values:

```css
@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.3211 0 0);
  --surface: #ffffff;
  --popover: oklch(1 0 0);
  --muted-foreground: oklch(0.52 0.0234 264.3637);
  --success: #15803d;
  --success-foreground: #ffffff;
  --success-soft: #e7f6ec;
  --success-soft-foreground: #166534;
  --elevation-raised: 0 0 0 1px rgb(0 0 0 / 0.07), 0 1px 2px rgb(0 0 0 / 0.05), 0 2px 8px -2px rgb(0 0 0 / 0.06);
}

.dark {
  --background: oklch(0 0 0);
  --foreground: oklch(0.9219 0 0);
  --surface: #1a1a1a;
  --popover: #262626;
  --muted-foreground: oklch(0.7155 0 0);
  --success-soft: #0d2315;
  --success-soft-foreground: #4ade80;
  --elevation-raised: inset 0 1px 0 0 rgb(255 255 255 / 0.06), 0 0 0 1px rgb(255 255 255 / 0.08), 0 1px 2px rgb(0 0 0 / 0.5);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-surface: var(--surface);
  --color-popover: var(--popover);
  --color-muted-foreground: var(--muted-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-success-soft: var(--success-soft);
  --color-success-soft-foreground: var(--success-soft-foreground);
  --shadow-raised: var(--elevation-raised);
}
```

The success fill and its white text are the same in both themes (5.02:1), so this excerpt declares them only in `:root` and `.dark` inherits them. Everything that changes is redeclared under `.dark`, and a component uses the same classes everywhere:

```tsx
export function InvoiceRow() {
  return (
    <div className="flex items-center justify-between rounded-2xl bg-surface p-4 text-foreground shadow-raised">
      <div>
        <p className="text-[15px] font-medium">Invoice 1042</p>
        <p className="text-sm text-muted-foreground">Emma Carter, New York</p>
      </div>
      <span className="rounded-full bg-success-soft px-2 py-0.5 text-xs font-medium text-success-soft-foreground">Paid</span>
    </div>
  );
}
```

The raw names follow shadcn/ui's convention on purpose: `--background`, `--card`, `--popover` and `--muted-foreground` are shadcn names, and the ones shadcn does not have (`--surface`, `--canvas`, the `--success-*` family) use the same `name` and `name-foreground` pattern. A project that already has shadcn tokens can take ours without renaming anything.

#### When do you need Tailwind v4 @theme inline?

Use `@theme inline` whenever a theme variable points at another variable, which is every token that changes with the theme. The [Tailwind docs](https://tailwindcss.com/docs/theme) say it directly: with `inline`, "the utility class will use the theme variable value instead of referencing the actual theme variable". Here is what that means in compiled CSS:

```css
/* @theme inline { --color-surface: var(--surface); } */
.bg-surface {
  background-color: var(--surface);
}

/* @theme { --color-surface: var(--surface); } */
:root, :host {
  --color-surface: var(--surface);
}
.bg-surface {
  background-color: var(--color-surface);
}
```

The difference shows up below the root. A custom property inherits its computed value, and `var()` is substituted where the property is declared. In the second version `--color-surface` is resolved once, on `:root`, and every element inherits that result. A `.dark` class on `<html>` still works, because `<html>` is the root. A dark section inside a light page (`<section className="dark">`), a dark preview pane or a `data-theme` attribute on a container does not: the section inherits the light value that `:root` already resolved. With `inline`, `bg-surface` reads `var(--surface)` on the element itself, so it picks up the nearest override. The Tailwind docs explain the option with the same kind of parent and child example.

One catch remains with `inline`: if you write `var(--color-surface)` yourself, in an arbitrary value like `bg-[var(--color-surface)]` or in plain CSS, Tailwind 4.3 emits `--color-surface: var(--surface)` on `:root` to satisfy it, and that reference is resolved on the root again. Inside components, read the raw variable instead: `bg-(--surface)` or `var(--surface)`.

Two more rules from the docs: theme variables must sit at the top level, never under a selector or a media query, so per-theme values live outside `@theme` anyway; and Tailwind only emits the theme variables your code uses, unless you write `@theme static`. The raw variables in `:root` always ship, which helps when a chart library reads a token with `getComputedStyle`.

#### Which semantic color tokens does a component library need?

Name colors by role, never by hue. A component library needs surfaces in the order they stack, text levels with a contrast floor, translucent tints for hover and fills, a border and a focus ring, and status tones. With semantic color tokens, components never contain `bg-gray-100` or `text-blue-600`, so a theme can change every value without touching a component.

##### Surfaces, back to front

| Token | Light | Dark | Use |
| --- | --- | --- | --- |
| `background` | `#FFFFFF` | `#000000` | the page |
| `canvas` | `#F6F7F9` | `#0E0E10` | the page of an app (dashboards, admin), under white panels |
| `card` | `#EBEBEB` | `#121212` | flat gray tiles with no shadow |
| `surface` | `#FFFFFF` with `shadow-raised` | `#1A1A1A` | raised panels: list groups, stat cards, forms |
| `popover` | `#FFFFFF` with `shadow-floating` | `#262626` | everything that floats: menus, selects, dialogs, sheets, toasts |
| `primary` | `#000000` | `#FAFAFA` | the neutral solid fill and tooltips |

In dark mode the surfaces get lighter as they come forward: `#000`, `#121212`, `#1A1A1A`, `#262626`. In light mode most of them are white, so the shadow does the separating. `canvas` exists because a dashboard on a white page has nothing to set white cards against; a cool gray page makes every `bg-surface` panel read as a card.

##### Text levels

| Level | Class | Use | Lowest ratio in our token pairs |
| --- | --- | --- | --- |
| Primary | `text-foreground` | titles, values, labels | 10.60:1 (light card) |
| Secondary | `text-muted-foreground` | descriptions, helper text, timestamps | 4.62:1 (light card) |
| Disabled | `text-foreground/45` | disabled labels only | none required |
| Tone text | `text-success-soft-foreground` and its siblings | errors, deltas, links | 5.28:1 (brand on the light card) |

`text-muted-foreground` is the floor for anything people must read. The disabled level has no contrast target because [WCAG 2.2 success criterion 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) exempts text in inactive controls, which is why it is never used for anything else.

##### Tints instead of gray fills

Hover states, field fills, chips, tracks and skeletons use translucent foreground: `bg-foreground/5`, `/7`, `/10` and `/15`, plus `border-foreground/10` for hairlines. Tailwind 4.3 compiles the opacity modifier to `color-mix()`, with the plain color as a fallback:

```css
.bg-foreground\/5 {
  background-color: var(--foreground);
  @supports (color: color-mix(in lab, red, red)) {
    background-color: color-mix(in oklab, var(--foreground) 5%, transparent);
  }
}
```

A tint is relative to whatever sits behind it, so it moves one step toward the text color on every surface, in both themes. A fixed fill cannot do that. Our dark `--muted` is `#171717`: lighter than the black page and darker than the `#1A1A1A` surface, so the same field would look raised on one and sunken on the other. The full-strength fallback only shows in browsers without `color-mix()`, which are all below Tailwind's [browser baseline](https://tailwindcss.com/docs/compatibility) of Chrome 111, Safari 16.4 and Firefox 128.

shadcn/ui's `secondary` and `accent` stay in our file so ported components keep working, but our `--accent` is an orange tint, and new components never use either.

#### How do status colors work without a class per color?

Give each status tone four tokens: a solid fill, the text on that fill, a soft tinted surface, and tone text that reads on the soft surface and on every neutral surface. Then let components paint through five generic variables that one class sets. That is the whole idea behind the free [Tones utility](https://wingo-ui.com/components/tones).

The four tokens per tone, for brand, success, warning, destructive and info:

```css
--success: #15803d;                 /* bg-success: buttons, solid badges, progress */
--success-foreground: #ffffff;      /* text on the fill */
--success-soft: #e7f6ec;            /* bg-success-soft: soft badges, alerts, selected rows */
--success-soft-foreground: #166534; /* colored text on the tint and on any neutral surface */
```

The split between fill and tone text is the easiest rule to skip, and it is where dark mode breaks. Fills are tuned to carry white text, and they make poor text. `text-destructive` (`#DC2626`) on our dark popover is 3.13:1; `text-destructive-soft-foreground` (`#FF8A80`) on the same surface is 6.63:1. The warning fill is amber (`#F5A524`) at 2.04:1 against white, so it carries dark text (`#2B1700`, 8.40:1) and is never used as text on a neutral surface.

##### Component variables

A component with a `tone` prop does not map tokens itself. `toneClasses[tone]` sets five variables, and every variant paints with them:

```ts
// lib/tones.ts (excerpt)
success:
  "[--tone:var(--success)] [--tone-foreground:var(--success-foreground)] [--tone-soft:var(--success-soft)] [--tone-soft-foreground:var(--success-soft-foreground)] [--tone-border:color-mix(in_oklab,var(--success)_45%,transparent)]",
```

The neutral tone maps `--tone` to `--primary` (black in light, near-white in dark) and builds its soft surface from `color-mix(in oklab, var(--foreground) 7%, transparent)`, which is why a neutral soft button works on any surface. A badge built this way:

```tsx
import type { ComponentProps } from "react";
import { colorVars, toneClasses, type Tone } from "@/lib/tones";
import { cn } from "@/lib/utils";

type StatusBadgeProps = ComponentProps<"span"> & { tone?: Tone; color?: string };

export function StatusBadge({ tone = "neutral", color, className, style, ...props }: StatusBadgeProps) {
  return (
    <span
      data-slot="status-badge"
      className={cn(
        toneClasses[tone],
        "inline-flex rounded-full bg-(--tone-soft) px-2 py-0.5 text-xs font-medium text-(--tone-soft-foreground)",
        className,
      )}
      style={{ ...colorVars(color), ...style }}
      {...props}
    />
  );
}
```

`bg-(--tone-soft)` is Tailwind v4's shorthand for `bg-[var(--tone-soft)]`. The free [Badge](https://wingo-ui.com/components/badge) is the full version of this pattern, with solid, soft and outline variants. `colorVars(color)` builds the same five variables from any CSS color as an inline style. Its text-on-fill value uses relative color syntax, `oklch(from <color> clamp(0, (0.7 - l) * 1000, 1) 0 0)`: white when the color's OKLCH lightness is below 0.7, black above. As of October 2026, [caniuse](https://caniuse.com/css-relative-colors) lists full support for relative color syntax from Chrome 131, Safari 18 and Firefox 133, and partial support before that, so full support arrived later than Tailwind's own baseline. Where a browser cannot compute the value, the declaration is invalid at computed-value time and the text inherits its parent's color. If you support those browsers, force the text color with `className="[--tone-foreground:white]"`.

> Live demo (Tones): Each row paints one tone three ways from the same five variables, and the last row is built by colorVars from one hex value, #0EA5E9. Switch the site theme: the solid fills stay, while the soft tints and the tone text take their dark values. Try it at [Tones](https://wingo-ui.com/components/tones) and install it with `npx wingo-ui@latest add tones`.

The free [Button](https://wingo-ui.com/components/button) is the reference consumer. Its variant map contains no color at all:

```ts
const VARIANTS: Record<ButtonVariant, string> = {
  solid: "bg-(--tone) text-(--tone-foreground) shadow-raised",
  soft: "bg-(--tone-soft) text-(--tone-soft-foreground)",
  outline: "border border-(--tone-border) text-(--tone-soft-foreground)",
  ghost: "text-(--tone-soft-foreground)",
  link: "rounded-[4px] text-(--tone-soft-foreground) underline decoration-current/35 decoration-1 underline-offset-4 transition-[color,text-decoration-color] hover:decoration-current",
};
```

Six tones times five variants, plus any custom color, from five lines. Hover and press are a layer of `currentColor` at 8% and 12% opacity, so they also work for every tone without extra classes.

#### How do you design dark mode with tokens?

Treat dark as a second set of values for the same roles, picked by hand, and switch it with a class. Components keep the same classes in both themes, so almost nothing in a component needs a `dark:` prefix.

The variant: our tokens, like shadcn/ui's, use `@custom-variant dark (&:is(.dark *));`. The [Tailwind dark mode docs](https://tailwindcss.com/docs/dark-mode) show `&:where(.dark, .dark *)`, which also matches the element that carries the class and adds no specificity. With the class on `<html>`, both behave the same for normal use. The class itself comes from [next-themes](https://github.com/pacocoursey/next-themes), which writes it before the first paint: wrap the app in its `ThemeProvider` with `attribute="class"` (the full provider file is in the props section below), and render `<html lang="en" suppressHydrationWarning>` in the root layout, because next-themes changes the class before React hydrates:

```tsx
// app/layout.tsx
import type { ReactNode } from "react";
import { Providers } from "./providers";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className="bg-background text-foreground">
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

What a designed dark theme looks like in practice, from our token file:

- **Surfaces lighten as they come forward.** `#000` page, `#121212` card, `#1A1A1A` surface, `#262626` popover.
- **Fills stay, soft surfaces flip.** The brand fill is `#D63F00` in both themes, so white text keeps 4.59:1. Its soft surface goes from `#FFEFE6` to `#2A1509`, and its text from `#B03400` to `#FF8A4C`.
- **The neutral fill inverts.** `primary` is black with white text in light mode and `#FAFAFA` with `#171717` in dark, so the neutral solid button keeps 21:1 in light and 17.16:1 in dark.
- **Elevation changes technique.** A drop shadow barely shows on black, so dark shadows lean on a lit top edge and a white hairline (see the elevation levels below).
- **The focus ring shifts.** `--ring` is `oklch(0.60 0.20 36.93)` in light and `oklch(0.6617 0.2215 36.93)` in dark, deeper on white so a 2px outline keeps 3:1 on white and on the gray card.
- **Some components need an exception.** Our soft [Card](https://wingo-ui.com/components/card) uses `bg-card` in light but `bg-foreground/7` in dark, because the dark `--card` is the same gray as a dark sidebar or stage and the card would vanish there. An inversion script never makes that call.

#### How do you check contrast for every token pair?

List the pairs that are meant to be used together, convert both colors to sRGB, compute the WCAG ratio in both themes, and fail the build below 4.5:1. WCAG asks for 4.5:1 for body text and 3:1 for large text ([1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)), and 3:1 for UI components and focus indicators against what is next to them ([1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)).

Our check covers 54 pairs per theme, 108 in total, and reports 0 below 4.5:1 as of release 1.7.0. The tightest pairs are `brand-foreground` on `brand` at 4.59:1 and `muted-foreground` on the light `card` at 4.62:1. Here is a self-contained version you can drop into `scripts/` and run with `npx tsx scripts/check-contrast.ts`. It reads hex and `oklch()` values (decimal or percent lightness), follows `var()` references and exits with code 1 on a failure. It expects the token names used in this guide; if yours differ, edit `SURFACES`, `TONES` and `PAIRS`:

```ts
// scripts/check-contrast.ts
import { readFileSync } from "node:fs";

type Rgb = [number, number, number];
const css = readFileSync("app/globals.css", "utf8").replace(/\/\*[\s\S]*?\*\//g, "");

// every --name: value inside the blocks that start with this selector
function vars(selector: string) {
  const map = new Map<string, string>();
  const block = new RegExp(`(?:^|\\n)${selector.replace(".", "\\.")}\\s*\\{([^}]*)\\}`, "g");
  for (const m of css.matchAll(block))
    for (const d of m[1].matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) map.set(d[1], d[2].trim());
  return map;
}

export function oklchToRgb(l: number, c: number, h: number): Rgb {
  const a = c * Math.cos((h * Math.PI) / 180);
  const b = c * Math.sin((h * Math.PI) / 180);
  const l3 = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
  const m3 = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
  const s3 = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
  const linear = [
    4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
    -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
    -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3,
  ];
  // clamp into srgb, then gamma-encode
  return linear.map((v) => {
    const x = Math.min(1, Math.max(0, v));
    return x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055;
  }) as Rgb;
}

function parse(value: string, map: Map<string, string>): Rgb {
  const ref = value.match(/^var\((--[\w-]+)\)$/);
  if (ref) return parse(map.get(ref[1]) ?? "", map);
  if (value.startsWith("#")) {
    const hex = value.length === 4 ? [...value.slice(1)].map((ch) => ch + ch).join("") : value.slice(1);
    return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255) as Rgb;
  }
  const ok = value.match(/^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)\s*\)$/);
  if (ok) return oklchToRgb(ok[2] ? +ok[1] / 100 : +ok[1], +ok[3], +ok[4]);
  throw new Error(`cannot parse "${value}"`);
}

const channel = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
const luminance = ([r, g, b]: Rgb) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);

export function contrast(fg: Rgb, bg: Rgb) {
  const [hi, lo] = [luminance(fg), luminance(bg)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}

const SURFACES = ["background", "card", "popover", "surface", "canvas"];
const TONES = ["brand", "success", "warning", "info", "destructive"];
const PAIRS = [
  ["foreground", "background"],
  ...SURFACES.map((s) => ["muted-foreground", s]),
  ...TONES.flatMap((t) => [
    [`${t}-foreground`, t],
    [`${t}-soft-foreground`, `${t}-soft`],
    ...SURFACES.map((s) => [`${t}-soft-foreground`, s]),
  ]),
];

const light = vars(":root");
const themes = { light, dark: new Map([...light, ...vars(".dark")]) };
let failures = 0;
for (const [theme, map] of Object.entries(themes)) {
  for (const [fg, bg] of PAIRS) {
    const ratio = contrast(parse(map.get(`--${fg}`) ?? "", map), parse(map.get(`--${bg}`) ?? "", map));
    if (ratio < 4.5) {
      failures++;
      console.log(`FAIL ${theme}: ${fg} on ${bg} is ${ratio.toFixed(2)}:1`);
    }
  }
}
console.log(`${PAIRS.length * 2} pairs checked, ${failures} below 4.5:1`);
process.exitCode = failures ? 1 : 0;
```

This trimmed version checks 82 pairs. Our full script adds the remaining surface, primary and legacy pairs and composites translucent values over the page first. The pair list is the valuable part: it encodes which text may sit on which surface, so a new token is checked the day it is added. Run it in CI next to the type check.

#### Should you write Tailwind v4 OKLCH values or hex?

Use whichever format you can reason about; the format does not change contrast. Tailwind's own palette moved "from `rgb` to `oklch`, taking advantage of the wider gamut" in v4.0 ([release post](https://tailwindcss.com/blog/tailwindcss-v4)), and its [colors reference](https://tailwindcss.com/docs/colors) lists every Tailwind v4 OKLCH value, such as `--color-red-500: oklch(63.7% 0.237 25.331)`. OKLCH earns its place when you derive colors in code, because lightness is its own channel: you can move it while hue and chroma stay put, and the result still looks like the same color.

In our file, neutrals are `oklch()` with zero chroma (`oklch(0.3211 0 0)` is the light foreground), and the tone values are hex, tuned by hand against the contrast check. The [theme generator](https://wingo-ui.com/theme) goes the other way: you pick a base color for each tone (brand, success, warning, danger, info), and it derives that tone's fill, soft surface and text in OKLCH. For light mode it puts the soft surface at lightness 0.965 with chroma capped at 0.035, then walks the tone text's lightness down from 0.6 in 0.005 steps until it reaches 4.6:1 on the soft surface and on every neutral surface. Move `oklchToRgb` and `contrast` from the contrast script into their own module, `scripts/color.ts`, so importing them does not run the check, and the same search is a few lines:

```ts
import { contrast, oklchToRgb } from "./color";

type Rgb = [number, number, number];

// keep hue and chroma, walk lightness until the color reads on every surface it can sit on
export function findReadable(c: number, h: number, surfaces: Rgb[], from: number, to: number, target = 4.6): Rgb {
  const step = from < to ? 0.005 : -0.005;
  for (let l = from; step > 0 ? l <= to : l >= to; l += step) {
    const rgb = oklchToRgb(l, c, h);
    if (Math.min(...surfaces.map((bg) => contrast(rgb, bg))) >= target) return rgb;
  }
  return oklchToRgb(to, c, h);
}
```

The target is 4.6 rather than 4.5 so rounding to hex cannot push a color under the line. One caution: a high-chroma OKLCH value can fall outside sRGB, and what a screen then shows depends on the display and the browser. Keep token values inside sRGB, or at least measure the clamped sRGB value, as `oklchToRgb` does.

#### How do radius, elevation, z-index and motion become tokens?

They become scales with a fixed set of steps, each with one job, so a component picks a step instead of a number. A Tailwind v4 design system that only tokenizes color still ends up with one-off shadows and a `z-[9999]` somewhere.

##### Radius follows size

Tie radius to the control's size. A 32px and a 48px button only read as the same shape when the larger one has the larger radius. Our controls copy this map from the Button:

```ts
type Scale = "sm" | "md" | "lg";
type ButtonRadius = "none" | "sm" | "md" | "lg" | "full";

const RADII: Record<ButtonRadius, Record<Scale, string>> = {
  none: { sm: "rounded-none", md: "rounded-none", lg: "rounded-none" },
  sm: { sm: "rounded-[6px]", md: "rounded-[8px]", lg: "rounded-[10px]" },
  md: { sm: "rounded-[8px]", md: "rounded-[10px]", lg: "rounded-[12px]" },
  lg: { sm: "rounded-[10px]", md: "rounded-[14px]", lg: "rounded-[16px]" },
  full: { sm: "rounded-full", md: "rounded-full", lg: "rounded-full" },
};
```

Surfaces use `rounded-2xl` (16px) for cards, menus and popovers, `rounded-3xl` (24px) for dialogs, and `rounded-t-[28px]` for bottom sheets. Anything inside a padded surface takes the outer radius minus the padding: a `rounded-2xl p-1.5` menu has `rounded-[10px]` items. Sizes follow the same thinking: 32, 40 and 48px, with the 40px size growing to 44px on touch screens, the rule from our [mobile-first React components guide](https://wingo-ui.com/blog/mobile-first-react-components).

The trap is a global radius token. Our file still carries shadcn/ui's older scale for ported components: `--radius: 0.375rem`, `--radius-lg: var(--radius)` and `--radius-sm: calc(var(--radius) - 4px)`. That remaps Tailwind's `rounded-sm`, `rounded-md`, `rounded-lg` and `rounded-xl` to 2, 4, 6 and 10px everywhere, including markup pasted from Tailwind's docs (the compiled `.rounded-lg` is `border-radius: var(--radius)`), so new components never use those four classes. As of October 2026, [shadcn/ui's theming docs](https://ui.shadcn.com/docs/theming) derive the scale by multiplication instead (`--radius-sm: calc(var(--radius) * 0.6)` up to `--radius-4xl`), which has the same project-wide reach. If you theme radius globally, own every component that uses it.

##### Three elevation levels

Three levels cover a library: `shadow-raised` for buttons, cards and thumbs, `shadow-floating` for popovers, menus and toasts, `shadow-modal` for dialogs and sheets. Each level carries its own 1px hairline, so an elevated surface needs no border:

```css
:root {
  --elevation-floating: 0 0 0 1px rgb(0 0 0 / 0.06), 0 4px 12px -2px rgb(0 0 0 / 0.08), 0 16px 36px -10px rgb(0 0 0 / 0.16);
}
.dark {
  /* on a black page a drop shadow barely shows: a lit top edge and a hairline do the work */
  --elevation-floating: inset 0 1px 0 0 rgb(255 255 255 / 0.07), 0 0 0 1px rgb(255 255 255 / 0.09), 0 8px 24px -4px rgb(0 0 0 / 0.6), 0 20px 48px -12px rgb(0 0 0 / 0.7);
}
@theme inline {
  --shadow-floating: var(--elevation-floating);
}
```

An interactive Card moves between two of these levels on hover, and the lift runs as a CSS transition on a spring curve (below), so a grid of fifty cards animates without JavaScript.

> Live demo (Card): Hover the card to see it lift from shadow-raised to shadow-floating, then press it to see the dip to 98% (phones get only the press). Switch the site theme to see the dark elevation draw a lit top edge instead. Try it at [Card](https://wingo-ui.com/components/card) and install it with `npx wingo-ui@latest add card`.

##### Stacking layers

| Class | Value | Use |
| --- | --- | --- |
| `z-dropdown` | 1000 | in-flow panels that are not portaled |
| `z-sticky` | 1100 | sticky headers, tab bars, CTA bars |
| `z-overlay` | 1200 | the dimmed backdrop |
| `z-modal` | 1300 | dialogs, sheets, drawers |
| `z-popover` | 1400 | portaled menus, selects, popovers |
| `z-toast` | 1500 | toasts |
| `z-tooltip` | 1600 | tooltips, always on top |

Popovers sit above modals on purpose: a select inside a dialog has to open over it. No overlay in the library uses a raw number like `z-50`; small values such as `z-10` only order parts inside one component.

##### Motion

CSS transitions use three durations (`duration-fast` 150ms, `duration-normal` 240ms, `duration-slow` 400ms) and named curves (`ease-smooth` is `cubic-bezier(0.22, 1, 0.36, 1)`, `ease-sheet` is `cubic-bezier(0.32, 0.72, 0, 1)`). Our JavaScript springs are also sampled into CSS `linear()` easings: `ease-spring` with `duration-spring` (500ms) matches a spring with stiffness 300 and damping 30.

#### Can component props work like design tokens?

Yes, for the decisions that are props: the radius of every button, the default size of fields, the variant of every card. CSS variables cannot set a prop, so Wingo UI reads those from a React provider, and `UIProvider defaults` works as a token layer for props. The free [UIProvider](https://wingo-ui.com/components/ui-config) merges app-wide defaults under the props each component receives, keyed by its `data-slot` name:

```tsx
// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { ThemeProvider } from "next-themes";
import { UIProvider } from "@/lib/ui-config";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
      <UIProvider locale="en-US" defaults={{ button: { radius: "full" }, card: { variant: "outline" } }}>
        {children}
      </UIProvider>
    </ThemeProvider>
  );
}
```

Inside a component, the first line reads the defaults, and the signature defaults stay the last fallback:

```tsx
export function Button(buttonProps: ButtonProps) {
  const { variant = "solid", tone = "neutral", size = "md", radius = "md", ...rest } = useDefaults("button", buttonProps);
  // ...
}
```

Explicit props win, then the provider, then the component's own defaults. An `undefined` prop does not override a provider value, so wrappers can pass props through without erasing the theme. The same signature takes `ref` as a regular prop, with no `forwardRef` wrapper; our [React 19 forwardRef migration guide](https://wingo-ui.com/blog/react-19-forwardref-ref-as-prop) moves older components to that pattern, TypeScript types included.

> Live demo (UIProvider): The first button uses its built-in defaults; the two below get radius full, size lg and tone brand from a UIProvider, and the outline one keeps the variant it passes itself. Try it at [UIProvider](https://wingo-ui.com/components/ui-config) and install it with `npx wingo-ui@latest add ui-config`.

#### How do you add these tokens to an existing Next.js project?

Run `npx wingo-ui@latest init` in a project that has Tailwind CSS v4. It writes `wingo-ui.json` and `lib/utils.ts` (the `cn` helper), installs `clsx` and `tailwind-merge`, and merges the tokens into the stylesheet that contains `@import "tailwindcss"`. It only adds missing names and keeps your values; `add` later brings any tokens a new component needs. The full block, 74 variables in `:root` plus their dark values and Tailwind mappings, is served at `/r/tokens.css`, and coding agents get the same CSS from the MCP tool `get_theme_tokens` (see our [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide)). The [theming docs](https://wingo-ui.com/docs/theming) show the main tokens with their light and dark values, and the two dark mode setups the CLI supports: a `.dark` class, or `prefers-color-scheme` when your stylesheet already uses it.

To restyle, open the [theme generator](https://wingo-ui.com/theme), pick a brand color, neutrals, radius, font and component defaults, check its contrast report, and apply the export:

```bash
npx wingo-ui@latest theme apply ./theme.json
```

It replaces the values of the tokens the theme sets, in light and dark, adds Tailwind mappings for new ones and prints the `UIProvider` defaults and locale to paste into your provider.

Coming from shadcn/ui: the shared names line up, but two keep different meanings. Our `--card` is a flat gray tile where shadcn's is the card background, and our `--accent` is an orange tint. Because `init` keeps your existing values, a shadcn project keeps its own `--card` and `--accent`, so check the soft Card variant after the merge. Our [shadcn alternatives comparison](https://wingo-ui.com/blog/shadcn-alternatives) covers the wider differences between the two libraries.

#### Which mistakes break a Tailwind v4 design system?

The same few mistakes show up in most token files:

- **`dark:` classes in components.** A component that needs `dark:bg-zinc-900` is missing a token.
- **Palette names in components.** `bg-blue-600` cannot follow a theme; use a role or a tone.
- **Fill colors as text.** `text-destructive` on a dark surface fails AA; use the soft foreground.
- **Per-theme values in plain `@theme`.** Keep them in `:root` and `.dark`, mapped with `inline`.
- **A global radius that rewrites Tailwind's scale.** Every pasted `rounded-lg` changes with it.
- **Raw z-index numbers.** Two `z-50` overlays from two authors will collide.
- **No contrast check.** Tokens drift with every tweak; a check in CI catches it the same day.

#### Where should you start?

Run `npx wingo-ui@latest init` in your Next.js project, then `npx wingo-ui@latest add button`, which brings the Tones and UIProvider items with it. Replace one hard-coded color in a real screen with a role token, open it in both themes, and add the contrast script to CI. Two more guides in [Next.js and Tailwind CSS](https://wingo-ui.com/blog/category/nextjs-tailwind) cover the component code around the tokens: the [React 19 forwardRef migration](https://wingo-ui.com/blog/react-19-forwardref-ref-as-prop) and an [SSR-safe React use mobile hook](https://wingo-ui.com/blog/react-use-mobile-hook-ssr) that hydrates without a mismatch.

#### Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Tones](https://wingo-ui.com/components/tones) (Free): One way to color a component: a tone or any CSS color becomes five CSS variables every variant paints with. Install: `npx wingo-ui@latest add tones`
- [UIProvider](https://wingo-ui.com/components/ui-config) (Free): App-wide configuration for Wingo UI: default props for every component, the Intl locale and the reduced-motion policy. Install: `npx wingo-ui@latest add ui-config`
- [Card](https://wingo-ui.com/components/card) (Free): The surface listings, stats, settings and plans sit on: media, header, body and footer parts, four variants and a lift-and-press mode. Install: `npx wingo-ui@latest add card`
- [Badge](https://wingo-ui.com/components/badge) (Free): Status chips, removable filters and animated counts in three variants and six tones, plus an anchor that pins a count or dot to any corner. Install: `npx wingo-ui@latest add badge`

#### FAQ

##### Where do design tokens go in Tailwind v4?

In the global CSS file, after @import "tailwindcss". Variables in an @theme block become utilities (--color-surface gives bg-surface), and values that change per theme live in :root and .dark and are mapped with @theme inline. A tailwind.config.js file is no longer required.

##### What is the difference between @theme and @theme inline in Tailwind v4?

With @theme, the utility references the theme variable, so bg-surface compiles to var(--color-surface), which is resolved once on :root. With @theme inline, the utility gets the referenced value written in, so bg-surface compiles to var(--surface) and resolves on the element that uses it. Use inline whenever a theme variable points at another variable.

##### Should Tailwind v4 colors be OKLCH or hex?

Either works, because tokens are plain CSS colors and the format does not change contrast. Tailwind's own palette moved to oklch in v4.0. OKLCH helps most when you derive colors in code, since you can keep hue and chroma and move lightness until a contrast target passes.

##### How do I add dark mode to Tailwind v4 design tokens?

Redefine the same variables in a .dark block and add @custom-variant dark (&:is(.dark *)); so dark: utilities follow the class too. next-themes with attribute="class" sets the class before the first paint. Components that use semantic tokens then need no dark: classes.

##### How do I check color contrast for design tokens?

List every text token with each surface it can sit on, convert the values to sRGB, and compute the WCAG ratio for light and dark. Fail the build below 4.5:1 for body text; focus rings and other UI shapes need 3:1.

##### Are the Wingo UI design tokens free?

Yes. npx wingo-ui@latest init merges the tokens into your stylesheet without an account, and the Button, Card, Tones and UIProvider items in this guide are free. As of release 1.7.0, 75 of the 326 registry items are free and the rest need Pro.

---

Source: https://wingo-ui.com/blog/tailwind-v4-design-tokens

### TanStack Table v9 Data Table: Filters, Bulk Actions, Mobile

> Build an admin data table on TanStack Table v9: tableFeatures setup, column filters, bulk actions, start and end pinning, server pagination and phone cards.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Component guides](https://wingo-ui.com/blog/category/components)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/tanstack-table-v9-data-table

#### TL;DR

A TanStack Table v9 data table starts with tableFeatures: you register sorting, filtering, pagination, pinning and selection once at module scope and pass them to useTable, which replaces useReactTable. For server pagination you set manualPagination, manualSorting and manualFiltering with a rowCount from your API, and column pinning now uses start and end instead of left and right. The library gives you state and row models only; the filter UI, the bulk bar and a phone layout are still yours to build or install.

TanStack Table v9 went stable in August 2026, and many data table tutorials still show the v8 API: `useReactTable`, `getCoreRowModel()` and `columnPinning.left`. Copy one into a v9 project and the import fails, because `useReactTable` is gone; switch to `useTable` and nothing sorts until you register the sorting feature. This tutorial builds an admin data table on TanStack Table v9: column filters, bulk actions on selected rows, pinned columns and server pagination, plus the card layout it should switch to on a phone. The first half is plain TanStack, so it works with any markup. The second half uses the Wingo UI [Data Table](https://wingo-ui.com/components/data-table), which we build, so weigh our opinions accordingly.

#### What changed in TanStack Table v9 for a data table?

Features became explicit. You declare sorting, filtering, pagination, pinning and selection in a `tableFeatures()` object, and the row model factories live in that object instead of in the table options. The renames that touch a data table, from the [React migration guide](https://tanstack.com/table/latest/docs/framework/react/guide/migrating) as of October 2026:

| v8 | v9 |
| --- | --- |
| `useReactTable(options)` | `useTable(options, selector?)` with a required `features` option |
| `getCoreRowModel: getCoreRowModel()` | automatic |
| `getSortedRowModel: getSortedRowModel()` | `sortedRowModel: createSortedRowModel()` inside `tableFeatures` |
| `columnPinning: { left, right }`, `column.pin("left")` | `columnPinning: { start, end }`, `column.pin("start")` |
| `sortingFn`, `sortingFns` | `sortFn`, `sortFns` |
| `table.getState()` | `table.state`, or `table.Subscribe` for one slice |
| `createColumnHelper<Person>()` | `createColumnHelper<typeof features, Person>()` |

Three behavior changes bite during a migration. In 9.2.4, `row.getVisibleCells()` comes from `columnVisibilityFeature`, so a table without it has only `getAllCells()`, which ignores pinning order. `getIsSomeRowsSelected()` returns true when every row is selected, so an indeterminate header checkbox needs `getIsSomeRowsSelected() && !getIsAllRowsSelected()`. And `row.getToggleSelectedHandler()` selects a range on Shift-click by default (`enableRowRangeSelection: false` turns it off).

The [v9 announcement](https://tanstack.com/blog/announcing-tanstack-table-v9) (August 4, 2026) says the whole package grew from 14kb to 25kb, and that features you do not register stay out of the bundle. Register what the table uses and nothing else.

#### How do you set up TanStack Table v9 with filters, selection and pinning?

Build the features object and the columns once at module scope, then call `useTable` with the data. TanStack's docs ask for stable `features`, `columns` and `data`, and a fresh `data` array on every render invalidates every row model built from it. Here is a complete TanStack Table v9 example for a clients list:

```tsx
// clients-grid.tsx
"use client";

import type { CSSProperties } from "react";
import {
  columnFilteringFeature, columnPinningFeature, columnSizingFeature, columnVisibilityFeature,
  createColumnHelper, createFilteredRowModel, createPaginatedRowModel, createSortedRowModel,
  filterFn_arrIncludesSome, filterFn_includesString, rowPaginationFeature, rowSelectionFeature,
  rowSortingFeature, sortFn_alphanumeric, sortFn_basic, tableFeatures, useTable, type Column,
} from "@tanstack/react-table";

export type Client = { id: string; name: string; city: string; status: string; balance: number };

const features = tableFeatures({
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  sortFns: { alphanumeric: sortFn_alphanumeric, basic: sortFn_basic },
  columnFilteringFeature,
  filteredRowModel: createFilteredRowModel(),
  filterFns: { includesString: filterFn_includesString, arrIncludesSome: filterFn_arrIncludesSome },
  rowPaginationFeature,
  paginatedRowModel: createPaginatedRowModel(),
  columnSizingFeature,
  columnPinningFeature,
  columnVisibilityFeature,
  rowSelectionFeature,
});

const helper = createColumnHelper<typeof features, Client>();
const columns = helper.columns([
  helper.display({
    id: "select",
    size: 40,
    header: ({ table }) => (
      <input
        type="checkbox"
        aria-label="Select page"
        checked={table.getIsAllPageRowsSelected()}
        // v9: "some" stays true when all are selected
        ref={(el) => {
          if (el) el.indeterminate = table.getIsSomePageRowsSelected() && !table.getIsAllPageRowsSelected();
        }}
        onChange={table.getToggleAllPageRowsSelectedHandler()}
      />
    ),
    cell: ({ row }) => (
      <input type="checkbox" aria-label="Select row" checked={row.getIsSelected()} onChange={row.getToggleSelectedHandler()} />
    ),
  }),
  helper.accessor("name", { header: "Client", size: 220, filterFn: "includesString", sortFn: "alphanumeric" }),
  helper.accessor("city", { header: "City", filterFn: "arrIncludesSome" }),
  helper.accessor("status", { header: "Status", filterFn: "arrIncludesSome" }),
  helper.accessor("balance", { header: "Balance", sortFn: "basic" }),
]);

// fixed widths keep the sticky offsets true; pinned cells need a background
function cellStyle(column: Column<typeof features, Client, unknown>): CSSProperties {
  const width = column.getSize();
  const side = column.getIsPinned();
  if (side === "start") return { width, position: "sticky", insetInlineStart: column.getStart("start"), zIndex: 1, background: "Canvas" };
  if (side === "end") return { width, position: "sticky", insetInlineEnd: column.getAfter("end"), zIndex: 1, background: "Canvas" };
  return { width };
}

export function ClientsGrid({ data }: { data: Client[] }) {
  const table = useTable({
    features,
    columns,
    data,
    getRowId: (row) => row.id,
    initialState: { columnPinning: { start: ["select", "name"], end: [] } },
  });

  return (
    <div style={{ overflowX: "auto" }}>
      <table style={{ tableLayout: "fixed", width: table.getTotalSize() }}>
        <thead>
          {table.getHeaderGroups().map((group) => (
            <tr key={group.id}>
              {group.headers.map((header) => (
                <th key={header.id} style={cellStyle(header.column)}>
                  {header.column.getCanSort() ? (
                    <button type="button" onClick={header.column.getToggleSortingHandler()}>
                      <table.FlexRender header={header} />
                    </button>
                  ) : (
                    <table.FlexRender header={header} />
                  )}
                </th>
              ))}
            </tr>
          ))}
        </thead>
        <tbody>
          {table.getRowModel().rows.map((row) => (
            <tr key={row.id}>
              {row.getVisibleCells().map((cell) => (
                <td key={cell.id} style={cellStyle(cell.column)}>
                  <table.FlexRender cell={cell} />
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}
```

The fixed layout and the widths matter. `getStart("start")` returns 40 for the name column, the select column's `size`, so the browser has to draw that column 40px wide, or the pinned name column sticks with a gap in front of it. `Canvas` is the page background in the active color scheme; swap in your own token.

The filter functions are registered by name, so `filterFn: "arrIncludesSome"` is type-checked against the registry. Filtering and bulk work go through the same instance:

```ts
table.getColumn("status")?.setFilterValue(["Overdue"]);
const ids = table.getSelectedRowModel().rows.map((row) => row.original.id);
```

That is the whole job of the library: state, row models and handlers. Everything a person sees is still missing: a search box, filter menus with checkboxes and ranges, chips for the applied filters, a bar that swaps in when rows are selected, keyboard navigation between rows and a layout for 390px screens. If you started from the shadcn data table guide, [it is written for TanStack Table v9](https://ui.shadcn.com/docs/components/data-table) as of October 2026 and adds sorting, a text filter, column visibility, client pagination, a row actions menu and a selected-row count. Server pagination, pinning, bulk actions and a phone layout are not in it.

#### How do you get filters, bulk actions and pinning without building the UI?

Install a component that builds the same kind of TanStack table and renders those parts. Our [Data Table](https://wingo-ui.com/components/data-table) runs on TanStack Table v9 with its features registered once at module scope, and takes plain column objects:

```bash
npx wingo-ui@latest login   # once, with a Pro account
npx wingo-ui@latest add data-table
```

```tsx
// clients-table.tsx
"use client";

import { useState } from "react";
import { useRouter } from "next/navigation";
import { Archive, Download, Pencil, Plus, Trash2 } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";
// your server actions; each takes the selected ids
import { archiveClients, deleteClients, exportClients } from "./actions";

export type Client = {
  id: string;
  name: string;
  taxId: string;
  city: string;
  status: "Active" | "Overdue" | "Prospect";
  owner: string;
  balance: number;
  lastInvoice: string | null;
};

const col = createColumns<Client>();
export const columns = col([
  col.accessor("name", { header: "Client", filter: "text", pinned: "left", mobile: "title" }),
  col.accessor("city", { header: "City", filter: "multi-select", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" }, Prospect: { tone: "info" } },
    filter: "multi-select",
    mobile: "meta",
  }),
  col.accessor("owner", { header: "Owner", type: "avatar", filter: "select" }),
  col.accessor("balance", { header: "Balance", type: "currency", footer: "sum", filter: "number-range" }),
  col.accessor("lastInvoice", { header: "Last invoice", type: "relative", filter: "date-range" }),
  // hidden by default, still found by the search
  col.accessor("taxId", { header: "Tax ID", searchable: true, mobile: "hidden" }),
]);

export function ClientsTable({ clients }: { clients: Client[] }) {
  const router = useRouter();
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <DataTable
      data={clients}
      columns={columns}
      caption="Clients"
      locale="en-US"
      searchPlaceholder="Search by name, tax ID or city"
      defaultColumnVisibility={{ taxId: false }}
      quickFilters={[
        { id: "overdue", label: "Overdue", columnFilter: { id: "status", value: ["Overdue"] } },
        { id: "big", label: "Over $10k", filter: (row) => row.balance > 10_000 },
      ]}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectedKeysChange={setSelected}
      bulkActions={(_rows, keys) => [
        { label: "Export", icon: <Download />, onSelect: () => exportClients(keys) },
        { label: "Archive", icon: <Archive />, onSelect: () => archiveClients(keys).then(() => setSelected([])) },
        { label: "Delete", icon: <Trash2 />, tone: "danger", onSelect: () => deleteClients(keys).then(() => setSelected([])) },
      ]}
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, href: `/clients/${row.id}` }]}
      toolbarActions={[{ label: "New client", icon: <Plus />, primary: true, onSelect: () => router.push("/clients/new") }]}
      persistKey="clients"
    />
  );
}
```

`createColumns<Client>()` checks every accessor key against the row type, and `pinned: "left"` becomes `columnPinning.start` in the TanStack state. Each header's menu can also pin, move or hide a column at runtime, and `persistKey` remembers visibility, order, widths, density and page size in local storage. The `rowActions` menu gets a ⋯ column pinned to the end, the same menu on right-click, and Shift+F10 on a focused row.

> Live demo (Data Table): Select a few rows and the toolbar turns into the bulk bar; open a header's chevron to filter or pin that column, or press the Overdue chip. Below 768px each row is a card: long press one to start selecting. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

##### Which filter fits which column?

Pick the filter by the question people ask of the column, and know the value shape, because a server has to parse it. These React data table filters, with the values `onColumnFiltersChange` and the server query carry:

| `filter` | Use it for | Value |
| --- | --- | --- |
| `text` | names, emails, ids | `"cafe"` |
| `select` | one owner, one plan | `"Emma Carter"` |
| `multi-select` | statuses, cities, tags | `["Active", "Overdue"]` |
| `number-range` | balances, quantities | `[1000, null]` (either end may be null) |
| `date-range` | invoice dates, sign-ups | `{ from, to }`, each a `Date` or null (ISO strings once JSON-encoded) |

In client mode the select filters list the column's unique values with counts, and the search box matches every word across the searchable columns, accents and formatted values included: "cafe" finds Café and "12480" finds $12,480.00. Quick filters are chips for the two or three questions someone asks every morning. A chip with a `columnFilter` works in both modes; a chip with a `filter` function runs in the browser only.

#### How should bulk actions work across pages?

Act on the ids, not on the row objects. `bulkActions` receives `(rows, keys)`: `keys` holds every selected id, including rows on other pages or hidden by a filter, while `rows` only holds the selected rows present in `data`. In server mode that is the current page, so an export built from `rows` silently drops everything selected on page 1 once you are on page 3.

While rows are selected the [Toolbar](https://wingo-ui.com/components/toolbar) switches to its bulk mode: an inline band on desktop, a floating bar on phones. The rest follows Gmail. Selecting a whole page in client mode shows a banner that offers every matching row, and rows that a new filter hides stay selected, with the banner saying how many. Shift-click selects a range, Ctrl or Cmd + A does what the header checkbox does, Escape clears. A bulk action that returns a promise shows its button loading until it settles, and a `danger` tone stays red, the floating phone bar included. For "Delete 240 clients" we still open an [Alert Dialog](https://wingo-ui.com/components/alert-dialog) from `onSelect`: a bulk delete deserves one more tap.

Clear the selection after an action removes rows. The table never drops a selected id on its own, since a missing id may sit on another page, so after a delete the bar would still count rows that no longer exist. That is why the example above controls `selectedKeys`.

#### How do you set up server-side pagination in TanStack Table?

Tell the table the server owns the work, give it the total, and fetch whenever the state changes. TanStack Table server side pagination in v9 is three flags and a count, and the row model factories can go, because the browser never sorts or slices:

```ts
const serverFeatures = tableFeatures({ rowSortingFeature, columnFilteringFeature, rowPaginationFeature });
// columns come from createColumnHelper<typeof serverFeatures, Client>()
const NO_ROWS: Client[] = [];

// in the component: result is your fetch for { pagination, sorting, columnFilters }
const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize: 25 });
const [sorting, setSorting] = useState<SortingState>([]);
const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
const table = useTable({
  features: serverFeatures,
  columns,
  data: result.data?.rows ?? NO_ROWS,
  rowCount: result.data?.total,
  state: { pagination, sorting, columnFilters },
  onPaginationChange: setPagination,
  onSortingChange: setSorting,
  onColumnFiltersChange: setColumnFilters,
  manualPagination: true,
  manualSorting: true,
  manualFiltering: true,
});
```

The Data Table folds that wiring into `mode="server"`: `data` is the current page, `rowCount` the total, and every change arrives in `onQueryChange` as one object with `page`, `pageSize`, `sorting`, `globalFilter` and `columnFilters`. That object is a ready-made query key for TanStack Query:

```tsx
// server-clients-table.tsx
"use client";

import { useState } from "react";
import { keepPreviousData, useQuery } from "@tanstack/react-query";
import { Trash2 } from "lucide-react";
import { DataTable, type DataTableQuery } from "@/components/ui/data-table";
import { deleteClients } from "./actions";
import { columns, type Client } from "./clients-table";

// must match the table's defaults: the first render does not call onQueryChange
const FIRST: DataTableQuery = { page: 1, pageSize: 25, sorting: [], globalFilter: "", columnFilters: [] };
const NO_ROWS: Client[] = [];

async function fetchClients(query: DataTableQuery): Promise<{ rows: Client[]; total: number }> {
  const res = await fetch(`/api/clients?q=${encodeURIComponent(JSON.stringify(query))}`);
  if (!res.ok) throw new Error(`Clients failed with ${res.status}`);
  return res.json();
}

export function ServerClientsTable() {
  const [query, setQuery] = useState(FIRST);
  const [selected, setSelected] = useState<string[]>([]);
  const { data, isPending, isFetching, error, refetch } = useQuery({
    queryKey: ["clients", query],
    queryFn: () => fetchClients(query),
    placeholderData: keepPreviousData,
  });

  return (
    <DataTable
      mode="server"
      data={data?.rows ?? NO_ROWS}
      rowCount={data?.total ?? 0}
      columns={columns}
      onQueryChange={setQuery}
      loading={isPending}
      refreshing={isFetching && !isPending}
      error={error ? "Clients could not load." : undefined}
      onRetry={() => refetch()}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectedKeysChange={setSelected}
      bulkActions={(_rows, keys) => [
        {
          label: "Delete",
          icon: <Trash2 />,
          tone: "danger",
          onSelect: async () => {
            await deleteClients(keys);
            setSelected([]);
            await refetch();
          },
        },
      ]}
      caption="Clients"
      locale="en-US"
    />
  );
}
```

`keepPreviousData` keeps the last page on screen while the next one loads, and `refreshing` slides a thin bar along the top edge instead of swapping the rows for skeletons. The search arrives debounced (300ms), and the page goes back to 1 when the search, a filter or the sort changes.

The route handler treats the query as untrusted input. Sort ids and page sizes come from a whitelist, and each filter id maps to a clause you wrote:

```ts
// app/api/clients/route.ts
import type { NextRequest } from "next/server";
import type { DataTableQuery } from "@/components/ui/data-table";
import { findClients } from "@/server/clients";

const SORTABLE = new Set(["name", "city", "status", "owner", "balance", "lastInvoice"]);
const PAGE_SIZES = [10, 25, 50, 100];

export async function GET(request: NextRequest) {
  let raw: Partial<DataTableQuery> = {};
  try {
    raw = JSON.parse(request.nextUrl.searchParams.get("q") ?? "{}");
  } catch {}
  const pageSize = PAGE_SIZES.includes(Number(raw.pageSize)) ? Number(raw.pageSize) : 25;
  const page = Math.max(1, Math.floor(Number(raw.page)) || 1);
  const first = (Array.isArray(raw.sorting) ? raw.sorting : []).find((s) => SORTABLE.has(s?.id));
  const sort = first ? { id: first.id, desc: first.desc === true } : undefined;
  // findClients checks the session and maps each filter id to a known SQL clause
  const { rows, total } = await findClients({
    offset: (page - 1) * pageSize,
    limit: pageSize,
    sort,
    search: String(raw.globalFilter ?? "").slice(0, 100),
    filters: Array.isArray(raw.columnFilters) ? raw.columnFilters : [],
  });
  return Response.json({ rows, total });
}
```

Two server-mode details. The table has no faceted values without the full data, so a select filter lists only its `filterOptions`, or the badge map's keys on a badge column: `status` works as is, while `city` and `owner` need an explicit `filterOptions` list (a `select distinct` on the server, for example). And quick filters need a `columnFilter`, since a `filter` function never reaches the server. If the page, sort and filters should live in the URL so a link reopens the same view, the [Next.js admin dashboard tutorial](https://wingo-ui.com/blog/nextjs-admin-dashboard-tutorial) does that with `router.replace` and a server component.

> Live demo (Data Table): Sort, search, or select rows on page 1 and then on page 2 (long press a card on a phone): the query object the server receives is printed under the table, and the selection count keeps the rows from both pages. Try it at [Data Table](https://wingo-ui.com/components/data-table) and install it with `npx wingo-ui@latest add data-table`.

Server mode has a cost: every pause in typing is a request. When one request can load every row a user may see, client mode filters instantly and needs no query API. We switch past a few thousand rows, or when permissions decide which rows exist for a user.

#### What should a data table look like on a phone?

A card per row. Eight columns on a 390px screen show about two at a time, and the header that names them scrolls out of sight. Below 768px the Data Table renders each row as a card, built from the same `mobile` roles you saw in the columns:

- `title` is the card heading (by default the first column), `subtitle` the line under it.
- `meta` sits in the top corner (by default the first badge or the last number column).
- Up to four `field` columns show as label and value pairs; `hidden` keeps a column off the card.

Long press a card to start selecting, then tap to add more, and the bulk bar floats at the bottom of the screen. Sort, filters and the row menu open as bottom sheets, and client mode appends rows with Load more while server mode keeps a compact [Pagination](https://wingo-ui.com/components/pagination) pager. The switch is a CSS breakpoint, so the server HTML already has the right layout before hydration and nothing jumps. `renderCard` replaces the mapping with your own card, and `mobileLayout="scroll"` keeps the table scrolling sideways for the rare grid that people compare column by column. The reasoning behind those defaults, with 44px touch targets and bottom sheets, is in [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components). How to pick the columns for a card, and the same layout on a plain shadcn/ui table, are in [responsive tables on mobile](https://wingo-ui.com/blog/responsive-table-mobile-cards).

For small read-only tables, such as invoice lines or a price list, the plain [Table](https://wingo-ui.com/components/table) does the same card switch without TanStack, selection or a toolbar.

#### Should you build on TanStack directly or use a component?

Build directly when the table is one of a kind or when your design system already has the menus and sheets; use a component when you need the same admin table on twenty screens. The options we would consider, as of October 2026:

| Option | License and price | Server mode | Bulk actions | Pinning | Phone layout |
| --- | --- | --- | --- | --- | --- |
| [TanStack Table v9](https://tanstack.com/table/latest) alone | MIT, free | State only | State only | State only | Yours |
| [shadcn data table guide](https://ui.shadcn.com/docs/components/data-table) | MIT, free | Linked to TanStack docs | Selected-row count | No | No |
| [tablecn](https://github.com/sadmann7/tablecn) | MIT, free | Yes, with Drizzle and PostgreSQL | Action bar on selection | Not listed | Not listed |
| Wingo UI Data Table | Pro: $8 a month, $80 a year or $150 lifetime | Yes (`mode="server"`) | Yes, floating on phones | Yes, plus header menu | Cards below 768px |

If you want Notion-style advanced filters over a Postgres table, tablecn is the better free starting point. If you only need sorting, one text filter and client pagination, the shadcn guide is enough. The Data Table, with the Table, Pagination and Toolbar it builds on, is part of [Wingo UI Pro](https://wingo-ui.com/pricing).

#### What should you build next?

Open the playground on the [Data Table docs](https://wingo-ui.com/components/data-table), switch `mode` to server and watch the query object change as you sort and filter, then install it with `npx wingo-ui@latest add data-table` after a one-time [CLI login](https://wingo-ui.com/docs/cli). Other tables in the library, from the members table to the editable grid, are listed under [tables](https://wingo-ui.com/components/category/tables), and more component tutorials live in the [component guides](https://wingo-ui.com/blog/category/components) category, starting with the [React form components guide](https://wingo-ui.com/blog/react-form-components-guide) for the filter forms around your tables.

#### Components in this post

- [Data Table](https://wingo-ui.com/components/data-table) (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: `npx wingo-ui@latest add data-table`
- [Table](https://wingo-ui.com/components/table) (Pro): The library's one table look: semantic table parts plus a props API for small read-only tables that turn into cards on phones. Install: `npx wingo-ui@latest add table`
- [Pagination](https://wingo-ui.com/components/pagination) (Pro): Pages for tables and lists: numbers with ellipses, previous / next, page size, jump to page, a compact phone pager and load more. Install: `npx wingo-ui@latest add pagination`
- [Toolbar](https://wingo-ui.com/components/toolbar) (Pro): The bar above a list or table: search, filter chips, applied filters, sort, a list / grid switch, the count, actions and a bulk mode. Install: `npx wingo-ui@latest add toolbar`

#### FAQ

##### What replaced useReactTable in TanStack Table v9?

useTable, which takes a required features option built with tableFeatures(). Row models such as sorting and pagination moved into that features object as factories (sortedRowModel: createSortedRowModel()), and useLegacyTable from @tanstack/react-table/legacy keeps the v8 API as a deprecated migration aid.

##### How do I do server-side pagination in TanStack Table v9?

Set manualPagination: true, pass the total as rowCount, control the pagination state and fetch the page your API returns for it. Add manualSorting and manualFiltering when the server also sorts and filters, and leave the matching row model factories out of tableFeatures, since the browser never runs them.

##### How do I pin columns in TanStack Table v9?

Register columnPinningFeature and set columnPinning to { start: [...], end: [...] }; v9 renamed left and right to start and end with no aliases. Register columnSizingFeature too, make the pinned cells position: sticky with column.getStart('start') or column.getAfter('end') as the offset, and give them a width and a background so the offsets line up and rows do not show through.

##### Does the shadcn data table work on phones?

As of October 2026 the shadcn data table guide covers sorting, filtering, column visibility, client pagination and row selection on TanStack Table v9, and has no phone layout: the table keeps its columns and scrolls sideways. A card per row below 768px is something you add yourself or get from a component that ships it.

##### Is the Wingo UI Data Table free?

No. The Data Table is part of Wingo UI Pro, and so are the Table, Pagination and Toolbar it builds on. The checkbox, dropdown menu, popover and other basics it uses are free on their own.

---

Source: https://wingo-ui.com/blog/tanstack-table-v9-data-table

### v0 vs Claude Code for UI: Ownership, Screens and Cost

> v0 vs Claude Code for UI, checked in October 2026: who owns the code, how each keeps sign-in, pricing and settings screens consistent, and what you pay.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons)
- Reading time: 12 min
- Canonical: https://wingo-ui.com/blog/v0-vs-claude-code-for-ui

#### TL;DR

Pick v0 when you need a screen you can click through before a repository exists: it writes Next.js, Tailwind CSS and shadcn/ui code in a hosted sandbox, previews it and deploys to Vercel. Pick Claude Code when the screens belong in a repository you already have, next to your components, rules and tests. You own the code either way, entry plans cost $20 to $30 a month, and many screens stay consistent when each one imports the same component files, which v0 sets up with Design Systems 2.0 and Claude Code with a registry and a rules file.

The v0 vs Claude Code question usually gets answered on one component: a card or a form, generated in a minute. The harder part starts at the third screen. A sign-in page, a pricing page and a settings page belong to one product, so they have to share buttons, fields, spacing and tone, call your real API, and still match after six months of changes. This post compares v0 and Claude Code on that yardstick: who owns and maintains the code, how each keeps many screens consistent, what each costs and where each one wins. Lovable sits alongside.

We build Wingo UI, a component registry that Claude Code installs from, so read this as a vendor's view. We ran no generation benchmark and show no v0 or Lovable output: what we say about them comes from their docs and pricing pages, checked in October 2026 and linked. The Claude Code side uses our real Login, Pricing and Settings Page blocks. More head to head posts live under [Comparisons and alternatives](https://wingo-ui.com/blog/category/comparisons), and the [shadcn alternatives guide](https://wingo-ui.com/blog/shadcn-alternatives) covers the libraries these tools install.

#### How are v0 and Claude Code different?

v0 is a hosted builder: you chat on v0.app, it writes code in a sandbox, previews it and deploys to Vercel. Claude Code is an agent in your repository: it reads and edits your files, runs your commands and commits through git, from the terminal, an IDE, the desktop app or the web. Lovable is another hosted builder with a live preview, and it picks the framework and the database for you.

As of October 2026, from each vendor's own docs:

| | v0 | Claude Code | Lovable |
| --- | --- | --- | --- |
| Where the work happens | A Vercel Sandbox virtual machine, with a live preview | Your machine or a cloud session, inside your repository | Lovable's hosted editor, with a live preview |
| Stack it writes | Next.js, React, TypeScript, Tailwind CSS, shadcn/ui | Whatever your repository uses | TanStack Start for new apps, React with Vite for older ones; no framework choice |
| Existing repository | Import from GitHub, a Vercel project or a ZIP | Starts there | Cannot connect an existing repository |
| How code leaves | GitHub sync: a branch per chat, then a pull request | Already in your repository; commits and pull requests through git | Git sync on every plan, ZIP download on paid plans |
| Teaching it your design system | Design Systems 2.0, saved as a skill | `CLAUDE.md`, skills, MCP servers and the component files themselves | Design systems on paid plans, copied into each connected project |
| Entry paid plan | Plus, $30 per user per month | Claude Pro, $20 a month | Pro, $25 a month for 100 credits |

Sources: the v0 [FAQ](https://v0.app/docs/faqs), [GitHub docs](https://v0.app/docs/github), [Design Systems 2.0](https://v0.app/docs/design-systems-2) and [pricing](https://v0.app/pricing); the Claude Code [overview](https://code.claude.com/docs/en/overview) and [Claude pricing](https://claude.com/pricing); the Lovable [FAQ](https://docs.lovable.dev/introduction/faq), [plans](https://docs.lovable.dev/introduction/subscription-plans) and [design systems](https://docs.lovable.dev/features/design-systems).

The two have converged: v0 imports existing repositories and opens pull requests, and its sandbox ships with Claude Code pre-installed in the terminal, on by default outside Enterprise and billed to the team's AI Gateway credits ([v0 docs](https://v0.app/docs/pre-installed-agents)). What still separates them is the loop. v0's centers on the preview: prompt, look, adjust, publish. Claude Code's centers on the diff: prompt, read the change, run your type-check and tests, commit.

#### Who owns AI-generated UI code, and who maintains it?

You do: v0 and Lovable say so in their own terms, and Claude Code writes straight into your repository. The difference is where the source of truth lives and whether anything upstream can fix it later.

The v0 FAQ says "Vercel doesn't own the code generated based on your queries and prompts." Once you connect GitHub, the repository "becomes the source of truth for your project's code": each chat gets its own branch, v0 pushes changes to it automatically, and publishing merges a pull request. The Lovable FAQ says "Your apps, code, and the content you create with Lovable are yours." Claude Code edits your working tree, and you decide what gets committed.

Ownership has a second half the vendor FAQs skip: maintenance. Whatever generator writes them, generated screens have no upstream. When the sign-in screen mishandles a pasted one-time code, nobody ships a patch: you prompt for a fix, screen by screen, and hope each chat fixes it the same way.

Code installed from a registry has an upstream. Our blocks carry versions (in release 1.7.0 the Login Page is 1.0.1, the Pricing Page 1.1.0 and the Settings Page 1.0.0), the CLI records what it installed, and `update` runs a 3-way merge that keeps your edits:

```bash
npx wingo-ui@latest outdated            # installed items vs the latest release
npx wingo-ui@latest diff login-page     # your file vs upstream
npx wingo-ui@latest update login-page   # merge upstream changes into your edited file
```

That upstream comes with the code, whichever tool installs it; v0's agent also runs [shell commands in its sandbox](https://v0.app/docs/agentic-features), though we have not tried our CLI there. Our guide to [updating copied components without losing edits](https://wingo-ui.com/blog/update-shadcn-components-without-losing-edits) shows the merge step by step.

#### How do you keep AI-built screens consistent?

Make every screen import the same component files, and give the agent rules that forbid anything else. "Match the other pages" in a prompt does not survive a new chat.

v0's answer is Design Systems 2.0: you teach v0 your system once from an npm package, a repository or an app that uses it, and v0 saves it as a skill that a team owner on a paid plan can make the default for new chats. Its core rule is strict in the right way: "If a component, prop, or token cannot be verified from the sources, v0 should not use it." Two limits matter here: existing projects do not update when the skill changes (you ask v0 to update each one), and an import should stick to one design system and one framework stack where possible. Lovable copies a design system into `src/design-system/<slug>/` of each connected project and offers new versions as an "Update available" prompt in the project chat.

With Claude Code, consistency lives in the repository. The three Wingo UI blocks share code at the file level: the Login Page, the Pricing Page and the Settings Page all import `Button` from `@/components/ui/button`, and their dependency trees share 13 registry items, among them the avatar, the toast, the spinner, the tones and the motion presets. Change the button file once and the sign-in submit, the plan buttons and the settings save bar change together.

Every block also reads its defaults through the [UI config](https://wingo-ui.com/components/ui-config) provider, so one `UIProvider` in the root layout sets the tone and corners of all three screens, and a prop on one page still wins:

```tsx
// app/layout.tsx
import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";
import "./globals.css";

// keyed by each block's data-slot name
const defaults = {
  "login-page": { tone: "brand", radius: "lg" },
  "pricing-page": { tone: "brand", ctaTone: "brand", radius: "lg" },
  "settings-page": { tone: "brand", radius: "lg" },
};

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider defaults={defaults}>{children}</UIProvider>
      </body>
    </html>
  );
}
```

The rules file closes the loop: a few lines in `CLAUDE.md` saying that screens are built from installed blocks and components and that the agent searches the MCP server before it writes UI. Our [Claude Code shadcn setup](https://wingo-ui.com/blog/claude-code-shadcn-mcp-setup) has the full block, and the [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide) explains why the rules and the server need each other.

The sign-in screen below is the [Login Page](https://wingo-ui.com/components/login-page) block with nothing wired; its simulated sign-in rejects passwords shorter than 8 characters.

> Live demo (Login Page): Sign in with a short password to see the error alert, then open Forgot password: the email you typed carries over. Try it at [Login Page](https://wingo-ui.com/components/login-page) and install it with `npx wingo-ui@latest add login-page`.

#### How do you build sign-in, pricing and settings pages with Claude Code?

Install the blocks, then spend the agent on the wiring: handlers, data and routes, the part only your repository knows.

```bash
npx wingo-ui@latest login                                      # Pro items need a signed-in key
npx wingo-ui@latest add login-page pricing-page settings-page
```

The CLI writes the blocks to `components/blocks`, everything they import to `components/ui`, `hooks` and `lib`, and installs their npm packages. In release 1.7.0 the three blocks and their dependencies come to 83 registry items in 88 files. The blocks are Pro; the [Button](https://wingo-ui.com/components/button) they share is free.

Each route is then one block with your handlers and copy. The sign-in page:

```tsx
// app/(auth)/sign-in/page.tsx
"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";
import { LoginPage } from "@/components/blocks/login-page";

export default function SignInRoute() {
  const router = useRouter();
  return (
    <LoginPage
      layout="centered"
      logo={<span className="text-lg font-semibold">Acme</span>}
      labels={{ appName: "Acme", signInDescription: "Sign in to your Acme account to continue." }}
      methods={["password"]}
      showProviders={false}
      registerHref="/sign-up"
      linkComponent={Link}
      onSignIn={async ({ email, password, remember }) => {
        const res = await fetch("/api/auth/sign-in", { method: "POST", body: JSON.stringify({ email, password, remember }) });
        if (!res.ok) throw new Error("The email or the password is not correct");
      }}
      onSuccess={() => router.push("/dashboard")}
    />
  );
}
```

The pricing page, with your plans inside your own site header and footer:

```tsx
// app/(marketing)/pricing/page.tsx
"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";
import { PricingPage } from "@/components/blocks/pricing-page";
import type { PricingPlan } from "@/components/ui/pricing-table";

const PLANS: PricingPlan[] = [
  { id: "free", name: "Free", price: 0, features: ["3 projects", "Community support"], cta: { label: "Start for free" } },
  {
    id: "pro",
    name: "Pro",
    price: { monthly: 12, yearly: 120 },
    featured: true,
    features: ["Unlimited projects", "Priority email support"],
    cta: { label: "Start a 14 day trial" },
  },
];

export default function PricingRoute() {
  const router = useRouter();
  return (
    <PricingPage
      plans={PLANS}
      currencies={["USD"]}
      labels={{ title: "Simple pricing for every team", subtitle: "Start free and upgrade when you need more projects." }}
      faqs={[{ question: "Can I cancel anytime?", answer: "Yes. Your plan stays active until the end of the period you paid for." }]}
      header={false}
      footer={false}
      showComparison={false}
      showLogos={false}
      showTestimonials={false}
      showCta={false}
      linkComponent={Link}
      onSelectPlan={(planId, period) => router.push(`/checkout?plan=${planId}&period=${period}`)}
    />
  );
}
```

On the [Pricing Page](https://wingo-ui.com/components/pricing-page), the period switch rolls every price to its new value, and in a column narrower than 768px, like the one below or a phone, the plans turn into a swipeable carousel that starts on the featured plan.

> Live demo (Pricing Page): Switch between Monthly and Yearly, then dollars and euros: every price rolls to its new value, and a plan's button spins before a toast confirms the choice. Try it at [Pricing Page](https://wingo-ui.com/components/pricing-page) and install it with `npx wingo-ui@latest add pricing-page`.

And the settings page, saving each section to your API (password, two-step and session changes have their own handlers):

```tsx
// app/(app)/settings/page.tsx
"use client";

import { SettingsPage } from "@/components/blocks/settings-page";

export default function SettingsRoute() {
  return (
    <SettingsPage
      sections={["profil", "cont", "notificari", "securitate"]}
      onSave={async (section, values) => {
        const res = await fetch(`/api/settings/${section}`, { method: "PUT", body: JSON.stringify(values) });
        if (!res.ok) throw new Error("We could not save. Please try again.");
      }}
    />
  );
}
```

Three things the blocks leave to you:

- **Simulated handlers.** A handler you leave out stays simulated so the demo works: without `onVerifyCode` the code views accept 123456, and without `onSave` the settings page pretends to save.
- **Sample content.** The defaults describe demo companies: Northwind CRM on sign-in, Acme CRM on pricing, Emma Carter's profile in settings. Pass your own `labels`, `logo`, `plans`, `faqs` and `profile`.
- **Section ids.** The settings sections are keyed by Romanian words (`profil`, `cont`, `notificari`, `facturare`, `securitate`, `pericol`), while the labels default to English. The billing form validates a Romanian company ID (CUI) and a Romanian address, so leave `facturare` out if you bill elsewhere.

A prompt that covers all three: "Build /sign-in, /pricing and /settings from the installed Wingo UI blocks, reading their props with get_block first. Wire every handler to app/api, list any on* handler left on its simulated default, then type-check and lint."

The [Settings Page](https://wingo-ui.com/components/settings-page) below is narrower than 768px here, so it shows its phone layout: a list that pushes each section in.

> Live demo (Settings Page): Open Security and turn on two-step verification: copy the key, type 123456, then copy or download the ten backup codes. Try it at [Settings Page](https://wingo-ui.com/components/settings-page) and install it with `npx wingo-ui@latest add settings-page`.

#### How much do v0, Lovable and Claude Code cost?

Entry plans cost about the same, $20 to $30 a month, but each meters something different: v0 pricing turns tokens into credits, Lovable charges credits per message, and Claude Code comes with a subscription's usage limits or bills API tokens. Prices as of October 2026, before tax:

| Tool | Free tier | Paid plans | What is metered |
| --- | --- | --- | --- |
| [v0](https://v0.app/pricing) | 7 messages a day | Plus $30 per user per month, with $30 of monthly credits and $2 of daily credits on login; Business $100 per user per month | Tokens at per-model rates per million, for example $2 input and $10 output on v0 Pro, $5 and $25 on v0 Max |
| [Lovable](https://docs.lovable.dev/introduction/subscription-plans) | 5 build credits a day, up to 30 a month | Pro $25 a month for 100 credits ($250 a year), with unlimited workspace members; Business $50 a month | Credits per message, for example 0.50 for "Make the button gray" and 1.20 for "Add authentication with sign up and login" |
| [Claude Code](https://claude.com/pricing) | Not in Claude Free | Claude Pro $20 a month or $17 billed yearly; Max from $100 a month; Team seats from $20 billed yearly | Usage limits per plan, or API tokens with a Console key |
| [Cursor](https://cursor.com/pricing) | Hobby, limited agent requests | Pro $20 a month; Teams $40 per user per month | A set amount of model usage per plan, on-demand usage billed after |
| [Wingo UI](https://wingo-ui.com/pricing) | 75 free items | Pro $8 a month, $80 a year or $150 once | Nothing; installing files uses no model tokens |

Lovable's credit examples come from its [pricing page](https://lovable.dev/pricing). We did not measure what each tool spends on these screens, so we put no price on a screen. One structural point is safe: the three blocks' own files are about 7,650 lines of TypeScript, and the settings page with its dependencies is 74 registry items. Generating screens of that depth costs output tokens or credits on every line, and again on every fix. Installing them costs none, and the agent's budget goes to the wiring.

#### When should you use v0, and when Claude Code?

v0 wins before there is a repository. Claude Code wins once there is one.

v0 is the better choice when:

- You need a clickable screen today, at a URL you can share. Deploys take one click.
- A designer does the iterating. Design Mode edits styles visually on every plan, Free included, and on paid plans v0 [turns a Figma link into a working app](https://v0.app/docs/figma).
- Your stack is already Next.js, Tailwind CSS and shadcn/ui on Vercel, so v0's defaults are your defaults.

Claude Code is the better choice when:

- The screens call your real APIs, with your environment variables, database and tests.
- You are building the tenth screen of a product, and it has to match the first nine.
- Your stack is not v0's default: another framework, another component library, a monorepo.
- You want every change as a diff you read before it lands.

Lovable vs Claude Code is a different question: who is building. Lovable suits a founder who does not want to read code and needs a hosted app with a database. It offers no framework choice and cannot connect an existing repository, so a developer with a Next.js codebase is better served by Claude Code.

As of October 2026, a search for v0 vs Claude Code Reddit threads mostly returns comparison sites, and the advice they repeat is the hybrid: draft in v0, integrate with Claude Code. That holds, with one change for products with many screens: let the draft settle the layout, then build the real screens from components already in your repository, so the draft never becomes your design system.

#### Where does Cursor fit next to v0 and Claude Code?

In a v0 vs Cursor vs Claude Code comparison, Cursor sits on Claude Code's side of the line: an editor whose agent works on the files in your repository, and Claude Code runs inside it through the same extension it uses in VS Code ([Claude Code overview](https://code.claude.com/docs/en/overview)). Between those two, pick the interface you prefer; the v0 question stays the same.

#### Where should you start?

If you have no repository yet and need something to show this week, start in v0 and connect GitHub from the first chat. If you have a repository, put the screens there. Connect the [Wingo UI MCP server](https://wingo-ui.com/docs/mcp) with `npx wingo-ui@latest agents install claude`, install the three blocks and spend your prompts on wiring. The blocks are part of Wingo UI Pro; the Button they share and 74 other items are free.

#### Components in this post

- [Login Page](https://wingo-ui.com/components/login-page) (Pro): The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. Install: `npx wingo-ui@latest add login-page`
- [Pricing Page](https://wingo-ui.com/components/pricing-page) (Pro): The pricing page of a SaaS: hero, plans with a monthly or yearly and dollar or euro switch, comparison, quotes, FAQ and a closing call. Install: `npx wingo-ui@latest add pricing-page`
- [Settings Page](https://wingo-ui.com/components/settings-page) (Pro): The account settings of a back office: profile, account, notifications, billing, security and a danger zone, with a save bar. Install: `npx wingo-ui@latest add settings-page`

#### FAQ

##### Is v0 better than Claude Code for building UI?

For a first draft you can click through and share, often yes: v0 shows a live preview, edits styles visually and deploys with one click. For screens that call your real API, follow your conventions and must match screens built months earlier, Claude Code fits better because it works in your repository with your files and rules.

##### Can I use v0 and Claude Code together?

Yes. Connect the v0 project to GitHub and pull its branch into your local checkout for Claude Code. As of October 2026, v0 also pre-installs Claude Code in its sandbox terminal, where its requests use your team's AI Gateway credits.

##### Who owns the code that v0 or Lovable generates?

You do, by their own terms as of October 2026. The v0 FAQ says Vercel does not own the code generated from your prompts, and the Lovable FAQ says your apps, code and content are yours, subject to third-party rights such as open source licenses.

##### Does Lovable support Next.js?

No. As of October 2026 the Lovable FAQ says it does not offer a choice of framework: new apps use TanStack Start and older ones React with Vite. If your app runs on Next.js, v0 or Claude Code fit better.

##### How much does Claude Code cost?

As of October 2026 it is not in Claude Free; it is included in Claude Pro at $20 a month, or $17 a month billed yearly, and in Max from $100 a month. It also runs on an Anthropic API key billed by usage, and Team seats start at $20 a month billed yearly.

##### Can Claude Code install the Wingo UI login, pricing and settings pages?

Yes. Run npx wingo-ui@latest add login-page pricing-page settings-page and the CLI writes the three blocks and everything they import into your project. They are Pro items, so sign in first with npx wingo-ui@latest login.

---

Source: https://wingo-ui.com/blog/v0-vs-claude-code-for-ui

### Web Vibration API: Haptic Feedback on Android and iPhone

> The Web Vibration API in 2026: navigator.vibrate on Android, the iPhone switch tick that iOS 26.5 limits to real taps, and a React helper that fails quietly.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Oct 9, 2026
- Category: [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui)
- Reading time: 11 min
- Canonical: https://wingo-ui.com/blog/web-vibration-api-haptic-feedback

#### TL;DR

As of October 2026 the Web Vibration API (navigator.vibrate) works only in Chromium browsers on Android, only after the user has tapped the page, and with no control over intensity; Safari on iPhone has never shipped it. The one haptic a page can trigger on an iPhone is the system tick of a native HTML switch, and since iOS 26.5 WebKit plays it only when the user's own tap toggles the switch, never for a click from JavaScript. Put navigator.vibrate behind one helper that returns false instead of throwing, lay a label for a hidden switch over buttons that should tick on iPhone, and never let a tick be the only feedback.

You want a tap to tick under the thumb the way it does in a native app, so you reach for the web vibration API. On an Android phone `navigator.vibrate(10)` works on the first try. On an iPhone nothing happens, on a laptop the call returns `true` and nothing happens, and the iPhone workaround you found on GitHub stopped working in iOS 26.5. This tutorial maps what a page can really trigger in October 2026, builds a helper that stays silent wherever it cannot play, and wires haptics into a switch, a button and a wheel picker in React.

#### What can the Web Vibration API do in 2026?

It can switch the vibration motor on and off for durations you give in milliseconds, in Chromium browsers on Android, after the user has tapped the page. That is the whole API: one method, navigator.vibrate, that takes a number or an array of alternating vibrate and pause times. There is no intensity, no waveform and no way to ask whether the device has a motor at all. Software Mansion's [August 2026 overview of web haptics](https://swmansion.com/blog/haptic-feedback-on-the-web-why-the-web-deliberately-refuses-to-be-as-tactile-as-native-apps) sums up the support in one line: "the vibration API is effectively limited to Chromium-based browsers."

Here is where a tick can reach a finger, as of October 2026 ([caniuse](https://caniuse.com/vibration) for support, our own test in desktop Chromium for the last row):

| Where the page runs | `navigator.vibrate` | What the user feels |
| --- | --- | --- |
| Chrome or Samsung Internet on Android | supported | the pattern you pass, once the page has seen a tap |
| Firefox | removed in version 129, not supported on Android | nothing |
| Safari on iPhone, and home screen web apps | never shipped | the system tick of a native switch, only when the user's own tap toggles it |
| Chrome on a desktop | present, returns `true` | nothing, there is no motor |

The last row is the trap. Feature detection with `"vibrate" in navigator` says yes in desktop Chrome, so it tells you nothing about hardware. The boolean that `navigator.vibrate()` returns only says the browser accepted the pattern; it says nothing about whether anyone felt it.

#### How does navigator.vibrate behave on Android?

It plays the pattern you pass and replaces any pattern already running, within limits you can read in Chromium's [vibration controller](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/vibration/vibration_controller.cc):

```ts
navigator.vibrate(8); // one 8ms pulse: a light tick
navigator.vibrate([10, 60, 16]); // pulse, pause, pulse: a success pattern
navigator.vibrate(0); // cancels whatever is running (so does [])
```

- **It needs a tap first.** [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate) lists sticky user activation as a requirement. Until the page has seen a tap, a click or a key press, Chrome returns `false` and logs "Blocked call to navigator.vibrate because user hasn't tapped on the frame or any embedded frame yet". Once granted, the activation lasts until the page navigates, so a tick from a scroll handler or after an `await` works later on.
- **It is silent in the background.** The call returns `false` while the page is hidden.
- **Long patterns are trimmed.** Chromium caps each entry at 10,000ms, keeps the first 99 entries and drops a trailing pause.
- **The phone can overrule you.** MDN notes that some devices do not vibrate in silent or Do Not Disturb mode.

Keep the pulses short; the helper below uses 4 to 22ms per pulse. The 200ms buzz in many examples (MDN's first one included) reads as a notification, which is the wrong message for a toggle.

#### Does the Web Vibration API work on iOS?

No. Safari has never implemented navigator.vibrate, and caniuse lists no version of Safari on iOS with it, up to 27.2. Look up web vibration API iOS support and you land on one workaround: Safari 17.4 added a native switch control, `<input type="checkbox" switch>` ([WebKit's announcement](https://webkit.org/blog/15054/an-html-switch-control/)), and toggling it plays the system haptic tick.

Until iOS 26.5, libraries such as ios-haptics played that tick on demand by calling `.click()` on a hidden label wired to the switch. That no longer works. The [ios-haptics README of April 2026](https://www.npmjs.com/package/ios-haptics/v/0.1.5) says the trick "only works on ios 17.4 to 26.4, as apple patched it in ios 26.5". The [WebKit fix](https://commits.webkit.org/313638@main), merged into the main branch on May 21, 2026, closes that gap: WebKit already required user activation for the haptic, and now it also requires a trusted event, which a click forwarded from `label.click()` no longer is.

What still works is a real tap that lands on a label for the switch. The tap produces a trusted click, the label forwards it to the switch, and because the original click was trusted, the WebKit change still lets the switch tick. The [ios-haptics source](https://github.com/tijnjh/ios-haptics) moved to exactly that on September 22, 2026: it lays a transparent label over your element. Here is the same idea as a React 19 component:

```tsx
// components/ios-tap-tick.tsx
"use client";

// iOS plays the switch haptic only for a trusted click, so the user's own tap has to land on a label for the switch.
// put it inside a positioned button; it covers the button and the click still bubbles to the button's onClick
export function IOSTapTick() {
  return (
    <label
      aria-hidden="true"
      data-slot="ios-tap-tick"
      className="absolute inset-0 touch-manipulation [-webkit-tap-highlight-color:transparent]"
    >
      <input
        type="checkbox"
        // react 19 passes the unknown attribute through; the spread keeps TypeScript quiet
        {...{ switch: "" }}
        tabIndex={-1}
        // the label, not the switch, sits under the finger, so a swipe that starts here still scrolls the page
        className="invisible absolute m-0 size-px"
        // the label forwards the click to the switch: stop that second click before it reaches the button
        onClick={(event) => event.stopPropagation()}
      />
    </label>
  );
}
```

Use it in buttons, not links: in our Chromium test a label inside an `<a>` ran the link's `onClick` but took over the default action, so the link never navigated. Leave the input without a `name`, so it never ends up in a form submission. Outside iOS a tap on it only toggles a hidden checkbox nobody sees, so it can render on every platform and never causes a hydration mismatch.

On an iPhone you get one fixed tick per tap, from the tap itself: no patterns, nothing after an `await`, nothing during a drag, and nothing for a wheel spinning past rows, because a scroll never produces a click.

#### How do you call navigator.vibrate safely where it is unsupported?

Check for the method itself, check activation, catch everything, and return a boolean. Here is the whole helper without dependencies:

```ts
// lib/vibrate.ts
export type HapticKind = "selection" | "light" | "medium" | "heavy" | "success" | "warning" | "error";

const PATTERNS: Record<HapticKind, number | number[]> = {
  selection: 4,
  light: 8,
  medium: 14,
  heavy: 22,
  success: [10, 60, 16],
  warning: [16, 70, 16],
  error: [22, 50, 22, 50, 22],
};

let enabled = true;

export function setHapticsEnabled(value: boolean) {
  enabled = value;
}

export function vibrate(kind: HapticKind = "light"): boolean {
  if (!enabled) return false;
  // node 21+ has a global navigator too, so test for the method, not for navigator
  if (typeof navigator === "undefined" || typeof navigator.vibrate !== "function") return false;
  // chrome blocks the call (and logs a warning) until the page has seen a tap
  if (navigator.userActivation && !navigator.userActivation.hasBeenActive) return false;
  try {
    return navigator.vibrate(PATTERNS[kind]);
  } catch {
    return false; // feedback is never worth an exception
  }
}
```

The Node check matters. Node 21 and later define a global `navigator` with no `vibrate`, so a helper that only checks `typeof navigator` gets past its guard on the server and calls a method that is not there.

Wingo UI's [haptics helper](https://wingo-ui.com/components/haptics) is the same idea plus an iPhone fallback and a `force` option that plays a tick even when haptics are off. `haptic(kind)` returns whether a haptic was sent, `configureHaptics({ enabled, iosFallback })` sets the app-wide options, and `supportsHaptics()` tells you whether the browser exposes a haptic path at all (call it in an effect: it is `false` on the server, and `true` in desktop Chrome for the reason above).

> Live demo (Haptics): On an Android phone, tap each tile to feel the seven kinds; the bars draw each vibration pattern and the line under the card shows what haptic() returned. Try it at [Haptics](https://wingo-ui.com/components/haptics) and install it with `npx wingo-ui@latest add haptics`.

A caveat about our own code: the helper's `iosFallback` option, on by default, still clicks a hidden label from script. That plays on iPhones up to iOS 26.4, is ignored from 26.5, and the call still returns `true` there because WebKit reports nothing back. If you add the tap overlay above, call `configureHaptics({ iosFallback: false })` once so iPhones on older versions do not tick twice.

The snippets below import Wingo UI's helper. With the dependency-free file above, import `vibrate` from `@/lib/vibrate` instead and use `setHapticsEnabled` in place of `configureHaptics`; it has no `force` option.

#### Which haptic should each interaction get?

One tick per event, sized to the event. These are the patterns the helper sends on Android:

| Kind | Pattern (ms) | Use it for | Wingo UI component that plays it |
| --- | --- | --- | --- |
| `selection` | 4 | a row of a wheel or a slider step passing the center | Picker Wheel |
| `light` | 8 | a tap, a toggle | Haptic Button press |
| `medium` | 14 | a long press, a snap, a crossed threshold | Haptic Button long press, Pull To Refresh arming, Slide To Confirm armed |
| `heavy` | 22 | a committed full swipe, a drop | none; call it from your own drop handler |
| `success` | 10, 60, 16 | payment sent, item saved | Haptic Button hold confirmed, Slide To Confirm done |
| `warning` | 16, 70, 16 | a limit reached, a hold released too early | Haptic Button tap in hold mode |
| `error` | 22, 50, 22, 50, 22 | a wrong PIN, a failed save | Haptic Button rejected promise |

Three rules keep it from turning into noise. Call it from the handler of a real gesture, never from an effect or a render. Never tick per animation frame; tick when something changes state, like a row reaching the center. And never put information only in the tick: desktop users, iPhone users on a wheel and anyone with a phone on silent will not feel it, so the screen must say the same thing.

#### How do you add React haptic feedback to a switch, a button and a wheel?

Call `haptic()` in the handler where the state changes, once per change.

##### A switch

The free [Switch](https://wingo-ui.com/components/switch) calls `onCheckedChange` on every click, key or drag, and a returned promise makes it spin, then flip back with `errorText` if the save fails. Tick on the change and again on failure:

```tsx
"use client";

import { Switch } from "@/components/ui/switch";
import { haptic } from "@/lib/haptics";

export function NewMessagesSetting({ save }: { save: (on: boolean) => Promise<void> }) {
  return (
    <Switch
      label="New messages"
      description="When someone writes to you about a listing"
      labelPosition="start"
      defaultChecked
      onCheckedChange={async (on) => {
        haptic("light");
        try {
          await save(on);
        } catch (error) {
          haptic("error");
          throw error; // the switch flips back and shows errorText
        }
      }}
    />
  );
}
```

On iOS 26.5 and later this Switch stays silent: it is a Radix button with `role="switch"`, not the native input, so no system tick comes with the tap, and `haptic()` cannot reach the switch tick from script. If an iPhone tick on a settings toggle matters more to you than the custom look, a plain `<input type="checkbox" switch>` ticks on its own and renders as a checkbox in browsers that do not know the attribute.

##### A button

The [Haptic Button](https://wingo-ui.com/components/haptic-button) plays its `hapticKind` (default `light`) on touch and pen presses only, so a mouse click never asks for a vibration. In `mode="hold"` it plays light when the hold starts, success once `onConfirm` has finished, warning for a tap that was too short and error when `onConfirm` rejects; with `onLongPress` set, a long press plays medium.

```tsx
"use client";

import { Send } from "lucide-react";
import { HapticButton } from "@/components/ui/haptic-button";

export function SendRent({ onSend }: { onSend: () => Promise<void> }) {
  return (
    <HapticButton mode="hold" fullWidth leftIcon={<Send />} labels={{ holdHint: "Hold to send" }} onConfirm={onSend}>
      Hold to send $1,850
    </HapticButton>
  );
}
```

> Live demo (Haptic Button): Hold the Hold to send button with a finger on an Android phone: a light tick starts the fill, a success pattern lands with the check, and a quick tap shakes the button with a warning tick. Try it at [Haptic Button](https://wingo-ui.com/components/haptic-button) and install it with `npx wingo-ui@latest add haptic-button`.

For an ordinary [Button](https://wingo-ui.com/components/button) that should tick on both platforms, combine the call and the overlay. The Button is already `position: relative`, so the overlay covers it:

```tsx
"use client";

import { Button } from "@/components/ui/button";
import { IOSTapTick } from "@/components/ios-tap-tick";
import { haptic } from "@/lib/haptics";

export function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
  return (
    <Button
      onClick={async () => {
        haptic("light"); // android; the overlay ticks on iPhone
        try {
          await onSave();
          haptic("success"); // android only: iPhone has no tick after an await
        } catch {
          haptic("error");
        }
      }}
    >
      Save
      <IOSTapTick />
    </Button>
  );
}
```

##### A wheel

The [Picker Wheel](https://wingo-ui.com/components/picker-wheel) plays a `selection` tick each time a new row reaches the center while a finger, a mouse drag or a scroll wheel drives it, and never for keys, clicks or value changes from outside. `haptics={false}` turns it off.

```tsx
"use client";

import { PickerWheel, pickerRange } from "@/components/ui/picker-wheel";

const hours = pickerRange(8, 19, { pad: 2 });
const minutes = pickerRange(0, 55, { step: 5, pad: 2 });

export function AppointmentTime() {
  return (
    <PickerWheel
      aria-label="Appointment time"
      loop
      defaultValue={["10", "30"]}
      columns={[
        { id: "hour", label: "h", options: hours },
        { id: "minute", label: "min", options: minutes },
      ]}
    />
  );
}
```

> Live demo (Picker Wheel): Flick a column on an Android phone: each row that reaches the center ticks once, and the value changes when the wheel comes to rest. Try it at [Picker Wheel](https://wingo-ui.com/components/picker-wheel) and install it with `npx wingo-ui@latest add picker-wheel`.

This is the clearest case of the platform gap. On Android every row that passes the center ticks. On an iPhone the wheel is silent from iOS 26.5, because a spin is a scroll and never produces the trusted click the switch needs; the band, the tilt and the snap carry the feedback there.

#### How do you let people turn haptics off?

Give them a setting and pass it to the helper once. Every haptic feedback web app needs one: some people find vibration distracting, and the browser gives a page no way to read the phone's own haptics setting.

```tsx
"use client";

import { useEffect, useState } from "react";
import { Switch } from "@/components/ui/switch";
import { configureHaptics, haptic } from "@/lib/haptics";

export function VibrationSetting() {
  const [on, setOn] = useState(true);

  useEffect(() => {
    configureHaptics({ enabled: on });
  }, [on]);

  return (
    <Switch
      label="Vibrations"
      description="A short tick when you tap, hold or pick"
      labelPosition="start"
      checked={on}
      onCheckedChange={(next) => {
        setOn(next);
        // the effect has not run yet, so force the confirmation tick
        if (next) haptic("light", { force: true });
      }}
    />
  );
}
```

Store the value with the rest of the user's settings. Every component that ticks through the helper follows it without a prop: the Haptic Button, the Picker Wheel, and the Pull To Refresh from our [pull to refresh guide](https://wingo-ui.com/blog/react-pull-to-refresh) among them.

#### What comes after navigator.vibrate?

A semantic API with named effects, if browsers adopt the one being drafted now. The [Web Haptics API](https://github.com/WICG/web-haptics) started as a [proposal to the CSS Working Group](https://github.com/w3c/csswg-drafts/issues/13728) in March 2026 and has been incubated at the WICG since April. Its draft has a `navigator.playHaptics(effect, intensity)` call and a nested `@haptic` CSS rule, with six named effects (hint, edge, tick, align, success, error) and an intensity from 0 to 1 that the browser maps to the platform's own haptics. The call returns `undefined`, so a page learns nothing about the device. As of October 2026 [Chrome Platform Status](https://chromestatus.com/feature/5167864517623808) lists Web haptics as Proposed, and no stable browser ships it.

The shape is familiar: named kinds instead of millisecond patterns. If your app already funnels every tick through one `haptic(kind)` call, moving to a new API later means changing one file.

#### Where should you start?

Add a helper first, then tick the three places users touch most: toggles, the primary button and any wheel or slider. The dependency-free `lib/vibrate.ts` above covers Android. `npx wingo-ui@latest add haptics` copies Wingo UI's `lib/haptics.ts` instead; it is part of [Wingo UI Pro](https://wingo-ui.com/pricing), like the Haptic Button and the Picker Wheel, while the Switch is free. For the rest of the phone checklist (bottom sheets, [44px touch targets](https://wingo-ui.com/blog/minimum-touch-target-size-react-tailwind), [safe area insets](https://wingo-ui.com/blog/tailwind-safe-area-insets)), read [mobile-first React components](https://wingo-ui.com/blog/mobile-first-react-components) or browse the [Mobile UI in React](https://wingo-ui.com/blog/category/mobile-ui) category.

#### Components in this post

- [Haptics](https://wingo-ui.com/components/haptics) (Pro): Haptic feedback for the web in one call: short vibration ticks on Android and the system tick on iPhone, silent everywhere else. Install: `npx wingo-ui@latest add haptics`
- [Haptic Button](https://wingo-ui.com/components/haptic-button) (Pro): A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode. Install: `npx wingo-ui@latest add haptic-button`
- [Switch](https://wingo-ui.com/components/switch) (Free): An on / off setting that applies at once: a spring thumb that stretches and drags like iOS, thumb icons, and async saves that roll back. Install: `npx wingo-ui@latest add switch`
- [Picker Wheel](https://wingo-ui.com/components/picker-wheel) (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: `npx wingo-ui@latest add picker-wheel`

#### FAQ

##### Does navigator.vibrate work on iPhone?

No. Safari has never implemented the Vibration API, and as of October 2026 caniuse lists no version of Safari on iOS that supports it. The only haptic a web page can produce on an iPhone is the system tick of a native switch input, and since iOS 26.5 only the user's own tap on it plays that tick.

##### Why does navigator.vibrate return true on my laptop?

Because true only means the browser accepted the pattern. Desktop Chrome exposes navigator.vibrate and, once the page has seen a click, returns true for a valid pattern even though there is no motor to run. Use the return value to detect refusals and never to detect hardware.

##### Why does navigator.vibrate do nothing on my Android phone?

The usual causes are a page the user has not tapped yet (Chrome blocks the call and logs a warning until the page has sticky user activation), a hidden tab, silent or Do Not Disturb mode, or Firefox, which removed the API in version 129.

##### Can a web page control vibration intensity?

Not with the Vibration API, which only switches the motor on and off for the durations you pass. The Web Haptics API proposal, incubated at the WICG since April 2026, adds named effects with an intensity from 0 to 1, but as of October 2026 no stable browser ships it.

##### Is the Wingo UI haptics helper free?

No. The haptics helper, the Haptic Button and the Picker Wheel are Pro items; the Switch is free. With a Pro account signed in through npx wingo-ui@latest login, npx wingo-ui@latest add haptics copies lib/haptics.ts into your project.

---

Source: https://wingo-ui.com/blog/web-vibration-api-haptic-feedback