; } ``` `` renders with `rounded-lg border border-border p-6`. `Panel` has no `"use client"`, so it imports `cn` from `chunks-ui/utils`, and it works in server and client components. ### What it accepts Strings, numbers, arrays (readonly ones and `as const` tuples too) and dictionaries of class names to conditions. Booleans, `null`, `undefined` and `0` are skipped, so conditions can go inline: ```tsx cn("text-sm", isActive && "font-semibold", ["rounded-md", { "opacity-50": disabled }]); // isActive true, disabled false: "text-sm font-semibold rounded-md" ``` Functions are a type error. clsx ignores them, so a function would never produce a class. For a `className` that may be a function of state, use [`cnState`](#cnstate). ### Theme tokens `cn` knows the tokens from `chunks-ui/theme.css`, so an override of a token class replaces it instead of adding a second one: | Token | Classes | Example | |---|---|---| | Z-index layers | `z-base`, `z-dropdowns`, `z-tooltips`, `z-overlays`, `z-drawers`, `z-modals`, `z-notifications`, `z-toasts`, `z-cursor` | `cn("z-dropdowns", "z-50")` → `"z-50"` | | Component sizing | `ui-height`, `ui-icon-height` in any spacing utility (`h-`, `size-`, `min-h-`, `p-`…) | `cn("h-ui-height", "h-8")` → `"h-8"` | | Heading font | `font-heading` | `cn("font-heading", "font-mono")` → `"font-mono"` | | Easing curves | `ease-fluid`, `ease-snappy` | `cn("ease-fluid", "ease-in")` → `"ease-in"` | The z-index, sizing and easing values are on the [Theme](/theme) page. `font-heading` reads `--font-heading`, which has no default, so titles inherit their font until you set it. ## cnState Base UI parts accept `className` as a string or as a function of the part's state. `cnState` is `cn` for those parts: pass your classes first and the consumer's `className` last. - A string (or `undefined`) merges like `cn` and returns a string. - A function returns a new function of the state that merges your classes with its result. Use it when you wrap a Base UI part yourself: ```tsx import { Toggle } from "@base-ui/react/toggle"; import { cnState } from "chunks-ui"; import type { ComponentProps } from "react"; export function FavoriteToggle({ className, ...props }: ComponentProps) { return ( ); } ``` Consumers of `FavoriteToggle` can then pass either form, and both keep your base classes: ```tsx (state.pressed ? "bg-primary/10" : undefined)} /> ``` `cn(base, className)` does not compile here, because `cn` takes no functions. In `cnState` only the last argument may be one. ## className functions on components The parts that wrap a Base UI part take a `className` function and call it with that part's state. Its result merges with the part's own classes: ```tsx import { Tabs } from "chunks-ui"; (state.active ? "font-semibold" : undefined)}> Activity ; ``` Most of that state is also on the element as `data-*` attributes, so a plain string often does the same job: `className="data-active:font-semibold"`. These put `className` on an element that has no Base UI state: - **Plain HTML components**, such as `Card`, `Empty`, `Skeleton` and `Table`, take a string. - **`Tabs.Content`, `Tabs.Contents`, `Tabs.Animate` and `DatePicker`** render or wrap a plain `

`, so they take a string. - **`Radio.Item`** puts it on its ``, so it takes a string. Style the radio itself with `Radio.Root`. - **`Input`** with `startAdornment`, `endAdornment`, `clearable` or `onClear` (and `InputCopy`, which always has an end adornment) puts a string on the wrapper that positions the adornments, and a function on the input inside it: ```tsx import { Input } from "chunks-ui"; import { Search } from "lucide-react"; } className={(state) => (state.focused ? "border-primary" : undefined)} />; ``` ## mergeLabels `mergeLabels` merges a `labels` prop over a component's English defaults (see [Labels](/labels)), as the components do. A key set to `undefined` keeps the default, unlike a spread, which would overwrite it: ```tsx import { DEFAULT_CHIP_LABELS, mergeLabels } from "chunks-ui/utils"; const labels = mergeLabels(DEFAULT_CHIP_LABELS, { remove: undefined }); // { remove: "Remove" } ``` ## Types | Type | Description | |---|---| | `ClassInput` | What `cn` accepts: a string, number, bigint, boolean or nullish value, an array of `ClassInput`, or a dictionary of class names to conditions. clsx's `ClassValue` without functions. | | `StateClassName` | A Base UI part's `className`: `string \| ((state: State) => string \| undefined) \| undefined`. The last argument of `cnState`. | ## touch-target `touch-target` makes the hit area of a small control at least 44×44px, or the [size you set](#area-size). The area is centred on the control and takes no space, so the control keeps its size and the layout does not change. A press anywhere in the area goes to the control. It is opt-in: no component applies it, so add it to a control that is smaller than 44px and that people tap, for example an `IconButton` (32px), a `ClearButton` (24px) or a `Checkbox.Root` (16px): ```tsx ``` The class comes with `chunks-ui/theme.css`. It works with variants too (Tailwind 4.1 or later for these two): - `pointer-coarse:touch-target` makes the area larger only when the primary pointer is coarse, for example on a phone or tablet. - `any-pointer-coarse:touch-target` makes it larger when any pointer is coarse. Use it for hybrid devices, such as a laptop with a touch screen, where the primary pointer is the mouse or trackpad but people also tap. Use media-style variants (`pointer-coarse:`, `any-pointer-coarse:`, `min-[…]:`); state variants such as `hover:` create the area only in that state. ### Area size The `--touch-target-size` token sets the smallest size of the area on each axis. It is not defined by default: without it the area is 44px, the size that WCAG 2.5.5 (Target Size, Enhanced) asks for. Set it on any scope (an element, `:root`, or `@theme`) to change it for the controls inside, with an arbitrary property or in CSS: ```tsx

``` ```css .toolbar { --touch-target-size: 48px; } ``` A control that is larger than the token on an axis keeps its own size on that axis. The area is the control's `::after` pseudo-element, which has `position: absolute`. That has these effects: - **The control gets `position: relative`**, so the area is centred on it. This has zero specificity, so a position utility (`absolute`, `fixed`, `sticky`, also with a variant such as `md:`), an inline style or unlayered CSS wins, and the area is still centred. - **CSS in `@layer base` or `@layer components` does not win** over that `position: relative`. - **Do not combine `touch-target` with `static`** (or unlayered `position: static`): the area then sizes to the nearest positioned ancestor and covers it. - **Absolutely positioned children** of the control are now positioned relative to the control. - **Your `after:` classes change the area.** Do not use them on the same element. - **Some elements have no `::after`**, for example ``, `

` and `<img>`. On these elements the area does not grow.
- **Overflow cuts the area.** If the control or one of its parents has `overflow: hidden`, the area stops at that edge. In a scroll container, an area that goes past the container's padding makes the content scroll further. Give the container padding of at least half the difference between the area size (44px by default) and the control size.
- **The area covers the elements around the control**, except elements that paint above it (later positioned or transformed elements, or a higher z-index). Where it covers a neighbour, a press goes to the control, also on the neighbour's own box. Keep the centres of neighbouring controls at least the area size (44px by default) apart. If two areas overlap, the press goes to the control that comes later in the DOM.
- **A disabled control does not get presses.** The area inherits `pointer-events` from the control, so a control with `pointer-events: none`, such as a disabled `IconButton`, gets no presses anywhere in the area. A pointer in the area hovers an enabled control, so its hover styles apply; a disabled control's stay off. A disabled `Checkbox.Root`, `Switch.Root` or `ClearButton` keeps its pointer events (it shows a not-allowed cursor), so its area takes the press and the control ignores it: a disabled native button swallows the click.
- **A control with interactive descendants loses them.** The area paints and hit-tests above the control's own non-positioned children, so a press on, for example, the remove button of a `Chip` with `onRemove` goes to the `Chip`. Use `touch-target` only on a control with no interactive descendants.

## PortalContainerProvider

Popups (`Select`, `Combobox`, `Menu`, `Popover`, `DatePicker`, `Dialog`, `Drawer`, `Tooltip`) and the `NumberField.ScrubAreaCursor` render into `document.body`. `PortalContainerProvider` renders them into the element you pass as `value` instead, for example an element that scopes theme variables, so they get the same tokens. Popups opened directly in the content of a `Dialog`, `Drawer`, `Popover`, `Combobox`, `Menu`, `Select` or `Tooltip`, and the scrub cursor of a `NumberField` there, render inside that popup's own portal, so they end up in the same element.

Hold the element in state with a callback ref. A `useRef().current` is `null` on the first render, and setting it does not re-render. While `value` is `null`, popups are held back; once the element exists they render inside it. The scrub cursor is not held back: it exists only during a scrub, so it renders in `<body>` until the element exists.

```tsx
import { Button, Popover, PortalContainerProvider } from "chunks-ui";
import { useState } from "react";

export function ScopedPopover() {
  const [el, setEl] = useState<HTMLElement | null>(null);

return (
    <div ref={setEl} className="dark">
      <PortalContainerProvider value={el}>
        <Popover.Root>
          <Popover.Trigger render={<Button />}>Open</Popover.Trigger>
          <Popover.Content>Rendered inside the scoped element.</Popover.Content>
        </Popover.Root>
      </PortalContainerProvider>
    </div>
  );
}
```

`usePortalContainer()` returns the current container as `HTMLElement | null | undefined`: `undefined` means no provider, `null` means not mounted yet. Inside `Popover`, `Combobox`, `Menu`, `Select`, `Tooltip`, `Dialog` or `Drawer` content it is that popup's own portal element.

### Container limits

Inside the element, the popups are positioned as they are in `<body>`, unless the element or an ancestor inside `<body>` has a `position` other than `static` or one of these properties: `transform`, `translate`, `rotate`, `scale`, `perspective`, `filter`, `backdrop-filter`, `transform-style: preserve-3d`, a `contain` with `layout` or `paint` (as `content` and `strict` have), `content-visibility: auto`, or a `will-change` that names one of them. The element in the example has neither. A box that has one limits the popups, and so do some other properties of the element and its ancestors:

- **The box must not move while a trigger stays put.** `Combobox`, `DatePicker`, `Menu`, `Popover` and `Tooltip`, and a `Select` that opens below its trigger, have `position: absolute`, and Base UI places them against the nearest such box. It places them again on a scroll, on a window resize, when the trigger or the popup resizes, and when the trigger moves, but not when the box moves. A box after content that changes height moves with that content, and an open popup moves with it, away from a trigger above that content or in a fixed header.
- **The box must be at least as wide as those popups.** A popup that sizes to its content, such as a `Menu`, shrinks to the width of a narrower box, down to its minimum width, and its text wraps.
- **The box and the boxes around it must not clip.** An `overflow` other than `visible`, a `contain` with `paint`, or `content-visibility: auto` on the box, or on a box around it, cuts off the popups placed against the box at its edges. A `clip-path` on the element or an ancestor cuts off every popup at its edges, the fixed parts too, and so does a `mask` in Chromium and Firefox.
- **Parts with `position: fixed` need a box with none of the listed properties.** These are `Dialog`, `Drawer`, a `Select` aligned over its trigger (opened by touch, or with too little room to align, it opens below the trigger with `position: absolute`), the scrub cursor, and the backdrops, including the invisible one that Base UI puts behind a modal popup (`Dialog`, `Drawer`, `Menu` and `Select` are modal by default). They are placed against the viewport, and a listed property makes them relative to the box: a dialog centres in it, a drawer pins to its edge, a backdrop covers only the box, so a press outside it reaches the page, and the select and the scrub cursor, which Base UI places with viewport coordinates, are offset from the trigger and the pointer. A `position` alone does not move them, though `fixed` and `sticky` form a stacking context.
- **The popups stack inside the nearest stacking context around the element.** A `z-index` on a positioned element or a flex or grid item, `position: fixed` or `sticky`, an `opacity` below 1, `isolation: isolate`, a `mix-blend-mode`, a `mask`, a `clip-path` or one of the listed properties forms one. The `z-index` layers of the popups and the fixed parts count only inside it: page content that paints above that context covers them and takes their presses, such as a `sticky z-10` header beside a `relative z-0` `<main>` that holds the element.
- **The popups inherit from the element.** `pointer-events: none` on it or an ancestor stops presses on them, `inert` also stops focus, and `visibility: hidden` hides them.

To avoid these limits, render an element with no `position`, none of the listed properties and no stacking context straight into `<body>`, for example with `createPortal`, and give it the theme class or variables of the region its popups open from.

The popups' own portal elements, where nested popups and scrub cursors render, have no listed property and do not clip. Those of `Dialog` and `Drawer` are `fixed inset-x-0 top-0`: a box that stays put and is as wide as the viewport, and a stacking context on purpose, so what opens from a dialog stacks above it (see [Z-Index Layers](/theme#z-index-layers)). The others have no `position`.

---

# Components

---

# Accordion

A vertically stacked set of collapsible sections built on Base UI's `Accordion` primitive. Each item has a trigger header that reveals its panel with an animated height transition.

## Import

```tsx
import { Accordion } from "chunks-ui";
```

## Basic Usage

```tsx
<Accordion.Root>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger>What is chunks-ui?</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>
      <div className="pb-4">A personal React component library.</div>
    </Accordion.Panel>
  </Accordion.Item>
  <Accordion.Item value="item-2">
    <Accordion.Header>
      <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>
      <div className="pb-4">Yes — keyboard nav and ARIA handled by Base UI.</div>
    </Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

## Multiple Open Items

By default only one item can be open at a time. Set `multiple` to allow expanding several items simultaneously:

```tsx
<Accordion.Root multiple>
  {/* items */}
</Accordion.Root>
```

## Default Open

Pass an array of item values to `defaultValue` to start with those items expanded:

```tsx
<Accordion.Root defaultValue={["item-1"]}>
  {/* items */}
</Accordion.Root>
```

## Controlled

`Accordion.Root` infers the type of an item's value from `value` or `defaultValue` (arrays of it), so a typed `useState` setter is an `onValueChange`:

```tsx
function ControlledAccordion() {
  const [value, setValue] = useState<string[]>([]);

return (
    <Accordion.Root value={value} onValueChange={setValue}>
      <Accordion.Item value="item-1">
        <Accordion.Header>
          <Accordion.Trigger>Section</Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Panel>
          <div className="pb-4">Content</div>
        </Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  );
}
```

## Disabled Item

Set `disabled` on `Accordion.Item` to prevent it from being opened:

```tsx
<Accordion.Item value="item-2" disabled>
  <Accordion.Header>
    <Accordion.Trigger>Unavailable</Accordion.Trigger>
  </Accordion.Header>
  <Accordion.Panel>
    <div className="pb-4">Unreachable content.</div>
  </Accordion.Panel>
</Accordion.Item>
```

## Animation

The panel height animates using CSS transitions via Base UI's `--accordion-panel-height` CSS variable. No JavaScript animation library is required. To opt out, override the `transition` class on `Accordion.Panel`.

Respects `prefers-reduced-motion` — with reduced motion enabled the panel and chevron don't transition.

## Compound Parts

| Part | Description |
|---|---|
| `Accordion.Root` | State container. Manages which items are open. |
| `Accordion.Item` | Wraps a single collapsible section. Requires a unique `value`. |
| `Accordion.Header` | Semantic `<h3>` wrapper around the trigger. |
| `Accordion.Trigger` | Clickable button that toggles the panel. Includes the chevron icon. |
| `Accordion.Panel` | The collapsible content area. Animates height on open/close. |

## Props

All compound parts accept the same props as their underlying Base UI [`Accordion`](https://base-ui.com/react/components/accordion#api-reference) counterparts. No additional custom props are defined.

---

# Avatar

Displays a user avatar image with automatic fallback to initials. Supports numeric sizing and multiple shapes. Built on Base UI's [`Avatar`](https://base-ui.com/react/components/avatar).

## Import

```tsx
import { Avatar } from 'chunks-ui'
```

## Basic Usage

With an image:

```tsx
<Avatar src="/jane.jpeg" alt="Jane Doe" />
```

Without an image (shows initials derived from `alt`):

```tsx
<Avatar alt="Jane Doe" />
```

This renders "JD" as fallback initials.

The initials also show while the image loads and if it fails to load (a 404, a blocked or expired URL), so a broken image never shows.

## Custom Fallback

Override the auto-generated initials with the `fallback` prop:

```tsx
<Avatar fallback="?" />
<Avatar alt="John Doe" fallback="J" />
<Avatar alt="John Doe" fallback="J" src={'/bro2.jpeg'}/>
```

## Sizes

The `size` prop accepts a numeric value in pixels:

<div className="flex items-center justify-between max-w-lg mx-auto">
  {[10, 20, 30, 40, 50, 60, 100].map(size => (
    <div className="grid grid-rows-2 gap-x-10 gap-y-5 items-center h-[200px]" key={size}>
      <p className="mx-auto">{size}px</p>
      <Avatar src={'/jane.jpeg'} size={size} className="self-center" />
    </div>
  ))}

## Shapes

```tsx
<Avatar alt="User" shape="circle" src="/bro.jpeg" size={50} />
<Avatar alt="User" shape="rounded" src="/bro.jpeg" size={50} />
<Avatar alt="User" shape="square" src="/bro.jpeg" size={50} />
```

## Initials Generation

When there is no image to show (no `src`, or it is loading or failed) and no `fallback` is set, initials are automatically generated from the `alt` text:

- `"Jane Doe"` produces `"JD"`
- `"Alice B. Charlie"` produces `"AB"` (first two initials)
- Single word `"Admin"` produces `"A"`

## Accessibility

`alt` names the avatar. With a loaded image, the name is the image's alt text. Without one, the initials are exposed as an image (`role="img"`) labelled with `alt`, so screen readers announce "Jane Doe", not "JD". Without `alt`, the avatar is decorative and hidden from assistive technology.

Next to a visible name, omit `alt` and pass the initials as `fallback`, so the name isn't announced twice:

```tsx
<Avatar fallback="JD" />
<span>Jane Doe</span>
```

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<AvatarProps, 'src' | 'alt' | 'fallback' | 'size' | 'shape'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<span>` element.

---

# Breadcrumb

A navigation aid showing the user's location within a page hierarchy. Uses semantic HTML (`<nav>`, `<ol>`, `<li>`) with proper ARIA attributes.

## Import

```tsx
import { Breadcrumb } from "chunks-ui";
```

## Basic Usage

```tsx
<Breadcrumb.Root>
  <Breadcrumb.List>
    <Breadcrumb.Item>
      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
    </Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item>
      <Breadcrumb.Link href="/collections">Collections</Breadcrumb.Link>
    </Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item>
      <Breadcrumb.Page>Citadel Base White</Breadcrumb.Page>
    </Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>
```

## Collapsed Breadcrumb

Use `Breadcrumb.Ellipsis` to indicate hidden intermediate levels:

```tsx
<Breadcrumb.Item>
  <Breadcrumb.Ellipsis />
</Breadcrumb.Item>
```

## Custom Separator

Pass children to `Breadcrumb.Separator` to replace the default chevron icon:

```tsx
<Breadcrumb.Separator>/</Breadcrumb.Separator>
```

## Custom Link Component

Use the `render` prop on `Breadcrumb.Link` to render a framework-specific link (e.g. React Router, Next.js):

```tsx
<Breadcrumb.Link render={<Link to="/paints" />}>Paints</Breadcrumb.Link>
```

## Compound Parts

| Part | Description |
|---|---|
| `Breadcrumb.Root` | `<nav>` wrapper named "Breadcrumb". Takes `labels` for the parts' built-in text. |
| `Breadcrumb.List` | Ordered list (`<ol>`) containing items. |
| `Breadcrumb.Item` | List item (`<li>`) wrapping a link or page. |
| `Breadcrumb.Link` | Clickable anchor. Accepts `render` prop for custom link components. |
| `Breadcrumb.Page` | Current page indicator with `aria-current="page"`. |
| `Breadcrumb.Separator` | Decorative separator. Renders its own `<li>`, so place it between items, not inside one. Defaults to a chevron icon. |
| `Breadcrumb.Ellipsis` | Collapsed state indicator (three dots). Screen readers read "More" (`labels.ellipsis`) in its place. Children you pass replace the dots; screen readers read them too, so give a decorative icon `aria-hidden`. |

## Breadcrumb.Root Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<BreadcrumbRootProps, 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<nav>` element.

## Breadcrumb.Link Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<BreadcrumbLinkProps, 'render'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<a>` element (or the custom element provided via `render`).

## Breadcrumb.Separator Props

All props are forwarded to the underlying `<li>` element. Pass `children` to replace the default chevron separator icon.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_BREADCRUMB_LABELS`. `aria-label` on `Breadcrumb.Root` takes precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default BreadcrumbLabels
`
  })}
/>

---

# Button

A styled button component built on Base UI's `Button` primitive. Supports multiple visual variants, semantic colors, loading state, and start/end icons.

## Import

```tsx
import { Button } from 'chunks-ui'
```

## Basic Usage

```tsx
<Button>Click me</Button>
```

## Variants

The `variant` prop controls the visual style:

```tsx
<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="text">Text</Button>
```

## Colors

The `color` prop sets the semantic color:

```tsx
<Button color="primary">Primary</Button>
<Button color="destructive">Destructive</Button>
<Button color="success">Success</Button>
<Button color="warning">Warning</Button>
<Button color="secondary">Secondary</Button>
```

Colors work with all variants:

```tsx
<Button variant="outlined" color="destructive">Delete</Button>
<Button variant="text" color="success">Approve</Button>
```

## Loading State

When `loading` is `true`, the button shows a `Loader` spinner in place of the `startIcon` and becomes disabled:

```tsx
<Button loading>Saving...</Button>
```

The button remains focusable while loading (for accessibility) but click events are suppressed.

## Icons

```tsx
<Button startIcon={<PlusIcon />}>Add Item</Button>
<Button endIcon={<ArrowRightIcon />}>Next</Button>
```

Icons are hidden during loading state. The `startIcon` slot is replaced by the `Loader`.

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ButtonProps, 'variant' | 'color' | 'loading' | 'startIcon' | 'endIcon'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Button`](https://base-ui.com/react/components/button#api-reference).

---

# Calendar

A standalone date picker grid built without an external primitive. Supports controlled and uncontrolled selection, min/max bounds, and custom disabled-date predicates.

## Import

```tsx
import { Calendar } from "chunks-ui";
```

## Basic Usage

```tsx
<Calendar />
```

## Controlled

```tsx
function ControlledCalendar() {
  const [date, setDate] = useState<Date | null>(null);

return (
    <Calendar value={date} onValueChange={setDate} />
  );
}
```

When `value` changes to another day, the calendar shows that day's month. A re-render with the same day, such as an inline `value={new Date()}`, keeps the month the user moved to. The same rule means that setting a new `Date` for the day that is already selected does not move the view back, so a "Today" button does nothing visible while today is selected and the user is on another month. To show the month again, control the month: see [Shown Month](#shown-month).

## Shown Month

The calendar opens on the month of the selected day, else today's, and the arrows and keys move it. To control the shown month, pass `month`, any date in that month, and `onMonthChange`. `onMonthChange` gets the first day of the month the user moves to, at local midnight: by the arrows, by a key that moves focus out of the shown month, or by a click on a day from a neighbouring month. The view then waits for a new `month`. If you keep the month, a key that would leave it leaves focus where it is. When the new `month` comes later, for example from a transition, focus moves with the view to the day the key moved to. If you set another month instead, for example to keep the view inside a range, focus goes to that month's Tab stop.

```tsx
function MonthCalendar() {
  const [date, setDate] = useState<Date | null>(null);
  const [month, setMonth] = useState(() => new Date());

return (
    <>
      <Button
        onClick={() => {
          const today = new Date();
          setDate(today);
          setMonth(today);
        }}
      >
        Today
      </Button>
      <Calendar value={date} onValueChange={setDate} month={month} onMonthChange={setMonth} />
    </>
  );
}
```

With `month`, a new `value` does not move the view: set `month` too, as the Today button does. An Invalid Date, or a date before year 1, as `month` shows the selected day's month, else today's.

Without `month`, `onMonthChange` still tells you when the user moves to another month, for example to load that month's data. A new `value` that moves the view does not call it.

```tsx
function MonthChangeCalendar() {
  const [moved, setMoved] = useState<Date | null>(null);

return (
    <>
      <Calendar onMonthChange={setMoved} />
      <p>
        {moved
          ? `Moved to ${moved.toLocaleDateString("en-US", { month: "long", year: "numeric" })}`
          : "No month change yet"}
      </p>
    </>
  );
}
```

## Disabled Dates

Use `min`/`max` to set a date range, or `isDateDisabled` to disable individual dates with a predicate:

```tsx
const today = new Date();
const isWeekend = (date: Date) => date.getDay() === 0 || date.getDay() === 6;

<Calendar
  min={today}
  isDateDisabled={isWeekend}
/>
```

A disabled day is dimmed and shows the not-allowed cursor.

## Week Start and Outside Days

`weekStartsOn` sets the first column of the week: `0` is Sunday (the default), `1` is Monday. `showOutsideDays` fills the empty cells before the 1st and after the last day of the month with dimmed days from the neighbouring months. Clicking one of them selects it and shows its month. They are never Tab stops. In forced-colors mode, such as a Windows contrast theme, they take the system colour for dimmed text (`GrayText`); there, the selected day takes the system highlight (`Highlight`), today is underlined in place of its ring, and a disabled day is struck through in `GrayText` at full opacity, so it differs from an outside day.

```tsx
<Calendar weekStartsOn={1} showOutsideDays />
```

## Keyboard

The day grid follows the keyboard pattern of the [WAI-ARIA date picker example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/). It has one Tab stop: the selected day if it is in the shown month, else today, else the 1st of the month. After you move with the keys, the day you moved to becomes the Tab stop. Days from neighbouring months (`showOutsideDays`) are never Tab stops.

| Key | Moves focus to |
| --- | --- |
| <kbd>←</kbd> / <kbd>→</kbd> | The previous / next day |
| <kbd>↑</kbd> / <kbd>↓</kbd> | The same weekday in the previous / next week |
| <kbd>Home</kbd> / <kbd>End</kbd> | The first / last day of the week, following `weekStartsOn` |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | The same day in the previous / next month |
| <kbd>Shift</kbd> + <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | The same day in the previous / next year |

Disabled days (`min`, `max`, `isDateDisabled`) can take focus, and screen readers announce them as unavailable. Arrow keys do not skip them, but Enter, Space and clicks do not select them.

The left and right arrows are not mirrored in right-to-left layouts.

## Calendar Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<CalendarProps, 'value' | 'defaultValue' | 'onValueChange' | 'month' | 'onMonthChange' | 'isDateDisabled' | 'min' | 'max' | 'weekStartsOn' | 'showOutsideDays' | 'labels'>
export default Props
`
  })}
/>

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_CALENDAR_LABELS`. The keys that depend on a date are functions of that date, so you can pass `Intl` formatters. They get the date at local midnight: format it in the local time zone, not with `timeZone: "UTC"`. A server component can't pass functions, so set them in a client component. See [Labels](/labels).

Each column header shows `weekday` and screen readers read `weekdayLong`; set both when you translate them (see [Labels](/labels)).

<TSDoc
  definition={generateDefinition({
    code: `

export default CalendarLabels
`
  })}
/>

---

# Card

A compound layout component for displaying grouped content. Built with plain HTML elements (no Base UI dependency). Follows the compound pattern: `Card.Root`, `Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, `Card.Footer`.

## Import

```tsx
import { Card } from "chunks-ui";
```

## Basic Usage

```tsx
<Card.Root>
  <Card.Header>
    <Card.Title>Project Alpha</Card.Title>
    <Card.Description>A brief description of the project.</Card.Description>
  </Card.Header>
  <Card.Content>
    <p>Main content goes here.</p>
  </Card.Content>
  <Card.Footer>
    <Button variant="outlined" color="secondary">Cancel</Button>
    <Button>Save</Button>
  </Card.Footer>
</Card.Root>
```

## Minimal Card

You can use any subset of compound parts. Each one gets the same padding from the edges of the card:

```tsx
<Card.Root>
  <Card.Content>
    <p>Simple card with content only.</p>
  </Card.Content>
</Card.Root>
```

## With Custom Content

```tsx
<Card.Root className="max-w-sm">
  <Card.Header>
    <Card.Title>Team Members</Card.Title>
    <Card.Description>Manage your team members and roles.</Card.Description>
  </Card.Header>
  <Card.Content>
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-3">
        <Avatar fallback="AJ" size={32} />
        <div>
          <p className="text-sm font-medium">Alice Johnson</p>
          <p className="text-xs text-muted-foreground">Admin</p>
        </div>
      </div>
      <div className="flex items-center gap-3">
        <Avatar fallback="BS" size={32} />
        <div>
          <p className="text-sm font-medium">Bob Smith</p>
          <p className="text-xs text-muted-foreground">Member</p>
        </div>
      </div>
    </div>
  </Card.Content>
  <Card.Footer>
    <Button>Invite Member</Button>
  </Card.Footer>
</Card.Root>
```

## Styling

- **No shadow.** `Card.Root` has a border and a background, and no shadow. To add one, pass a class: `<Card.Root className="shadow-md">`.
- **Spacing comes from the root.** `Card.Root` is a flex column with `py-6` and `gap-6`. `Card.Header`, `Card.Content` and `Card.Footer` have only `px-6`. So the content of any subset of parts is 24px from every edge, with 24px between parts (6 spacing units at the default `--spacing`).
- **Dividers.** A `Card.Header` with `border-b` gets `pb-6`, and a `Card.Footer` with `border-t` gets `pt-6`, so the border sits 24px from the text. To change that padding, use the same variant, for example `[.border-b]:pb-4`. A plain `pb-4` loses to it. Only the exact `border-b` and `border-t` classes trigger this; with `border-b-2`, `border-y` or `border`, add the padding yourself.
- **Upgrading.** A card that starts with `Card.Header` looks the same as before. Every child of the root is now a flex item, and padding on the parts or `space-y-*` on the root adds to the root's `py-6` and `gap-6`. The changelog lists each case.

To change the spacing, set the vertical padding and the gap on the root, and the horizontal padding on the parts:

```tsx
<Card.Root className="gap-4 py-4">
  <Card.Content className="px-4">
    <p>Tighter card.</p>
  </Card.Content>
</Card.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Card.Root` | Outer container. Rounded border and background, no shadow. Vertical flex with `gap-6 py-6`. |
| `Card.Header` | Top section. Vertical flex with `gap-1.5 px-6`, and `pb-6` when it has `border-b`. |
| `Card.Title` | Heading rendered as `<h3>`. Semibold, tight tracking. |
| `Card.Description` | Subtext below the title. `text-muted-foreground`. |
| `Card.Content` | Main body area. Padding `px-6`. |
| `Card.Footer` | Bottom section. Horizontal flex with `gap-2 px-6`, and `pt-6` when it has `border-t`. |

## Props

All compound parts accept standard HTML `div` props (or `h3`/`p` for Title/Description) plus `className` for additional styling. There are no component-specific variant props.

---

# Checkbox

A styled checkbox built on Base UI's `Checkbox` primitive. Supports checked, unchecked, and indeterminate states with a compound component pattern.

## Import

```tsx
import { Checkbox } from "chunks-ui";
```

## Basic Usage

```tsx
<Checkbox.Root aria-label="Accept terms">
  <Checkbox.Indicator />
</Checkbox.Root>
```

A checkbox without a visible label needs an `aria-label`. To show a label, use `Field` as below.

## With Label

Use the `Field` component to associate a label:

```tsx
<Field.Root>
  <div className="flex items-center gap-2">
    <Checkbox.Root>
      <Checkbox.Indicator />
    </Checkbox.Root>
    <Field.Label>Accept terms and conditions</Field.Label>
  </div>
</Field.Root>
```

## Controlled

```tsx
function ControlledCheckbox() {
  const [checked, setChecked] = useState(false);

return (
    <Checkbox.Root checked={checked} onCheckedChange={setChecked} aria-label="Subscribe">
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}
```

## Indeterminate State

The indeterminate state is used for "select all" patterns where some items are checked. Set the `indeterminate` prop (`checked` takes only a boolean):

```tsx
<Checkbox.Root indeterminate aria-label="Select all">
  <Checkbox.Indicator />
</Checkbox.Root>
```

## Disabled

```tsx
<Checkbox.Root disabled aria-label="Unavailable option">
  <Checkbox.Indicator />
</Checkbox.Root>
```

## Touch Target

The box is 16px. To make it easier to tap, add [`touch-target`](/utilities#touch-target) to `Checkbox.Root`: the hit area grows to 44×44px, and the box's size and the layout stay the same. A [label](#with-label) is pressable too, so it also makes the target larger. In a stacked list, keep rows at least the area size apart centre to centre, or let the label enlarge the target instead: overlapping areas send presses to the next row.

```tsx
<Checkbox.Root aria-label="Accept terms" className="touch-target">
  <Checkbox.Indicator />
</Checkbox.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Checkbox.Root` | The checkbox control. Handles checked state and keyboard interaction. |
| `Checkbox.Indicator` | Renders the check, or the minus when indeterminate, inside the root. Children you pass replace them; with a `render` element and no children, there is neither, and the element may be a void element such as `<img>`. Your content scales and fades in and out as the check does; the morph between the check and the minus belongs to the default icon. |

## Props

All compound parts accept the same props as their underlying Base UI [`Checkbox`](https://base-ui.com/react/components/checkbox#api-reference) counterparts. No additional custom props are defined.

---

# Chip

A small label/tag component with optional remove functionality. Uses the `ClearButton` component internally for the dismiss action.

## Import

```tsx
import { Chip } from "chunks-ui";
```

## Basic Usage

```tsx
<Chip>Default</Chip>
```

## Colors

```tsx
<Chip color="primary">Primary</Chip>
<Chip color="destructive">Destructive</Chip>
<Chip color="success">Success</Chip>
<Chip color="warning">Warning</Chip>
<Chip color="secondary">Secondary</Chip>
```

Each color applies a light tinted background with matching text and border (e.g. `bg-primary/10 text-primary-text border-primary/30`).

## Variants

The `variant` prop controls the fill style:

```tsx
<Chip variant="contained" color="primary">Contained</Chip>
<Chip variant="outlined" color="primary">Outlined</Chip>
```

The `outlined` variant removes the background fill, keeping only the border and text color.

## Removable Chip

Pass an `onRemove` callback to show a close button:

```tsx
function TagList() {
  const [tags, setTags] = useState(["React", "TypeScript", "Tailwind"]);

return (
    <div className="flex gap-2">
      {tags.map((tag) => (
        <Chip
          key={tag}
          onRemove={() => setTags((prev) => prev.filter((t) => t !== tag))}
        >
          {tag}
        </Chip>
      ))}
    </div>
  );
}
```

The remove button reads its label and then the chip's text, for example "Remove React". To put the chip's text first, mark its place with `{chip}`: `labels={{ remove: "{chip} を削除" }}` reads "React を削除". See [Labels](/labels#remove-buttons).

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ChipProps, 'onRemove' | 'color' | 'variant' | 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<span>` element.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_CHIP_LABELS`. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default ChipLabels
`
  })}
/>

---

# ClearButton

A small circular icon button for clearing or dismissing values. Used internally by `Input` (via `onClear`) and `Chip` (via `onRemove`), but also exported for direct use.

## Import

```tsx
import { ClearButton } from 'chunks-ui'
```

## Basic Usage

```tsx
<ClearButton onClick={() => console.log('Cleared')} />
```

## Custom Label

Use `labels` to replace the default accessible name, "Clear":

```tsx
<ClearButton labels={{ clear: "Remove tag" }} />
```

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ClearButtonProps, 'label' | 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<button>` element. Children you pass replace the X icon, and the button keeps its `aria-label`. If the children are visible text, pass an `aria-label` that contains it: with the default one, `<ClearButton>Clear all</ClearButton>` is announced "Clear".

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_CLEAR_BUTTON_LABELS`. `aria-label` and the deprecated `label` take precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default ClearButtonLabels
`
  })}
/>

## Styling

The button renders at `size-6` (24px) with a rounded-full shape. It shows `text-muted-foreground` by default. On hover the icon turns `text-destructive-text` over a faint `bg-destructive/5` background, and the button grows slightly (`hover:scale-105`). While `disabled` it shows the not-allowed cursor and its hover and press feedback stay off.

To make it easier to tap, add [`touch-target`](/utilities#touch-target): the hit area grows to 44×44px, and the button's size and the layout stay the same.

```tsx
<ClearButton className="touch-target" />
```

---

# Collapsible

A single togglable section built on Base UI's `Collapsible` primitive. For multiple collapsible sections with exclusive selection, use `Accordion` instead.

## Import

```tsx
import { Collapsible } from "chunks-ui";
```

## Basic Usage

```tsx
<Collapsible.Root>
  <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
  <Collapsible.Panel>
    <div className="pb-4">Hidden content revealed on click.</div>
  </Collapsible.Panel>
</Collapsible.Root>
```

## Default Open

Set `defaultOpen` to render the panel expanded on first mount:

```tsx
<Collapsible.Root defaultOpen>
  <Collapsible.Trigger className="group flex items-center gap-1.5">
    Shipping information
    <ChevronRightIcon className="size-4 rotate-0 group-data-panel-open:rotate-90" />
  </Collapsible.Trigger>
  <Collapsible.Panel>...</Collapsible.Panel>
</Collapsible.Root>
```

The chevron rotation uses Base UI's `data-panel-open` attribute — see [Styling with data attributes](#styling-with-data-attributes) below.

## Controlled

Use `open` and `onOpenChange` for controlled state:

```tsx
const [open, setOpen] = useState(false);

<Collapsible.Root open={open} onOpenChange={setOpen}>
  <Collapsible.Trigger>Advanced settings</Collapsible.Trigger>
  <Collapsible.Panel>...</Collapsible.Panel>
</Collapsible.Root>
```

## Animation

The panel height animates using CSS transitions via Base UI's `--collapsible-panel-height` CSS variable, matching the Accordion animation pattern. No JavaScript animation library is required.

## Compound Parts

| Part | Description |
|---|---|
| `Collapsible.Root` | State container. Manages open/closed state. |
| `Collapsible.Trigger` | Button that toggles the panel. |
| `Collapsible.Panel` | Collapsible content area with animated height. |

## Styling with data attributes

Base UI exposes data attributes on each part that you can target with Tailwind's `data-*` variant — no JavaScript state needed.

### Trigger

The Trigger receives `data-panel-open` when the panel is expanded. Combine it with Tailwind's `group` utility to style child elements:

```tsx
<Collapsible.Trigger className="group flex items-center gap-1.5">
  Details
  <ChevronRightIcon className="size-4 transition-transform group-data-panel-open:rotate-90" />
</Collapsible.Trigger>
```

### Panel

The Panel exposes `data-open`, `data-closed`, `data-starting-style`, and `data-ending-style`:

```tsx
<Collapsible.Panel
  className="h-(--collapsible-panel-height) data-starting-style:h-0 data-ending-style:h-0"
/>
```

| Attribute | Part | Present when |
|---|---|---|
| `data-panel-open` | Trigger | Panel is open |
| `data-open` | Panel | Panel is open |
| `data-closed` | Panel | Panel is closed |
| `data-starting-style` | Panel | Entering (animating in) |
| `data-ending-style` | Panel | Exiting (animating out) |

### CSS variables

| Variable | Description |
|---|---|
| `--collapsible-panel-height` | Computed height of the panel content |
| `--collapsible-panel-width` | Computed width of the panel content |

## Props

All compound parts accept the same props as their underlying Base UI [`Collapsible`](https://base-ui.com/react/components/collapsible#api-reference) counterparts. No additional custom props are defined.

---

# Combobox

A styled autocomplete/combobox built on Base UI's `Combobox` primitive. Includes text input with built-in filtering, popup with items, grouped options, multi-select with chips, and built-in Floating UI positioning.

## Import

```tsx
import { Combobox } from "chunks-ui";
```

## Basic Usage

```tsx
const fruits = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "cherry", label: "Cherry" },
];

<Combobox.Root items={fruits}>
  <div className="relative">
    <Combobox.Input placeholder="Search a fruit..." aria-label="Fruit" />
    <Combobox.Trigger />
  </div>
  <Combobox.Portal>
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.List>
          {(item) => (
            <Combobox.Item key={item.value} value={item}>
              {item.label}
              <Combobox.ItemIndicator />
            </Combobox.Item>
          )}
        </Combobox.List>
        <Combobox.Empty>No results found.</Combobox.Empty>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>
```

`Combobox.Empty` shows when no item matches the input. Set `items` (or `filteredItems`) on `Combobox.Root`, or it always shows.

Pass each item object as the `Combobox.Item` `value`. Base UI shows an object's `label` in the input and submits its `value` with a form, so picking "Banana" fills the input with "Banana". For other object shapes, set `itemToStringLabel` (and `itemToStringValue` for forms) on `Combobox.Root`. If you pass the selected value in from elsewhere (`value`/`defaultValue`) and it isn't the same object as the item, set `isItemEqualToValue`.

## With Clear Button

```tsx
<Combobox.Root items={fruits}>
  <div className="relative">
    <Combobox.Input placeholder="Search a fruit..." aria-label="Fruit" />
    <Combobox.Clear />
    <Combobox.Trigger />
  </div>
  <Combobox.Portal>
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.List>
          {(item) => (
            <Combobox.Item key={item.value} value={item}>
              {item.label}
              <Combobox.ItemIndicator />
            </Combobox.Item>
          )}
        </Combobox.List>
        <Combobox.Empty>No results found.</Combobox.Empty>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>
```

## Grouped Options

Pass groups (`{ value, items }`) as `items`. `Combobox.List` then calls its child once per group, with only the group's matching items, and hides empty groups while filtering:

```tsx
const colors = [
  {
    value: "Warm",
    items: [
      { value: "red", label: "Red" },
      { value: "orange", label: "Orange" },
      { value: "yellow", label: "Yellow" },
    ],
  },
  {
    value: "Cool",
    items: [
      { value: "blue", label: "Blue" },
      { value: "green", label: "Green" },
      { value: "purple", label: "Purple" },
    ],
  },
];

<Combobox.Root items={colors}>
  <div className="relative">
    <Combobox.Input placeholder="Pick a color..." aria-label="Color" />
    <Combobox.Trigger />
  </div>
  <Combobox.Portal>
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.List>
          {(group: (typeof colors)[number]) => (
            <Combobox.Group key={group.value} items={group.items}>
              <Combobox.GroupLabel>{group.value}</Combobox.GroupLabel>
              {group.items.map((item) => (
                <Combobox.Item key={item.value} value={item}>
                  {item.label}
                  <Combobox.ItemIndicator />
                </Combobox.Item>
              ))}
            </Combobox.Group>
          )}
        </Combobox.List>
        <Combobox.Empty>No results found.</Combobox.Empty>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>
```

## Multi-Select with Chips

```tsx
type Framework = { value: string; label: string };

function MultiSelectCombobox() {
  const [value, setValue] = useState<Framework[]>([]);

return (
    <Combobox.Root multiple items={frameworks} value={value} onValueChange={setValue}>
      <Combobox.Control>
        <Combobox.Chips>
          {value.map((item) => (
            <Combobox.Chip key={item.value}>
              {item.label}
              <Combobox.ChipRemove />
            </Combobox.Chip>
          ))}
          <Combobox.Input
            className="h-7 min-w-20 flex-1 border-0 bg-transparent px-0"
            placeholder="Select frameworks..."
            aria-label="Frameworks"
          />
        </Combobox.Chips>
        <Combobox.Clear />
        <Combobox.Trigger />
      </Combobox.Control>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.List>
              {(item) => (
                <Combobox.Item key={item.value} value={item}>
                  {item.label}
                  <Combobox.ItemIndicator />
                </Combobox.Item>
              )}
            </Combobox.List>
            <Combobox.Empty>No results found.</Combobox.Empty>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

Put `Combobox.Input` inside `Combobox.Chips`, after the chips. Only there does the keyboard reach the chips: ArrowLeft (ArrowRight in a right-to-left layout) at the start of the input focuses the last chip, and Backspace in an empty input removes it.

## Trigger with Search

A select with a search field: `Combobox.Trigger` is a button that shows `Combobox.Value`, and `Combobox.Input` sits inside the popup.

```tsx
<Combobox.Root items={fruits}>
  <Combobox.Trigger
    aria-label="Favorite fruit"
    className="static h-ui-height w-full rounded-md border border-input bg-background px-3 text-sm max-md:text-base md:[@media(pointer:coarse)]:text-base focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
  >
    <Combobox.Value placeholder="Pick a fruit" />
    <Combobox.Icon />
  </Combobox.Trigger>
  <Combobox.Portal>
    <Combobox.Positioner>
      <Combobox.Popup aria-label="Fruits" className="flex flex-col overflow-hidden">
        <Combobox.Input
          placeholder="Search..."
          aria-label="Search fruits"
          className="mb-1 shrink-0 pe-3"
        />
        <Combobox.List className="min-h-0 overflow-y-auto overscroll-contain scroll-py-1">
          {(item) => (
            <Combobox.Item key={item.value} value={item}>
              {item.label}
              <Combobox.ItemIndicator />
            </Combobox.Item>
          )}
        </Combobox.List>
        <Combobox.Empty>No results found.</Combobox.Empty>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>
```

`Combobox.Trigger`'s default classes put a chevron over the end of an input: `absolute inset-y-0 end-0 flex items-center pe-2`. `cn` merges your `className` over them, so `static` replaces `absolute` (which leaves `inset-y-0 end-0` without effect) and `px-3` replaces `pe-2`. The other classes draw the field, its text size and its focus ring as on `Select.Trigger`.

In the popup, `pe-3` replaces the end padding (`pe-12`) that `Combobox.Input` keeps for the buttons over its end. `Combobox.Popup` scrolls as a whole, so in a long list the search input would scroll out of view: `flex flex-col overflow-hidden` stops the popup scrolling, `shrink-0` keeps the input's height, and `min-h-0 overflow-y-auto` makes `Combobox.List` scroll below the input instead.

With children, `Combobox.Trigger` loses its default name, "Show options", and the value it shows does not name it either: with the input inside the popup, Base UI gives the trigger the `combobox` role, which takes no name from its content. Pass an `aria-label`, as here, or put the Combobox in `Field.Root` with a `Field.Label`. With the input inside, the popup is a `dialog`, so name it too, with an `aria-label` on `Combobox.Popup`.

## Controlled

```tsx
type Status = { value: string; label: string };

const statuses: Status[] = [
  { value: "active", label: "Active" },
  { value: "inactive", label: "Inactive" },
  { value: "pending", label: "Pending" },
];

function ControlledCombobox() {
  const [value, setValue] = useState<Status | null>(null);

return (
    <Combobox.Root items={statuses} value={value} onValueChange={setValue}>
      <div className="relative">
        <Combobox.Input placeholder="Select status..." aria-label="Status" />
        <Combobox.Clear />
        <Combobox.Trigger />
      </div>
      <Combobox.Portal>
        <Combobox.Positioner>
          <Combobox.Popup>
            <Combobox.List>
              {(item) => (
                <Combobox.Item key={item.value} value={item}>
                  {item.label}
                  <Combobox.ItemIndicator />
                </Combobox.Item>
              )}
            </Combobox.List>
            <Combobox.Empty>No results found.</Combobox.Empty>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`): the `popup` spring (`springs.popup`) with Motion installed, a CSS transition of `opacity` and `scale` without it; reduced motion turns off both. The popup grows out of its trigger (`origin-(--transform-origin)`); a `className` such as `origin-top` replaces it.

`render` on `Combobox.Popup` replaces the element the spring animates, so a popup with `render` uses the CSS transition even with Motion installed. To restyle the popup, pass `className`.

## Compound Parts

| Part | Description |
|---|---|
| `Combobox.Root` | State container. Manages open/close, filtering, and selected value(s). |
| `Combobox.Control` | Bordered wrapper for multi-select (chips + input): Base UI's `Combobox.InputGroup`, a `role="group"` (pass `aria-label` to name it). The popup anchors to it, and a press on its padding focuses the input and opens the popup, unless `openOnInputClick` is false. `Combobox.Clear` and `Combobox.Trigger` sit over its end: its end padding (`pe-12`) keeps the chips and the input's text out from under them. A `px-*` or `p-*` class, with or without a variant such as `md:`, replaces it: add `pe-12` back. Draws the focus ring (`has-[:focus-visible]`) while the input or a chip inside it has keyboard focus, and turns off the ring of its combobox input, so one ring shows; a focused chip also draws its own. |
| `Combobox.Input` | Text input with built-in filtering. In a single-select, `Combobox.Clear` and `Combobox.Trigger` sit over its end: its end padding (`pe-12`) keeps the text out from under them. A `px-*` or `p-*` class, with or without a variant such as `md:`, replaces it: add `pe-12` back. Inside `Combobox.Chips`, the example's `px-0` removes it, and the Control's end padding keeps the text clear instead. A placeholder cut at the end of the text box ends in an ellipsis (`placeholder-shown:text-ellipsis`), except while the input has focus in Chromium browsers and Safari, which cut it; a cut value has no ellipsis. `placeholder-shown:text-clip` in `className` removes the ellipsis; a plain `text-clip` does not, because the `:placeholder-shown` rule is more specific. |
| `Combobox.Trigger` | Button that toggles the popup. Renders a default chevron icon, named "Show options". Children or a `render` element replace both the chevron and the name: see Accessible Names below. At most as wide as its container (`max-w-full`), and it shrinks in a flex row (`min-w-0`); `max-w-none` lifts the cap. |
| `Combobox.Icon` | Chevron icon, usable standalone outside the trigger. Children you pass replace the chevron. With a `render` element and no children, there is no chevron: the element draws its own, and may be a void element such as `<img>`. |
| `Combobox.Portal` | Renders the popup in a portal. |
| `Combobox.Positioner` | Handles Floating UI positioning. Default `sideOffset={8}`, as on `Popover.Content` and `Menu.Content`: the input's focus ring, 4px outside its edge, stays clear of the popup. A `sideOffset` you pass replaces it, so `sideOffset={0}` opens the popup flush against the input, or against the trigger when the input is inside the popup. Inside a `Combobox.Control` the popup anchors to the Control: it is as wide as the Control and opens 8px below the Control's border. |
| `Combobox.Popup` | The dropdown panel containing items. It is as wide as the input, as the `Combobox.Control` in a multi-select, or as the trigger when `Combobox.Input` is inside the popup. Item text wraps to that width, and a word longer than the popup breaks. Scrolls when the items need more than the space between the input (or that trigger) and the viewport edge. |
| `Combobox.List` | List container. Takes a function child that renders each matching item (or each group, when `items` holds groups). |
| `Combobox.Item` | An individual selectable option. Its text wraps, and a word longer than the popup breaks; give an icon, badge or shortcut beside the text `shrink-0`, or it is squeezed. |
| `Combobox.ItemIndicator` | Checkmark shown for the selected item. Children you pass replace the checkmark. With a `render` element and no children, there is no checkmark: the element draws its own, and may be a void element such as `<img>`. The indicator is `aria-hidden`, so screen readers skip its children and announce the option's selected state instead. |
| `Combobox.Empty` | Message displayed when no items match the filter. Needs `items` on Root. |
| `Combobox.Clear` | Button that clears the current value. Renders a default X icon. Children you pass replace the X; with a `render` element and no children, there is no X. The button keeps its name, "Clear selection", whatever its content: if the children are visible text, pass an `aria-label` that contains it. |
| `Combobox.Group` | Groups related items together. |
| `Combobox.GroupLabel` | Label for a group of items. |
| `Combobox.Chips` | Container for selected chips in multi-select mode: a wrapping row with a 4px gap between the chips (`gap-1`; `className` merges with it). Takes ordinary children: map the selected values to `Combobox.Chip`s, and put `Combobox.Input` after them. It fills the free width of `Combobox.Control` (`flex-1`), so an input with `flex-1`, as in the example, takes the rest of the row; `flex-initial` in `className` sizes the row by its content instead. |
| `Combobox.Chip` | A styled chip representing a selected value. Draws the focus ring when the arrow keys focus it. Arrow keys move focus from the input to a chip only when the input is inside `Combobox.Chips`. |
| `Combobox.ChipRemove` | Button to remove a chip. Renders a default X icon. Children you pass replace the X; with a `render` element and no children, there is no X. The button keeps its name, "Remove" and the chip's text, whatever its icon. Inside a chip, text children are read with the chip's text ("Remove Apple Drop"), so pass an `aria-label` with text children. |
| `Combobox.Value` | Displays the selected value, or `placeholder` while nothing is selected, in a `<span>` that stays on one line and ends in an ellipsis when the value is wider than its trigger, and fills the trigger's free space (`flex-1`, so an element beside it keeps its width); `flex-initial` in `className` sizes it by its text instead, and `whitespace-normal` brings back wrapping. In a right-to-left trigger, a long Latin value shows its last words: the line starts at the right edge, so its first words overflow on the left. `dir="auto"` on the value takes the direction from its first letter: a Latin value then shows its first words and sits at the left, and a right-to-left value stays at the right. While nothing is selected, what the `<span>` shows is muted (`text-muted-foreground`), as in `Select`: the `placeholder`, static children, and a function child's result in a single-select. To colour it yourself, use `in-data-placeholder:text-*`; `in-data-placeholder:text-inherit` keeps it in the colour around it. A plain `text-*` in `className` colours the value only: the muted colour stays beside it and wins while nothing is selected. A function child in a multi-select gets no `<span>`, so it can return the chips or the `Combobox.Chips` itself, but text it returns is neither clipped nor muted: return your own clipped element, such as `<span className="flex-1 truncate text-start">...</span>`. |
| `Combobox.Status` | Accessible status announcements for screen readers. |

## Accessible Names

`Combobox.Trigger`, `Combobox.Clear` and `Combobox.ChipRemove` show only an icon, so each one has a default name: "Show options", "Clear selection" and "Remove" followed by the text of its chip ("Remove Apple"). Pass [`labels`](#labels) to `Combobox.Root` to translate them, or `aria-label` to a part to use a different name:

```tsx
<Combobox.ChipRemove aria-label={`Deselect ${item.label}`} />
```

`Combobox.Clear` and `Combobox.ChipRemove` keep their name whatever you pass. `children` replace the X, and a `render` element with no children gets no X. If the children are visible text, pass an `aria-label` that contains it, so speech input users can say what they see.

`Combobox.Trigger` is different: it can hold content, such as the selected value. If you pass `children` or a `render` element, its default name and its chevron are not applied. Beside an input, the content you pass names the button:

```tsx
<Combobox.Trigger render={<button type="button">Choose</button>} />
```

Give icon-only content an `aria-label`.

With the input inside the popup, as in [Trigger with Search](#trigger-with-search), the trigger is a `combobox`, which takes no name from its content: give it an `aria-label` or a `Field.Label`.

Inside `Field.Root`, Base UI sets `aria-labelledby` on `Combobox.Trigger` to the field label. That label takes precedence over `aria-label`, so the default "Show options" name does not apply there.

When `Combobox.Input` is outside the popup, Base UI hides everything but the popup, the input and elements with `aria-live` from assistive technology (`aria-hidden`) while the popup is open. That includes `Combobox.Clear`, `Combobox.Trigger` and, in a multi-select, the chips and their `Combobox.ChipRemove` buttons, so a screen reader user can reach them only after the popup closes.

## Touch Targets

`Combobox.Clear` is 14px wide and `Combobox.Trigger` is 24px wide. To make the clear button easier to tap, add [`touch-target`](/utilities#touch-target) to it: its hit area grows to 44×44px, and the layout stays the same. The area also covers the last 15px of the input before the button. Keep `Combobox.Clear` before `Combobox.Trigger` in the DOM, as in the examples: the clear button's area covers part of the trigger, and DOM order makes the trigger paint above it.

```tsx
<div className="relative">
  <Combobox.Input placeholder="Search a fruit..." aria-label="Fruit" />
  <Combobox.Clear className="touch-target" />
  <Combobox.Trigger />
</div>
```

Add `touch-target` to `Combobox.Trigger` only when there is no `Combobox.Clear` next to it. Their centres are 23px apart, so the trigger's area would cover the end of the clear button, and a press there would open the popup.

## Text Size

The text of `Combobox.Input` is 16px below the `md` breakpoint (768px by default) and on a touch screen, so iOS Safari does not zoom the page when the field takes focus (it zooms into text under 16px); otherwise it is 14px, as in `Input`. With a mouse, a text-size class on `Combobox.Input`, such as `text-lg`, sets the size from `md` up. A `max-md:` class, such as `max-md:text-lg`, sets it below `md`, on a touch screen too; from `md` up on a touch screen, a `md:[@media(pointer:coarse)]:` class sets it. See [Text Size](/components/input#text-size) in `Input` for the limits.

## Props

All compound parts accept the same props as their underlying Base UI [`Combobox`](https://base-ui.com/react/components/combobox#api-reference) counterparts. `Combobox.Control` is Base UI's `Combobox.InputGroup` and accepts its props. `Combobox.Value` also takes a `<span>`'s props. `Combobox.Root` also takes `labels`:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ComboboxRootProps, 'labels'>
export default Props
`
  })}
/>

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_COMBOBOX_LABELS`. An `aria-label` on a part takes precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default ComboboxLabels
`
  })}
/>

---

# CopyButton

A button that copies a value to the clipboard and shows a brief confirmation. Transitions from a clipboard icon to a check icon on click.

## Import

```tsx
import { CopyButton } from "chunks-ui";
```

## Basic Usage

```tsx
<CopyButton value="npm install chunks-ui" />
```

## Custom Children

Use the render-prop `children` for custom content. The `copied` boolean reflects the current state:

```tsx
<CopyButton value="REF-2024-XK9">
  {({ copied }) => (
    <span className="text-xs">{copied ? "Copied!" : "Copy code"}</span>
  )}
</CopyButton>
```

## Timeout

Control how long the "copied" confirmation persists with the `timeout` prop (default 2000ms):

```tsx
<CopyButton value="text" timeout={5000} />
```

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<CopyButtonProps, 'value' | 'timeout' | 'children' | 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying [`IconButton`](/components/icon-button), so `variant` and `color` work too. They default to `text` and `secondary`. With a `render` element and no `children`, the button draws no icon: the element draws its own, and may be a void element such as `<img>`. The button keeps its default name.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_COPY_BUTTON_LABELS`. `aria-label` takes precedence and keeps one name in both states. With `children`, the button has no default name, so `labels` does not apply. The content names the button then, so icon-only `children` need an `aria-label`. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default CopyButtonLabels
`
  })}
/>

---

# Data Table

A recipe for building data tables using [TanStack Table](https://tanstack.com/table) with chunks-ui's `Table` component for styling. TanStack handles all the logic (sorting, filtering, pagination, row selection) while `Table.*` handles the look and feel.

## Dependencies

```bash
bun add @tanstack/react-table
```

## Full Example

This example shows sorting, filtering, pagination (5 rows per page) and row selection, all composed from chunks-ui primitives (`Table`, `Button`, `Input`, `Checkbox`).

## How It Works

### 1. Define Columns

Use TanStack's `ColumnDef` type. Render chunks-ui components inside `header` and `cell`:

```tsx
import { type ColumnDef } from "@tanstack/react-table";
import { Button, Checkbox } from "chunks-ui";
import { ArrowUpDown } from "lucide-react";

const columns: ColumnDef<Payment>[] = [
  {
    id: "select",
    header: ({ table }) => (
      <Checkbox.Root
        checked={table.getIsAllPageRowsSelected()}
        onCheckedChange={(checked) =>
          table.toggleAllPageRowsSelected(!!checked)
        }
      >
        <Checkbox.Indicator />
      </Checkbox.Root>
    ),
    cell: ({ row }) => (
      <Checkbox.Root
        checked={row.getIsSelected()}
        onCheckedChange={(checked) => row.toggleSelected(!!checked)}
      >
        <Checkbox.Indicator />
      </Checkbox.Root>
    ),
  },
  {
    accessorKey: "email",
    header: ({ column }) => (
      <Button
        variant="text"
        color="secondary"
        onClick={() =>
          column.toggleSorting(column.getIsSorted() === "asc")
        }
      >
        Email
        <ArrowUpDown className="ms-1 size-4" />
      </Button>
    ),
  },
  {
    accessorKey: "amount",
    header: () => <div className="text-end">Amount</div>,
    cell: ({ row }) => {
      const formatted = new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "USD",
      }).format(row.getValue("amount"));
      return <div className="text-end font-medium">{formatted}</div>;
    },
  },
];
```

### 2. Create the Table Instance

```tsx
import {
  useReactTable,
  getCoreRowModel,
  getSortedRowModel,
  getFilteredRowModel,
  getPaginationRowModel,
} from "@tanstack/react-table";

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  state: { sorting, columnFilters, rowSelection },
  onSortingChange: setSorting,
  onColumnFiltersChange: setColumnFilters,
  onRowSelectionChange: setRowSelection,
  // TanStack shows 10 rows per page by default
  initialState: { pagination: { pageSize: 5 } },
});
```

### 3. Render with Table.\*

Use `flexRender` from TanStack to render column definitions into chunks-ui styled cells:

```tsx
import { flexRender } from "@tanstack/react-table";
import { Table } from "chunks-ui";

<Table.Root>
  <Table.Header>
    {table.getHeaderGroups().map((headerGroup) => (
      <Table.Row key={headerGroup.id}>
        {headerGroup.headers.map((header) => (
          <Table.Head key={header.id}>
            {flexRender(header.column.columnDef.header, header.getContext())}
          </Table.Head>
        ))}
      </Table.Row>
    ))}
  </Table.Header>
  <Table.Body>
    {table.getRowModel().rows.map((row) => (
      <Table.Row
        key={row.id}
        data-state={row.getIsSelected() ? "selected" : undefined}
      >
        {row.getVisibleCells().map((cell) => (
          <Table.Cell key={cell.id}>
            {flexRender(cell.column.columnDef.cell, cell.getContext())}
          </Table.Cell>
        ))}
      </Table.Row>
    ))}
  </Table.Body>
</Table.Root>
```

### 4. Add Controls

Filter with `Input`, paginate with `Button` — no special wrapper needed:

```tsx
<Input
  placeholder="Filter emails..."
  aria-label="Filter emails"
  value={(table.getColumn("email")?.getFilterValue() as string) ?? ""}
  onChange={(e) => table.getColumn("email")?.setFilterValue(e.target.value)}
/>

<Button
  variant="outlined"
  color="secondary"
  onClick={() => table.previousPage()}
  disabled={!table.getCanPreviousPage()}
>
  Previous
</Button>
```

## Why This Pattern?

- **No table logic in chunks-ui** — `Table.*` is pure styling, TanStack owns the state
- **Composable** — swap TanStack for plain `.map()`, the styling stays the same
- **Familiar** — same pattern as shadcn/ui, widely adopted in the React ecosystem
- **Type-safe** — `ColumnDef<T>` gives you full type inference in cell renderers

---

# DatePicker

A trigger-and-popover date picker built on Base UI's `Popover` primitive and the `Calendar` component. Selecting a date closes the popover, or with a controlled `open`, asks you to close it through `onOpenChange` (see [Open State](#open-state)).

## Import

```tsx
import { DatePicker } from "chunks-ui";
```

## Basic Usage

```tsx
<DatePicker />
```

## Controlled

```tsx
function ControlledDatePicker() {
  const [date, setDate] = useState<Date | null>(null);

return (
    <DatePicker
      value={date}
      onValueChange={setDate}
      placeholder="Select a date"
    />
  );
}
```

## Date Constraints

Use `min` and `max` to limit the selectable range. Dates outside the range are rendered disabled in the calendar:

```tsx
const today = new Date();
const nextMonth = new Date(today.getFullYear(), today.getMonth() + 1, today.getDate());

<DatePicker min={today} max={nextMonth} />
```

## Week Start and Outside Days

`weekStartsOn` and `showOutsideDays` are passed to the calendar in the popover. See [Calendar](/components/calendar#week-start-and-outside-days) for what they do.

```tsx
<DatePicker weekStartsOn={1} showOutsideDays />
```

## Shown Month

`month` and `onMonthChange` are passed to the calendar too. See [Calendar](/components/calendar#shown-month) for what they do. With `month`, the calendar opens on that month, not on the selected date's, so set it when the date changes:

```tsx
function MonthDatePicker() {
  const [date, setDate] = useState<Date | null>(null);
  const [month, setMonth] = useState(() => new Date());

return (
    <DatePicker
      value={date}
      onValueChange={(next) => {
        setDate(next);
        if (next) setMonth(next);
      }}
      month={month}
      onMonthChange={setMonth}
    />
  );
}
```

## Open State

`open` and `onOpenChange` control whether the calendar is open, with the names and the `onOpenChange(open, eventDetails)` signature of Base UI's `Popover.Root`, and `defaultOpen` opens it on mount. A trigger press, a pick, Escape, an outside press and focus leaving the calendar (`focus-out`) call `onOpenChange` with Base UI's event details; a pick closes the calendar with the reason `close-press`. A controlled calendar opens and closes only when you change `open`. Without `open`, `eventDetails.cancel()` keeps the calendar as it is. However the calendar opened, a pick or Escape that closes it returns focus to the trigger if focus is still in the calendar.

```tsx
function OpenDatePicker() {
  const [open, setOpen] = useState(false);

return (
    <>
      <Button onClick={() => setOpen(true)}>Set due date</Button>
      <DatePicker aria-label="Due date" open={open} onOpenChange={setOpen} />
    </>
  );
}
```

## Disabled

A disabled `DatePicker` is dimmed and shows the not-allowed cursor. The `disabled` prop disables it, and so does a disabled `Field.Root`, Base UI's `Fieldset` or a `<fieldset disabled>`. A disabled picker stays closed whatever `open` and `defaultOpen` say, and it ignores a pick. Disabling a picker with an open calendar closes the calendar without calling `onOpenChange`. When it is enabled again, a controlled calendar opens if `open` is `true`; an uncontrolled one stays closed.

The `disabled` prop does all this at once. The other causes take effect when the picker next renders, because the picker reads the disabled state of its trigger after each render. Until then an open calendar stays open, but a pick in it is already ignored, and closes the calendar. When a disabled picker's calendar closes with focus in it, focus moves to the page, as it does when any focused control is disabled.

```tsx
<DatePicker disabled />
```

## Labelling

The trigger is a button. Without a label, its accessible name is its text: the placeholder or the selected date. Every `<button>` prop that `DatePicker` does not use itself goes to the trigger: `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `data-*`, event handlers and `ref`. Use one of these to label it.

With `aria-label`:

```tsx
<DatePicker aria-label="Due date" />
```

With a `<label>`: give the picker an `id` and set `htmlFor` on the label to the same value.

```tsx
<label htmlFor="due">Due date</label>
<DatePicker id="due" />
```

Inside `Field.Root`: `Field.Label` names the trigger and `Field.Description` describes it.

```tsx
<Field.Root>
  <Field.Label>Due date</Field.Label>
  <DatePicker />
  <Field.Description>The task is overdue after this day.</Field.Description>
</Field.Root>
```

A click on a `<label>` or a `Field.Label` clicks the trigger, so it opens the calendar.

The calendar opens in a dialog named "Choose date". Set `labels.dialog` to change the name, for example to translate it.

## Forms

Give the picker a `name` to send the selected date with a `<form>`. A hidden input holds the date as `yyyy-mm-dd`, or an empty string when no date is selected. The year always has 4 digits: January 5, 999 is `0999-01-05`. A disabled picker sends nothing.

To turn the value back into a local `Date`, add a time: `` new Date(`${value}T00:00`) ``. A date and time without an offset is read as local time. Do not use `new Date("2026-10-10")`: a date alone is read as midnight UTC, which is the day before in time zones west of UTC.

With `required`, the form does not submit until a date is selected, and focus moves to the trigger. A button has no required state for screen readers, so put it in the label, for example "Due date (required)". When Base UI's `Form` (`@base-ui/react/form`) validates the field on submit, an empty required picker is `valueMissing` in `Field.Validity`: `Field.Error` with `match="valueMissing"` shows its message and the trigger gets `aria-invalid`.

```tsx
<form
  onSubmit={(event) => {
    event.preventDefault();
    new FormData(event.currentTarget).get("due"); // "2026-10-10"
  }}
>
  <Field.Root>
    <Field.Label>Due date (required)</Field.Label>
    <DatePicker name="due" required />
  </Field.Root>
  <Button type="submit">Save</Button>
</form>
```

Inside `Field.Root`, the field's `name` wins over the picker's, as it does for Base UI's `Field.Control`. For example, with `<Field.Root name="due">` around `<DatePicker name="deadline" />`, the picker submits its date as `due`, and in development it warns once, naming both. A picker whose `Field.Root` has no name submits under its own `name`. A disabled field disables the hidden input too. For a picker outside its `<form>`, set `form` to the form's `id`.

Inside `Field.Root` in Base UI's `Form`, an entry for the field's name in the form's `errors`, for example `errors={{ due: "Pick a later date" }}`, shows in `Field.Error` and sets `aria-invalid` on the trigger until the user picks a date. `onFormSubmit` gets the date under the same name: `{ due: "2026-10-10" }`.

A form reset sets the picker back to its `defaultValue`, or to no date. This includes a picker that `form` links to a form it is outside of, with or without a `name`. A controlled picker keeps its `value`, as a controlled input does: set it back in the form's `onReset`. A reset that `onReset` cancels with `event.preventDefault()` leaves the picker as it is. As with native controls, a reset does not call `onValueChange`: an uncontrolled picker that you mirror in state through `onValueChange` is out of date after a reset, so reset that state in the form's `onReset` too.

When the picker has a `name` or is `required`, or its `Field.Root` has a `name`, the form input is the field's control and takes part in the browser's form validation, as an `Input` does. A failing `validate` on `Field.Root` with `validationMode` set to `"onChange"` or `"onBlur"` then also blocks the submit of a plain `<form>` and shows the browser's validation bubble.

## Text Size

The text of the trigger has the size of the text fields: 16px below the `md` breakpoint (768px by default) and on a touch screen, and 14px otherwise, so a form has one text size. To change it, pass a text-size class in `triggerClassName`. See [Text Size](/components/input#text-size) in `Input`.

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Enter</kbd> / <kbd>Space</kbd> on the trigger | Opens the calendar |
| <kbd>Enter</kbd> / <kbd>Space</kbd> on a day | Selects the day, closes the calendar and returns focus to the trigger |
| <kbd>Escape</kbd> | Closes the calendar without changing the date and returns focus to the trigger |

With a controlled `open`, these keys only call `onOpenChange` (a day is still selected at once): the calendar opens or closes, and focus moves, once you change `open`.

When the calendar opens, focus goes to the selected day, or to today if no date is selected. Inside the calendar, the arrow, Home, End and Page keys move focus as described in [Calendar keyboard](/components/calendar#keyboard). Disabled days can take focus but cannot be selected.

## DatePicker Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<DatePickerProps, 'value' | 'defaultValue' | 'onValueChange' | 'open' | 'defaultOpen' | 'onOpenChange' | 'placeholder' | 'disabled' | 'min' | 'max' | 'isDateDisabled' | 'weekStartsOn' | 'showOutsideDays' | 'month' | 'onMonthChange' | 'name' | 'required' | 'form' | 'className' | 'triggerClassName' | 'labels'>
export default Props
`
  })}
/>

`DatePicker` also takes every other `<button>` prop except `onChange` and passes it to the trigger. Use `onValueChange` to follow the date.

`className` goes on the wrapper `<div>` (set the width here). `triggerClassName` and `style` go on the trigger `<button>`; a conflicting class in `triggerClassName` replaces the default, such as `h-12` for the height. The trigger has a `data-placeholder` attribute while no date is picked, and the muted colour is a `data-placeholder:text-muted-foreground` class: a plain text colour in `triggerClassName` colours the picked date, and `data-placeholder:text-red-600` colours the placeholder.

The calendar popup is at least as wide as the trigger, and never narrower than the calendar (about 280px). In a wider popup the calendar sits in the centre.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_DATE_PICKER_LABELS`. They include every [Calendar key](/components/calendar#labels), which the picker passes to its calendar. The `placeholder` prop takes precedence over `labels.placeholder`. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default DatePickerLabels
`
  })}
/>

---

# Dialog

A modal dialog built on Base UI's `Dialog` primitive. Includes a backdrop overlay, centered popup with scale/fade animation, title, and description.

## Import

```tsx
import { Dialog } from "chunks-ui";
```

## Basic Usage

```tsx
<Dialog.Root>
  <Dialog.Trigger>Open Dialog</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>Are you sure?</Dialog.Title>
      <Dialog.Description>
        This action cannot be undone.
      </Dialog.Description>
      <div className="mt-4 flex justify-end gap-2">
        <Dialog.Close>Cancel</Dialog.Close>
        <Button color="destructive">Delete</Button>
      </div>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
```

## With Backdrop

The `Dialog.Backdrop` renders a semi-transparent black overlay (`bg-black/50`) with a fade transition. A dialog opened from inside another dialog or drawer renders its backdrop too, so it dims the parent (Base UI skips nested backdrops by default; pass `forceRender={false}` to do the same):

```tsx
<Dialog.Root>
  <Dialog.Trigger>Show</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>Dialog with backdrop</Dialog.Title>
      <Dialog.Description>
        The backdrop dims the content behind the dialog.
      </Dialog.Description>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
```

## Controlled

```tsx
function ControlledDialog() {
  const [open, setOpen] = useState(false);

return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Controlled Dialog</Dialog.Title>
          <Dialog.Description>You can control the open state.</Dialog.Description>
          <Dialog.Close>Done</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

## Long content

Put long content in a `Dialog.Body` between the Title and the actions. The popup is at most the viewport height less 2rem. The Title, the Description and the actions stay in place, and only the Body scrolls:

```tsx
<Dialog.Root>
  <Dialog.Trigger>Read the terms</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>Terms of service</Dialog.Title>
      <Dialog.Description>Read the terms before you accept them.</Dialog.Description>
      <Dialog.Body className="mt-4 space-y-3 text-sm">
        <p>These terms apply to your use of the service.</p>
        <p>Keep your account details safe.</p>
      </Dialog.Body>
      <div className="mt-4 flex justify-end gap-2">
        <Dialog.Close render={<Button variant="outlined" color="secondary" />}>
          Cancel
        </Dialog.Close>
        <Dialog.Close render={<Button />}>Accept</Dialog.Close>
      </div>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
```

- A Body whose content fits is skipped by the keyboard, and the first action takes the initial focus, so a short Body adds no tab stop. In jsdom, which has no layout, no Body is a tab stop; to test the overflow path, shim `scrollHeight` and `clientHeight` (`scrollWidth` and `clientWidth` for sideways overflow) on the element.
- `Dialog.Body` must be a direct child of `Dialog.Popup`. Wrapping the Body in a `<form>` or a `<div>` loses the layout: the popup scrolls as a whole again, the actions are not pinned and the Body does not scroll. For a form, see below.
- With a Body, the popup is a flex column. Bare inline children, such as a lone `Dialog.Close` button, stretch to the full width, and the margins between children do not collapse. Wrap the actions in a block, as in the example.
- The Body has a 0.25rem gutter (`-m-1 p-1`), so the focus rings of full-width fields are not clipped at its edges. The content does not move. A margin class on the Body, such as `mt-4`, replaces the negative margin on that side and adds the 0.25rem of padding.
- While its content overflows, the Body is a tab stop, so the keyboard can scroll it (arrow keys, Page Up and Page Down, Home and End); it measures itself again when its box or its content changes, including a child that grows on its own, such as an image that loads or a list that fills in. It is a region that the Title names.
- While it overflows, the Body also has a `data-overflowing` attribute, so a class can show that there is more to scroll, such as a line between the content and the actions: `<Dialog.Body className="data-overflowing:border-b">`.
- When the Body overflows and nothing tabbable comes before it, the Body gets the focus when the dialog opens with a keyboard or a mouse. The dialog opens at the top of the content, and a screen reader reads the Body's name. On touch, Base UI focuses the popup itself. The Body shows a focus ring when the dialog was opened with the keyboard.
- For a form in the Body, pass `initialFocus` on `Dialog.Popup` a ref to the first field.

### Form in a Body

Render the Body as the `<form>` with `render`, as on any Base UI part, and let the submit button in the actions point at it with the `form` attribute. The form is the Body: it keeps the scroll region, its name and its tab stop, and the actions stay in place while the fields scroll:

```tsx
<Dialog.Root>
  <Dialog.Trigger>New task</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>New task</Dialog.Title>
      <Dialog.Body
        render={<form id="new-task" onSubmit={(e) => e.preventDefault()} />}
        className="mt-4 space-y-3"
      >
        <Input aria-label="Title" placeholder="Title" />
        <Textarea aria-label="Notes" placeholder="Notes" />
      </Dialog.Body>
      <div className="mt-4 flex justify-end gap-2">
        <Dialog.Close render={<Button variant="outlined" color="secondary" />}>
          Cancel
        </Dialog.Close>
        <Button type="submit" form="new-task">
          Create
        </Button>
      </div>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
```

A `<form>` inside the Body, around the fields, works the same way; a `<form>` around the Body and the actions does not (the Body must be a direct child of the Popup, as above). `render` also takes a function of the props, as on Base UI parts. With a function, put the name on the Body (`aria-label` or `aria-labelledby`): the Body reads a name from its own props and from a `render` element, not from what a function returns, so the Title's name wins over one set inside the function.

Without a Body, content taller than the popup makes the whole popup scroll. Base UI focuses the first tabbable element and scrolls to it, so a dialog with its actions only at the bottom opens at the bottom. Pass `initialFocus` a ref to a top element, such as the Close button or the Title with `tabIndex={-1}`, to open at the top.

With nothing tabbable inside, or with `initialFocus` on the popup itself, the popup takes focus. When the browser shows focus there (after keyboard use, for example), the ring is the library focus ring, as on a Button: 2px of `--ring`, 2px outside the popup's edge.

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`). With Motion installed it uses the `overlay` spring (`springs.overlay`). Without Motion it is a CSS transition of `opacity` and `scale` (`micro-interactions`: 300ms, `cubic-bezier(0.4, 0, 0.2, 1)`). Reduced motion turns off both. The backdrop fades in and out independently.

`render` on `Dialog.Popup` or `Dialog.Backdrop` replaces the element the spring animates, so a popup or backdrop with `render` uses the CSS transition even with Motion installed. To restyle either, pass `className`; to change the element of the content, put `render` on `Dialog.Body`.

## Popups in a dialog

A Menu, Select, Popover or other popup opened from the dialog is placed against `Dialog.Portal`, a box fixed to the top of the viewport, so it stays at its trigger when the page behind scrolls or changes height. That has two limits:

- A popup taller than the viewport is clipped at the viewport's edge: a modal dialog locks the page's scroll, and in a `modal={false}` or `modal="trap-focus"` dialog the page scrolls but the fixed box adds no height to it. Menu and Combobox cap their height at the space available (`--available-height`) and scroll. A Popover does not, nor a Select that is not aligned over its trigger (with `alignItemWithTrigger={false}` on `Select.Positioner`, or opened by touch): cap them at `--available-height` and let them scroll. In a Popover, scroll an element inside `Popover.Content`, as `overflow` on the popup clips `Popover.Arrow`.
- A position class in the Portal's `className`, such as `absolute`, replaces `fixed`, and the popups move away from their triggers again when the page behind scrolls or changes height.

## Compound Parts

| Part | Description |
|---|---|
| `Dialog.Root` | State container. Manages open/close. |
| `Dialog.Trigger` | Button that opens the dialog. |
| `Dialog.Portal` | Renders children in a portal outside the DOM tree. Puts the dialog on the `z-modals` (700) layer; popups, dialogs and drawers opened from it stack above it. |
| `Dialog.Backdrop` | Semi-transparent overlay behind the dialog. Also renders for a nested dialog, so it dims the parent. |
| `Dialog.Popup` | Centered content panel. Max width 28rem (`max-w-md`), and never wider than the viewport less a 1rem gutter on each side, so its focus ring stays on the page; a `max-w-*` class in `className` replaces that cap. Max height the viewport less 2rem, then its content scrolls. |
| `Dialog.Title` | Dialog heading. Rendered as a semibold `text-lg`. |
| `Dialog.Description` | Supporting text below the title. Rendered in `text-muted-foreground`. |
| `Dialog.Body` | Optional scrolling area for long content, between the Title and the actions. Only the Body scrolls; the other parts stay in place. |
| `Dialog.Close` | Button that closes the dialog. |

## Props

All Dialog parts except `Dialog.Body` are pass-throughs to the underlying Base UI [`Dialog`](https://base-ui.com/react/components/dialog#api-reference). `Dialog.Body` is a `<section>` and takes its props, plus Base UI's `render` to replace the element (see the form above). Pass `aria-label` or `aria-labelledby`, on the Body or on the `render` element, to give it a name other than the Title; with a function `render`, put it on the Body. A `<div>` or `<span>` `render` element, or one a function `render` returns, gets `role="region"` from the Body while the Body is named. A `<form>` and any `role` you set are kept. A component in `render` gets none: give its element a role, or pass `role="region"` on the Body.

---

# Drawer

A side or bottom sheet overlay built on Base UI's `Dialog` primitive. Slides in from the left, right, or bottom edge.

## Import

```tsx
import { Drawer } from "chunks-ui";
```

## Basic Usage

```tsx
<Drawer.Root>
  <Drawer.Trigger>Open Drawer</Drawer.Trigger>
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Popup>
      <Drawer.Title>Navigation</Drawer.Title>
      <Drawer.Description>Browse the app sections.</Drawer.Description>
      <nav className="mt-4 flex flex-col gap-2">
        <a href="/">Home</a>
        <a href="/theme">Theme</a>
      </nav>
      <Drawer.Close>Close</Drawer.Close>
    </Drawer.Popup>
  </Drawer.Portal>
</Drawer.Root>
```

## Side Variants

The `side` prop on `Drawer.Popup` controls which edge the drawer slides from:

```tsx
{/* Right side (default) */}
<Drawer.Popup side="right">...</Drawer.Popup>

{/* Left side */}
<Drawer.Popup side="left">...</Drawer.Popup>

{/* Bottom sheet */}
<Drawer.Popup side="bottom">...</Drawer.Popup>
```

- `left` and `right` drawers have a fixed width of `w-80`.
- `bottom` drawer spans the full width with automatic height (up to `80dvh`) and rounded top corners.
- Content taller than the drawer scrolls inside it. To keep the Title and the actions in place, put the content in a `Drawer.Body` (below).
- With long content and actions only at the bottom, Base UI focuses the first tabbable element and scrolls to it. Pass `initialFocus` a ref to a top element, such as the Close button or the Title with `tabIndex={-1}`, to open at the top.
- With nothing tabbable inside, or with `initialFocus` on the popup itself, the popup takes focus. When the browser shows focus there (after keyboard use, for example), the ring is 2px in `--ring` and drawn just inside the 1px border on the open side, 3px from the popup's edge, so the border stays visible.

## Long content

Put long content in a `Drawer.Body` between the Title and the actions. The Title, the Description and the actions stay in place, and only the Body scrolls. In a `left` or `right` drawer the Body fills the height, so the actions sit at the bottom edge; a `bottom` drawer grows with its content up to `80dvh`:

```tsx
<Drawer.Root>
  <Drawer.Trigger>Read the terms</Drawer.Trigger>
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Popup>
      <Drawer.Title>Terms of service</Drawer.Title>
      <Drawer.Description>Read the terms before you accept them.</Drawer.Description>
      <Drawer.Body className="mt-4 space-y-3 text-sm">
        <p>These terms apply to your use of the service.</p>
        <p>Keep your account details safe.</p>
      </Drawer.Body>
      <div className="mt-4 flex justify-end gap-2">
        <Drawer.Close render={<Button variant="outlined" color="secondary" />}>
          Cancel
        </Drawer.Close>
        <Drawer.Close render={<Button />}>Accept</Drawer.Close>
      </div>
    </Drawer.Popup>
  </Drawer.Portal>
</Drawer.Root>
```

`Drawer.Body` works as `Dialog.Body`: the tab stop, `data-overflowing`, the name from the Title and the form through `render`. See [Dialog](/components/dialog#form-in-a-body).

## Controlled

```tsx
function ControlledDrawer() {
  const [open, setOpen] = useState(false);

return (
    <Drawer.Root open={open} onOpenChange={setOpen}>
      <Drawer.Trigger>Menu</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Backdrop />
        <Drawer.Popup side="left">
          <Drawer.Title>Menu</Drawer.Title>
          <Drawer.Close>Close</Drawer.Close>
        </Drawer.Popup>
      </Drawer.Portal>
    </Drawer.Root>
  );
}
```

## Animation

The drawer slides in from its edge: on the x-axis for `left` and `right`, on the y-axis for `bottom`. With Motion installed it uses the `overlay` spring (`springs.overlay`). Without Motion it is a CSS transition (`micro-interactions`: 300ms, `cubic-bezier(0.4, 0, 0.2, 1)`). Reduced motion turns off both. The backdrop fades in independently.

`render` on `Drawer.Popup` or `Drawer.Backdrop` replaces the element the spring animates, so a popup or backdrop with `render` uses the CSS transition even with Motion installed. To restyle either, pass `className`; to change the element of the content, put `render` on `Drawer.Body`.

## Popups in a drawer

As in a [Dialog](/components/dialog#popups-in-a-dialog), a popup opened from the drawer is placed against `Drawer.Portal`, a box fixed to the top of the viewport, so it stays at its trigger when the page behind scrolls or changes height. That has two limits:

- A popup taller than the viewport is clipped at the viewport's edge: a modal drawer locks the page's scroll, and in a `modal={false}` or `modal="trap-focus"` drawer the page scrolls but the fixed box adds no height to it. Menu and Combobox cap their height at the space available (`--available-height`) and scroll. A Popover does not, nor a Select that is not aligned over its trigger (with `alignItemWithTrigger={false}` on `Select.Positioner`, or opened by touch): cap them at `--available-height` and let them scroll. In a Popover, scroll an element inside `Popover.Content`, as `overflow` on the popup clips `Popover.Arrow`.
- A position class in the Portal's `className`, such as `absolute`, replaces `fixed`, and the popups move away from their triggers again when the page behind scrolls or changes height.

## Compound Parts

| Part | Description |
|---|---|
| `Drawer.Root` | State container. Manages open/close state. |
| `Drawer.Trigger` | Button that opens the drawer. |
| `Drawer.Portal` | Renders children in a portal. Puts the drawer on the `z-drawers` (600) layer; popups, dialogs and drawers opened from it stack above it. |
| `Drawer.Backdrop` | Semi-transparent overlay. Also renders for a nested drawer, so it dims the parent. |
| `Drawer.Popup` | The sliding panel. Accepts `side` prop. |
| `Drawer.Title` | Drawer heading. |
| `Drawer.Description` | Supporting description text. |
| `Drawer.Body` | Optional scrolling area for long content, between the Title and the actions. Only the Body scrolls; the other parts stay in place. |
| `Drawer.Close` | Button that closes the drawer. |

## Drawer.Root Props

All `Drawer.Root` props are forwarded to the underlying Base UI [`Dialog`](https://base-ui.com/react/components/dialog#api-reference).

## Drawer.Body Props

`Drawer.Body` takes the props of `Dialog.Body`: a `<section>`'s, plus Base UI's `render`.

## Drawer.Popup Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<DrawerPopupProps, 'side'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Dialog.Popup`](https://base-ui.com/react/components/dialog#api-reference).

---

# Empty

A structured empty state for lists, tables, and search results. Provides a consistent centered layout with optional icon, title, description, and action buttons.

## Import

```tsx
import { Empty } from "chunks-ui";
```

## Basic Usage

```tsx
<Empty.Root>
  <Empty.Media>
    <BoxIcon />
  </Empty.Media>
  <Empty.Title>No paints found</Empty.Title>
  <Empty.Description>Try adjusting your search or filter criteria.</Empty.Description>
  <Empty.Actions>
    <Button variant="outlined">Clear filters</Button>
  </Empty.Actions>
</Empty.Root>
```

## Minimal

All parts except `Root` are optional. Use just a title and description for simple cases:

```tsx
<Empty.Root>
  <Empty.Title>No results</Empty.Title>
  <Empty.Description>There are no items to display yet.</Empty.Description>
</Empty.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Empty.Root` | Centered flex column container with vertical spacing. |
| `Empty.Media` | Icon or illustration container. Auto-sizes SVGs to 48px. |
| `Empty.Title` | Heading text (`<h3>`). |
| `Empty.Description` | Supporting text in muted color. Max width constrained for readability. |
| `Empty.Actions` | Horizontal button group. |

## Props

All parts accept `className` for customization. All other props are forwarded to their respective HTML elements (`<div>`, `<h3>`, `<p>`).

---

# Field

A form field wrapper built on Base UI's `Field` primitive. Provides label, description, error message, and validation state management for form controls like `Input`, `Textarea`, `Checkbox`, etc.

## Import

```tsx
import { Field } from "chunks-ui";
```

## Basic Usage

```tsx
<Field.Root>
  <Field.Label>Email</Field.Label>
  <Input type="email" placeholder="you@example.com" />
</Field.Root>
```

## With Description

```tsx
<Field.Root>
  <Field.Label>Password</Field.Label>
  <Field.Description>Must be at least 8 characters.</Field.Description>
  <Input type="password" />
</Field.Root>
```

## Validation Error

Set `invalid` on `Field.Root` to activate error styling. The input receives `aria-invalid` and `data-invalid` for red border styling. `invalid` alone does not show `Field.Error`: it renders only for a failed validation (see Native Validation), a server error passed to `Form`, or `match={true}`. To show a message for the `invalid` prop, add `match`:

```tsx
<Field.Root invalid>
  <Field.Label>Email</Field.Label>
  <Input type="email" placeholder="you@example.com" />
  <Field.Error match>Please enter a valid email address.</Field.Error>
</Field.Root>
```

## With Textarea

`Textarea` works in a field the same way as `Input`: the label names it, the description describes it, and the field's `disabled` and `invalid` state apply to it.

```tsx
<Field.Root>
  <Field.Label>Message</Field.Label>
  <Field.Description>Describe your issue in detail.</Field.Description>
  <Textarea autoResize placeholder="Type here..." />
</Field.Root>
```

## Native Validation

Use `Field.Validity` for native constraint validation:

```tsx
<Field.Root>
  <Field.Label>Username</Field.Label>
  <Field.Control
    render={<Input />}
    required
    minLength={3}
  />
  <Field.Validity>
    {(state) =>
      state.validity.valueMissing ? (
        <Field.Error>Username is required.</Field.Error>
      ) : state.validity.tooShort ? (
        <Field.Error>Must be at least 3 characters.</Field.Error>
      ) : null
    }
  </Field.Validity>
</Field.Root>
```

## Disabled State

Labels dim to 50% opacity and show a not-allowed cursor when the field is disabled:

```tsx
<Field.Root disabled>
  <Field.Label>Locked Field</Field.Label>
  <Input disabled value="Cannot edit" />
</Field.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Field.Root` | Wrapper element. Vertical flex with `gap-2`, so the control's focus ring (4px past its edge) stays clear of the label and the text below. Manages `invalid` and `disabled` state. |
| `Field.Label` | Form label. `text-sm font-medium`. Dims and shows a not-allowed cursor when disabled. |
| `Field.Description` | Help text below the label. `text-xs text-muted-foreground`. |
| `Field.Error` | Error message. `text-xs text-destructive-text`. Renders on a failed validation, a server error, or with `match`. |
| `Field.Control` | Connects a form control to the field (for native validation). Uses `render` prop. |
| `Field.Validity` | Render prop for accessing native validity state. |

## Props

All Field parts are pass-throughs to the underlying Base UI [`Field`](https://base-ui.com/react/components/field#api-reference).

---

# IconButton

A compact, square button for a single icon. Built on Base UI's `Button` primitive and sharing the same `variant` and `color` system as [`Button`](./button).

## Import

```tsx
import { IconButton } from 'chunks-ui'
```

## Basic Usage

Icon-only buttons have no visible text, so an `aria-label` is **required** for accessibility.

```tsx
<IconButton aria-label="Add item">
  <PlusIcon />
</IconButton>
```

## Variants

The `variant` prop controls the visual style. Default: `text`.

```tsx
<IconButton variant="contained" aria-label="Add"><PlusIcon /></IconButton>
<IconButton variant="outlined" aria-label="Add"><PlusIcon /></IconButton>
<IconButton variant="text" aria-label="Add"><PlusIcon /></IconButton>
```

## Colors

The `color` prop sets the semantic color. Default: `secondary` — the familiar muted "toolbar icon" look.

```tsx
<IconButton variant="contained" color="primary" aria-label="Search"><SearchIcon /></IconButton>
<IconButton variant="contained" color="destructive" aria-label="Delete"><TrashIcon /></IconButton>
<IconButton variant="contained" color="success" aria-label="Confirm"><CheckIcon /></IconButton>
<IconButton variant="contained" color="warning" aria-label="Settings"><SettingsIcon /></IconButton>
<IconButton variant="contained" color="secondary" aria-label="Add"><PlusIcon /></IconButton>
```

Colors work with all variants:

```tsx
<IconButton variant="outlined" color="destructive" aria-label="Delete"><TrashIcon /></IconButton>
<IconButton variant="text" color="success" aria-label="Confirm"><CheckIcon /></IconButton>
```

## Accessibility

Because the button has no visible text, you **must** provide an `aria-label` describing the action. Screen readers will announce this label; without it the button is anonymous.

```tsx
<IconButton aria-label="Delete item">
  <TrashIcon />
</IconButton>
```

### Touch Target

The button is 32px square. To make it easier to tap, add [`touch-target`](/utilities#touch-target): the hit area grows to 44×44px, and the button's size and the layout stay the same. With `pointer-coarse:` (Tailwind 4.1 or later), it grows only on touch screens:

```tsx
<IconButton aria-label="Close" className="pointer-coarse:touch-target">
  <XIcon />
</IconButton>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `"contained" \| "outlined" \| "text"` | `"text"` | Visual style. |
| `color` | `"primary" \| "secondary" \| "success" \| "warning" \| "destructive"` | `"secondary"` | Semantic color. |

All other props are forwarded to the underlying Base UI [`Button`](https://base-ui.com/react/components/button#api-reference).

---

# InputCopy

A read-only input with an integrated copy button. Composes `Input` and `CopyButton` internally.

## Import

```tsx
import { InputCopy } from "chunks-ui";
```

## Basic Usage

```tsx
<InputCopy value="https://vibekanban.com/invite/abc123" aria-label="Invite link" />
```

## Editable

The input is read-only by default (`readOnly` defaults to `true`). To let users edit the value, pass `readOnly={false}` and control `value` with `onChange`. The button copies the current value:

```tsx
function EditableInputCopy() {
  const [value, setValue] = useState("PROMO-2024-SUMMER");

return (
    <InputCopy
      value={value}
      onChange={(e) => setValue(e.target.value)}
      readOnly={false}
      aria-label="Promo code"
    />
  );
}
```

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<InputCopyProps, 'value' | 'labels'>
export default Props
`
  })}
/>

All other `Input` props are forwarded except `endAdornment` and `onClear` (reserved for the internal `CopyButton`). `readOnly` defaults to `true`. `aria-label` names the input, not the copy button.

The text of the field is 16px below `md` (768px by default) and on a touch screen, and 14px otherwise, as in `Input`. A string `className` goes on the wrapper, not the input; a function reaches the input. See [Text Size](/components/input#text-size) in `Input`.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_INPUT_COPY_LABELS`. They name the copy button, which reads "Copied" for a moment after a copy. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default InputCopyLabels
`
  })}
/>

---

InputErrorExample,
  InputWithFieldExample,
  ClearableSearch,
  InputWithClearButton,
} from '@/examples/Input'

# Input

A styled text input built on Base UI's `Input` primitive. Supports start/end adornments, a clear button, and error states via `data-invalid`.

## Import

```tsx
import { Input } from 'chunks-ui'
```

## Basic Usage

```tsx
<Input placeholder="Enter your name" aria-label="Name" />
```

## Adornments

Use `startAdornment` and `endAdornment` to place icons or text at the edges of the input:

```tsx
<Input startAdornment={<SearchIcon className="size-4" />} placeholder="Search..." aria-label="Search" />
```

```tsx
<Input endAdornment={<span className="text-xs text-muted-foreground">USD</span>} placeholder="0.00" aria-label="Amount" />
```

## Clear Button

Add `clearable` to show a built-in clear button (the `ClearButton` component). The button shows while the input has text and can be edited: it hides while the input is disabled or read-only, whichever sets it (`disabled`, `readOnly`, or a disabled `Field.Root`). While it is visible it takes the place of `endAdornment`, so the two don't show together. On a `type="search"` input, Chromium browsers and Safari also draw a clear button of their own. With `clearable` or `onClear`, the browser's button never shows, so the built-in one is the only clear button.

Clearing empties the input the way typing does: `onChange` and `onValueChange` fire with `''`. With a mouse click, focus stays in the input, because the click doesn't blur it, so a `Field.Root` with `validationMode="onBlur"` doesn't validate in the middle of a clear. With the keyboard (Tab to the button, then Enter or Space), the input blurs, and focus then returns to it.

```tsx
<Input type="search" defaultValue="Hello" clearable placeholder="Search..." aria-label="Search" />
```

An uncontrolled input shows the button while it has text, also after a form reset. React Hook Form's `reset()` and `setValue()` write `input.value` from code, which fires no event: the button follows such a write when the input next renders, for example when the component that holds the form re-renders.

A controlled input is cleared by the handler that sets its `value`, so it needs one: `onChange`, `onValueChange` or `onClear`. Without one, the button changes nothing, and each such input warns once in the console in development.

```tsx
export const ClearableSearch = () => {
  const [value, setValue] = useState('Hello')

return (
    <Input value={value} onValueChange={setValue} clearable placeholder="Search..." aria-label="Search" />
  )
}
```

### onClear

`onClear` is called when the clear button is used. Passing it also shows the button, without `clearable`. With `clearable` too, the value handlers fire first, as above, and `onClear` only tells you that it happened. With `onClear` alone, a controlled input fires no `onChange` or `onValueChange`, and keeps its `value` until your `onClear` sets it to `''`:

```tsx
export const InputWithClearButton = () => {
  const [value, setValue] = useState('')

return (
    <Input
      value={value}
      onChange={e => setValue(e.target.value)}
      onClear={() => setValue('')}
      placeholder="Search..."
      aria-label="Search"
    />
  )
}
```

An uncontrolled input (`defaultValue`) is emptied for you, and `onClear` only tells you that it happened.

## Error State

The input styles change when the `data-invalid` attribute is present (set automatically by `Field.Root` with `invalid` prop, or manually). `Field.Error` shows only when the field fails validation, so add `match` to show it whenever you set `invalid` yourself. `match={true}` shows the error regardless of `invalid`, so pass `match={hasError}` (or render `Field.Error` only while the field is invalid). This example is always invalid, so `match` can stay:

```tsx
<Field.Root invalid>
  <Field.Label>Email</Field.Label>
  <Input placeholder="user@example.com" />
  <Field.Error match>Invalid email address</Field.Error>
</Field.Root>
```

## With Field

Wrap `Input` in a `Field` for labels, descriptions, and validation:

```tsx
<Field.Root>
  <Field.Label>Username</Field.Label>
  <Field.Description>Choose a unique username</Field.Description>
  <Input placeholder="johndoe" />
</Field.Root>
```

## Mobile Keyboards

`type`, `inputMode`, `enterKeyHint` and `autoComplete` pass through to the `<input>`. Phones read them to choose the on-screen keyboard and the label of its Enter key, and to suggest saved values. A search field gets a search key:

```tsx
<Input type="search" enterKeyHint="search" placeholder="Search..." aria-label="Search" />
```

A decimal value, such as an amount, gets a number keypad with a decimal separator:

```tsx
<Input inputMode="decimal" placeholder="0.00" aria-label="Amount" />
```

## Text Size

The text is 16px below the `md` breakpoint (768px by default) and at any width where touch is the main pointer (`pointer: coarse`), such as a phone or a tablet, and 14px otherwise; a laptop with a touch screen keeps 14px. iOS Safari zooms the page when a field with text under 16px takes focus, and a touch device can be wider than `md`: an iPad, or a larger iPhone (such as the Plus, Pro Max and Air models) held sideways. `Select.Trigger`, the `Select` items and the `DatePicker` trigger have the same size, so a form has one text size. The 16px assumes the default root font size, because `text-base` is 1rem.

With a mouse, a text-size class on the input, such as `text-lg`, sets the size from `md` up. A `max-md:` class, such as `max-md:text-lg`, sets it below `md`, on a touch screen too; a size under 16px brings the zoom back. A `sm:` size applies from 640px and wins over the 16px until `md`, on a touch screen too: with `sm:text-sm`, an iPhone 17 held sideways (750px) has 14px text, and iOS zooms.

From `md` up, on a touch screen the 16px wins over those classes. To change the size there, use a `md:[@media(pointer:coarse)]:` class, such as `md:[@media(pointer:coarse)]:text-lg`; a size under 16px brings the zoom back. A `[@media(pointer:coarse)]:` class without `md:`, or a `pointer-coarse:` class (Tailwind 4.1 or newer), does not change it there. Below `md` it does apply, so a phone shows it and a tablet does not. For 18px everywhere, pass `text-lg max-md:text-lg md:[@media(pointer:coarse)]:text-lg`.

On an `Input` with `startAdornment`, `endAdornment`, `clearable` or `onClear`, and in every `InputCopy`, a string `className` goes on the wrapper, not the input, so a text-size class there does not change the field. Pass a function, `className={() => "md:[@media(pointer:coarse)]:text-lg"}`, to reach the input.

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<InputProps, 'startAdornment' | 'endAdornment' | 'clearable' | 'onClear' | 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Input`](https://base-ui.com/react/components/input#api-reference).

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_INPUT_LABELS`. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default InputLabels
`
  })}
/>

---

# Label

A standalone form label with consistent typography. Use when you need a label outside of a `Field` context. For labels inside a `Field.Root`, use `Field.Label` instead.

## Import

```tsx
import { Label } from "chunks-ui";
```

## Basic Usage

```tsx
<Label htmlFor="email">Email address</Label>
```

## With Input

```tsx
<div className="flex flex-col gap-1.5">
  <Label htmlFor="username">Username</Label>
  <Input id="username" />
</div>
```

## Disabled

`disabled` dims the label and shows a not-allowed cursor. The label does not read its control's state, so pass `disabled` to both:

```tsx
<div className="flex items-center gap-2">
  <Label htmlFor="terms" disabled>Accept terms</Label>
  <Checkbox.Root id="terms" disabled>
    <Checkbox.Indicator />
  </Checkbox.Root>
</div>
```

A disabled label carries `data-disabled`, the attribute Base UI sets on `Field.Label` inside a disabled `Field.Root`, and its disabled look is keyed on that attribute alone. One `data-disabled:` class in `className` restyles it (spell the variant `data-disabled:`, as the component does, so `cn` drops the default):

```tsx
<Label htmlFor="terms" disabled className="data-disabled:opacity-75">
  Accept terms
</Label>
```

Inside a `Field.Root`, use `Field.Label`, which dims when the field is disabled.

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<LabelProps, 'disabled'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying native `<label>` element.

## Styling

- `font-medium text-sm leading-none` — matches `Field.Label` typography

---

# Loader

An animated SVG spinner for loading states. Used internally by `Button` during its loading state, and available for standalone use.

## Import

```tsx
import { Loader } from "chunks-ui";
```

## Basic Usage

The spinner inherits the current text color of its parent, so it always keeps contrast with the background.

```tsx
<Loader />
```

## Custom Color

Override the color via `className`:

```tsx
<Loader className="text-primary-text" />
<Loader className="text-muted-foreground" />
```

## Inline with Text

```tsx
<div className="flex items-center gap-2 text-muted-foreground">
  <Loader />
  <span>Loading data...</span>
</div>
```

## Full-Page Loading

Cover the page with a fixed overlay while something loads. The demo hides it after two seconds:

```tsx
<div role="status">
  {loading && (
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
      <Loader className="text-white" />
      <span className="sr-only">Loading…</span>
    </div>
  )}
</div>
```

Keep the `role="status"` element mounted and change only its content. Screen readers often skip a status region that mounts together with its text.

## Props

This component accepts all props from the underlying `<svg>` element. The spinner uses `animate-spin` for rotation and is marked `aria-hidden="true"`, so pair it with text or a `role="status"` region that says what is loading. It keeps spinning when the user prefers reduced motion, because it is an essential status indicator.

---

# Menu

A dropdown menu built on Base UI's `Menu` primitive. Supports plain items, groups, checkbox items, and radio groups. Animates with Motion when available, falls back to CSS transitions.

## Import

```tsx
import { Menu } from "chunks-ui";
```

## Basic Usage

```tsx
<Menu.Root>
  <Menu.Trigger>Options</Menu.Trigger>
  <Menu.Content>
    <Menu.Item>View profile</Menu.Item>
    <Menu.Item>Edit settings</Menu.Item>
    <Menu.Separator />
    <Menu.Item>Sign out</Menu.Item>
  </Menu.Content>
</Menu.Root>
```

## Groups

Use `Menu.Group` with `Menu.GroupLabel` to organize items into labelled sections:

```tsx
<Menu.Root>
  <Menu.Trigger>Actions</Menu.Trigger>
  <Menu.Content>
    <Menu.Group>
      <Menu.GroupLabel>File</Menu.GroupLabel>
      <Menu.Item>New file</Menu.Item>
      <Menu.Item>Open...</Menu.Item>
    </Menu.Group>
    <Menu.Separator />
    <Menu.Group>
      <Menu.GroupLabel>Edit</Menu.GroupLabel>
      <Menu.Item>Undo</Menu.Item>
      <Menu.Item>Redo</Menu.Item>
    </Menu.Group>
  </Menu.Content>
</Menu.Root>
```

## Checkbox Items

`Menu.CheckboxItem` keeps a checked state. Pair with `Menu.CheckboxItemIndicator` to show a check mark:

```tsx
<Menu.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
  <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator>
  Show grid
</Menu.CheckboxItem>
```

## Radio Group

`Menu.RadioGroup` enforces single selection among `Menu.RadioItem` children:

```tsx
<Menu.RadioGroup value={theme} onValueChange={setTheme}>
  <Menu.RadioItem value="light">
    <Menu.RadioItemIndicator>•</Menu.RadioItemIndicator>
    Light
  </Menu.RadioItem>
  <Menu.RadioItem value="dark">
    <Menu.RadioItemIndicator>•</Menu.RadioItemIndicator>
    Dark
  </Menu.RadioItem>
</Menu.RadioGroup>
```

## Positioning

`Menu.Content` accepts positioning props forwarded to Base UI's positioner:

```tsx
<Menu.Content side="right" align="start" sideOffset={12}>
  ...
</Menu.Content>
```

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`): the `popup` spring (`springs.popup`) with Motion installed, a CSS transition of `opacity` and `scale` without it; reduced motion turns off both. The popup grows out of its trigger (`origin-(--transform-origin)`); a `className` such as `origin-top` replaces it.

`render` on `Menu.Content` replaces the element the spring animates, so a popup with `render` uses the CSS transition even with Motion installed. To restyle the popup, pass `className`.

## Compound Parts

| Part | Description |
|---|---|
| `Menu.Root` | State container. Manages open/close. |
| `Menu.Trigger` | Element that opens the menu. |
| `Menu.Content` | Portal + positioner + popup panel. Default `sideOffset={8}`, as on `Popover.Content`: the popup's focus ring, 4px outside its edge, stays clear of the trigger. Scrolls when the items need more than the space between the trigger and the viewport edge. The items scroll in an inner element, so layout classes on `Menu.Content` (such as `grid` or `gap-*`) do not reach them: wrap the items in your own element instead. When the menu itself takes focus, as when a shortcut opens it, it shows the library focus ring after keyboard use: 2px of `--ring`, 2px outside its edge. From the first pointer move over the popup (one with real movement) until the next key press the ring stays off: the popup sets `data-pointer` meanwhile, so the focus Base UI gives the popup when the pointer leaves an item draws no ring. |
| `Menu.Item` | A single actionable menu entry. |
| `Menu.Separator` | Horizontal divider between groups of items. |
| `Menu.Group` | Semantic grouping wrapper for related items. |
| `Menu.GroupLabel` | Non-interactive label for a `Menu.Group`. |
| `Menu.CheckboxItem` | Menu item with a toggleable checked state. |
| `Menu.CheckboxItemIndicator` | Visual indicator shown when `CheckboxItem` is checked. |
| `Menu.RadioGroup` | Enforces single selection among `RadioItem` children. |
| `Menu.RadioItem` | Selectable item within a `Menu.RadioGroup`. |
| `Menu.RadioItemIndicator` | Visual indicator shown when `RadioItem` is selected. |
| `Menu.Arrow` | Arrow on the popup edge that faces the trigger, in the popup's `--popover` background and `--border` colour. Place it inside `Menu.Content`. In RTL it needs `dir="rtl"` on `<html>` or `<body>`. The menu moves out by the arrow's length, so `sideOffset` stays the gap between the trigger and the arrow's tip. The arrow stays at least `arrowPadding` pixels from the menu's ends, clear of the rounded corner. The default is the menu's corner radius plus 0.21 × the arrow's size (about 10 in the default theme). It is read when the menu mounts and again when a `Menu.Arrow` mounts or unmounts in it (not after a runtime `--radius` change), so it follows `--radius`, `--spacing` and a `rounded-*` class on `Menu.Content`. With an arrow, the focus ring is drawn on the menu's `::after`, above the arrow. It is the same ring as without an arrow, and the `::after` takes the menu's border width, so restyle it with classes under the same `has-[.PopupArrow]:focus-visible:after:` prefix (for example `has-[.PopupArrow]:focus-visible:after:outline-destructive`), or remove it with `focus-visible:after:hidden`. |

## Menu.Content Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<MenuContentProps, 'sideOffset' | 'side' | 'align' | 'alignOffset' | 'arrowPadding'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Menu.Popup`](https://base-ui.com/react/components/menu#api-reference).

## Menu.Item Props

All props are forwarded to the underlying Base UI [`Menu.Item`](https://base-ui.com/react/components/menu#api-reference).

---

# NumberField

A numeric input built on Base UI's `NumberField` primitive. Supports increment/decrement buttons, min/max/step constraints, and scrub-area drag interaction.

## Import

```tsx
import { NumberField } from "chunks-ui";
```

## Basic Usage

```tsx
<NumberField.Root defaultValue={10}>
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input aria-label="Quantity" />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>
```

## Min, Max, and Step

Use `min` and `max` to constrain the value, and `step` to set how far the buttons and arrow keys move it. `Field.Label` names the input:

```tsx
<Field.Root>
  <Field.Label>Quantity (1–20)</Field.Label>
  <NumberField.Root defaultValue={5} min={1} max={20}>
    <NumberField.Group>
      <NumberField.Decrement />
      <NumberField.Input />
      <NumberField.Increment />
    </NumberField.Group>
  </NumberField.Root>
</Field.Root>

<Field.Root>
  <Field.Label>Step by 5</Field.Label>
  <NumberField.Root defaultValue={0} min={0} max={100} step={5}>
    <NumberField.Group>
      <NumberField.Decrement />
      <NumberField.Input />
      <NumberField.Increment />
    </NumberField.Group>
  </NumberField.Root>
</Field.Root>
```

## Scrub Area

Wrap a label with `NumberField.ScrubArea` to allow click-and-drag adjustment. While you drag with a mouse, the browser locks and hides the system pointer. `NumberField.ScrubAreaCursor` shows in its place, as a left-right arrow by default; pass children or a `render` element to draw your own. Without `ScrubAreaCursor`, a mouse scrub shows no pointer at all, so always include it. Safari and touch input keep the system pointer, so the part does not render there:

```tsx
<NumberField.Root defaultValue={100}>
  <NumberField.ScrubArea>
    <span>Drag to adjust</span>
    <NumberField.ScrubAreaCursor />
  </NumberField.ScrubArea>
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input aria-label="Amount" />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>
```

The cursor renders where the popups do: in the [`PortalContainerProvider`](/utilities#portalcontainerprovider)'s element, or in the portal of the `Dialog`, `Drawer`, `Popover`, `Combobox`, `Menu`, `Select` or `Tooltip` it sits in. Its layer is in [Z-Index Layers](/theme#z-index-layers). Like a `Dialog`, it is placed against the viewport, so a `transform` or a similar property on the provider's element or an ancestor offsets it from the pointer: see [Container limits](/utilities#container-limits).

## Disabled

A disabled `NumberField` is dimmed and shows the not-allowed cursor over its input and buttons.

```tsx
<NumberField.Root defaultValue={42} disabled>
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input aria-label="Quantity" />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>
```

## Mobile Keyboards

Base UI sets `inputMode` on `NumberField.Input` for you: `numeric`, except on iOS, whose number keypad has no minus key. There a `min` of 0 or more gives the decimal keypad, and without one, or with a negative `min`, the full keyboard shows, so a minus sign can be typed. Set `min={0}` when the value can't be negative, so iOS shows the keypad. An `inputMode` you pass to `NumberField.Input` replaces Base UI's.

A `numeric` keypad need not have a decimal separator: the HTML spec suggests `numeric` for PIN entry and asks for the locale's separator only with `decimal`. When the value can have a fraction, for example with a fractional `step`, pass `inputMode="decimal"` to `NumberField.Input`. On iOS it also replaces the full keyboard that Base UI shows when `min` is negative or not set. The decimal keypad has no minus key, so the minus sign can't be typed on iOS. For a value that can be both negative and fractional, pass `inputMode="text"`: every platform then shows the full keyboard, which Base UI uses on iOS when `min` is negative or not set.

## Text Size

The text of `NumberField.Input` is 16px below the `md` breakpoint (768px by default) and on a touch screen, so iOS Safari does not zoom the page when the field takes focus (it zooms into text under 16px); otherwise it is 14px, as in `Input`. With a mouse, a text-size class on `NumberField.Input`, such as `text-lg`, sets the size from `md` up. A `max-md:` class, such as `max-md:text-lg`, sets it below `md`, on a touch screen too; from `md` up on a touch screen, a `md:[@media(pointer:coarse)]:` class sets it. See [Text Size](/components/input#text-size) in `Input` for the limits.

## Compound Parts

| Part | Description |
|---|---|
| `NumberField.Root` | State container. Manages value, min, max, step, and disabled state. |
| `NumberField.Group` | Wraps `Decrement`, `Input`, and `Increment` into a single bordered control. |
| `NumberField.Input` | The text input. Displays and accepts the numeric value. |
| `NumberField.Decrement` | Button that decrements the value by `step`. Children you pass replace the minus icon; with a `render` element and no children, there is no minus icon. The button keeps its `aria-label` whatever its content: if the children are visible text, pass an `aria-label` that contains it. |
| `NumberField.Increment` | Button that increments the value by `step`. Children you pass replace the plus icon; with a `render` element and no children, there is no plus icon. The button keeps its `aria-label` whatever its content: if the children are visible text, pass an `aria-label` that contains it. |
| `NumberField.ScrubArea` | A region the user can click-drag to change the value. |
| `NumberField.ScrubAreaCursor` | The cursor shown in place of the locked system pointer while the user scrubs. Renders a left-right arrow unless you pass children or `render`. Leave it out and a mouse scrub shows no pointer. |

## Props

All parts accept the props from their corresponding Base UI [`NumberField`](https://base-ui.com/react/components/number-field#api-reference) sub-components. `NumberField.Root` also takes `labels`:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<NumberFieldRootProps, 'labels'>
export default Props
`
  })}
/>

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_NUMBER_FIELD_LABELS`. Base UI sets these strings; `aria-label` on `NumberField.Increment` or `NumberField.Decrement` and `aria-roledescription` on `NumberField.Input` take precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default NumberFieldLabels
`
  })}
/>

---

# Pagination

A navigation component for paginated content. Uses semantic HTML (`<nav>`, `<ul>`, `<li>`) with `aria-label="Pagination"`. Unstyled structure — consumers provide page range logic.

## Import

```tsx
import { Pagination } from "chunks-ui";
```

## Basic Usage

```tsx
<Pagination.Root>
  <Pagination.Content>
    <Pagination.Item>
      <Pagination.Previous href="?page=1" />
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="?page=1">1</Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="?page=2" active>2</Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="?page=3">3</Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Next href="?page=3" />
    </Pagination.Item>
  </Pagination.Content>
</Pagination.Root>
```

## With Ellipsis

Use `Pagination.Ellipsis` for large page ranges:

```tsx
<Pagination.Item>
  <Pagination.Ellipsis />
</Pagination.Item>
```

## Custom Link Component

Use the `render` prop on `Link`, `Previous`, and `Next` to render framework-specific links:

```tsx
<Pagination.Link render={<Link to="?page=2" />} active>2</Pagination.Link>
<Pagination.Previous render={<Link to="?page=1" />} />
```

## Compound Parts

| Part | Description |
|---|---|
| `Pagination.Root` | `<nav>` wrapper named "Pagination". Takes `labels` for the parts' built-in text. |
| `Pagination.Content` | `<ul>` containing page items. |
| `Pagination.Item` | `<li>` wrapping a link, ellipsis, or nav button. |
| `Pagination.Link` | Page number link. `active` sets `aria-current="page"`. |
| `Pagination.Previous` | Previous page button with chevron icon. |
| `Pagination.Next` | Next page button with chevron icon. |
| `Pagination.Ellipsis` | Collapsed page range indicator. Children you pass replace the dots; screen readers read them and the hidden label (`labels.ellipsis`), so give a decorative icon `aria-hidden`. |

## Pagination.Root Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<PaginationRootProps, 'labels'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<nav>` element.

## Pagination.Link Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<PaginationLinkProps, 'active' | 'render'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<a>` element.

## Pagination.Previous / Pagination.Next Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<PaginationPreviousProps, 'render'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<a>` element.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_PAGINATION_LABELS`. `aria-label` on `Pagination.Root` and `children` on `Pagination.Previous` and `Pagination.Next` take precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default PaginationLabels
`
  })}
/>

---

# Popover

A positioned popup built on Base UI's `Popover` primitive. Includes built-in Floating UI positioning, an optional arrow, and scale/fade enter/exit transitions.

## Import

```tsx
import { Popover } from "chunks-ui";
```

## Basic Usage

```tsx
<Popover.Root>
  <Popover.Trigger>More info</Popover.Trigger>
  <Popover.Content>
    <Popover.Title>Details</Popover.Title>
    <Popover.Description>
      This is additional context about the feature.
    </Popover.Description>
  </Popover.Content>
</Popover.Root>
```

## With Arrow

`Popover.Arrow` draws a small arrow on the popup edge that faces the trigger, filled with the popup's `--popover` background and edged with its `--border` colour. Place it inside `Popover.Content`. The popup moves out by the arrow's length, so `sideOffset` stays the gap between the trigger and the arrow's tip. The arrow stays at least `arrowPadding` pixels from the popup's ends, clear of the rounded corner. The default is the popup's corner radius plus 0.21 × the arrow's size (about 10 in the default theme). It is read when the popup mounts and again when a `Popover.Arrow` mounts or unmounts in it (not after a runtime `--radius` change), so it follows `--radius`, `--spacing` and a `rounded-*` class on `Popover.Content`. With `align` `start` or `end` next to a smaller trigger, the popup shifts so the arrow still points at the trigger's centre (with the default `center`, near a viewport edge, the arrow can be held at the padding instead). With an arrow, the focus ring is drawn on the popup's `::after`, above the arrow. It is the same ring as without an arrow, and the `::after` takes the popup's border width, so restyle it with classes under the same `has-[.PopupArrow]:focus-visible:after:` prefix (for example `has-[.PopupArrow]:focus-visible:after:outline-destructive`), or remove it with `focus-visible:after:hidden`. In RTL, set `dir="rtl"` on `<html>` or `<body>`: the popup is portalled there, so a `dir` on a wrapper element doesn't reach the arrow.

```tsx
<Popover.Root>
  <Popover.Trigger>Help</Popover.Trigger>
  <Popover.Content>
    <Popover.Arrow />
    <Popover.Title>Need help?</Popover.Title>
    <Popover.Description>
      Contact support at help@example.com.
    </Popover.Description>
  </Popover.Content>
</Popover.Root>
```

## With Close Button

```tsx
<Popover.Root>
  <Popover.Trigger>Open</Popover.Trigger>
  <Popover.Content>
    <div className="flex items-center justify-between">
      <Popover.Title>Settings</Popover.Title>
      <Popover.Close>Close</Popover.Close>
    </div>
    <Popover.Description>
      Configure your preferences here.
    </Popover.Description>
  </Popover.Content>
</Popover.Root>
```

## Positioning

The `Popover.Content` uses Base UI's built-in Floating UI integration. It has a default `sideOffset` of `8px`. You can customize placement via `side` and `align` props:

```tsx
<Popover.Content side="bottom" align="start">
  ...
</Popover.Content>
```

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`): the `popup` spring (`springs.popup`) with Motion installed, a CSS transition of `opacity` and `scale` without it; reduced motion turns off both. The popup grows out of its trigger (`origin-(--transform-origin)`); a `className` such as `origin-top` replaces it.

`render` on `Popover.Content` replaces the element the spring animates, so a popup with `render` uses the CSS transition even with Motion installed. To restyle the popup, pass `className`.

## Compound Parts

| Part | Description |
|---|---|
| `Popover.Root` | State container. Manages open/close. |
| `Popover.Trigger` | Element that toggles the popover. |
| `Popover.Content` | Portal + positioner + popup panel. Default `sideOffset={8}`. Accepts `side`, `align`, `alignOffset`, `arrowPadding` props. With nothing tabbable inside, the popup takes focus itself. After keyboard use it then shows the library focus ring: 2px of `--ring`, 2px outside its edge. |
| `Popover.Arrow` | Arrow on the popup edge that faces the trigger, in the popup's `--popover` background and `--border` colour. Place it inside `Popover.Content`. |
| `Popover.Title` | Popover heading. Semibold `text-sm`. |
| `Popover.Description` | Supporting text. `text-muted-foreground`. |
| `Popover.Close` | Button that closes the popover. |

## Popover.Root Props

All props are forwarded to the underlying Base UI [`Popover.Root`](https://base-ui.com/react/components/popover#api-reference).

Disabling `Popover.Trigger` does not close an open popover. When you disable it, close the popover yourself (set `open` to `false`).

## Popover.Content Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<PopoverContentProps, 'sideOffset' | 'side' | 'align' | 'alignOffset' | 'arrowPadding'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Popover.Popup`](https://base-ui.com/react/components/popover#api-reference).

---

# Progress

A progress bar built on Base UI's `Progress` primitive. Supports determinate values and an indeterminate loading state.

## Import

```tsx
import { Progress } from "chunks-ui";
```

## Basic Usage

Pass `value` and `max` to show a determinate progress bar:

```tsx
<Progress.Root value={65} max={100} aria-label="Upload progress">
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
```

## Indeterminate

Pass `value={null}` to activate the indeterminate pulse animation:

```tsx
<Progress.Root value={null} aria-label="Loading">
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
```

To replace the pulse, add a `data-indeterminate:animate-*` class to the indicator, such as `data-indeterminate:animate-none`. An `animate-*` class without the `data-indeterminate:` prefix does not replace it.

### Reduced motion

With `prefers-reduced-motion: reduce`, the indeterminate pulse keeps running. It is an essential status indicator, like the [Loader](/components/loader) spinner: without it, an indeterminate bar is a static block that gives no sign of activity. To stop the pulse with reduced motion, add `data-indeterminate:motion-reduce:animate-none` to the indicator. The determinate bar does not transition its width, so it jumps to each new value.

## Animated

Use state and an interval to animate progress. This example includes play, pause, and reset controls:

## Multiple Values

## Compound Parts

| Part | Description |
|---|---|
| `Progress.Root` | State container. Holds `value`, `max`, and exposes `data-indeterminate` when no value is set. |
| `Progress.Track` | The background rail. Full-width pill shape. |
| `Progress.Indicator` | Fills the track proportionally. Pulses when indeterminate. |

## Props

All parts accept the props from their corresponding Base UI [`Progress`](https://base-ui.com/react/components/progress#api-reference) sub-components.

---

# Radio

Radio buttons built on Base UI's `Radio` and `RadioGroup` primitives. Includes a group wrapper for managing single-selection among multiple options.

## Import

```tsx
import { Radio } from 'chunks-ui'
```

## Basic Usage

```tsx
<Radio.Group defaultValue="option-a">
  <Radio.Item value="option-a">Option A</Radio.Item>
  <Radio.Item value="option-b">Option B</Radio.Item>
  <Radio.Item value="option-c">Option C</Radio.Item>
</Radio.Group>
```

## Controlled

`Radio.Group` infers the type of its value from `value` or `defaultValue`, so a typed `useState` setter is an `onValueChange`:

```tsx
function ControlledRadio() {
  const [value, setValue] = useState<'a' | 'b'>('a')

return (
    <Radio.Group value={value} onValueChange={setValue}>
      <Radio.Item value="a">Option A</Radio.Item>
      <Radio.Item value="b">Option B</Radio.Item>
    </Radio.Group>
  )
}
```

## Disabled

Disable individual radio buttons or the entire group:

```tsx
<Radio.Group disabled>
  <Radio.Item value="a">Disabled option</Radio.Item>
</Radio.Group>
```

A disabled `Radio.Root` dims and shows a not-allowed cursor on its own too, outside `Radio.Item` and in a group that isn't disabled. Inside a disabled `Radio.Group` or a disabled `Radio.Item`, the radio is dimmed once with them, not twice. `Radio.Item` dims its radio and its text together whichever disables the radio: its own `disabled`, its `Radio.Group` or a `Field.Root` around them.

```tsx
<Radio.Group defaultValue="free" aria-label="Plan">
  <Radio.Root value="free" aria-label="Free">
    <Radio.Indicator />
  </Radio.Root>
  <Radio.Root value="pro" aria-label="Pro" disabled>
    <Radio.Indicator />
  </Radio.Root>
</Radio.Group>
```

The `Radio.Item` dim is keyed on the radio's `data-disabled`, so an override in `className` on `Radio.Item` is spelled with the same variant; a plain `opacity-75` loses to it:

```tsx
<Radio.Item value="pro" disabled className="has-[>[data-disabled]]:opacity-75">Pro</Radio.Item>
```

That holds for the item's own `disabled`. In a disabled `Radio.Group`, or a group inside a disabled `Field.Root`, the group carries the dim and the item turns its own off, so override it there on `Radio.Group` with `data-disabled:opacity-75`:

```tsx
<Radio.Group disabled className="data-disabled:opacity-75" aria-label="Plan">
  <Radio.Item value="pro">Pro</Radio.Item>
</Radio.Group>
```

## Compound Parts

| Part              | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `Radio.Group`     | Wrapper that manages value state. Renders a vertical flex column by default. |
| `Radio.Item`      | Convenience compound: label + radio + indicator in one element.              |
| `Radio.Root`      | Individual radio button. Renders a circular control.                         |
| `Radio.Indicator` | The inner dot that appears when the radio is selected. Children you pass replace the dot; with a `render` element and no children, there is no dot, and the element may be a void element such as `<img>`. Your content scales and fades in and out as the dot does. |

## Radio.Group Props

All props are forwarded to the underlying Base UI [`RadioGroup`](https://base-ui.com/react/components/radio-group#api-reference).

## Radio.Item Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<RadioItemProps, 'children' | 'className'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI [`Radio.Root`](https://base-ui.com/react/components/radio-group#api-reference). `className` is the exception: it goes on the item's `<label>`, and it takes a string only. To style the radio itself, build the item from `Radio.Root` and `Radio.Indicator`.

## Radio.Root Props

All props are forwarded to the underlying Base UI [`Radio.Root`](https://base-ui.com/react/components/radio-group#api-reference).

---

ResizableHorizontalExample,
  ResizableVerticalExample,
  ResizableMixedExample,
  ResizableNestedExample,
  ResizableControlledExample,
  ResizableGripExample,
} from '@/examples/Resizable'

# Resizable

A split-pane layout: two or more panels in a row or a column, with a draggable, keyboard-operable handle between each pair. Built for master/detail screens, editors with a terminal, and inspector sidebars. Sizes are in px, in %, or both, and the layout can be saved and restored with no storage code in the component.

## Import

```tsx
import { Resizable, sanitizeLayout } from "chunks-ui";
```

## Basic Usage

`Resizable.Group` holds the panels. Put a `Resizable.Handle` between each two. Every panel needs a stable `id`: the name its size goes by in a [layout](#layout-and-controlled-use). The `id` is a layout key only. It is not the panel's DOM `id`: the DOM `id` is generated, so two groups on one page (or in tabs, or in a list of cards) can reuse the same names without a clash. The panel carries its key as `data-panel-id`, which is what a test or a style rule can select by. Keep each `id` unique within its group. `__proto__` is not a valid `id`, and a panel that uses it is treated as having none: it still renders and resizes, under a generated key that `onLayoutChange` reports but a saved layout can't count on (`sanitizeLayout` drops it), and development builds warn. Give the group a size, since it fills its parent:

```tsx
<Resizable.Group className="h-48 w-full" aria-label="Sidebar and content">
  <Resizable.Panel id="side" defaultSize="30%" minSize="15%" maxSize="60%">
    Sidebar
  </Resizable.Panel>
  <Resizable.Handle aria-label="Resize sidebar" />
  <Resizable.Panel id="main">Content</Resizable.Panel>
</Resizable.Group>
```

Drag a handle, or focus it and use the keys below. A handle resizes the panel before it and the panel after it. A drag or key step commits the layout as the group shows it, so a panel the group had to fit (held at a px `minSize`, shrunk or stretched) keeps what it showed: a px panel its px size, a % panel the share of the group it had then, which grows and shrinks with the group from there.

## Vertical

Set `orientation="vertical"` on the group to stack the panels. The handle lines then run horizontally, and the up and down arrow keys move them. A vertical group fills its parent's height, so give the group or its parent a height (`h-64` below). Without one the group is only as tall as its content, and a drag changes nothing on screen.

```tsx
<Resizable.Group orientation="vertical" className="h-64 w-full" aria-label="Editor and terminal">
  <Resizable.Panel id="editor" defaultSize="65%" minSize="20%">
    Editor
  </Resizable.Panel>
  <Resizable.Handle aria-label="Resize terminal" />
  <Resizable.Panel id="terminal" minSize="15%">
    Terminal
  </Resizable.Panel>
</Resizable.Group>
```

## Sizes: px and %

`defaultSize`, `minSize` and `maxSize` take a number (px) or a string with a unit: `240`, `"240px"` and `"30%"` are all valid. The unit of `defaultSize` is the unit of the panel: it decides how the panel's value reads in a layout (see [Layout](#layout-and-controlled-use)). A panel without a `defaultSize` is a % panel.

- A **px panel** keeps its size when the group resizes, as long as the % panels can take the change.
- A **% panel** takes a share of what the px panels and the handles leave. In a group with no px panel that is a share of the whole group. The shares of a group's % panels always add up to 100: values that don't are scaled, so `20%` and `20%` are two halves. A % panel grows and shrinks with the group.
- `minSize` and `maxSize` are limits in either unit, whatever the unit of the panel. A limit in % is a percent of the group (minus its handles). Both neighbours' limits bind a handle, so it stops when either panel reaches one.
- When the % panels can't take all of the change (there are none, or they are at their `minSize` or `maxSize`), the px panels share the rest. A group of px panels only still fills its width, up to their `maxSize`s: `200` and `300` show at about 450px and 550px in a 1000px group.
- A px panel wider than the group is shrunk to fit. A % panel with a px `minSize` the group is too small for is held at that size, and goes back to its share when the group grows. A drag or key step in between commits the share it is held at, and the panel keeps that share: a `34%` panel held at 300px in a 500px group keeps 60%, about 720px of a 1200px group.

```tsx
<Resizable.Group className="h-48 w-full" aria-label="Folders, list and detail">
  <Resizable.Panel id="folders" defaultSize={160} minSize={120} maxSize={280}>
    Folders
  </Resizable.Panel>
  <Resizable.Handle aria-label="Resize folders" />
  <Resizable.Panel id="list" defaultSize="40%" minSize="20%">
    List
  </Resizable.Panel>
  <Resizable.Handle aria-label="Resize list" />
  <Resizable.Panel id="detail" defaultSize="60%" minSize="20%">
    Detail
  </Resizable.Panel>
</Resizable.Group>
```

Don't put padding or a border on a `Resizable.Panel`. The browser takes them off before it shares the space, which skews the sizes and makes the handle drift from the pointer. Put them on an element inside the panel, as the examples do. Development builds warn when a panel has either.

The group may be a flex box with a `gap` (`gap-2`, say): the measure takes the gap between its children off before sharing the space, so the handle still follows the pointer. A gap in % is not counted. Padding and border on the group itself are counted off too.

## Nested groups

For a layout that splits both ways, put a group inside a panel. Each group has its own orientation, handles and layout:

```tsx
<Resizable.Group className="h-64 w-full" aria-label="Files and workspace">
  <Resizable.Panel id="files" defaultSize="30%" minSize="15%">
    Files
  </Resizable.Panel>
  <Resizable.Handle aria-label="Resize files" />
  <Resizable.Panel id="workspace" defaultSize="70%">
    <Resizable.Group orientation="vertical" aria-label="Editor and terminal">
      <Resizable.Panel id="editor" defaultSize="70%" minSize="20%">
        Editor
      </Resizable.Panel>
      <Resizable.Handle aria-label="Resize terminal" />
      <Resizable.Panel id="terminal" minSize="15%">
        Terminal
      </Resizable.Panel>
    </Resizable.Group>
  </Resizable.Panel>
</Resizable.Group>
```

## Grip

A 1px line is easy to miss. `Resizable.Grip` is an optional part you put inside a handle: a small rounded pill centred on the line with a few dots in it, so users can see it can be dragged.

```tsx
<Resizable.Handle aria-label="Resize sidebar">
  <Resizable.Grip />
</Resizable.Handle>
```

The grip is decorative. It has `aria-hidden="true"`, is not focusable and has `pointer-events: none`, so a press that lands on it starts the drag of the handle under it, and the handle keeps its role, values and keys. It follows the group's orientation and the handle's hover, drag and focus state, and it keeps a visible border in forced-colors mode. Pass `className` to restyle it.

It takes the props of a `div`; `className` replaces the library's classes where they conflict (`rounded-full` for a round pill, say). The dots are drawn by CSS, so there is no icon to supply.

## Layout and controlled use

A layout maps each panel `id` to its size, in the unit that panel declares: px for a px panel, a share for a % panel.

```ts
type ResizableLayout = Record<string, number>;

// { folders: 160, list: 40, detail: 60 }
```

Three props on the group carry it:

- `defaultLayout` is where the group starts. It is read once, at the first render, so the server's HTML has the right sizes too.
- `layout` makes the group controlled: it shows this layout, fitted to the panels' limits and the group's size. A change is reported to `onLayoutChange`, and applied only once you pass the new layout back. If you don't, the panels return to your layout.
- `onLayoutChange(layout)` is called with the whole layout once per change a user commits: when the pointer is released after a drag, and on each key step. It is not called on mount, while a drag is in progress, when the window or the group resizes, or when a key can't move the handle (it is at its limit). There is no per-pointer-move callback. A drag writes the sizes straight to the DOM and React hears of it on release.

```tsx
import { type ResizableLayout, Resizable } from "chunks-ui";
import { useState } from "react";

function ControlledSplit() {
  const [layout, setLayout] = useState<ResizableLayout>({ left: 50, right: 50 });

return (
    <Resizable.Group layout={layout} onLayoutChange={setLayout} className="h-32 w-full">
      <Resizable.Panel id="left" minSize="20%" maxSize="80%">
        Left
      </Resizable.Panel>
      <Resizable.Handle aria-label="Resize left" />
      <Resizable.Panel id="right" minSize="20%">
        Right
      </Resizable.Panel>
    </Resizable.Group>
  );
}
```

Update the state synchronously in `onLayoutChange`, as above. A parent that applies the new layout later (inside `startTransition`, after a router navigation, after a request) makes the group snap back to the old layout on release and then jump to the new one when it arrives, because the group shows the `layout` it is given at every render. To save the layout somewhere slow, set the state at once and write to the slow place from an effect or a debounce.

Both props go through `sanitizeLayout`, so a layout that doesn't fit the panels (an old one, say) never breaks the group. See [`sanitizeLayout`](#sanitizelayout).

## Persistence

The component has no storage code. It gives you `defaultLayout` to start from and `onLayoutChange` to save, and `sanitizeLayout` to make what you read back safe. Three recipes follow.

Always run what you read through `sanitizeLayout`. Storage can hold anything: an older layout, a value another tab wrote, a hand-edited URL. Always wrap reads and writes of `localStorage` in `try`/`catch`: it throws in some private windows, when site data is blocked, and when the quota is full.

**Version the key when a panel's unit changes.** A stored `30` means 30% for a % panel and 30px for a px panel, and `sanitizeLayout` can't tell which one wrote it. After changing a panel from `%` to px (or back), change the key (`panels-v1` to `panels-v2`), so old values are ignored. Adding, removing and reordering panels needs no new key: missing panels take their defaults and unknown ids are dropped.

### localStorage

For an app that renders only on the client, such as a Vite app. In a server-rendered app the server can't read `localStorage`, so the first render would differ from the stored layout: use the cookie recipe.

```tsx
import { type ResizablePanelConfig, type ResizableLayout, Resizable, sanitizeLayout } from "chunks-ui";
import { useState } from "react";

const PANELS = [
  { id: "list", defaultSize: "30%", minSize: "15%" },
  { id: "detail", defaultSize: "70%" },
] satisfies ResizablePanelConfig[];

// Version the key when a panel changes between px and %
const KEY = "panels-v1";

function readLayout(): ResizableLayout {
  try {
    return sanitizeLayout(JSON.parse(localStorage.getItem(KEY) ?? "null"), PANELS);
  } catch {
    return sanitizeLayout(null, PANELS);
  }
}

function writeLayout(layout: ResizableLayout) {
  try {
    localStorage.setItem(KEY, JSON.stringify(layout));
  } catch {
    // Storage is blocked or full: the layout is simply not remembered
  }
}

function MasterDetail() {
  const [initial] = useState(readLayout);

return (
    <Resizable.Group defaultLayout={initial} onLayoutChange={writeLayout} className="h-96 w-full">
      <Resizable.Panel id="list" defaultSize="30%" minSize="15%">
        List
      </Resizable.Panel>
      <Resizable.Handle aria-label="Resize list" />
      <Resizable.Panel id="detail" defaultSize="70%">
        Detail
      </Resizable.Panel>
    </Resizable.Group>
  );
}
```

### Cookie with server rendering

The server reads the cookie and passes the layout as `defaultLayout`, so the first paint already has the saved sizes. With % panels and % limits only, that is the final layout: no flash, no jump after hydration. A px panel or a px limit can only be checked against the measured group, so a layout that doesn't fit the group (the defaults in a narrow window too, or a layout saved at another window size) is corrected after hydration (see [`sanitizeLayout`](#sanitizelayout)). Each panel's size is the fallback of its CSS variable in its inline style, and `defaultLayout` is read at the first render. This is a Next.js App Router page; any server that can read the request's cookies works the same.

A cookie that only remembers a layout is a functional preference: it holds something the user set and nothing that identifies them. It is often treated as needing no consent banner. The rules differ by country and some regulators ask for a short lifetime, so check the ones that apply to you.

```tsx
// app/page.tsx (a server component)
import { cookies } from "next/headers";
import { sanitizeLayout } from "chunks-ui/utils";
import { MasterDetail } from "./master-detail";
import { COOKIE, PANELS } from "./panels";

export default async function Page() {
  const stored = (await cookies()).get(COOKIE)?.value;
  let raw: unknown = null;
  try {
    // Next has decoded the value already: it is the JSON the browser wrote
    raw = JSON.parse(stored ?? "null");
  } catch {
    // A cookie that isn't JSON gives the defaults
  }
  return <MasterDetail defaultLayout={sanitizeLayout(raw, PANELS)} />;
}
```

```tsx
// app/panels.ts (no "use client": the server reads it too)
import type { ResizablePanelConfig } from "chunks-ui/utils";

export const COOKIE = "panels-v1"; // change it when a panel changes between px and %

export const PANELS = [
  { id: "list", defaultSize: "30%", minSize: "15%" },
  { id: "detail", defaultSize: "70%" },
] satisfies ResizablePanelConfig[];
```

```tsx
// app/master-detail.tsx
"use client";

import { type ResizableLayout, Resizable, sanitizeLayout } from "chunks-ui";
import { useState } from "react";
import { COOKIE, PANELS } from "./panels";

export function MasterDetail({ defaultLayout }: { defaultLayout: ResizableLayout }) {
  // On a first load the cookie is what the server read, so the layouts match and hydration is clean
  const [initial] = useState(() =>
    typeof document === "undefined" ? defaultLayout : (readCookie() ?? defaultLayout),
  );

return (
    <Resizable.Group defaultLayout={initial} onLayoutChange={saveLayout} className="h-96 w-full">
      <Resizable.Panel id="list" defaultSize="30%" minSize="15%">
        List
      </Resizable.Panel>
      <Resizable.Handle aria-label="Resize list" />
      <Resizable.Panel id="detail" defaultSize="70%">
        Detail
      </Resizable.Panel>
    </Resizable.Group>
  );
}
```

Reading `cookies()` makes the route render on every request (dynamic rendering). With `cacheComponents` on, read it inside a `<Suspense>` boundary, or the build fails. Next decodes cookie values, so the page parses `value` as it is; on a server that doesn't, decode it yourself first.

The client component reads the cookie again in its `useState` initializer. On a first load that is the value the server read, so hydration matches. Back and Forward reuse the server's first answer for a page, which can be older than the cookie, and the client's read makes the newer layout win. The browser's cookie string is still encoded, so `readCookie` decodes the value before it parses it.

The server page imports `sanitizeLayout` from `chunks-ui/utils`, not from `chunks-ui`. The main entry starts with `"use client"`, so a Server Component that imports `sanitizeLayout` from it gets a client reference, and calling that on the server throws. `chunks-ui/utils` is built without the banner and holds the React-free helpers, `sanitizeLayout` and the `ResizableLayout` and `ResizablePanelConfig` types among them, so a server can call them. `PANELS` and `COOKIE` live in a plain module for the same reason: a module marked `"use client"` hands the server a reference too, not the value. The server still renders each panel's `defaultSize` as the fallback for a panel with no stored value, so give every % panel a `defaultSize`.

### URL

A layout in the query string survives a reload and can be shared as a link. `history.replaceState` changes the address without adding a history entry for every drag. Browsers limit how often it can be called: Safari throws a `SecurityError` after 100 calls in 10 seconds, and Firefox ignores calls past its limit. A held arrow key commits once per repeat, so debounce the write and keep the `try`/`catch` for Safari. Like the `localStorage` recipe, this one is for a page that renders only on the client: `readUrl` reads `location`, which a server doesn't have. `useState(readUrl)` reads the URL once, on the first render, not on every render.

```tsx
import { type ResizablePanelConfig, type ResizableLayout, Resizable, sanitizeLayout } from "chunks-ui";
import { useState } from "react";

const PANELS = [
  { id: "list", defaultSize: "30%", minSize: "15%" },
  { id: "detail", defaultSize: "70%" },
] satisfies ResizablePanelConfig[];

const PARAM = "panels-v1";

let timer: ReturnType<typeof setTimeout> | undefined;

// Writes once the changes stop: a held arrow key commits on every repeat
function writeUrl(layout: ResizableLayout) {
  const page = location.pathname;
  clearTimeout(timer);
  timer = setTimeout(() => {
    // A router went to another page in the meantime: this layout is not that page's
    if (location.pathname !== page) return;
    const url = new URL(location.href);
    url.searchParams.set(PARAM, JSON.stringify(layout));
    try {
      history.replaceState(history.state, "", url);
    } catch {
      // Safari throws a SecurityError when replaceState is called too often
    }
  }, 300);
}

function UrlSplit() {
  const [initial] = useState(readUrl);

return (
    <Resizable.Group defaultLayout={initial} onLayoutChange={writeUrl} className="h-96 w-full">
      <Resizable.Panel id="list" defaultSize="30%" minSize="15%">
        List
      </Resizable.Panel>
      <Resizable.Handle aria-label="Resize list" />
      <Resizable.Panel id="detail" defaultSize="70%">
        Detail
      </Resizable.Panel>
    </Resizable.Group>
  );
}
```

A change made less than 300ms before the user leaves or reloads the page is not written.

On a server-rendered page don't call `readUrl` during render. Read the same parameter from the request on the server, as the cookie recipe does, and pass it down.

## `sanitizeLayout`

```ts
function sanitizeLayout(raw: unknown, panels: readonly ResizablePanelConfig[]): ResizableLayout;
```

Makes a layout that came from storage safe to use. `panels` is a list of `{ id, defaultSize?, minSize?, maxSize? }`, the same fields as the panels' props. It never throws.

- Input that is not a plain object (`null`, a string, an array, `undefined`) gives the defaults.
- Ids that match no panel are dropped.
- A panel whose `id` is empty or `__proto__`, or that repeats the `id` of an earlier panel, is skipped.
- A missing value, or one that is not a finite, non-negative number, is filled from the panel's default. Missing % panels take what the others leave of 100.
- A px panel is clamped to its px `minSize` and `maxSize`.
- The % shares are scaled to add up to 100. In a group of % panels only, they are also clamped to the panels' % `minSize` and `maxSize`, and the difference goes to the panels that have room, so the result is inside the limits and still adds up to 100 (`{ side: 99, main: 1 }` with `side` at most `60%` gives `{ side: 60, main: 40 }`).
- When the group has a px panel, a % limit is a percent of the measured size, which the server doesn't have. `sanitizeLayout` then leaves % limits out, and the group applies them once it has measured. So does a limit in the other unit of a panel.

## Keyboard

A handle is a focusable separator. These keys work with it focused:

| Key | Action |
|---|---|
| `ArrowRight` / `ArrowLeft` | In a horizontal group, move the handle by 1% of the group. In RTL the two swap, so the key that points toward the end of the line still moves the handle that way. |
| `ArrowDown` / `ArrowUp` | In a vertical group, move the handle by 1% of the group. |
| `Shift` + an arrow | Move by 10% of the group. |
| `Home` | Move to the smallest size of the panel before the handle, or as far as the panel after it allows. |
| `End` | Move to the largest size of the panel before the handle, or as far as the panel after it allows. |

Each key press that moves the handle is one committed change: `onLayoutChange` is called once per press, also while a key is held. A press that can't move the handle calls nothing. The arrows of the other axis do nothing.

## Accessibility

`Resizable.Handle` follows the [WAI-ARIA window splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/) pattern:

- `role="separator"`, focusable with `tabindex="0"` once it has its values. A focusable separator needs `aria-valuenow`, so a handle without a panel on each side is not focusable, and neither is a handle in a group with a px panel until the group has measured.
- `aria-orientation` is the orientation of the separator line, as the pattern defines it: a horizontal group (panels side by side) has `"vertical"` lines. The handle's `data-orientation` has the same value.
- `aria-valuenow` is the size of the panel before the handle, as a percent of the group. `aria-valuemin` and `aria-valuemax` are the range the handle can move that panel to, given the limits of both neighbours. They update while dragging.
- `aria-controls` lists the DOM `id`s of the two panels it resizes (the generated ones, not the layout keys).
- A disabled handle is out of the tab order and has `aria-disabled="true"`.

Give each handle an accessible name with `aria-label` ("Resize sidebar") or `aria-labelledby`: the component has no built-in text, so there is nothing to translate. `Resizable.Group` has `role="group"`; label it too when the page holds more than one.

The server's HTML has the panels' sizes but not the handles' `aria-value*` and `aria-controls`: they depend on the panels' order and the group's measured size, so they appear at hydration. A handle joins the tab order then too.

### Right to left

Everything follows the writing direction, which the component reads from the group's computed `direction`. In RTL the first panel sits at the right, dragging toward the left grows it, and the horizontal arrow keys swap. `Home` and `End` do not: they go to the smallest and the largest size of the panel before the handle. Nothing in the component uses a physical left or right, so a `dir="rtl"` on any ancestor is enough.

### Pointer and touch

A drag uses pointer events with pointer capture, so it works with a mouse, a pen and a finger, and keeps going when the pointer leaves the thin handle. The handle has `touch-action: none` so a touch drag doesn't scroll the page. Its hit area is wider than the line: 12px with a mouse and 44px on a touch screen (the `touch-target` utility). The hit area reaches about 6px (mouse) or 22px (touch) into each neighbouring panel and takes presses there, so keep buttons and links that far from the line. While dragging, the page's text selection is switched off and the cursor stays a resize cursor. A drag that is cancelled (the system takes the pointer, the component unmounting) puts the sizes back and calls nothing.

## Styling

The handle is a 1px line in `bg-border` that turns `bg-ring` on hover and while dragging. Pass `className` to change it. State is on data attributes, so use Tailwind's `data-*` variants:

| Part | Attribute | Meaning |
|---|---|---|
| `Resizable.Group` | `data-orientation` | `horizontal` or `vertical`: the axis of the panels |
| `Resizable.Handle` | `data-orientation` | The orientation of its line, as `aria-orientation`: `vertical` in a horizontal group |
| `Resizable.Panel` | `data-panel-id` | The panel's `id`, its layout key |
| `Resizable.Handle` | `data-dragging` | Present while a drag is in progress |
| `Resizable.Handle` | `data-disabled` | Present when disabled |

A `Resizable.Grip` reads these from its handle (`group-data-dragging/handle:`, `group-data-[orientation=vertical]/handle:`), so a handle you restyle can restyle its grip the same way.

```tsx
<Resizable.Handle
  aria-label="Resize sidebar"
  className="data-dragging:bg-primary data-[orientation=vertical]:w-0.5"
/>
```

## Not supported

- **Collapsing a panel to zero** (a handle that snaps it shut). A panel stops at its `minSize`, which is 0 when unset, so a panel without one can be dragged down to 0. For a collapsible sidebar, render the panel and its handle, or neither.
- **Motion.** Resizing is direct manipulation, and sizes never animate.
- **Resetting on double click.** To offer a reset, keep the layout in state (the controlled `layout` prop) and set it back.
- **A storage hook.** The recipes above are a few lines each; the component stays free of storage code.
- **Padding or a border on a panel.** See [Sizes](#sizes-px-and-).

## Props

### Resizable.Group

A `div` with `role="group"`. It takes the props of a `div`, plus:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ResizableGroupProps, 'orientation' | 'defaultLayout' | 'layout' | 'onLayoutChange'>
export default Props
`
  })}
/>

### Resizable.Panel

A `div`. It takes the props of a `div`, plus the required `id`, which is a layout key and not the DOM `id`:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ResizablePanelProps, 'id' | 'defaultSize' | 'minSize' | 'maxSize'>
export default Props
`
  })}
/>

### Resizable.Handle

A `div` with `role="separator"`. It takes the props of a `div`, plus:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ResizableHandleProps, 'disabled'>
export default Props
`
  })}
/>

### Resizable.Grip

An optional, decorative `div` that goes inside a `Resizable.Handle`. It takes the props of a `div` and no others; `aria-hidden` is always `"true"`.

---

# ScrollArea

A custom scrollable container built on Base UI's `ScrollArea` primitive. Hides native scrollbars and replaces them with styled overlays that appear on hover or scroll.

## Import

```tsx
import { ScrollArea } from "chunks-ui";
```

## Basic Usage

Vertical scrolling — constrain height on the root and the scrollbar renders automatically:

```tsx
<ScrollArea.Root className="h-64 w-full rounded border border-border">
  <ScrollArea.Viewport>
    <ScrollArea.Content>
      {/* tall content */}
    </ScrollArea.Content>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar orientation="vertical">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
</ScrollArea.Root>
```

## Horizontal Scrollbar

Set `orientation="horizontal"` on the scrollbar for wide content:

```tsx
<ScrollArea.Root className="w-full rounded border border-border">
  <ScrollArea.Viewport>
    <ScrollArea.Content>{/* wide content */}</ScrollArea.Content>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar orientation="horizontal">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
</ScrollArea.Root>
```

## Both Axes

Add both scrollbars and `ScrollArea.Corner` to fill the intersection:

```tsx
<ScrollArea.Root className="h-48 w-full rounded border border-border">
  <ScrollArea.Viewport>
    <ScrollArea.Content>{/* tall + wide content */}</ScrollArea.Content>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar orientation="vertical">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Scrollbar orientation="horizontal">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `ScrollArea.Root` | Outer container. Sets `overflow: hidden` and positions scrollbars. |
| `ScrollArea.Viewport` | The scrollable window. Native scrollbars are hidden via CSS. |
| `ScrollArea.Content` | Wraps the actual content inside the viewport. |
| `ScrollArea.Scrollbar` | The custom scrollbar track. Fades in on hover/scroll via `data-hovering` and `data-scrolling`. |
| `ScrollArea.Thumb` | The draggable scrollbar handle. Expands the hit area with a negative margin. |
| `ScrollArea.Corner` | Fills the corner square when both scrollbars are visible. |

## Props

All parts accept the props from their corresponding Base UI [`ScrollArea`](https://base-ui.com/react/components/scroll-area#api-reference) sub-components.

---

# Select

A styled single-select dropdown built on Base UI's `Select` primitive. Includes trigger, popup, items, grouped options, and built-in Floating UI positioning.

## Import

```tsx
import { Select } from "chunks-ui";
```

## Basic Usage

```tsx
const fruits = {
  apple: "Apple",
  banana: "Banana",
  cherry: "Cherry",
  strawberry: "Strawberry",
};

<Select.Root items={fruits}>
  <Select.Trigger aria-label="Fruit">
    <Select.Value placeholder="Choose a fruit" />
    <Select.Icon />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner sideOffset={5} alignItemWithTrigger={false}>
      <Select.Popup>
        <Select.Item value="apple">
          <Select.ItemText>Apple</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Item value="banana">
          <Select.ItemText>Banana</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Item value="cherry">
          <Select.ItemText>Cherry</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Item value="strawberry" disabled>
          <Select.ItemText>Strawberry</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>
```

## Grouped Options

```tsx
const colors = {
  red: "Red",
  orange: "Orange",
  blue: "Blue",
  green: "Green",
};

<Select.Root items={colors}>
  <Select.Trigger aria-label="Color">
    <Select.Value placeholder="Pick a color" />
    <Select.Icon />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner sideOffset={5} alignItemWithTrigger={false}>
      <Select.Popup>
        <Select.Group>
          <Select.GroupLabel className="uppercase">Warm</Select.GroupLabel>
          <Select.Item value="red">
            <Select.ItemText>Red</Select.ItemText>
            <Select.ItemIndicator />
          </Select.Item>
          <Select.Item value="orange">
            <Select.ItemText>Orange</Select.ItemText>
            <Select.ItemIndicator />
          </Select.Item>
        </Select.Group>
        <Select.Group>
          <Select.GroupLabel className="uppercase">Cool</Select.GroupLabel>
          <Select.Item value="blue">
            <Select.ItemText>Blue</Select.ItemText>
            <Select.ItemIndicator />
          </Select.Item>
          <Select.Item value="green">
            <Select.ItemText>Green</Select.ItemText>
            <Select.ItemIndicator />
          </Select.Item>
        </Select.Group>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>
```

## Controlled

```tsx
const statuses = {
  active: "Active",
  inactive: "Inactive",
};

function ControlledSelect() {
  const [value, setValue] = useState<string | null>(null);

return (
    <Select.Root items={statuses} value={value} onValueChange={setValue}>
      <Select.Trigger aria-label="Status">
        <Select.Value placeholder="Select status" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner sideOffset={5} alignItemWithTrigger={false}>
          <Select.Popup>
            <Select.Item value="active">
              <Select.ItemText>Active</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
            <Select.Item value="inactive">
              <Select.ItemText>Inactive</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          </Select.Popup>
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
}
```

## Disabled

A disabled `Select` is dimmed and shows the not-allowed cursor. The `disabled` prop disables it, and so does a disabled `Field.Root`, Base UI's `Fieldset` or a `<fieldset disabled>`. A disabled `Select` stays closed whatever `open` and `defaultOpen` say, and it ignores a pick. Disabling a `Select` with an open listbox closes the listbox without calling `onOpenChange`. When it is enabled again, a controlled listbox opens if `open` is `true`; an uncontrolled one stays closed. The `disabled` prop acts at once; the other causes act when the `Select` next renders, because it reads the disabled state of its form input after each render, and until then a pick in an open listbox is ignored and closes it. When a disabled `Select`'s listbox closes with focus in it, focus moves to the page, as it does when any focused control is disabled.

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`): the `popup` spring (`springs.popup`) with Motion installed, a CSS transition of `opacity` and `scale` without it; reduced motion turns off both. Aligned over its trigger (the default), the popup only fades; below the trigger (`alignItemWithTrigger={false}`), it grows out of the trigger (`origin-(--transform-origin)`), and a `className` such as `origin-top` replaces that origin. On the CSS path, `data-[side=none]:data-starting-style:scale-95` and its `data-ending-style` pair bring the scale back to an aligned popup.

`render` on `Select.Popup` replaces the element the spring animates, so a popup with `render` uses the CSS transition even with Motion installed. To restyle the popup, pass `className`.

## Compound Parts

| Part | Description |
|---|---|
| `Select.Root` | State container. Manages open/close and selected value. `items` makes the trigger show the selected item's label: pass an object that maps each `value` to its label (`{ cherry: "Cherry" }`), or an array of `{ value, label }`. |
| `Select.Trigger` | The button that opens the dropdown. Styled like an input. At most as wide as its container (`max-w-full`), and it shrinks in a flex row (`min-w-0`); `max-w-none` lifts the cap. |
| `Select.Value` | Displays the label of the selected item, or the placeholder text. The label comes from `items` on `Select.Root`. Without `items`, `itemToStringLabel` or a function as children, a string value shows as is (`cherry`, not `Cherry`). A value wider than the trigger stays on one line and ends in an ellipsis before the chevron. It fills the trigger's free space (`flex-1`), so an element beside it, such as a badge, keeps its width and the value truncates first; `flex-initial` in `className` sizes it by its text instead. In a right-to-left trigger, a long Latin value shows its last words: the line starts at the right edge, so its first words overflow on the left. `dir="auto"` on the value takes the direction from its first letter: a Latin value then shows its first words and sits at the left, and a right-to-left value stays at the right. |
| `Select.Icon` | Chevron icon inside the trigger. Children you pass replace the chevron. With a `render` element and no children, there is no chevron: the element draws its own, and may be a void element such as `<img>`. |
| `Select.Portal` | Renders the popup in a portal. |
| `Select.Positioner` | Handles Floating UI positioning. Base UI's default `alignItemWithTrigger` places the popup over the trigger, with the selected item on top of it; the examples pass `alignItemWithTrigger={false}` and `sideOffset={5}` to open it below the trigger instead. Gives the popup the trigger's width (`w-[var(--anchor-width)]`). For a trigger sized by its value, pass `w-auto min-w-[var(--anchor-width)]` in `className`: the popup is never narrower than the trigger, and its items keep their text on one line. Bare `w-auto` sizes the popup by its items. Set a width here, not on `Select.Popup`: a width on the popup spills out of the positioner, and Floating UI's collision handling measures the positioner. |
| `Select.Popup` | The dropdown panel containing items. It is as wide as the trigger, over the trigger or below it. Item text wraps to that width, and a word longer than the popup breaks; the check mark keeps its room at the item's end. |
| `Select.Item` | An individual selectable option. Put its text in `Select.ItemText`: only that wraps at the popup's width, so text placed straight in the item can run past a narrow popup. |
| `Select.ItemText` | The text content of an item. It wraps at the popup's width and breaks a word longer than that; a badge or shortcut beside it keeps its width. |
| `Select.ItemIndicator` | Checkmark shown for the selected item. Children you pass replace the checkmark. With a `render` element and no children, there is no checkmark: the element draws its own, and may be a void element such as `<img>`. The indicator is `aria-hidden`, so screen readers skip its children and announce the option's selected state instead. |
| `Select.Group` | Groups related items together. |
| `Select.GroupLabel` | Label for a group of items. |

## Text Size

The text of `Select.Trigger` has the size of the text fields: 16px below the `md` breakpoint (768px by default) and on a touch screen, and 14px otherwise, so a form has one text size. The items follow the field size too, as a popup not opened by touch lays the selected item over the trigger's value; where the text is 16px, an item is 4px taller (36px). A text-size class on `Select.Trigger` or `Select.Item` follows the same rules as on an `Input`. A size class meant for the whole field goes on both `Select.Trigger` and `Select.Item`, or the item opens over the value at a different size. See [Text Size](/components/input#text-size) in `Input`.

## Props

All parts accept the props from their corresponding Base UI [`Select`](https://base-ui.com/react/components/select#api-reference) sub-components.

---

# Separator

A visual divider built on Base UI's `Separator` primitive. Supports horizontal and vertical orientations.

## Import

```tsx
import { Separator } from "chunks-ui";
```

## Basic Usage

Horizontal separator (default):

```tsx
<div>
  <p>Content above</p>
  <Separator />
  <p>Content below</p>
</div>
```

## Vertical

```tsx
<div className="flex h-8 items-center gap-4">
  <span>Left</span>
  <Separator orientation="vertical" />
  <span>Right</span>
</div>
```

## In a List

```tsx
<div className="flex flex-col">
  <div className="py-2">Item 1</div>
  <Separator />
  <div className="py-2">Item 2</div>
  <Separator />
  <div className="py-2">Item 3</div>
</div>
```

## Props

This component accepts all props from the underlying Base UI [`Separator`](https://base-ui.com/react/components/separator#api-reference).

## Styling

- Horizontal: `h-px w-full` with `bg-border`
- Vertical: `w-px h-full` with `bg-border`

---

# Skeleton

A placeholder loading indicator. CSS-only animation with `animate-pulse` on a muted background. Use className to control size and shape.

## Import

```tsx
import { Skeleton } from "chunks-ui";
```

## Basic Usage

```tsx
<Skeleton className="h-4 w-[250px]" />
```

## Circle

```tsx
<Skeleton className="size-12 rounded-full" />
```

## Card Skeleton

Compose multiple skeletons to create loading placeholders for complex layouts:

```tsx
<div className="flex items-center gap-4">
  <Skeleton className="size-12 rounded-full" />
  <div className="flex flex-col gap-2">
    <Skeleton className="h-4 w-[180px]" />
    <Skeleton className="h-3 w-[120px]" />
  </div>
</div>
```

## Props

This component accepts all standard `<div>` props. Use `className` to control size, shape, and border radius.

---

# Slider

A draggable range input built on Base UI's `Slider` primitive. Supports single values, ranges, horizontal and vertical orientations, and keyboard navigation.

## Import

```tsx
import { Slider } from "chunks-ui";
```

## Basic Usage

```tsx
<Slider.Root defaultValue={40}>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb aria-label="Value" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

## With Value Display

Use `Slider.Value` to display the current value. Place it anywhere inside `Slider.Root`:

```tsx
<Slider.Root defaultValue={60}>
  <div className="flex items-center justify-between">
    <span className="text-sm text-muted-foreground">Volume</span>
    <Slider.Value />
  </div>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb aria-label="Volume" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

## Range Slider

Pass an array to `defaultValue` and render a `Slider.Thumb` with `index` for each handle:

```tsx
<Slider.Root defaultValue={[20, 80]}>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb index={0} aria-label="Minimum" />
      <Slider.Thumb index={1} aria-label="Maximum" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

## Vertical Orientation

Set `orientation="vertical"` on the root. The track and indicator switch to a vertical layout. A vertical slider fills its parent's height (`h-full`), so give the parent a height, or it collapses:

```tsx
<div className="flex h-40">
  <Slider.Root defaultValue={50} orientation="vertical">
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb aria-label="Value" />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
</div>
```

## Controlled

`Slider.Root` infers whether its value is a number or an array from `value` or `defaultValue`, so a typed `useState` setter is an `onValueChange`. A range (`useState([20, 80])`) works the same way:

```tsx
function ControlledSlider() {
  const [value, setValue] = useState(50);

return (
    <Slider.Root value={value} onValueChange={setValue}>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb aria-label="Value" />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
}
```

## Disabled

A disabled `Slider` is dimmed and shows the not-allowed cursor.

```tsx
<Slider.Root defaultValue={50} disabled>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb aria-label="Value" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Slider.Root` | State container. Manages value, orientation, and disabled state. |
| `Slider.Value` | Displays the current numeric value as text. |
| `Slider.Control` | The interactive area. Handles pointer and keyboard events. |
| `Slider.Track` | The background rail. Full width (or height when vertical). |
| `Slider.Indicator` | Fills the track from origin to the current thumb position. |
| `Slider.Thumb` | The draggable handle. Requires `aria-label` for accessibility. |

## Props

All compound parts are thin style wrappers. Props are forwarded to the underlying Base UI [`Slider`](https://base-ui.com/react/components/slider#api-reference). `Slider.Root` also takes `labels`:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<SliderRootProps, 'labels'>
export default Props
`
  })}
/>

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_SLIDER_LABELS`. They are the `aria-valuetext` that Base UI gives the two thumbs of a range slider, as functions of the formatted value. `getAriaValueText` and `aria-valuetext` on `Slider.Thumb` take precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default SliderLabels
`
  })}
/>

---

# Switch

A toggle switch built on Base UI's `Switch` primitive. Provides an accessible on/off control with a sliding thumb animation.

## Import

```tsx
import { Switch } from "chunks-ui";
```

## Basic Usage

```tsx
<Switch.Root aria-label="Airplane mode">
  <Switch.Thumb />
</Switch.Root>
```

A switch without a visible label needs an `aria-label`. To show a label, use `Field` as below.

## With Label

```tsx
<Field.Root>
  <div className="flex items-center gap-2">
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
    <Field.Label>Enable notifications</Field.Label>
  </div>
</Field.Root>
```

## Controlled

```tsx
function ControlledSwitch() {
  const [enabled, setEnabled] = useState(false);

return (
    <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="Dark mode">
      <Switch.Thumb />
    </Switch.Root>
  );
}
```

## Disabled

```tsx
<Switch.Root disabled aria-label="Unavailable setting">
  <Switch.Thumb />
</Switch.Root>
```

## Compound Parts

| Part | Description |
|---|---|
| `Switch.Root` | The switch track. Manages checked state and keyboard interaction. Changes background color when checked. |
| `Switch.Thumb` | The sliding circle. When checked it moves toward its inline end by its own width (`translate-x-full`, or `-translate-x-full` right to left), so it fits any `--spacing`. If you resize the switch, keep the track's inner width at twice the thumb's, e.g. `h-6 w-11` on `Switch.Root` with `size-5` on `Switch.Thumb`. |

## Props

All compound parts are thin style wrappers. Props are forwarded to the underlying Base UI [`Switch`](https://base-ui.com/react/components/switch#api-reference).

---

# Table

A compound styling component for HTML tables. Zero logic — just consistent styling for headers, rows, cells, and captions. Pairs perfectly with [TanStack Table](https://tanstack.com/table) for data-rich use cases (see [Data Table](/components/data-table)).

## Import

```tsx
import { Table } from "chunks-ui";
```

## Basic Usage

```tsx
<Table.Root>
  <Table.Caption>A list of your recent invoices.</Table.Caption>
  <Table.Header>
    <Table.Row>
      <Table.Head>Invoice</Table.Head>
      <Table.Head>Status</Table.Head>
      <Table.Head>Method</Table.Head>
      <Table.Head className="text-end">Amount</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell className="font-medium">INV001</Table.Cell>
      <Table.Cell>Paid</Table.Cell>
      <Table.Cell>Credit Card</Table.Cell>
      <Table.Cell className="text-end">$250.00</Table.Cell>
    </Table.Row>
  </Table.Body>
  <Table.Footer>
    <Table.Row>
      <Table.Cell colSpan={3}>Total</Table.Cell>
      <Table.Cell className="text-end">$1,750.00</Table.Cell>
    </Table.Row>
  </Table.Footer>
</Table.Root>
```

## Minimal Table

You can use any subset of compound parts:

```tsx
<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.Head>Name</Table.Head>
      <Table.Head>Role</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Alice Johnson</Table.Cell>
      <Table.Cell>Admin</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

## Compound Parts

| Part | Element | Description |
|---|---|---|
| `Table.Root` | `<table>` | Outer wrapper. Full-width, scrollable overflow container. |
| `Table.Header` | `<thead>` | Header section. Bottom border on rows. |
| `Table.Body` | `<tbody>` | Body section. No border on last row. |
| `Table.Footer` | `<tfoot>` | Footer section. Top border, muted background. |
| `Table.Row` | `<tr>` | Row. Bottom border, hover highlight, `data-[state=selected]` support. |
| `Table.Head` | `<th>` | Header cell. Muted foreground, medium weight, aligned to the inline start (left in left-to-right layouts, right in right-to-left ones). |
| `Table.Cell` | `<td>` | Data cell. Standard padding, vertical alignment. |
| `Table.Caption` | `<caption>` | Table description. Muted text, below the table. |

## Row Selection

Use `data-state="selected"` on `Table.Row` to highlight selected rows:

```tsx
<Table.Row data-state="selected">
  <Table.Cell>This row is highlighted</Table.Cell>
</Table.Row>
```

## Props

All compound parts accept their native HTML element props plus `className` for additional styling. There are no component-specific variant props — this is a pure styling layer.

## With TanStack Table

For sorting, filtering, pagination, and row selection, see the [Data Table](/components/data-table) recipe.

---

TabsAnimateExample,
  TabsBasicExample,
  TabsDirectionExample,
  TabsDisabledExample,
  TabsHookExample,
  TabsUnderlineExample,
  TabsVerticalExample,
} from '@/examples/Tabs'

# Tabs

A tabbed navigation component built on Base UI's `Tabs` primitive. Features an animated indicator that slides between active tabs.

## Import

```tsx
import { Tabs } from "chunks-ui";
```

## Basic Usage

```tsx
<Tabs.Root defaultValue="tab-1">
  <Tabs.List>
    <Tabs.Tab value="tab-1">Account</Tabs.Tab>
    <Tabs.Tab value="tab-2">Security</Tabs.Tab>
    <Tabs.Tab value="tab-3">Notifications</Tabs.Tab>
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Contents>
    <Tabs.Content value="tab-1">
      <p className="p-4">Account settings content.</p>
    </Tabs.Content>
    <Tabs.Content value="tab-2">
      <p className="p-4">Security settings content.</p>
    </Tabs.Content>
    <Tabs.Content value="tab-3">
      <p className="p-4">Notification preferences.</p>
    </Tabs.Content>
  </Tabs.Contents>
</Tabs.Root>
```

`Tabs.Contents` keeps every `Tabs.Content` mounted. With Motion it slides between them and animates the height. For plain panels without animation, use `Tabs.Panel` instead, as in the Controlled example below. Only the active `Tabs.Panel` is mounted, unless you set `keepMounted`.

Each `Tabs.Content` is a Base UI `Tabs.Panel` that stays mounted. It has `role="tabpanel"`, its tab names it, and the tab's `aria-controls` points to it. The active panel is in the tab order, as `Tabs.Panel` is, and shows a focus ring inside its edge. Outside `Tabs.Contents`, every `Tabs.Content` shows, and the inactive ones are inert; for plain panels that show and hide, use `Tabs.Panel`.

With Motion, `Tabs.Contents` clips the panels beside the active one. The clip leaves 4px of room around the content (`overflow-clip-margin`), so a focus ring of up to 4px outside an element at the edge shows in full. That room counts as overflow too: when `Tabs.Contents` sits flush against the edge of a scroll container, the container can scroll 4px further, which can show a scrollbar or let a touch screen pan sideways. Give that scroll container at least 4px of padding, or give the content an inset focus ring. Safari does not support `overflow-clip-margin`, so it adds no overflow there, but it clips a ring at the edge; the same padding or inset ring helps. Without Motion, or with reduced motion, nothing is clipped.

## Controlled

```tsx
function ControlledTabs() {
  const [tab, setTab] = useState("overview");

return (
    <Tabs.Root value={tab} onValueChange={setTab}>
      <Tabs.List>
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="details">Details</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
      <Tabs.Panel value="details">Details content</Tabs.Panel>
    </Tabs.Root>
  );
}
```

## Vertical Orientation

Set `orientation="vertical"` on the root. The list stacks its tabs in a column (`flex-col`), and the arrow keys move up and down:

```tsx
<Tabs.Root defaultValue="tab-1" orientation="vertical">
  <Tabs.List>
    <Tabs.Tab value="tab-1">General</Tabs.Tab>
    <Tabs.Tab value="tab-2">Advanced</Tabs.Tab>
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Contents>
    <Tabs.Content value="tab-1">
      <p className="p-4">General settings</p>
    </Tabs.Content>
    <Tabs.Content value="tab-2">
      <p className="p-4">Advanced settings</p>
    </Tabs.Content>
  </Tabs.Contents>
</Tabs.Root>
```

## Animated Indicator

The `Tabs.Indicator` component renders a pill behind the active tab. With Motion installed, a spring moves it between tabs. When the tabs are hidden (for example with `display: none`) and shown again, the pill appears over the active tab at once.

Without Motion, or with reduced motion, it takes its position and size from the CSS variables Base UI sets on it (`--active-tab-left`, `--active-tab-top`, `--active-tab-width`, `--active-tab-height`). It slides with a CSS transition, which reduced motion turns off.

Only a change of tab slides the pill. When the active tab or the list changes size (for example a font size, padding or container width change), the pill moves to the tab at once, so it does not trail behind it. A size change during a slide changes where the slide ends.

### Server rendering

The pill is in the server-rendered page before React hydrates. `Tabs.Indicator` sets Base UI's `renderBeforeHydration` by default: Base UI renders a small inline `<script>` after the indicator that measures the active tab and shows the pill over it. Set `renderBeforeHydration={false}` to leave the script out. The pill then shows once React has hydrated.

A CSP that doesn't allow inline scripts (no `'unsafe-inline'` in `script-src`, or `default-src` when `script-src` is absent, or a nonce, hash or `'strict-dynamic'`, which make browsers ignore `'unsafe-inline'`) blocks the script. Pass your per-request nonce to Base UI's `CSPProvider`, so the script carries it:

```tsx
import { CSPProvider } from "@base-ui/react/csp-provider";

<CSPProvider nonce={nonce}>
  <App />
</CSPProvider>
```

Or opt out with `renderBeforeHydration={false}`.

### Restyling the indicator

The indicator box always covers the active tab. While Motion drives it, Motion writes `left`, `top`, `width` and `height` as inline styles, and they win over classes. Position and size classes on `Tabs.Indicator`, such as `top-auto bottom-0 h-0.5`, therefore have no effect with Motion. The CSS fallback applies them, so the indicator would look different with and without Motion.

To change the look, keep the box and change what is drawn in it. For an underline in a horizontal list, remove the pill's background and shadow, and draw the line with a pseudo-element at the bottom of the box:

```tsx
<Tabs.Root defaultValue="tab-1">
  <Tabs.List className="rounded-none border-border border-b bg-transparent p-0">
    <Tabs.Tab value="tab-1">General</Tabs.Tab>
    <Tabs.Tab value="tab-2">Advanced settings</Tabs.Tab>
    <Tabs.Indicator className="rounded-none bg-transparent shadow-none after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary" />
  </Tabs.List>
</Tabs.Root>
```

The line then sits along the bottom of the active tab and moves with it, with Motion and with the CSS fallback.

## Disabled tabs

Set `disabled` on a `Tabs.Tab`. The tab dims to 50%, and a user can't select it. Base UI keeps it focusable, so it gets `aria-disabled`, not the `disabled` attribute. The arrow keys move focus onto it, and Enter or Space does nothing. With `activateOnFocus`, focus does not select it either.

```tsx
<Tabs.Root defaultValue="tab-1">
  <Tabs.List>
    <Tabs.Tab value="tab-1">Account</Tabs.Tab>
    <Tabs.Tab value="tab-2" disabled>
      Billing
    </Tabs.Tab>
    <Tabs.Tab value="tab-3">Notifications</Tabs.Tab>
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Contents>
    <Tabs.Content value="tab-1">
      <p className="p-4">Account settings content.</p>
    </Tabs.Content>
    <Tabs.Content value="tab-2">
      <p className="p-4">Billing details.</p>
    </Tabs.Content>
    <Tabs.Content value="tab-3">
      <p className="p-4">Notification preferences.</p>
    </Tabs.Content>
  </Tabs.Contents>
</Tabs.Root>
```

At mount, a `value` or an explicit `defaultValue` can select a disabled tab. The tab stays selected, and the indicator under it dims to 50%. Without either, the root selects the first enabled tab.

When the selected tab becomes disabled later, a controlled root keeps it selected. The indicator dims and fades with the tab (at once with reduced motion). Base UI does not call `onValueChange`, so moving the selection is up to you. An uncontrolled root moves the selection to the first enabled tab, also when `defaultValue` selected it, and calls `onValueChange` with the new value and the reason `"disabled"`. `eventDetails.cancel()` can't stop this move.

The indicator does not follow a disabled opacity of your own on `Tabs.Tab`: it stays at 50%. Set that opacity with `aria-disabled:` (for example `aria-disabled:opacity-70`), as a disabled tab is never `:disabled`. To dim the indicator the same, give `Tabs.Indicator` that opacity with the variant the library dims it with: `group-has-[[data-active][aria-disabled=true]]/tabs-list:opacity-70`. It replaces the library's `opacity-50`.

## Routed Tabs (single panel)

`Tabs.Contents` mounts every panel in a flex track and slides between them on the x-axis. That works great for tabbed UIs where every panel coexists -- but it doesn't fit a router-driven setup, where only one panel is rendered at a time (typically through a single outlet) and the previous panel has already unmounted by the time the new one appears.

For that case, opt out of `Tabs.Contents` and reach for one of:

- **`Tabs.Animate`** — drop-in wrapper around the active panel content. Re-keys on tab change so children always remount, and accepts `initial` / `animate` / `transition` props so you bring your own animation.
- **`useTabsValue()`** — hook returning the active tab value. Use it when you need a motion primitive `Tabs.Animate` doesn't expose (`AnimatePresence`, layout animations, custom orchestration).

The two compose: read `useTabsValue()` to derive a value (e.g. direction relative to a known order), then feed it to `Tabs.Animate`.

### With `Tabs.Animate` (component)

The simplest case. One outlet, one motion target. Pass `initial` / `animate` / `transition` directly:

```tsx
<Tabs.Root value={tab} onValueChange={setTab}>
  <Tabs.List>
    <Tabs.Tab value="home">Home</Tabs.Tab>
    <Tabs.Tab value="profile">Profile</Tabs.Tab>
    <Tabs.Tab value="settings">Settings</Tabs.Tab>
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Animate
    initial={{ y: 16, opacity: 0 }}
    animate={{ y: 0, opacity: 1 }}
    transition={{ duration: 0.2 }}
  >
    <p className="p-4">Content for the {tab} tab</p>
  </Tabs.Animate>
</Tabs.Root>
```

`Tabs.Animate` can also wrap several `Tabs.Panel`s. Base UI mounts only the active panel, so that panel animates in on every tab change:

```tsx
<Tabs.Animate>
  <Tabs.Panel value="home">Home</Tabs.Panel>
  <Tabs.Panel value="profile">Profile</Tabs.Panel>
  <Tabs.Panel value="settings">Settings</Tabs.Panel>
</Tabs.Animate>
```

`Tabs.Animate` remounts everything inside it when the tab changes. A `keepMounted` panel inside it therefore still remounts and loses its state. To keep panel state, put `keepMounted` panels outside `Tabs.Animate`, or use `Tabs.Contents`.

### With `useTabsValue` (hook)

When you need a motion feature that `Tabs.Animate` doesn't surface — here, an exit animation via `AnimatePresence`:

```tsx
import { useTabsValue } from "chunks-ui";
import { AnimatePresence, motion } from "motion/react";

function HookPanel({ children }: { children: React.ReactNode }) {
  const value = useTabsValue();
  return (
    <AnimatePresence mode="wait" initial={false}>
      <motion.div
        key={String(value)}
        initial={{ scale: 0.97, opacity: 0 }}
        animate={{ scale: 1, opacity: 1 }}
        exit={{ scale: 0.97, opacity: 0 }}
        transition={{ duration: 0.18 }}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  );
}
```

### Direction-aware slide (hook + component)

The case `Tabs.Contents` cannot serve: a routed-tabs UI where you've opted out of the multi-panel slide because only one panel is mounted at a time, but you still want the new panel to enter from the *direction the user navigated* — right when going forward, left when going back.

The hook and the component compose cleanly here. `useTabsValue()` exposes the active value; a small wrapper hook stores the previous value in a ref, compares its position in a known order, and derives a direction. That direction feeds `initial.x` on `Tabs.Animate`, which handles re-keying and motion-availability fallbacks for you:

```tsx
import { Tabs, useTabsValue } from "chunks-ui";
import { useEffect, useRef } from "react";

function useTabsDirection(order: readonly string[]): 1 | -1 {
  const value = String(useTabsValue() ?? "");
  const prevRef = useRef(value);
  const currentIdx = order.indexOf(value);
  const prevIdx = order.indexOf(prevRef.current);
  const direction: 1 | -1 = currentIdx === -1 || prevIdx === -1 || currentIdx >= prevIdx ? 1 : -1;
  useEffect(() => {
    prevRef.current = value;
  }, [value]);
  return direction;
}

> **Don't** wrap `Tabs.Animate` inside `Tabs.Contents`. `Tabs.Contents` already mounts every panel and slides between them; layering `Tabs.Animate` on top double-animates and re-mounts panels that haven't changed visibility. `Tabs.Animate` is for the routed/single-outlet case; `Tabs.Contents` is for the multi-panel case. Pick one.

## Compound Parts

| Part | Description |
|---|---|
| `Tabs.Root` | State container. Manages active tab value. |
| `Tabs.List` | Horizontal (or vertical) container for tab triggers. Renders a rounded, muted background behind the tabs. |
| `Tabs.Tab` | Individual tab trigger button. Shows muted text by default, foreground text when active. |
| `Tabs.Panel` | Content panel associated with a tab value. Mounted only while its tab is active, unless `keepMounted` is set. No animation. |
| `Tabs.Indicator` | Pill behind the active tab. Slides to a tab when it becomes active, and follows a resize at once. Shows before hydration on a server-rendered page. |
| `Tabs.Contents` | Container that keeps every `Tabs.Content` mounted. With Motion it slides between them and animates the height. Without Motion, or with reduced motion, it shows only the active one, with no animation. |
| `Tabs.Content` | Individual content panel for use inside `Tabs.Contents`. Requires a `value` matching a `Tabs.Tab`. A Base UI `Tabs.Panel` that stays mounted, labelled by its tab. |
| `Tabs.Animate` | Wrapper for routed tabs or for several `Tabs.Panel`s. Re-keys its children on tab change (so they remount) and accepts `initial` / `animate` / `transition`. |

## Hooks

| Hook | Description |
|---|---|
| `useTabsValue()` | Read the active tab value from the surrounding `<Tabs.Root>` context. Throws if used outside a `Tabs.Root`. Use as an escape hatch when `Tabs.Animate` doesn't fit. |

## Props

`Tabs.Root`, `Tabs.List`, `Tabs.Tab`, `Tabs.Panel`, and `Tabs.Indicator` are thin style wrappers. Props are forwarded to the underlying Base UI [`Tabs`](https://base-ui.com/react/components/tabs#api-reference). One default differs: `Tabs.Indicator` has `renderBeforeHydration` on (see [Server rendering](#server-rendering)).

### Tabs.Contents Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<TabsContentsProps, 'children' | 'transition'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<div>` element.

### Tabs.Content Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<TabsContentProps, 'value'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying Base UI `Tabs.Panel`, except `keepMounted` and `hidden`: `Tabs.Contents` keeps every panel mounted and decides which one shows.

### Tabs.Animate Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<TabsAnimateProps, 'children' | 'initial' | 'animate' | 'transition'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<div>` element.

---

# Textarea

A multi-line text input with optional auto-resize behavior using the CSS `field-sizing: content` property.

## Import

```tsx
import { Textarea } from "chunks-ui";
```

## Basic Usage

```tsx
<Textarea placeholder="Write your message..." />
```

## Auto-Resize

When `autoResize` is `true`, the textarea grows vertically to fit its content using the native CSS `field-sizing: content` property:

```tsx
<Textarea autoResize placeholder="Start typing..." />
```

The textarea has a minimum height of `min-h-ui-height` by default.

## With Field

`Textarea` is a field control, like `Input`. Inside `Field.Root`, `Field.Label` names it, `Field.Description` describes it, and `disabled` on the root disables it. When the field is invalid, the textarea gets `aria-invalid` and `data-invalid`, and the same red border as `Input`.

```tsx
<Field.Root>
  <Field.Label>Bio</Field.Label>
  <Field.Description>Write a short bio (max 280 characters)</Field.Description>
  <Textarea autoResize placeholder="Tell us about yourself..." maxLength={280} />
</Field.Root>
```

## Controlled Value

`Textarea` passes `value` and `defaultValue` through Base UI, like `Input`. A controlled `value` must be controlled from the first render, so never start with `undefined`. Use `value={bio ?? ""}`. Switching between controlled and uncontrolled after mount leaves the textarea empty and logs a warning in development, and changing `defaultValue` after mount logs an error.

```tsx
<Textarea value={bio ?? ""} onChange={(event) => setBio(event.target.value)} />
```

`onValueChange` gives you the new text directly, with the same signature as on `Input`: `(value, eventDetails)`.

```tsx
<Textarea value={bio ?? ""} onValueChange={setBio} />
```

## Disabled

A disabled `Textarea` shows the not-allowed cursor and has no resize handle. Pass `disabled:resize-y` in `className` to keep the handle.

```tsx
<Textarea disabled placeholder="This field is disabled" />
```

## Text Size

The text is 16px below the `md` breakpoint (768px by default) and on a touch screen, so iOS Safari does not zoom the page when the field takes focus (it zooms into text under 16px); otherwise it is 14px, as in `Input`. With a mouse, a text-size class, such as `text-lg`, sets the size from `md` up. A `max-md:` class, such as `max-md:text-lg`, sets it below `md`, on a touch screen too; from `md` up on a touch screen, a `md:[@media(pointer:coarse)]:` class sets it. Where the text is 16px a row of text is 4px taller (24px), so a `Textarea` sized by its `rows` is taller there. See [Text Size](/components/input#text-size) in `Input` for the limits.

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<TextareaProps, 'autoResize' | 'onValueChange'>
export default Props
`
  })}
/>

All other props are forwarded to the underlying `<textarea>` element. `className` can also be a function of the field state (`disabled`, `valid`, `touched`, `dirty`, `filled`, `focused`).

---

# ThemeToggle

A controlled button for switching between light and dark themes. Animates between sun and moon icons with a crossfade, and respects `prefers-reduced-motion`.

## Import

```tsx
import { ThemeToggle } from "chunks-ui";
```

## Basic Usage

`ThemeToggle` is fully controlled — pass the current `theme` and an `onClick` handler to toggle it:

```tsx
function App() {
  const [theme, setTheme] = useState<"light" | "dark">("light");

return (
    <ThemeToggle
      theme={theme}
      onClick={() => setTheme(theme === "light" ? "dark" : "light")}
    />
  );
}
```

## Custom Icons

Replace the default sun/moon icons via `lightIcon` and `darkIcon`:

```tsx
<ThemeToggle
  theme={theme}
  onClick={() => setTheme(theme === "light" ? "dark" : "light")}
  lightIcon={<SunIcon />}
  darkIcon={<MoonIcon />}
/>
```

## With a Tooltip

`ThemeToggle` forwards its `ref` and props to the `<button>`, so it works as a `Tooltip.Trigger` render target:

```tsx
<Tooltip.Root>
  <Tooltip.Trigger
    render={<ThemeToggle theme={theme} onClick={() => setTheme(theme === "light" ? "dark" : "light")} />}
  />
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup>Toggle theme</Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>
```

## Props

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ThemeToggleProps, 'theme' | 'onClick' | 'lightIcon' | 'darkIcon' | 'labels'>
export default Props
`
  })}
/>

All other `<button>` props, including `ref`, are forwarded to the underlying `<button>` element. Pass `aria-label` to replace the default name ("Switch to dark mode" / "Switch to light mode") in both themes, or `labels` to replace each one.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_THEME_TOGGLE_LABELS`. `aria-label` takes precedence. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default ThemeToggleLabels
`
  })}
/>

---

ToastBasicExample,
  ToastHighPriorityExample,
  ToastPromiseExample,
  ToastStackingExample,
  ToastVariantsExample,
  ToastWithActionExample,
} from '@/examples/Toast'

# Toast

A notification system built on Base UI's `Toast` primitive. Toasts slide in from the bottom corner at the inline end (bottom-right in left-to-right layouts, bottom-left in right-to-left ones) and auto-dismiss. In both directions a toast can be swiped away down, left or right, and it leaves the way it was swiped. The `useToast` hook triggers them from anywhere within the provider.

## Import

```tsx
import { Toast } from "chunks-ui"
```

## Setup

Wrap your app (or the relevant subtree) with `Toast.Provider` and place `Toast.Viewport` where the toasts should render:

```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <Toast.Provider>
      {children}
      <Toast.Viewport />
    </Toast.Provider>
  )
}
```

## Basic Usage

Use `Toast.useToast()` to get the `add` function and trigger notifications:

```tsx
function SaveButton() {
  const { add } = Toast.useToast()

return (
    <button onClick={() => add({ title: "Saved", description: "Your changes have been saved." })}>
      Save
    </button>
  )
}
```

## Per-toast Styling

`chunks-ui` doesn't ship any icons, semantic types, or default colours — bring your own. Three per-toast slots let you plug into whatever icon library and design tokens your project uses:

| Field | Purpose |
|---|---|
| `icon` | Component rendered in the leading slot. Receives a `className` prop pre-populated with default sizing (`size-5 shrink-0 self-start`). |
| `iconClassName` | Extra classes merged onto `icon` — use for color. |
| `className` | Extra classes merged onto `Toast.Root` — use for accent bars, borders, background tints. |

For the simple case, pass a lucide component directly:

```tsx
import { CheckCircle2 } from 'lucide-react'

add({
  title: "File saved",
  icon: CheckCircle2,
  iconClassName: "text-success-text",
})
```

### Semantic Types — A Custom Pattern

The example below renders four colour-coded variants — but **chunks-ui doesn't ship semantic types**. The icons, accent borders, and text colours are entirely a consumer-side pattern built on the three slots above.

Define a pure-data `TYPE_STYLES` map once and spread it into `add()` at the call site:

```tsx
import { Button, Toast } from 'chunks-ui'
import { AlertTriangle, CheckCircle2, Info, XCircle } from 'lucide-react'

const TYPE_STYLES = {
  primary:     { icon: Info,          iconClassName: 'text-primary-text',     className: 'border-s-4 border-primary' },
  success:     { icon: CheckCircle2,  iconClassName: 'text-success-text',     className: 'border-s-4 border-success' },
  destructive: { icon: XCircle,       iconClassName: 'text-destructive-text', className: 'border-s-4 border-destructive' },
  warning:     { icon: AlertTriangle, iconClassName: 'text-warning-text',     className: 'border-s-4 border-warning' },
} as const

type ToastType = keyof typeof TYPE_STYLES

function ToastTrigger({
  label,
  title,
  description,
  type,
}: {
  label: string
  title: string
  description?: string
  type?: ToastType
}) {
  const { add } = Toast.useToast()

return (
    <Button
      type="button"
      variant="outlined"
      color={type}
      onClick={() => add({ title, description, ...(type && TYPE_STYLES[type]) })}
    >
      {label}
    </Button>
  )
}
```

No factory functions, no closures — the icon references are stable lucide components, so React reconciles them cleanly across re-renders. Add a type, drop a row in the map; rename a colour, change one row. The library never has to ship an opinion.

## With Action

Pass `actionProps` to render a labelled action button inside the toast:

```tsx
const { add } = Toast.useToast()

add({
  title: "Message deleted",
  description: "The message has been removed from your inbox.",
  actionProps: {
    children: "Undo",
    onClick: () => restoreMessage(),
  },
})
```

## High Priority

Pass `priority: "high"` for a toast the user must not miss. Screen readers announce it at once, interrupting what they read; a toast of the default `low` priority waits until they finish:

```tsx
add({
  title: "Connection lost",
  description: "Trying to reconnect…",
  priority: "high",
})
```

Base UI 1.9 hides a high-priority toast from screen readers until keyboard focus enters the viewport, and Tab passes over the toast for that time: press F6, then Tab, to reach it. See the note under [Props](#props).

## Dismissible Toasts

By default toasts auto-dismiss after the provider's `timeout` and don't render a close button. Opt in per-toast by passing `dismissible: true` to `add()`:

```tsx
const { add } = Toast.useToast()

add({
  title: "Saved",
  description: "Your changes are safe.",
  dismissible: true,
})
```

That toast gets a `×` button in its top-end corner (top-right in left-to-right layouts, top-left in right-to-left ones) that dismisses it via Base UI's `Toast.Close`. Other toasts in the same viewport are unaffected — dismissibility is a per-toast concern, not a viewport-wide setting.

`closeProps` takes the props of that button, as `actionProps` does for the action: `className` merges after the library classes, and `aria-label` replaces `labels.close` for that toast. Unlike `actionProps`, it does not render the button on its own: the button appears with `dismissible` or `onClose`. To keep the focus ring flush with the button instead of 2px outside it:

```tsx
add({
  title: "Saved",
  dismissible: true,
  closeProps: { className: "focus-visible:outline-offset-0" },
})
```

> **Note**: `dissmissable` is a deprecated misspelled alias of `dismissible`. When both are set, `dismissible` wins.

### Reacting to Close

If you need to run a side effect when a toast closes, such as tracking analytics, offering an undo stack or syncing with a backend, pass `onClose`. It takes no arguments and fires once per close, whichever way the toast closes: the close button, the timeout, a swipe, Escape with focus inside the toast, or `manager.close`. Passing `onClose` also implicitly enables the close button, so you don't need to also set `dismissible`. To track a toast that closes by itself without showing a button, set `dismissible: false`. `onClose` doesn't say which toast closed; to know that, keep the id that `add()` returns:

```tsx
const id = add({
  title: "Message archived",
  onClose: () => {
    analytics.track('toast_closed', { id })
  },
})
```

`onClose` runs *in addition to* Base UI's built-in dismissal. It is for side effects, not for preventing the toast from closing. To keep a toast open on a click of the close button, call `event.preventBaseUIHandler()` in `closeProps.onClick`: the toast stays and `onClose` does not fire. Set `timeout: 0` as well, or the timer closes the toast anyway:

```tsx
add({
  title: "Unsaved changes",
  timeout: 0,
  dismissible: true,
  closeProps: {
    onClick: (event) => {
      if (hasUnsaved) event.preventBaseUIHandler()
    },
  },
})
```

## Promise Toasts

`toast.promise(promise, { loading, success, error })` wires a single toast through the lifecycle of an async operation. It starts with the `loading` options, then swaps to `success` or `error` once the promise settles. `success` and `error` can be static options or functions that receive the resolved value / rejection reason:

```tsx
import { CheckCircle2, XCircle } from 'lucide-react'

const { promise } = Toast.useToast()

promise(uploadFile(), {
  loading: { title: "Uploading file…", description: "Hold tight." },
  success: (result) => ({
    title: "Upload complete",
    description: `Saved ${result.name} to your workspace.`,
    icon: CheckCircle2,
    iconClassName: "text-success-text",
  }),
  error: (err) => ({
    title: "Upload failed",
    description: err.message,
    icon: XCircle,
    iconClassName: "text-destructive-text",
  }),
})
```

The method returns the original promise, so you can still `await` or `.catch()` it downstream — the toast is a side effect, not a replacement for your own error handling.

## Stacking Behaviour

By default `Toast.Viewport` renders toasts as a flex column. For the "stacked deck" pattern — where a pile of notifications collapses behind the frontmost one and fans out on hover — chunks-ui ships two opt-in CSS classes in `theme.css`:

| Class | Where | What it does |
|---|---|---|
| `toast-stack-viewport` | `Toast.Viewport` | Overrides the default flex layout so children can absolute-stack at the same anchor point. |
| `toast-stack` | each toast's `className` | Drives the collapsed/expanded transforms off Base UI's per-root CSS variables (`--toast-index`, `--toast-height`, `--toast-frontmost-height`, `--toast-offset-y`, `--toast-swipe-movement-x/y`) and responds to `data-expanded`, `data-starting-style`, `data-ending-style`, and `data-swipe-direction`. |

```tsx
<Toast.Provider limit={5}>
  <TriggerButton />
  <Toast.Viewport className="toast-stack-viewport" />
</Toast.Provider>
```

Then give each toast the `toast-stack` class when you add it:

```tsx
add({
  title: "Notification",
  description: "Hover the stack to expand.",
  className: "toast-stack",
})
```

The stacking CSS respects `prefers-reduced-motion: reduce` — users with that setting get an instant stack/expand with no transitions. The pattern is ported directly from Base UI's reference example, so the visual and physics match what Base UI documents.

## Compound Parts

| Part | Description |
|---|---|
| `Toast.Provider` | Context provider. Must wrap any component that calls `useToast`. Accepts `timeout` and `limit` (default `3`). In the default viewport, toasts past the limit stay hidden until newer ones close, then slide in (at once with reduced motion, or in browsers without `@starting-style`). |
| `Toast.Viewport` | Fixed-position container that renders all active toasts. |
| `Toast.Root` | Individual toast wrapper with slide/fade enter/exit transitions. |
| `Toast.Title` | Bold toast heading. |
| `Toast.Description` | Supporting text in `text-muted-foreground`. |
| `Toast.Close` | Icon button that dismisses the toast. Children you pass replace the X; with a `render` element and no children, there is no X. The button keeps its `aria-label` whatever its content (`labels.close` on the button a toast adds itself; "Close" on one you render yourself): if the children are visible text, pass an `aria-label` that contains it. |
| `Toast.Action` | Optional action button rendered inside the toast. |
| `Toast.useToast` | Hook that returns `{ toasts, add, close, update, promise }` for the nearest provider. |

## Props

### Per-toast options — `add` / `update` / `promise`

Pass any subset of these at the call site. The fields below are chunks-ui additions on top of Base UI's `ToastObject` — all other options (`title`, `description`, `type`, `timeout`, `actionProps`, `priority`, `data`, …) are forwarded directly to Base UI; see the [`ToastObject` API reference](https://base-ui.com/react/components/toast#api-reference) for the full list.

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ToastStyleOptions, 'icon' | 'iconClassName' | 'className' | 'dismissible' | 'onClose' | 'closeProps'>
export default Props
`
  })}
/>

> **Note**: Base UI 1.9 hides a toast added with `priority: "high"` from screen readers (`aria-hidden`) and announces it through a visually hidden alert instead. The toast stays hidden until keyboard focus enters the viewport, and is hidden again when focus leaves it. While it is hidden, chunks-ui keeps the toast, its `Toast.Close` and its `Toast.Action` out of the tab order (except where a `tabIndex` of yours wins, see [Compound parts](#compound-parts)), so Tab passes over the toast: press F6, then Tab, to reach the toast and its buttons. A mouse click still focuses the toast and leaves it hidden. Other focusable elements that you put in a high-priority `Toast.Root` keep their tab stops ([mui/base-ui#5659](https://github.com/mui/base-ui/issues/5659)). This includes a link in the `title` or `description` of a high-priority toast: Base UI also renders those in a visually hidden copy, which screen readers announce, and the link in it is an invisible tab stop. With `add()`, navigate from `actionProps.onClick` instead. In a custom `Toast.Root`, render the link through the `render` prop of `Toast.Action`, with `nativeButton={false}` on `Toast.Action` and `role={undefined}` on the link, and do not set `tabIndex` on the link or in `actionProps` there. Base UI gives the action `role="button"`. A `role` on the link wins over it. Without `role={undefined}`, screen readers announce the link as a button. In a `render` function, put `role={undefined}` after `{...props}`: `props` already holds `role: "button"`, and nothing merges after your element. Biome's `useValidAriaRole` flags `role={undefined}`. Suppress it there: its fix removes the attribute, and the link is a button again.
>
> Base UI also hides the close button of every toast from screen readers while the toasts are collapsed, with no pointer over them and no keyboard focus in them. chunks-ui keeps the button out of the tab order for that time. Keyboard focus on a toast expands the toasts and brings the button back: from the toast, Tab reaches its action first when it has one, then its close button.

### Toast.Viewport

`Toast.Viewport` is a thin style wrapper. It renders the toast list itself and forwards every other prop to Base UI's [`Toast.Viewport`](https://base-ui.com/react/components/toast#api-reference); `children` you pass are not rendered. All per-toast behaviour (`icon`, `iconClassName`, `className`, `dismissible`, `onClose`, `closeProps`) lives on the individual `add()` call, not the container, so a single viewport can host a mix of dismissible and non-dismissible toasts, styled and unstyled ones, etc.

Only string-level overrides are worth knowing about here:

- Pass `className="toast-stack-viewport"` to opt into the [stacking pattern](#stacking-behaviour).
- Otherwise, you almost never need to touch the viewport beyond mounting it.

`Toast.Viewport` also takes `labels`:

<TSDoc
  definition={generateDefinition({
    code: `

type Props = Pick<ToastViewportProps, 'labels'>
export default Props
`
  })}
/>

### Compound parts

All other compound parts (`Toast.Provider`, `Toast.Root`, `Toast.Title`, `Toast.Description`, `Toast.Close`, `Toast.Action`) are thin style wrappers and forward their props to the corresponding Base UI primitive, except that `Toast.Root`, `Toast.Close` and `Toast.Action` set `tabIndex` to `-1` while Base UI hides them from screen readers, replacing a `tabIndex` you pass (see the note under [Props](#props)). A `tabIndex` on the element you pass to `render` still wins. On a `Toast.Action` with a `render`, so does a `tabIndex` in `actionProps`. See the [Base UI Toast reference](https://base-ui.com/react/components/toast#api-reference) for the full prop surface.

## Labels

`labels` replaces the built-in English text, for example to translate it. Keys you leave out keep their default from `DEFAULT_TOAST_LABELS`. `labels.viewport` names the region that Base UI announces the toasts in, and `labels.close` names the close button of a dismissible toast. `aria-label` on `Toast.Viewport` takes precedence over `labels.viewport`. See [Labels](/labels).

<TSDoc
  definition={generateDefinition({
    code: `

export default ToastLabels
`
  })}
/>

---

# Toggle Group

A group of toggle buttons where one or multiple items can be pressed at a time. Built on Base UI's `Toggle` and `ToggleGroup` primitives. In single-select mode, a sliding indicator animates between the active item using Motion (with CSS transition fallback). When the group is hidden (for example with `display: none`) and shown again, the indicator appears over the pressed item instead of growing from nothing. Only pressing another item slides the indicator: when an item or the group changes size (for example a font size, padding or container width change), it moves to the pressed item at once, so it does not trail behind it.

## Import

```tsx
import { ToggleGroup } from "chunks-ui";
```

## Basic Usage

By default, the toggle group operates in single-select mode. Only one item can be pressed at a time, and a sliding indicator highlights the active selection:

```tsx
import { AlignLeftIcon, AlignCenterIcon, AlignRightIcon } from 'lucide-react'

<ToggleGroup.Root aria-label="Text alignment" defaultValue={["left"]}>
  <ToggleGroup.Item value="left" aria-label="Align left"><AlignLeftIcon /></ToggleGroup.Item>
  <ToggleGroup.Item value="center" aria-label="Align center"><AlignCenterIcon /></ToggleGroup.Item>
  <ToggleGroup.Item value="right" aria-label="Align right"><AlignRightIcon /></ToggleGroup.Item>
</ToggleGroup.Root>
```

### Preventing Deselection

Base UI allows deselecting the active item by clicking it again. To enforce that one item is always selected, reject empty values:

```tsx
<ToggleGroup.Root
  aria-label="Text alignment"
  value={value}
  onValueChange={(newValue) => {
    if (newValue.length > 0) setValue(newValue);
  }}
>
  {/* items */}
</ToggleGroup.Root>
```

## Multiple Selection

Set `multiple` to allow pressing more than one item at a time. Each pressed item gets its own background highlight instead of a shared sliding indicator:

```tsx
import { BoldIcon, ItalicIcon, UnderlineIcon } from 'lucide-react'

<ToggleGroup.Root aria-label="Text formatting" multiple defaultValue={["bold", "italic"]}>
  <ToggleGroup.Item value="bold" aria-label="Bold"><BoldIcon /></ToggleGroup.Item>
  <ToggleGroup.Item value="italic" aria-label="Italic"><ItalicIcon /></ToggleGroup.Item>
  <ToggleGroup.Item value="underline" aria-label="Underline"><UnderlineIcon /></ToggleGroup.Item>
</ToggleGroup.Root>
```

## Controlled

`ToggleGroup.Root` infers the type of an item's value from `value` or `defaultValue`, so a typed `useState` setter is an `onValueChange`:

```tsx
import { AlignLeftIcon, AlignCenterIcon, AlignRightIcon } from 'lucide-react'

function ControlledToggleGroup() {
  const [value, setValue] = useState<("left" | "center" | "right")[]>(["left"]);

return (
    <ToggleGroup.Root aria-label="Text alignment" value={value} onValueChange={setValue}>
      <ToggleGroup.Item value="left" aria-label="Align left"><AlignLeftIcon /></ToggleGroup.Item>
      <ToggleGroup.Item value="center" aria-label="Align center"><AlignCenterIcon /></ToggleGroup.Item>
      <ToggleGroup.Item value="right" aria-label="Align right"><AlignRightIcon /></ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}
```

## Disabled items

A disabled item dims to 50%. In single-select mode the indicator dims with the pressed item when that item or the group is disabled, and fades with the item when it becomes disabled.

The indicator is internal, so it does not follow a disabled opacity of your own on the item (for example `disabled:opacity-70`): it stays at 50%. To match the item's opacity, add a rule of your own for the indicator, the `span` that `ToggleGroup.Root` renders before its items: with `className="my-group"` on the root, `.my-group:has([data-pressed]:disabled) > span:first-child { opacity: 0.7 }`. The rule must sit outside any `@layer`, or in `@layer utilities`: in `@layer components` it loses to the library's `opacity-50` whatever its specificity. For a group that holds another group, use `.my-group:has(> [data-pressed]:disabled) > span:first-child` instead: it has the same specificity, but counts only the items placed directly in the group, not those of the group inside.

When one group is nested in another, each takes its indicator state from its own items; an item wrapped in an element of its own, rather than placed directly in its group, can still take the other group's state.

## Compound Parts

| Part | Description |
|---|---|
| `ToggleGroup.Root` | Container that manages selection state. Renders a pill-shaped muted background with inline-flex layout. In single-select mode, renders a sliding indicator behind the active item. The indicator slides to an item when it is pressed, and follows a resize at once. |
| `ToggleGroup.Item` | Individual toggle button. Shows muted text by default, foreground text when pressed. In multiple mode, each pressed item gets its own background highlight. |

## Server rendering

In server HTML the pressed item draws the pill itself until the indicator is measured; no script is involved. A `::before` of your own on the pressed item shows only after hydration.

## Props

All compound parts are thin style wrappers. `ToggleGroup.Root` props are forwarded to the underlying Base UI [`ToggleGroup`](https://base-ui.com/react/components/toggle-group#api-reference) and `ToggleGroup.Item` props are forwarded to the underlying Base UI [`Toggle`](https://base-ui.com/react/components/toggle#api-reference).

---

# Tooltip

A hover/focus tooltip built on Base UI's `Tooltip` primitive. Automatically positioned via Floating UI with a scale/fade transition.

## Import

```tsx
import { Button, Tooltip } from "chunks-ui";
```

## Basic Usage

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<Button variant="outlined" />}>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup>Helpful tip</Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>
```

## With Arrow

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<Button variant="outlined" />}>Info</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup>
        <Tooltip.Arrow />
        This is a tooltip with an arrow.
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>
```

## Tooltip Provider

Use `Tooltip.Provider` to share delay settings across multiple tooltips. Every `Tooltip.Trigger` inside it opens after the Provider's `delay`, and once one tooltip is open, moving to a nearby one opens it instantly:

```tsx
<Tooltip.Provider delay={200} closeDelay={0}>
  <Tooltip.Root>
    <Tooltip.Trigger render={<Button variant="outlined" />}>A</Tooltip.Trigger>
    <Tooltip.Portal>
      <Tooltip.Positioner>
        <Tooltip.Popup>Tooltip A</Tooltip.Popup>
      </Tooltip.Positioner>
    </Tooltip.Portal>
  </Tooltip.Root>

<Tooltip.Root>
    <Tooltip.Trigger render={<Button variant="outlined" />}>B</Tooltip.Trigger>
    <Tooltip.Portal>
      <Tooltip.Positioner>
        <Tooltip.Popup>Tooltip B</Tooltip.Popup>
      </Tooltip.Positioner>
    </Tooltip.Portal>
  </Tooltip.Root>
</Tooltip.Provider>
```

A `delay` on a `Tooltip.Trigger` overrides the Provider's for that trigger.

Use the `Tooltip.Provider` from chunks-ui, not the one from `@base-ui/react/tooltip`: chunks-ui triggers ignore a Base UI Provider's `delay`.

A nested `Tooltip.Provider` without a `delay` uses 50ms, not the outer Provider's `delay`, so repeat the outer `delay` on it.

## Positioning

The popup sits 2 spacing units (8px at the default `--spacing`) from the trigger. The arrow tip clears the trigger at any spacing. A `sideOffset` on the positioner adds to that gap. The arrow stays at least `arrowPadding` pixels from the popup's ends, clear of the rounded corner. The default is the popup's corner radius plus 0.21 × the arrow's size (about 10 in the default theme), read when the popup mounts and again when a `Tooltip.Arrow` mounts or unmounts in it, so it follows `--radius` and `--spacing` but not a later change to them. A `keepMounted` tooltip mounts closed and keeps that value while it stays mounted; an arrow with a content-sized width (`auto`, `fit-content`, a percentage) has no pixel width while hidden, so it gets Base UI's default until the tooltip mounts on open. With an explicit `arrowPadding`, or an arrow with a content-sized width, a `Tooltip.Arrow` that mounts or unmounts while the tooltip is open is placed at the next scroll, resize or open. On the left and right, one line of text (about 24px tall) is too short for that padding, so Floating UI holds the arrow near the middle; there the two corners on the arrow's edge become elliptical, curving less far along it, so the arrow's foot still meets a straight edge. They start from `--radius-md` and ignore `rounded-*` on `Tooltip.Popup`, and assume the default arrow (`size-2.5`). To square them, or to fit a larger arrow, set `--tooltip-arrow-corner` on `Tooltip.Popup`: `[--tooltip-arrow-corner:0px]` with `rounded-none` squares all four corners, and a length such as `[--tooltip-arrow-corner:var(--radius-xl)]` sets the two on the arrow's edge. With `align="start"` or `"end"`, the popup shifts past a trigger narrower than 30px by up to 5px. Override placement with `side` and `align`:

```tsx
<Tooltip.Positioner side="right" align="center">
  <Tooltip.Popup>Right-aligned tooltip</Tooltip.Popup>
</Tooltip.Positioner>
```

## Animation

The popup enters with a scale-up and fade (from `scale-95` and `opacity-0`): the `popup` spring (`springs.popup`) with Motion installed, a CSS transition of `opacity` and `scale` without it; reduced motion turns off both. The popup grows out of its trigger (`origin-(--transform-origin)`); a `className` such as `origin-top` replaces it.

In a `Tooltip.Provider`, a tooltip that opens while another one is open, or within the Provider's `timeout` (400ms by default) of one closing, shows at once, and the other one hides at once. Base UI marks both popups `data-instant="delay"`, and both paths skip the animation. Outside such a swap, a tooltip opened by keyboard focus, or closed with Escape or a click on its trigger, still animates.

`render` on `Tooltip.Popup` replaces the element the spring animates, so a popup with `render` uses the CSS transition even with Motion installed. To restyle the popup, pass `className`.

## Compound Parts

| Part | Description |
|---|---|
| `Tooltip.Root` | State container. Manages hover/focus open state. |
| `Tooltip.Trigger` | The element that activates the tooltip on hover/focus. Renders a `<button>`, so don't nest another button inside it: pass `render={<Button />}` to use a chunks-ui `Button`. |
| `Tooltip.Portal` | Renders children in a portal. |
| `Tooltip.Positioner` | Floating UI positioner. `z-tooltips` (400). No default `sideOffset`; the gap to the trigger is a 2-spacing-unit margin on `Tooltip.Popup`, and a `sideOffset` adds to it. `arrowPadding` defaults to the popup's corner radius plus 0.21 × the arrow's size (about 10). |
| `Tooltip.Popup` | The tooltip content. Dark background (`bg-foreground`), light text (`text-background`). |
| `Tooltip.Arrow` | A rotated square (`bg-foreground`) absolutely positioned at the popup edge. Aligned to the anchor via Base UI CSS variables. |
| `Tooltip.Provider` | Shared delay configuration for grouped tooltips. `delay` defaults to `50`. |

## Props

All compound parts are thin style wrappers. Props are forwarded to the underlying Base UI [`Tooltip`](https://base-ui.com/react/components/tooltip#api-reference). The open delay is `50`ms by default (Base UI's default is `600`). A `Tooltip.Trigger` uses its own `delay` if set, then the nearest `Tooltip.Provider`'s `delay`, then `50`.

---