# mwui Full Context

> MediaWeb's installable UI component library.

This file expands the Markdown pages listed in https://mwui.vercel.app/llms.txt. Use https://mwui.vercel.app/registry.json for the machine-readable shadcn registry index.

---

URL: https://mwui.vercel.app/docs.md

Publish installable registry items with public docs from the same workspace.

# Introduction

Publish installable registry items with public docs from the same workspace.

This registry publishes copy-and-paste components, blocks, hooks, files, themes, styles, fonts, bases, and universal items that can be installed with the shadcn CLI.

Use the docs in this section to set up the registry, customize the site, and publish your own items.

<Callout title="Authoring model">
  Registry docs live in `registry/docs`. Installable source lives in `registry/items`. You can
  update any of these files freely (or completely delete them!)
</Callout>


---

URL: https://mwui.vercel.app/docs/installation.md

Install and run the registry template locally.

# Installation

Install and run the registry template locally.

After forking the template, install dependencies with [Vite+](https://viteplus.dev/guide/) and start the local docs app.

```sh
vp install
vp dev
```

Open the local URL from Vite+ to preview your docs, registry catalog, and install pages.

## Customize the Registry

Update `registry/config.ts` before publishing your fork. This file controls the public registry identity, namespace, description, homepage, repository URL, and generated install URLs.

## Add Registry Items

Scaffold new installable items under `registry/items/**` with the starter script.

```sh
bun --bun ./scripts/new.ts --type registry:ui --name example-card --description "A compact card component."
```

You can also run `bun --bun ./scripts/new.ts` for an interactive prompt. Use `--target` for `registry:page`, `registry:file`, custom alias installs such as `@ui/ai/prompt-input.tsx`, or targeted `registry:item` files.

The scaffold creates the item source, `_registry.mdx` metadata and usage docs, and an optional `_preview.tsx` preview. Public documentation pages live directly in `registry/docs/`.

## Verify Changes

Run the registry doctor after item changes, check the files you touched, and build before publishing.

```sh
bun --bun ./scripts/doctor.ts
vp check --fix <touched-file>
vp build
```


---

URL: https://mwui.vercel.app/docs/registry.md

Scaffold and author installable registry items under registry/items.

# Registry

Scaffold and author installable registry items under registry/items.

Registry items live under `registry/items/**` and can be installed by shadcn-compatible CLIs. Start new items with the scaffold command so the folder, `_registry.mdx`, source file, metadata, and generated registry JSON paths follow the template conventions.

```sh
bun --bun ./scripts/new.ts --type registry:ui --name example-card --description "A compact card component."
```

Or, run the command without flags if you want an interactive prompt (recommended).

```sh
bun --bun ./scripts/new.ts
```

<Callout title="Requires Bun">
  [Make sure Bun is installed before running these scripts.](https://bun.com/)
</Callout>

## Item Types

Choose the registry type from what the item installs:

| Type                 | Use For                                   | Folder                         |
| -------------------- | ----------------------------------------- | ------------------------------ |
| `registry:ui`        | Shadcn-style UI components                | `registry/items/components/**` |
| `registry:component` | Components outside `components/ui`        | `registry/items/components/**` |
| `registry:block`     | Larger composed UI patterns               | `registry/items/blocks/**`     |
| `registry:hook`      | React hooks                               | `registry/items/hooks/**`      |
| `registry:lib`       | Utility or helper modules                 | `registry/items/lib/**`        |
| `registry:page`      | App page files with explicit targets      | `registry/items/pages/**`      |
| `registry:file`      | Other files with explicit install targets | `registry/items/files/**`      |
| `registry:style`     | Style-level CSS and dependency metadata   | `registry/items/styles/**`     |
| `registry:theme`     | Theme CSS variables                       | `registry/items/themes/**`     |
| `registry:font`      | Font metadata                             | `registry/items/fonts/**`      |
| `registry:base`      | Design system base configuration          | `registry/items/bases/**`      |
| `registry:item`      | Universal or metadata-only items          | `registry/items/items/**`      |

The scaffold creates each item in its own folder:

```text
registry/items/components/example-card/
  _registry.mdx
  _preview.tsx
  example-card.tsx
```

## CLI Flags

Use flags for agent-friendly and CI-friendly scaffolding:

```sh
bun --bun ./scripts/new.ts --type registry:block --name team-access-panel --description "A team member access panel."
bun --bun ./scripts/new.ts --type registry:ui --name prompt-input --description "An AI prompt input." --target @ui/ai/prompt-input.tsx
bun --bun ./scripts/new.ts --type registry:page --name dashboard-page --description "A starter dashboard page." --target app/dashboard/page.tsx
bun --bun ./scripts/new.ts --type registry:file --name chart-theme --description "Shared chart theme tokens." --target styles/chart-theme.css --file-extension css
bun --bun ./scripts/new.ts --type registry:font --name font-inter --description "Inter font metadata." --font-family "'Inter Variable', sans-serif" --font-import Inter --font-variable=--font-sans
```

Supported flags:

- `--type`: registry item type. Defaults to `registry:ui`.
- `--name`: required kebab-case item name.
- `--title`: optional public title. Defaults from the name.
- `--description`: required public description.
- `--target`: required for `registry:page` and `registry:file`; optional for source-backed items that need a custom install path, including shadcn target placeholders like `@ui/ai/prompt-input.tsx`.
- `--file-extension`: for `registry:file` and targeted `registry:item`; defaults to `ts`.
- `--font-family`, `--font-import`, `--font-variable`: required for noninteractive `registry:font` scaffolds.

Use `bun --bun ./scripts/new.ts --help` to print the full usage.

## Authoring

Use `_registry.mdx` for public metadata and usage docs. Put the optional named `Preview` export in `_preview.tsx`. Keep both files private to authoring; never list them in `files`.

For one-file `registry:ui` items, the catalog infers `<item-name>.tsx`. Hooks, libs, blocks, pages, target paths, and multi-file items should list `files` explicitly. Metadata-only styles, themes, fonts, bases, and universal items can omit `files`.

List authored source files with paths relative to the item `_registry.mdx` file. The catalog automatically emits `files[].target` placeholders such as `@ui/<name>.tsx`, `@components/<name>.tsx`, `@hooks/<name>.ts`, and `@lib/<name>.ts` for file types that should install through the user's `components.json` aliases. Use explicit `target` values for `registry:page`, `registry:file`, and nested alias installs like `@ui/ai/prompt-input.tsx`; do not add `registry/items/**` prefixes or a separate `sourcePath` field.

Use `localRegistryDependencies` for dependencies on other local registry items.

After editing an item, run `vp check --fix` on touched files and `bun --bun ./scripts/doctor.ts`. Run `vp build` when registry docs, routes, JSON output, catalog loading, or source loading changed.


---

URL: https://mwui.vercel.app/docs/agents.md

Give AI coding tools the right context for using and authoring this registry.

# Agents

Give AI coding tools the right context for using and authoring this registry.

This template is designed to work well with coding agents and LLM-powered tools. It exposes Markdown-first routes for reading context, and it ships an installable Agent Skill for authoring registry items correctly.

## Install the Registry Skill

Install the `mwui` registry authoring skill:

```sh
npx skills add mgalexandre/mwui --skill shadcn-registry
```

Forks can install the same skill from their own repository:

```sh
npx skills add <owner>/<repo> --skill shadcn-registry
```

After installing the skill, ask for registry work directly:

- "add a button component to the registry"
- "adapt this modal from my app into a reusable registry component"
- "add a reusable hook to the registry"
- "turn this dashboard section into a registry block"

The skill covers all public registry item types, previews, usage docs, dependency metadata, and the scaffold command for creating new items non-interactively.

## Point Agents At Markdown

The generated [`/llms.txt`](/llms.txt) route gives AI tools a compact map of the docs, registry catalog, and item pages.

Use [`/llms-full.txt`](/llms-full.txt) when a tool needs expanded context with generated Markdown content inlined.

Every docs page, the registry catalog, and each registry item also has a Markdown route:

- [`/docs.md`](/docs.md)
- [`/docs/agents.md`](/docs/agents.md)
- [`/registry.md`](/registry.md)
- [`/components/autosize-textarea.md`](/components/autosize-textarea.md)

Inspired by [Fumadocs](https://www.fumadocs.dev/docs/headless/utils/negotiation), "human" permalinks support Markdown content negotiation too. AI clients can request `text/markdown`, `text/x-markdown`, or `text/plain` in the `Accept` header on pages like [`/docs`](/docs) or [`/components/autosize-textarea`](/components/autosize-textarea) and receive Markdown without changing URLs.

## Recommended Agent Workflow

For registry authoring tasks, agents should:

1. Read `AGENTS.md`, this docs section, and `/llms.txt` or `/llms-full.txt` for project context.
2. Use the `shadcn-registry` skill when available.
3. Scaffold new items with `bun --bun ./scripts/new.ts --type <type> --name <kebab-name> --description "<description>"`.
4. Add `--target` for `registry:page`, `registry:file`, custom alias installs like `@ui/ai/<file>.tsx`, and targeted `registry:item` files; use `--file-extension` for `registry:file` and targeted `registry:item` files.
5. Edit the generated source, `_registry.mdx`, and `_preview.tsx` with usage docs, previews, and dependency metadata.
6. Run `vp check --fix` on touched files, `bun --bun ./scripts/doctor.ts`, and `vp build` before handoff when docs, routes, registry JSON, catalog loading, or source loading changed.


---

URL: https://mwui.vercel.app/docs/cli.md

Install items from this registry with the shadcn CLI.

# CLI

Install items from this registry with the shadcn CLI.

Install a registry item with the command shown on its docs page.

```sh
npx shadcn@latest add https://mwui.vercel.app/r/autosize-textarea.json
```

The command that's displayed uses the `homepage` value from `registry/config.ts` for the base URL.

Human-facing item pages also work with the shadcn CLI through content negotiation. For example, a browser can view [`/components/autosize-textarea`](/components/autosize-textarea), while the CLI receives the installable item JSON from the same URL:

```sh
npx shadcn@latest add https://mwui.vercel.app/components/autosize-textarea
```

Use the package manager selector on item pages to switch between npm, pnpm, yarn, bun, vite+, and deno commands.

## Endpoints

The registry index is served from both the root and the `/r` path, while installable item JSON lives
under `/r`:

| Route              | Serves                   |
| ------------------ | ------------------------ |
| `/registry.json`   | The registry index.      |
| `/r/registry.json` | The same registry index. |
| `/r/<name>.json`   | One installable item.    |

Authored metadata is validated against the schemas from
[`shadcn/schema`](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/registry/schema.ts),
so anything these routes serve is CLI-compatible.


---

URL: https://mwui.vercel.app/docs/theming.md

Customize the docs shell and published components with your own design tokens.

# Theming

Customize the docs shell and published components with your own design tokens.

The docs app uses the local shadcn configuration in `components.json` and the global theme in `src/styles.css`.

Published registry items are independent from the docs shell. Put installable component source in `registry/items/**`, and include any required CSS, dependencies, or registry dependencies in the item frontmatter.

Use semantic tokens such as `background`, `foreground`, `primary`, `muted`, and `border` so installed components remain easy to customize.


---

URL: https://mwui.vercel.app/components.md

Installable UI primitives and components.

# Components

Installable UI primitives and components.

- [Autosize Textarea](https://mwui.vercel.app/components/autosize-textarea): A textarea that grows with its content between row bounds.
- [Avatar Group](https://mwui.vercel.app/components/avatar-group): A stacked avatar row with overflow counting and tooltips.
- [Color Picker](https://mwui.vercel.app/components/color-picker): An accessible, composable color picker with a saturation area, hue and alpha sliders, eyedropper, swatches, and hex/rgb/hsl/oklch output.
- [Command Palette](https://mwui.vercel.app/components/command-palette): A searchable command palette with groups, nested pages, and recent actions.
- [Confirm Dialog](https://mwui.vercel.app/components/confirm-dialog): A promise-based confirmation dialog driven by an imperative confirm() call.
- [Copy Button](https://mwui.vercel.app/components/copy-button): A copy-to-clipboard button with success feedback.
- [Date Range Picker](https://mwui.vercel.app/components/date-range-picker): A date range picker with a self-contained calendar, quick presets, and keyboard-first navigation.
- [File Dropzone](https://mwui.vercel.app/components/file-dropzone): A drag-and-drop file input with previews, validation, and per-file progress.
- [Multi Select](https://mwui.vercel.app/components/multi-select): A multi-select combobox with chips, async search, and grouped options.
- [OTP Input](https://mwui.vercel.app/components/otp-input): A one-time-code input with per-character slots and paste support.
- [Phone Input](https://mwui.vercel.app/components/phone-input): An international phone input with country select and formatting.
- [Tags Input](https://mwui.vercel.app/components/tags-input): A free-form chip input with paste splitting, validation, and duplicate handling.
- [Time Picker](https://mwui.vercel.app/components/time-picker): A keyboard-first time input with 12/24-hour formats and step granularity.
- [Timeline](https://mwui.vercel.app/components/timeline): A vertical timeline for activity feeds and status history.


---

URL: https://mwui.vercel.app/components/autosize-textarea.md

A textarea that grows with its content between row bounds.

# Autosize Textarea

A textarea that grows with its content between row bounds.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/autosize-textarea.json
```

[Registry JSON](https://mwui.vercel.app/r/autosize-textarea.json)

## Preview

```tsx
import * as React from "react";

import { AutosizeTextarea } from "@/components/ui/autosize-textarea";

export function Preview() {
  const [message, setMessage] = React.useState(
    "Type a few lines here and watch the field grow.\nIt stops after six rows and scrolls instead.",
  );

  return (
    <div className="flex w-full max-w-sm flex-col gap-2 text-sm">
      <AutosizeTextarea
        value={message}
        onChange={(event) => setMessage(event.target.value)}
        minRows={2}
        maxRows={6}
        placeholder="Write a message…"
      />

      <p className="text-xs text-muted-foreground">
        {message.length} characters · {message.split("\n").length} lines
      </p>
    </div>
  );
}
```


## Source

### ui/autosize-textarea.tsx

```tsx
"use client";

import * as React from "react";

import { ScrollArea } from "@/components/ui/scroll-area";
import { useResizeObserver } from "@/hooks/use-resize-observer";
import { cn } from "@/lib/utils";

type AutosizeTextareaProps = Omit<React.ComponentProps<"textarea">, "rows"> & {
  minRows?: number;
  maxRows?: number;
  scrollArea?: boolean;
  onHeightChange?: (height: number) => void;
};

function AutosizeTextarea({
  minRows = 2,
  maxRows,
  scrollArea = true,
  onHeightChange,
  className,
  ref,
  value,
  defaultValue,
  onChange,
  ...props
}: AutosizeTextareaProps) {
  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
  const containerRef = React.useRef<HTMLDivElement>(null);
  const { ref: observerRef, width } = useResizeObserver<HTMLTextAreaElement>();

  const [internalValue, setInternalValue] = React.useState(defaultValue ?? "");
  const resolvedValue = value ?? internalValue;

  const scrolled = scrollArea && maxRows !== undefined;

  const onHeightChangeRef = React.useRef(onHeightChange);

  React.useEffect(() => {
    onHeightChangeRef.current = onHeightChange;
  });

  const setRefs = React.useCallback(
    (node: HTMLTextAreaElement | null) => {
      textareaRef.current = node;
      observerRef(node);

      if (typeof ref === "function") {
        ref(node);
      } else if (ref) {
        ref.current = node;
      }
    },
    [observerRef, ref],
  );

  React.useLayoutEffect(() => {
    const textarea = textareaRef.current;
    if (!textarea) return;

    const styles = getComputedStyle(textarea);
    const lineHeight = Number.parseFloat(styles.lineHeight) || 20;
    const padding = Number.parseFloat(styles.paddingTop) + Number.parseFloat(styles.paddingBottom);
    const border =
      Number.parseFloat(styles.borderTopWidth) + Number.parseFloat(styles.borderBottomWidth);

    textarea.style.height = "auto";

    const contentHeight = textarea.scrollHeight + border;
    const minHeight = minRows * lineHeight + padding + border;
    const maxHeight = maxRows === undefined ? Infinity : maxRows * lineHeight + padding + border;

    const height = scrolled
      ? Math.max(contentHeight, minHeight)
      : Math.min(Math.max(contentHeight, minHeight), maxHeight);

    textarea.style.height = `${height}px`;
    textarea.style.overflowY = !scrolled && contentHeight > maxHeight ? "auto" : "hidden";

    const container = containerRef.current;

    if (container) {
      // The viewport is the element that actually scrolls, so the row cap belongs on it.
      const viewport =
        container.querySelector<HTMLElement>("[data-slot=scroll-area-viewport]") ?? container;

      viewport.style.maxHeight = `${maxHeight}px`;
      container.style.maxHeight = `${maxHeight}px`;
    }

    onHeightChangeRef.current?.(Math.min(height, maxHeight));
  }, [resolvedValue, width, minRows, maxRows, scrolled]);

  const field = (
    <textarea
      ref={setRefs}
      data-slot="autosize-textarea"
      value={value}
      defaultValue={defaultValue}
      rows={minRows}
      onChange={(event) => {
        if (value === undefined) setInternalValue(event.target.value);
        onChange?.(event);
      }}
      className={cn(
        "block w-full resize-none bg-transparent px-2.5 py-1.5 text-base outline-none",
        "placeholder:text-muted-foreground md:text-sm",
        scrolled
          ? "disabled:cursor-not-allowed"
          : [
              "rounded-lg border border-input transition-colors dark:bg-input/30",
              "focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
              "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
              "aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20",
            ],
        // The container owns the frame once it exists, so `className` styles that instead.
        !scrolled && className,
      )}
      {...props}
    />
  );

  if (!scrolled) return field;

  return (
    <ScrollArea
      ref={containerRef}
      className={cn(
        "w-full rounded-lg border border-input bg-transparent transition-colors dark:bg-input/30",
        "focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
        "has-[textarea:disabled]:pointer-events-none has-[textarea:disabled]:opacity-50",
        "has-[textarea[aria-invalid=true]]:border-destructive has-[textarea[aria-invalid=true]]:ring-3 has-[textarea[aria-invalid=true]]:ring-destructive/20",
        className,
      )}
    >
      {field}
    </ScrollArea>
  );
}

export { AutosizeTextarea, type AutosizeTextareaProps };
```



## Usage

A textarea that starts at a comfortable size, grows as the message gets longer, and stops growing
before it eats the page. The interaction every composer, comment box, and prompt field needs.

```tsx
import { AutosizeTextarea } from "@/components/ui/autosize-textarea";

export function Composer() {
  const [message, setMessage] = React.useState("");

  return (
    <AutosizeTextarea
      value={message}
      onChange={(event) => setMessage(event.target.value)}
      minRows={2}
      maxRows={10}
      placeholder="Write a message…"
    />
  );
}
```

Past `maxRows` the field stops growing and scrolls internally. Without a maximum it grows without
limit, which is fine inside a page but wrong inside a fixed composer.

It is a real `<textarea>` — every prop, `ref`, and form behavior passes straight through — so
`required`, `maxLength`, `name`, and controlled or uncontrolled use all work as usual.

## Scrolling past `maxRows`

A `<textarea>` is its own scroll container, so capping its height normally hands you the native
scrollbar — the one piece of a styled form that still looks like the operating system. Instead the
field is allowed to grow to its full content height and a [ScrollArea](https://ui.shadcn.com/docs/components/scroll-area)
clips it to the row cap, so the overflow gets the same overlay scrollbar as the rest of the app.

The frame — border, background, focus ring, invalid state — moves to that container, and `className`
follows it, so styling the component still means styling the box you can see. Typing still keeps the
caret in view: the browser scrolls the nearest scrollable ancestor, which is now the viewport.

```tsx
<AutosizeTextarea maxRows={6} scrollArea={false} />
```

Pass `scrollArea={false}` for the native scrollbar and a plain `<textarea>` with no wrapper — worth
it if you are dropping the field into something that already measures or scrolls its children. The
prop does nothing without `maxRows`, since an unbounded field never scrolls.

## Why not `field-sizing: content`

The CSS property does this natively in one line, and it is the right answer once support is
universal. Today it is missing in Safari and Firefox, where the field would silently stop resizing.
This measures instead, so it behaves the same everywhere.

## Resizing when the width changes

Height depends on width: a sidebar collapsing, a modal opening, or a window resize can rewrap the
text and change how many lines it takes. The component observes its own width with
[useResizeObserver](/utilities/use-resize-observer) and re-measures — which a value-only effect
would miss, leaving a field that is suddenly too short.

## Props

| Prop             | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `minRows`        | Starting height in rows. Defaults to `2`.                           |
| `maxRows`        | Stop growing after this many rows and scroll. Omit for no limit.     |
| `scrollArea`     | Scroll the overflow inside a `ScrollArea` instead of the native textarea scrollbar. Defaults to `true`. Needs `maxRows`. |
| `onHeightChange` | Called with the new pixel height — useful for keeping a scroll container pinned to the bottom. |

Everything else is forwarded to the underlying `textarea`.

## Behavior

- Measurement runs in a layout effect, before paint, so the height never flickers.
- `line-height` and padding are read from the computed style, so the row math follows your CSS
  instead of a hardcoded number.
- Manual resizing is disabled, since the drag handle would fight the automatic height.
- `onHeightChange` reports the visible height, so it stops at `maxRows` rather than reporting the
  full content height of a scrolled field.


---

URL: https://mwui.vercel.app/components/avatar-group.md

A stacked avatar row with overflow counting and tooltips.

# Avatar Group

A stacked avatar row with overflow counting and tooltips.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/avatar-group.json
```

[Registry JSON](https://mwui.vercel.app/r/avatar-group.json)

## Preview

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group";

const PEOPLE = [
  { id: "alice", name: "Alice Nguyen" },
  { id: "bruno", name: "Bruno Costa" },
  { id: "chen", name: "Chen Wei" },
  { id: "dara", name: "Dara Okafor" },
  { id: "elif", name: "Elif Demir" },
  { id: "farid", name: "Farid Haddad" },
  { id: "gita", name: "Gita Rao" },
];

export function Preview() {
  return (
    <div className="flex flex-col gap-6 text-sm">
      <div className="flex flex-col gap-2">
        <p className="font-medium">Default</p>
        <AvatarGroup people={PEOPLE} max={4} aria-label="Project members" />
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Small, more visible</p>
        <AvatarGroup people={PEOPLE} size="sm" max={6} aria-label="Reviewers" />
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Large, no overflow</p>
        <AvatarGroup people={PEOPLE.slice(0, 3)} size="lg" aria-label="Owners" />
      </div>
    </div>
  );
}
```


## Source

### ui/avatar-group.tsx

```tsx
"use client";

import { cva, type VariantProps } from "class-variance-authority";
import * as React from "react";

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";

const avatarVariants = cva(
  // The ring punches a gap between overlapping avatars, so it has to match whatever
  // surface sits behind them. Override with [--avatar-ring:var(--card)] on the group.
  "relative flex shrink-0 items-center justify-center overflow-hidden rounded-full bg-muted font-medium text-muted-foreground ring-2 ring-[var(--avatar-ring,var(--background))] select-none",
  {
    variants: {
      size: {
        xs: "size-5 text-[0.625rem]",
        sm: "size-6 text-[0.6875rem]",
        default: "size-8 text-xs",
        lg: "size-10 text-sm",
      },
    },
    defaultVariants: {
      size: "default",
    },
  },
);

const overlapBySize = {
  xs: "-ml-1.5",
  sm: "-ml-2",
  default: "-ml-2.5",
  lg: "-ml-3",
} as const;

type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;

type AvatarGroupPerson = {
  id?: string;
  name: string;
  src?: string;
  initials?: string;
  href?: string;
};

type AvatarProps = React.ComponentProps<"span"> &
  VariantProps<typeof avatarVariants> & {
    name: string;
    src?: string;
    initials?: string;
  };

function Avatar({ name, src, initials, size, className, ...props }: AvatarProps) {
  const [failed, setFailed] = React.useState(false);
  const showImage = src !== undefined && !failed;

  return (
    <span
      data-slot="avatar"
      className={cn(avatarVariants({ size }), className)}
      title={props.title ?? undefined}
      {...props}
    >
      {showImage ? (
        <img
          src={src}
          alt={name}
          loading="lazy"
          className="size-full object-cover"
          onError={() => setFailed(true)}
        />
      ) : (
        <span aria-hidden="true">{initials ?? getInitials(name)}</span>
      )}
      {showImage ? null : <span className="sr-only">{name}</span>}
    </span>
  );
}

type AvatarGroupProps = React.ComponentProps<"div"> &
  VariantProps<typeof avatarVariants> & {
    people: AvatarGroupPerson[];
    max?: number;
    tooltips?: boolean;
    "aria-label"?: string;
  };

function AvatarGroup({
  people,
  max = 4,
  size = "default",
  tooltips = true,
  className,
  "aria-label": ariaLabel = "People",
  ...props
}: AvatarGroupProps) {
  const visible = people.slice(0, max);
  const overflow = people.slice(max);
  const overlap = overlapBySize[(size ?? "default") as AvatarSize];

  return (
    <div
      data-slot="avatar-group"
      role="group"
      aria-label={ariaLabel}
      className={cn("flex items-center", className)}
      {...props}
    >
      {visible.map((person, index) => (
        <AvatarGroupMember
          key={person.id ?? person.name}
          person={person}
          size={size}
          tooltips={tooltips}
          className={index === 0 ? undefined : overlap}
        />
      ))}

      {overflow.length > 0 ? (
        <OptionalTooltip
          enabled={tooltips}
          label={overflow.map((person) => person.name).join(", ")}
        >
          <span
            data-slot="avatar-group-overflow"
            className={cn(avatarVariants({ size }), overlap, "bg-muted text-muted-foreground")}
          >
            <span aria-hidden="true">+{overflow.length}</span>
            <span className="sr-only">{overflow.length} more</span>
          </span>
        </OptionalTooltip>
      ) : null}
    </div>
  );
}

function AvatarGroupMember({
  person,
  size,
  tooltips,
  className,
}: {
  person: AvatarGroupPerson;
  size: VariantProps<typeof avatarVariants>["size"];
  tooltips: boolean;
  className?: string;
}) {
  const avatar = (
    <Avatar
      name={person.name}
      src={person.src}
      initials={person.initials}
      size={size}
      className={cn("transition-transform hover:z-10 hover:-translate-y-0.5", className)}
    />
  );

  if (person.href) {
    return (
      <OptionalTooltip enabled={tooltips} label={person.name}>
        <a
          href={person.href}
          className="rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
        >
          {avatar}
        </a>
      </OptionalTooltip>
    );
  }

  return (
    <OptionalTooltip enabled={tooltips} label={person.name}>
      {avatar}
    </OptionalTooltip>
  );
}

function OptionalTooltip({
  enabled,
  label,
  children,
}: {
  enabled: boolean;
  label: string;
  children: React.ReactElement;
}) {
  if (!enabled) return children;

  return (
    <Tooltip>
      <TooltipTrigger render={children} />
      <TooltipContent>{label}</TooltipContent>
    </Tooltip>
  );
}

function getInitials(name: string): string {
  const parts = name.trim().split(/\s+/u).filter(Boolean);

  if (parts.length === 0) return "?";
  if (parts.length === 1) return (parts[0] ?? "").slice(0, 2).toUpperCase();

  return `${(parts[0] ?? "").charAt(0)}${(parts[parts.length - 1] ?? "").charAt(0)}`.toUpperCase();
}

export {
  Avatar,
  AvatarGroup,
  avatarVariants,
  type AvatarGroupPerson,
  type AvatarGroupProps,
  type AvatarProps,
};
```



## Usage

The row of overlapping faces that shows who is on a project, in a thread, or assigned to a task —
with the "+3" that keeps it from taking over the layout.

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group";

const PEOPLE = [
  { id: "1", name: "Alice Nguyen", src: "/avatars/alice.jpg" },
  { id: "2", name: "Bruno Costa" },
  { id: "3", name: "Chen Wei", src: "/avatars/chen.jpg" },
];

<AvatarGroup people={PEOPLE} max={4} />;
```

Self-contained — no separate avatar dependency to install. `Avatar` is exported too, for the places
you need a single one.

## Images and initials

`src` is optional. Without it — or when the image fails to load, which is the common case with
user-supplied URLs — the avatar falls back to initials derived from `name`. Pass `initials` to
override, which matters for names the two-word heuristic gets wrong.

## Overflow

`max` counts avatars, not people: with `max={4}` and six people you see four faces and a `+2`. The
counter's tooltip lists everyone it hides, so the information is still reachable.

## Sizes

`xs`, `sm`, `default`, and `lg`. The overlap scales with the size, so the stack keeps its proportions.

```tsx
<AvatarGroup people={PEOPLE} size="xs" max={6} />
```

## Ring color

Overlapping avatars are separated by a ring that punches a gap in the surface behind them, so it has
to match that surface. It defaults to `var(--background)`, which is right on the page but wrong
anywhere the background differs — inside a `Card`, a popover, or a muted panel, where the ring reads
as a dark outline in dark mode.

Set `--avatar-ring` on any ancestor to correct it. Custom properties inherit, so one declaration
covers every avatar inside, including standalone `Avatar` elements:

```tsx
<Card className="[--avatar-ring:var(--card)]">
  <AvatarGroup people={PEOPLE} />
</Card>
```

In the default theme the light palette gives `--background` and `--card` the same value, so a missing
override only shows up in dark mode. Check both.

## Props

| Prop         | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `people`     | `{ id?, name, src?, initials?, href? }[]`. `href` makes the avatar a link. |
| `max`        | Avatars shown before collapsing. Defaults to `4`.                       |
| `size`       | `"xs"`, `"sm"`, `"default"`, `"lg"`.                                     |
| `tooltips`   | Name on hover and focus. On by default.                                  |
| `aria-label` | Labels the group. Defaults to `"People"`.                                |

## Accessibility

Names are not decoration: an avatar rendering an image uses the name as its `alt`, and an avatar
rendering initials keeps the full name in visually hidden text — so the group reads as a list of
people rather than "image, image, image". The overflow counter announces "3 more".

Tooltips only appear on hover and focus, so the name must also exist in the accessible name for
touch users. That is why both are present.


---

URL: https://mwui.vercel.app/components/color-picker.md

An accessible, composable color picker with a saturation area, hue and alpha sliders, eyedropper, swatches, and hex/rgb/hsl/oklch output.

# Color Picker

An accessible, composable color picker with a saturation area, hue and alpha sliders, eyedropper, swatches, and hex/rgb/hsl/oklch output.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/color-picker.json
```

[Registry JSON](https://mwui.vercel.app/r/color-picker.json)

## Preview

```tsx
import * as React from "react";

import {
  ColorPicker,
  ColorPickerAlpha,
  ColorPickerArea,
  ColorPickerEyeDropper,
  ColorPickerFormatSelect,
  ColorPickerHue,
  ColorPickerInput,
  ColorPickerPreview,
  ColorPickerSwatch,
  ColorPickerSwatches,
} from "@/components/ui/color-picker";

const SWATCHES = [
  "#000000",
  "#64748b",
  "#ef4444",
  "#f97316",
  "#eab308",
  "#22c55e",
  "#06b6d4",
  "#3b82f6",
  "#8b5cf6",
  "#ec4899",
];

export function Preview() {
  const [color, setColor] = React.useState("#3b82f6");

  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <ColorPicker value={color} onValueChange={setColor} className="rounded-xl border p-3">
        <ColorPickerArea />

        <div className="flex items-center gap-3">
          <ColorPickerEyeDropper />
          <div className="flex min-w-0 flex-1 flex-col gap-2">
            <ColorPickerHue />
            <ColorPickerAlpha />
          </div>
          <ColorPickerPreview />
        </div>

        <ColorPickerFormatSelect className="w-full *:flex-1" />
        <ColorPickerInput alpha />

        <ColorPickerSwatches>
          {SWATCHES.map((swatch) => (
            <ColorPickerSwatch key={swatch} value={swatch} />
          ))}
        </ColorPickerSwatches>
      </ColorPicker>

      <p className="text-center font-mono text-xs text-muted-foreground">{color}</p>
    </div>
  );
}
```


## Source

### ui/color-picker.tsx

```tsx
"use client";

import { IconCheck, IconColorPicker } from "@tabler/icons-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import { ButtonGroup } from "@/components/ui/button-group";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
import { cn } from "@/lib/utils";

type ColorFormat = "hex" | "rgb" | "hsl" | "oklch";

type Hsva = { h: number; s: number; v: number; a: number };

type Rgb = { r: number; g: number; b: number };

type Oklch = { l: number; c: number; h: number };

const BLACK: Hsva = { h: 0, s: 0, v: 0, a: 1 };

function clamp(value: number, min = 0, max = 1) {
  return Math.min(max, Math.max(min, value));
}

function normalizeHue(hue: number) {
  return ((hue % 360) + 360) % 360;
}

function round(value: number, precision = 0) {
  const factor = 10 ** precision;
  return Math.round(value * factor) / factor;
}

function hsvaToRgb({ h, s, v }: Hsva): Rgb {
  const hue = normalizeHue(h);
  const chroma = v * s;
  const x = chroma * (1 - Math.abs(((hue / 60) % 2) - 1));
  const m = v - chroma;
  const [r, g, b] =
    hue < 60
      ? [chroma, x, 0]
      : hue < 120
        ? [x, chroma, 0]
        : hue < 180
          ? [0, chroma, x]
          : hue < 240
            ? [0, x, chroma]
            : hue < 300
              ? [x, 0, chroma]
              : [chroma, 0, x];

  return {
    r: Math.round((r + m) * 255),
    g: Math.round((g + m) * 255),
    b: Math.round((b + m) * 255),
  };
}

function rgbToHsv({ r, g, b }: Rgb): Omit<Hsva, "a"> {
  const red = r / 255;
  const green = g / 255;
  const blue = b / 255;
  const max = Math.max(red, green, blue);
  const min = Math.min(red, green, blue);
  const delta = max - min;

  let h = 0;
  if (delta !== 0) {
    if (max === red) h = ((green - blue) / delta + 6) % 6;
    else if (max === green) h = (blue - red) / delta + 2;
    else h = (red - green) / delta + 4;
    h *= 60;
  }

  return { h, s: max === 0 ? 0 : delta / max, v: max };
}

function hsvToHsl({ h, s, v }: Omit<Hsva, "a">) {
  const l = v * (1 - s / 2);
  const saturation = l === 0 || l === 1 ? 0 : (v - l) / Math.min(l, 1 - l);
  return { h, s: saturation, l };
}

function hslToHsv({ h, s, l }: { h: number; s: number; l: number }) {
  const v = l + s * Math.min(l, 1 - l);
  return { h, s: v === 0 ? 0 : 2 * (1 - l / v), v };
}

const SRGB_LINEAR_THRESHOLD = 0.04045;

function srgbToLinear(channel: number) {
  return channel <= SRGB_LINEAR_THRESHOLD ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
}

function linearToSrgb(channel: number) {
  return channel <= 0.0031308 ? channel * 12.92 : 1.055 * channel ** (1 / 2.4) - 0.055;
}

function rgbToOklch({ r, g, b }: Rgb): Oklch {
  const red = srgbToLinear(r / 255);
  const green = srgbToLinear(g / 255);
  const blue = srgbToLinear(b / 255);

  const l = Math.cbrt(0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue);
  const m = Math.cbrt(0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue);
  const s = Math.cbrt(0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue);

  const lightness = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;

  return {
    l: lightness,
    c: Math.sqrt(a * a + bb * bb),
    h: normalizeHue((Math.atan2(bb, a) * 180) / Math.PI),
  };
}

function oklchToRgb({ l, c, h }: Oklch): Rgb {
  const hueRadians = (normalizeHue(h) * Math.PI) / 180;
  const a = c * Math.cos(hueRadians);
  const b = c * Math.sin(hueRadians);

  const lCubed = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
  const mCubed = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
  const sCubed = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;

  const red = 4.0767416621 * lCubed - 3.3077115913 * mCubed + 0.2309699292 * sCubed;
  const green = -1.2684380046 * lCubed + 2.6097574011 * mCubed - 0.3413193965 * sCubed;
  const blue = -0.0041960863 * lCubed - 0.7034186147 * mCubed + 1.707614701 * sCubed;

  return {
    r: Math.round(clamp(linearToSrgb(red)) * 255),
    g: Math.round(clamp(linearToSrgb(green)) * 255),
    b: Math.round(clamp(linearToSrgb(blue)) * 255),
  };
}

function expandShorthandHex(hex: string) {
  return hex
    .split("")
    .map((character) => character + character)
    .join("");
}

function parseHex(input: string): Hsva | null {
  const hex = input.replace(/^#/, "").toLowerCase();
  if (!/^[0-9a-f]+$/.test(hex)) return null;

  const expanded = hex.length === 3 || hex.length === 4 ? expandShorthandHex(hex) : hex;
  if (expanded.length !== 6 && expanded.length !== 8) return null;

  const rgb = {
    r: Number.parseInt(expanded.slice(0, 2), 16),
    g: Number.parseInt(expanded.slice(2, 4), 16),
    b: Number.parseInt(expanded.slice(4, 6), 16),
  };
  const alpha = expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1;

  return { ...rgbToHsv(rgb), a: alpha };
}

function parseFunctionalNotation(input: string) {
  const match = /^([a-z]+)\(([^)]*)\)$/.exec(input);
  if (!match) return null;

  const [, name, body] = match;
  const [values, alphaPart] = body.split("/");
  const args = values
    .trim()
    .split(/[\s,]+/)
    .filter(Boolean);
  const alphaArgs =
    alphaPart
      ?.trim()
      .split(/[\s,]+/)
      .filter(Boolean) ?? [];

  const alphaToken = alphaArgs[0] ?? (args.length > 3 ? args[3] : undefined);

  return { name, args, alphaToken };
}

function readNumber(token: string | undefined, scaleIfPercent: number) {
  if (token === undefined) return null;
  const value = Number.parseFloat(token);
  if (Number.isNaN(value)) return null;
  return token.endsWith("%") ? (value / 100) * scaleIfPercent : value;
}

function readAlpha(token: string | undefined) {
  const alpha = readNumber(token, 1);
  return alpha === null ? 1 : clamp(alpha);
}

function parseColor(input: string): Hsva | null {
  const value = input.trim().toLowerCase();
  if (!value) return null;
  if (value === "transparent") return { ...BLACK, a: 0 };
  if (value.startsWith("#") || /^[0-9a-f]{3,8}$/.test(value)) return parseHex(value);

  const parsed = parseFunctionalNotation(value);
  if (!parsed) return null;

  const { name, args, alphaToken } = parsed;
  const alpha = readAlpha(alphaToken);

  if (name === "rgb" || name === "rgba") {
    const r = readNumber(args[0], 255);
    const g = readNumber(args[1], 255);
    const b = readNumber(args[2], 255);
    if (r === null || g === null || b === null) return null;
    return {
      ...rgbToHsv({ r: clamp(r, 0, 255), g: clamp(g, 0, 255), b: clamp(b, 0, 255) }),
      a: alpha,
    };
  }

  if (name === "hsl" || name === "hsla") {
    const h = readNumber(args[0], 360);
    const s = readNumber(args[1], 1);
    const l = readNumber(args[2], 1);
    if (h === null || s === null || l === null) return null;
    const saturation = args[1]?.endsWith("%") ? s : s / 100;
    const lightness = args[2]?.endsWith("%") ? l : l / 100;
    return { ...hslToHsv({ h, s: clamp(saturation), l: clamp(lightness) }), a: alpha };
  }

  if (name === "oklch") {
    const l = readNumber(args[0], 1);
    const c = readNumber(args[1], 0.4);
    const h = readNumber(args[2], 360);
    if (l === null || c === null || h === null) return null;
    return { ...rgbToHsv(oklchToRgb({ l: clamp(l), c: Math.max(0, c), h })), a: alpha };
  }

  return null;
}

function toHex(hsva: Hsva, { alpha = true }: { alpha?: boolean } = {}) {
  const { r, g, b } = hsvaToRgb(hsva);
  const channels = [r, g, b];
  if (alpha && hsva.a < 1) channels.push(Math.round(hsva.a * 255));
  return `#${channels.map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
}

function formatColor(hsva: Hsva, format: ColorFormat): string {
  const alpha = round(hsva.a, 3);
  const alphaSuffix = alpha < 1 ? ` / ${alpha}` : "";

  if (format === "hex") return toHex(hsva);

  if (format === "rgb") {
    const { r, g, b } = hsvaToRgb(hsva);
    return `rgb(${r} ${g} ${b}${alphaSuffix})`;
  }

  if (format === "hsl") {
    const { h, s, l } = hsvToHsl(hsva);
    return `hsl(${round(normalizeHue(h), 2)} ${round(s * 100, 2)}% ${round(l * 100, 2)}%${alphaSuffix})`;
  }

  const { l, c, h } = rgbToOklch(hsvaToRgb(hsva));
  return `oklch(${round(l, 4)} ${round(c, 4)} ${round(h, 2)}${alphaSuffix})`;
}

const HUE_ANCHORS: [angle: number, name: string][] = [
  [29, "red"],
  [55, "orange"],
  [85, "orange yellow"],
  [110, "yellow"],
  [128, "yellow green"],
  [142, "green"],
  [170, "green cyan"],
  [195, "cyan"],
  [230, "blue cyan"],
  [264, "blue"],
  [290, "blue purple"],
  [310, "purple"],
  [328, "magenta"],
  [350, "pink"],
];

function nameHue(oklchHue: number) {
  let closest = HUE_ANCHORS[0];
  let smallestDistance = Number.POSITIVE_INFINITY;

  for (const anchor of HUE_ANCHORS) {
    const difference = Math.abs(normalizeHue(oklchHue - anchor[0]));
    const distance = Math.min(difference, 360 - difference);
    if (distance < smallestDistance) {
      smallestDistance = distance;
      closest = anchor;
    }
  }

  return closest[1];
}

function describeColor(hsva: Hsva): string {
  if (hsva.a === 0) return "transparent";

  const { l, c, h } = rgbToOklch(hsvaToRgb(hsva));
  if (l < 0.08) return "black";
  if (l > 0.97 && c < 0.02) return "white";

  const lightness =
    l < 0.3
      ? "very dark "
      : l < 0.45
        ? "dark "
        : l < 0.72
          ? ""
          : l < 0.88
            ? "light "
            : "very light ";

  if (c < 0.025) return `${lightness}gray`.trim();

  const chroma = c < 0.06 ? "grayish " : c < 0.12 ? "muted " : c > 0.2 ? "vibrant " : "";
  const hue = nameHue(h);

  if (l < 0.55 && (hue === "orange" || hue === "orange yellow")) {
    return `${lightness}${chroma}brown`.trim();
  }

  return `${lightness}${chroma}${hue}`.trim();
}

const CHECKERBOARD_STYLE: React.CSSProperties = {
  backgroundColor: "#fff",
  backgroundImage:
    "linear-gradient(45deg, rgb(0 0 0 / 0.12) 25%, transparent 25% 75%, rgb(0 0 0 / 0.12) 75%), linear-gradient(45deg, rgb(0 0 0 / 0.12) 25%, transparent 25% 75%, rgb(0 0 0 / 0.12) 75%)",
  backgroundSize: "8px 8px",
  backgroundPosition: "0 0, 4px 4px",
};

const HUE_GRADIENT =
  "linear-gradient(to right, hsl(0 100% 50%), hsl(60 100% 50%), hsl(120 100% 50%), hsl(180 100% 50%), hsl(240 100% 50%), hsl(300 100% 50%), hsl(360 100% 50%))";

const thumbClassName =
  "pointer-events-none absolute size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_1px_rgb(0_0_0/0.35),0_1px_2px_rgb(0_0_0/0.25)]";

const trackClassName =
  "relative h-3 w-full touch-none rounded-full outline-none select-none has-[input:focus-visible]:ring-3 has-[input:focus-visible]:ring-ring/50 data-disabled:pointer-events-none data-disabled:opacity-50";

const srOnlyClassName =
  "absolute size-px overflow-hidden [clip-path:inset(50%)] whitespace-nowrap border-0 p-0 m-0";

type ColorPickerContextValue = {
  hsva: Hsva;
  setColor: (next: Hsva | ((previous: Hsva) => Hsva)) => void;
  rgb: Rgb;
  hex: string;
  cssColor: string;
  value: string;
  format: ColorFormat;
  setFormat: (format: ColorFormat) => void;
  description: string;
  disabled: boolean;
};

const ColorPickerContext = React.createContext<ColorPickerContextValue | null>(null);

function useColorPicker() {
  const context = React.useContext(ColorPickerContext);
  if (!context) {
    throw new Error("useColorPicker must be used within a <ColorPicker />.");
  }
  return context;
}

type ColorPickerProps = Omit<React.ComponentProps<"div">, "color" | "defaultValue" | "onChange"> & {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  format?: ColorFormat;
  defaultFormat?: ColorFormat;
  onFormatChange?: (format: ColorFormat) => void;
  disabled?: boolean;
  name?: string;
};

function ColorPicker({
  value,
  defaultValue = "#000000",
  onValueChange,
  format,
  defaultFormat = "hex",
  onFormatChange,
  disabled = false,
  name,
  className,
  children,
  ...props
}: ColorPickerProps) {
  const [uncontrolledFormat, setUncontrolledFormat] = React.useState(defaultFormat);
  const activeFormat = format ?? uncontrolledFormat;

  const [uncontrolledColor, setUncontrolledColor] = React.useState(
    () => parseColor(defaultValue) ?? BLACK,
  );

  const emitted = React.useRef<{ text: string; hsva: Hsva } | null>(null);

  const isControlled = value !== undefined;
  const hsva = React.useMemo(() => {
    if (!isControlled) return uncontrolledColor;
    if (emitted.current?.text === value) return emitted.current.hsva;
    return parseColor(value) ?? BLACK;
  }, [isControlled, value, uncontrolledColor]);

  const emit = React.useCallback(
    (next: Hsva, nextFormat: ColorFormat) => {
      const text = formatColor(next, nextFormat);
      emitted.current = { text, hsva: next };
      if (!isControlled) setUncontrolledColor(next);
      onValueChange?.(text);
      return text;
    },
    [isControlled, onValueChange],
  );

  const setColor = React.useCallback<ColorPickerContextValue["setColor"]>(
    (next) => {
      if (disabled) return;
      emit(typeof next === "function" ? next(hsva) : next, activeFormat);
    },
    [disabled, emit, hsva, activeFormat],
  );

  const setFormat = React.useCallback(
    (nextFormat: ColorFormat) => {
      if (disabled || nextFormat === activeFormat) return;
      if (format === undefined) setUncontrolledFormat(nextFormat);
      onFormatChange?.(nextFormat);
      emit(hsva, nextFormat);
    },
    [disabled, activeFormat, format, onFormatChange, emit, hsva],
  );

  const contextValue = React.useMemo<ColorPickerContextValue>(() => {
    const rgb = hsvaToRgb(hsva);
    return {
      hsva,
      setColor,
      rgb,
      hex: toHex(hsva, { alpha: false }),
      cssColor: `rgb(${rgb.r} ${rgb.g} ${rgb.b} / ${round(hsva.a, 3)})`,
      value: formatColor(hsva, activeFormat),
      format: activeFormat,
      setFormat,
      description: describeColor(hsva),
      disabled,
    };
  }, [hsva, setColor, activeFormat, setFormat, disabled]);

  return (
    <ColorPickerContext.Provider value={contextValue}>
      <div
        data-slot="color-picker"
        data-disabled={disabled || undefined}
        className={cn("flex w-full flex-col gap-3", className)}
        {...props}
      >
        {children}
        {name ? <input type="hidden" name={name} value={contextValue.value} /> : null}
      </div>
    </ColorPickerContext.Provider>
  );
}

const AREA_STEP = 0.01;
const AREA_LARGE_STEP = 0.1;

function ColorPickerArea({
  className,
  style,
  ...props
}: Omit<React.ComponentProps<"div">, "onChange">) {
  const { hsva, setColor, disabled, description } = useColorPicker();
  const areaRef = React.useRef<HTMLDivElement>(null);

  const commitFromPointer = (clientX: number, clientY: number) => {
    const area = areaRef.current;
    if (!area) return;
    const rect = area.getBoundingClientRect();
    setColor((previous) => ({
      ...previous,
      s: clamp((clientX - rect.left) / rect.width),
      v: 1 - clamp((clientY - rect.top) / rect.height),
    }));
  };

  const handlePointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    if (disabled || event.button !== 0) return;
    event.currentTarget.setPointerCapture(event.pointerId);
    commitFromPointer(event.clientX, event.clientY);
  };

  const handlePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    if (!event.currentTarget.hasPointerCapture(event.pointerId)) return;
    commitFromPointer(event.clientX, event.clientY);
  };

  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    const step = event.shiftKey ? AREA_LARGE_STEP : AREA_STEP;
    const nudge = (axis: "s" | "v", delta: number) => {
      event.preventDefault();
      setColor((previous) => ({ ...previous, [axis]: clamp(previous[axis] + delta) }));
    };

    switch (event.key) {
      case "ArrowLeft":
        return nudge("s", -step);
      case "ArrowRight":
        return nudge("s", step);
      case "ArrowUp":
        return nudge("v", step);
      case "ArrowDown":
        return nudge("v", -step);
      case "PageUp":
        return nudge("v", AREA_LARGE_STEP);
      case "PageDown":
        return nudge("v", -AREA_LARGE_STEP);
      case "Home":
        event.preventDefault();
        return setColor((previous) => ({ ...previous, s: 0 }));
      case "End":
        event.preventDefault();
        return setColor((previous) => ({ ...previous, s: 1 }));
      default:
    }
  };

  const saturation = Math.round(hsva.s * 100);
  const brightness = Math.round(hsva.v * 100);

  const axisInputProps = {
    min: 0,
    max: 100,
    step: 1,
    disabled,
    className: srOnlyClassName,
    onKeyDown: handleKeyDown,
  };

  return (
    <div
      ref={areaRef}
      data-slot="color-picker-area"
      data-disabled={disabled || undefined}
      role="group"
      aria-label="Saturation and brightness"
      className={cn(
        "relative aspect-4/3 w-full touch-none rounded-lg outline-none select-none",
        "has-[input:focus-visible]:ring-3 has-[input:focus-visible]:ring-ring/50",
        "data-disabled:pointer-events-none data-disabled:opacity-50",
        !disabled && "cursor-crosshair",
        className,
      )}
      style={{
        backgroundColor: `hsl(${round(normalizeHue(hsva.h), 2)} 100% 50%)`,
        backgroundImage:
          "linear-gradient(to top, rgb(0 0 0) 0%, rgb(0 0 0 / 0) 100%), linear-gradient(to right, rgb(255 255 255) 0%, rgb(255 255 255 / 0) 100%)",
        ...style,
      }}
      onPointerDown={handlePointerDown}
      onPointerMove={handlePointerMove}
      {...props}
    >
      <input
        type="range"
        {...axisInputProps}
        aria-label="Saturation"
        aria-valuetext={`${saturation}%, ${description}`}
        value={saturation}
        onChange={(event) =>
          setColor((previous) => ({ ...previous, s: Number(event.target.value) / 100 }))
        }
      />
      <input
        type="range"
        {...axisInputProps}
        aria-label="Brightness"
        aria-valuetext={`${brightness}%, ${description}`}
        value={brightness}
        onChange={(event) =>
          setColor((previous) => ({ ...previous, v: Number(event.target.value) / 100 }))
        }
      />
      <div
        data-slot="color-picker-area-thumb"
        aria-hidden="true"
        className={thumbClassName}
        style={{
          left: `${hsva.s * 100}%`,
          top: `${(1 - hsva.v) * 100}%`,
          backgroundColor: toHex({ ...hsva, a: 1 }),
        }}
      />
    </div>
  );
}

type SliderTrackProps = Omit<React.ComponentProps<"div">, "onChange"> & {
  slot: string;
  label: string;
  valueText: string;
  min: number;
  max: number;
  step: number;
  largeStep: number;
  value: number;
  onValueChange: (value: number) => void;
  trackStyle: React.CSSProperties;
  thumbColor: string;
};

function SliderTrack({
  slot,
  label,
  valueText,
  min,
  max,
  step,
  largeStep,
  value,
  onValueChange,
  trackStyle,
  thumbColor,
  className,
  style,
  ...props
}: SliderTrackProps) {
  const { disabled } = useColorPicker();
  const trackRef = React.useRef<HTMLDivElement>(null);

  const commitFromPointer = (clientX: number) => {
    const track = trackRef.current;
    if (!track) return;
    const rect = track.getBoundingClientRect();
    const ratio = clamp((clientX - rect.left) / rect.width);
    const raw = min + ratio * (max - min);
    onValueChange(clamp(Math.round(raw / step) * step, min, max));
  };

  const handlePointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    if (disabled || event.button !== 0) return;
    event.currentTarget.setPointerCapture(event.pointerId);
    commitFromPointer(event.clientX);
  };

  const handlePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    if (!event.currentTarget.hasPointerCapture(event.pointerId)) return;
    commitFromPointer(event.clientX);
  };

  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    if (!event.shiftKey) return;
    const delta =
      event.key === "ArrowRight" || event.key === "ArrowUp"
        ? largeStep
        : event.key === "ArrowLeft" || event.key === "ArrowDown"
          ? -largeStep
          : 0;
    if (delta === 0) return;
    event.preventDefault();
    onValueChange(clamp(value + delta, min, max));
  };

  return (
    <div
      ref={trackRef}
      data-slot={slot}
      data-disabled={disabled || undefined}
      className={cn(trackClassName, !disabled && "cursor-pointer", className)}
      style={{ ...trackStyle, ...style }}
      onPointerDown={handlePointerDown}
      onPointerMove={handlePointerMove}
      {...props}
    >
      <input
        type="range"
        min={min}
        max={max}
        step={step}
        value={value}
        disabled={disabled}
        aria-label={label}
        aria-valuetext={valueText}
        className={srOnlyClassName}
        onChange={(event) => onValueChange(Number(event.target.value))}
        onKeyDown={handleKeyDown}
      />
      <div
        data-slot={`${slot}-thumb`}
        aria-hidden="true"
        className={cn(thumbClassName, "top-1/2")}
        style={{
          left: `${((value - min) / (max - min)) * 100}%`,
          backgroundColor: thumbColor,
        }}
      />
    </div>
  );
}

function ColorPickerHue(props: Omit<React.ComponentProps<"div">, "onChange">) {
  const { hsva, setColor, description } = useColorPicker();
  const hue = Math.round(normalizeHue(hsva.h));

  return (
    <SliderTrack
      slot="color-picker-hue"
      label="Hue"
      valueText={`${hue} degrees, ${description}`}
      min={0}
      max={360}
      step={1}
      largeStep={10}
      value={hue}
      onValueChange={(value) => setColor((previous) => ({ ...previous, h: value }))}
      trackStyle={{ backgroundImage: HUE_GRADIENT }}
      thumbColor={`hsl(${hue} 100% 50%)`}
      {...props}
    />
  );
}

function ColorPickerAlpha(props: Omit<React.ComponentProps<"div">, "onChange">) {
  const { hsva, setColor, rgb, description } = useColorPicker();
  const alpha = Math.round(hsva.a * 100);

  return (
    <SliderTrack
      slot="color-picker-alpha"
      label="Alpha"
      valueText={`${alpha}%, ${description}`}
      min={0}
      max={100}
      step={1}
      largeStep={10}
      value={alpha}
      onValueChange={(value) => setColor((previous) => ({ ...previous, a: value / 100 }))}
      trackStyle={{
        ...CHECKERBOARD_STYLE,
        backgroundImage: `linear-gradient(to right, rgb(${rgb.r} ${rgb.g} ${rgb.b} / 0), rgb(${rgb.r} ${rgb.g} ${rgb.b})), ${CHECKERBOARD_STYLE.backgroundImage}`,
        backgroundSize: `auto, ${CHECKERBOARD_STYLE.backgroundSize}`,
        backgroundPosition: `0 0, ${CHECKERBOARD_STYLE.backgroundPosition}`,
      }}
      thumbColor={`rgb(${rgb.r} ${rgb.g} ${rgb.b})`}
      {...props}
    />
  );
}

function ColorPickerPreview({ className, style, ...props }: React.ComponentProps<"div">) {
  const { cssColor, description, value } = useColorPicker();

  return (
    <div
      data-slot="color-picker-preview"
      role="img"
      aria-label={`${description}, ${value}`}
      className={cn(
        "relative size-8 shrink-0 overflow-hidden rounded-lg border border-border",
        className,
      )}
      style={{ ...CHECKERBOARD_STYLE, ...style }}
      {...props}
    >
      <div className="absolute inset-0" style={{ backgroundColor: cssColor }} />
    </div>
  );
}

type EyeDropperInstance = {
  open: (options?: { signal?: AbortSignal }) => Promise<{ sRGBHex: string }>;
};

declare global {
  interface Window {
    EyeDropper?: new () => EyeDropperInstance;
  }
}

function ColorPickerEyeDropper({
  className,
  onClick,
  ...props
}: React.ComponentProps<typeof Button>) {
  const { setColor, disabled } = useColorPicker();
  const [isSupported, setIsSupported] = React.useState(false);

  React.useEffect(() => {
    setIsSupported(typeof window !== "undefined" && "EyeDropper" in window);
  }, []);

  if (!isSupported) return null;

  const pick = async () => {
    const EyeDropperConstructor = window.EyeDropper;
    if (!EyeDropperConstructor) return;
    const result = await new EyeDropperConstructor().open().catch(() => null);
    if (!result) return;
    const picked = parseColor(result.sRGBHex);
    if (picked) setColor((previous) => ({ ...picked, a: previous.a }));
  };

  return (
    <Button
      type="button"
      variant="outline"
      size="icon"
      data-slot="color-picker-eye-dropper"
      aria-label="Pick a color from the screen"
      disabled={disabled}
      className={className}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented) void pick();
      }}
      {...props}
    >
      <IconColorPicker />
    </Button>
  );
}

const ALL_FORMATS: ColorFormat[] = ["hex", "rgb", "hsl", "oklch"];

function ColorPickerFormatSelect({
  formats = ALL_FORMATS,
  className,
  ...props
}: React.ComponentProps<typeof ButtonGroup> & { formats?: ColorFormat[] }) {
  const { format, setFormat, disabled } = useColorPicker();

  return (
    <ButtonGroup
      data-slot="color-picker-format-select"
      aria-label="Color format"
      className={className}
      {...props}
    >
      {formats.map((option) => (
        <Button
          key={option}
          type="button"
          size="xs"
          variant="outline"
          aria-pressed={format === option}
          disabled={disabled}
          className="uppercase aria-pressed:bg-muted aria-pressed:text-foreground"
          onClick={() => setFormat(option)}
        >
          {option}
        </Button>
      ))}
    </ButtonGroup>
  );
}

type ChannelKey = "r" | "g" | "b" | "h" | "s" | "l" | "c" | "a";

type ChannelConfig = {
  key: ChannelKey;
  label: string;
  name: string;
  min: number;
  max: number;
  step: number;
  precision: number;
};

const CHANNELS: Record<Exclude<ColorFormat, "hex">, ChannelConfig[]> = {
  rgb: [
    { key: "r", label: "R", name: "Red", min: 0, max: 255, step: 1, precision: 0 },
    { key: "g", label: "G", name: "Green", min: 0, max: 255, step: 1, precision: 0 },
    { key: "b", label: "B", name: "Blue", min: 0, max: 255, step: 1, precision: 0 },
  ],
  hsl: [
    { key: "h", label: "H", name: "Hue", min: 0, max: 360, step: 1, precision: 0 },
    { key: "s", label: "S", name: "Saturation", min: 0, max: 100, step: 1, precision: 0 },
    { key: "l", label: "L", name: "Lightness", min: 0, max: 100, step: 1, precision: 0 },
  ],
  oklch: [
    { key: "l", label: "L", name: "Lightness", min: 0, max: 1, step: 0.001, precision: 3 },
    { key: "c", label: "C", name: "Chroma", min: 0, max: 0.4, step: 0.001, precision: 3 },
    { key: "h", label: "H", name: "Hue", min: 0, max: 360, step: 0.1, precision: 1 },
  ],
};

const ALPHA_CHANNEL: ChannelConfig = {
  key: "a",
  label: "A",
  name: "Alpha",
  min: 0,
  max: 100,
  step: 1,
  precision: 0,
};

function readChannels(hsva: Hsva, format: Exclude<ColorFormat, "hex">): Record<string, number> {
  if (format === "rgb") return hsvaToRgb(hsva);
  if (format === "hsl") {
    const { h, s, l } = hsvToHsl(hsva);
    return { h: normalizeHue(h), s: s * 100, l: l * 100 };
  }
  return rgbToOklch(hsvaToRgb(hsva));
}

function writeChannels(
  channels: Record<string, number>,
  format: Exclude<ColorFormat, "hex">,
  alpha: number,
): Hsva {
  if (format === "rgb") {
    return { ...rgbToHsv({ r: channels.r, g: channels.g, b: channels.b }), a: alpha };
  }
  if (format === "hsl") {
    return {
      ...hslToHsv({ h: channels.h, s: channels.s / 100, l: channels.l / 100 }),
      a: alpha,
    };
  }
  return {
    ...rgbToHsv(oklchToRgb({ l: channels.l, c: channels.c, h: channels.h })),
    a: alpha,
  };
}

function ChannelField({
  config,
  value,
  onCommit,
}: {
  config: ChannelConfig;
  value: number;
  onCommit: (value: number) => void;
}) {
  const { disabled } = useColorPicker();
  const [draft, setDraft] = React.useState<string | null>(null);
  const displayed = draft ?? String(round(value, config.precision));

  return (
    <InputGroup className="min-w-0">
      <InputGroupAddon>
        <span className="text-xs text-muted-foreground select-none">{config.label}</span>
      </InputGroupAddon>
      <InputGroupInput
        type="number"
        inputMode="decimal"
        min={config.min}
        max={config.max}
        step={config.step}
        value={displayed}
        disabled={disabled}
        aria-label={config.name}
        className="[appearance:textfield] pl-0! tabular-nums [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
        onChange={(event) => {
          setDraft(event.target.value);
          const parsed = Number.parseFloat(event.target.value);
          if (!Number.isNaN(parsed)) {
            onCommit(clamp(parsed, config.min, config.max));
          }
        }}
        onBlur={() => setDraft(null)}
      />
    </InputGroup>
  );
}

function HexField() {
  const { hsva, setColor, disabled } = useColorPicker();
  const [draft, setDraft] = React.useState<string | null>(null);
  const displayed = draft ?? toHex(hsva).replace(/^#/, "");

  return (
    <InputGroup className="min-w-0">
      <InputGroupAddon>
        <span className="text-xs text-muted-foreground select-none">#</span>
      </InputGroupAddon>
      <InputGroupInput
        value={displayed}
        disabled={disabled}
        aria-label="Hex color"
        spellCheck={false}
        autoComplete="off"
        autoCapitalize="none"
        maxLength={8}
        className="pl-0! font-mono uppercase"
        onChange={(event) => {
          const sanitized = event.target.value.replace(/[^0-9a-fA-F]/g, "").slice(0, 8);
          setDraft(sanitized);
          const parsed = parseColor(sanitized);
          if (parsed) setColor(parsed);
        }}
        onBlur={() => setDraft(null)}
      />
    </InputGroup>
  );
}

function ColorPickerInput({
  alpha = false,
  className,
  ...props
}: React.ComponentProps<"div"> & {
  alpha?: boolean;
}) {
  const { hsva, setColor, format } = useColorPicker();

  const channels = format === "hex" ? [] : CHANNELS[format];
  const values = format === "hex" ? {} : readChannels(hsva, format);

  return (
    <div
      data-slot="color-picker-input"
      className={cn("grid auto-cols-fr grid-flow-col gap-2", className)}
      {...props}
    >
      {format === "hex" ? (
        <HexField />
      ) : (
        channels.map((config) => (
          <ChannelField
            key={config.key}
            config={config}
            value={values[config.key]}
            onCommit={(next) =>
              setColor((previous) =>
                writeChannels(
                  { ...readChannels(previous, format), [config.key]: next },
                  format,
                  previous.a,
                ),
              )
            }
          />
        ))
      )}
      {alpha ? (
        <ChannelField
          config={ALPHA_CHANNEL}
          value={hsva.a * 100}
          onCommit={(next) => setColor((previous) => ({ ...previous, a: next / 100 }))}
        />
      ) : null}
    </div>
  );
}

function ColorPickerSwatches({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="color-picker-swatches"
      role="group"
      aria-label="Color presets"
      className={cn("flex flex-wrap gap-1.5", className)}
      {...props}
    />
  );
}

function ColorPickerSwatch({
  value,
  className,
  style,
  onClick,
  ...props
}: Omit<React.ComponentProps<"button">, "value"> & { value: string }) {
  const { hsva, setColor, disabled } = useColorPicker();

  const swatch = parseColor(value);
  const isSelected = swatch ? toHex(swatch) === toHex(hsva) : false;
  const checkColor = swatch && rgbToOklch(hsvaToRgb(swatch)).l < 0.6 ? "#fff" : "#000";

  return (
    <button
      type="button"
      data-slot="color-picker-swatch"
      data-selected={isSelected || undefined}
      aria-pressed={isSelected}
      aria-label={swatch ? `${describeColor(swatch)}, ${value}` : value}
      disabled={disabled}
      className={cn(
        "relative flex size-6 items-center justify-center rounded-md border border-border/60 transition-[box-shadow,transform] outline-none",
        "hover:scale-110 focus-visible:ring-3 focus-visible:ring-ring/50",
        "disabled:pointer-events-none disabled:opacity-50",
        className,
      )}
      style={{ backgroundColor: value, ...style }}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented && swatch) setColor(swatch);
      }}
      {...props}
    >
      {isSelected ? <IconCheck className="size-3.5" style={{ color: checkColor }} /> : null}
    </button>
  );
}

export {
  ColorPicker,
  ColorPickerAlpha,
  ColorPickerArea,
  ColorPickerEyeDropper,
  ColorPickerFormatSelect,
  ColorPickerHue,
  ColorPickerInput,
  ColorPickerPreview,
  ColorPickerSwatch,
  ColorPickerSwatches,
  describeColor,
  formatColor,
  parseColor,
  useColorPicker,
  type ColorFormat,
  type ColorPickerProps,
  type Hsva,
};
```



## Usage

A headless-ish set of parts rather than one fixed widget: `ColorPicker` owns the color state and
every other part reads from it, so you arrange the surface you actually need. Nothing renders unless
you ask for it — drop `ColorPickerAlpha` if your colors are always opaque, drop
`ColorPickerFormatSelect` if you only ever emit hex.

```tsx
import {
  ColorPicker,
  ColorPickerAlpha,
  ColorPickerArea,
  ColorPickerEyeDropper,
  ColorPickerFormatSelect,
  ColorPickerHue,
  ColorPickerInput,
  ColorPickerPreview,
  ColorPickerSwatch,
  ColorPickerSwatches,
} from "@/components/ui/color-picker";

export function BrandColor() {
  const [color, setColor] = useState("#3b82f6");

  return (
    <ColorPicker value={color} onValueChange={setColor}>
      <ColorPickerArea />
      <div className="flex items-center gap-3">
        <ColorPickerEyeDropper />
        <div className="flex min-w-0 flex-1 flex-col gap-2">
          <ColorPickerHue />
          <ColorPickerAlpha />
        </div>
        <ColorPickerPreview />
      </div>
      <ColorPickerFormatSelect />
      <ColorPickerInput alpha />
      <ColorPickerSwatches>
        <ColorPickerSwatch value="#ef4444" />
        <ColorPickerSwatch value="#22c55e" />
        <ColorPickerSwatch value="#3b82f6" />
      </ColorPickerSwatches>
    </ColorPicker>
  );
}
```

## State

`ColorPicker` is controlled with `value` / `onValueChange` and uncontrolled with `defaultValue`.
`onValueChange` hands you a CSS color string serialized in the active format, so the value you get
back is the value you can paste straight into a stylesheet.

```tsx
<ColorPicker defaultValue="oklch(0.62 0.19 259)" defaultFormat="oklch" />
```

Internally the color is stored as HSVA, not as the string. That is what lets you drag into pure
black and drag back out onto the hue you started from — a picker that round-trips through hex loses
the hue the moment brightness hits zero.

`format` / `defaultFormat` / `onFormatChange` control the output format the same way. Switching
format fires `onValueChange` too, since the value string changes with it.

Pass `name` to submit the value with a plain HTML form:

```tsx
<ColorPicker name="accent" defaultValue="#3b82f6" />
```

## Parts

| Part                      | Notes                                                                       |
| ------------------------- | --------------------------------------------------------------------------- |
| `ColorPicker`             | State owner and context provider. Accepts `disabled` and `name`.             |
| `ColorPickerArea`         | Saturation and brightness plane.                                             |
| `ColorPickerHue`          | Hue slider, 0–360.                                                           |
| `ColorPickerAlpha`        | Alpha slider over a checkerboard.                                            |
| `ColorPickerPreview`      | Current color chip. Size it with `className`.                                |
| `ColorPickerEyeDropper`   | Screen sampler. Renders nothing where the EyeDropper API is unavailable.     |
| `ColorPickerFormatSelect` | Segmented format control. Narrow it with `formats={["hex", "rgb"]}`.         |
| `ColorPickerInput`        | Format-aware fields — a hex box, or one field per channel. `alpha` adds one. |
| `ColorPickerSwatches`     | Preset container.                                                            |
| `ColorPickerSwatch`       | One preset. `value` takes any parseable color string.                        |

## Popover trigger

The item ships the panel, not the trigger, so it composes with whatever overlay you already use:

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    <span className="size-4 rounded" style={{ backgroundColor: color }} />
    {color}
  </PopoverTrigger>
  <PopoverContent className="w-64">
    <ColorPicker value={color} onValueChange={setColor}>
      <ColorPickerArea />
      <ColorPickerHue />
      <ColorPickerInput />
    </ColorPicker>
  </PopoverContent>
</Popover>
```

## Custom parts

`useColorPicker` exposes the same context the built-in parts use, so you can add your own without
forking the component:

```tsx
import { useColorPicker } from "@/components/ui/color-picker";

function CopyColor() {
  const { value, description } = useColorPicker();

  return (
    <Button variant="ghost" onClick={() => navigator.clipboard.writeText(value)}>
      Copy {description}
    </Button>
  );
}
```

It returns `hsva`, `setColor`, `rgb`, `hex`, `cssColor`, `value`, `format`, `setFormat`,
`description`, and `disabled`.

## Color utilities

`parseColor`, `formatColor`, and `describeColor` are exported for use outside the picker.
`parseColor` reads `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `hsl()`, and `oklch()` in both
the legacy comma syntax and the modern space/slash syntax, and returns `null` rather than throwing
on input it cannot read.

```tsx
formatColor(parseColor("#3b82f6")!, "oklch"); // "oklch(0.6231 0.188 259.81)"
describeColor(parseColor("#3b82f6")!); // "vibrant blue"
```

## Accessibility

The saturation plane is backed by two visually hidden range inputs — one per axis — following the
pattern React Aria uses for its `ColorArea`. Screen readers get a real value to announce, keyboard
users get a real control to focus, and mobile assistive tech gets its native slider gestures. Arrow
keys drive both axes from either input, so focus order never changes what the keys do.

Every control announces a plain-language color description next to its numeric value — "62%, dark
vibrant blue" rather than "182, 96, 38". Descriptions are derived in OKLCH, whose lightness is
perceptually even across hues, so "dark" means the same thing on yellow as it does on blue.

| Key                    | Action                                       |
| ---------------------- | -------------------------------------------- |
| `←` `→`                | Saturation, or the slider value, by one step |
| `↑` `↓`                | Brightness in the area                       |
| `Shift` + arrow        | Ten steps                                    |
| `Home` `End`           | Minimum / maximum                            |
| `Page Up` `Page Down`  | Ten steps                                    |


---

URL: https://mwui.vercel.app/components/command-palette.md

A searchable command palette with groups, nested pages, and recent actions.

# Command Palette

A searchable command palette with groups, nested pages, and recent actions.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/command-palette.json
```

[Registry JSON](https://mwui.vercel.app/r/command-palette.json)

## Preview

```tsx
import {
  IconFilePlus,
  IconMoon,
  IconSettings,
  IconSun,
  IconUserPlus,
  IconUsers,
} from "@tabler/icons-react";
import * as React from "react";

import { Button } from "@/components/ui/button";

import { CommandPalette, type CommandAction } from "@/components/ui/command-palette";

export function Preview() {
  const [open, setOpen] = React.useState(false);
  const [log, setLog] = React.useState("Nothing run yet.");

  const actions: CommandAction[] = React.useMemo(
    () => [
      {
        id: "new-project",
        label: "New project",
        description: "Start from a blank workspace",
        group: "Create",
        shortcut: "⌘ N",
        icon: <IconFilePlus />,
        onSelect: () => setLog("Ran: New project"),
      },
      {
        id: "invite",
        label: "Invite teammate",
        group: "Create",
        keywords: ["member", "seat", "user"],
        icon: <IconUserPlus />,
        onSelect: () => setLog("Ran: Invite teammate"),
      },
      {
        id: "members",
        label: "Go to members",
        group: "Navigate",
        icon: <IconUsers />,
        onSelect: () => setLog("Ran: Go to members"),
      },
      {
        id: "theme",
        label: "Change theme",
        group: "Preferences",
        icon: <IconSettings />,
        children: [
          {
            id: "theme-light",
            label: "Light",
            icon: <IconSun />,
            onSelect: () => setLog("Ran: Theme → Light"),
          },
          {
            id: "theme-dark",
            label: "Dark",
            icon: <IconMoon />,
            onSelect: () => setLog("Ran: Theme → Dark"),
          },
        ],
      },
    ],
    [],
  );

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open palette
        <kbd className="ml-auto rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-[0.7rem]">
          ⌘K
        </kbd>
      </Button>

      <p className="text-xs text-muted-foreground">{log}</p>

      <CommandPalette
        actions={actions}
        open={open}
        onOpenChange={setOpen}
        recentsKey="mwui:command-palette-preview"
      />
    </div>
  );
}
```


## Source

### ui/command-palette.tsx

```tsx
"use client";

import { IconChevronRight, IconCornerDownLeft } from "@tabler/icons-react";
import * as React from "react";

import {
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandShortcut,
} from "@/components/ui/command";
import { useHotkeys } from "@/hooks/use-hotkeys";
import { useLocalStorage } from "@/hooks/use-local-storage";
import { cn } from "@/lib/utils";

type CommandAction = {
  id: string;
  label: string;
  description?: string;
  group?: string;
  keywords?: string[];
  shortcut?: string;
  icon?: React.ReactNode;
  disabled?: boolean;
  children?: CommandAction[];
  onSelect?: () => void;
};

type CommandPalettePage = {
  title: string;
  actions: CommandAction[];
};

type CommandPaletteProps = {
  actions: CommandAction[];
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  hotkey?: string | null;
  placeholder?: string;
  emptyMessage?: string;
  recentsKey?: string | null;
  maxRecents?: number;
};

function CommandPalette({
  actions,
  open: openProp,
  onOpenChange,
  hotkey = "mod+k",
  placeholder = "Type a command or search…",
  emptyMessage = "No results found.",
  recentsKey = "command-palette:recents",
  maxRecents = 5,
}: CommandPaletteProps) {
  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(false);
  const open = openProp ?? uncontrolledOpen;

  const [pages, setPages] = React.useState<CommandPalettePage[]>([]);
  const [query, setQuery] = React.useState("");
  const [recentIds, setRecentIds] = useLocalStorage<string[]>(
    recentsKey ?? "command-palette:disabled",
    [],
  );

  const setOpen = React.useCallback(
    (next: boolean) => {
      if (openProp === undefined) setUncontrolledOpen(next);
      onOpenChange?.(next);
    },
    [onOpenChange, openProp],
  );

  useHotkeys(hotkey ?? "", () => setOpen(!open), { enabled: hotkey !== null });

  React.useEffect(() => {
    if (open) return undefined;

    const timeout = setTimeout(() => {
      setPages([]);
      setQuery("");
    }, 150);

    return () => clearTimeout(timeout);
  }, [open]);

  const currentPage = pages[pages.length - 1];
  const visibleActions = currentPage?.actions ?? actions;

  const flatActions = React.useMemo(() => flatten(actions), [actions]);

  const recents = React.useMemo(() => {
    if (recentsKey === null || currentPage || query) return [];

    return recentIds
      .map((id) => flatActions.find((action) => action.id === id))
      .filter((action): action is CommandAction => action !== undefined)
      .slice(0, maxRecents);
  }, [currentPage, flatActions, maxRecents, query, recentIds, recentsKey]);

  const recentIdSet = new Set(recents.map((action) => action.id));

  const runAction = (action: CommandAction) => {
    if (action.children && action.children.length > 0) {
      setPages((previous) => [
        ...previous,
        { title: action.label, actions: action.children ?? [] },
      ]);
      setQuery("");
      return;
    }

    if (recentsKey !== null) {
      setRecentIds((previous) =>
        [action.id, ...previous.filter((id) => id !== action.id)].slice(0, maxRecents),
      );
    }

    setOpen(false);
    action.onSelect?.();
  };

  const goBack = () => {
    setPages((previous) => previous.slice(0, -1));
    setQuery("");
  };

  const groups = groupActions(visibleActions.filter((action) => !recentIdSet.has(action.id)));

  return (
    <CommandDialog
      open={open}
      onOpenChange={setOpen}
      title="Command palette"
      description="Search for a command to run."
    >
      {pages.length > 0 ? (
        <div className="flex items-center gap-1 px-2 pt-2 text-xs text-muted-foreground">
          <button
            type="button"
            onClick={goBack}
            className="rounded px-1 py-0.5 outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
          >
            Home
          </button>
          {pages.map((page, index) => (
            <React.Fragment key={page.title}>
              <IconChevronRight className="size-3" />
              <span className={cn(index === pages.length - 1 && "text-foreground")}>
                {page.title}
              </span>
            </React.Fragment>
          ))}
        </div>
      ) : null}

      <CommandInput
        value={query}
        onValueChange={setQuery}
        placeholder={currentPage ? `Search ${currentPage.title.toLowerCase()}…` : placeholder}
        onKeyDown={(event) => {
          if (event.key === "Backspace" && query === "" && pages.length > 0) {
            event.preventDefault();
            goBack();
          }
        }}
      />

      <CommandList>
        <CommandEmpty>{emptyMessage}</CommandEmpty>

        {recents.length > 0 ? (
          <CommandGroup heading="Recent">
            {recents.map((action) => (
              <CommandActionItem key={action.id} action={action} onRun={runAction} />
            ))}
          </CommandGroup>
        ) : null}

        {groups.map(({ heading, items }) => (
          <CommandGroup key={heading ?? "ungrouped"} heading={heading}>
            {items.map((action) => (
              <CommandActionItem key={action.id} action={action} onRun={runAction} />
            ))}
          </CommandGroup>
        ))}
      </CommandList>
    </CommandDialog>
  );
}

function CommandActionItem({
  action,
  onRun,
}: {
  action: CommandAction;
  onRun: (action: CommandAction) => void;
}) {
  const hasChildren = action.children !== undefined && action.children.length > 0;

  return (
    <CommandItem
      value={`${action.label} ${action.keywords?.join(" ") ?? ""} ${action.description ?? ""}`}
      disabled={action.disabled}
      onSelect={() => onRun(action)}
    >
      {action.icon ? (
        <span className="flex size-4 shrink-0 items-center justify-center text-muted-foreground">
          {action.icon}
        </span>
      ) : null}

      <span className="flex min-w-0 flex-1 flex-col">
        <span className="truncate">{action.label}</span>
        {action.description ? (
          <span className="truncate text-xs text-muted-foreground">{action.description}</span>
        ) : null}
      </span>

      {action.shortcut ? <CommandShortcut>{action.shortcut}</CommandShortcut> : null}

      {hasChildren ? (
        <IconChevronRight className="size-3.5 text-muted-foreground" />
      ) : (
        <IconCornerDownLeft className="size-3.5 text-muted-foreground opacity-0 in-data-[selected=true]:opacity-100" />
      )}
    </CommandItem>
  );
}

function flatten(actions: CommandAction[]): CommandAction[] {
  return actions.flatMap((action) => [action, ...flatten(action.children ?? [])]);
}

function groupActions(
  actions: CommandAction[],
): { heading: string | undefined; items: CommandAction[] }[] {
  const groups = new Map<string | undefined, CommandAction[]>();

  for (const action of actions) {
    const existing = groups.get(action.group);

    if (existing) {
      existing.push(action);
    } else {
      groups.set(action.group, [action]);
    }
  }

  return Array.from(groups, ([heading, items]) => ({ heading, items }));
}

export { CommandPalette, type CommandAction, type CommandPaletteProps };
```



## Usage

Describe your commands as data and get the whole ⌘K surface: fuzzy search, groups, keyboard
navigation, a nested page per action that has children, and a recents list that survives reloads.

```tsx
import { CommandPalette } from "@/components/ui/command-palette";

const ACTIONS = [
  {
    id: "new-project",
    label: "New project",
    group: "Create",
    shortcut: "⌘ N",
    onSelect: () => router.navigate({ to: "/projects/new" }),
  },
  {
    id: "theme",
    label: "Change theme",
    group: "Preferences",
    children: [
      { id: "theme-light", label: "Light", onSelect: () => setTheme("light") },
      { id: "theme-dark", label: "Dark", onSelect: () => setTheme("dark") },
    ],
  },
];

export function AppCommands() {
  return <CommandPalette actions={ACTIONS} />;
}
```

Mount it once, near the root. It binds `mod+k` itself, so nothing else needs wiring.

## Nested pages

An action with `children` opens them as a page instead of running. The breadcrumb shows where you
are, `Backspace` on an empty query goes back, and search applies to the current page only — which is
what makes a two-level menu (Change theme → Dark) feel faster than a flat list of every permutation.

## Recents

Selected actions are remembered in `localStorage` and shown above everything else when the query is
empty. They are resolved by `id` against the current action list, so a command you removed from the
app simply stops appearing.

```tsx
<CommandPalette actions={ACTIONS} recentsKey="acme:commands" maxRecents={3} />
```

Pass `recentsKey={null}` to turn the feature off — worth doing if the palette can act on data the
user may no longer be allowed to see.

## Controlled

Pass `open` and `onOpenChange` to drive it from elsewhere — a toolbar button, a route, an onboarding
step. Set `hotkey={null}` if you want to own the shortcut.

```tsx
<CommandPalette actions={ACTIONS} open={open} onOpenChange={setOpen} hotkey={null} />
```

## Action shape

| Field         | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `id`          | Stable identity. Used for recents, so keep it stable across releases.       |
| `label`       | What the user reads and searches.                                           |
| `description` | Second line, also searchable.                                               |
| `group`       | Heading to file the action under. Ungrouped actions render first.           |
| `keywords`    | Extra search terms — synonyms, the old name of a feature, a misspelling.    |
| `shortcut`    | Display only. Render the shortcut you bound elsewhere; the palette does not bind it. |
| `icon`        | Any node.                                                                   |
| `children`    | Opens a nested page instead of running.                                     |
| `onSelect`    | What the action does. Called after the palette closes, so a focus change lands cleanly. |

## Props

| Prop           | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `actions`      | The root action list.                                                    |
| `open` / `onOpenChange` | Control the palette externally.                                 |
| `hotkey`       | Toggle shortcut. Defaults to `"mod+k"` — ⌘ on Apple platforms, Ctrl elsewhere. `null` disables it. |
| `placeholder`  | Input placeholder on the root page.                                      |
| `emptyMessage` | Shown when nothing matches.                                              |
| `recentsKey`   | `localStorage` key for recents. `null` disables them.                    |
| `maxRecents`   | How many to keep. Defaults to `5`.                                       |


---

URL: https://mwui.vercel.app/components/confirm-dialog.md

A promise-based confirmation dialog driven by an imperative confirm() call.

# Confirm Dialog

A promise-based confirmation dialog driven by an imperative confirm() call.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/confirm-dialog.json
```

[Registry JSON](https://mwui.vercel.app/r/confirm-dialog.json)

## Preview

```tsx
import * as React from "react";

import { Button } from "@/components/ui/button";

import { ConfirmDialogProvider, useConfirm } from "@/components/ui/confirm-dialog";

function Demo() {
  const confirm = useConfirm();
  const [log, setLog] = React.useState("Nothing yet.");

  const discard = async () => {
    const ok = await confirm({
      title: "Discard changes?",
      description: "Your edits to this draft will be lost.",
      confirmLabel: "Discard",
    });

    setLog(ok ? "Discarded." : "Kept the draft.");
  };

  const revoke = async () => {
    const ok = await confirm({
      title: "Revoke API key?",
      description: "Requests using this key will start failing immediately.",
      confirmLabel: "Revoke",
      destructive: true,
      onConfirm: () =>
        new Promise<void>((resolve) => {
          setTimeout(resolve, 1200);
        }),
    });

    setLog(ok ? "Revoked after a pending round-trip." : "Cancelled.");
  };

  const deleteOrganization = async () => {
    const ok = await confirm({
      title: "Delete organization",
      description: "This cannot be undone.",
      confirmText: "acme-inc",
      confirmLabel: "Delete organization",
      destructive: true,
    });

    setLog(ok ? "Organization deleted." : "Cancelled.");
  };

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div className="flex flex-wrap gap-2">
        <Button size="sm" variant="outline" onClick={() => void discard()}>
          Discard
        </Button>
        <Button size="sm" variant="outline" onClick={() => void revoke()}>
          Revoke with pending
        </Button>
        <Button size="sm" variant="outline" onClick={() => void deleteOrganization()}>
          Type to confirm
        </Button>
      </div>

      <p className="text-xs text-muted-foreground">{log}</p>
    </div>
  );
}

export function Preview() {
  return (
    <ConfirmDialogProvider>
      <Demo />
    </ConfirmDialogProvider>
  );
}
```


## Source

### ui/confirm-dialog.tsx

```tsx
"use client";

import * as React from "react";

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Spinner } from "@/components/ui/spinner";

type ConfirmOptions = {
  title: React.ReactNode;
  description?: React.ReactNode;
  confirmLabel?: string;
  cancelLabel?: string;
  destructive?: boolean;
  confirmText?: string;
  onConfirm?: () => void | Promise<void>;
};

type ConfirmFunction = (options: ConfirmOptions) => Promise<boolean>;

const ConfirmDialogContext = React.createContext<ConfirmFunction | null>(null);

type ConfirmDialogProviderProps = {
  children: React.ReactNode;
  confirmLabel?: string;
  cancelLabel?: string;
};

function ConfirmDialogProvider({
  children,
  confirmLabel = "Confirm",
  cancelLabel = "Cancel",
}: ConfirmDialogProviderProps) {
  const [request, setRequest] = React.useState<ConfirmOptions | null>(null);
  const [open, setOpen] = React.useState(false);
  const [pending, setPending] = React.useState(false);
  const [error, setError] = React.useState<string | null>(null);
  const [typed, setTyped] = React.useState("");

  const resolveRef = React.useRef<((result: boolean) => void) | null>(null);
  const confirmTextId = React.useId();

  const settle = React.useCallback((result: boolean) => {
    resolveRef.current?.(result);
    resolveRef.current = null;
    setOpen(false);
  }, []);

  const confirm = React.useCallback<ConfirmFunction>((options) => {
    resolveRef.current?.(false);

    setRequest(options);
    setTyped("");
    setError(null);
    setPending(false);
    setOpen(true);

    return new Promise<boolean>((resolve) => {
      resolveRef.current = resolve;
    });
  }, []);

  const handleConfirm = async () => {
    if (!request) return;

    if (!request.onConfirm) {
      settle(true);
      return;
    }

    setError(null);
    setPending(true);

    try {
      await request.onConfirm();
      settle(true);
    } catch (thrown) {
      setError(thrown instanceof Error ? thrown.message : "Something went wrong.");
    } finally {
      setPending(false);
    }
  };

  const confirmDisabled =
    pending || (request?.confirmText !== undefined && typed !== request.confirmText);

  return (
    <ConfirmDialogContext.Provider value={confirm}>
      {children}

      <Dialog
        open={open}
        onOpenChange={(next) => {
          if (!next && !pending) settle(false);
        }}
        onOpenChangeComplete={(next) => {
          if (!next) setRequest(null);
        }}
      >
        <DialogContent showCloseButton={false}>
          <DialogHeader>
            <DialogTitle>{request?.title}</DialogTitle>
            {request?.description ? (
              <DialogDescription>{request.description}</DialogDescription>
            ) : null}
          </DialogHeader>

          {request?.confirmText ? (
            <div className="flex flex-col gap-2">
              <Label htmlFor={confirmTextId}>
                Type <span className="font-mono text-foreground">{request.confirmText}</span> to
                confirm
              </Label>
              <Input
                id={confirmTextId}
                value={typed}
                autoComplete="off"
                disabled={pending}
                onChange={(event) => setTyped(event.target.value)}
              />
            </div>
          ) : null}

          {error ? (
            <p role="alert" className="text-xs text-destructive">
              {error}
            </p>
          ) : null}

          <DialogFooter>
            <Button variant="outline" disabled={pending} onClick={() => settle(false)}>
              {request?.cancelLabel ?? cancelLabel}
            </Button>
            <Button
              variant={request?.destructive ? "destructive" : "default"}
              disabled={confirmDisabled}
              onClick={() => {
                void handleConfirm();
              }}
            >
              {pending ? <Spinner data-icon="inline-start" /> : null}
              {request?.confirmLabel ?? confirmLabel}
            </Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </ConfirmDialogContext.Provider>
  );
}

function useConfirm(): ConfirmFunction {
  const confirm = React.useContext(ConfirmDialogContext);

  if (!confirm) {
    throw new Error("useConfirm must be used inside a <ConfirmDialogProvider>.");
  }

  return confirm;
}

export {
  ConfirmDialogProvider,
  useConfirm,
  type ConfirmFunction,
  type ConfirmOptions,
  type ConfirmDialogProviderProps,
};
```



## Usage

`window.confirm` has the right API and the wrong everything else. This is the same call — one line,
inline with the code it guards — rendered as a real dialog.

```tsx
import { useConfirm } from "@/components/ui/confirm-dialog";

function DeleteButton({ project }: { project: Project }) {
  const confirm = useConfirm();

  async function handleDelete() {
    const ok = await confirm({
      title: "Delete project?",
      description: `${project.name} and all of its data will be removed.`,
      confirmLabel: "Delete",
      destructive: true,
    });

    if (!ok) return;
    await deleteProject(project.id);
  }

  return <Button variant="destructive" onClick={handleDelete}>Delete</Button>;
}
```

No `open` state, no pending-action state, no dialog markup at the call site — the branch reads the
way the decision actually works.

## Setup

Mount the provider once, near the root:

```tsx
import { ConfirmDialogProvider } from "@/components/ui/confirm-dialog";

export function App({ children }: { children: React.ReactNode }) {
  return <ConfirmDialogProvider>{children}</ConfirmDialogProvider>;
}
```

One dialog instance serves the whole tree. Cancelling — button, `Escape`, or the backdrop — resolves
`false`; nothing rejects, so there is no `try`/`catch` around a user saying no.

## Running the action inside the dialog

Pass `onConfirm` and the dialog stays open while it settles: the confirm button shows a spinner and
both buttons lock. If it throws, the message renders in the dialog and the user can retry — closing
on failure would leave them guessing whether the delete happened.

```tsx
await confirm({
  title: "Revoke API key?",
  destructive: true,
  onConfirm: () => revokeKey(key.id),
});
```

Without `onConfirm` the dialog closes immediately and you run the work yourself.

## Type-to-confirm

For actions that are genuinely unrecoverable, require the name:

```tsx
await confirm({
  title: "Delete organization",
  description: "This cannot be undone.",
  confirmText: organization.slug,
  confirmLabel: "Delete organization",
  destructive: true,
});
```

The confirm button stays disabled until the text matches exactly.

## Options

| Option         | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `title`        | Required. The question being asked.                                      |
| `description`  | Supporting detail. Accepts nodes, not just strings.                      |
| `confirmLabel` / `cancelLabel` | Override the provider defaults per call.                |
| `destructive`  | Style the confirm action as destructive.                                 |
| `confirmText`  | Require this exact string to be typed first.                             |
| `onConfirm`    | Run the action inside the dialog, with pending and error states.         |

## Behavior

- Calling `confirm` while a dialog is open resolves the previous one as cancelled, so a stray second
  call cannot leave a promise hanging forever.
- While `onConfirm` is pending, `Escape` and the backdrop do not close the dialog.
- The request stays mounted through the close animation and is cleared afterwards, so the text does
  not vanish mid-fade.
- Writing the label as the verb — "Delete", not "OK" — is what makes the dialog readable when it is
  the only thing on screen.


---

URL: https://mwui.vercel.app/components/copy-button.md

A copy-to-clipboard button with success feedback.

# Copy Button

A copy-to-clipboard button with success feedback.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/copy-button.json
```

[Registry JSON](https://mwui.vercel.app/r/copy-button.json)

## Preview

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

export function Preview() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4 text-sm">
      <div className="flex items-center justify-between gap-2 rounded-lg border border-border px-3 py-2">
        <code className="truncate font-mono text-xs">npx shadcn add copy-button</code>
        <CopyButton value="npx shadcn add copy-button" />
      </div>

      <div className="flex flex-wrap items-center gap-2">
        <CopyButton value="sk_live_51H8xX2" showLabel copyLabel="Copy key" variant="outline" />
        <CopyButton
          value={() =>
            new Promise<string>((resolve) => {
              setTimeout(() => resolve("deferred value"), 400);
            })
          }
          showLabel
          copyLabel="Copy deferred"
          variant="outline"
        />
      </div>
    </div>
  );
}
```


## Source

### ui/copy-button.tsx

```tsx
"use client";

import { IconCheck, IconCopy } from "@tabler/icons-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import { useCopyToClipboard } from "@/hooks/use-copy-to-clipboard";
import { cn } from "@/lib/utils";

type CopyButtonClickEvent = Parameters<
  NonNullable<React.ComponentProps<typeof Button>["onClick"]>
>[0];

type CopyButtonProps = Omit<React.ComponentProps<typeof Button>, "children" | "value"> & {
  value: string | (() => string | Promise<string>);
  showLabel?: boolean;
  copyLabel?: string;
  copiedLabel?: string;
  errorLabel?: string;
  resetDelay?: number;
  onCopied?: (value: string) => void;
  onCopyError?: (error: Error) => void;
};

function CopyButton({
  value,
  showLabel = false,
  copyLabel = "Copy",
  copiedLabel = "Copied",
  errorLabel = "Copy failed",
  resetDelay = 2000,
  variant = "ghost",
  size,
  className,
  disabled,
  onClick,
  onCopied,
  onCopyError,
  ...props
}: CopyButtonProps) {
  const { status, error, copy, reset } = useCopyToClipboard();
  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  React.useEffect(() => () => clearTimeout(timeoutRef.current), []);

  const handleClick = async (event: CopyButtonClickEvent) => {
    onClick?.(event);
    if (event.defaultPrevented || disabled || status === "copied") return;

    const text = typeof value === "function" ? await value() : value;
    const copied = await copy(text);

    clearTimeout(timeoutRef.current);
    timeoutRef.current = setTimeout(reset, resetDelay);

    if (copied) {
      onCopied?.(text);
    } else if (error) {
      onCopyError?.(error);
    }
  };

  const label = status === "copied" ? copiedLabel : status === "error" ? errorLabel : copyLabel;

  return (
    <Button
      type="button"
      data-slot="copy-button"
      data-status={status}
      variant={status === "error" ? "destructive" : variant}
      size={size ?? (showLabel ? "sm" : "icon-sm")}
      disabled={disabled}
      aria-label={showLabel ? undefined : label}
      className={cn("shrink-0", status === "copied" && "cursor-default", className)}
      onClick={(event) => {
        void handleClick(event);
      }}
      {...props}
    >
      {status === "copied" ? (
        <IconCheck aria-hidden="true" data-icon={showLabel ? "inline-start" : undefined} />
      ) : (
        <IconCopy aria-hidden="true" data-icon={showLabel ? "inline-start" : undefined} />
      )}

      {showLabel ? <span>{label}</span> : null}

      {}
      <span aria-live="polite" className="sr-only">
        {status === "idle" ? "" : label}
      </span>
    </Button>
  );
}

export { CopyButton, type CopyButtonProps };
```



## Usage

Copy something, show that it worked, go back to normal. Small enough to keep rewriting, which is
exactly why it should be installed once.

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

<CopyButton value="npx shadcn add copy-button" />;
```

The icon swaps to a check for two seconds, then returns. If the clipboard write fails — an insecure
origin, a denied permission, an old browser — the button turns destructive and says so, instead of
pretending the copy happened.

## Deferred values

Pass a function when the value is expensive or only known at click time, such as a token you would
rather not hold in state:

```tsx
<CopyButton value={() => generateApiKey()} showLabel copyLabel="Copy key" />
```

It may return a promise; the success state waits for it.

## Props

| Prop           | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `value`        | The text, or a function resolving to it.                              |
| `showLabel`    | Render the label next to the icon. Icon-only by default.              |
| `copyLabel` / `copiedLabel` / `errorLabel` | Override the three states.                |
| `resetDelay`   | How long the success state lasts. Defaults to `2000`.                 |
| `onCopied` / `onCopyError` | Side effects — analytics, a toast.                        |

Button props pass through, so `variant`, `size`, and `className` behave as usual.

## Accessibility

Icon-only buttons take their accessible name from the current state, so the button is "Copy" before
and "Copied" after. The state change is also written into a visually hidden `aria-live` region —
without it the swap from one icon to another is silent, and a screen reader user has no way to know
the copy succeeded.


---

URL: https://mwui.vercel.app/components/date-range-picker.md

A date range picker with a self-contained calendar, quick presets, and keyboard-first navigation.

# Date Range Picker

A date range picker with a self-contained calendar, quick presets, and keyboard-first navigation.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/date-range-picker.json
```

[Registry JSON](https://mwui.vercel.app/r/date-range-picker.json)

## Preview

```tsx
import * as React from "react";

import { DateRangePicker, formatRangeLabel, type DateRange } from "@/components/ui/date-range-picker";

export function Preview() {
  const [range, setRange] = React.useState<DateRange | null>(null);

  return (
    <div className="flex w-full flex-col items-center gap-4">
      <DateRangePicker
        value={range}
        onValueChange={setRange}
        className="rounded-xl border p-3"
        numberOfMonths={2}
      />

      <p className="text-center font-mono text-xs text-muted-foreground">
        {formatRangeLabel(range)}
      </p>
    </div>
  );
}
```


## Source

### ui/date-range-picker.tsx

```tsx
"use client";

import { IconChevronLeft, IconChevronRight } from "@tabler/icons-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import { useControllableState } from "@/hooks/use-controllable-state";
import { formatDate, formatDateRange } from "@/lib/format";
import { cn } from "@/lib/utils";

type DateRange = {
  start: Date;
  end: Date | null;
};

type DateRangePreset = {
  label: string;
  getValue: () => DateRange;
};

const DAYS_PER_WEEK = 7;
const WEEKS_PER_GRID = 6;

function startOfDay(date: Date) {
  const next = new Date(date);
  next.setHours(0, 0, 0, 0);
  return next;
}

function addDays(date: Date, amount: number) {
  const next = new Date(date);
  next.setDate(next.getDate() + amount);
  return startOfDay(next);
}

function addMonths(date: Date, amount: number) {
  const next = new Date(date);
  const day = next.getDate();

  next.setDate(1);
  next.setMonth(next.getMonth() + amount);

  const lastDay = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate();
  next.setDate(Math.min(day, lastDay));

  return startOfDay(next);
}

function startOfMonth(date: Date) {
  const next = new Date(date);
  next.setDate(1);
  return startOfDay(next);
}

function endOfMonth(date: Date) {
  return startOfDay(new Date(date.getFullYear(), date.getMonth() + 1, 0));
}

function startOfYear(date: Date) {
  return startOfDay(new Date(date.getFullYear(), 0, 1));
}

function compareDays(a: Date, b: Date) {
  return startOfDay(a).getTime() - startOfDay(b).getTime();
}

function isSameDay(a: Date, b: Date) {
  return compareDays(a, b) === 0;
}

function isSameMonth(a: Date, b: Date) {
  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
}

function clampDate(date: Date, min?: Date, max?: Date) {
  if (min && compareDays(date, min) < 0) return startOfDay(min);
  if (max && compareDays(date, max) > 0) return startOfDay(max);
  return startOfDay(date);
}

function isOutOfBounds(date: Date, min?: Date, max?: Date) {
  return Boolean((min && compareDays(date, min) < 0) || (max && compareDays(date, max) > 0));
}

function toDateKey(date: Date) {
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  return `${date.getFullYear()}-${month}-${day}`;
}

type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;

function getWeekdayLabels(locale: string | undefined, weekStartsOn: WeekStart) {
  const formatter = new Intl.DateTimeFormat(locale, { weekday: "short" });
  const sunday = new Date(2024, 0, 7);

  return Array.from({ length: DAYS_PER_WEEK }, (_, index) => {
    const day = (weekStartsOn + index) % DAYS_PER_WEEK;
    return { day, label: formatter.format(addDays(sunday, day)) };
  });
}

function getMonthGrid(month: Date, weekStartsOn: WeekStart) {
  const first = startOfMonth(month);
  const offset = (first.getDay() - weekStartsOn + DAYS_PER_WEEK) % DAYS_PER_WEEK;
  const gridStart = addDays(first, -offset);

  const days = Array.from({ length: WEEKS_PER_GRID * DAYS_PER_WEEK }, (_, index) =>
    addDays(gridStart, index),
  );

  return Array.from({ length: WEEKS_PER_GRID }, (_, week) =>
    days.slice(week * DAYS_PER_WEEK, (week + 1) * DAYS_PER_WEEK),
  );
}

function selectDate(current: DateRange | null, date: Date): DateRange {
  if (!current || current.end !== null) return { start: date, end: null };
  if (compareDays(date, current.start) < 0) return { start: date, end: current.start };
  return { start: current.start, end: date };
}

function getPaintedBounds(range: DateRange | null, preview: Date | null) {
  if (!range) return null;

  const end = range.end ?? preview;
  if (!end) return { start: range.start, end: range.start };

  return compareDays(end, range.start) < 0
    ? { start: end, end: range.start }
    : { start: range.start, end };
}

const defaultPresets: DateRangePreset[] = [
  {
    label: "Today",
    getValue: () => {
      const today = startOfDay(new Date());
      return { start: today, end: today };
    },
  },
  {
    label: "Yesterday",
    getValue: () => {
      const yesterday = addDays(new Date(), -1);
      return { start: yesterday, end: yesterday };
    },
  },
  {
    label: "Last 7 days",
    getValue: () => ({ start: addDays(new Date(), -6), end: startOfDay(new Date()) }),
  },
  {
    label: "Last 30 days",
    getValue: () => ({ start: addDays(new Date(), -29), end: startOfDay(new Date()) }),
  },
  {
    label: "This month",
    getValue: () => ({ start: startOfMonth(new Date()), end: endOfMonth(new Date()) }),
  },
  {
    label: "Last month",
    getValue: () => {
      const previous = addMonths(startOfMonth(new Date()), -1);
      return { start: previous, end: endOfMonth(previous) };
    },
  },
  {
    label: "Year to date",
    getValue: () => ({ start: startOfYear(new Date()), end: startOfDay(new Date()) }),
  },
];

function formatRangeLabel(range: DateRange | null, locale?: string) {
  if (!range) return "No dates selected";
  if (!range.end) return `${formatDate(range.start, { locale })} — select end date`;
  return formatDateRange(range.start, range.end, { locale });
}

type DateRangePickerProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "value"
> & {
  value?: DateRange | null;
  defaultValue?: DateRange | null;
  onValueChange?: (value: DateRange | null) => void;
  numberOfMonths?: number;
  locale?: string;
  weekStartsOn?: WeekStart;
  min?: Date;
  max?: Date;
  presets?: DateRangePreset[] | false;
  disabled?: boolean;
};

function DateRangePicker({
  value,
  defaultValue = null,
  onValueChange,
  numberOfMonths = 2,
  locale,
  weekStartsOn = 1,
  min,
  max,
  presets,
  disabled = false,
  className,
  ...props
}: DateRangePickerProps) {
  const [range, setRange] = useControllableState<DateRange | null>({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  const [month, setMonth] = React.useState(() => startOfMonth(range?.start ?? new Date()));
  const [focusedDate, setFocusedDate] = React.useState(() =>
    clampDate(range?.start ?? new Date(), min, max),
  );
  const [previewDate, setPreviewDate] = React.useState<Date | null>(null);

  const gridRef = React.useRef<HTMLDivElement>(null);
  const shouldRestoreFocusRef = React.useRef(false);

  const weekdayLabels = React.useMemo(
    () => getWeekdayLabels(locale, weekStartsOn),
    [locale, weekStartsOn],
  );
  const visibleMonths = React.useMemo(
    () => Array.from({ length: numberOfMonths }, (_, index) => addMonths(month, index)),
    [month, numberOfMonths],
  );

  const resolvedPresets = presets === false ? [] : (presets ?? defaultPresets);
  const painted = getPaintedBounds(range, previewDate);

  React.useEffect(() => {
    if (!shouldRestoreFocusRef.current) return;
    shouldRestoreFocusRef.current = false;

    gridRef.current
      ?.querySelector<HTMLButtonElement>(`[data-date="${toDateKey(focusedDate)}"]`)
      ?.focus();
  }, [focusedDate, month]);

  const goToMonth = (next: Date) => {
    setMonth(startOfMonth(next));
    setPreviewDate(null);
  };

  const moveFocus = (next: Date) => {
    const clamped = clampDate(next, min, max);
    shouldRestoreFocusRef.current = true;
    setFocusedDate(clamped);

    if (compareDays(clamped, month) < 0) {
      setMonth(startOfMonth(clamped));
      return;
    }

    const lastVisibleDay = endOfMonth(visibleMonths[visibleMonths.length - 1]);
    if (compareDays(clamped, lastVisibleDay) > 0) {
      setMonth(startOfMonth(addMonths(clamped, -(numberOfMonths - 1))));
    }
  };

  const commitDate = (date: Date) => {
    if (disabled || isOutOfBounds(date, min, max)) return;
    setRange((previous) => selectDate(previous, date));
    setPreviewDate(null);
  };

  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
    if (disabled) return;

    const shiftDays = (amount: number) => {
      event.preventDefault();
      moveFocus(addDays(focusedDate, amount));
    };

    const shiftMonths = (amount: number) => {
      event.preventDefault();
      moveFocus(addMonths(focusedDate, amount));
    };

    const weekOffset = (focusedDate.getDay() - weekStartsOn + DAYS_PER_WEEK) % DAYS_PER_WEEK;

    switch (event.key) {
      case "ArrowLeft":
        return shiftDays(-1);
      case "ArrowRight":
        return shiftDays(1);
      case "ArrowUp":
        return shiftDays(-DAYS_PER_WEEK);
      case "ArrowDown":
        return shiftDays(DAYS_PER_WEEK);
      case "Home":
        return shiftDays(-weekOffset);
      case "End":
        return shiftDays(DAYS_PER_WEEK - 1 - weekOffset);
      case "PageUp":
        return shiftMonths(event.shiftKey ? -12 : -1);
      case "PageDown":
        return shiftMonths(event.shiftKey ? 12 : 1);
      default:
    }
  };

  const isPresetSelected = (preset: DateRangePreset) => {
    if (!range?.end) return false;
    const candidate = preset.getValue();
    return (
      candidate.end !== null &&
      isSameDay(candidate.start, range.start) &&
      isSameDay(candidate.end, range.end)
    );
  };

  return (
    <div
      data-slot="date-range-picker"
      data-disabled={disabled || undefined}
      className={cn(
        "flex w-fit flex-col gap-3 sm:flex-row sm:items-start",
        "data-disabled:pointer-events-none data-disabled:opacity-50",
        className,
      )}
      {...props}
    >
      {resolvedPresets.length > 0 ? (
        <div
          data-slot="date-range-picker-presets"
          role="group"
          aria-label="Date range presets"
          className="flex shrink-0 flex-wrap gap-1 sm:w-32 sm:flex-col"
        >
          {resolvedPresets.map((preset) => (
            <Button
              key={preset.label}
              type="button"
              size="xs"
              variant="ghost"
              disabled={disabled}
              aria-pressed={isPresetSelected(preset)}
              className="justify-start aria-pressed:bg-muted aria-pressed:text-foreground"
              onClick={() => {
                const next = preset.getValue();
                setRange(next);
                goToMonth(next.start);
                setFocusedDate(clampDate(next.start, min, max));
              }}
            >
              {preset.label}
            </Button>
          ))}
        </div>
      ) : null}

      <div className="flex flex-col gap-2">
        <div className="flex items-center justify-between gap-2">
          <Button
            type="button"
            size="icon-xs"
            variant="outline"
            aria-label="Previous month"
            disabled={disabled || Boolean(min && compareDays(startOfMonth(month), min) <= 0)}
            onClick={() => goToMonth(addMonths(month, -1))}
          >
            <IconChevronLeft />
          </Button>

          <div aria-live="polite" className="flex flex-1 justify-around gap-4">
            {visibleMonths.map((visibleMonth) => (
              <div key={toDateKey(visibleMonth)} className="text-sm font-medium">
                {formatDate(visibleMonth, { locale, month: "long", year: "numeric" })}
              </div>
            ))}
          </div>

          <Button
            type="button"
            size="icon-xs"
            variant="outline"
            aria-label="Next month"
            disabled={
              disabled ||
              Boolean(max && compareDays(endOfMonth(visibleMonths.at(-1) ?? month), max) >= 0)
            }
            onClick={() => goToMonth(addMonths(month, 1))}
          >
            <IconChevronRight />
          </Button>
        </div>

        <div ref={gridRef} className="flex gap-4" onPointerLeave={() => setPreviewDate(null)}>
          {visibleMonths.map((visibleMonth) => (
            <div
              key={toDateKey(visibleMonth)}
              role="grid"
              aria-label={formatDate(visibleMonth, { locale, month: "long", year: "numeric" })}
              className="flex flex-col gap-1"
              onKeyDown={handleKeyDown}
            >
              <div role="row" className="flex">
                {weekdayLabels.map((weekday) => (
                  <div
                    key={weekday.day}
                    role="columnheader"
                    aria-label={weekday.label}
                    className="flex size-8 items-center justify-center text-xs text-muted-foreground"
                  >
                    {weekday.label.slice(0, 2)}
                  </div>
                ))}
              </div>

              {getMonthGrid(visibleMonth, weekStartsOn).map((week) => (
                <div key={toDateKey(week[0])} role="row" className="flex">
                  {week.map((day) => {
                    const outsideMonth = !isSameMonth(day, visibleMonth);
                    const unavailable = isOutOfBounds(day, min, max);
                    const isStart = Boolean(painted && isSameDay(day, painted.start));
                    const isEnd = Boolean(painted && isSameDay(day, painted.end));
                    const inRange = Boolean(
                      painted &&
                      compareDays(day, painted.start) >= 0 &&
                      compareDays(day, painted.end) <= 0,
                    );

                    return (
                      <div
                        key={toDateKey(day)}
                        role="gridcell"
                        aria-selected={inRange}
                        className={cn(
                          "p-0",
                          inRange && !outsideMonth && "bg-muted",
                          inRange && isStart && "rounded-l-md",
                          inRange && isEnd && "rounded-r-md",
                        )}
                      >
                        <button
                          type="button"
                          data-date={toDateKey(day)}
                          data-outside-month={outsideMonth || undefined}
                          data-selected={isStart || isEnd || undefined}
                          data-in-range={inRange || undefined}
                          disabled={disabled || unavailable}
                          tabIndex={isSameDay(day, focusedDate) ? 0 : -1}
                          aria-label={formatDate(day, { locale, dateStyle: "full" })}
                          className={cn(
                            "flex size-8 items-center justify-center rounded-md text-sm tabular-nums outline-none",
                            "not-data-selected:hover:bg-foreground/10 not-data-selected:hover:text-foreground",
                            "focus-visible:ring-3 focus-visible:ring-ring/50",
                            "disabled:pointer-events-none disabled:opacity-40",
                            outsideMonth && "text-muted-foreground/50",
                            "data-selected:bg-primary data-selected:text-primary-foreground",
                          )}
                          onClick={() => commitDate(day)}
                          onFocus={() => setFocusedDate(day)}
                          onPointerEnter={() => {
                            if (range && !range.end) setPreviewDate(day);
                          }}
                        >
                          {day.getDate()}
                        </button>
                      </div>
                    );
                  })}
                </div>
              ))}
            </div>
          ))}
        </div>

        <div className="flex items-center justify-between gap-2 border-t pt-2">
          <p aria-live="polite" className="text-xs text-muted-foreground">
            {formatRangeLabel(range, locale)}
          </p>
          <Button
            type="button"
            size="xs"
            variant="ghost"
            disabled={disabled || range === null}
            onClick={() => {
              setRange(null);
              setPreviewDate(null);
            }}
          >
            Clear
          </Button>
        </div>
      </div>
    </div>
  );
}

export {
  DateRangePicker,
  defaultPresets,
  formatRangeLabel,
  type DateRange,
  type DateRangePickerProps,
  type DateRangePreset,
  type WeekStart,
};
```



## Usage

A range calendar with the presets people actually reach for. The calendar grid is built on native
`Date` and `Intl` — there is no date library underneath, so installing this does not add a runtime
dependency or a second date API to your project.

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

export function ReportFilters() {
  const [range, setRange] = React.useState<DateRange | null>(null);

  return <DateRangePicker value={range} onValueChange={setRange} />;
}
```

## Value

A range is `{ start: Date; end: Date | null }`, or `null` when nothing is selected. `end` is `null`
while a range is half-selected — the user has clicked a start date and has not yet picked an end.
Treat that as "still choosing" rather than a complete value:

```tsx
const isComplete = range?.end != null;
```

Clicking always moves forward: the first click starts a range, the second completes it, and a third
starts over. Clicking before the current start extends backwards instead of restarting, which is
what people expect when they overshoot.

`DateRangePicker` is controlled with `value` / `onValueChange` and uncontrolled with `defaultValue`.

## Presets

Presets render beside the calendar and are shown by default. Pass your own, or `presets={false}` to
hide them:

```tsx
<DateRangePicker
  presets={[
    { label: "This sprint", getValue: () => ({ start: sprintStart, end: sprintEnd }) },
    { label: "All time", getValue: () => ({ start: projectStart, end: new Date() }) },
  ]}
/>
```

`getValue` runs when the preset is clicked, not when it is defined, so relative presets such as
"Last 7 days" stay correct in a long-lived tab. The built-in list is exported as `defaultPresets` if
you want to extend rather than replace it:

```tsx
<DateRangePicker presets={[...defaultPresets, myPreset]} />
```

A preset renders as pressed when the current range matches it exactly.

## Props

| Prop             | Default | Description                                                       |
| ---------------- | ------- | ----------------------------------------------------------------- |
| `value`          | —       | Controlled range.                                                  |
| `defaultValue`   | `null`  | Uncontrolled initial range.                                        |
| `onValueChange`  | —       | Called with the next range, or `null` when cleared.                |
| `numberOfMonths` | `2`     | How many months to show side by side.                              |
| `weekStartsOn`   | `1`     | First day of the week, `0` Sunday through `6` Saturday.            |
| `locale`         | —       | BCP 47 tag for month, weekday, and label formatting.               |
| `min` / `max`    | —       | Selectable bounds. Days outside them are disabled.                 |
| `presets`        | —       | Preset list, or `false` to hide the column.                        |
| `disabled`       | `false` | Disables the whole picker.                                         |

`weekStartsOn` is explicit rather than derived from `locale`, because the browser API that reports a
locale's first weekday is still not available everywhere. Set it once alongside your locale:

```tsx
<DateRangePicker locale="en-US" weekStartsOn={0} />
```

## Popover trigger

The item ships the panel, not the trigger, so it composes with whatever overlay you already use:

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    {formatRangeLabel(range)}
  </PopoverTrigger>
  <PopoverContent className="w-auto p-2">
    <DateRangePicker value={range} onValueChange={setRange} />
  </PopoverContent>
</Popover>
```

`formatRangeLabel` is exported for exactly this: it renders a complete range through
`formatDateRange`, a half-selected range as a prompt for the end date, and an empty range as
placeholder text.

## Accessibility

Each month is a `role="grid"` with `columnheader` weekday labels and `gridcell` days. A roving
tabindex keeps one day in the tab order, so the calendar is a single tab stop and arrow keys move
within it. Every day button is labelled with its full date, and focus follows keyboard navigation
across month boundaries — paging to a month that is not visible scrolls it into view and moves focus
with it.

| Key                   | Action                          |
| --------------------- | ------------------------------- |
| `←` `→`               | Previous / next day             |
| `↑` `↓`               | Previous / next week            |
| `Home` `End`          | First / last day of the week    |
| `Page Up` `Page Down` | Previous / next month           |
| `Shift` + `Page Up/Down` | Previous / next year         |
| `Enter` `Space`       | Select the focused day          |

Day arithmetic normalizes to midnight on every step, so ranges stay correct across daylight saving
boundaries — a week that contains a clock change is still seven days.


---

URL: https://mwui.vercel.app/components/file-dropzone.md

A drag-and-drop file input with previews, validation, and per-file progress.

# File Dropzone

A drag-and-drop file input with previews, validation, and per-file progress.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/file-dropzone.json
```

[Registry JSON](https://mwui.vercel.app/r/file-dropzone.json)

## Preview

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

export function Preview() {
  return (
    <div className="w-full max-w-md">
      <FileDropzone
        accept="image/*,.pdf"
        maxSize={2 * 1024 * 1024}
        maxFiles={4}
        label="Drop attachments here"
        onUpload={(_item, { onProgress, signal }) =>
          new Promise<void>((resolve, reject) => {
            let step = 0;

            const timer = setInterval(() => {
              step += 1;
              onProgress(step / 12);

              if (signal.aborted) {
                clearInterval(timer);
                resolve();
                return;
              }

              if (step >= 12) {
                clearInterval(timer);

                if (Math.random() < 0.25) {
                  reject(new Error("The server rejected this file."));
                  return;
                }

                resolve();
              }
            }, 120);
          })
        }
      />
    </div>
  );
}
```


## Source

### ui/file-dropzone.tsx

```tsx
"use client";

import { IconAlertCircle, IconFile, IconRefresh, IconUpload, IconX } from "@tabler/icons-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import {
  formatBytes,
  useFileUpload,
  type UploadFile,
  type UseFileUploadOptions,
} from "@/hooks/use-file-upload";
import { cn } from "@/lib/utils";

type FileDropzoneProps = Omit<React.ComponentProps<"div">, "onChange"> & {
  accept?: string;
  maxSize?: number;
  maxFiles?: number;
  multiple?: boolean;
  disabled?: boolean;
  label?: string;
  description?: string;
  onUpload?: UseFileUploadOptions["onUpload"];
  onFilesChange?: (files: UploadFile[]) => void;
};

function FileDropzone({
  accept,
  maxSize,
  maxFiles,
  multiple = true,
  disabled = false,
  label = "Drop files here",
  description,
  onUpload,
  onFilesChange,
  className,
  ...props
}: FileDropzoneProps) {
  const upload = useFileUpload({
    accept,
    maxSize,
    maxFiles,
    multiple,
    disabled,
    onUpload,
    autoUpload: onUpload !== undefined,
    onFilesChange,
  });

  const hint =
    description ??
    [
      accept ? describeAccept(accept) : null,
      maxSize ? `up to ${formatBytes(maxSize)}` : null,
      maxFiles ? `${maxFiles} files max` : null,
    ]
      .filter(Boolean)
      .join(" · ");

  return (
    <div
      data-slot="file-dropzone"
      className={cn("flex w-full flex-col gap-2", className)}
      {...props}
    >
      <div
        {...upload.getDropzoneProps()}
        data-dragging={upload.isDragging || undefined}
        data-disabled={disabled || undefined}
        className={cn(
          "flex flex-col items-center justify-center gap-2 rounded-xl border border-dashed border-border bg-background px-6 py-8 text-center transition-colors",
          "data-dragging:border-ring data-dragging:bg-muted/50",
          "data-disabled:pointer-events-none data-disabled:opacity-50",
        )}
      >
        <div className="flex size-9 items-center justify-center rounded-full bg-muted text-muted-foreground">
          <IconUpload className="size-4" />
        </div>

        <div className="flex flex-col gap-0.5">
          <p className="text-sm font-medium">{label}</p>
          {hint ? <p className="text-xs text-muted-foreground">{hint}</p> : null}
        </div>

        <input {...upload.getInputProps()} />

        <Button type="button" size="sm" variant="outline" onClick={upload.openFileDialog}>
          Browse files
        </Button>
      </div>

      {upload.rejections.length > 0 ? (
        <ul className="flex flex-col gap-1">
          {upload.rejections.map((rejection) => (
            <li
              key={`${rejection.file.name}-${rejection.reason}`}
              className="flex items-center gap-1.5 text-xs text-destructive"
            >
              <IconAlertCircle className="size-3.5 shrink-0" />
              {rejection.message}
            </li>
          ))}
        </ul>
      ) : null}

      {upload.files.length > 0 ? (
        <ul className="flex flex-col gap-2">
          {upload.files.map((item) => (
            <li
              key={item.id}
              data-status={item.status}
              className="flex items-center gap-3 rounded-lg border border-border p-2 data-[status=error]:border-destructive/40"
            >
              <FilePreview file={item} />

              <div className="flex min-w-0 flex-1 flex-col gap-1">
                <div className="flex items-baseline justify-between gap-2">
                  <span className="truncate text-sm">{item.file.name}</span>
                  <span className="shrink-0 text-xs text-muted-foreground tabular-nums">
                    {formatBytes(item.file.size)}
                  </span>
                </div>

                {item.status === "error" ? (
                  <span className="text-xs text-destructive">{item.error}</span>
                ) : onUpload ? (
                  <div
                    role="progressbar"
                    aria-label={`Uploading ${item.file.name}`}
                    aria-valuenow={Math.round(item.progress * 100)}
                    className="h-1 overflow-hidden rounded-full bg-muted"
                  >
                    <div
                      className="h-full rounded-full bg-primary transition-[width] duration-200 ease-out"
                      style={{ width: `${item.progress * 100}%` }}
                    />
                  </div>
                ) : null}
              </div>

              {item.status === "error" ? (
                <Button
                  type="button"
                  size="icon-xs"
                  variant="ghost"
                  aria-label={`Retry ${item.file.name}`}
                  onClick={() => upload.retryFile(item.id)}
                >
                  <IconRefresh />
                </Button>
              ) : null}

              <Button
                type="button"
                size="icon-xs"
                variant="ghost"
                aria-label={`Remove ${item.file.name}`}
                onClick={() => upload.removeFile(item.id)}
              >
                <IconX />
              </Button>
            </li>
          ))}
        </ul>
      ) : null}
    </div>
  );
}

function FilePreview({ file }: { file: UploadFile }) {
  if (file.previewUrl) {
    return (
      <img
        src={file.previewUrl}
        alt=""
        className="size-9 shrink-0 rounded-md border border-border object-cover"
      />
    );
  }

  return (
    <div className="flex size-9 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
      <IconFile className="size-4" />
    </div>
  );
}

function describeAccept(accept: string): string {
  const parts = accept
    .split(",")
    .map((part) => part.trim())
    .filter(Boolean)
    .map((part) => (part.endsWith("/*") ? `${part.slice(0, -2)}s` : part.replace(/^\./u, "")));

  return parts.join(", ").toUpperCase();
}

export { FileDropzone, type FileDropzoneProps };
```



## Usage

A drop target, a real file input, image thumbnails, size and type validation, and a progress row per
file. All of the state lives in [useFileUpload](/utilities/use-file-upload), so the component is
markup — swap it for your own layout without rewriting the logic.

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

export function Attachments() {
  return (
    <FileDropzone
      accept="image/*,.pdf"
      maxSize={5 * 1024 * 1024}
      maxFiles={5}
      onFilesChange={setAttachments}
    />
  );
}
```

Without `onUpload` the dropzone is a collector: it validates and lists files and hands them to
`onFilesChange`, and you submit them with the rest of your form.

## Uploading

Pass `onUpload` and each accepted file uploads immediately, with a progress bar, an error state, and
a retry button.

```tsx
<FileDropzone
  accept="image/*"
  onUpload={async (item, { onProgress, signal }) => {
    const body = new FormData();
    body.append("file", item.file);

    await fetch("/api/upload", { method: "POST", body, signal });
    onProgress(1);
  }}
/>
```

`signal` aborts if the file is removed mid-flight, so cancelling actually cancels. Real byte-level
progress needs `XMLHttpRequest` — `fetch` cannot report it — and `onProgress` takes a fraction from
`0` to `1`.

## Validation

`accept` is enforced on drop as well as in the picker. The browser applies the `accept` attribute
only to the file dialog, so a dragged `.exe` would otherwise sail through.

Rejected files never enter the list; they render above it with a specific reason — wrong type, too
large, over the file count, or already added.

## Props

| Prop            | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `accept`        | Same syntax as the `accept` attribute: `"image/*,.pdf"`.                  |
| `maxSize`       | Per-file limit in bytes.                                                  |
| `maxFiles`      | Maximum number of accepted files.                                         |
| `multiple`      | When `false`, a new selection replaces the current file.                   |
| `onUpload`      | Upload transport. Enables progress, errors, and retry.                    |
| `onFilesChange` | Called with the full list after every change.                             |
| `label`         | Headline inside the drop target.                                          |
| `description`   | Overrides the hint line, which is otherwise derived from the constraints. |
| `disabled`      | Ignore selection and drops.                                               |

## Behavior

- Drag state uses enter/leave depth counting, so dragging across a child element does not flicker the
  highlight.
- Image previews are object URLs, revoked when the file is removed or the component unmounts.
- The file input stays in the DOM and is visually hidden rather than replaced by a button, so
  keyboard and assistive-technology users get the native picker.


---

URL: https://mwui.vercel.app/components/multi-select.md

A multi-select combobox with chips, async search, and grouped options.

# Multi Select

A multi-select combobox with chips, async search, and grouped options.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/multi-select.json
```

[Registry JSON](https://mwui.vercel.app/r/multi-select.json)

## Preview

```tsx
import * as React from "react";

import { MultiSelect } from "@/components/ui/multi-select";

const OPTIONS = [
  { value: "alice", label: "Alice Nguyen", group: "Design" },
  { value: "bruno", label: "Bruno Costa", group: "Design" },
  { value: "chen", label: "Chen Wei", group: "Engineering" },
  { value: "dara", label: "Dara Okafor", group: "Engineering" },
  { value: "elif", label: "Elif Demir", group: "Engineering" },
  { value: "farid", label: "Farid Haddad", group: "Sales" },
  { value: "gita", label: "Gita Rao", group: "Sales" },
];

export function Preview() {
  const [assignees, setAssignees] = React.useState<string[]>(["alice", "chen"]);

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <MultiSelect
        options={OPTIONS}
        value={assignees}
        onValueChange={setAssignees}
        placeholder="Assign people…"
      />

      <p className="font-mono text-xs text-muted-foreground">
        {assignees.length > 0 ? JSON.stringify(assignees) : "[]"}
      </p>
    </div>
  );
}
```


## Source

### ui/multi-select.tsx

```tsx
"use client";

import { Combobox } from "@base-ui/react/combobox";
import { IconCheck, IconChevronDown, IconX } from "@tabler/icons-react";
import * as React from "react";

import { Spinner } from "@/components/ui/spinner";
import { useControllableState } from "@/hooks/use-controllable-state";
import { useDebouncedValue } from "@/hooks/use-debounced-value";
import { cn } from "@/lib/utils";

type MultiSelectOption = {
  value: string;
  label: string;
  disabled?: boolean;
  group?: string;
};

type MultiSelectOptionGroup = {
  value: string;
  items: MultiSelectOption[];
};

function isOptionGroup(
  item: MultiSelectOption | MultiSelectOptionGroup,
): item is MultiSelectOptionGroup {
  return "items" in item;
}

function groupOptions(
  options: MultiSelectOption[],
): MultiSelectOption[] | MultiSelectOptionGroup[] {
  if (!options.some((option) => option.group)) return options;

  const groups = new Map<string, MultiSelectOption[]>();

  for (const option of options) {
    const key = option.group ?? "";
    const existing = groups.get(key);

    if (existing) {
      existing.push(option);
    } else {
      groups.set(key, [option]);
    }
  }

  return Array.from(groups, ([value, items]) => ({ value, items }));
}

type MultiSelectChipsLayout = "wrap" | "scroll";

type MultiSelectProps = Omit<React.ComponentProps<"div">, "defaultValue" | "onChange" | "value"> & {
  options: MultiSelectOption[];
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
  onSearchChange?: (query: string) => void;
  searchDelay?: number;
  loading?: boolean;
  placeholder?: string;
  emptyMessage?: string;
  loadingMessage?: string;
  maxSelected?: number;
  chipsLayout?: MultiSelectChipsLayout;
  disabled?: boolean;
  name?: string;
};

function MultiSelect({
  options,
  value,
  defaultValue = [],
  onValueChange,
  onSearchChange,
  searchDelay = 250,
  loading = false,
  placeholder = "Select options",
  emptyMessage = "No results found.",
  loadingMessage = "Searching…",
  maxSelected,
  chipsLayout = "wrap",
  disabled = false,
  name,
  className,
  ...props
}: MultiSelectProps) {
  const [selected, setSelected] = useControllableState<string[]>({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  const [query, setQuery] = React.useState("");
  const debouncedQuery = useDebouncedValue(query, searchDelay);

  const isAsync = onSearchChange !== undefined;
  const onSearchChangeRef = React.useRef(onSearchChange);

  React.useEffect(() => {
    onSearchChangeRef.current = onSearchChange;
  });

  React.useEffect(() => {
    onSearchChangeRef.current?.(debouncedQuery);
  }, [debouncedQuery]);

  const fieldRef = React.useRef<HTMLDivElement>(null);
  const chipsAreaRef = React.useRef<HTMLDivElement>(null);
  const previousCount = React.useRef(selected.length);
  const [labelCache, setLabelCache] = React.useState<Record<string, string>>({});

  React.useEffect(() => {
    const grew = selected.length > previousCount.current;
    previousCount.current = selected.length;

    if (!grew || chipsLayout !== "scroll") return;

    const area = chipsAreaRef.current;
    if (area) area.scrollLeft = area.scrollWidth;
  }, [selected.length, chipsLayout]);

  React.useEffect(() => {
    setLabelCache((previous) => {
      let changed = false;
      const next = { ...previous };

      for (const option of options) {
        if (next[option.value] !== option.label) {
          next[option.value] = option.label;
          changed = true;
        }
      }

      return changed ? next : previous;
    });
  }, [options]);

  const optionByValue = React.useMemo(
    () => new Map(options.map((option) => [option.value, option])),
    [options],
  );

  const selectedOptions = React.useMemo(
    () =>
      selected.map(
        (item) => optionByValue.get(item) ?? { value: item, label: labelCache[item] ?? item },
      ),
    [selected, optionByValue, labelCache],
  );

  const items = React.useMemo(() => groupOptions(options), [options]);
  const isAtLimit = maxSelected !== undefined && selected.length >= maxSelected;

  const handleValueChange = (next: MultiSelectOption[]) => {
    if (maxSelected !== undefined && next.length > maxSelected) return;
    setSelected(next.map((option) => option.value));
  };

  const renderOption = (option: MultiSelectOption) => (
    <Combobox.Item
      key={option.value}
      value={option}
      disabled={option.disabled ?? (isAtLimit && !selected.includes(option.value))}
      className={cn(
        "flex cursor-default items-center gap-2 rounded-md px-2 py-1.5 text-sm outline-none select-none",
        "data-highlighted:bg-muted data-highlighted:text-foreground",
        "data-disabled:pointer-events-none data-disabled:opacity-50",
      )}
    >
      <span className="flex size-4 shrink-0 items-center justify-center">
        <Combobox.ItemIndicator>
          <IconCheck className="size-4" />
        </Combobox.ItemIndicator>
      </span>
      <span className="truncate">{option.label}</span>
    </Combobox.Item>
  );

  return (
    <Combobox.Root
      multiple
      items={items}
      value={selectedOptions}
      onValueChange={handleValueChange}
      isItemEqualToValue={(a: MultiSelectOption, b: MultiSelectOption) => a.value === b.value}
      itemToStringLabel={(option: MultiSelectOption) => option.label}
      itemToStringValue={(option: MultiSelectOption) => option.value}
      filter={isAsync ? null : undefined}
      disabled={disabled}
      onInputValueChange={setQuery}
    >
      <div
        data-slot="multi-select"
        data-disabled={disabled || undefined}
        className={cn("w-full", className)}
        {...props}
      >
        <Combobox.Chips
          ref={fieldRef}
          className={cn(
            "flex min-h-8 w-full gap-1 rounded-lg border border-border bg-background px-1.5 py-1 text-sm",
            chipsLayout === "scroll" ? "items-center" : "items-start",
            "focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
            "data-disabled:pointer-events-none data-disabled:opacity-50",
          )}
        >
          <div
            ref={chipsAreaRef}
            className={cn(
              "flex min-w-0 flex-1 items-center gap-1",
              chipsLayout === "scroll"
                ? "overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
                : "flex-wrap",
            )}
          >
            {selectedOptions.map((option) => (
              <Combobox.Chip
                key={option.value}
                className={cn(
                  "flex min-w-0 items-center gap-1 rounded-md bg-muted py-0.5 pr-0.5 pl-1.5 text-xs text-foreground",
                  chipsLayout === "scroll" && "shrink-0",
                )}
              >
                <span className="max-w-40 truncate">{option.label}</span>
                <Combobox.ChipRemove
                  aria-label={`Remove ${option.label}`}
                  className="flex size-4 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-background hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
                >
                  <IconX className="size-3" />
                </Combobox.ChipRemove>
              </Combobox.Chip>
            ))}

            <Combobox.Input
              placeholder={selectedOptions.length > 0 ? undefined : placeholder}
              className="h-6 min-w-16 flex-1 bg-transparent px-1 outline-none placeholder:text-muted-foreground"
            />
          </div>

          <div className="flex h-6 shrink-0 items-center gap-0.5 pr-0.5">
            {loading ? <Spinner className="size-3.5 text-muted-foreground" /> : null}
            {selectedOptions.length > 0 ? (
              <Combobox.Clear
                aria-label="Clear selection"
                className="flex size-5 items-center justify-center rounded-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
              >
                <IconX className="size-3.5" />
              </Combobox.Clear>
            ) : null}
            <Combobox.Trigger
              aria-label="Open options"
              className="flex size-5 items-center justify-center rounded-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
            >
              <Combobox.Icon>
                <IconChevronDown className="size-3.5" />
              </Combobox.Icon>
            </Combobox.Trigger>
          </div>
        </Combobox.Chips>

        {name
          ? selected.map((item) => (
              <input key={item} type="hidden" name={name} value={item} readOnly />
            ))
          : null}
      </div>

      <Combobox.Portal>
        <Combobox.Positioner anchor={fieldRef} sideOffset={4} className="z-50 outline-none">
          <Combobox.Popup
            className={cn(
              "max-h-64 w-(--anchor-width) min-w-56 overflow-y-auto overscroll-contain rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-md",
              "origin-(--transform-origin) transition-[transform,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
            )}
          >
            <Combobox.Status className="px-2 py-1.5 text-sm text-muted-foreground empty:hidden">
              {loading ? loadingMessage : null}
            </Combobox.Status>

            {loading ? null : (
              <Combobox.Empty className="px-2 py-1.5 text-sm text-muted-foreground empty:p-0">
                {emptyMessage}
              </Combobox.Empty>
            )}

            <Combobox.List>
              {(item: MultiSelectOption | MultiSelectOptionGroup) =>
                isOptionGroup(item) ? (
                  <Combobox.Group key={item.value} items={item.items} className="pb-1">
                    <Combobox.GroupLabel className="px-2 py-1 text-xs font-medium text-muted-foreground">
                      {item.value}
                    </Combobox.GroupLabel>
                    <Combobox.Collection>{renderOption}</Combobox.Collection>
                  </Combobox.Group>
                ) : (
                  renderOption(item)
                )
              }
            </Combobox.List>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox.Root>
  );
}

export {
  MultiSelect,
  type MultiSelectChipsLayout,
  type MultiSelectOption,
  type MultiSelectOptionGroup,
  type MultiSelectProps,
};
```



## Usage

A combobox that selects many values, shows them as removable chips, and searches either locally or
against your server. Built on Base UI's `Combobox`, so filtering, typeahead, focus management, and
the listbox interaction model come from a primitive that already handles them.

```tsx
import { MultiSelect } from "@/components/ui/multi-select";

const OPTIONS = [
  { value: "design", label: "Design" },
  { value: "engineering", label: "Engineering" },
  { value: "sales", label: "Sales" },
];

export function TeamFilter() {
  const [teams, setTeams] = React.useState<string[]>([]);

  return <MultiSelect options={OPTIONS} value={teams} onValueChange={setTeams} />;
}
```

The value is a `string[]` of option values — not option objects — so it drops straight into a query
string, a form body, or a database column without mapping.

## Async search

Pass `onSearchChange` and the component switches to server-driven filtering: local filtering is
turned off, and the query is debounced before it reaches you.

```tsx
const [query, setQuery] = React.useState("");
const { data, isLoading } = useSearchContacts(query);

<MultiSelect
  options={data ?? []}
  value={contacts}
  onValueChange={setContacts}
  onSearchChange={setQuery}
  loading={isLoading}
  placeholder="Search contacts…"
/>;
```

Selected options keep their labels even after `options` no longer contains them, which is what makes
async search usable: search "ali", select Alice, search "bob", and Alice is still a chip reading
"Alice" rather than her raw id. Adjust the debounce with `searchDelay`, which defaults to 250ms.

## Groups

Give options a `group` and they render under headings, in first-seen order:

```tsx
const OPTIONS = [
  { value: "alice", label: "Alice", group: "Design" },
  { value: "bob", label: "Bob", group: "Engineering" },
];
```

## Props

| Prop             | Default             | Description                                                  |
| ---------------- | ------------------- | ------------------------------------------------------------ |
| `options`        | —                   | Available options. `{ value, label, disabled?, group? }`.     |
| `value`          | —                   | Controlled selection, as option values.                       |
| `defaultValue`   | `[]`                | Uncontrolled initial selection.                               |
| `onValueChange`  | —                   | Called with the next selection.                               |
| `onSearchChange` | —                   | Enables async mode and receives the debounced query.          |
| `searchDelay`    | `250`               | Debounce applied before `onSearchChange` fires.               |
| `loading`        | `false`             | Shows a spinner and the loading message.                      |
| `maxSelected`    | —                   | Caps the selection; unselected options disable at the cap.    |
| `chipsLayout`    | `"wrap"`            | `"wrap"` grows the field over multiple lines; `"scroll"` keeps one row. |
| `placeholder`    | `"Select options"`  | Input placeholder, hidden once anything is selected.          |
| `emptyMessage`   | `"No results found."` | Shown when nothing matches.                                 |
| `disabled`       | `false`             | Disables the whole control.                                   |
| `name`           | —                   | Submits one hidden input per selected value.                  |

## Chips layout

By default the field wraps onto a second line as selections accumulate. In a table row or a tight
form grid that growth shifts the surrounding layout, so `chipsLayout="scroll"` keeps the field at a
single row and scrolls the chips horizontally instead:

```tsx
<MultiSelect chipsLayout="scroll" options={ROLES} />
```

The scrollbar is hidden, and selecting an option scrolls the newest chip into view so it never lands
off-screen. The trade-off is that chips past the right edge are not visible at a glance — prefer
`"wrap"` when the full selection needs to be readable, and pair `"scroll"` with `maxSelected` when
the count should stay small.

## Forms

`name` renders a hidden input per selected value, which is how HTML forms represent a multi-value
field:

```tsx
<MultiSelect name="tags" options={TAGS} defaultValue={["urgent"]} />
```

On the server, `formData.getAll("tags")` returns the array.

## Accessibility

Base UI supplies the combobox semantics: the input is `role="combobox"` with `aria-expanded` and
`aria-activedescendant`, and the popup is a listbox whose options carry `aria-selected`. Typeahead,
highlight, and focus return on close are handled by the primitive.

Each chip's remove button is labelled with the option it removes — "Remove Alice", not "Remove" —
so a screen reader user hears which chip they are on without inspecting the surrounding text.


---

URL: https://mwui.vercel.app/components/otp-input.md

A one-time-code input with per-character slots and paste support.

# OTP Input

A one-time-code input with per-character slots and paste support.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/otp-input.json
```

[Registry JSON](https://mwui.vercel.app/r/otp-input.json)

## Preview

```tsx
import * as React from "react";

import { OtpInput } from "@/components/ui/otp-input";

export function Preview() {
  const [code, setCode] = React.useState("");
  const [status, setStatus] = React.useState("Waiting for a code.");

  return (
    <div className="flex w-full max-w-sm flex-col gap-6 text-sm">
      <div className="flex flex-col gap-2">
        <p className="font-medium">Six digits, grouped</p>
        <OtpInput
          value={code}
          onValueChange={setCode}
          groupSize={3}
          onComplete={(value) => setStatus(`Submitted ${value}.`)}
        />
        <p className="text-xs text-muted-foreground">{status}</p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Alphanumeric, masked</p>
        <OtpInput length={4} pattern="alphanumeric" mask aria-label="Backup code" />
      </div>
    </div>
  );
}
```


## Source

### ui/otp-input.tsx

```tsx
"use client";

import * as React from "react";

import { useControllableState } from "@/hooks/use-controllable-state";
import { cn } from "@/lib/utils";

type OtpInputPattern = "numeric" | "alphanumeric" | RegExp;

type OtpInputProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "onPaste" | "value"
> & {
  length?: number;
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  onComplete?: (value: string) => void;
  pattern?: OtpInputPattern;
  groupSize?: number;
  separator?: React.ReactNode;
  mask?: boolean;
  disabled?: boolean;
  autoFocus?: boolean;
  name?: string;
  "aria-label"?: string;
};

function OtpInput({
  length = 6,
  value,
  defaultValue = "",
  onValueChange,
  onComplete,
  pattern = "numeric",
  groupSize,
  separator = "-",
  mask = false,
  disabled = false,
  autoFocus = false,
  name,
  className,
  "aria-label": ariaLabel = "One-time code",
  ...props
}: OtpInputProps) {
  const [code, setCode] = useControllableState<string>({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  const [focused, setFocused] = React.useState(false);
  const [caret, setCaret] = React.useState({ start: 0, end: 0 });

  const inputRef = React.useRef<HTMLInputElement>(null);
  const allowed = React.useMemo(() => toRegExp(pattern), [pattern]);

  React.useEffect(() => {
    if (autoFocus) inputRef.current?.focus();
  }, [autoFocus]);

  const syncCaret = () => {
    const input = inputRef.current;
    if (!input) return;

    setCaret({ start: input.selectionStart ?? 0, end: input.selectionEnd ?? 0 });
  };

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const next = Array.from(event.target.value)
      .filter((character) => allowed.test(character))
      .join("")
      .slice(0, length);

    setCode(next);
    if (next.length === length && next !== code) onComplete?.(next);
  };

  const isRangeSelection = caret.end - caret.start > 1;
  const activeIndex = Math.min(caret.start, length - 1);

  return (
    <div
      data-slot="otp-input"
      data-disabled={disabled || undefined}
      className={cn(
        "relative inline-flex w-fit items-center gap-1.5 data-disabled:pointer-events-none data-disabled:opacity-50",
        className,
      )}
      {...props}
    >
      <input
        ref={inputRef}
        value={code}
        name={name}
        disabled={disabled}
        inputMode={pattern === "numeric" ? "numeric" : "text"}
        autoComplete="one-time-code"
        aria-label={ariaLabel}
        maxLength={length}
        className="absolute inset-0 z-10 w-full bg-transparent text-transparent caret-transparent opacity-0 outline-none"
        onChange={handleChange}
        onSelect={syncCaret}
        onKeyUp={syncCaret}
        onPointerUp={syncCaret}
        onFocus={() => {
          setFocused(true);
          syncCaret();
        }}
        onBlur={() => setFocused(false)}
      />

      {Array.from({ length }, (_, index) => {
        const character = code[index];
        const active =
          focused &&
          !disabled &&
          (isRangeSelection ? index >= caret.start && index < caret.end : index === activeIndex);

        return (
          <React.Fragment key={index}>
            {groupSize && index > 0 && index % groupSize === 0 ? (
              <span aria-hidden="true" className="px-0.5 text-muted-foreground">
                {separator}
              </span>
            ) : null}

            <div
              data-slot="otp-input-slot"
              data-active={active || undefined}
              data-filled={character !== undefined || undefined}
              aria-hidden="true"
              className={cn(
                "relative flex h-10 w-9 items-center justify-center rounded-lg border border-input bg-transparent text-sm font-medium transition-colors",
                "data-active:border-ring data-active:ring-3 data-active:ring-ring/50",
              )}
            >
              {character === undefined ? null : mask ? (
                <span className="size-2 rounded-full bg-foreground" />
              ) : (
                character
              )}

              {active && character === undefined && !isRangeSelection ? (
                <span className="absolute h-4 w-px animate-caret-blink bg-foreground" />
              ) : null}
            </div>
          </React.Fragment>
        );
      })}
    </div>
  );
}

function toRegExp(pattern: OtpInputPattern): RegExp {
  if (pattern instanceof RegExp) return pattern;
  if (pattern === "alphanumeric") return /^[a-z0-9]$/iu;

  return /^[0-9]$/u;
}

export { OtpInput, type OtpInputPattern, type OtpInputProps };
```



## Usage

Verification codes deserve one box per character, and every implementation that renders one real
`<input>` per box breaks something: paste fills only the first slot, iOS SMS autofill does not fire,
backspace across boundaries gets weird, and the whole thing is unusable to a screen reader.

This one is a single input — transparent, stretched across the field — with the boxes drawn behind
it. The platform keeps doing its job.

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

export function VerifyForm() {
  return <OtpInput length={6} onComplete={(code) => verify(code)} />;
}
```

`onComplete` fires as soon as the last slot fills, which is the moment to submit — asking someone to
press a button after typing the sixth digit is a step nobody needs.

## What you get for free

- **Paste** puts the whole code in, from anywhere in the field.
- **SMS autofill** works: `autocomplete="one-time-code"` on a real input is what iOS and Android look
  for. Splitting into several inputs is exactly what disables it.
- **Selection** behaves — shift-arrow, select-all, drag — and the highlighted slots follow it.
- **Password managers and IME** see one ordinary text field.

## Format

```tsx
<OtpInput length={6} groupSize={3} />
<OtpInput length={4} pattern="alphanumeric" />
<OtpInput length={6} mask />
```

`pattern` accepts `"numeric"` (the default), `"alphanumeric"`, or your own single-character `RegExp`
— characters that fail it are dropped as they arrive, including from a paste, so a copied code with
spaces or dashes still lands correctly.

`groupSize` inserts a separator every N slots. `mask` renders dots, for codes that act as secrets
rather than transcriptions.

## Props

| Prop           | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `length`       | Number of slots. Defaults to `6`.                                     |
| `value` / `defaultValue` / `onValueChange` | Controlled or uncontrolled string.         |
| `onComplete`   | Called with the full code once the last slot fills.                   |
| `pattern`      | `"numeric"`, `"alphanumeric"`, or a single-character `RegExp`.         |
| `groupSize`    | Insert `separator` every N slots.                                     |
| `separator`    | Node rendered between groups. Defaults to `"-"`.                      |
| `mask`         | Render filled slots as dots.                                          |
| `name`         | Posts the code in a plain HTML form.                                  |
| `aria-label`   | Labels the field. Defaults to `"One-time code"`.                      |

## Accessibility

The slots are `aria-hidden` decoration; the input underneath carries the label and the value, so
assistive technology reads a single labelled text field rather than announcing six unlabelled boxes.
The blinking caret is drawn on the active empty slot, since the real caret is hidden.


---

URL: https://mwui.vercel.app/components/phone-input.md

An international phone input with country select and formatting.

# Phone Input

An international phone input with country select and formatting.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/phone-input.json
```

[Registry JSON](https://mwui.vercel.app/r/phone-input.json)

## Preview

```tsx
import * as React from "react";

import { PhoneInput } from "@/components/ui/phone-input";

export function Preview() {
  const [phone, setPhone] = React.useState("");

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <PhoneInput value={phone} onValueChange={setPhone} defaultCountry="PT" />

      <p className="font-mono text-xs text-muted-foreground">{phone || '""'}</p>

      <p className="text-xs text-muted-foreground">
        Try pasting <span className="font-mono">+44 7700 900123</span> — the country follows the
        number.
      </p>
    </div>
  );
}
```


## Source

### ui/phone-input.tsx

```tsx
"use client";

import { Combobox } from "@base-ui/react/combobox";
import { IconCheck, IconChevronDown } from "@tabler/icons-react";
import * as React from "react";

import { useControllableState } from "@/hooks/use-controllable-state";
import { cn } from "@/lib/utils";

type PhoneCountry = {
  code: string;
  name: string;
  dial: string;
  groups?: number[];
};

const DEFAULT_COUNTRIES: PhoneCountry[] = [
  { code: "US", name: "United States", dial: "1", groups: [3, 3, 4] },
  { code: "CA", name: "Canada", dial: "1", groups: [3, 3, 4] },
  { code: "GB", name: "United Kingdom", dial: "44", groups: [4, 6] },
  { code: "IE", name: "Ireland", dial: "353", groups: [2, 3, 4] },
  { code: "PT", name: "Portugal", dial: "351", groups: [3, 3, 3] },
  { code: "ES", name: "Spain", dial: "34", groups: [3, 3, 3] },
  { code: "FR", name: "France", dial: "33", groups: [1, 2, 2, 2, 2] },
  { code: "DE", name: "Germany", dial: "49", groups: [4, 7] },
  { code: "IT", name: "Italy", dial: "39", groups: [3, 3, 4] },
  { code: "NL", name: "Netherlands", dial: "31", groups: [2, 3, 4] },
  { code: "BE", name: "Belgium", dial: "32", groups: [3, 2, 2, 2] },
  { code: "LU", name: "Luxembourg", dial: "352", groups: [3, 3, 3] },
  { code: "CH", name: "Switzerland", dial: "41", groups: [2, 3, 2, 2] },
  { code: "AT", name: "Austria", dial: "43", groups: [3, 3, 4] },
  { code: "DK", name: "Denmark", dial: "45", groups: [2, 2, 2, 2] },
  { code: "SE", name: "Sweden", dial: "46", groups: [2, 3, 2, 2] },
  { code: "NO", name: "Norway", dial: "47", groups: [3, 2, 3] },
  { code: "FI", name: "Finland", dial: "358", groups: [2, 3, 3] },
  { code: "IS", name: "Iceland", dial: "354", groups: [3, 4] },
  { code: "PL", name: "Poland", dial: "48", groups: [3, 3, 3] },
  { code: "CZ", name: "Czechia", dial: "420", groups: [3, 3, 3] },
  { code: "SK", name: "Slovakia", dial: "421", groups: [3, 3, 3] },
  { code: "HU", name: "Hungary", dial: "36", groups: [2, 3, 4] },
  { code: "RO", name: "Romania", dial: "40", groups: [3, 3, 3] },
  { code: "BG", name: "Bulgaria", dial: "359", groups: [3, 3, 3] },
  { code: "GR", name: "Greece", dial: "30", groups: [3, 3, 4] },
  { code: "HR", name: "Croatia", dial: "385", groups: [2, 3, 4] },
  { code: "SI", name: "Slovenia", dial: "386", groups: [2, 3, 3] },
  { code: "RS", name: "Serbia", dial: "381", groups: [2, 3, 4] },
  { code: "UA", name: "Ukraine", dial: "380", groups: [2, 3, 4] },
  { code: "TR", name: "Türkiye", dial: "90", groups: [3, 3, 4] },
  { code: "RU", name: "Russia", dial: "7", groups: [3, 3, 2, 2] },
  { code: "EE", name: "Estonia", dial: "372", groups: [4, 4] },
  { code: "LV", name: "Latvia", dial: "371", groups: [4, 4] },
  { code: "LT", name: "Lithuania", dial: "370", groups: [3, 5] },
  { code: "BR", name: "Brazil", dial: "55", groups: [2, 5, 4] },
  { code: "MX", name: "Mexico", dial: "52", groups: [2, 4, 4] },
  { code: "AR", name: "Argentina", dial: "54", groups: [2, 4, 4] },
  { code: "CL", name: "Chile", dial: "56", groups: [1, 4, 4] },
  { code: "CO", name: "Colombia", dial: "57", groups: [3, 3, 4] },
  { code: "PE", name: "Peru", dial: "51", groups: [3, 3, 3] },
  { code: "AU", name: "Australia", dial: "61", groups: [3, 3, 3] },
  { code: "NZ", name: "New Zealand", dial: "64", groups: [2, 3, 4] },
  { code: "JP", name: "Japan", dial: "81", groups: [2, 4, 4] },
  { code: "KR", name: "South Korea", dial: "82", groups: [2, 4, 4] },
  { code: "CN", name: "China", dial: "86", groups: [3, 4, 4] },
  { code: "HK", name: "Hong Kong", dial: "852", groups: [4, 4] },
  { code: "SG", name: "Singapore", dial: "65", groups: [4, 4] },
  { code: "IN", name: "India", dial: "91", groups: [5, 5] },
  { code: "ID", name: "Indonesia", dial: "62", groups: [3, 4, 4] },
  { code: "MY", name: "Malaysia", dial: "60", groups: [2, 4, 4] },
  { code: "TH", name: "Thailand", dial: "66", groups: [2, 3, 4] },
  { code: "PH", name: "Philippines", dial: "63", groups: [3, 3, 4] },
  { code: "VN", name: "Vietnam", dial: "84", groups: [3, 4, 3] },
  { code: "AE", name: "United Arab Emirates", dial: "971", groups: [2, 3, 4] },
  { code: "SA", name: "Saudi Arabia", dial: "966", groups: [2, 3, 4] },
  { code: "IL", name: "Israel", dial: "972", groups: [2, 3, 4] },
  { code: "EG", name: "Egypt", dial: "20", groups: [3, 3, 4] },
  { code: "MA", name: "Morocco", dial: "212", groups: [3, 3, 3] },
  { code: "NG", name: "Nigeria", dial: "234", groups: [3, 3, 4] },
  { code: "KE", name: "Kenya", dial: "254", groups: [3, 3, 3] },
  { code: "ZA", name: "South Africa", dial: "27", groups: [2, 3, 4] },
];

type PhoneInputProps = Omit<React.ComponentProps<"div">, "defaultValue" | "onChange" | "value"> & {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  defaultCountry?: string;
  onCountryChange?: (country: PhoneCountry) => void;
  countries?: PhoneCountry[];
  placeholder?: string;
  disabled?: boolean;
  name?: string;
  "aria-label"?: string;
};

function PhoneInput({
  value,
  defaultValue = "",
  onValueChange,
  defaultCountry = "US",
  onCountryChange,
  countries = DEFAULT_COUNTRIES,
  placeholder = "Phone number",
  disabled = false,
  name,
  className,
  "aria-label": ariaLabel = "Phone number",
  ...props
}: PhoneInputProps) {
  const [phone, setPhone] = useControllableState<string>({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  const fallback = countries.find((country) => country.code === defaultCountry) ?? countries[0];

  const [selected, setSelected] = React.useState<PhoneCountry>(
    () => matchCountry(phone, countries) ?? fallback,
  );

  const matched = matchCountry(phone, countries);
  const country = matched && !phone.startsWith(`+${selected.dial}`) ? matched : selected;
  const national = phone.startsWith(`+${country.dial}`) ? phone.slice(country.dial.length + 1) : "";

  const fieldRef = React.useRef<HTMLDivElement>(null);
  const inputRef = React.useRef<HTMLInputElement>(null);

  const emit = (nextCountry: PhoneCountry, digits: string) => {
    setPhone(digits ? `+${nextCountry.dial}${digits}` : "");
  };

  const handleCountryChange = (nextCountry: PhoneCountry | null) => {
    if (!nextCountry) return;

    setSelected(nextCountry);
    onCountryChange?.(nextCountry);
    emit(nextCountry, national);
    inputRef.current?.focus();
  };

  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const raw = event.target.value;

    // Typing or pasting a full international number switches country.
    if (raw.trimStart().startsWith("+")) {
      const digits = onlyDigits(raw);
      const parsed = matchDialCode(digits, countries);

      if (parsed) {
        setSelected(parsed);
        onCountryChange?.(parsed);
        setPhone(`+${digits}`);
        return;
      }
    }

    emit(country, onlyDigits(raw));
  };

  return (
    <div
      ref={fieldRef}
      data-slot="phone-input"
      data-disabled={disabled || undefined}
      className={cn(
        "flex h-8 w-full items-center rounded-lg border border-input bg-transparent text-sm transition-colors",
        "focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
        "data-disabled:pointer-events-none data-disabled:opacity-50",
        className,
      )}
      {...props}
    >
      <Combobox.Root
        items={countries}
        value={country}
        onValueChange={handleCountryChange}
        isItemEqualToValue={(a: PhoneCountry, b: PhoneCountry) => a.code === b.code}
        itemToStringLabel={(item: PhoneCountry) => `${item.name} +${item.dial}`}
        itemToStringValue={(item: PhoneCountry) => item.code}
        disabled={disabled}
      >
        <Combobox.Trigger
          aria-label={`Country: ${country.name}`}
          className="flex h-full shrink-0 items-center gap-1 rounded-l-lg border-r border-input px-2 outline-none hover:bg-muted focus-visible:bg-muted"
        >
          <span aria-hidden="true">{toFlag(country.code)}</span>
          <span className="text-muted-foreground tabular-nums">+{country.dial}</span>
          <Combobox.Icon>
            <IconChevronDown className="size-3 text-muted-foreground" />
          </Combobox.Icon>
        </Combobox.Trigger>

        <Combobox.Portal>
          <Combobox.Positioner anchor={fieldRef} sideOffset={4} align="start" className="z-50">
            <Combobox.Popup className="flex max-h-72 w-72 origin-(--transform-origin) flex-col overflow-hidden rounded-lg border border-border bg-popover text-popover-foreground shadow-md transition-[transform,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0">
              <div className="border-b border-border p-1">
                <Combobox.Input
                  placeholder="Search country…"
                  className="h-7 w-full rounded-md bg-transparent px-2 text-sm outline-none placeholder:text-muted-foreground"
                />
              </div>

              <Combobox.Empty className="px-3 py-4 text-sm text-muted-foreground empty:p-0">
                No country found.
              </Combobox.Empty>

              <Combobox.List className="overflow-y-auto overscroll-contain p-1">
                {(item: PhoneCountry) => (
                  <Combobox.Item
                    key={item.code}
                    value={item}
                    className="flex cursor-default items-center gap-2 rounded-md px-2 py-1.5 text-sm outline-none select-none data-highlighted:bg-muted"
                  >
                    <span className="flex size-4 shrink-0 items-center justify-center">
                      <Combobox.ItemIndicator>
                        <IconCheck className="size-4" />
                      </Combobox.ItemIndicator>
                    </span>
                    <span aria-hidden="true">{toFlag(item.code)}</span>
                    <span className="flex-1 truncate">{item.name}</span>
                    <span className="text-xs text-muted-foreground tabular-nums">+{item.dial}</span>
                  </Combobox.Item>
                )}
              </Combobox.List>
            </Combobox.Popup>
          </Combobox.Positioner>
        </Combobox.Portal>
      </Combobox.Root>

      <input
        ref={inputRef}
        type="tel"
        inputMode="tel"
        autoComplete="tel"
        aria-label={ariaLabel}
        placeholder={placeholder}
        disabled={disabled}
        value={formatNational(national, country.groups)}
        onChange={handleInputChange}
        className="h-full min-w-0 flex-1 bg-transparent px-2 outline-none placeholder:text-muted-foreground"
      />

      {name ? <input type="hidden" name={name} value={phone} readOnly /> : null}
    </div>
  );
}

function matchCountry(phone: string, countries: PhoneCountry[]): PhoneCountry | null {
  if (!phone.startsWith("+")) return null;

  return matchDialCode(phone.slice(1), countries);
}

function matchDialCode(digits: string, countries: PhoneCountry[]): PhoneCountry | null {
  let best: PhoneCountry | null = null;

  for (const country of countries) {
    if (!digits.startsWith(country.dial)) continue;
    if (!best || country.dial.length > best.dial.length) best = country;
  }

  return best;
}

function formatNational(digits: string, groups?: number[]): string {
  if (!digits) return "";

  const sizes = groups ?? [3, 3, 3, 3];
  const parts: string[] = [];

  let cursor = 0;

  for (const size of sizes) {
    if (cursor >= digits.length) break;

    parts.push(digits.slice(cursor, cursor + size));
    cursor += size;
  }

  if (cursor < digits.length) parts.push(digits.slice(cursor));

  return parts.join(" ");
}

function onlyDigits(value: string): string {
  return value.replace(/\D/gu, "");
}

function toFlag(code: string): string {
  return String.fromCodePoint(
    ...Array.from(code.toUpperCase(), (character) => 0x1_f1_a5 + character.charCodeAt(0)),
  );
}

export { PhoneInput, DEFAULT_COUNTRIES, type PhoneCountry, type PhoneInputProps };
```



## Usage

A searchable country picker joined to a number field, storing one E.164 string. Country lookup and
digit grouping ship in the component, so nothing here pulls in a metadata library.

```tsx
import { PhoneInput } from "@/components/ui/phone-input";

export function ContactField() {
  const [phone, setPhone] = React.useState("");

  return <PhoneInput value={phone} onValueChange={setPhone} defaultCountry="PT" />;
}
```

The value is `"+351912345678"` — country code included, no spaces, no punctuation. That is what
`tel:` links, SMS providers, and every phone column want, and it is the one format that survives a
user changing country later.

## Pasting a full number

Paste `+44 7700 900123` into the field and the country switches to the United Kingdom on its own,
because the dial code is in the string. Longest-prefix matching means `+1` picks the US while `+351`
picks Portugal rather than a shorter partial match.

Setting `value` from outside behaves the same way, so a number loaded from your API renders with the
right flag without you resolving it first.

## Countries

`countries` replaces the built-in list — restrict it to where you actually operate, reorder it to
put your main market first, or extend it:

```tsx
import { PhoneInput, DEFAULT_COUNTRIES } from "@/components/ui/phone-input";

<PhoneInput countries={DEFAULT_COUNTRIES.filter((country) => EU.includes(country.code))} />;
```

Each entry is `{ code, name, dial, groups? }`. `groups` is the digit grouping used for display —
`[3, 3, 3]` renders `912 345 678`. It only affects presentation; the stored value never contains
spaces.

Flags are emoji derived from the ISO code, so there are no image assets to host and nothing to
localize.

## Scope

Formatting here is grouping, not validation. Real phone-number rules — valid prefixes per carrier,
national trunk digits, variable lengths — need a metadata library such as `libphonenumber-js`, which
is roughly 145 kB. If you need to *verify* a number, validate on the server; if you need it to look
right as it is typed, this is enough.

## Props

| Prop              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `value` / `defaultValue` / `onValueChange` | Controlled or uncontrolled E.164 string. |
| `defaultCountry`  | ISO code selected before the user picks one. Defaults to `"US"`.    |
| `onCountryChange` | Called with the country whenever it changes.                        |
| `countries`       | Replace the built-in list.                                          |
| `name`            | Emits a hidden input with the E.164 value for plain HTML forms.     |
| `aria-label`      | Labels the number field. Defaults to `"Phone number"`.              |

## Accessibility

The country trigger announces the current country rather than only showing a flag, since flag emoji
read as the country name in some screen readers and as nothing in others. The number field is a
real `type="tel"` input with `autocomplete="tel"`, so browser autofill works.


---

URL: https://mwui.vercel.app/components/tags-input.md

A free-form chip input with paste splitting, validation, and duplicate handling.

# Tags Input

A free-form chip input with paste splitting, validation, and duplicate handling.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/tags-input.json
```

[Registry JSON](https://mwui.vercel.app/r/tags-input.json)

## Preview

```tsx
import * as React from "react";

import { TagsInput } from "@/components/ui/tags-input";

export function Preview() {
  const [labels, setLabels] = React.useState<string[]>(["design", "urgent"]);
  const [recipients, setRecipients] = React.useState<string[]>([]);

  return (
    <div className="flex w-full max-w-sm flex-col gap-6 text-sm">
      <div className="flex flex-col gap-2">
        <p className="font-medium">Labels</p>
        <TagsInput
          value={labels}
          onValueChange={setLabels}
          max={6}
          aria-label="Labels"
          placeholder="Add a label…"
        />
        <p className="font-mono text-xs text-muted-foreground">{JSON.stringify(labels)}</p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Recipients</p>
        <TagsInput
          value={recipients}
          onValueChange={setRecipients}
          delimiters={[",", " ", ";"]}
          aria-label="Recipients"
          placeholder="name@example.com"
          validate={(tag) =>
            /^[^@\s]+@[^@\s]+\.[^@\s]+$/u.test(tag) ? true : `${tag} is not an email address.`
          }
        />
        <p className="text-xs text-muted-foreground">
          Try pasting <span className="font-mono">a@b.com, c@d.com</span>.
        </p>
      </div>
    </div>
  );
}
```


## Source

### ui/tags-input.tsx

```tsx
"use client";

import { IconX } from "@tabler/icons-react";
import * as React from "react";

import { useControllableState } from "@/hooks/use-controllable-state";
import { cn } from "@/lib/utils";

type TagsInputValidation = true | string;

type TagsInputProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "onInvalid" | "value"
> & {
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
  placeholder?: string;
  delimiters?: string[];
  max?: number;
  allowDuplicates?: boolean;
  validate?: (tag: string) => TagsInputValidation;
  blurBehavior?: "add" | "clear" | "keep";
  disabled?: boolean;
  name?: string;
  "aria-label"?: string;
};

function TagsInput({
  value,
  defaultValue = [],
  onValueChange,
  placeholder = "Add a tag…",
  delimiters = [",", " "],
  max,
  allowDuplicates = false,
  validate,
  blurBehavior = "add",
  disabled = false,
  name,
  className,
  "aria-label": ariaLabel = "Tags",
  ...props
}: TagsInputProps) {
  const [tags, setTags] = useControllableState<string[]>({
    value,
    defaultValue,
    onChange: onValueChange,
    isEqual: (a, b) => a.length === b.length && a.every((tag, index) => tag === b[index]),
  });

  const [draft, setDraft] = React.useState("");
  const [error, setError] = React.useState<string | null>(null);
  const [duplicate, setDuplicate] = React.useState<string | null>(null);

  const errorId = React.useId();
  const inputRef = React.useRef<HTMLInputElement>(null);
  const isFull = max !== undefined && tags.length >= max;

  const flagDuplicate = (tag: string) => {
    setDuplicate(tag);
    window.setTimeout(() => setDuplicate((current) => (current === tag ? null : current)), 600);
  };

  const addTags = (candidates: string[]) => {
    const next = [...tags];
    let rejected: string | null = null;

    for (const candidate of candidates) {
      const tag = candidate.trim();
      if (!tag) continue;

      if (max !== undefined && next.length >= max) {
        rejected = `Up to ${max} tags.`;
        break;
      }

      if (!allowDuplicates && next.includes(tag)) {
        flagDuplicate(tag);
        continue;
      }

      const result = validate?.(tag) ?? true;

      if (result !== true) {
        rejected = typeof result === "string" ? result : `${tag} is not allowed.`;
        continue;
      }

      next.push(tag);
    }

    setError(rejected);
    if (next.length !== tags.length) setTags(next);

    return rejected === null;
  };

  const removeTag = (tag: string) => {
    setError(null);
    setTags(tags.filter((current) => current !== tag));
  };

  const commitDraft = () => {
    if (!draft.trim()) return;
    if (addTags(splitValue(draft, delimiters))) setDraft("");
  };

  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    if (event.key === "Enter") {
      event.preventDefault();
      commitDraft();
      return;
    }

    if (delimiters.includes(event.key) && draft.trim()) {
      event.preventDefault();
      commitDraft();
      return;
    }

    if (event.key === "Backspace" && draft === "" && tags.length > 0) {
      event.preventDefault();
      removeTag(tags[tags.length - 1]);
    }
  };

  return (
    <div
      data-slot="tags-input"
      data-disabled={disabled || undefined}
      className={cn("flex w-full flex-col gap-1.5", className)}
      {...props}
    >
      {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions */}
      <div
        className={cn(
          "flex min-h-8 w-full flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent px-1.5 py-1 text-sm transition-colors",
          "focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
          "data-disabled:pointer-events-none data-disabled:opacity-50",
          error && "border-destructive focus-within:border-destructive",
        )}
        data-disabled={disabled || undefined}
        onClick={() => inputRef.current?.focus()}
      >
        <ul aria-label={ariaLabel} className="contents">
          {tags.map((tag) => (
            <li
              key={tag}
              data-duplicate={tag === duplicate || undefined}
              className={cn(
                "flex items-center gap-1 rounded-md bg-muted py-0.5 pr-0.5 pl-1.5 text-xs text-foreground transition-colors",
                "data-duplicate:bg-destructive/15 data-duplicate:text-destructive",
              )}
            >
              <span className="max-w-40 truncate">{tag}</span>
              <button
                type="button"
                aria-label={`Remove ${tag}`}
                disabled={disabled}
                onClick={() => removeTag(tag)}
                className="flex size-4 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-background hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
              >
                <IconX className="size-3" />
              </button>
            </li>
          ))}
        </ul>

        <input
          ref={inputRef}
          value={draft}
          disabled={disabled || isFull}
          placeholder={isFull ? undefined : tags.length > 0 ? "" : placeholder}
          aria-invalid={error !== null || undefined}
          aria-describedby={error ? errorId : undefined}
          className="h-6 min-w-16 flex-1 bg-transparent px-1 outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed"
          onChange={(event) => {
            setError(null);
            setDraft(event.target.value);
          }}
          onKeyDown={handleKeyDown}
          onPaste={(event) => {
            const text = event.clipboardData.getData("text");
            const parts = splitValue(text, delimiters);

            if (parts.length <= 1) return;

            event.preventDefault();
            addTags(parts);
            setDraft("");
          }}
          onBlur={() => {
            if (blurBehavior === "add") commitDraft();
            if (blurBehavior === "clear") setDraft("");
          }}
        />
      </div>

      {error ? (
        <p id={errorId} role="alert" className="text-xs text-destructive">
          {error}
        </p>
      ) : null}

      {name
        ? tags.map((tag) => <input key={tag} type="hidden" name={name} value={tag} readOnly />)
        : null}
    </div>
  );
}

function splitValue(value: string, delimiters: string[]): string[] {
  const pattern = new RegExp(
    `[${delimiters.map(escapeForCharacterClass).join("")}\\n\\r\\t]+`,
    "u",
  );

  return value.split(pattern).filter(Boolean);
}

function escapeForCharacterClass(value: string): string {
  return value.replace(/[\\\]^-]/gu, "\\$&");
}

export { TagsInput, type TagsInputProps, type TagsInputValidation };
```



## Usage

For values the user types rather than picks: labels, keywords, recipients, allowed domains. Where
[multi-select](/components/multi-select) chooses from a known list, this one accepts anything that
passes your `validate`.

```tsx
import { TagsInput } from "@/components/ui/tags-input";

export function LabelField() {
  const [labels, setLabels] = React.useState<string[]>(["bug"]);

  return <TagsInput value={labels} onValueChange={setLabels} placeholder="Add a label…" />;
}
```

The value is a `string[]`, so it goes straight into a form body or a database column.

## Committing a tag

Enter commits. So does any character in `delimiters`, which defaults to comma and space — set it to
`[","]` alone when tags may contain spaces:

```tsx
<TagsInput delimiters={[","]} placeholder="Add a phrase…" />
```

Backspace on an empty input removes the last tag. Blur commits the draft by default; pass
`blurBehavior="clear"` to discard it, or `"keep"` to leave it in place.

## Pasting

Pasting text that contains delimiters, newlines, or tabs adds every part at once, which is what
makes this usable for a column copied out of a spreadsheet:

```
alice@example.com, bob@example.com, carol@example.com
```

A paste with no delimiter is left alone as ordinary text, so a single value can still be edited
before committing.

## Validation

`validate` returns `true` to accept, or a message to reject. The message renders under the field and
is wired up with `aria-describedby`.

```tsx
<TagsInput
  validate={(tag) => (tag.includes("@") ? true : `${tag} is not an email address.`)}
  onValueChange={setRecipients}
/>
```

Duplicates are rejected silently and the existing chip flashes instead — repeating "already added"
as an error is noise for something the user can see.

## Props

| Prop              | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `value` / `defaultValue` / `onValueChange` | Controlled or uncontrolled `string[]`.             |
| `delimiters`      | Characters that commit the draft. Defaults to `[",", " "]`.                  |
| `max`             | Maximum number of tags. The input disables at the limit.                     |
| `allowDuplicates` | Permit repeated values. Off by default.                                      |
| `validate`        | `(tag) => true \| string`. A string is shown as the error message.           |
| `blurBehavior`    | `"add"` (default), `"clear"`, or `"keep"`.                                   |
| `name`            | Emits one hidden input per tag, so the field posts in a plain HTML form.      |
| `aria-label`      | Labels the chip list. Defaults to `"Tags"`.                                  |

## Accessibility

Tags are a list of `li` elements, each with its own labelled remove button, so a screen reader
announces the count and reads every tag. Rejections use `role="alert"`. Clicking anywhere in the
field forwards focus to the input.


---

URL: https://mwui.vercel.app/components/time-picker.md

A keyboard-first time input with 12/24-hour formats and step granularity.

# Time Picker

A keyboard-first time input with 12/24-hour formats and step granularity.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/time-picker.json
```

[Registry JSON](https://mwui.vercel.app/r/time-picker.json)

## Preview

```tsx
import * as React from "react";

import { TimePicker } from "@/components/ui/time-picker";

export function Preview() {
  const [time, setTime] = React.useState<string | null>("09:30");
  const [precise, setPrecise] = React.useState<string | null>(null);

  return (
    <div className="flex w-full max-w-sm flex-col gap-6 text-sm">
      <div className="flex flex-col gap-2">
        <p className="font-medium">Locale format</p>
        <TimePicker value={time} onValueChange={setTime} step={15} aria-label="Reminder time" />
        <p className="font-mono text-xs text-muted-foreground">{time ?? "null"}</p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">24-hour, with seconds</p>
        <TimePicker
          value={precise}
          onValueChange={setPrecise}
          hourCycle={24}
          withSeconds
          aria-label="Exact time"
        />
        <p className="font-mono text-xs text-muted-foreground">{precise ?? "null"}</p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Outside business hours</p>
        <TimePicker defaultValue="19:45" min="09:00" max="17:00" aria-label="Meeting time" />
      </div>
    </div>
  );
}
```


## Source

### ui/time-picker.tsx

```tsx
"use client";

import { IconClock } from "@tabler/icons-react";
import * as React from "react";

import { useControllableState } from "@/hooks/use-controllable-state";
import { useMounted } from "@/hooks/use-mounted";
import { cn } from "@/lib/utils";

type TimePickerHourCycle = 12 | 24;

type TimeParts = {
  hour: number | null;
  minute: number | null;
  second: number | null;
};

type TimePickerProps = Omit<React.ComponentProps<"div">, "defaultValue" | "onChange" | "value"> & {
  value?: string | null;
  defaultValue?: string | null;
  onValueChange?: (value: string | null) => void;
  hourCycle?: TimePickerHourCycle;
  step?: number;
  withSeconds?: boolean;
  min?: string;
  max?: string;
  disabled?: boolean;
  readOnly?: boolean;
  name?: string;
  "aria-label"?: string;
};

function TimePicker({
  value,
  defaultValue = null,
  onValueChange,
  hourCycle,
  step = 1,
  withSeconds = false,
  min,
  max,
  disabled = false,
  readOnly = false,
  name,
  className,
  "aria-label": ariaLabel = "Time",
  ...props
}: TimePickerProps) {
  const [time, setTime] = useControllableState<string | null>({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  const mounted = useMounted();
  const resolvedHourCycle = hourCycle ?? (mounted ? getLocaleHourCycle() : 24);
  const [draft, setDraft] = React.useState<TimeParts>(() => parseTime(time));
  const [syncedTime, setSyncedTime] = React.useState(time);

  if (time !== syncedTime) {
    setSyncedTime(time);
    setDraft(parseTime(time));
  }

  const parts = draft;

  const containerRef = React.useRef<HTMLDivElement>(null);
  const typing = React.useRef<{ segment: string; digits: string; at: number } | null>(null);

  const commit = (next: TimeParts) => {
    setDraft(next);

    const complete =
      next.hour !== null && next.minute !== null && (!withSeconds || next.second !== null);
    const nextTime = complete ? formatTime(next, withSeconds) : null;

    setSyncedTime(nextTime);
    if (nextTime !== time) setTime(nextTime);
  };

  const focusSibling = (from: HTMLElement, direction: 1 | -1) => {
    const segments = Array.from(
      containerRef.current?.querySelectorAll<HTMLElement>("[data-segment]") ?? [],
    );
    const index = segments.indexOf(from);
    segments[index + direction]?.focus();
  };

  const invalid = isOutOfRange(time, min, max);

  const segmentProps = (segment: "hour" | "minute" | "second") => {
    const max12 = segment === "hour" && resolvedHourCycle === 12;
    const bounds = {
      min: max12 ? 1 : 0,
      max: segment === "hour" ? (max12 ? 12 : 23) : 59,
    };

    const displayed = getDisplayValue(parts, segment, resolvedHourCycle);
    const increment = segment === "minute" ? step : 1;

    const setSegment = (nextDisplayed: number | null) => {
      commit(applySegment(parts, segment, nextDisplayed, resolvedHourCycle));
    };

    return {
      "data-segment": segment,
      role: "spinbutton" as const,
      tabIndex: disabled ? -1 : 0,
      "aria-label": segment,
      "aria-valuemin": bounds.min,
      "aria-valuemax": bounds.max,
      "aria-valuenow": displayed ?? undefined,
      "aria-valuetext": displayed === null ? "Empty" : pad(displayed),
      "aria-disabled": disabled || undefined,
      "aria-readonly": readOnly || undefined,
      "aria-invalid": invalid || undefined,
      onKeyDown: (event: React.KeyboardEvent<HTMLSpanElement>) => {
        if (disabled) return;

        if (event.key === "ArrowUp" || event.key === "ArrowDown") {
          event.preventDefault();
          if (readOnly) return;

          const delta = event.key === "ArrowUp" ? increment : -increment;
          const current = displayed ?? (delta > 0 ? bounds.min - 1 : bounds.max + 1);

          setSegment(wrap(current + delta, bounds.min, bounds.max));
          return;
        }

        if (event.key === "ArrowRight") {
          event.preventDefault();
          focusSibling(event.currentTarget, 1);
          return;
        }

        if (event.key === "ArrowLeft") {
          event.preventDefault();
          focusSibling(event.currentTarget, -1);
          return;
        }

        if (event.key === "Backspace" || event.key === "Delete") {
          event.preventDefault();
          if (readOnly) return;

          typing.current = null;
          setSegment(null);
          return;
        }

        if (!/^[0-9]$/u.test(event.key)) return;

        event.preventDefault();
        if (readOnly) return;

        const previous = typing.current;
        const fresh = !previous || previous.segment !== segment || Date.now() - previous.at > 1500;
        const digits = fresh ? event.key : `${previous.digits}${event.key}`;
        const candidate = Number(digits);

        if (candidate > bounds.max || digits.length > 2) {
          typing.current = { segment, digits: event.key, at: Date.now() };
          setSegment(clampToBounds(Number(event.key), bounds));
          return;
        }

        typing.current = { segment, digits, at: Date.now() };
        setSegment(clampToBounds(candidate, bounds));

        const canExtend = candidate * 10 <= bounds.max && digits.length < 2;

        if (!canExtend) {
          typing.current = null;
          focusSibling(event.currentTarget, 1);
        }
      },
    };
  };

  const dayPeriod = parts.hour === null ? null : parts.hour >= 12 ? "PM" : "AM";

  const setDayPeriod = (next: "AM" | "PM") => {
    if (parts.hour === null) return;

    const base = parts.hour % 12;
    commit({ ...parts, hour: next === "PM" ? base + 12 : base });
  };

  return (
    <div
      ref={containerRef}
      data-slot="time-picker"
      role="group"
      aria-label={ariaLabel}
      aria-disabled={disabled || undefined}
      data-invalid={invalid || undefined}
      className={cn(
        "inline-flex h-8 items-center gap-0.5 rounded-lg border border-input bg-transparent px-2 text-sm transition-colors",
        "focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
        "aria-disabled:pointer-events-none aria-disabled:opacity-50",
        "data-invalid:border-destructive data-invalid:focus-within:ring-destructive/20",
        className,
      )}
      {...props}
    >
      <IconClock className="mr-1 size-3.5 shrink-0 text-muted-foreground" />

      <TimeSegment
        {...segmentProps("hour")}
        value={getDisplayValue(parts, "hour", resolvedHourCycle)}
      />
      <span className="text-muted-foreground">:</span>
      <TimeSegment {...segmentProps("minute")} value={parts.minute} />

      {withSeconds ? (
        <>
          <span className="text-muted-foreground">:</span>
          <TimeSegment {...segmentProps("second")} value={parts.second} />
        </>
      ) : null}

      {resolvedHourCycle === 12 ? (
        <span
          data-segment="day-period"
          role="spinbutton"
          tabIndex={disabled ? -1 : 0}
          aria-label="AM or PM"
          aria-valuetext={dayPeriod ?? "Empty"}
          aria-disabled={disabled || undefined}
          className="ml-1 rounded px-1 py-0.5 tabular-nums outline-none select-none focus:bg-primary focus:text-primary-foreground data-empty:text-muted-foreground"
          data-empty={dayPeriod === null || undefined}
          onKeyDown={(event) => {
            if (disabled || readOnly) return;

            if (event.key === "ArrowUp" || event.key === "ArrowDown") {
              event.preventDefault();
              setDayPeriod(dayPeriod === "PM" ? "AM" : "PM");
              return;
            }

            if (event.key === "ArrowLeft") {
              event.preventDefault();
              focusSibling(event.currentTarget, -1);
              return;
            }

            const key = event.key.toLowerCase();

            if (key === "a" || key === "p") {
              event.preventDefault();
              setDayPeriod(key === "a" ? "AM" : "PM");
            }
          }}
        >
          {dayPeriod ?? "--"}
        </span>
      ) : null}

      {name ? <input type="hidden" name={name} value={time ?? ""} readOnly /> : null}
    </div>
  );
}

type TimeSegmentProps = React.ComponentProps<"span"> & {
  value: number | null;
};

function TimeSegment({ value, className, ...props }: TimeSegmentProps) {
  return (
    <span
      className={cn(
        "rounded px-1 py-0.5 tabular-nums outline-none select-none",
        "focus:bg-primary focus:text-primary-foreground",
        "data-empty:text-muted-foreground",
        className,
      )}
      data-empty={value === null || undefined}
      {...props}
    >
      {value === null ? "--" : pad(value)}
    </span>
  );
}

function parseTime(value: string | null): TimeParts {
  if (!value) return { hour: null, minute: null, second: null };

  const match = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/u.exec(value);
  if (!match) return { hour: null, minute: null, second: null };

  return {
    hour: Number(match[1]),
    minute: Number(match[2]),
    second: match[3] === undefined ? 0 : Number(match[3]),
  };
}

function formatTime(parts: TimeParts, withSeconds: boolean): string {
  const base = `${pad(parts.hour ?? 0)}:${pad(parts.minute ?? 0)}`;
  return withSeconds ? `${base}:${pad(parts.second ?? 0)}` : base;
}

function getDisplayValue(
  parts: TimeParts,
  segment: "hour" | "minute" | "second",
  hourCycle: TimePickerHourCycle,
): number | null {
  if (segment === "minute") return parts.minute;
  if (segment === "second") return parts.second;
  if (parts.hour === null) return null;
  if (hourCycle === 24) return parts.hour;

  return parts.hour % 12 === 0 ? 12 : parts.hour % 12;
}

function applySegment(
  parts: TimeParts,
  segment: "hour" | "minute" | "second",
  displayed: number | null,
  hourCycle: TimePickerHourCycle,
): TimeParts {
  if (segment === "minute") return { ...parts, minute: displayed };
  if (segment === "second") return { ...parts, second: displayed };
  if (displayed === null) return { ...parts, hour: null };
  if (hourCycle === 24) return { ...parts, hour: displayed };

  const wasAfternoon = (parts.hour ?? 0) >= 12;
  const base = displayed % 12;

  return { ...parts, hour: wasAfternoon ? base + 12 : base };
}

function isOutOfRange(value: string | null, min?: string, max?: string): boolean {
  if (!value) return false;
  if (min && value < min) return true;
  if (max && value > max) return true;

  return false;
}

function getLocaleHourCycle(): TimePickerHourCycle {
  if (typeof Intl === "undefined") return 24;

  const [hourPart] = new Intl.DateTimeFormat(undefined, { hour: "numeric" }).formatToParts(
    new Date(2020, 0, 1, 13),
  );

  return hourPart?.value === "1" ? 12 : 24;
}

function pad(value: number): string {
  return String(value).padStart(2, "0");
}

function wrap(value: number, min: number, max: number): number {
  const size = max - min + 1;
  return ((((value - min) % size) + size) % size) + min;
}

function clampToBounds(value: number, bounds: { min: number; max: number }): number {
  return Math.min(bounds.max, Math.max(bounds.min, value));
}

export { TimePicker, type TimePickerHourCycle, type TimePickerProps };
```



## Usage

Segmented hour, minute, and optional second fields that behave the way a native date field does —
type digits and the caret advances, arrows step, each segment announces itself — without inheriting
`<input type="time">`'s unstyleable UI or its inconsistent behavior across browsers.

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

export function ReminderField() {
  const [time, setTime] = React.useState<string | null>("09:30");

  return <TimePicker value={time} onValueChange={setTime} />;
}
```

The value is always 24-hour `"HH:mm"` regardless of what is displayed, and `null` until every
segment is filled. That is the form a `time` column, an ISO timestamp, and a `<input type="hidden">`
all want.

## Hour cycle

Display follows the viewer's locale by default — a US visitor sees `09:30 AM`, a French visitor sees
`09:30` — while the value stays 24-hour. Force it when the domain demands one format:

```tsx
<TimePicker hourCycle={24} withSeconds />
```

The locale is only readable on the client, so a server render cannot know it. Left unset, the field
renders 24-hour on the server and switches to the locale's cycle once mounted — a 12-hour visitor
sees the AM/PM segment appear on hydration. Pass `hourCycle` explicitly to render the same markup on
both sides and avoid that shift.

## Stepping

`step` is the minute increment for the arrow keys. Typing digits is never restricted by it, so a
15-minute grid still permits an exact `09:07` when someone types it.

```tsx
<TimePicker step={15} />
```

## Range

`min` and `max` mark the field invalid — `data-invalid` for styling, `aria-invalid` on the segments —
rather than silently rewriting what the user typed. Clamping input as it is typed makes intermediate
values impossible to reach.

```tsx
<TimePicker min="09:00" max="17:00" />
```

## Props

| Prop            | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `value` / `defaultValue` / `onValueChange` | Controlled or uncontrolled `"HH:mm"` string, or `null`. |
| `hourCycle`     | `12` or `24`. Defaults to the viewer's locale, resolved after mount.     |
| `step`          | Minute increment for the arrow keys. Defaults to `1`.                   |
| `withSeconds`   | Add a seconds segment; the value becomes `"HH:mm:ss"`.                  |
| `min` / `max`   | Flag values outside the range as invalid.                               |
| `readOnly`      | Focusable and announced, but not editable.                              |
| `name`          | Emits a hidden input so the field posts in a plain HTML form.           |

## Keyboard

| Key                | Action                                                            |
| ------------------ | ----------------------------------------------------------------- |
| `↑` / `↓`          | Step the focused segment, wrapping at its bounds.                  |
| `←` / `→`          | Move between segments.                                             |
| `0`–`9`            | Type directly. The caret advances as soon as no further digit fits — `3` in a 24-hour hour segment moves on immediately, `1` waits for a second digit. |
| `Backspace` / `Delete` | Clear the segment.                                             |
| `A` / `P`          | Set AM or PM on the day-period segment.                            |

Each segment is a `spinbutton` with its own label and value text, so a screen reader announces
"hour, 9" rather than reading the whole field as one opaque string. Empty segments read as "Empty"
instead of "minus minus".

## Composing a range

Two pickers and a [date range picker](/components/date-range-picker) make a datetime range without
another component:

```tsx
<DateRangePicker value={range} onValueChange={setRange} />
<TimePicker value={startTime} onValueChange={setStartTime} aria-label="Start time" />
<TimePicker value={endTime} onValueChange={setEndTime} aria-label="End time" />
```


---

URL: https://mwui.vercel.app/components/timeline.md

A vertical timeline for activity feeds and status history.

# Timeline

A vertical timeline for activity feeds and status history.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/timeline.json
```

[Registry JSON](https://mwui.vercel.app/r/timeline.json)

## Preview

```tsx
import { IconAlertTriangle, IconCheck, IconTruck } from "@tabler/icons-react";

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

export function Preview() {
  return (
    <Timeline className="w-full max-w-sm">
      <TimelineItem status="complete">
        <TimelineConnector />
        <TimelineIndicator>
          <IconCheck className="size-3" />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineTitle>Order placed</TimelineTitle>
          <TimelineDescription>Payment authorized for €48.00.</TimelineDescription>
          <TimelineTime date="2026-08-14T09:12:00Z">14 Aug, 09:12</TimelineTime>
        </TimelineContent>
      </TimelineItem>

      <TimelineItem status="error">
        <TimelineConnector />
        <TimelineIndicator>
          <IconAlertTriangle className="size-3" />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineTitle>Delivery attempt failed</TimelineTitle>
          <TimelineDescription>Nobody was home. A second attempt is scheduled.</TimelineDescription>
          <TimelineTime date="2026-08-16T14:03:00Z">16 Aug, 14:03</TimelineTime>
        </TimelineContent>
      </TimelineItem>

      <TimelineItem status="current">
        <TimelineConnector />
        <TimelineIndicator>
          <IconTruck className="size-3" />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineTitle>Out for delivery</TimelineTitle>
          <TimelineDescription>Expected before 18:00.</TimelineDescription>
          <TimelineTime date="2026-08-18T08:40:00Z">Today, 08:40</TimelineTime>
        </TimelineContent>
      </TimelineItem>

      <TimelineItem status="pending">
        <TimelineConnector />
        <TimelineIndicator />
        <TimelineContent>
          <TimelineTitle>Delivered</TimelineTitle>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}
```


## Source

### ui/timeline.tsx

```tsx
"use client";

import { cva, type VariantProps } from "class-variance-authority";
import * as React from "react";

import { cn } from "@/lib/utils";

type TimelineStatus = "complete" | "current" | "pending" | "error";

const TimelineItemContext = React.createContext<{ status: TimelineStatus }>({
  status: "complete",
});

function Timeline({ className, ...props }: React.ComponentProps<"ol">) {
  return <ol data-slot="timeline" className={cn("flex flex-col", className)} {...props} />;
}

type TimelineItemProps = React.ComponentProps<"li"> & {
  status?: TimelineStatus;
};

function TimelineItem({ status = "complete", className, ...props }: TimelineItemProps) {
  const value = React.useMemo(() => ({ status }), [status]);

  return (
    <TimelineItemContext.Provider value={value}>
      <li
        data-slot="timeline-item"
        data-status={status}
        className={cn(
          "group/timeline-item relative grid grid-cols-[auto_1fr] gap-x-3 pb-6 last:pb-0",
          className,
        )}
        {...props}
      />
    </TimelineItemContext.Provider>
  );
}

const indicatorVariants = cva(
  "relative z-10 mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-full border-2 border-background text-[0.625rem] font-medium",
  {
    variants: {
      status: {
        complete: "bg-primary text-primary-foreground",
        current: "bg-background text-foreground ring-2 ring-primary",
        pending: "bg-muted text-muted-foreground",
        error: "bg-destructive/15 text-destructive ring-2 ring-destructive/40",
      },
    },
    defaultVariants: {
      status: "complete",
    },
  },
);

type TimelineIndicatorProps = React.ComponentProps<"div"> &
  Omit<VariantProps<typeof indicatorVariants>, "status">;

function TimelineIndicator({ className, children, ...props }: TimelineIndicatorProps) {
  const { status } = React.useContext(TimelineItemContext);

  return (
    <div
      data-slot="timeline-indicator"
      aria-hidden="true"
      className={cn(indicatorVariants({ status }), className)}
      {...props}
    >
      {children}
    </div>
  );
}

function TimelineConnector({ className, ...props }: React.ComponentProps<"div">) {
  const { status } = React.useContext(TimelineItemContext);

  return (
    <div
      data-slot="timeline-connector"
      aria-hidden="true"
      className={cn(
        "absolute top-6 bottom-1 left-2.5 w-px -translate-x-1/2 group-last/timeline-item:hidden",
        status === "pending" ? "bg-border" : "bg-primary/40",
        className,
      )}
      {...props}
    />
  );
}

function TimelineContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-content"
      className={cn("flex min-w-0 flex-col gap-1 pt-px", className)}
      {...props}
    />
  );
}

function TimelineTitle({ className, ...props }: React.ComponentProps<"p">) {
  return (
    <p
      data-slot="timeline-title"
      className={cn("text-sm leading-5 font-medium text-foreground", className)}
      {...props}
    />
  );
}

function TimelineDescription({ className, ...props }: React.ComponentProps<"p">) {
  return (
    <p
      data-slot="timeline-description"
      className={cn("text-sm text-muted-foreground", className)}
      {...props}
    />
  );
}

type TimelineTimeProps = React.ComponentProps<"time"> & {
  date?: Date | string;
};

function TimelineTime({ date, className, children, ...props }: TimelineTimeProps) {
  const resolved = date === undefined ? undefined : new Date(date);

  return (
    <time
      data-slot="timeline-time"
      dateTime={resolved?.toISOString()}
      className={cn("text-xs text-muted-foreground", className)}
      {...props}
    >
      {children ?? resolved?.toLocaleString()}
    </time>
  );
}

export {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
  type TimelineItemProps,
  type TimelineStatus,
  type TimelineTimeProps,
};
```



## Usage

Composable parts rather than one configured widget, because activity rows never stay simple: one
item needs an avatar, another an inline diff, another a button. You arrange them; the component owns
the rail, the alignment, and the status colors.

```tsx
import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

<Timeline>
  <TimelineItem status="complete">
    <TimelineConnector />
    <TimelineIndicator />
    <TimelineContent>
      <TimelineTitle>Order placed</TimelineTitle>
      <TimelineDescription>Payment authorized.</TimelineDescription>
      <TimelineTime>2 hours ago</TimelineTime>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem status="current">
    <TimelineConnector />
    <TimelineIndicator />
    <TimelineContent>
      <TimelineTitle>In transit</TimelineTitle>
    </TimelineContent>
  </TimelineItem>
</Timeline>;
```

## Status

`status` on the item drives the indicator and the connector below it, and reaches them through
context — so nothing has to be threaded down by hand.

| Status     | Reads as                                        |
| ---------- | ----------------------------------------------- |
| `complete` | Done. Filled indicator, solid rail. The default. |
| `current`  | Where things are now. Ringed, hollow indicator.  |
| `pending`  | Not reached yet. Muted indicator, muted rail.    |
| `error`    | Failed at this step.                             |

## Indicators

An empty `TimelineIndicator` is a dot. Put anything inside it — a number, an icon, a tiny avatar —
and it centers automatically:

```tsx
<TimelineIndicator>
  <IconCheck className="size-3" />
</TimelineIndicator>

<TimelineIndicator className="size-7">
  <img src={user.avatar} alt="" className="size-full rounded-full object-cover" />
</TimelineIndicator>
```

Resizing the indicator does not move the rail, so mixed sizes still line up.

## Connectors

`TimelineConnector` draws the line from an item to the next one and hides itself on the last item,
so you can render it in every row without special-casing the end of the list.

## Timestamps

`TimelineTime` accepts a `Date` or an ISO string and writes a machine-readable `dateTime` attribute.
Pass your own text as children whenever the page is server-rendered:

```tsx
<TimelineTime date={event.createdAt}>{formatRelative(event.createdAt)}</TimelineTime>
```

The automatic fallback formats with the viewer's locale and timezone, which the server does not
know — so it will differ between the server render and the client. Text you supply, or a
[useMounted](/utilities/use-mounted) guard, avoids that.

## Accessibility

The timeline is an ordered list and each entry is a list item, which is what makes it navigable as a
sequence rather than a wall of text. Indicators and connectors are `aria-hidden`, so status must also
be present in the text — "Failed to deliver", not a red dot alone.


---

URL: https://mwui.vercel.app/blocks.md

Composed templates and larger UI sections.

# Blocks

Composed templates and larger UI sections.

- [Schedule Meeting](https://mwui.vercel.app/blocks/schedule-meeting): A booking panel composing a date range, a time window, a phone number, and a confirm step.
- [Team Access Panel](https://mwui.vercel.app/blocks/team-access-panel): A member list with per-row role assignment, a shareable invite link, and guarded access revocation.


---

URL: https://mwui.vercel.app/blocks/schedule-meeting.md

A booking panel composing a date range, a time window, a phone number, and a confirm step.

# Schedule Meeting

A booking panel composing a date range, a time window, a phone number, and a confirm step.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/schedule-meeting.json
```

[Registry JSON](https://mwui.vercel.app/r/schedule-meeting.json)

## Preview

```tsx
import { ScheduleMeeting } from "@/components/schedule-meeting";

export function Preview() {
  return <ScheduleMeeting />;
}
```


## Source

### components/schedule-meeting.tsx

```tsx
"use client";

import { IconCalendarEvent, IconClock, IconPhone } from "@tabler/icons-react";
import * as React from "react";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { ConfirmDialogProvider, useConfirm } from "@/components/ui/confirm-dialog";
import {
  DateRangePicker,
  formatRangeLabel,
  type DateRange,
} from "@/components/ui/date-range-picker";
import { Field, FieldDescription, FieldGroup, FieldLabel } from "@/components/ui/field";
import { PhoneInput } from "@/components/ui/phone-input";
import { Separator } from "@/components/ui/separator";
import { TimePicker } from "@/components/ui/time-picker";
import { cn } from "@/lib/utils";

type MeetingBooking = {
  range: DateRange | null;
  startTime: string | null;
  endTime: string | null;
  phone: string;
};

type ScheduleMeetingProps = React.ComponentProps<"div"> & {
  defaultBooking?: Partial<MeetingBooking>;
  locale?: string;
  onSchedule?: (booking: MeetingBooking) => void | Promise<void>;
};

function ScheduleMeeting({ ...props }: ScheduleMeetingProps) {
  return (
    <ConfirmDialogProvider>
      <ScheduleMeetingCard {...props} />
    </ConfirmDialogProvider>
  );
}

function ScheduleMeetingCard({
  defaultBooking,
  locale,
  onSchedule,
  className,
  ...props
}: ScheduleMeetingProps) {
  const confirm = useConfirm();

  const [range, setRange] = React.useState<DateRange | null>(defaultBooking?.range ?? null);
  const [startTime, setStartTime] = React.useState<string | null>(
    defaultBooking?.startTime ?? "09:00",
  );
  const [endTime, setEndTime] = React.useState<string | null>(defaultBooking?.endTime ?? "09:30");
  const [phone, setPhone] = React.useState(defaultBooking?.phone ?? "");
  const [scheduled, setScheduled] = React.useState(false);

  const booking: MeetingBooking = { range, startTime, endTime, phone };
  const isComplete = Boolean(range?.end && startTime && endTime && phone.trim().length > 6);

  const handleSchedule = async () => {
    const accepted = await confirm({
      title: "Confirm this meeting?",
      description: `${formatRangeLabel(range, locale)} · ${startTime ?? ""}–${endTime ?? ""} · ${phone}`,
      confirmLabel: "Schedule",
      cancelLabel: "Back",
      onConfirm: () => onSchedule?.(booking),
    });

    if (accepted) {
      setScheduled(true);
    }
  };

  return (
    <Card className={cn("w-full max-w-xl", className)} {...props}>
      <CardHeader>
        <CardTitle>Schedule a meeting</CardTitle>
        <CardDescription>Pick the dates, a time window, and a number to call.</CardDescription>
        <CardAction>
          <Badge variant={scheduled ? "default" : "secondary"}>
            {scheduled ? "Scheduled" : "Draft"}
          </Badge>
        </CardAction>
      </CardHeader>

      <CardContent>
        <FieldGroup>
          <Field>
            <FieldLabel htmlFor="schedule-meeting-dates">Dates</FieldLabel>
            <DateRangePicker
              id="schedule-meeting-dates"
              locale={locale}
              numberOfMonths={1}
              onValueChange={(next) => {
                setRange(next);
                setScheduled(false);
              }}
              presets={false}
              value={range}
            />
          </Field>

          <div className="grid gap-4 sm:grid-cols-2">
            <Field>
              <FieldLabel htmlFor="schedule-meeting-start">Starts at</FieldLabel>
              <TimePicker
                id="schedule-meeting-start"
                onValueChange={(next) => {
                  setStartTime(next);
                  setScheduled(false);
                }}
                value={startTime}
              />
            </Field>
            <Field>
              <FieldLabel htmlFor="schedule-meeting-end">Ends at</FieldLabel>
              <TimePicker
                id="schedule-meeting-end"
                min={startTime ?? undefined}
                onValueChange={(next) => {
                  setEndTime(next);
                  setScheduled(false);
                }}
                value={endTime}
              />
              <FieldDescription>Must be after the start time.</FieldDescription>
            </Field>
          </div>

          <Field>
            <FieldLabel htmlFor="schedule-meeting-phone">Contact number</FieldLabel>
            <PhoneInput
              id="schedule-meeting-phone"
              onValueChange={(next) => {
                setPhone(next);
                setScheduled(false);
              }}
              value={phone}
            />
          </Field>
        </FieldGroup>

        <Separator className="my-6" />

        <dl className="grid gap-3 text-sm">
          <SummaryRow icon={<IconCalendarEvent />} label="When">
            {formatRangeLabel(range, locale)}
          </SummaryRow>
          <SummaryRow icon={<IconClock />} label="Time">
            {startTime && endTime ? `${startTime} – ${endTime}` : "No time selected"}
          </SummaryRow>
          <SummaryRow icon={<IconPhone />} label="Call">
            {phone.trim() || "No number yet"}
          </SummaryRow>
        </dl>
      </CardContent>

      <CardFooter className="justify-end gap-2">
        <Button
          onClick={() => {
            setRange(null);
            setPhone("");
            setScheduled(false);
          }}
          variant="ghost"
        >
          Reset
        </Button>
        <Button
          disabled={!isComplete || scheduled}
          onClick={() => {
            void handleSchedule();
          }}
        >
          {scheduled ? "Scheduled" : "Review and schedule"}
        </Button>
      </CardFooter>
    </Card>
  );
}

function SummaryRow({
  icon,
  label,
  children,
}: {
  icon: React.ReactNode;
  label: string;
  children: React.ReactNode;
}) {
  return (
    <div className="flex items-center gap-3">
      <span className="text-muted-foreground [&_svg]:size-4">{icon}</span>
      <dt className="w-12 shrink-0 text-muted-foreground">{label}</dt>
      <dd className="font-medium">{children}</dd>
    </div>
  );
}

export { ScheduleMeeting, type MeetingBooking, type ScheduleMeetingProps };
```



## Usage

A booking panel for scheduling a call. It pairs the date range picker with two time pickers, a
phone input, and a live summary, then routes the submit through a confirmation dialog.

The block renders its own `ConfirmDialogProvider`, so it works standalone without extra setup. The
end time picker receives the start time as its `min`, so the two stay consistent.

```tsx
import { ScheduleMeeting } from "@/components/schedule-meeting";

<ScheduleMeeting
  onSchedule={(booking) => {
    console.log(booking);
  }}
/>;
```

`onSchedule` runs while the confirmation dialog is pending, so returning a promise keeps the dialog
in its loading state until the request settles.


---

URL: https://mwui.vercel.app/blocks/team-access-panel.md

A member list with per-row role assignment, a shareable invite link, and guarded access revocation.

# Team Access Panel

A member list with per-row role assignment, a shareable invite link, and guarded access revocation.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/team-access-panel.json
```

[Registry JSON](https://mwui.vercel.app/r/team-access-panel.json)

## Preview

```tsx
import { TeamAccessPanel } from "@/components/team-access-panel";

export function Preview() {
  return <TeamAccessPanel />;
}
```


## Source

### components/team-access-panel.tsx

```tsx
"use client";

import { IconLink, IconTrash } from "@tabler/icons-react";
import * as React from "react";

import { Avatar, AvatarGroup } from "@/components/ui/avatar-group";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { ConfirmDialogProvider, useConfirm } from "@/components/ui/confirm-dialog";
import { CopyButton } from "@/components/ui/copy-button";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
import { MultiSelect } from "@/components/ui/multi-select";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";

import { defaultInviteLink, defaultMembers, roleOptions, type TeamMember } from "@/lib/team-data";

type TeamAccessPanelProps = React.ComponentProps<"div"> & {
  members?: TeamMember[];
  inviteLink?: string;
  onMembersChange?: (members: TeamMember[]) => void;
};

function TeamAccessPanel({ ...props }: TeamAccessPanelProps) {
  return (
    <ConfirmDialogProvider>
      <TeamAccessPanelCard {...props} />
    </ConfirmDialogProvider>
  );
}

function TeamAccessPanelCard({
  members: membersProp,
  inviteLink = defaultInviteLink,
  onMembersChange,
  className,
  ...props
}: TeamAccessPanelProps) {
  const confirm = useConfirm();
  const [members, setMembers] = React.useState<TeamMember[]>(membersProp ?? defaultMembers);

  const updateMembers = (next: TeamMember[]) => {
    setMembers(next);
    onMembersChange?.(next);
  };

  const handleRolesChange = (id: string, roles: string[]) => {
    updateMembers(members.map((member) => (member.id === id ? { ...member, roles } : member)));
  };

  const handleRevoke = async (member: TeamMember) => {
    const accepted = await confirm({
      title: `Revoke access for ${member.name}?`,
      description:
        "They lose access to every project in this workspace immediately. Type the name to confirm.",
      confirmLabel: "Revoke access",
      confirmText: member.name,
      destructive: true,
    });

    if (accepted) {
      updateMembers(members.filter((item) => item.id !== member.id));
    }
  };

  return (
    <Card className={cn("w-full max-w-2xl [--avatar-ring:var(--card)]", className)} {...props}>
      <CardHeader>
        <CardTitle>Team access</CardTitle>
        <CardDescription>
          {members.length} {members.length === 1 ? "person has" : "people have"} access to this
          workspace.
        </CardDescription>
        <CardAction>
          <AvatarGroup aria-label="Workspace members" people={members} size="sm" />
        </CardAction>
      </CardHeader>

      <CardContent className="space-y-6">
        <InputGroup>
          <InputGroupAddon>
            <IconLink />
          </InputGroupAddon>
          <InputGroupInput aria-label="Invite link" readOnly value={inviteLink} />
          <InputGroupAddon align="inline-end">
            <CopyButton copiedLabel="Copied" copyLabel="Copy link" size="sm" value={inviteLink} />
          </InputGroupAddon>
        </InputGroup>

        <Separator />

        <ul className="divide-y">
          {members.map((member) => (
            <li className="flex flex-wrap items-center gap-4 py-4 first:pt-0" key={member.id}>
              <Avatar name={member.name} src={member.src} />
              <div className="min-w-0 flex-1">
                <p className="truncate text-sm font-medium">{member.name}</p>
                <p className="truncate text-sm text-muted-foreground">{member.email}</p>
              </div>
              <MultiSelect
                aria-label={`Roles for ${member.name}`}
                chipsLayout="scroll"
                className="w-full sm:w-56"
                onValueChange={(roles) => {
                  handleRolesChange(member.id, roles);
                }}
                options={roleOptions}
                placeholder="No roles"
                value={member.roles}
              />
              <Button
                aria-label={`Revoke access for ${member.name}`}
                onClick={() => {
                  void handleRevoke(member);
                }}
                size="icon"
                variant="ghost"
              >
                <IconTrash />
              </Button>
            </li>
          ))}
        </ul>

        {members.length === 0 ? (
          <p className="py-6 text-center text-sm text-muted-foreground">
            Nobody has access yet. Share the invite link to add people.
          </p>
        ) : null}
      </CardContent>
    </Card>
  );
}

export { TeamAccessPanel, type TeamAccessPanelProps };
```


### lib/team-data.ts

```ts
import type { MultiSelectOption } from "@/components/ui/multi-select";

type TeamMember = {
  id: string;
  name: string;
  email: string;
  src?: string;
  roles: string[];
};

const roleOptions: MultiSelectOption[] = [
  { value: "owner", label: "Owner", group: "Administration" },
  { value: "admin", label: "Admin", group: "Administration" },
  { value: "billing", label: "Billing", group: "Administration" },
  { value: "editor", label: "Editor", group: "Workspace" },
  { value: "reviewer", label: "Reviewer", group: "Workspace" },
  { value: "viewer", label: "Viewer", group: "Workspace" },
];

const defaultMembers: TeamMember[] = [
  {
    id: "ana",
    name: "Ana Ribeiro",
    email: "ana@example.com",
    roles: ["owner", "admin"],
  },
  {
    id: "tomas",
    name: "Tomás Lima",
    email: "tomas@example.com",
    roles: ["editor"],
  },
  {
    id: "wei",
    name: "Wei Zhang",
    email: "wei@example.com",
    roles: ["reviewer", "viewer"],
  },
  {
    id: "marta",
    name: "Marta Sousa",
    email: "marta@example.com",
    roles: ["viewer"],
  },
];

const defaultInviteLink = "https://app.example.com/invite/9f3c-24ab-71de";

export { defaultInviteLink, defaultMembers, roleOptions, type TeamMember };
```



## Usage

A workspace access panel. The header summarises members with an avatar group, the invite link sits
in a copyable input group, and each row carries a grouped multi-select for roles plus a destructive
revoke action.

Revoking runs through `confirmText`, so the person's name has to be typed before the action is
allowed. The block renders its own `ConfirmDialogProvider`.

```tsx
import { TeamAccessPanel } from "@/components/team-access-panel";

<TeamAccessPanel
  inviteLink="https://app.example.com/invite/9f3c-24ab-71de"
  onMembersChange={(members) => {
    console.log(members);
  }}
/>;
```

Members and role options ship as a separate data module, so the sample fixture can be swapped for
real data without touching the component.


---

URL: https://mwui.vercel.app/utilities.md

Hooks, libraries, pages, files, themes, fonts, bases, styles, and other items.

# Utilities

Hooks, libraries, pages, files, themes, fonts, bases, styles, and other items.

- [Color Contrast](https://mwui.vercel.app/utilities/color-contrast): WCAG contrast ratios and readable text color selection, with no dependencies.
- [Format](https://mwui.vercel.app/utilities/format): Locale-aware formatters for dates, ranges, currency, numbers, and durations.
- [useControllableState](https://mwui.vercel.app/utilities/use-controllable-state): A hook that makes any component work controlled or uncontrolled from one state API.
- [useCopyToClipboard](https://mwui.vercel.app/utilities/use-copy-to-clipboard): A small hook that copies text and tracks the latest copy result.
- [useDebouncedValue](https://mwui.vercel.app/utilities/use-debounced-value): A hook that defers a rapidly changing value until it settles.
- [useEventListener](https://mwui.vercel.app/utilities/use-event-listener): A hook that attaches a typed event listener with automatic cleanup.
- [useFileUpload](https://mwui.vercel.app/utilities/use-file-upload): A hook that manages file selection, validation, previews, and upload progress.
- [useHotkeys](https://mwui.vercel.app/utilities/use-hotkeys): A hook that binds keyboard shortcuts with modifier and sequence support.
- [useIntersectionObserver](https://mwui.vercel.app/utilities/use-intersection-observer): A hook that tracks whether an element is in the viewport.
- [useLocalStorage](https://mwui.vercel.app/utilities/use-local-storage): A hook that persists state to localStorage and syncs it across tabs.
- [useMediaQuery](https://mwui.vercel.app/utilities/use-media-query): A hook that tracks a CSS media query without tearing during hydration.
- [useMounted](https://mwui.vercel.app/utilities/use-mounted): A hook that reports whether the component has mounted on the client.
- [usePrevious](https://mwui.vercel.app/utilities/use-previous): A hook that remembers the value from before the most recent change.
- [useResizeObserver](https://mwui.vercel.app/utilities/use-resize-observer): A hook that measures an element and updates on resize.
- [useScrollLock](https://mwui.vercel.app/utilities/use-scroll-lock): A hook that locks body scroll without layout shift.


---

URL: https://mwui.vercel.app/utilities/color-contrast.md

WCAG contrast ratios and readable text color selection, with no dependencies.

# Color Contrast

WCAG contrast ratios and readable text color selection, with no dependencies.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/color-contrast.json
```

[Registry JSON](https://mwui.vercel.app/r/color-contrast.json)

## Preview

```tsx
import { getContrastRatio, getReadableTextColor } from "@/lib/color-contrast";

const LIGHT = "#fafafa";
const DARK = "#0a0a0a";

const SWATCHES = [
  { label: "brand", value: "#6400DC" },
  { label: "yellow", value: "#facc15" },
  { label: "blue", value: "#2563eb" },
  { label: "mint", value: "#6ee7b7" },
  { label: "slate", value: "#64748b" },
  { label: "rose", value: "#f43f5e" },
];

export function Preview() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-1.5">
      {SWATCHES.map((swatch) => {
        const tone = getReadableTextColor(swatch.value, { light: LIGHT, dark: DARK });
        const foreground = tone === "light" ? LIGHT : DARK;

        return (
          <div
            className="flex items-baseline justify-between gap-4 rounded-md px-3 py-2 text-sm"
            key={swatch.label}
            style={{ backgroundColor: swatch.value, color: foreground }}
          >
            <span className="font-mono text-xs">{swatch.label}</span>
            <span className="tabular-nums">
              {tone} · {getContrastRatio(swatch.value, foreground).toFixed(2)}:1
            </span>
          </div>
        );
      })}
    </div>
  );
}
```


## Source

### lib/color-contrast.ts

```ts
type Rgb = {
  r: number;
  g: number;
  b: number;
};

type ColorInput = Rgb | string;

type ReadableTone = "light" | "dark";

type ReadableTextColorOptions = {
  light?: ColorInput;
  dark?: ColorInput;
};

const HEX_SHORTHAND_LENGTH = 3;

/**
 * Parses `#abc`, `#aabbcc`, `#aabbccdd`, and `rgb()` / `rgba()` into 0-255 channels.
 * Alpha is ignored: contrast is only meaningful against an opaque backdrop, and
 * guessing what sits behind a translucent color would be worse than not trying.
 */
function parseRgb(input: ColorInput): Rgb | null {
  if (typeof input !== "string") return input;

  const value = input.trim();
  const rgbMatch = /^rgba?\(([^)]+)\)$/iu.exec(value);

  if (rgbMatch?.[1]) {
    const parts = rgbMatch[1]
      .split(/[\s,/]+/u)
      .filter(Boolean)
      .map((part) => (part.endsWith("%") ? (Number(part.slice(0, -1)) * 255) / 100 : Number(part)));

    const [r, g, b] = parts;
    if (r === undefined || g === undefined || b === undefined) return null;
    if ([r, g, b].some(Number.isNaN)) return null;

    return { r, g, b };
  }

  const hex = value.startsWith("#") ? value.slice(1) : value;
  if (!/^[0-9a-f]+$/iu.test(hex)) return null;

  const expanded =
    hex.length === HEX_SHORTHAND_LENGTH || hex.length === HEX_SHORTHAND_LENGTH + 1
      ? Array.from(hex, (char) => char + char).join("")
      : hex;

  if (expanded.length !== 6 && expanded.length !== 8) return null;

  return {
    r: Number.parseInt(expanded.slice(0, 2), 16),
    g: Number.parseInt(expanded.slice(2, 4), 16),
    b: Number.parseInt(expanded.slice(4, 6), 16),
  };
}

function toLinear(channel: number): number {
  const value = Math.min(1, Math.max(0, channel / 255));

  return value <= 0.040_45 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
}

/**
 * WCAG 2.x relative luminance. Returns 0 for anything unparseable, which biases
 * callers toward light text rather than throwing inside a render.
 */
function getRelativeLuminance(color: ColorInput): number {
  const rgb = parseRgb(color);
  if (!rgb) return 0;

  return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
}

/**
 * WCAG 2.x contrast ratio, from 1 (identical) to 21 (black on white).
 * Order does not matter.
 */
function getContrastRatio(a: ColorInput, b: ColorInput): number {
  const first = getRelativeLuminance(a);
  const second = getRelativeLuminance(b);

  return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
}

/**
 * Picks whichever of the two candidates contrasts better with `background`.
 *
 * Returns the tone rather than a color so the caller can map it onto whatever it
 * actually applies — a design token, a class name, a CSS variable.
 */
function getReadableTextColor(
  background: ColorInput,
  options: ReadableTextColorOptions = {},
): ReadableTone {
  const { light = "#ffffff", dark = "#000000" } = options;

  return getContrastRatio(background, light) >= getContrastRatio(background, dark)
    ? "light"
    : "dark";
}

export {
  getContrastRatio,
  getReadableTextColor,
  getRelativeLuminance,
  parseRgb,
  type ColorInput,
  type ReadableTextColorOptions,
  type ReadableTone,
  type Rgb,
};
```



## Usage

Three functions built on the WCAG 2.x definitions: relative luminance, the contrast ratio between
two colors, and the choice between a light and a dark foreground. No dependencies, no color library.

```ts
import { getContrastRatio, getReadableTextColor } from "@/lib/color-contrast";

getContrastRatio("#6400DC", "#ffffff"); // 8.15
getReadableTextColor("#6400DC"); // "light"
getReadableTextColor("#facc15"); // "dark"
```

## Choosing a foreground

`getReadableTextColor` returns a tone, not a color, so the caller maps it onto whatever it actually
applies — a design token, a class, a CSS variable:

```tsx
const tone = getReadableTextColor(accent, { light: "#fafafa", dark: "#0a0a0a" });

element.style.setProperty("--brand-foreground", tone === "light" ? LIGHT : DARK);
```

Pass `light` and `dark` whenever the real candidates are not pure white and black. Doing so rarely
changes which tone wins — swapping pure white and black for a near-white and near-black moves the tie
point from a luminance of `0.1791` to `0.1810`, not enough to flip any 8-bit grey — but it does make
the ratios themselves correct, which matters as soon as you compare them against an AA or AAA
threshold rather than just against each other.

## Why not a lightness threshold

The tempting shortcut is to read one number — HSL lightness, or OKLCH `L` — and compare it against a
constant. It is close, but it is not the same thing, because the point where white and black tie
depends on hue as well as lightness:

| Background          | Ideal OKLCH `L` crossover |
| ------------------- | ------------------------- |
| Neutral grey        | 0.566                     |
| Saturated yellow    | 0.556                     |
| Saturated red       | 0.592                     |
| Saturated blue      | 0.628                     |

No single threshold sits on all of those, so a fixed constant is guaranteed to pick the worse
foreground for some slice of the color wheel. Comparing the two ratios costs a few lines and is
exact.

If you do reach for a threshold anyway, use OKLCH `L` rather than HSL `L`: OKLCH lightness is
perceptual, so a yellow and a blue that share an `L` genuinely look equally light.

## Parsing

`parseRgb` accepts `#abc`, `#aabbcc`, `#aabbccdd`, and `rgb()` / `rgba()`, returning 0-255 channels
or `null`. Alpha is parsed but ignored — contrast is only meaningful against an opaque backdrop, and
guessing what sits behind a translucent color would be less accurate than not trying. Composite the
color yourself first if it is translucent.

Unparseable input yields a luminance of `0` rather than an exception, so a bad value at runtime
degrades to "assume dark, use light text" instead of breaking a render.

## Functions

| Function                | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `getRelativeLuminance`  | WCAG relative luminance, `0`–`1`.                                         |
| `getContrastRatio`      | WCAG contrast ratio, `1`–`21`. Argument order does not matter.            |
| `getReadableTextColor`  | `"light"` or `"dark"`, whichever contrasts better. Candidates are configurable. |
| `parseRgb`              | Hex or `rgb()` string to `{ r, g, b }` in 0-255, or `null`.               |

For reference, WCAG AA wants `4.5` for body text and `3` for large text or UI components; AAA wants
`7` and `4.5`.


---

URL: https://mwui.vercel.app/utilities/format.md

Locale-aware formatters for dates, ranges, currency, numbers, and durations.

# Format

Locale-aware formatters for dates, ranges, currency, numbers, and durations.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/format.json
```

[Registry JSON](https://mwui.vercel.app/r/format.json)

## Preview

```tsx
import * as React from "react";

import {
  formatCompactNumber,
  formatCurrency,
  formatDate,
  formatDateRange,
  formatDuration,
  formatPercent,
  formatRelativeTime,
  parseDuration,
} from "@/lib/format";

const DAY = 86_400_000;

export function Preview() {
  const now = React.useMemo(() => Date.now(), []);

  const rows = [
    { label: "formatDate", value: formatDate(now) },
    { label: "formatDateRange", value: formatDateRange(now, now + 5 * DAY) },
    { label: "formatRelativeTime", value: formatRelativeTime(now - 3 * DAY) },
    { label: "formatCurrency", value: formatCurrency(1234.5, { currency: "EUR" }) },
    { label: "formatCompactNumber", value: formatCompactNumber(1_234_567) },
    { label: "formatPercent", value: formatPercent(0.4567) },
    { label: "formatDuration", value: formatDuration(8_100_000) },
    { label: "formatDuration · clock", value: formatDuration(25_500_000, { style: "clock" }) },
    { label: 'parseDuration("1h 30m")', value: `${String(parseDuration("1h 30m"))} ms` },
  ];

  return (
    <div className="flex w-full max-w-sm flex-col gap-1.5">
      {rows.map((row) => (
        <div key={row.label} className="flex items-baseline justify-between gap-4 text-sm">
          <span className="font-mono text-xs text-muted-foreground">{row.label}</span>
          <span className="text-right tabular-nums">{row.value}</span>
        </div>
      ))}
    </div>
  );
}
```


## Source

### lib/format.ts

```ts
type DateInput = Date | number | string;

type LocaleOption = {
  locale?: Intl.LocalesArgument;
};

type FormatDateOptions = LocaleOption & Intl.DateTimeFormatOptions;

type FormatNumberOptions = LocaleOption & Intl.NumberFormatOptions;

type FormatCurrencyOptions = FormatNumberOptions & {
  currency?: string;
};

type FormatRelativeTimeOptions = LocaleOption & {
  now?: DateInput;
  numeric?: Intl.RelativeTimeFormatNumeric;
};

type DurationStyle = "short" | "long" | "clock";

type FormatDurationOptions = LocaleOption & {
  style?: DurationStyle;
};

const MS_PER_SECOND = 1000;
const MS_PER_MINUTE = 60 * MS_PER_SECOND;
const MS_PER_HOUR = 60 * MS_PER_MINUTE;
const MS_PER_DAY = 24 * MS_PER_HOUR;

const RELATIVE_UNITS: [unit: Intl.RelativeTimeFormatUnit, milliseconds: number][] = [
  ["year", 365 * MS_PER_DAY],
  ["month", 30 * MS_PER_DAY],
  ["week", 7 * MS_PER_DAY],
  ["day", MS_PER_DAY],
  ["hour", MS_PER_HOUR],
  ["minute", MS_PER_MINUTE],
  ["second", MS_PER_SECOND],
];

const DURATION_UNIT_MILLISECONDS: Record<string, number> = {
  d: MS_PER_DAY,
  day: MS_PER_DAY,
  days: MS_PER_DAY,
  h: MS_PER_HOUR,
  hr: MS_PER_HOUR,
  hrs: MS_PER_HOUR,
  hour: MS_PER_HOUR,
  hours: MS_PER_HOUR,
  m: MS_PER_MINUTE,
  min: MS_PER_MINUTE,
  mins: MS_PER_MINUTE,
  minute: MS_PER_MINUTE,
  minutes: MS_PER_MINUTE,
  s: MS_PER_SECOND,
  sec: MS_PER_SECOND,
  secs: MS_PER_SECOND,
  second: MS_PER_SECOND,
  seconds: MS_PER_SECOND,
};

const DATE_PART_OPTIONS = [
  "dateStyle",
  "timeStyle",
  "weekday",
  "era",
  "year",
  "month",
  "day",
  "dayPeriod",
  "hour",
  "minute",
  "second",
  "fractionalSecondDigits",
  "timeZoneName",
] as const satisfies readonly (keyof Intl.DateTimeFormatOptions)[];

const dateTimeFormatters = new Map<string, Intl.DateTimeFormat>();
const numberFormatters = new Map<string, Intl.NumberFormat>();
const relativeTimeFormatters = new Map<string, Intl.RelativeTimeFormat>();

function getDateTimeFormatter(locale: Intl.LocalesArgument, options: Intl.DateTimeFormatOptions) {
  const key = JSON.stringify([locale, options]);
  let formatter = dateTimeFormatters.get(key);

  if (!formatter) {
    formatter = new Intl.DateTimeFormat(locale, options);
    dateTimeFormatters.set(key, formatter);
  }

  return formatter;
}

function getNumberFormatter(locale: Intl.LocalesArgument, options: Intl.NumberFormatOptions) {
  const key = JSON.stringify([locale, options]);
  let formatter = numberFormatters.get(key);

  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, options);
    numberFormatters.set(key, formatter);
  }

  return formatter;
}

function getRelativeTimeFormatter(
  locale: Intl.LocalesArgument,
  options: Intl.RelativeTimeFormatOptions,
) {
  const key = JSON.stringify([locale, options]);
  let formatter = relativeTimeFormatters.get(key);

  if (!formatter) {
    formatter = new Intl.RelativeTimeFormat(locale, options);
    relativeTimeFormatters.set(key, formatter);
  }

  return formatter;
}

function withDefaultDateStyle(options: Intl.DateTimeFormatOptions): Intl.DateTimeFormatOptions {
  const hasDatePart = DATE_PART_OPTIONS.some((option) => options[option] !== undefined);
  return hasDatePart ? options : { ...options, dateStyle: "medium" };
}

function toDate(value: DateInput): Date {
  return value instanceof Date ? value : new Date(value);
}

function isValidDate(value: Date): boolean {
  return !Number.isNaN(value.getTime());
}

function formatDate(value: DateInput, { locale, ...options }: FormatDateOptions = {}): string {
  const date = toDate(value);
  if (!isValidDate(date)) return "";

  return getDateTimeFormatter(locale, withDefaultDateStyle(options)).format(date);
}

function formatDateRange(
  start: DateInput,
  end: DateInput,
  { locale, ...options }: FormatDateOptions = {},
): string {
  const startDate = toDate(start);
  const endDate = toDate(end);

  if (!isValidDate(startDate) || !isValidDate(endDate)) return "";

  return getDateTimeFormatter(locale, withDefaultDateStyle(options)).formatRange(
    startDate,
    endDate,
  );
}

function formatRelativeTime(
  value: DateInput,
  { locale, now = Date.now(), numeric = "auto" }: FormatRelativeTimeOptions = {},
): string {
  const date = toDate(value);
  if (!isValidDate(date)) return "";

  const formatter = getRelativeTimeFormatter(locale, { numeric });
  const difference = date.getTime() - toDate(now).getTime();
  const magnitude = Math.abs(difference);

  for (const [unit, milliseconds] of RELATIVE_UNITS) {
    if (magnitude >= milliseconds) {
      return formatter.format(Math.round(difference / milliseconds), unit);
    }
  }

  return formatter.format(0, "second");
}

function formatNumber(value: number, { locale, ...options }: FormatNumberOptions = {}): string {
  if (!Number.isFinite(value)) return "";
  return getNumberFormatter(locale, options).format(value);
}

function formatCurrency(
  value: number,
  { locale, currency = "USD", ...options }: FormatCurrencyOptions = {},
): string {
  return formatNumber(value, { locale, style: "currency", currency, ...options });
}

function formatPercent(value: number, options: FormatNumberOptions = {}): string {
  return formatNumber(value, { style: "percent", maximumFractionDigits: 1, ...options });
}

function formatCompactNumber(value: number, options: FormatNumberOptions = {}): string {
  return formatNumber(value, { notation: "compact", maximumFractionDigits: 1, ...options });
}

function formatDuration(
  milliseconds: number,
  { locale, style = "short" }: FormatDurationOptions = {},
): string {
  if (!Number.isFinite(milliseconds)) return "";

  const sign = milliseconds < 0 ? "-" : "";
  const total = Math.round(Math.abs(milliseconds) / MS_PER_SECOND) * MS_PER_SECOND;

  const hours = Math.floor(total / MS_PER_HOUR);
  const minutes = Math.floor((total % MS_PER_HOUR) / MS_PER_MINUTE);
  const seconds = Math.floor((total % MS_PER_MINUTE) / MS_PER_SECOND);

  if (style === "clock") {
    return `${sign}${hours}:${String(minutes).padStart(2, "0")}`;
  }

  const unitDisplay = style === "long" ? "long" : "narrow";
  const parts: string[] = [];

  if (hours > 0) {
    parts.push(formatNumber(hours, { locale, style: "unit", unit: "hour", unitDisplay }));
  }

  if (minutes > 0) {
    parts.push(formatNumber(minutes, { locale, style: "unit", unit: "minute", unitDisplay }));
  }

  if (parts.length === 0 || (seconds > 0 && hours === 0)) {
    parts.push(formatNumber(seconds, { locale, style: "unit", unit: "second", unitDisplay }));
  }

  return `${sign}${parts.join(style === "long" ? ", " : " ")}`;
}

function parseDuration(input: string): number | null {
  const value = input.trim().toLowerCase();
  if (!value) return null;

  const clockMatch = /^(\d+):([0-5]?\d)$/u.exec(value);
  if (clockMatch) {
    return Number(clockMatch[1]) * MS_PER_HOUR + Number(clockMatch[2]) * MS_PER_MINUTE;
  }

  if (/^\d+(?:\.\d+)?$/u.test(value)) {
    return Number(value) * MS_PER_MINUTE;
  }

  const tokens = value.matchAll(/(\d+(?:\.\d+)?)\s*([a-z]+)/gu);
  let total = 0;
  let matched = false;
  let consumed = 0;

  for (const [token, amount, unit] of tokens) {
    const unitMilliseconds = DURATION_UNIT_MILLISECONDS[unit];
    if (unitMilliseconds === undefined) return null;

    total += Number(amount) * unitMilliseconds;
    consumed += token.length;
    matched = true;
  }

  if (!matched) return null;
  if (consumed < value.replace(/\s+/gu, "").length) return null;

  return total;
}

export {
  formatCompactNumber,
  formatCurrency,
  formatDate,
  formatDateRange,
  formatDuration,
  formatNumber,
  formatPercent,
  formatRelativeTime,
  parseDuration,
  type DateInput,
  type DurationStyle,
  type FormatCurrencyOptions,
  type FormatDateOptions,
  type FormatDurationOptions,
  type FormatNumberOptions,
  type FormatRelativeTimeOptions,
};
```



## Usage

A small set of formatters built entirely on the `Intl` APIs — no dependencies, no bundled locale
data, no timezone database to keep current. Every function takes an optional `locale`, and falls
back to the runtime's locale when you omit it.

```ts
import { formatCurrency, formatDate, formatDateRange, formatRelativeTime } from "@/lib/format";

formatDate("2025-03-04"); // "Mar 4, 2025"
formatDateRange("2025-03-04", "2025-03-09"); // "Mar 4 – 9, 2025"
formatRelativeTime(Date.now() - 3 * 86_400_000); // "3 days ago"
formatCurrency(1234.5, { currency: "EUR" }); // "€1,234.50"
```

Constructing an `Intl` formatter is expensive relative to using one, so every formatter is cached
by locale and options. Calling these in a table cell or a render loop is fine.

## Dates

`formatDate` defaults to a medium date style, and forwards any `Intl.DateTimeFormatOptions`:

```ts
formatDate(order.placedAt, { dateStyle: "full" }); // "Tuesday, March 4, 2025"
formatDate(order.placedAt, { month: "short", day: "numeric" }); // "Mar 4"
formatDate(order.placedAt, { timeZone: "UTC" }); // "Mar 4, 2025"
```

Options that only configure the formatter, such as `timeZone`, keep the default style. Options that
select date parts replace it.

`formatDateRange` uses `Intl.DateTimeFormat.formatRange`, which collapses whatever the two dates
share:

```ts
formatDateRange("2025-03-04", "2025-03-09"); // "Mar 4 – 9, 2025"
formatDateRange("2024-12-30", "2025-03-09"); // "Dec 30, 2024 – Mar 9, 2025"
```

`formatRelativeTime` picks the largest unit that fits and reads naturally at the boundaries:

```ts
formatRelativeTime(date); // "yesterday", "in 2 hours", "3 days ago", "now"
formatRelativeTime(date, { numeric: "always" }); // "1 day ago"
formatRelativeTime(date, { now: reportGeneratedAt }); // relative to a fixed point
```

## Numbers

```ts
formatNumber(1234.5678, { maximumFractionDigits: 2 }); // "1,234.57"
formatCurrency(1234.5, { currency: "EUR" }); // "€1,234.50"
formatPercent(0.4567); // "45.7%"
formatCompactNumber(1_234_567); // "1.2M"
```

`formatCurrency` defaults to `USD`. Wrap it once in your app if you have a single currency:

```ts
export const money = (value: number) => formatCurrency(value, { currency: "EUR", locale: "pt-PT" });
```

## Durations

Durations are milliseconds in, so they compose with plain date arithmetic.

```ts
formatDuration(8_100_000); // "2h 15m"
formatDuration(8_100_000, { style: "long" }); // "2 hours, 15 minutes"
formatDuration(25_500_000, { style: "clock" }); // "7:05"
```

`clock` is the timesheet format: hours are never rolled into days, so a 20-hour total reads `20:00`
rather than something a reader has to convert. `parseDuration` reads the formats people actually
type and returns milliseconds, or `null` when the input is not a duration:

```ts
parseDuration("1h 30m"); // 5400000
parseDuration("1.5h"); // 5400000
parseDuration("1:30"); // 5400000
parseDuration("90"); // 5400000 — a bare number is minutes
parseDuration("tomorrow"); // null
```

Anything it cannot fully account for returns `null` rather than a partial reading, so
`parseDuration("1h bogus")` fails instead of silently meaning one hour.

## Reference

| Function              | Takes                          | Returns                        |
| --------------------- | ------------------------------ | ------------------------------ |
| `formatDate`          | `Date \| number \| string`     | Formatted date                 |
| `formatDateRange`     | Two dates                      | Collapsed range                |
| `formatRelativeTime`  | A date, optional `now`         | `"3 days ago"`                 |
| `formatNumber`        | `number`                       | Formatted number               |
| `formatCurrency`      | `number`, `currency`           | Formatted money                |
| `formatPercent`       | `number` where `1` is 100%     | `"45.7%"`                      |
| `formatCompactNumber` | `number`                       | `"1.2M"`                       |
| `formatDuration`      | milliseconds                   | `"2h 15m"`, `"7:05"`           |
| `parseDuration`       | `string`                       | milliseconds, or `null`        |

Invalid dates and non-finite numbers format to an empty string rather than `"Invalid Date"` or
`"NaN"`, so a missing field renders as a blank cell.


---

URL: https://mwui.vercel.app/utilities/use-controllable-state.md

A hook that makes any component work controlled or uncontrolled from one state API.

# useControllableState

A hook that makes any component work controlled or uncontrolled from one state API.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-controllable-state.json
```

[Registry JSON](https://mwui.vercel.app/r/use-controllable-state.json)

## Preview

```tsx
import * as React from "react";

import { Button } from "@/components/ui/button";

import { useControllableState } from "@/hooks/use-controllable-state";

function Stepper({
  value,
  defaultValue = 0,
  onValueChange,
}: {
  value?: number;
  defaultValue?: number;
  onValueChange?: (value: number) => void;
}) {
  const [count, setCount] = useControllableState({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  return (
    <div className="flex items-center gap-2">
      <Button size="icon-xs" variant="outline" onClick={() => setCount((previous) => previous - 1)}>
        -
      </Button>
      <span className="w-8 text-center text-sm tabular-nums">{count}</span>
      <Button size="icon-xs" variant="outline" onClick={() => setCount((previous) => previous + 1)}>
        +
      </Button>
    </div>
  );
}

export function Preview() {
  const [controlled, setControlled] = React.useState(5);

  return (
    <div className="flex flex-col gap-6 text-sm">
      <div className="flex flex-col gap-2">
        <p className="font-medium">Uncontrolled</p>
        <Stepper defaultValue={0} />
        <p className="text-xs text-muted-foreground">Owns its state.</p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Controlled</p>
        <Stepper value={controlled} onValueChange={setControlled} />
        <p className="text-xs text-muted-foreground">
          Parent state: <span className="font-mono">{controlled}</span>
        </p>
      </div>

      <div className="flex flex-col gap-2">
        <p className="font-medium">Controlled and frozen</p>
        <Stepper value={42} />
        <p className="text-xs text-muted-foreground">
          No `onValueChange`, so the value never moves.
        </p>
      </div>
    </div>
  );
}
```


## Source

### hooks/use-controllable-state.ts

```ts
"use client";

import * as React from "react";

type ControllableStateUpdater<T> = (previous: T) => T;

type UseControllableStateOptions<T> = {
  value?: T | undefined;
  defaultValue: T | (() => T);
  onChange?: (value: T) => void;
  isEqual?: (a: T, b: T) => boolean;
};

function isControllableStateUpdater<T>(
  next: T | ControllableStateUpdater<T>,
): next is ControllableStateUpdater<T> {
  return typeof next === "function";
}

function useControllableState<T>({
  value,
  defaultValue,
  onChange,
  isEqual = Object.is,
}: UseControllableStateOptions<T>): [T, (next: T | ControllableStateUpdater<T>) => void] {
  const [uncontrolled, setUncontrolled] = React.useState(defaultValue);

  const isControlled = value !== undefined;
  const resolved = isControlled ? value : uncontrolled;

  const resolvedRef = React.useRef(resolved);
  const onChangeRef = React.useRef(onChange);
  const isEqualRef = React.useRef(isEqual);

  React.useEffect(() => {
    resolvedRef.current = resolved;
    onChangeRef.current = onChange;
    isEqualRef.current = isEqual;
  });

  const setValue = React.useCallback(
    (next: T | ControllableStateUpdater<T>) => {
      const previous = resolvedRef.current;
      const nextValue = isControllableStateUpdater(next) ? next(previous) : next;

      if (isEqualRef.current(nextValue, previous)) return;

      resolvedRef.current = nextValue;
      if (!isControlled) setUncontrolled(nextValue);
      onChangeRef.current?.(nextValue);
    },
    [isControlled],
  );

  return [resolved, setValue];
}

export { useControllableState, type ControllableStateUpdater, type UseControllableStateOptions };
```



## Usage

Every reusable component eventually needs to work both ways: controlled by a parent through
`value` / `onValueChange`, and uncontrolled through `defaultValue`. This hook collapses both into a
single `useState`-shaped API, so the component body never branches on which mode it is in.

```tsx
import { useControllableState } from "@/hooks/use-controllable-state";

function Rating({ value, defaultValue = 0, onValueChange }: RatingProps) {
  const [rating, setRating] = useControllableState({
    value,
    defaultValue,
    onChange: onValueChange,
  });

  return <button onClick={() => setRating((previous) => previous + 1)}>{rating}</button>;
}
```

`<Rating defaultValue={3} />` manages its own state. `<Rating value={rating} onValueChange={setRating} />`
defers to the parent. The component itself does not know the difference.

## Behavior

- The setter accepts a value or an updater function, exactly like `useState`.
- `onChange` fires only when the value actually changes, compared with `Object.is` by default.
- In controlled mode the hook never writes to internal state — if the parent ignores `onChange`,
  the value does not move. That is what makes a controlled component genuinely controlled.
- The setter identity is stable, so it is safe in dependency arrays and in memoized children.

## Options

| Option         | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `value`        | The controlled value. Passing `undefined` selects uncontrolled mode.     |
| `defaultValue` | Initial value when uncontrolled. Accepts a lazy initializer.             |
| `onChange`     | Called with the next value whenever it changes, in either mode.          |
| `isEqual`      | Custom equality used to decide whether a change happened.                |

Pass `isEqual` when the value is a structure that is rebuilt on every render:

```tsx
const [range, setRange] = useControllableState({
  value,
  defaultValue: null,
  onChange: onValueChange,
  isEqual: (a, b) => a?.start === b?.start && a?.end === b?.end,
});
```


---

URL: https://mwui.vercel.app/utilities/use-copy-to-clipboard.md

A small hook that copies text and tracks the latest copy result.

# useCopyToClipboard

A small hook that copies text and tracks the latest copy result.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-copy-to-clipboard.json
```

[Registry JSON](https://mwui.vercel.app/r/use-copy-to-clipboard.json)

## Preview

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

import { useCopyToClipboard } from "@/hooks/use-copy-to-clipboard";

export function Preview() {
  const copyState = useCopyToClipboard();
  const copyValue = "npx shadcn@latest add https://example.com/r/example-card.json";

  return (
    <div className="flex flex-col items-center gap-3 text-center">
      <Button onClick={() => void copyState.copy(copyValue)}>Copy example command</Button>
      <p className="text-sm text-muted-foreground">
        {copyState.status === "copied" ? "Copied to clipboard." : "Ready to copy."}
      </p>
    </div>
  );
}
```


## Source

### hooks/use-copy-to-clipboard.ts

```ts
"use client";

import * as React from "react";

type CopyState =
  | {
      status: "idle";
      value: null;
      error: null;
    }
  | {
      status: "copied";
      value: string;
      error: null;
    }
  | {
      status: "error";
      value: null;
      error: Error;
    };

function useCopyToClipboard() {
  const [state, setState] = React.useState<CopyState>({
    status: "idle",
    value: null,
    error: null,
  });

  const copy = React.useCallback(async (value: string) => {
    try {
      await navigator.clipboard.writeText(value);
      setState({ status: "copied", value, error: null });
      return true;
    } catch (error) {
      const copyError = error instanceof Error ? error : new Error("Copy failed.");

      setState({ status: "error", value: null, error: copyError });
      return false;
    }
  }, []);

  const reset = React.useCallback(() => {
    setState({ status: "idle", value: null, error: null });
  }, []);

  return { ...state, copy, reset };
}

export { useCopyToClipboard, type CopyState };
```



## Usage

Call `copy` with the text you want to place on the clipboard. The hook exposes the latest copy
status so your UI can respond after the operation completes.

```tsx
import { useCopyToClipboard } from "@/hooks/use-copy-to-clipboard";

export function CopyButton() {
  const copyState = useCopyToClipboard();

  return (
    <button onClick={() => void copyState.copy("Copied from my app")}>
      {copyState.status === "copied" ? "Copied" : "Copy"}
    </button>
  );
}
```


---

URL: https://mwui.vercel.app/utilities/use-debounced-value.md

A hook that defers a rapidly changing value until it settles.

# useDebouncedValue

A hook that defers a rapidly changing value until it settles.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-debounced-value.json
```

[Registry JSON](https://mwui.vercel.app/r/use-debounced-value.json)

## Preview

```tsx
import * as React from "react";

import { Input } from "@/components/ui/input";

import { useDebouncedValue } from "@/hooks/use-debounced-value";

export function Preview() {
  const [query, setQuery] = React.useState("");
  const debouncedQuery = useDebouncedValue(query, 500);
  const isPending = query !== debouncedQuery;

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <Input
        value={query}
        placeholder="Type here…"
        aria-label="Search"
        onChange={(event) => setQuery(event.target.value)}
      />

      <div className="flex flex-col gap-1 text-sm">
        <p className="text-muted-foreground">
          Live: <span className="font-mono text-foreground">{query || "—"}</span>
        </p>
        <p className="text-muted-foreground">
          Debounced: <span className="font-mono text-foreground">{debouncedQuery || "—"}</span>
        </p>
        <p className="text-xs text-muted-foreground">
          {isPending ? "Waiting for input to settle…" : "Settled."}
        </p>
      </div>
    </div>
  );
}
```


## Source

### hooks/use-debounced-value.ts

```ts
"use client";

import * as React from "react";

function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = React.useState(value);

  React.useEffect(() => {
    if (delay <= 0) {
      setDebounced(value);
      return undefined;
    }

    const timeout = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timeout);
  }, [value, delay]);

  return debounced;
}

export { useDebouncedValue };
```



## Usage

Returns a copy of the value that only updates once it has stopped changing for `delay`
milliseconds. Use it to keep an input responsive while throttling whatever the input drives —
a search request, an expensive filter, a URL update.

```tsx
import { useDebouncedValue } from "@/hooks/use-debounced-value";

function Search() {
  const [query, setQuery] = React.useState("");
  const debouncedQuery = useDebouncedValue(query, 300);

  React.useEffect(() => {
    void search(debouncedQuery);
  }, [debouncedQuery]);

  return <input value={query} onChange={(event) => setQuery(event.target.value)} />;
}
```

The input stays bound to `query`, so typing never feels laggy. Only `debouncedQuery` is throttled.

## Knowing when it is pending

The hook deliberately returns just the value. Compare it against the source to derive the
pending state, rather than tracking a second piece of state:

```tsx
const isPending = query !== debouncedQuery;
```

## Notes

- The timer resets on every change and is cleared on unmount, so a value that never settles never
  fires.
- A `delay` of `0` or less updates synchronously on the next effect, which is useful for turning
  debouncing off behind a flag.
- Works with any value type. Non-primitive values are compared by identity, so memoize objects
  before passing them in.


---

URL: https://mwui.vercel.app/utilities/use-event-listener.md

A hook that attaches a typed event listener with automatic cleanup.

# useEventListener

A hook that attaches a typed event listener with automatic cleanup.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-event-listener.json
```

[Registry JSON](https://mwui.vercel.app/r/use-event-listener.json)

## Preview

```tsx
import * as React from "react";

import { useEventListener } from "@/hooks/use-event-listener";

export function Preview() {
  const cardRef = React.useRef<HTMLDivElement>(null);
  const [lastKey, setLastKey] = React.useState("—");
  const [point, setPoint] = React.useState<{ x: number; y: number } | null>(null);

  useEventListener("keydown", (event) => {
    setLastKey(event.key === " " ? "Space" : event.key);
  });

  useEventListener(
    "pointermove",
    (event) => {
      const bounds = cardRef.current?.getBoundingClientRect();
      if (!bounds) return;

      setPoint({
        x: Math.round(event.clientX - bounds.left),
        y: Math.round(event.clientY - bounds.top),
      });
    },
    cardRef,
  );

  useEventListener("pointerleave", () => setPoint(null), cardRef);

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div
        ref={cardRef}
        className="flex h-28 items-center justify-center rounded-lg border border-dashed border-border bg-muted/40 text-muted-foreground"
      >
        {point ? (
          <span className="font-mono text-xs">
            x: {point.x} · y: {point.y}
          </span>
        ) : (
          <span className="text-xs">Move the pointer in here</span>
        )}
      </div>

      <p className="text-xs text-muted-foreground">
        Last key on <span className="font-mono">window</span>:{" "}
        <span className="font-mono text-foreground">{lastKey}</span>
      </p>
    </div>
  );
}
```


## Source

### hooks/use-event-listener.ts

```ts
"use client";

import * as React from "react";

type UseEventListenerOptions = {
  capture?: boolean;
  passive?: boolean;
  once?: boolean;
  enabled?: boolean;
};

type EventTargetLike<T> = T | React.RefObject<T | null> | null | undefined;

function useEventListener<K extends keyof WindowEventMap>(
  type: K,
  listener: (event: WindowEventMap[K]) => void,
  target?: undefined,
  options?: UseEventListenerOptions,
): void;
function useEventListener<K extends keyof DocumentEventMap>(
  type: K,
  listener: (event: DocumentEventMap[K]) => void,
  target: EventTargetLike<Document>,
  options?: UseEventListenerOptions,
): void;
function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(
  type: K,
  listener: (event: HTMLElementEventMap[K]) => void,
  target: EventTargetLike<T>,
  options?: UseEventListenerOptions,
): void;
function useEventListener(
  type: string,
  listener: (event: Event) => void,
  target?: EventTargetLike<EventTarget>,
  options: UseEventListenerOptions = {},
): void {
  const { capture, passive, once, enabled = true } = options;
  const listenerRef = React.useRef(listener);

  React.useEffect(() => {
    listenerRef.current = listener;
  });

  React.useEffect(() => {
    if (!enabled) return undefined;

    const element = resolveEventTarget(target);
    if (!element) return undefined;

    const handler = (event: Event) => listenerRef.current(event);

    element.addEventListener(type, handler, { capture, passive, once });
    return () => element.removeEventListener(type, handler, { capture });
  }, [type, target, capture, passive, once, enabled]);
}

function resolveEventTarget(target: EventTargetLike<EventTarget>): EventTarget | null {
  if (target === undefined) return typeof window === "undefined" ? null : window;
  if (target === null) return null;
  if ("current" in target) return target.current;
  return target;
}

export { useEventListener, type UseEventListenerOptions };
```



## Usage

`addEventListener` in an effect is four lines of boilerplate that go wrong in two ways: the cleanup
gets forgotten, or the handler is added to the dependency array and the listener is torn down and
re-attached on every render. This hook fixes both, and keeps the event fully typed.

```tsx
import { useEventListener } from "@/hooks/use-event-listener";

function ShortcutBar() {
  useEventListener("keydown", (event) => {
    if (event.key === "Escape") close();
  });

  return null;
}
```

With no target, the listener goes on `window` — `event` is narrowed from `WindowEventMap`, so
`event.key` type-checks and `event.clientX` does not.

## Targets

Pass a ref or an element as the third argument. The ref does not need to be populated on the first
render; the listener is attached in an effect.

```tsx
const cardRef = React.useRef<HTMLDivElement>(null);

useEventListener("pointermove", (event) => setPoint({ x: event.clientX, y: event.clientY }), cardRef);
useEventListener("visibilitychange", () => setActive(!document.hidden), document);
```

The event type follows the target: `HTMLElementEventMap` for elements, `DocumentEventMap` for
`document`, `WindowEventMap` for the default.

## Options

| Option    | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| `capture` | Listen during the capture phase.                                                   |
| `passive` | Promise never to call `preventDefault` — required for smooth `touchmove`/`wheel`.  |
| `once`    | Remove the listener after it fires once.                                           |
| `enabled` | Detach without unmounting. Flip it instead of conditionally calling the hook.      |

## Behavior

- The handler is read from a ref, so it always sees fresh props and state without re-subscribing.
  You never need to memoize what you pass in.
- Nothing touches the DOM during render, so the hook is safe in server-rendered trees.
- `target` resolution happens inside the effect, which is why `window` and `document` defaults do
  not break SSR.


---

URL: https://mwui.vercel.app/utilities/use-file-upload.md

A hook that manages file selection, validation, previews, and upload progress.

# useFileUpload

A hook that manages file selection, validation, previews, and upload progress.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-file-upload.json
```

[Registry JSON](https://mwui.vercel.app/r/use-file-upload.json)

## Preview

```tsx
import { IconUpload, IconX } from "@tabler/icons-react";

import { Button } from "@/components/ui/button";

import { formatBytes, useFileUpload } from "@/hooks/use-file-upload";

export function Preview() {
  const upload = useFileUpload({
    accept: "image/*,.pdf",
    maxSize: 2 * 1024 * 1024,
    maxFiles: 3,
    autoUpload: true,
    onUpload: (_item, { onProgress, signal }) =>
      new Promise<void>((resolve) => {
        let step = 0;

        const timer = setInterval(() => {
          step += 1;
          onProgress(step / 10);

          if (step >= 10 || signal.aborted) {
            clearInterval(timer);
            resolve();
          }
        }, 120);
      }),
  });

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div
        {...upload.getDropzoneProps()}
        data-dragging={upload.isDragging}
        className="flex flex-col items-center gap-2 rounded-lg border border-dashed border-border p-6 text-center transition-colors data-[dragging=true]:border-ring data-[dragging=true]:bg-muted/50"
      >
        <IconUpload className="size-5 text-muted-foreground" />
        <p className="text-xs text-muted-foreground">Drop images or PDFs here, up to 2 MB</p>
        <input {...upload.getInputProps()} />
        <Button size="xs" variant="outline" onClick={upload.openFileDialog}>
          Choose files
        </Button>
      </div>

      {upload.files.map((item) => (
        <div key={item.id} className="flex items-center gap-2 rounded-lg border border-border p-2">
          {item.previewUrl ? (
            <img src={item.previewUrl} alt="" className="size-8 rounded object-cover" />
          ) : (
            <div className="size-8 rounded bg-muted" />
          )}

          <div className="min-w-0 flex-1">
            <p className="truncate text-xs">{item.file.name}</p>
            <div className="mt-1 h-1 overflow-hidden rounded-full bg-muted">
              <div
                className="h-full bg-primary transition-[width] duration-200"
                style={{ width: `${item.progress * 100}%` }}
              />
            </div>
          </div>

          <span className="text-[0.7rem] text-muted-foreground">{formatBytes(item.file.size)}</span>

          <Button
            size="icon-xs"
            variant="ghost"
            aria-label={`Remove ${item.file.name}`}
            onClick={() => upload.removeFile(item.id)}
          >
            <IconX />
          </Button>
        </div>
      ))}

      {upload.rejections.map((rejection) => (
        <p key={`${rejection.file.name}-${rejection.reason}`} className="text-xs text-destructive">
          {rejection.message}
        </p>
      ))}
    </div>
  );
}
```


## Source

### hooks/use-file-upload.ts

```ts
"use client";

import * as React from "react";

type UploadStatus = "pending" | "uploading" | "success" | "error";

type UploadFile = {
  id: string;
  file: File;
  status: UploadStatus;
  /** Upload progress from 0 to 1. */
  progress: number;
  error: string | null;
  /** Object URL, present only for images. Revoked when the file is removed. */
  previewUrl: string | null;
};

type UploadRejection = {
  file: File;
  reason: "type" | "size" | "count" | "duplicate";
  message: string;
};

type UploadHandlerContext = {
  onProgress: (progress: number) => void;
  signal: AbortSignal;
};

type UseFileUploadOptions = {
  /** Same syntax as the `accept` attribute: `"image/*,.pdf"`. */
  accept?: string;
  /** Maximum size per file, in bytes. */
  maxSize?: number;
  maxFiles?: number;
  multiple?: boolean;
  disabled?: boolean;
  /** Upload transport. Resolve to finish, throw to fail. */
  onUpload?: (file: UploadFile, context: UploadHandlerContext) => Promise<void>;
  /** Start uploading as soon as files are accepted. Requires `onUpload`. */
  autoUpload?: boolean;
  onFilesChange?: (files: UploadFile[]) => void;
  onRejected?: (rejections: UploadRejection[]) => void;
};

function useFileUpload(options: UseFileUploadOptions = {}) {
  const {
    accept,
    maxSize,
    maxFiles,
    multiple = true,
    disabled = false,
    onUpload,
    autoUpload = false,
    onFilesChange,
    onRejected,
  } = options;

  const [files, setFiles] = React.useState<UploadFile[]>([]);
  const [rejections, setRejections] = React.useState<UploadRejection[]>([]);
  const [isDragging, setIsDragging] = React.useState(false);

  const inputRef = React.useRef<HTMLInputElement>(null);
  const dragDepth = React.useRef(0);
  const controllers = React.useRef(new Map<string, AbortController>());
  const filesRef = React.useRef(files);

  const callbacks = React.useRef({ onUpload, onFilesChange, onRejected });

  React.useEffect(() => {
    callbacks.current = { onUpload, onFilesChange, onRejected };
  });

  React.useEffect(() => {
    filesRef.current = files;
  }, [files]);

  React.useEffect(() => {
    const pending = controllers.current;

    return () => {
      for (const controller of pending.values()) controller.abort();
      for (const item of filesRef.current) {
        if (item.previewUrl) URL.revokeObjectURL(item.previewUrl);
      }
    };
  }, []);

  const commit = React.useCallback((next: UploadFile[]) => {
    filesRef.current = next;
    setFiles(next);
    callbacks.current.onFilesChange?.(next);
  }, []);

  const upload = React.useCallback(
    async (item: UploadFile) => {
      const handler = callbacks.current.onUpload;
      if (!handler) return;

      const controller = new AbortController();
      controllers.current.set(item.id, controller);

      const patch = (changes: Partial<UploadFile>) => {
        commit(
          filesRef.current.map((current) =>
            current.id === item.id ? { ...current, ...changes } : current,
          ),
        );
      };

      patch({ status: "uploading", progress: 0, error: null });

      try {
        await handler(item, {
          signal: controller.signal,
          onProgress: (progress) => patch({ progress: clamp(progress) }),
        });

        if (!controller.signal.aborted) patch({ status: "success", progress: 1 });
      } catch (error) {
        if (controller.signal.aborted) return;
        patch({ status: "error", error: toMessage(error) });
      } finally {
        controllers.current.delete(item.id);
      }
    },
    [commit],
  );

  const addFiles = React.useCallback(
    (incoming: Iterable<File>) => {
      if (disabled) return;

      const candidates = Array.from(incoming);
      const accepted: UploadFile[] = [];
      const refused: UploadRejection[] = [];

      let total = multiple ? filesRef.current.length : 0;

      for (const file of candidates) {
        const rejection = validateFile(file, {
          accept,
          maxSize,
          maxFiles,
          total,
          existing: multiple ? filesRef.current : [],
        });

        if (rejection) {
          refused.push(rejection);
          continue;
        }

        accepted.push(createUploadFile(file));
        total += 1;
      }

      if (!multiple) {
        for (const item of filesRef.current) {
          if (item.previewUrl) URL.revokeObjectURL(item.previewUrl);
        }
      }

      const next = multiple ? [...filesRef.current, ...accepted] : accepted.slice(0, 1);

      setRejections(refused);
      if (refused.length > 0) callbacks.current.onRejected?.(refused);
      if (accepted.length > 0 || !multiple) commit(next);

      if (autoUpload && callbacks.current.onUpload) {
        for (const item of next.filter((candidate) => candidate.status === "pending")) {
          void upload(item);
        }
      }
    },
    [accept, autoUpload, commit, disabled, maxFiles, maxSize, multiple, upload],
  );

  const removeFile = React.useCallback(
    (id: string) => {
      controllers.current.get(id)?.abort();
      controllers.current.delete(id);

      const item = filesRef.current.find((candidate) => candidate.id === id);
      if (item?.previewUrl) URL.revokeObjectURL(item.previewUrl);

      commit(filesRef.current.filter((candidate) => candidate.id !== id));
    },
    [commit],
  );

  const clearFiles = React.useCallback(() => {
    for (const controller of controllers.current.values()) controller.abort();
    controllers.current.clear();

    for (const item of filesRef.current) {
      if (item.previewUrl) URL.revokeObjectURL(item.previewUrl);
    }

    setRejections([]);
    commit([]);
  }, [commit]);

  const uploadAll = React.useCallback(async () => {
    const pending = filesRef.current.filter(
      (item) => item.status === "pending" || item.status === "error",
    );

    await Promise.all(pending.map((item) => upload(item)));
  }, [upload]);

  const retryFile = React.useCallback(
    (id: string) => {
      const item = filesRef.current.find((candidate) => candidate.id === id);
      if (item) void upload(item);
    },
    [upload],
  );

  const openFileDialog = React.useCallback(() => {
    if (!disabled) inputRef.current?.click();
  }, [disabled]);

  const getInputProps = React.useCallback(
    (): React.ComponentProps<"input"> => ({
      ref: inputRef,
      type: "file",
      accept,
      multiple,
      disabled,
      className: "sr-only",
      tabIndex: -1,
      onChange: (event) => {
        if (event.target.files) addFiles(event.target.files);
        event.target.value = "";
      },
    }),
    [accept, addFiles, disabled, multiple],
  );

  const getDropzoneProps = React.useCallback(
    (): React.ComponentProps<"div"> => ({
      onDragEnter: (event) => {
        event.preventDefault();
        if (disabled) return;
        dragDepth.current += 1;
        setIsDragging(true);
      },
      onDragOver: (event) => {
        event.preventDefault();
        if (!disabled) event.dataTransfer.dropEffect = "copy";
      },
      onDragLeave: (event) => {
        event.preventDefault();
        dragDepth.current = Math.max(0, dragDepth.current - 1);
        if (dragDepth.current === 0) setIsDragging(false);
      },
      onDrop: (event) => {
        event.preventDefault();
        dragDepth.current = 0;
        setIsDragging(false);
        if (!disabled && event.dataTransfer.files.length > 0) addFiles(event.dataTransfer.files);
      },
    }),
    [addFiles, disabled],
  );

  const isUploading = files.some((item) => item.status === "uploading");

  return {
    files,
    rejections,
    isDragging,
    isUploading,
    inputRef,
    addFiles,
    removeFile,
    clearFiles,
    retryFile,
    uploadAll,
    openFileDialog,
    getInputProps,
    getDropzoneProps,
  };
}

function createUploadFile(file: File): UploadFile {
  return {
    id: `${file.name}-${file.size}-${file.lastModified}-${Math.random().toString(36).slice(2, 8)}`,
    file,
    status: "pending",
    progress: 0,
    error: null,
    previewUrl: file.type.startsWith("image/") ? URL.createObjectURL(file) : null,
  };
}

function validateFile(
  file: File,
  context: {
    accept?: string;
    maxSize?: number;
    maxFiles?: number;
    total: number;
    existing: UploadFile[];
  },
): UploadRejection | null {
  const { accept, maxSize, maxFiles, total, existing } = context;

  if (maxFiles !== undefined && total >= maxFiles) {
    return { file, reason: "count", message: `Only ${maxFiles} files can be uploaded.` };
  }

  if (accept && !matchesAccept(file, accept)) {
    return { file, reason: "type", message: `${file.name} is not an accepted file type.` };
  }

  if (maxSize !== undefined && file.size > maxSize) {
    return {
      file,
      reason: "size",
      message: `${file.name} is larger than ${formatBytes(maxSize)}.`,
    };
  }

  const duplicate = existing.some(
    (item) =>
      item.file.name === file.name &&
      item.file.size === file.size &&
      item.file.lastModified === file.lastModified,
  );

  if (duplicate) {
    return { file, reason: "duplicate", message: `${file.name} was already added.` };
  }

  return null;
}

function matchesAccept(file: File, accept: string): boolean {
  const patterns = accept
    .split(",")
    .map((pattern) => pattern.trim().toLowerCase())
    .filter(Boolean);

  if (patterns.length === 0) return true;

  const type = file.type.toLowerCase();
  const name = file.name.toLowerCase();

  return patterns.some((pattern) => {
    if (pattern.startsWith(".")) return name.endsWith(pattern);
    if (pattern.endsWith("/*")) return type.startsWith(pattern.slice(0, -1));
    return type === pattern;
  });
}

function formatBytes(bytes: number): string {
  const units = ["B", "KB", "MB", "GB"];
  let value = bytes;
  let unit = 0;

  while (value >= 1024 && unit < units.length - 1) {
    value /= 1024;
    unit += 1;
  }

  return `${value % 1 === 0 ? value : value.toFixed(1)} ${units[unit]}`;
}

function clamp(value: number): number {
  return Math.min(1, Math.max(0, value));
}

function toMessage(error: unknown): string {
  if (error instanceof Error) return error.message;
  return "Upload failed.";
}

export {
  useFileUpload,
  formatBytes,
  type UploadFile,
  type UploadRejection,
  type UploadStatus,
  type UseFileUploadOptions,
};
```



## Usage

Everything a file input needs that the platform does not give you: drag state, accept and size
validation with usable rejection messages, image previews that get revoked, per-file progress, and
retry. It renders nothing, so the same logic backs a dropzone, an avatar picker, or a paste handler.

```tsx
import { useFileUpload } from "@/hooks/use-file-upload";

function Uploader() {
  const upload = useFileUpload({
    accept: "image/*",
    maxSize: 5 * 1024 * 1024,
    maxFiles: 4,
  });

  return (
    <div {...upload.getDropzoneProps()} data-dragging={upload.isDragging}>
      <input {...upload.getInputProps()} />
      <button onClick={upload.openFileDialog}>Choose files</button>

      {upload.files.map((item) => (
        <p key={item.id}>{item.file.name}</p>
      ))}
    </div>
  );
}
```

## Uploading

Pass `onUpload` and the hook drives the transport, tracking status and progress per file. Resolve to
mark it uploaded; throw and the message lands on `item.error` with a retry available.

```tsx
const upload = useFileUpload({
  autoUpload: true,
  onUpload: async (item, { onProgress, signal }) => {
    const body = new FormData();
    body.append("file", item.file);

    await fetch("/api/upload", { method: "POST", body, signal });
    onProgress(1);
  },
});
```

`signal` aborts when the file is removed or the component unmounts, so a cancelled upload does not
keep streaming. For real byte-level progress use `XMLHttpRequest` — `fetch` cannot report upload
progress — and call `onProgress` with a fraction between `0` and `1`.

## Rejections

Files that fail validation never enter `files`. They arrive as `rejections`, each with a reason
(`"type"`, `"size"`, `"count"`, `"duplicate"`) and a message you can render as-is.

```tsx
{upload.rejections.map((rejection) => (
  <p key={rejection.file.name} className="text-destructive">{rejection.message}</p>
))}
```

Duplicates are matched on name, size, and last-modified time — the closest thing to a file identity
the browser offers.

## Options

| Option         | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| `accept`       | Same syntax as the `accept` attribute: `"image/*,.pdf"`. Enforced on drop too, which the attribute alone does not do. |
| `maxSize`      | Per-file limit in bytes.                                                    |
| `maxFiles`     | Maximum number of accepted files.                                           |
| `multiple`     | When `false`, a new selection replaces the current file.                    |
| `disabled`     | Ignore selection and drops.                                                 |
| `onUpload`     | Upload transport. Receives `onProgress` and an `AbortSignal`.               |
| `autoUpload`   | Upload as soon as files are accepted.                                       |
| `onFilesChange`| Called with the full list after every change.                               |
| `onRejected`   | Called with the rejections from a single selection.                         |

## Returns

| Value                              | Description                                                     |
| ---------------------------------- | --------------------------------------------------------------- |
| `files`                            | `UploadFile[]` — `id`, `file`, `status`, `progress`, `error`, `previewUrl`. |
| `rejections`                       | Rejections from the most recent selection.                       |
| `isDragging` / `isUploading`       | Derived flags for styling.                                       |
| `addFiles` / `removeFile` / `clearFiles` | Imperative list control — `addFiles` also accepts a paste or drop `FileList`. |
| `uploadAll` / `retryFile`          | Trigger uploads when `autoUpload` is off.                        |
| `openFileDialog` / `inputRef`      | Open the native picker from your own trigger.                    |
| `getInputProps` / `getDropzoneProps` | Prop getters for the hidden input and the drop target.         |

`previewUrl` is an object URL created only for `image/*` files and revoked when the file is removed
or the component unmounts, so previews do not leak.

The `formatBytes` helper is exported alongside the hook for rendering file sizes.


---

URL: https://mwui.vercel.app/utilities/use-hotkeys.md

A hook that binds keyboard shortcuts with modifier and sequence support.

# useHotkeys

A hook that binds keyboard shortcuts with modifier and sequence support.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-hotkeys.json
```

[Registry JSON](https://mwui.vercel.app/r/use-hotkeys.json)

## Preview

```tsx
import * as React from "react";

import { useHotkeys } from "@/hooks/use-hotkeys";

function Kbd({ children }: { children: React.ReactNode }) {
  return (
    <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-[0.7rem]">
      {children}
    </kbd>
  );
}

export function Preview() {
  const [log, setLog] = React.useState<{ id: number; label: string }[]>([]);

  const push = React.useCallback((label: string) => {
    setLog((previous) => [{ id: Date.now(), label }, ...previous].slice(0, 4));
  }, []);

  useHotkeys("mod+k", () => push("mod+k — open command menu"));
  useHotkeys("g i", () => push("g i — go to inbox"));
  useHotkeys("?", () => push("? — show shortcuts"));

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
        Try <Kbd>⌘/Ctrl</Kbd>
        <Kbd>K</Kbd>, then <Kbd>G</Kbd> <Kbd>I</Kbd>, then <Kbd>?</Kbd>
      </div>

      <div className="min-h-24 rounded-lg border border-border p-2">
        {log.length === 0 ? (
          <p className="p-1 text-xs text-muted-foreground">No shortcut fired yet.</p>
        ) : (
          <ul className="flex flex-col gap-1">
            {log.map((entry, index) => (
              <li
                key={entry.id}
                className="rounded px-1 py-0.5 font-mono text-xs data-[latest=true]:bg-muted"
                data-latest={index === 0}
              >
                {entry.label}
              </li>
            ))}
          </ul>
        )}
      </div>
    </div>
  );
}
```


## Source

### hooks/use-hotkeys.ts

```ts
"use client";

import * as React from "react";

type HotkeyStep = {
  key: string;
  ctrl: boolean;
  meta: boolean;
  alt: boolean;
  shift: boolean;
};

type UseHotkeysOptions = {
  enabled?: boolean;
  /** Element the listener is attached to. Defaults to `document`. */
  target?: HTMLElement | Document | null;
  /** Fire while an input, textarea, select, or contenteditable has focus. */
  enableOnFormElements?: boolean;
  preventDefault?: boolean;
  /** Milliseconds allowed between the steps of a sequence such as `"g i"`. */
  sequenceTimeout?: number;
};

const KEY_ALIASES: Record<string, string> = {
  esc: "escape",
  del: "delete",
  ins: "insert",
  up: "arrowup",
  down: "arrowdown",
  left: "arrowleft",
  right: "arrowright",
  spacebar: "space",
  return: "enter",
  cmd: "meta",
  command: "meta",
  control: "ctrl",
  option: "alt",
};

const MODIFIERS = new Set(["ctrl", "meta", "alt", "shift", "mod"]);

function useHotkeys(
  hotkeys: string | string[],
  handler: (event: KeyboardEvent) => void,
  options: UseHotkeysOptions = {},
): void {
  const {
    enabled = true,
    target,
    enableOnFormElements = false,
    preventDefault = true,
    sequenceTimeout = 1000,
  } = options;

  const bindingKey = Array.isArray(hotkeys) ? hotkeys.join("|") : hotkeys;
  const handlerRef = React.useRef(handler);

  React.useEffect(() => {
    handlerRef.current = handler;
  });

  React.useEffect(() => {
    if (!enabled) return undefined;

    const element = target ?? document;
    const bindings = bindingKey.split("|").map(parseHotkey);
    const longest = Math.max(...bindings.map((binding) => binding.length));

    let buffer: KeyboardEvent[] = [];
    let timeout: ReturnType<typeof setTimeout> | undefined;

    const onKeyDown = (event: Event) => {
      if (!(event instanceof KeyboardEvent)) return;

      const keyboardEvent = event;

      if (keyboardEvent.repeat) return;
      if (isModifierKey(keyboardEvent.key)) return;
      if (!enableOnFormElements && isFormElement(keyboardEvent.target)) return;

      buffer = [...buffer, keyboardEvent].slice(-longest);

      clearTimeout(timeout);
      timeout = setTimeout(() => {
        buffer = [];
      }, sequenceTimeout);

      for (const binding of bindings) {
        if (binding.length > buffer.length) continue;

        const tail = buffer.slice(-binding.length);
        const matched = binding.every((step, index) => {
          const stepEvent = tail[index];
          return stepEvent ? matchesStep(step, stepEvent) : false;
        });

        if (!matched) continue;

        buffer = [];
        clearTimeout(timeout);
        if (preventDefault) keyboardEvent.preventDefault();
        handlerRef.current(keyboardEvent);
        return;
      }
    };

    element.addEventListener("keydown", onKeyDown);

    return () => {
      clearTimeout(timeout);
      element.removeEventListener("keydown", onKeyDown);
    };
  }, [bindingKey, enabled, target, enableOnFormElements, preventDefault, sequenceTimeout]);
}

function parseHotkey(hotkey: string): HotkeyStep[] {
  return hotkey
    .trim()
    .split(/\s+/u)
    .filter(Boolean)
    .map((step) => parseHotkeyStep(step));
}

function parseHotkeyStep(step: string): HotkeyStep {
  const parts = step
    .split("+")
    .map((part) => normalizeKey(part))
    .filter(Boolean);

  const isApple = typeof navigator !== "undefined" && /mac|iphone|ipad/iu.test(navigator.userAgent);
  const key = parts.find((part) => !MODIFIERS.has(part)) ?? "";
  const has = (name: string) => parts.includes(name);
  const mod = has("mod");

  return {
    key,
    ctrl: has("ctrl") || (mod && !isApple),
    meta: has("meta") || (mod && isApple),
    alt: has("alt"),
    shift: has("shift"),
  };
}

function normalizeKey(key: string): string {
  const normalized = key.trim().toLowerCase();

  if (normalized === " ") return "space";
  return KEY_ALIASES[normalized] ?? normalized;
}

function matchesStep(step: HotkeyStep, event: KeyboardEvent): boolean {
  if (step.ctrl !== event.ctrlKey) return false;
  if (step.meta !== event.metaKey) return false;
  if (step.alt !== event.altKey) return false;
  if (step.shift && !event.shiftKey) return false;

  // A literal `"k"` should not fire on `Shift+K`, but a symbol such as `"?"` needs Shift to type.
  if (!step.shift && event.shiftKey && /^[a-z0-9]$/u.test(step.key)) return false;

  return normalizeKey(event.key) === step.key || codeToKey(event.code) === step.key;
}

function codeToKey(code: string): string {
  if (code.startsWith("Key")) return code.slice(3).toLowerCase();
  if (code.startsWith("Digit")) return code.slice(5);

  const punctuation: Record<string, string> = {
    Slash: "/",
    Period: ".",
    Comma: ",",
    Semicolon: ";",
    Quote: "'",
    Backquote: "`",
    Minus: "-",
    Equal: "=",
    BracketLeft: "[",
    BracketRight: "]",
    Backslash: "\\",
  };

  return punctuation[code] ?? code.toLowerCase();
}

function isModifierKey(key: string): boolean {
  return ["Control", "Meta", "Alt", "Shift"].includes(key);
}

function isFormElement(target: EventTarget | null): boolean {
  if (!(target instanceof HTMLElement)) return false;
  if (target.isContentEditable) return true;

  return ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
}

export { useHotkeys, type UseHotkeysOptions };
```



## Usage

Declare a shortcut where the thing it does lives, instead of routing every key through one global
`keydown` switch.

```tsx
import { useHotkeys } from "@/hooks/use-hotkeys";

function CommandMenu() {
  const [open, setOpen] = React.useState(false);

  useHotkeys("mod+k", () => setOpen((value) => !value));

  return <CommandDialog open={open} onOpenChange={setOpen} />;
}
```

## Syntax

- **Combinations** join with `+`: `"mod+k"`, `"ctrl+shift+p"`, `"alt+arrowleft"`.
- **Sequences** separate with a space: `"g i"` fires when `g` is followed by `i` within
  `sequenceTimeout`. This is the Gmail-style navigation pattern.
- **`mod`** is `⌘` on Apple platforms and `Ctrl` everywhere else — the whole reason not to hardcode
  `meta`.
- Aliases are accepted for the names people actually type: `esc`, `del`, `up`, `down`, `left`,
  `right`, `return`, `cmd`, `option`, `space`.

Pass an array to bind several shortcuts to the same handler:

```tsx
useHotkeys(["mod+s", "ctrl+s"], save);
```

## Matching

Modifiers must match exactly, so `"k"` does not fire on `⌘K`. Keys are matched against both
`event.key` and a normalized `event.code`, which means two things worth knowing:

- Letter shortcuts work on non-QWERTY layouts, because `KeyK` resolves to `k` regardless of layout.
- Shifted punctuation works either way: `"?"` and `"shift+/"` both fire on the same keystroke.

## Options

| Option                 | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| `enabled`              | Detach the listener without unmounting — e.g. only while a panel is focused. |
| `target`               | Element to listen on. Defaults to `document`.                                |
| `enableOnFormElements` | Fire while an input, textarea, select, or contenteditable has focus. Off by default. |
| `preventDefault`       | Call `preventDefault` on a match. On by default, since most shortcuts shadow a browser default. |
| `sequenceTimeout`      | Milliseconds allowed between sequence steps. Defaults to `1000`.             |

## Behavior

- The handler is read from a ref, so it always sees current state and never re-binds the listener.
- Auto-repeat is ignored, so holding a key fires once.
- Pressing a modifier on its own never starts or breaks a sequence.
- Sequence progress resets after a match, a timeout, or a non-matching key.


---

URL: https://mwui.vercel.app/utilities/use-intersection-observer.md

A hook that tracks whether an element is in the viewport.

# useIntersectionObserver

A hook that tracks whether an element is in the viewport.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-intersection-observer.json
```

[Registry JSON](https://mwui.vercel.app/r/use-intersection-observer.json)

## Preview

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

import { useIntersectionObserver } from "@/hooks/use-intersection-observer";

export function Preview() {
  const watched = useIntersectionObserver<HTMLDivElement>({ threshold: 0.9 });
  const revealed = useIntersectionObserver<HTMLDivElement>({ threshold: 0.5, once: true });

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div className="flex items-center justify-between">
        <span className="text-muted-foreground">Card in view</span>
        <Badge variant={watched.isIntersecting ? "default" : "outline"}>
          {watched.isIntersecting ? "visible" : "hidden"}
        </Badge>
      </div>

      <div className="h-48 overflow-y-auto rounded-lg border border-border p-3">
        <div className="flex h-32 items-center justify-center text-xs text-muted-foreground">
          Scroll down ↓
        </div>

        <div
          ref={watched.ref}
          className="flex h-24 items-center justify-center rounded-md bg-muted text-xs"
        >
          Watched card
        </div>

        <div className="flex h-32 items-center justify-center text-xs text-muted-foreground">
          Keep scrolling ↓
        </div>

        <div
          ref={revealed.ref}
          data-visible={revealed.isIntersecting}
          className="flex h-24 items-center justify-center rounded-md border border-dashed border-border text-xs opacity-0 transition-opacity duration-500 data-[visible=true]:opacity-100"
        >
          Revealed once
        </div>

        <div className="h-16" />
      </div>
    </div>
  );
}
```


## Source

### hooks/use-intersection-observer.ts

```ts
"use client";

import * as React from "react";

type UseIntersectionObserverOptions = {
  root?: Element | Document | null;
  rootMargin?: string;
  threshold?: number | number[];
  once?: boolean;
  disabled?: boolean;
  initialIsIntersecting?: boolean;
  onChange?: (entry: IntersectionObserverEntry) => void;
};

type UseIntersectionObserverResult<T extends Element> = {
  ref: (node: T | null) => void;
  entry: IntersectionObserverEntry | null;
  isIntersecting: boolean;
};

function useIntersectionObserver<T extends Element = HTMLElement>({
  root = null,
  rootMargin = "0px",
  threshold = 0,
  once = false,
  disabled = false,
  initialIsIntersecting = false,
  onChange,
}: UseIntersectionObserverOptions = {}): UseIntersectionObserverResult<T> {
  const [element, setElement] = React.useState<T | null>(null);
  const [entry, setEntry] = React.useState<IntersectionObserverEntry | null>(null);
  const [isIntersecting, setIsIntersecting] = React.useState(initialIsIntersecting);

  const onChangeRef = React.useRef(onChange);

  React.useEffect(() => {
    onChangeRef.current = onChange;
  });

  const thresholdKey = Array.isArray(threshold) ? threshold.join(",") : String(threshold);
  const frozen = once && isIntersecting;

  React.useEffect(() => {
    if (!element || disabled || frozen) return undefined;
    if (typeof IntersectionObserver === "undefined") return undefined;

    const observer = new IntersectionObserver(
      (entries) => {
        for (const nextEntry of entries) {
          setEntry(nextEntry);
          setIsIntersecting(nextEntry.isIntersecting);
          onChangeRef.current?.(nextEntry);
        }
      },
      {
        root,
        rootMargin,
        threshold: thresholdKey.includes(",")
          ? thresholdKey.split(",").map(Number)
          : Number(thresholdKey),
      },
    );

    observer.observe(element);
    return () => observer.disconnect();
  }, [element, root, rootMargin, thresholdKey, disabled, frozen]);

  return { ref: setElement, entry, isIntersecting };
}

export {
  useIntersectionObserver,
  type UseIntersectionObserverOptions,
  type UseIntersectionObserverResult,
};
```



## Usage

The primitive behind infinite scroll, lazy media, reveal-on-scroll animation, and scroll-spy
navigation — all of which are the same question asked with different options.

```tsx
import { useIntersectionObserver } from "@/hooks/use-intersection-observer";

function LoadMore({ onReach }: { onReach: () => void }) {
  const { ref } = useIntersectionObserver({
    rootMargin: "400px",
    onChange: (entry) => entry.isIntersecting && onReach(),
  });

  return <div ref={ref} aria-hidden className="h-px" />;
}
```

`ref` is a callback ref, so the element can mount, unmount, and remount — inside a conditional, a
list, or a virtualized viewport — and the observer follows it. A `RefObject` cannot do that.

## Reveal once

`once` freezes the result after the first intersection and disconnects the observer, which is what
entrance animations want: they should not replay when the user scrolls back up.

```tsx
const { ref, isIntersecting } = useIntersectionObserver({ threshold: 0.3, once: true });

<section ref={ref} data-visible={isIntersecting} className="opacity-0 data-[visible=true]:animate-in">
```

## Options

| Option                  | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| `root`                  | Scroll container to measure against. Defaults to the viewport.              |
| `rootMargin`            | Grows or shrinks the root box. Positive values fire early — use for prefetch. |
| `threshold`             | Fraction of the element that must be visible. Accepts an array.             |
| `once`                  | Stop observing after the first intersection.                                |
| `disabled`              | Pause observation without unmounting.                                       |
| `initialIsIntersecting` | Value returned before the observer reports. Set `true` to avoid a flash.     |
| `onChange`              | Called with each entry. Read from a ref, so it need not be memoized.        |

## Returns

`entry` is the raw `IntersectionObserverEntry` — reach for `intersectionRatio` or `boundingClientRect`
when a boolean is not enough, such as a scroll-spy that highlights the most visible heading.


---

URL: https://mwui.vercel.app/utilities/use-local-storage.md

A hook that persists state to localStorage and syncs it across tabs.

# useLocalStorage

A hook that persists state to localStorage and syncs it across tabs.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-local-storage.json
```

[Registry JSON](https://mwui.vercel.app/r/use-local-storage.json)

## Preview

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

import { useLocalStorage } from "@/hooks/use-local-storage";

export function Preview() {
  const [count, setCount, reset] = useLocalStorage("mwui:preview:count", 0);

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <div className="flex items-center justify-center gap-3">
        <Button size="icon-xs" variant="outline" onClick={() => setCount((value) => value - 1)}>
          -
        </Button>
        <span className="w-10 text-center text-lg tabular-nums">{count}</span>
        <Button size="icon-xs" variant="outline" onClick={() => setCount((value) => value + 1)}>
          +
        </Button>
      </div>

      <Button size="xs" variant="ghost" onClick={reset}>
        Reset
      </Button>

      <p className="text-center text-xs text-muted-foreground">
        Reload the page, or open this page in a second tab, and the value follows.
      </p>
    </div>
  );
}
```


## Source

### hooks/use-local-storage.ts

```ts
"use client";

import * as React from "react";

type LocalStorageUpdater<T> = (previous: T) => T;

type UseLocalStorageOptions<T> = {
  serialize?: (value: T) => string;
  deserialize?: (raw: string) => T;
};

function isLocalStorageUpdater<T>(
  next: T | LocalStorageUpdater<T>,
): next is LocalStorageUpdater<T> {
  return typeof next === "function";
}

function getChangeEventName(key: string) {
  return `use-local-storage:${key}`;
}

function useLocalStorage<T>(
  key: string,
  defaultValue: T,
  { serialize = JSON.stringify, deserialize = JSON.parse }: UseLocalStorageOptions<T> = {},
): [T, (next: T | LocalStorageUpdater<T>) => void, () => void] {
  const subscribe = React.useCallback(
    (onStoreChange: () => void) => {
      const eventName = getChangeEventName(key);

      const handleStorage = (event: StorageEvent) => {
        if (event.key === null || event.key === key) onStoreChange();
      };

      window.addEventListener("storage", handleStorage);
      window.addEventListener(eventName, onStoreChange);

      return () => {
        window.removeEventListener("storage", handleStorage);
        window.removeEventListener(eventName, onStoreChange);
      };
    },
    [key],
  );

  const getSnapshot = React.useCallback(() => {
    try {
      return window.localStorage.getItem(key);
    } catch {
      return null;
    }
  }, [key]);

  const raw = React.useSyncExternalStore(subscribe, getSnapshot, () => null);

  const value = React.useMemo(() => {
    if (raw === null) return defaultValue;

    try {
      return deserialize(raw);
    } catch {
      return defaultValue;
    }
  }, [raw, defaultValue, deserialize]);

  const valueRef = React.useRef(value);
  const serializeRef = React.useRef(serialize);
  const defaultValueRef = React.useRef(defaultValue);

  React.useEffect(() => {
    valueRef.current = value;
    serializeRef.current = serialize;
    defaultValueRef.current = defaultValue;
  });

  const setValue = React.useCallback(
    (next: T | LocalStorageUpdater<T>) => {
      const nextValue = isLocalStorageUpdater(next) ? next(valueRef.current) : next;

      try {
        window.localStorage.setItem(key, serializeRef.current(nextValue));
      } catch {
        return;
      }

      valueRef.current = nextValue;
      window.dispatchEvent(new Event(getChangeEventName(key)));
    },
    [key],
  );

  const remove = React.useCallback(() => {
    try {
      window.localStorage.removeItem(key);
    } catch {
      return;
    }

    valueRef.current = defaultValueRef.current;
    window.dispatchEvent(new Event(getChangeEventName(key)));
  }, [key]);

  return [value, setValue, remove];
}

export { useLocalStorage, type LocalStorageUpdater, type UseLocalStorageOptions };
```



## Usage

State that survives a reload, shaped like `useState`.

```tsx
import { useLocalStorage } from "@/hooks/use-local-storage";

function SidebarToggle() {
  const [collapsed, setCollapsed, reset] = useLocalStorage("sidebar:collapsed", false);

  return <button onClick={() => setCollapsed((previous) => !previous)}>{String(collapsed)}</button>;
}
```

The tuple is `[value, setValue, remove]`. `setValue` takes a value or an updater; `remove` deletes
the key and returns the hook to `defaultValue`.

## Staying in sync

Every component reading the same key stays in sync, in two directions:

- **Across tabs**, through the native `storage` event.
- **Within a tab**, through a scoped event the hook dispatches on write — because `storage` does
  not fire in the tab that made the change.

So two sidebars, two tabs, and a background write all converge on the same value without a store.

## Server rendering

The hook reads through `useSyncExternalStore` with a server snapshot of `null`, so the first render
returns `defaultValue` on both sides and hydration never mismatches. The stored value appears
immediately after mount.

## Notes

- Values are serialized with `JSON.stringify` / `JSON.parse`. Pass `serialize` and `deserialize` for
  anything else, such as `Date` or `Map`.
- Unreadable, unwritable, and unparseable storage all fall back to `defaultValue` rather than
  throwing, which covers private browsing modes, disabled storage, quota limits, and values written
  by an older version of your app.
- `defaultValue` and `deserialize` participate in memoization. Hoist them to module scope, or
  memoize them, if you pass non-primitives.


---

URL: https://mwui.vercel.app/utilities/use-media-query.md

A hook that tracks a CSS media query without tearing during hydration.

# useMediaQuery

A hook that tracks a CSS media query without tearing during hydration.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-media-query.json
```

[Registry JSON](https://mwui.vercel.app/r/use-media-query.json)

## Preview

```tsx
import { useMediaQuery } from "@/hooks/use-media-query";

const QUERIES = [
  { label: "sm", query: "(min-width: 640px)" },
  { label: "md", query: "(min-width: 768px)" },
  { label: "lg", query: "(min-width: 1024px)" },
  { label: "Dark", query: "(prefers-color-scheme: dark)" },
  { label: "Reduced motion", query: "(prefers-reduced-motion: reduce)" },
];

function QueryRow({ label, query }: { label: string; query: string }) {
  const matches = useMediaQuery(query);

  return (
    <div className="flex items-center justify-between gap-6 text-sm">
      <span className="font-mono text-xs text-muted-foreground">{label}</span>
      <span
        data-matches={matches || undefined}
        className="rounded-md bg-muted px-2 py-0.5 text-xs data-matches:bg-primary data-matches:text-primary-foreground"
      >
        {matches ? "matches" : "no match"}
      </span>
    </div>
  );
}

export function Preview() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      {QUERIES.map((entry) => (
        <QueryRow key={entry.query} label={entry.label} query={entry.query} />
      ))}
      <p className="pt-2 text-xs text-muted-foreground">Resize the window to see these change.</p>
    </div>
  );
}
```


## Source

### hooks/use-media-query.ts

```ts
"use client";

import * as React from "react";

type UseMediaQueryOptions = {
  defaultValue?: boolean;
};

function useMediaQuery(
  query: string,
  { defaultValue = false }: UseMediaQueryOptions = {},
): boolean {
  const subscribe = React.useCallback(
    (onStoreChange: () => void) => {
      const mediaQueryList = window.matchMedia(query);
      mediaQueryList.addEventListener("change", onStoreChange);
      return () => mediaQueryList.removeEventListener("change", onStoreChange);
    },
    [query],
  );

  const getSnapshot = React.useCallback(() => window.matchMedia(query).matches, [query]);
  const getServerSnapshot = React.useCallback(() => defaultValue, [defaultValue]);

  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

export { useMediaQuery, type UseMediaQueryOptions };
```



## Usage

Subscribes to a CSS media query and re-renders when it starts or stops matching.

```tsx
import { useMediaQuery } from "@/hooks/use-media-query";

function Navigation() {
  const isDesktop = useMediaQuery("(min-width: 768px)");

  return isDesktop ? <Sidebar /> : <MobileDrawer />;
}
```

## Server rendering

The hook is built on `useSyncExternalStore`, which takes a separate server snapshot. On the server
and during the first client render it returns `defaultValue`, then switches to the real result — so
React never has to reconcile two different trees for the same commit.

```tsx
const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)", {
  defaultValue: true,
});
```

Pick the `defaultValue` that matches the markup you render on the server. For layout queries that
usually means the mobile branch; for `prefers-reduced-motion` it usually means the safe one.

> **Prefer CSS where you can.** A media query in CSS costs nothing and never mismatches. Reach for
> this hook when the breakpoint has to change *what renders* — a different component, a different
> DOM structure — not just how it looks.

## Notes

- The query string is passed straight to `window.matchMedia`, so any valid media query works.
- Changing `query` resubscribes automatically.
- Listeners are registered with `addEventListener`, and are cleaned up on unmount.


---

URL: https://mwui.vercel.app/utilities/use-mounted.md

A hook that reports whether the component has mounted on the client.

# useMounted

A hook that reports whether the component has mounted on the client.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-mounted.json
```

[Registry JSON](https://mwui.vercel.app/r/use-mounted.json)

## Preview

```tsx
import * as React from "react";

import { Skeleton } from "@/components/ui/skeleton";

import { useMounted } from "@/hooks/use-mounted";

export function Preview() {
  const mounted = useMounted();
  const [now] = React.useState(() => new Date());

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div className="flex items-center justify-between rounded-lg border border-border px-3 py-2">
        <span className="text-muted-foreground">Local time</span>
        {mounted ? (
          <span className="font-mono tabular-nums">{now.toLocaleTimeString()}</span>
        ) : (
          <Skeleton className="h-4 w-20" />
        )}
      </div>

      <p className="text-xs text-muted-foreground">
        The server has no timezone for this user, so the formatted time renders only after
        hydration.
      </p>
    </div>
  );
}
```


## Source

### hooks/use-mounted.ts

```ts
"use client";

import * as React from "react";

function subscribe(): () => void {
  return () => {};
}

function getSnapshot(): boolean {
  return true;
}

function getServerSnapshot(): boolean {
  return false;
}

function useMounted(): boolean {
  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

export { useMounted };
```



## Usage

For the handful of values that genuinely cannot match between server and client — a locale-formatted
date, a resolved theme, a portal target, anything read from `window` — render a stable placeholder
until after hydration.

```tsx
import { useMounted } from "@/hooks/use-mounted";

function LocalTime({ date }: { date: Date }) {
  const mounted = useMounted();

  if (!mounted) return <span className="opacity-0">00:00</span>;

  return <span>{date.toLocaleTimeString()}</span>;
}
```

## Why `useSyncExternalStore`

The usual implementation is `useState(false)` plus an effect that sets it to `true`. That works, but
it schedules an extra state update on every mounted component and is easy to accidentally call
during a render that React may discard.

`useSyncExternalStore` expresses the same thing declaratively: the server snapshot is `false`, the
client snapshot is `true`, and the store never notifies. React reads `false` while rendering on the
server and during hydration, then `true` — no effect, no extra state.

## Use it sparingly

Every `useMounted` branch is content the user does not see on first paint, and it is not the fix for
most hydration warnings. Reach for it when the value is genuinely client-only. When the difference
is only visual, prefer CSS; when it is data, prefer passing it down from the server.


---

URL: https://mwui.vercel.app/utilities/use-previous.md

A hook that remembers the value from before the most recent change.

# usePrevious

A hook that remembers the value from before the most recent change.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-previous.json
```

[Registry JSON](https://mwui.vercel.app/r/use-previous.json)

## Preview

```tsx
import * as React from "react";

import { Button } from "@/components/ui/button";

import { usePrevious } from "@/hooks/use-previous";

export function Preview() {
  const [value, setValue] = React.useState(12);
  const [unrelated, setUnrelated] = React.useState(0);
  const previous = usePrevious(value);

  const direction = previous === undefined ? "—" : value > previous ? "up" : "down";

  return (
    <div className="flex w-full max-w-sm flex-col gap-4 text-sm">
      <div className="grid grid-cols-3 gap-2 rounded-lg border border-border p-3 text-center">
        <div>
          <p className="text-xs text-muted-foreground">Previous</p>
          <p className="font-mono text-lg tabular-nums">{previous ?? "—"}</p>
        </div>
        <div>
          <p className="text-xs text-muted-foreground">Current</p>
          <p className="font-mono text-lg tabular-nums">{value}</p>
        </div>
        <div>
          <p className="text-xs text-muted-foreground">Direction</p>
          <p className="font-mono text-lg">{direction}</p>
        </div>
      </div>

      <div className="flex flex-wrap gap-2">
        <Button size="sm" variant="outline" onClick={() => setValue((n) => n - 3)}>
          Decrease
        </Button>
        <Button size="sm" variant="outline" onClick={() => setValue((n) => n + 3)}>
          Increase
        </Button>
        <Button size="sm" variant="ghost" onClick={() => setUnrelated((n) => n + 1)}>
          Re-render only ({unrelated})
        </Button>
      </div>

      <p className="text-xs text-muted-foreground">
        Re-rendering without changing the value leaves the previous value untouched.
      </p>
    </div>
  );
}
```


## Source

### hooks/use-previous.ts

```ts
"use client";

import * as React from "react";

function usePrevious<T>(value: T, isEqual: (a: T, b: T) => boolean = Object.is): T | undefined {
  const [current, setCurrent] = React.useState(value);
  const [previous, setPrevious] = React.useState<T | undefined>(undefined);

  if (!isEqual(current, value)) {
    setPrevious(current);
    setCurrent(value);
  }

  return previous;
}

export { usePrevious };
```



## Usage

Useful whenever a render needs to know where a value came from: animating a number in the direction
it moved, highlighting a row that just changed, or firing a transition only on the edge.

```tsx
import { usePrevious } from "@/hooks/use-previous";

function Score({ value }: { value: number }) {
  const previous = usePrevious(value);
  const direction = previous === undefined ? "flat" : value > previous ? "up" : "down";

  return <span data-direction={direction}>{value}</span>;
}
```

## The value it actually returns

The common `useRef` + `useEffect` implementation returns "the value at the last commit", which
quietly becomes the *current* value as soon as the component re-renders for an unrelated reason —
a parent update, a sibling state change. That makes it unreliable exactly when you compare against
it in render.

This version stores the previous value in state and updates it during render, the pattern React
documents for deriving state from props. It returns the value from **before the last change**, and
holds that value steady across re-renders that did not change the input.

```tsx
const previous = usePrevious(value);
// value: 1 → 1 → 2 → 2 → 2
// previous: undefined → undefined → 1 → 1 → 1
```

`undefined` on the first render means there is no previous value yet — not that the previous value
was `undefined`.

## Comparison

Objects and arrays rebuilt each render would register as a change under the default `Object.is`.
Pass a comparator:

```tsx
const previousRange = usePrevious(range, (a, b) => a.start === b.start && a.end === b.end);
```


---

URL: https://mwui.vercel.app/utilities/use-resize-observer.md

A hook that measures an element and updates on resize.

# useResizeObserver

A hook that measures an element and updates on resize.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-resize-observer.json
```

[Registry JSON](https://mwui.vercel.app/r/use-resize-observer.json)

## Preview

```tsx
import { useResizeObserver } from "@/hooks/use-resize-observer";

export function Preview() {
  const { ref, width, height } = useResizeObserver<HTMLDivElement>();

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <div
        ref={ref}
        className="grid min-h-24 w-56 max-w-full min-w-24 resize place-items-center overflow-auto rounded-lg border border-dashed border-border bg-muted/40 p-3"
      >
        <span className="text-xs text-muted-foreground">Drag the corner ↘</span>
      </div>

      <p className="font-mono text-xs text-muted-foreground">
        {width} × {height}
      </p>
    </div>
  );
}
```


## Source

### hooks/use-resize-observer.ts

```ts
"use client";

import * as React from "react";

type ResizeObserverBox = "border-box" | "content-box";

type UseResizeObserverOptions = {
  box?: ResizeObserverBox;
  round?: (value: number) => number;
  onResize?: (size: ElementSize) => void;
};

type ElementSize = {
  width: number;
  height: number;
};

type UseResizeObserverResult<T extends Element> = ElementSize & {
  ref: (node: T | null) => void;
  element: T | null;
};

function useResizeObserver<T extends Element = HTMLElement>({
  box = "content-box",
  round = Math.round,
  onResize,
}: UseResizeObserverOptions = {}): UseResizeObserverResult<T> {
  const [element, setElement] = React.useState<T | null>(null);
  const [size, setSize] = React.useState<ElementSize>({ width: 0, height: 0 });

  const roundRef = React.useRef(round);
  const onResizeRef = React.useRef(onResize);

  React.useEffect(() => {
    roundRef.current = round;
    onResizeRef.current = onResize;
  });

  React.useEffect(() => {
    if (!element) return undefined;
    if (typeof ResizeObserver === "undefined") return undefined;

    const observer = new ResizeObserver(([entry]) => {
      if (!entry) return;

      const next = readEntrySize(entry, box, roundRef.current);

      setSize((previous) =>
        previous.width === next.width && previous.height === next.height ? previous : next,
      );
      onResizeRef.current?.(next);
    });

    observer.observe(element, { box });
    return () => observer.disconnect();
  }, [element, box]);

  return { ref: setElement, element, width: size.width, height: size.height };
}

function readEntrySize(
  entry: ResizeObserverEntry,
  box: ResizeObserverBox,
  round: (value: number) => number,
): ElementSize {
  const boxSize = box === "border-box" ? entry.borderBoxSize : entry.contentBoxSize;
  const measurement = Array.isArray(boxSize) ? boxSize[0] : boxSize;

  if (measurement) {
    return { width: round(measurement.inlineSize), height: round(measurement.blockSize) };
  }

  return { width: round(entry.contentRect.width), height: round(entry.contentRect.height) };
}

export {
  useResizeObserver,
  type ElementSize,
  type UseResizeObserverOptions,
  type UseResizeObserverResult,
};
```



## Usage

Element size, not viewport size. Use it for the decisions a media query cannot make: a card that
switches layout because its column is narrow, a chart that needs pixel dimensions, a textarea that
must re-measure when its container changes width.

```tsx
import { useResizeObserver } from "@/hooks/use-resize-observer";

function Chart({ points }: { points: Point[] }) {
  const { ref, width, height } = useResizeObserver<HTMLDivElement>();

  return (
    <div ref={ref} className="h-64 w-full">
      {width > 0 ? <svg width={width} height={height}>{/* … */}</svg> : null}
    </div>
  );
}
```

`ref` is a callback ref, so the measurement starts as soon as the node attaches — including when the
element mounts later or is swapped out.

## Boxes

`content-box` (the default) excludes padding and border; `border-box` is the element's rendered
size. Pick `border-box` when the number feeds back into a layout, so padding changes do not cause a
measure-resize loop.

```tsx
const { ref, width } = useResizeObserver<HTMLDivElement>({ box: "border-box" });
```

## Options

| Option     | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| `box`      | `"content-box"` (default) or `"border-box"`.                                     |
| `round`    | How subpixel values are collapsed. Defaults to `Math.round`; pass `Math.floor` to avoid overflow, or `(n) => n` for exact values. |
| `onResize` | Called on every observed change, for work that should not trigger a re-render.   |

## Behavior

- State updates are skipped when the rounded size did not change, so a resize that lands on the same
  integer does not re-render.
- `onResize` is read from a ref and never re-subscribes the observer.
- Before the first measurement — and during server rendering — `width` and `height` are `0`. Branch
  on that rather than rendering a zero-sized canvas.


---

URL: https://mwui.vercel.app/utilities/use-scroll-lock.md

A hook that locks body scroll without layout shift.

# useScrollLock

A hook that locks body scroll without layout shift.

## Installation

```bash
npx shadcn@latest add https://mwui.vercel.app/r/use-scroll-lock.json
```

[Registry JSON](https://mwui.vercel.app/r/use-scroll-lock.json)

## Preview

```tsx
import * as React from "react";

import { Button } from "@/components/ui/button";

import { useScrollLock } from "@/hooks/use-scroll-lock";

export function Preview() {
  const [locked, setLocked] = React.useState(false);

  useScrollLock(locked);

  return (
    <div className="flex w-full max-w-sm flex-col gap-3 text-sm">
      <Button variant={locked ? "default" : "outline"} onClick={() => setLocked((value) => !value)}>
        {locked ? "Unlock page scroll" : "Lock page scroll"}
      </Button>

      <p className="text-xs text-muted-foreground">
        {locked
          ? "The page behind this preview will not scroll, and the layout did not shift."
          : "Lock it, then try scrolling the docs page."}
      </p>
    </div>
  );
}
```


## Source

### hooks/use-scroll-lock.ts

```ts
"use client";

import * as React from "react";

type UseScrollLockOptions = {
  /** Element to lock. Defaults to `document.body`. */
  target?: HTMLElement | null;
  /** CSS variable set to the measured scrollbar width while locked. */
  widthVariable?: string;
};

type LockRecord = {
  count: number;
  overflow: string;
  paddingRight: string;
};

const locks = new WeakMap<HTMLElement, LockRecord>();

function useScrollLock(locked = true, options: UseScrollLockOptions = {}): void {
  const { target, widthVariable = "--scrollbar-width" } = options;

  React.useEffect(() => {
    if (!locked) return undefined;

    const element = target ?? document.body;
    const existing = locks.get(element);

    if (existing) {
      existing.count += 1;
    } else {
      const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
      const record: LockRecord = {
        count: 1,
        overflow: element.style.overflow,
        paddingRight: element.style.paddingRight,
      };

      locks.set(element, record);

      const currentPadding = Number.parseFloat(getComputedStyle(element).paddingRight) || 0;

      element.style.overflow = "hidden";
      element.style.setProperty(widthVariable, `${scrollbarWidth}px`);

      if (scrollbarWidth > 0) {
        element.style.paddingRight = `${currentPadding + scrollbarWidth}px`;
      }
    }

    return () => {
      const record = locks.get(element);
      if (!record) return;

      record.count -= 1;
      if (record.count > 0) return;

      element.style.overflow = record.overflow;
      element.style.paddingRight = record.paddingRight;
      element.style.removeProperty(widthVariable);
      locks.delete(element);
    };
  }, [locked, target, widthVariable]);
}

export { useScrollLock, type UseScrollLockOptions };
```



## Usage

When a modal, drawer, or full-screen menu opens, the page behind it should stop scrolling. Setting
`overflow: hidden` on `<body>` does that — and on desktop it also removes the scrollbar, which
shifts the whole layout a few pixels to the right. This hook compensates for the missing scrollbar
so nothing moves.

```tsx
import { useScrollLock } from "@/hooks/use-scroll-lock";

function Drawer({ open, children }: DrawerProps) {
  useScrollLock(open);

  return open ? <div className="fixed inset-0">{children}</div> : null;
}
```

Pass the open state directly — the hook is a no-op while it is `false`, so there is no conditional
hook call and no separate cleanup path.

## Nested locks

Locks are reference counted per element. A dialog that opens a confirmation on top of itself will
lock twice and unlock twice; scrolling is restored only when the last consumer releases it. Without
counting, closing the inner dialog would unlock the page while the outer one is still open.

## Fixed elements

While locked, the measured scrollbar width is published as a CSS variable on the locked element, so
position-fixed chrome can compensate too:

```css
.app-header {
  padding-right: var(--scrollbar-width, 0px);
}
```

## Options

| Option          | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `target`        | Element to lock. Defaults to `document.body`.                      |
| `widthVariable` | Name of the CSS variable holding the scrollbar width. Defaults to `--scrollbar-width`. |

## Behavior

- The previous inline `overflow` and `padding-right` are captured before locking and written back on
  release, so an element that already had inline styles keeps them.
- Padding is added on top of the computed value rather than replacing it.
- Everything runs in an effect, so server rendering is unaffected.