# Introduction

> What XiodUI is, how it's shipped, and its licence.

Source: https://ui.xiod.dev/docs/overview/introduction

## What is XiodUI?

XiodUI is a React component library: 90 styled, accessible components built on [Base UI](https://base-ui.com) and Tailwind CSS 4. Base UI provides the behaviour (keyboard support, focus management, screen reader semantics); XiodUI adds the design, the animations and components Base UI doesn't have, from a date picker to a file uploader.

```tsx title="app/page.tsx"
import { Button } from "xiod-ui/button";

export default function Page() {
  return <Button>Get started</Button>;
}
```

## How it differs

- **Animations are CSS.** Every transition is a CSS transition or keyframe. There is no animation library to install, and none runs in the browser.
- **Styles compile ahead of time.** Variants are Tailwind classes, so nothing calculates styles at runtime.
- **Themes are stylesheets.** 20 ready-made palettes, each with light and dark modes. Import one, or let users switch between them at runtime.
- **Touch targets are 44px.** On touch screens, small controls get a 44px hit area to meet WCAG 2.5.5.
- **Your icons, if you want them.** Every built-in icon can be replaced, one at a time or app-wide.

## How it's shipped

XiodUI is one versioned npm package. There is no CLI, no generator, and nothing to copy into your repository.

- **One install, every component.** `npm install xiod-ui` gives you all 90, and upgrades arrive like any other dependency.
- **One import path per component.** `import { Button } from "xiod-ui/button"`. There is no root import, so only the components you use reach your bundle.
- **Base UI and XiodIcons included.** They are dependencies of `xiod-ui`, so they upgrade with it. You install React and React DOM yourself.
- **One stylesheet.** `@import "xiod-ui/styles"` brings the design tokens and the `dark` variant. No config file, no plugin.
- **Typed, and ready for server components.** Type declarations for every component and prop, and `"use client"` where a component needs it.

## Licence

XiodUI is open source under [PolyForm Perimeter 1.0.1](https://polyformproject.org/licenses/perimeter/1.0.1). Use it in any project, commercial or not, open or closed source; nothing you build with it has to be published. The one restriction: you may not use XiodUI to build a product that competes with it, such as another component library or UI kit.

---

# Installation

> Install the package, add the stylesheet, and import your first component.

Source: https://ui.xiod.dev/docs/overview/installation

## Requirements

- React and React DOM 19.3 or later
- Tailwind CSS 4.3 or later, already set up in the project ([Tailwind's installation guide](https://tailwindcss.com/docs/installation))
- Node.js 20 or later

## Install

```bash
npm install xiod-ui
```

Base UI and XiodIcons are dependencies of `xiod-ui` and install with it. Don't install `@base-ui/react` yourself: a second copy breaks popups and portals.

## Add the stylesheet

Import XiodUI's stylesheet after Tailwind in your global CSS.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";
```

This adds the colour tokens and the `dark` variant, and tells Tailwind to generate the classes the components use. Without it, components render unstyled. There is no config file or plugin to add.

## Use a component

Import each component from its own path, the component's name in kebab-case.

```tsx title="app/page.tsx"
import { Button } from "xiod-ui/button";

export default function Page() {
  return <Button variant="destructive">Delete</Button>;
}
```

There is no root import: `import { Button } from "xiod-ui"` doesn't resolve. Components that need the browser already carry `"use client"`, so you can render them from a server component.

## Icons

To use XiodIcons in your own markup, add the package directly:

```bash
npm install xiod-icons
```

```tsx title="components/AddButton.tsx"
import { PlusSign } from "xiod-icons";
import { Button } from "xiod-ui/button";

export function AddButton() {
  return (
    <Button>
      <PlusSign aria-hidden />
      Add item
    </Button>
  );
}
```

To replace the icons components draw themselves, see [Icons](https://ui.xiod.dev/docs/styling/icons).

## Hooks

The two hooks the components use are exported too, from `xiod-ui/hooks/…`.

`useCopyToClipboard` copies text and reports it. `copyToClipboard` resolves to whether the copy succeeded, and `isCopied` stays `true` for `timeout` milliseconds (2000 by default; `0` keeps it). It works on plain `http` pages, where `navigator.clipboard` doesn't exist. When the browser refuses the copy, `onError` receives the error; without it, the error is logged.

```tsx title="components/CopyCommand.tsx"
"use client";

import { Button } from "xiod-ui/button";
import { useCopyToClipboard } from "xiod-ui/hooks/use-copy-to-clipboard";

export function CopyCommand({ command }: { command: string }) {
  const { isCopied, copyToClipboard } = useCopyToClipboard({
    onError: () => alert("Couldn't copy. Select the text instead."),
  });

  return (
    <Button variant="outline" onClick={() => copyToClipboard(command)}>
      {isCopied ? "Copied" : "Copy"}
    </Button>
  );
}
```

`useMediaQuery` returns whether a media query matches, and follows it as it changes. Pass a breakpoint name (`"lg"`, `"max-md"`, `"sm:max-lg"`), an object (`{ min: "md", pointer: "coarse" }`), or any CSS media query. `useIsMobile()` is `useMediaQuery("max-md")`. The named breakpoints are Tailwind's, except `md`, which is 800px rather than 768px.

```tsx
import { useIsMobile, useMediaQuery } from "xiod-ui/hooks/use-media-query";

const isMobile = useIsMobile();
const isWide = useMediaQuery("xl");
```

On the server there is no viewport, so both return `false` there, and a server-rendered page switches to the real value as it hydrates. Anything that must be right on the first paint belongs in responsive classes instead.

## AI agents

Coding agents tend to guess at this library's API from other libraries. Install the XiodUI Agent Skill so they use the real one:

```bash
npx skills add ImKKingshuk/XiodUI
```

See [Agent Skill](https://ui.xiod.dev/docs/overview/agent-skill) for what it covers, including guides for migrating from shadcn/ui, HeroUI, MUI, Ant Design, Mantine and Chakra UI.

---

# Agent Skill

> Teach coding agents XiodUI's real API, and migrate from other libraries.

Source: https://ui.xiod.dev/docs/overview/agent-skill

## Why a skill

Coding agents guess at libraries they don't know well, and the guesses come from other libraries: a root `from "xiod-ui"` import, `asChild`, an `npx … add` step, shadcn part names such as `DialogContent`. None of those exist in XiodUI, so the code the agent writes doesn't build.

The XiodUI Agent Skill gives the agent the library's real API before it writes anything. It is maintained in the library repo alongside the components, so it describes the version you install.

## Install

```bash
npx skills add ImKKingshuk/XiodUI
```

The [`skills`](https://skills.sh) CLI installs it for Claude Code, Codex, Cursor, GitHub Copilot and dozens of other agents. Run it inside a project to install it there, or add `-g` to install it for every project.

The agent loads the skill on its own when a task mentions XiodUI or `xiod-ui`, imports from the package, or asks to migrate from another UI library. Nothing needs to be pasted into the prompt.

## What it covers

- **Setup.** The one install command, the two CSS imports, and that there is no config file, plugin or CLI.
- **Imports.** Every component's subpath (`xiod-ui/input-otp`, not `xiod-ui/InputOtp`), and why `@base-ui/react` is never installed separately.
- **Composition.** Part names, `render` in place of `asChild`, data-driven components such as Select, Combobox and Command, and the Base UI state attributes (`data-open`, `data-checked`) to style against.
- **Theming.** Dark mode with `ThemeProvider`, palettes, runtime palette switching, overriding tokens, and swapping built-in icons.
- **Every component.** A reference file per component with its parts, props and an example, read only when the task uses that component.
- **Mistakes to avoid.** A list of the things agents most often get wrong here, from `tailwind.config.js` colour blocks to adding a second animation library.

## Migrating from another library

The skill includes a step-by-step guide for moving an existing app to XiodUI from each of these libraries:

| Library       | Detected by                                         |
| :------------ | :-------------------------------------------------- |
| shadcn/ui     | `components.json`, `components/ui/*`, `@radix-ui/*` |
| HeroUI/NextUI | `@heroui/react`, `@nextui-org/react`                |
| MUI           | `@mui/material`                                     |
| Ant Design    | `antd`                                              |
| Mantine       | `@mantine/core`                                     |
| Chakra UI     | `@chakra-ui/react`                                  |

Each guide maps the old library's components, part names and props to XiodUI's, and replaces its toast, theme, form and icon helpers. They all follow the same order: list the files that use the old library, set XiodUI up next to it, migrate one file at a time and build after each, then uninstall the old library and check light, dark and phone-width layouts.

To start, ask the agent something like:

```text
Migrate this app from shadcn/ui to XiodUI.
```

> [!NOTE]
> Where a component has no XiodUI equivalent, the guide says so and what to use instead. The agent is told never to invent a component or prop to fill the gap.

## Without the skill

For an agent that can't install skills, point it at the documentation directly:

- [`/llms.txt`](https://ui.xiod.dev/llms.txt) lists every page of these docs.
- [`/llms-full.txt`](https://ui.xiod.dev/llms-full.txt) is the whole documentation in one file.
- Every page is also available as Markdown at its own URL plus `.md`, and the **Copy page** button at the top of each page copies it.

---

# Colors

> Every colour token, what it's for, and how tokens pair up.

Source: https://ui.xiod.dev/docs/styling/colors

## How the tokens work

Components never hard-code a colour. Every one of them reads a CSS custom property — a _token_ — defined in `xiod-ui/styles`. Change a token and everything that uses it changes with it, which is the whole of how theming works here.

> [!NOTE]
> **Tokens come in pairs**
> A token names a surface. The matching `-foreground` token is what goes _on_ that surface. `--card` is the panel; `--card-foreground` is the text on the panel. Whenever you change one, look at the other.

> [!NOTE]
> **Each token is a Tailwind class**
> `--primary` gives you `bg-primary`, `text-primary`, `border-primary`, and so on — the token name minus the dashes. Your own markup can use them exactly like the components do.

```tsx title="Anywhere in your app"
/* Every token is available as a Tailwind utility, on any property
   that takes a colour. There is no xiodui- prefix. */

<div className="bg-card text-card-foreground border-border" />
<p className="text-muted-foreground" />
<span className="bg-primary/10 text-primary" />   {/* opacity works too */}

/* And in plain CSS, if you prefer: */
.my-panel {
  background: var(--card);
  color: var(--card-foreground);
}
```

Values can be written in any CSS colour syntax — `#0f6b72`, `oklch(0.55 0.21 264)`, `hsl(...)`, even `color-mix()`. The library uses a mix of all of them internally. Nothing is parsed at build time, so there is no format to conform to.

To change any of them, see the [Customization](https://ui.xiod.dev/docs/styling/customization) page. This page is the reference for what exists.

## Surfaces

The three layers a page is built from: the page itself, panels raised off it, and floating overlays like menus and popovers.

| Name | Token | Text on it |
| --- | --- | --- |
| Background | `--background` | `--foreground` |
| Card | `--card` | `--card-foreground` |
| Popover | `--popover` | `--popover-foreground` |

## Theme colors

`--primary` is your brand colour — it drives the default button, links, and focus emphasis. `--muted` and `--accent` are the quiet greys behind hover states and secondary text. If you only ever change one token, change `--primary`.

| Name | Token | Text on it |
| --- | --- | --- |
| Primary | `--primary` | `--primary-foreground` |
| Secondary | `--secondary` | `--secondary-foreground` |
| Muted | `--muted` | `--muted-foreground` |
| Accent | `--accent` | `--accent-foreground` |

## State colors

Error, information, success, and warning. Each has a `-foreground` partner, but it does not mean what it means above — see the note under the swatches.

| Name | Token | Text on it |
| --- | --- | --- |
| Destructive | `--destructive` | – |
| Info | `--info` | – |
| Success | `--success` | – |
| Warning | `--warning` | – |

> [!WARNING]
> **The state `-foreground` tokens are the exception**
> `--destructive-foreground` is not the text on a solid destructive button — that is always white. It is a darker shade of the same hue, meant for text on a faint tint of the colour, which is how alerts and outline buttons are drawn. The same holds for `--info`, `--success` and `--warning`. Set it to a readable shade of its own colour, not to a contrasting one.

## Lines and focus

`--border` is every divider and outline, `--input` the slightly stronger edge on form fields, and `--ring` the keyboard focus ring. These are usually near-transparent, so they may look almost invisible below.

| Name | Token | Text on it |
| --- | --- | --- |
| Border | `--border` | – |
| Input | `--input` | – |
| Ring | `--ring` | – |

## Corner radius

Not a colour, but the same idea. `--radius` is a single length that every component derives its corners from, so one value sets how round or how square the whole library looks.

- 0rem — square
- 0.625rem — default
- 1.25rem — round

Components step off it rather than using it raw — a small badge uses `calc(var(--radius) - 4px)` and a card the full value — so the proportions hold at every size. Each shipped palette sets its own `--radius` to suit its character.

## Sidebar colors

A parallel set used only by the sidebar, so app navigation can sit on its own surface without dragging the rest of the page with it. If you do not use the sidebar, you can ignore these entirely.

| Name | Token | Text on it |
| --- | --- | --- |
| Sidebar | `--sidebar` | `--sidebar-foreground` |
| Sidebar Primary | `--sidebar-primary` | `--sidebar-primary-foreground` |
| Sidebar Accent | `--sidebar-accent` | `--sidebar-accent-foreground` |

`--sidebar-border` and `--sidebar-ring` complete the set, matching `--border` and `--ring`.

## MorphicToast

MorphicToast has its own tokens for its motion and state colours. Override them like any other token.

| Token                     | Controls                                                                                 |
| :------------------------ | :--------------------------------------------------------------------------------------- |
| `--morphic-duration`      | How long the toast takes to morph (600ms)                                                |
| `--morphic-spring-easing` | The easing curve of the morph                                                            |
| `--morphic-state-<state>` | The colour for each state: `success`, `error`, `warning`, `info`, `loading` and `action` |

---

# Typography

> The Text component's type scale, weights and variants.

Source: https://ui.xiod.dev/docs/styling/typography

## The Text component

`Text` from `xiod-ui/text` applies the library's type scale, so headings and body copy match the components around them without repeating utility classes. It sets size, weight and colour only. The font comes from your app's `font-sans` and `font-mono`, and XiodUI doesn't ship a font.

```tsx title="components/ArticleHeader.tsx"
import { Text } from "xiod-ui/text";

export function ArticleHeader() {
  return (
    <header className="space-y-2">
      <Text variant="heading1">Release notes</Text>
      <Text size="lg">What changed in this version, and how to upgrade.</Text>
      <Text variant="secondary" size="sm">
        Updated 2 hours ago · 4 min read
      </Text>
    </header>
  );
}
```

`Text` renders a `<p>` by default. The heading variants render `<h1>`–`<h4>` and the mono variants a `<span>`. Pass `render` for any other element (see [below](#polymorphic-rendering)).

## Headings

Four heading variants, each semibold with slightly tight letter-spacing.

| Variant | Element | Size | Use |
| --- | --- | --- | --- |
| `heading1` | `<h1>` | 30px / 1.875rem | Page title, hero |
| `heading2` | `<h2>` | 24px / 1.5rem | Section heading |
| `heading3` | `<h3>` | 20px / 1.25rem | Subsection, card header |
| `heading4` | `<h4>` | 18px / 1.125rem | Widget, group header |

All four are semibold with `-0.025em` tracking.

## Body sizes

`size` sets the body text size. Sizes are one step larger on phones, where text is read at arm's length, and one step smaller from the `sm` breakpoint up.

| Props | Size | Use |
| --- | --- | --- |
| `size="xl"` | 18px (20px on phones) | Lead, editorial intro |
| `size="lg"` | 16px (18px on phones) | Subtitle, callout |
| `size="default"` | 14px (16px on phones) | Standard paragraph |
| `variant="secondary" size="sm"` | 12px (14px on phones) | Meta details, helper text |
| `size="xs"` | 12px | Footnote, legal, micro-copy |

## Weights

`weight` is `normal`, `medium`, `semibold` or `bold`, and combines with any size.

Every weight — `normal` (400), `medium` (500), `semibold` (600), `bold` (700) — combines with every size: `xl`, `lg`, `default`, `sm`, `xs`.

## Colour variants

`secondary` is muted text for metadata and helper copy. `success`, `info`, `warning` and `error` use the matching state colour, for inline feedback such as a field's validation message.

`success`, `info`, `warning` and `error` colour text with the matching state token, for alerts, status badges and form feedback.

## Monospace

`mono` and `mono-secondary` set text in `font-mono`, for commands, paths, IDs and values.

- `variant="mono"` — primary monospace for commands, paths and values.
- `variant="mono-secondary"` — subdued monospace for hashes, IDs and metadata.

## Rendering another element

Pass an element to `render` to keep the styles on a different tag, with that element's own props.

```tsx title="components/EmailLabel.tsx"
import { Text } from "xiod-ui/text";

export function EmailLabel() {
  return (
    <Text size="sm" weight="medium" render={<label htmlFor="email" />}>
      Email address
    </Text>
  );
}
```

A heading variant with `render` changes the tag without changing the look, so a visually large heading can still be an `<h2>` in the page outline:

```tsx
<Text variant="heading1" render={<h2 />}>
  Pricing
</Text>
```

## Truncation

`truncate` keeps text on one line and ends it with an ellipsis when it runs out of room, including inside flex layouts.

```tsx title="components/ProjectName.tsx"
import { Text } from "xiod-ui/text";

export function ProjectName({ name }: { name: string }) {
  return (
    <div className="w-48">
      <Text size="sm" truncate>
        {name}
      </Text>
    </div>
  );
}
```

---

# Themes

> Ready-made palettes, and letting users switch between them.

Source: https://ui.xiod.dev/docs/styling/themes

## What a theme is

A theme is a full set of the tokens on the [Colors](https://ui.xiod.dev/docs/styling/colors) page, plus `--radius`, in one stylesheet. Import it and every component follows, because components only read the tokens.

20 palettes ship with the library, in two families. Each one defines both colour schemes, so a theme and dark mode are independent choices rather than a grid you have to maintain.

## Apply one theme

Import a palette after `xiod-ui/styles`. It overrides the base tokens outright, so the whole app is that palette and nothing in your markup changes.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";

/* One line. Every token from the Colors page is redefined, light and dark. */
@import "xiod-ui/themes/cobalt";
```

Order matters: the import has to come after `xiod-ui/styles`, or the base tokens win. You can still override individual tokens below the import — the palette is a starting point, not a lock.

## Offer a choice

To let your own users pick, import the `/scoped` variant of each palette instead. A scoped stylesheet only applies under `[data-palette="name"]`, so several can coexist without fighting over the base tokens.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";

/* Scoped: each palette applies only under its own data-palette attribute,
   so importing several is safe — none of them touch the base tokens. */
@import "xiod-ui/themes/cobalt/scoped";
@import "xiod-ui/themes/lagoon/scoped";
@import "xiod-ui/themes/riso/scoped";
```

Then switch palettes with `setPalette` from `useTheme`. It writes the attribute to `<html>`, remembers the choice in localStorage and suppresses transitions during the swap, the same way the light/dark toggle does. A returning visitor's palette applies before the page first paints, like their light or dark choice, so it never flashes the default palette first. This needs `ThemeProvider` in your root layout — see the [Dark Mode](https://ui.xiod.dev/docs/styling/dark-mode) page for that setup.

```tsx title="components/PaletteSwitcher.tsx"
"use client";

import { Button } from "xiod-ui/button";
import { useTheme } from "xiod-ui/theme-provider";

const PALETTES = [
  { value: "cobalt", label: "Cobalt" },
  { value: "lagoon", label: "Lagoon" },
  { value: undefined, label: "Default" },
];

export function PaletteSwitcher() {
  const { palette, setPalette } = useTheme();

  return (
    <div className="flex gap-2">
      {PALETTES.map(({ value, label }) => (
        <Button
          key={label}
          variant={palette === value ? "default" : "outline"}
          onClick={() => setPalette(value)}
        >
          {label}
        </Button>
      ))}
    </div>
  );
}
```

Import only the palettes you actually offer. Each scoped stylesheet is about 1KB gzipped, but they all ship on every page.

## The palettes

Every card below is painted by that palette's real tokens, in whichever colour scheme you are currently reading in. Press _Try it_ to apply one to this entire site.

**Core** — Restrained enough to ship as-is.

- Neutral (the base, no import): The base theme, shipped with the library.
- Clay (`xiod-ui/themes/clay`): Warm cream and terracotta.
- Sepia (`xiod-ui/themes/sepia`): Aged paper and tanned leather.
- Sage (`xiod-ui/themes/sage`): Muted garden green.
- Lagoon (`xiod-ui/themes/lagoon`): Deep teal on cool mineral.
- Cobalt (`xiod-ui/themes/cobalt`): Deep cobalt blue on cool grey.
- Iris (`xiod-ui/themes/iris`): Indigo and violet on soft lilac.
- Roast (`xiod-ui/themes/roast`): Dark coffee and steamed cream.
- Crimson (`xiod-ui/themes/crimson`): Oxblood, olive and steel on gunmetal.
- Sorbet (`xiod-ui/themes/sorbet`): Rose, sky and citrus.

**Expressive** — Louder, with a point of view.

- Cel (`xiod-ui/themes/cel`): Sky blue and marigold, flat and high-key.
- Afterglow (`xiod-ui/themes/afterglow`): Sunset warmth by day, cerulean by night.
- Ion (`xiod-ui/themes/ion`): Violet and readout green on instrument grey.
- Cathode (`xiod-ui/themes/cathode`): Hot magenta and phosphor green on cold concrete.
- Riso (`xiod-ui/themes/riso`): Magenta and cyan misprint on newsprint.
- Taffy (`xiod-ui/themes/taffy`): Watermelon, sky and lemon.
- Mochi (`xiod-ui/themes/mochi`): Milky orchid, mint and blush.
- Blacklight (`xiod-ui/themes/blacklight`): Ultraviolet, acid green and hot pink.
- Toxin (`xiod-ui/themes/toxin`): Biohazard green and blood on wet concrete.
- Cinder (`xiod-ui/themes/cinder`): Molten orange on cold ash.

## What is guaranteed

Both families are held to the same bar. The difference is how much personality a palette imposes, not how carefully it was built.

- **Readable text.** Every `*-foreground` token clears 4.5:1 against the surface it actually sits on — including the state foregrounds, which are checked against their own colour tinted over the background at the opacity components really use.
- **Usable controls.** White text clears 4.5:1 on the solid `destructive` fill, and that fill clears 3:1 against the background, so a destructive button is legible as a control and not only as text.
- **Distinct from each other.** No two palettes' primaries sit closer than 0.055 in OKLab, a shade above the range where two colours read as one. Palettes may share a hue; none should be mistakable for another at a glance.

The library's build checks all three, so a palette that fails one can't ship.

## Rolling your own

A palette is only a stylesheet of tokens, so you can start from the closest one and override the tokens that differ below its import. [Customization](https://ui.xiod.dev/docs/styling/customization#start-from-palette) shows how, with the full token set as a template.

---

# Customization

> Override tokens for the whole app, one section, or one element.

Source: https://ui.xiod.dev/docs/styling/customization

## There is only one mechanism

Every colour, and the corner radius, is a CSS custom property. Components read those properties and nothing else. So customising XiodUI means redefining the properties you care about in your own stylesheet — no config file, no plugin, no wrapper components, and nothing to eject from.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";

/* Your overrides go below the import. That is the entire mechanism. */
:root {
  --primary: #4f46e5;
}
```

That is a complete, working customisation. Every button, link, and focus ring in the app is now indigo. If you only read one section of this page, this was it.

## Two rules that trip people up

> [!NOTE]
> **Overrides go after the import**
> CSS gives the last matching rule the win. Put your `:root` block above `@import "xiod-ui/styles"` and the library defaults simply overwrite it. Imports also have to sit at the top of the file, so in practice: imports first, your rules after.

> [!NOTE]
> **Use :root, not @theme**
> `@theme` is where Tailwind defines its own scales. XiodUI's tokens are already wired into Tailwind for you, so they are set on `:root` like ordinary CSS. Putting them in `@theme` quietly does nothing.

## Setting your brand colour

A colour is rarely alone. `--primary` is the fill; `--primary-foreground` is the label printed on that fill, and `--ring` is the focus outline that should match. Set all three, in both colour schemes.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";

:root {
  --primary: #4f46e5; /* the button fill */
  --primary-foreground: #ffffff; /* the label on that fill */
  --ring: #4f46e5; /* the focus ring, so it matches */

  @variant dark {
    --primary: #a5b4fc; /* lighter, so it reads on a dark page */
    --primary-foreground: #1e1b4b; /* dark text, because the fill is now light */
    --ring: #a5b4fc;
  }
}
```

> [!IMPORTANT]
> **Do not skip the dark values**
> Tokens you set only in `:root` apply in dark mode too, because nothing overrides them back. A brand colour picked to sit on white usually goes muddy on a dark page — most palettes use a lighter, less saturated version at night, and flip the foreground from white to dark to match.
>
> Put them in `@variant dark` rather than a separate `.dark { … }` rule. The variant matches from the first paint, while `ThemeProvider` puts the `dark` class on `<html>` only once React has hydrated, so a plain `.dark` rule would briefly show your light values to dark-mode visitors.

## Start from a palette

Writing all thirty-odd tokens by hand is real work, and most of it is deciding on greys. It is usually faster to import one of the shipped palettes and change the few tokens you disagree with — the import is just a stylesheet, so your rules below it still win.

```css title="app/globals.css"
@import "tailwindcss";
@import "xiod-ui/styles";

/* Start from a palette that is already close... */
@import "xiod-ui/themes/cobalt";

/* ...then change only what you disagree with. */
:root {
  --radius: 0.25rem;
  --primary: #1d4ed8;

  @variant dark {
    --primary: #93c5fd;
  }
}
```

## Or start from scratch

If you would rather define everything yourself, this is the complete set. Copy it below the import and edit in place — anything you leave out falls back to the library default, so you can also delete the parts you do not care about.

```css title="app/globals.css"
:root {
  --radius: 0.625rem;

  /* Surfaces */
  --background: #ffffff;
  --foreground: #262626;
  --card: #ffffff;
  --card-foreground: #262626;
  --popover: #ffffff;
  --popover-foreground: #262626;

  /* Theme */
  --primary: #262626;
  --primary-foreground: #fafafa;
  --secondary: #f5f5f5;
  --secondary-foreground: #262626;
  --muted: #f5f5f5;
  --muted-foreground: #737373;
  --accent: #f5f5f5;
  --accent-foreground: #262626;

  /* States — the -foreground is text on a TINT of the colour, not on the
     solid fill. Keep it the same hue, just darker. */
  --destructive: #ef4444;
  --destructive-foreground: #b91c1c;
  --info: #3b82f6;
  --info-foreground: #1d4ed8;
  --success: #10b981;
  --success-foreground: #047857;
  --warning: #f59e0b;
  --warning-foreground: #b45309;

  /* Lines and focus */
  --border: #e5e5e5;
  --input: #d4d4d4;
  --ring: #a3a3a3;

  /* Sidebar — safe to delete if you do not use it */
  --sidebar: #fafafa;
  --sidebar-foreground: #525252;
  --sidebar-primary: #262626;
  --sidebar-primary-foreground: #fafafa;
  --sidebar-accent: #f5f5f5;
  --sidebar-accent-foreground: #262626;
  --sidebar-border: #ebebeb;
  --sidebar-ring: #a3a3a3;

  @variant dark {
    /* Every token above, again, with dark-scheme values. Anything you leave
       out here keeps the library's dark default. */
    --background: #0a0a0a;
    --foreground: #f5f5f5;
    /* ... */
  }
}
```

Values can be any CSS colour syntax — hex, `oklch()`, `hsl()`, `color-mix()`. Hex is used here only because it is the easiest to paste from a design tool.

## Keeping it readable

Nothing stops you shipping unreadable colours, so two checks are worth doing by hand — they are the ones every shipped palette is held to.

- **Text on its own surface.** Each `-foreground` against its partner should reach 4.5:1 — `--foreground` on `--background`, `--primary-foreground` on `--primary`, and so on down the list.
- **The destructive fill.** Destructive buttons print white text on `--destructive` regardless of your tokens, so that colour has to be dark enough for white to read on it — and still distinct enough from `--background` to look like a control.

Any contrast checker will do. The failure to watch for is a `--primary` that looks great as a large button and becomes unreadable as a small link.

## Corner radius

`--radius` is one length that every component derives its corners from. Set it to `0rem` for a square, technical look, or past `1rem` for a soft, consumer one — nothing else needs to change.

```css title="app/globals.css"
:root {
  --radius: 0rem; /* square */
  --radius: 1.25rem; /* or round */
}
```

## Changing only part of the app

Tokens obey the cascade like any other CSS property, so an override can be attached to any selector rather than the whole document. Useful for a marketing page that should look louder than the product, or an embedded widget that has to match a host.

```css title="app/globals.css"
/* An override does not have to be global. Any selector works, because
   tokens cascade like any other CSS property. */

.marketing-site {
  --primary: #db2777;
  --radius: 1.5rem;
}

/* Everything inside is pink and round; the rest of the app is untouched. */
```

This is exactly how the shipped palettes work in their `/scoped` form — they attach to `[data-palette="name"]` instead of `:root`. See the [Themes](https://ui.xiod.dev/docs/styling/themes) page.

## Changing a single element

When you want one button to be different rather than every button, do not touch the tokens at all.

```tsx title="Any component"
/* For a single element, skip tokens entirely — every component
   forwards className, and your class wins. */

<Button className="bg-emerald-600 text-white hover:bg-emerald-700">
  Publish
</Button>

/* Reach for a token when you want the change everywhere,
   and for className when you want it exactly here. */
```

---

# Icons

> Swap any built-in icon, per instance or app-wide.

Source: https://ui.xiod.dev/docs/styling/icons

## Where the icons come from

Components draw their icons from [XiodIcons](https://icons.xiod.dev), which installs with `xiod-ui`. Every one of them can be replaced: with a component from another icon library, an inline `<svg>`, or an emoji. There are two ways to do it, and they combine.

## Change one instance

To change a single place, pass the part an icon prop. A part with one icon takes `icon`; a part with several takes named props such as `prevIcon` / `nextIcon` or `triggerIcon` / `clearIcon`. The value is anything React can render.

```tsx title="components/SaveDialog.tsx"
import { X } from "lucide-react";
import { DialogPopup } from "xiod-ui/dialog";

export function SaveDialog() {
  return (
    <DialogPopup closeIcon={<X className="size-4" />}>{/* … */}</DialogPopup>
  );
}
```

A node passed this way renders exactly as given, so give it its own size classes. Pass `null` to render no icon at all.

Every part that takes an icon lists it in the **API Reference** on its component page.

## Change it everywhere

To swap an icon across the whole app, wrap it in `IconProvider` from `xiod-ui/icon-provider`, keyed by the icon's name. Names you leave out keep the built-in icon.

```tsx title="app/providers.tsx"
"use client";

import { ArrowLeft, ArrowRight, Check, X } from "lucide-react";
import { IconProvider } from "xiod-ui/icon-provider";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <IconProvider
      icons={{
        Cancel: X,
        Check,
        ChevronLeft: ArrowLeft,
        ChevronRight: ArrowRight,
      }}
    >
      {children}
    </IconProvider>
  );
}
```

Pass components here, not elements (`Check`, not `<Check />`). Each XiodUI component then renders your icon with the size and colour classes it would have given its own, so the replacement fits without extra styling.

Providers nest. An inner one is merged over the outer one, so a section of the app can change a single icon without restating the rest.

## Which one wins

1. An icon prop on the part.
2. The nearest `IconProvider`.
3. The built-in XiodIcons icon.

FileUpload's file-type icons and AgentSteps' status icons are chosen from the content (the file's type, the step's status), so change those through the provider rather than a prop.

## Icon names

The names `IconProvider` accepts, exported as the `IconName` type:

| Group      | Names                                                                                                                                  |
| :--------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| Navigation | `ChevronUp`, `ChevronDown`, `ChevronLeft`, `ChevronRight`, `ChevronFirst`, `ChevronLast`, `ArrowRight`, `UnfoldMore`, `MoreHorizontal` |
| Status     | `Check`, `CheckmarkCircle`, `Alert`, `AlertCircle`, `InformationCircle`, `LoadingSpinner`, `SecurityCheck`                             |
| Actions    | `Cancel`, `Copy`, `Delete`, `Pencil`, `Search`, `PlusSign`, `MinusSign`, `Eye`, `EyeOff`, `Dropper`, `Zap`, `Terminal`                 |
| Files      | `File`, `FileEmpty`, `FileArchive`, `FileAudio`, `FileCode`, `FileImage`, `FileVideo`                                                  |
| Layout     | `GripHorizontal`, `GripVertical`, `ViewSidebarLeft`, `ArrowExpandDiagonalUpRight`, `ArrowShrinkDiagonalUpRight`                        |
| Other      | `Calendar`, `CreditCard`                                                                                                               |

## Your own components

A component of your own can honour the same overrides. `IconSlot` renders one icon the way the library's components do: the `icon` prop first, then the provider, then the fallback you give it.

```tsx title="components/NextButton.tsx"
import { ChevronRight } from "xiod-icons";
import { Button } from "xiod-ui/button";
import { IconSlot } from "xiod-ui/icon-provider";

export function NextButton({ icon }: { icon?: React.ReactNode }) {
  return (
    <Button variant="outline">
      Next
      <IconSlot name="ChevronRight" fallback={ChevronRight} icon={icon} />
    </Button>
  );
}
```

For the component alone, `useIcon(name, fallback)` returns the one in effect.

---

# Dark Mode

> Light, dark and system modes with ThemeProvider and useTheme.

Source: https://ui.xiod.dev/docs/styling/dark-mode

## How it works

Every token has a light and a dark value, and `xiod-ui/styles` switches between them through Tailwind's `dark:` variant. Components use the tokens, so they need nothing else: once the page is in dark mode, everything is.

For a site that is always dark, put `class="dark"` on `<html>` and stop there.

## Add the provider

To follow the system setting and let users choose, wrap your app in `ThemeProvider` from `xiod-ui/theme-provider`. It starts on `"system"`, follows `prefers-color-scheme`, and remembers the user's choice in localStorage.

```tsx title="app/layout.tsx"
import { ThemeProvider } from "xiod-ui/theme-provider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}
```

That is the whole setup. The saved mode and palette apply before the page first paints, server-rendered pages included, so there is no flash of light mode, no script of your own, and no `suppressHydrationWarning` on `<html>`.

## Build a switcher

`useTheme` returns the selected `theme` (`"light"`, `"dark"` or `"system"`), the `resolvedTheme` actually applied (never `"system"`), and `setTheme`. While the mode changes, transitions are paused so colours switch at once instead of animating.

```tsx title="components/ThemeToggle.tsx"
"use client";

import { Moon, Sun } from "xiod-icons";
import { Button } from "xiod-ui/button";
import { useTheme } from "xiod-ui/theme-provider";

export function ThemeToggle() {
  const { resolvedTheme, setTheme } = useTheme();

  return (
    <Button
      variant="outline"
      size="icon"
      aria-label="Toggle dark mode"
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      <Sun className="hidden dark:block" />
      <Moon className="dark:hidden" />
    </Button>
  );
}
```

To offer "System" as a third choice, call `setTheme("system")`.

The icon is chosen with `dark:` classes rather than from `resolvedTheme`, and that is deliberate. The server can't know which mode a visitor chose, so the HTML it sends is rendered with `resolvedTheme` at its default; the value is only right once React has hydrated. Styles follow the real mode from the first paint, so anything visual belongs in `dark:` classes. Read `resolvedTheme` in event handlers, or render what depends on it after mount.

## No flash on load

A dark-mode visitor never sees the page in light mode, even before your JavaScript loads. On a server-rendered page, the provider includes a tiny inline script that reads the saved mode and palette while the browser is still parsing, before anything paints. It marks the choice on an empty `<style>` element at the top of `<body>`, which the stylesheet reads. `<html>` is left exactly as the server rendered it, so React has no mismatch to warn about.

Once React has hydrated and the browser is idle, the provider moves the mode onto `<html>` as the `dark` class and removes the marker.

Two things follow from this:

- **Write your dark styles with the `dark` variant**: `dark:` classes in markup, and `@variant dark` in CSS. Both follow the marker, so they apply from the first paint. A plain `.dark { … }` or `html.dark …` rule still works, but only from the moment React hydrates, so it can briefly show the light version. To change dark token values, see [Customization](https://ui.xiod.dev/docs/styling/customization).

  ```css title="app/globals.css"
  .article-figure {
    @variant dark {
      filter: invert(1);
    }
  }
  ```

- **With a Content Security Policy that requires a nonce** for inline scripts, pass the request's nonce to the provider. Without one, the browser blocks the script and the saved mode applies only after hydration.

  ```tsx title="app/layout.tsx"
  import { headers } from "next/headers";

  export default async function RootLayout({
    children,
  }: {
    children: React.ReactNode;
  }) {
    const nonce = (await headers()).get("x-nonce") ?? undefined;

    return (
      <html lang="en">
        <body>
          <ThemeProvider nonce={nonce}>{children}</ThemeProvider>
        </body>
      </html>
    );
  }
  ```

> [!NOTE]
> **Upgrading from 1.1.0 or earlier**
> Delete any theme script you added to `<head>` to avoid the flash, and remove `suppressHydrationWarning` from `<html>` if nothing else needs it. The provider does both jobs now.

## Provider options

| Prop                | Default          | What it does                                                                                   |
| :------------------ | :--------------- | :--------------------------------------------------------------------------------------------- |
| `defaultTheme`      | `"system"`       | The mode before the user has chosen one.                                                       |
| `enableSystemTheme` | `true`           | Follow `prefers-color-scheme` while the mode is `"system"`.                                    |
| `attribute`         | `"class"`        | How the mode is written to `<html>`. Any other value is set as an attribute.                   |
| `storageKey`        | `"theme"`        | The localStorage key for the mode.                                                             |
| `defaultPalette`    | —                | The palette before the user has chosen one. See [Themes](https://ui.xiod.dev/docs/styling/themes#offer-a-choice). |
| `paletteAttribute`  | `"data-palette"` | The attribute the palette is written to.                                                       |
| `paletteStorageKey` | `"palette"`      | The localStorage key for the palette.                                                          |
| `nonce`             | —                | The nonce for the inline script, when a Content Security Policy requires one.                  |

Keep `attribute` as `"class"` unless you have a reason to change it: the `dark:` variant and the dark token values key off the `dark` class.

---

# Accordion

> A stack of headings that each expand to reveal a section of content.

Source: https://ui.xiod.dev/docs/components/accordion

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Accordion,
  AccordionItem,
  AccordionPanel,
  AccordionTrigger
} from "xiod-ui/accordion";
```

Anatomy:

```tsx
<Accordion>
  <AccordionItem>
    <AccordionTrigger />
    <AccordionPanel />
  </AccordionItem>
</Accordion>
```

## Example

```tsx
import {
  Accordion,
  AccordionItem,
  AccordionPanel,
  AccordionTrigger,
} from "xiod-ui/accordion";

export default function AccordionExample() {
  const items = [
    {
      content:
        "A React component library: styled, accessible components built on Base UI and Tailwind CSS 4, shipped as one npm package.",
      id: "1",
      title: "What is XiodUI?",
    },
    {
      content:
        'Install xiod-ui, add @import "xiod-ui/styles" after Tailwind in your CSS, and import each component from its own path, such as xiod-ui/button.',
      id: "2",
      title: "How do I get started?",
    },
    {
      content:
        "Yes, commercial or not. The licence only rules out using XiodUI to build a competing component library or UI kit.",
      id: "3",
      title: "Can I use it for my project?",
    },
  ];

  return (
    <div className="w-full max-w-md">
      <Accordion defaultValue={["3"]}>
        {items.map((item) => (
          <AccordionItem key={item.id} value={item.id}>
            <AccordionTrigger>{item.title}</AccordionTrigger>
            <AccordionPanel>{item.content}</AccordionPanel>
          </AccordionItem>
        ))}
      </Accordion>
    </div>
  );
}
```

## API Reference

### Accordion

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `AccordionValue<any>` | – | The uncontrolled value of the item(s) that should be initially expanded. To render a controlled accordion, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `hiddenUntilFound` | `boolean` | `false` | Allows the browser's built-in page search to find and expand the panel contents. Overrides the `keepMounted` prop and uses `hidden="until-found"` to hide the element without removing it from the DOM. |
| `keepMounted` | `boolean` | `false` | Whether to keep the element in the DOM while the panel is closed. This prop is ignored when `hiddenUntilFound` is used. |
| `multiple` | `boolean` | `false` | Whether multiple items can be open at the same time. |
| `onValueChange` | `((value: AccordionValue<any>, eventDetails: AccordionRootChangeEventDetails) => void)` | – | Event handler called when an accordion item is expanded or collapsed. Provides the new value as an argument. |
| `value` | `AccordionValue<any>` | – | The controlled value of the item(s) that should be expanded. To render an uncontrolled accordion, use the `defaultValue` prop instead. |

### AccordionItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onOpenChange` | `((open: boolean, eventDetails: AccordionItemChangeEventDetails) => void)` | – | Event handler called when the panel is opened or closed. |
| `value` | `any` | – | A unique value that identifies this accordion item. If no value is provided, a unique ID will be generated automatically. Use when controlling the accordion programmatically, or to set an initial open state. |

### AccordionPanel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hiddenUntilFound` | `boolean` | `false` | Allows the browser's built-in page search to find and expand the panel contents. Overrides the `keepMounted` prop and uses `hidden="until-found"` to hide the element without removing it from the DOM. |
| `keepMounted` | `boolean` | `false` | Whether to keep the element in the DOM while the panel is closed. This prop is ignored when `hiddenUntilFound` is used. |

### AccordionTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

---

# Agent Steps

> A live list of the steps an AI agent is taking, with a status for each and collapsible logs.

Source: https://ui.xiod.dev/docs/components/agent-steps

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  AgentSteps,
  AgentStep,
  AgentStepIcon,
  AgentStepLabel
} from "xiod-ui/agent-steps";
```

Anatomy:

```tsx
<AgentSteps>
  <AgentStep>
    <AgentStepIcon />
    <AgentStepLabel />
  </AgentStep>
</AgentSteps>
```

## Example

```tsx
"use client";

import {
  AgentStep,
  AgentStepIcon,
  AgentStepLabel,
  AgentSteps,
} from "xiod-ui/agent-steps";
import { Badge } from "xiod-ui/badge";

export default function AgentStepsExample() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-12">
      {/* Auto-cycling */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Auto Cycling
        </Badge>
        <AgentSteps
          steps={["Thinking", "Searching", "Planning", "Refining"]}
          interval={2000}
        />
      </div>

      {/* Statuses */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Statuses
        </Badge>
        <div className="flex flex-col items-start gap-3.5">
          <AgentSteps
            showSpinner
            icon="searching"
            status="running"
            label="Reading project files"
          />
          <AgentSteps
            icon="done"
            status="completed"
            label="Updated 4 components"
          />
          <AgentSteps icon="error" status="failed" label="Type check failed" />
        </div>
      </div>

      {/* Composition */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Composition
        </Badge>
        <AgentSteps>
          <div className="flex flex-col items-start gap-3.5">
            <AgentStep status="completed">
              <AgentStepIcon icon="thinking" />
              <AgentStepLabel>Analyze requirements</AgentStepLabel>
            </AgentStep>
            <AgentStep status="running">
              <AgentStepIcon icon="editing" showSpinner />
              <AgentStepLabel shimmer>Write implementation</AgentStepLabel>
            </AgentStep>
            <AgentStep status="waiting">
              <AgentStepIcon icon="verify" />
              <AgentStepLabel>Verify the output</AgentStepLabel>
            </AgentStep>
          </div>
        </AgentSteps>
      </div>
    </div>
  );
}
```

## API Reference

### AgentSteps

Also exported as `AgentStepIndicator`. Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableShimmer` | `boolean` | `false` | Whether to turn off the shimmer that sweeps across the text. Used when there are no `children`. |
| `icon` | `AgentStepIconValue` | – | The step's icon: a built-in name such as `thinking` or `searching`, or an icon component. Used when there are no `children`. |
| `interval` | `number` | `4000` | How long each of the `steps` is shown, in milliseconds. |
| `label` | `ReactNode` | – | The text of the step shown. Used when there are no `children`. |
| `showIcon` | `boolean` | `true` | Whether to show the icon. Used when there are no `children`. |
| `showSpinner` | `boolean` | `false` | Whether to show a spinning dashed ring around the icon while the step is `running`. Used when there are no `children`. |
| `size` | `"sm" \| "md" \| "lg"` | `md` | The size of the component. |
| `status` | `"completed" \| "waiting" \| "running" \| "failed"` | `running` | The step's status. `completed`, `failed` and `waiting` show their own icon and text style; the shimmer and spinner only run while `running`. Used when there are no `children`. |
| `steps` | `AgentStepItem[] \| string[]` | – | Steps to show one after another, every `interval` milliseconds, looping. Take the place of `label` and `icon`. Used when there are no `children`. |

### AgentStep

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"completed" \| "waiting" \| "running" \| "failed"` | `running` | The step's status. `completed`, `failed` and `waiting` show their own icon and text style; the shimmer and spinner only run while `running`. Used when there are no `children`. |

### AgentStepIcon

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `AgentStepIconValue` | – | The step's icon: a built-in name such as `thinking` or `searching`, or an icon component. Used when there are no `children`. |
| `showSpinner` | `boolean` | `false` | Whether to show a spinning dashed ring around the icon while the step is `running`. Used when there are no `children`. |

### AgentStepLabel

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shimmer` | `boolean` | `true` | Whether the label shows a shimmer sweep while its step is running. |

---

# Alert

> A callout that draws attention to a message, with an info, success, warning or error tone.

Source: https://ui.xiod.dev/docs/components/alert

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle
} from "xiod-ui/alert";
```

Anatomy:

```tsx
<Alert>
  <AlertTitle />
  <AlertDescription />
  <AlertAction />
</Alert>
```

## Example

```tsx
import {
  CircleCheck as CircleCheckIcon,
  InformationCircle as InfoIcon,
} from "xiod-icons";
import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from "xiod-ui/alert";
import { Button } from "xiod-ui/button";

export default function AlertExample() {
  return (
    <div className="space-y-6">
      <Alert>
        <InfoIcon />
        <AlertTitle>Heads up!</AlertTitle>
        <AlertDescription>
          Describe what can be done about it here.
        </AlertDescription>
        <AlertAction>
          <Button size="xs" variant="ghost">
            Dismiss
          </Button>
          <Button size="xs">Ok</Button>
        </AlertAction>
      </Alert>

      <Alert variant="info">
        <InfoIcon />
        <AlertTitle>Heads up!</AlertTitle>
        <AlertDescription>
          Describe what can be done about it here.
        </AlertDescription>
      </Alert>
      <Alert variant="success">
        <CircleCheckIcon />
        <AlertTitle>Heads up!</AlertTitle>
        <AlertDescription>
          Describe what can be done about it here.
        </AlertDescription>
      </Alert>
    </div>
  );
}
```

## API Reference

### Alert

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"error" \| "default" \| "success" \| "warning" \| "info"` | `default` | The visual style of the component. |

### AlertAction

Accepts `render`, plus every native `<div>` attribute.

### AlertDescription

Accepts `render`, plus every native `<div>` attribute.

### AlertTitle

Accepts `render`, plus every native `<div>` attribute.

---

# Alert Dialog

> A modal dialog that asks the user to confirm or cancel before continuing.

Source: https://ui.xiod.dev/docs/components/alert-dialog

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  AlertDialog,
  AlertDialogBackdrop,
  AlertDialogClose,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogPopup,
  AlertDialogPortal,
  AlertDialogTitle,
  AlertDialogTrigger,
  AlertDialogViewport,
  AlertDialogCreateHandle
} from "xiod-ui/alert-dialog";
```

Anatomy:

```tsx
<AlertDialog>
  <AlertDialogTrigger />
  <AlertDialogPopup>
    <AlertDialogHeader>
      <AlertDialogTitle />
      <AlertDialogDescription />
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogClose />
    </AlertDialogFooter>
  </AlertDialogPopup>
</AlertDialog>
```

## Example

```tsx
import {
  AlertDialog,
  AlertDialogClose,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogPopup,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "xiod-ui/alert-dialog";
import { Button } from "xiod-ui/button";

export default function AlertDialogExample() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="destructive-outline" />}>
        Delete Account
      </AlertDialogTrigger>
      <AlertDialogPopup>
        <AlertDialogHeader>
          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
          <AlertDialogDescription>
            This action cannot be undone. This will permanently delete your
            account and remove your data from our servers.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogClose render={<Button variant="ghost" />}>
            Cancel
          </AlertDialogClose>
          <AlertDialogClose render={<Button variant="destructive" />}>
            Delete Account
          </AlertDialogClose>
        </AlertDialogFooter>
      </AlertDialogPopup>
    </AlertDialog>
  );
}
```

## API Reference

### AlertDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<DialogRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the alert dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the alert dialog imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog. |
| `handle` | `AlertDialogHandle<Payload>` | – | A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog's open state. Can be created with the AlertDialog.createHandle() method. |
| `onOpenChange` | `((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void)` | – | Event handler called when the alert dialog is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the dialog is opened or closed. |
| `open` | `boolean` | – | Whether the dialog is currently open. |
| `triggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set). |

### AlertDialogBackdrop

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `forceRender` | `boolean` | `false` | Whether the backdrop is forced to render even when nested. |

### AlertDialogClose

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### AlertDialogDescription

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AlertDialogFooter

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "bare"` | `default` | The visual style of the component. |

### AlertDialogHeader

Accepts `render`, plus every native `<div>` attribute.

### AlertDialogPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bottomStickOnMobile` | `boolean` | `true` | Whether the dialog docks to the bottom edge as a full-width sheet on small screens. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |

### AlertDialogPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### AlertDialogTitle

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AlertDialogTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `AlertDialogHandle<unknown>` | – | A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `payload` | `unknown` | – | A payload to pass to the dialog when it is opened. |

### AlertDialogViewport

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### Helpers

`AlertDialogCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Aspect Ratio

> Keeps its content, such as an image or video, at a fixed width-to-height ratio.

Source: https://ui.xiod.dev/docs/components/aspect-ratio

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { AspectRatio } from "xiod-ui/aspect-ratio";
```

## Example

```tsx
import Image from "next/image";
import { AspectRatio } from "xiod-ui/aspect-ratio";
import { Badge } from "xiod-ui/badge";
import { Card } from "xiod-ui/card";

interface AspectRatioExampleItem {
  alt: string;
  cardClassName?: string;
  label: string;
  ratio: number;
  value: string;
}

const aspectRatioExamples: AspectRatioExampleItem[] = [
  {
    alt: "Standard widescreen placeholder",
    label: "Standard Widescreen",
    ratio: 16 / 9,
    value: "16:9",
  },
  {
    alt: "Standard monitor placeholder",
    label: "Standard Monitor",
    ratio: 4 / 3,
    value: "4:3",
  },
  {
    alt: "Square post placeholder",
    label: "Square Post",
    ratio: 1,
    value: "1:1",
  },
  {
    alt: "Mobile portrait placeholder",
    label: "Mobile Portrait",
    ratio: 3 / 4,
    value: "3:4",
  },
  {
    alt: "Cinematic ultrawide placeholder",
    cardClassName: "md:col-span-2",
    label: "Cinematic Ultrawide",
    ratio: 21 / 9,
    value: "21:9",
  },
];

export default function AspectRatioExample() {
  return (
    <div className="grid w-full max-w-5xl grid-cols-1 items-start gap-8 md:grid-cols-2 lg:grid-cols-3">
      {aspectRatioExamples.map((example) => (
        <Card
          key={example.label}
          className={`self-start overflow-hidden border-border bg-card ${example.cardClassName ?? ""}`}
        >
          <AspectRatio
            ratio={example.ratio}
            className="relative overflow-hidden bg-muted"
          >
            <Image
              src="/placeholder.svg"
              alt={example.alt}
              fill
              className="object-cover"
              sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
            />
            <div className="absolute inset-x-0 bottom-0 flex items-end justify-between gap-3 bg-linear-to-t from-black/80 via-black/48 to-transparent px-4 py-3 text-white">
              <span className="max-w-[70%] text-sm font-medium leading-tight">
                {example.label}
              </span>
              <Badge
                variant="outline"
                className="shrink-0 border-white/18 bg-black/35 text-white backdrop-blur-sm"
              >
                {example.value}
              </Badge>
            </div>
          </AspectRatio>
        </Card>
      ))}
    </div>
  );
}
```

## API Reference

### AspectRatio

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `number` | `1` | The width divided by the height, such as `16 / 9`. |

---

# Autocomplete

> A text input that suggests matching options as the user types.

Source: https://ui.xiod.dev/docs/components/autocomplete

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Autocomplete,
  AutocompleteClear,
  AutocompleteCollection,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
  AutocompleteRow,
  AutocompleteSeparator,
  AutocompleteStatus,
  AutocompleteTrigger,
  AutocompleteValue
} from "xiod-ui/autocomplete";
```

Anatomy:

```tsx
<Autocomplete>
  <AutocompleteInput />
  <AutocompletePopup>
    <AutocompleteEmpty />
    <AutocompleteList>
      <AutocompleteItem />
    </AutocompleteList>
  </AutocompletePopup>
</Autocomplete>
```

## Example

```tsx
"use client";

import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "xiod-ui/autocomplete";

const items = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Orange", value: "orange" },
  { label: "Grape", value: "grape" },
  { label: "Strawberry", value: "strawberry" },
  { label: "Mango", value: "mango" },
  { label: "Pineapple", value: "pineapple" },
  { label: "Kiwi", value: "kiwi" },
  { label: "Peach", value: "peach" },
  { label: "Pear", value: "pear" },
];

export default function AutocompleteExample() {
  return (
    <div className="w-full max-w-xs">
      <Autocomplete items={items}>
        <AutocompleteInput
          aria-label="Search items"
          placeholder="Search items…"
        />
        <AutocompletePopup>
          <AutocompleteEmpty>No items found.</AutocompleteEmpty>
          <AutocompleteList>
            {(item) => (
              <AutocompleteItem key={item.value} value={item}>
                {item.label}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompletePopup>
      </Autocomplete>
    </div>
  );
}
```

## API Reference

### Autocomplete

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `Items` | – | The items to be displayed in the list. Can be either a flat array of items or an array of groups with items. Nullish entries are not supported: remove them from the data before passing it. |
| `actionsRef` | `RefObject<AutocompleteRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the autocomplete. Call this after any externally controlled closing animation finishes. |
| `autoHighlight` | `boolean \| "always"` | `false` | Whether the first matching item is highlighted automatically. - `true`: highlight after the user types and keep the highlight while the query changes. - `'always'`: always highlight the first item. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultOpen` | `boolean` | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. |
| `defaultValue` | `string \| number \| readonly string[]` | – | The uncontrolled input value of the autocomplete when it's initially rendered. To render a controlled autocomplete, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `filter` | `AriaCombobox.Props<ItemValue, 'none'>['filter']` | – | Filter function used to match items against the input query. |
| `filteredItems` | `readonly ItemValue[] \| readonly Group<ItemValue>[]` | – | Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook. |
| `form` | `string` | – | Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form. |
| `grid` | `boolean` | `false` | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `id` | `string` | – | The id of the component. |
| `inline` | `boolean` | `false` | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Autocomplete.Root inline open>` |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to the hidden input element. |
| `itemToStringValue` | `((itemValue: Items[number]["items"][number]) => string)` | – | When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
| `keepHighlight` | `boolean` | `false` | Whether the highlighted item should be preserved when the pointer leaves the list. |
| `limit` | `number` | `-1` | The maximum number of items to display in the list. |
| `locale` | `LocalesArgument` | – | The locale to use for string comparison. Defaults to the user's runtime locale. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>. |
| `modal` | `boolean` | `false` | Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. |
| `mode` | `"none" \| "inline" \| "list" \| "both"` | `'list'` | Controls how the autocomplete behaves with respect to list filtering and inline autocompletion. - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item. - `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion). - `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion). - `none`: items are static (not filtered), and the input value will not change based on the active item. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onItemHighlighted` | `((highlightedValue: ItemValue, eventDetails: AutocompleteRootHighlightEventDetails) => void)` | – | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. - `'none'`: the highlight changed programmatically. |
| `onOpenChange` | `((open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void)` | – | Event handler called when the popup is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the popup is opened or closed. |
| `onValueChange` | `((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)` | – | Event handler called when the input value of the autocomplete changes. |
| `open` | `boolean` | – | Whether the popup is currently open. Use when controlled. |
| `openOnInputClick` | `boolean` | `false` | Whether the popup opens when clicking the input. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to choose a different option from the popup. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `submitOnItemClick` | `boolean` | `false` | Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input. |
| `value` | `string \| number \| readonly string[]` | – | The input value of the autocomplete. Use when controlled. |
| `virtualized` | `boolean` | `false` | Whether the items are being externally virtualized. |

### AutocompleteClear

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `keepMounted` | `boolean` | `false` | Whether the component should remain mounted in the DOM when not visible. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### AutocompleteCollection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `(item: any, index: number) => ReactNode` | – | The content of the component. |

### AutocompleteEmpty

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AutocompleteGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly any[]` | – | Items to be rendered within this group. When provided, child `Collection` components will use these items. |

### AutocompleteGroupLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AutocompleteInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `clearProps` | `ComboboxClearProps` | – | Props for the clear button, such as `aria-label` or `className`. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `showClear` | `boolean` | `false` | Whether to show a button at the end of the input that clears it. |
| `showTrigger` | `boolean` | `false` | Whether to show a button at the end of the input that opens the list. |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |
| `startAddon` | `ReactNode` | – | Decorative content, such as an icon, shown at the start of the input. It is hidden from screen readers. |
| `triggerIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `triggerProps` | `AutocompleteTriggerProps` | – | Props for the open button, such as `aria-label` or `className`. |

### AutocompleteItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `index` | `number` | – | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus. |
| `value` | `any` | `null` | A unique value that identifies this item. |

### AutocompleteList

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((item: any, index: number) => ReactNode)` | – | The content of the component. |

### AutocompletePopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Autocomplete$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popup is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popup is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `4` | Distance between the anchor and the popup, in pixels. |

### AutocompleteRow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AutocompleteSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### AutocompleteStatus

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### AutocompleteTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### AutocompleteValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((value: string) => ReactNode)` | – | The content of the component. |

---

# Avatar

> A user's image, with initials or an icon when the image is missing or still loading.

Source: https://ui.xiod.dev/docs/components/avatar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarImage
} from "xiod-ui/avatar";
```

Anatomy:

```tsx
<Avatar>
  <AvatarImage />
  <AvatarFallback />
</Avatar>
<AvatarGroup>
  <Avatar>
    <AvatarImage />
    <AvatarFallback />
  </Avatar>
</AvatarGroup>
```

## Example

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarImage,
} from "xiod-ui/avatar";
import { Badge } from "xiod-ui/badge";

const placeholderSrc = "/placeholder.svg";

export default function AvatarExample() {
  return (
    <div className="flex flex-col gap-12 items-center w-full max-w-4xl">
      {/* Sizes */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Sizes
        </Badge>
        <div className="flex items-end justify-center gap-6">
          <Avatar size="xs">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>XS</AvatarFallback>
          </Avatar>
          <Avatar size="sm">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>MG</AvatarFallback>
          </Avatar>
          <Avatar size="md">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>MD</AvatarFallback>
          </Avatar>
          <Avatar size="lg">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>LG</AvatarFallback>
          </Avatar>
          <Avatar size="xl">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>XL</AvatarFallback>
          </Avatar>
        </div>
      </div>

      {/* Shapes */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Shapes
        </Badge>
        <div className="flex items-center justify-center gap-8">
          <Avatar size="lg" shape="circle">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>CI</AvatarFallback>
          </Avatar>
          <Avatar size="lg" shape="square">
            <AvatarImage src={placeholderSrc} alt="Avatar" />
            <AvatarFallback>SQ</AvatarFallback>
          </Avatar>
        </div>
      </div>

      {/* Grouping */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Avatar Group
        </Badge>
        <div className="flex items-center justify-center gap-8">
          <AvatarGroup>
            <Avatar>
              <AvatarImage src={placeholderSrc} alt="Optimus Prime" />
              <AvatarFallback>OP</AvatarFallback>
            </Avatar>
            <Avatar>
              <AvatarImage src={placeholderSrc} alt="Bumblebee" />
              <AvatarFallback>BB</AvatarFallback>
            </Avatar>
            <Avatar>
              <AvatarImage src={placeholderSrc} alt="Megatron" />
              <AvatarFallback>MG</AvatarFallback>
            </Avatar>
            <Avatar className="bg-popover border border-border text-muted-foreground">
              <AvatarFallback>+3</AvatarFallback>
            </Avatar>
          </AvatarGroup>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Avatar

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `"circle" \| "square"` | `circle` | The avatar's shape: a circle or a square with rounded corners. |
| `size` | `"sm" \| "md" \| "lg" \| "xs" \| "xl" \| "2xl"` | `md` | The size of the component. |

### AvatarFallback

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `0` | How long to wait before showing the fallback. Specified in milliseconds. |

### AvatarGroup

Accepts `render`, plus every native attribute of the element it renders.

### AvatarImage

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | Whether the image element stays mounted and loads in place instead of being preloaded. Supports `loading="lazy"` and optimized image components such as `next/image`. |
| `onLoadingStatusChange` | `((status: ImageLoadingStatus) => void)` | – | Callback fired when the loading status changes. |

---

# Badge

> A small label for a status, count or category.

Source: https://ui.xiod.dev/docs/components/badge

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Badge } from "xiod-ui/badge";
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";

export default function BadgeExample() {
  return <Badge size="lg">Badge</Badge>;
}
```

## API Reference

### Badge

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `variant` | `"error" \| "default" \| "success" \| "warning" \| "info" \| "secondary" \| "outline" \| "destructive"` | `default` | The visual style of the component. |

---

# Breadcrumb

> Shows where the current page sits in the site's hierarchy, as a trail of links.

Source: https://ui.xiod.dev/docs/components/breadcrumb

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator
} from "xiod-ui/breadcrumb";
```

Anatomy:

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
  </BreadcrumbList>
</Breadcrumb>
```

## Example

```tsx
import Link from "next/link";
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "xiod-ui/breadcrumb";
import { Button } from "xiod-ui/button";
import { Menu, MenuItem, MenuPopup, MenuTrigger } from "xiod-ui/menu";

export default function BreadcrumbExample() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <Menu>
            <MenuTrigger
              render={
                <Button
                  className="-m-1.5 text-muted-foreground"
                  size="icon-sm"
                  variant="ghost"
                />
              }
            >
              <BreadcrumbEllipsis />
            </MenuTrigger>
            <MenuPopup align="start">
              <MenuItem render={<Link href="/docs" />}>Docs</MenuItem>
            </MenuPopup>
          </Menu>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/docs" />}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}
```

## API Reference

### Breadcrumb

Accepts `render`, plus every native `<nav>` attribute.

### BreadcrumbEllipsis

Accepts `render`, plus every native `<span>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### BreadcrumbItem

Accepts `render`, plus every native `<li>` attribute.

### BreadcrumbLink

Accepts `render`, plus every native `<a>` attribute.

### BreadcrumbList

Accepts `render`, plus every native `<ol>` attribute.

### BreadcrumbPage

Accepts `render`, plus every native `<span>` attribute.

### BreadcrumbSeparator

Accepts `render`, plus every native `<li>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

---

# Button

> A button, or a link styled as one, in several variants and sizes.

Source: https://ui.xiod.dev/docs/components/button

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Button } from "xiod-ui/button";
```

## Example

```tsx
import { Button } from "xiod-ui/button";

export default function ButtonExample() {
  return <Button variant="outline">Button</Button>;
}
```

## API Reference

### Button

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `default` | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `default` | The visual style of the component. |

---

# Button Group

> Joins buttons into one row with shared borders.

Source: https://ui.xiod.dev/docs/components/button-group

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "xiod-ui/button-group";
```

Anatomy:

```tsx
<ButtonGroup>
  <ButtonGroupSeparator />
</ButtonGroup>
```

## Example

```tsx
import {
  TextAlignCenter as AlignCenter,
  AlignLeft,
  AlignRight,
  Bold,
  TextItalic as Italic,
  TextUnderline as Underline,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "xiod-ui/button-group";

export default function ButtonGroupExample() {
  return (
    <div className="flex flex-col items-center gap-6">
      {/* Basic Text Formatting Group (Standard Outline) */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
          Standard Outline
        </span>
        <ButtonGroup>
          <Button variant="outline" size="icon" aria-label="Format Bold">
            <Bold className="size-4" />
          </Button>
          <Button variant="outline" size="icon" aria-label="Format Italic">
            <Italic className="size-4" />
          </Button>
          <Button variant="outline" size="icon" aria-label="Format Underline">
            <Underline className="size-4" />
          </Button>
        </ButtonGroup>
      </div>

      {/* Alignment Group (Mixed Sizes/Icons) */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
          With Separators
        </span>
        <ButtonGroup>
          <Button variant="outline" size="icon" aria-label="Align Left">
            <AlignLeft className="size-4" />
          </Button>
          <ButtonGroupSeparator />
          <Button variant="outline" size="icon" aria-label="Align Center">
            <AlignCenter className="size-4" />
          </Button>
          <ButtonGroupSeparator />
          <Button variant="outline" size="icon" aria-label="Align Right">
            <AlignRight className="size-4" />
          </Button>
        </ButtonGroup>
      </div>

      {/* Segmented Control / Text Button Group */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
          Segmented Controls
        </span>
        <ButtonGroup>
          <Button variant="outline">Today</Button>
          <Button variant="outline">Weekly</Button>
          <Button variant="outline">Monthly</Button>
        </ButtonGroup>
      </div>

      {/* Group with Text Prefix & Actions */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
          Text Prefixes & Solid Actions
        </span>
        <ButtonGroup>
          <ButtonGroupText>Status</ButtonGroupText>
          <Button variant="outline">Active</Button>
          <Button variant="default">All Profiles</Button>
        </ButtonGroup>
      </div>

      {/* Vertical Button Group */}
      <div className="flex flex-col items-center gap-2">
        <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
          Vertical Layout
        </span>
        <ButtonGroup orientation="vertical">
          <Button variant="outline" className="justify-start">
            Profile Settings
          </Button>
          <Button variant="outline" className="justify-start">
            Account Preferences
          </Button>
          <Button variant="outline" className="justify-start">
            Security & Login
          </Button>
        </ButtonGroup>
      </div>
    </div>
  );
}
```

## API Reference

### ButtonGroup

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Whether the items are laid out horizontally or vertically. |

### ButtonGroupSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### ButtonGroupText

Accepts `render`, plus every native `<div>` attribute.

---

# Button Split

> A button with a main action and an attached menu of related actions.

Source: https://ui.xiod.dev/docs/components/button-split

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  ButtonSplit,
  ButtonSplitAction,
  ButtonSplitContent,
  ButtonSplitSeparator,
  ButtonSplitTrigger
} from "xiod-ui/button-split";
```

Anatomy:

```tsx
<ButtonSplit>
  <ButtonSplitAction />
  <ButtonSplitSeparator />
  <ButtonSplitTrigger />
  <ButtonSplitContent />
</ButtonSplit>
```

## Example

```tsx
"use client";

import {
  ButtonSplit,
  ButtonSplitAction,
  ButtonSplitContent,
  ButtonSplitSeparator,
  ButtonSplitTrigger,
} from "xiod-ui/button-split";

export default function ButtonSplitExample() {
  return (
    <div className="flex flex-col items-center justify-center gap-6 p-6 sm:p-12">
      <ButtonSplit variant="outline">
        <ButtonSplitAction>Primary Action</ButtonSplitAction>
        <ButtonSplitSeparator />
        <ButtonSplitTrigger />
        <ButtonSplitContent align="end">
          <div className="text-sm px-2 py-1.5 hover:bg-accent rounded-sm cursor-pointer transition-colors">
            Action 1
          </div>
          <div className="text-sm px-2 py-1.5 hover:bg-accent rounded-sm cursor-pointer transition-colors">
            Action 2
          </div>
          <div className="text-sm px-2 py-1.5 hover:bg-accent rounded-sm cursor-pointer transition-colors text-destructive">
            Delete Profile
          </div>
        </ButtonSplitContent>
      </ButtonSplit>
    </div>
  );
}
```

## API Reference

### ButtonSplit

Accepts `className`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The content of the component. |
| `actionsRef` | `RefObject<PopoverRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - `close`: Closes the popover imperatively when called. |
| `defaultOpen` | `boolean` | `false` | Whether the popover is initially open. To render a controlled popover, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover. |
| `handle` | `PopoverHandle<unknown>` | – | A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state. |
| `modal` | `boolean \| "trap-focus"` | `false` | Determines if the popover enters a modal state when open. - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch screen readers can escape the popup. |
| `onOpenChange` | `((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)` | – | Event handler called when the popover is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the popover is opened or closed. |
| `open` | `boolean` | – | Whether the popover is currently open. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `default` | The size of the component. |
| `triggerId` | `string \| null` | – | ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set). |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `default` | The visual style of the component. |

### ButtonSplitAction

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | – | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | – | The visual style of the component. |

### ButtonSplitContent

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | – | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Popover$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `collisionAvoidance` | `CollisionAvoidance` | – | How the popup avoids collisions with the edges of the viewport. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popover is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | – | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `8` | Distance between the anchor and the popup, in pixels. |
| `tooltipStyle` | `boolean` | – | Whether the popup uses the compact look of a tooltip: smaller text, tighter padding and a width that fits the content. |

### ButtonSplitSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### ButtonSplitTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `300` | How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `handle` | `PopoverHandle<unknown>` | – | A handle to associate the trigger with a popover. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`). |
| `openOnHover` | `boolean` | `false` | Whether the popover should also open when the trigger is hovered. |
| `payload` | `unknown` | – | A payload to pass to the popover when it is opened. |

---

# Calendar

> A month grid for picking a single date or a range.

Source: https://ui.xiod.dev/docs/components/calendar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Calendar } from "xiod-ui/calendar";
```

## Example

```tsx
"use client";

import * as React from "react";
import { Calendar, type DateRange } from "xiod-ui/calendar";

export default function CalendarExample() {
  const [singleDate, setSingleDate] = React.useState<Date | null>(
    () => new Date(),
  );

  const [dateRange, setDateRange] = React.useState<DateRange>(() => {
    const today = new Date();
    const future = new Date();
    future.setDate(today.getDate() + 5);
    return {
      from: today,
      to: future,
    };
  });

  return (
    <div className="flex flex-col items-center justify-center gap-8 py-4 w-full">
      <div className="flex flex-col lg:flex-row items-center lg:items-start justify-center gap-8 w-full">
        {/* Single Mode Card */}
        <div className="flex flex-col items-center gap-3">
          <h3 className="text-sm font-semibold text-muted-foreground">
            Single Select
          </h3>
          <Calendar
            mode="single"
            selected={singleDate}
            onSelect={(date) => {
              if (date instanceof Date) {
                setSingleDate(date);
              }
            }}
          />
        </div>

        {/* Range Mode Card (Double Month) */}
        <div className="flex flex-col items-center gap-3">
          <h3 className="text-sm font-semibold text-muted-foreground">
            Range Select (2 Months)
          </h3>
          <Calendar
            mode="range"
            numberOfMonths={2}
            selected={dateRange}
            onSelect={(val) => {
              if (
                val &&
                typeof val === "object" &&
                ("from" in val || "to" in val)
              ) {
                setDateRange(val as DateRange);
              }
            }}
          />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Calendar

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `classNames` | `CalendarClassNames` | – | Classes for the calendar's parts, keyed by part name. |
| `disabled` | `Matcher \| Matcher[]` | – | Days that can't be selected: `true` for all, a date, a list of dates, a function that returns `true` for a date, `{ before }` and `{ after }` limits, or `{ dayOfWeek }` with 0 for Sunday. Pass an array to combine them. |
| `disableOutsideDays` | `boolean` | `false` | Whether days from the previous and next months can't be selected. |
| `fixedWeeks` | `boolean` | `true` | Whether every month shows six weeks, so the calendar's height doesn't change between months. |
| `localeMonths` | `string[]` | – | Full month names, starting from January. Defaults to English. |
| `localeMonthsShort` | `string[]` | – | Short month names, starting from January, for the month picker and the selection summary. Defaults to English. |
| `localeWeekdays` | `string[]` | – | Short weekday names for the column headings, starting from Sunday. Defaults to English. |
| `localeWeekdaysLong` | `string[]` | – | Full weekday names for screen readers, starting from Sunday. Defaults to English. |
| `maxDate` | `Date` | – | The latest date that can be selected. The calendar can't navigate past its month. |
| `minDate` | `Date` | – | The earliest date that can be selected. The calendar can't navigate before its month. |
| `mode` | `"single" \| "range"` | `single` | Whether the user picks one date (`single`) or a start and end date (`range`). |
| `modifiers` | `Record<string, Matcher \| Matcher[]>` | – | Named groups of days, each matched the same ways as `disabled`. Style them with `modifiersClassNames`. |
| `modifiersClassNames` | `Record<string, string>` | – | Classes for the days in each group named in `modifiers`, keyed by the group's name. |
| `nextIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `numberOfMonths` | `number` | `1` | How many months to show side by side. |
| `onSelect` | `((date: Date \| DateRange) => void)` | – | Called with the new date, or the new `{ from, to }` range in `range` mode, when the user picks a day. |
| `prevIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `selected` | `Date \| DateRange \| null` | – | The selected date, or `{ from, to }` in `range` mode. The calendar is controlled: update it from `onSelect`. |
| `showOutsideDays` | `boolean` | `true` | Whether to show the days of the previous and next months that fill the first and last weeks. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` | The first day of the week, from 0 for Sunday to 6 for Saturday. |

---

# Card

> A bordered panel with a header, body and footer.

Source: https://ui.xiod.dev/docs/components/card

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Card,
  CardAction,
  CardDescription,
  CardFooter,
  CardFrame,
  CardFrameDescription,
  CardFrameFooter,
  CardFrameHeader,
  CardFrameTitle,
  CardHeader,
  CardPanel,
  CardTitle
} from "xiod-ui/card";
```

Anatomy:

```tsx
<Card>
  <CardHeader>
    <CardTitle />
    <CardDescription />
  </CardHeader>
  <CardPanel />
  <CardFooter />
</Card>
```

## Example

```tsx
import { AlertCircle as CircleAlertIcon } from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Card,
  CardDescription,
  CardFooter,
  CardHeader,
  CardPanel,
  CardTitle,
} from "xiod-ui/card";
import { Field, FieldLabel } from "xiod-ui/field";
import { Form } from "xiod-ui/form";
import { Input } from "xiod-ui/input";
import {
  Select,
  SelectItem,
  SelectPopup,
  SelectTrigger,
  SelectValue,
} from "xiod-ui/select";

const frameworkOptions = [
  { label: "Next.js", value: "next" },
  { label: "Vite", value: "vite" },
  { label: "Remix", value: "remix" },
  { label: "Astro", value: "astro" },
];

export default function CardExample() {
  return (
    <Card className="w-full max-w-xs">
      <CardHeader>
        <CardTitle>Create project</CardTitle>
        <CardDescription>Deploy your new project in one-click.</CardDescription>
      </CardHeader>
      <CardPanel>
        <Form>
          <Field>
            <FieldLabel>Name</FieldLabel>
            <Input placeholder="Name of your project" type="text" />
          </Field>
          <Field>
            <FieldLabel>Framework</FieldLabel>
            <Select defaultValue="next" items={frameworkOptions}>
              <SelectTrigger>
                <SelectValue />
              </SelectTrigger>
              <SelectPopup>
                {frameworkOptions.map(({ label, value }) => (
                  <SelectItem key={value} value={value}>
                    {label}
                  </SelectItem>
                ))}
              </SelectPopup>
            </Select>
          </Field>
          <Button className="w-full" type="submit">
            Deploy
          </Button>
        </Form>
      </CardPanel>
      <CardFooter>
        <div className="flex gap-1 text-muted-foreground text-xs">
          <CircleAlertIcon className="size-3 h-lh shrink-0" />
          <p>This will take a few seconds to complete.</p>
        </div>
      </CardFooter>
    </Card>
  );
}
```

## API Reference

### Card

Accepts `render`, plus every native `<div>` attribute.

### CardAction

Accepts `render`, plus every native `<div>` attribute.

### CardDescription

Accepts `render`, plus every native `<div>` attribute.

### CardFooter

Accepts `render`, plus every native `<div>` attribute.

### CardFrame

Accepts `render`, plus every native `<div>` attribute.

### CardFrameDescription

Accepts `render`, plus every native `<div>` attribute.

### CardFrameFooter

Accepts `render`, plus every native `<div>` attribute.

### CardFrameHeader

Accepts `render`, plus every native `<div>` attribute.

### CardFrameTitle

Accepts `render`, plus every native `<div>` attribute.

### CardHeader

Accepts `render`, plus every native `<div>` attribute.

### CardPanel

Accepts `render`, plus every native `<div>` attribute.

### CardTitle

Accepts `render`, plus every native `<div>` attribute.

---

# Carousel

> A horizontal or vertical slideshow that scrolls with snapping, drag, arrow buttons and the keyboard.

Source: https://ui.xiod.dev/docs/components/carousel

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
  CarouselDots
} from "xiod-ui/carousel";
```

Anatomy:

```tsx
<Carousel>
  <CarouselContent>
    <CarouselItem />
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

## Example

```tsx
"use client";

import { Card, CardPanel } from "xiod-ui/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "xiod-ui/carousel";

export default function CarouselExample() {
  return (
    <Carousel className="w-full max-w-48 sm:max-w-xs">
      <CarouselContent>
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index}>
            <div className="p-1">
              <Card>
                <CardPanel className="flex aspect-square items-center justify-center p-6">
                  <span className="text-4xl font-semibold">{index + 1}</span>
                </CardPanel>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

## API Reference

### Carousel

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | Whether the carousel advances on its own. It pauses while hovered or focused, while the tab is hidden, and when the user prefers reduced motion. |
| `autoplayInterval` | `number` | `5000` | The time between slides when `autoplay` is on, in milliseconds. |
| `loop` | `boolean` | `true` | Whether going past the last slide returns to the first, and back from the first to the last. |
| `opts` | `CarouselOptions` | – | Options for the scrolling behaviour, such as `align`, `dragFree` or `speed`. `loop` set here takes precedence over the `loop` prop. |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Whether the items are laid out horizontally or vertically. |
| `plugins` | `CarouselPlugin[]` | – | Plugins to run with the carousel. Each plugin's `init` receives the carousel API once it is ready. |

### CarouselContent

Accepts `render`, plus every native `<div>` attribute.

### CarouselItem

Accepts `render`, plus every native `<div>` attribute.

### CarouselPrevious

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `icon-sm` | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `outline` | The visual style of the component. |

### CarouselNext

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `icon-sm` | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `outline` | The visual style of the component. |

### CarouselDots

Accepts `render`, plus every native `<div>` attribute.

---

# Checkbox

> A box the user can check or uncheck, with an indeterminate state.

Source: https://ui.xiod.dev/docs/components/checkbox

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Checkbox, CheckboxGroup } from "xiod-ui/checkbox";
```

## Example

```tsx
import { Checkbox } from "xiod-ui/checkbox";
import { Label } from "xiod-ui/label";

const checkboxVariants = [
  {
    title: "Default",
    value: "default",
  },
  {
    title: "Sharp",
    value: "sharp",
  },
  {
    title: "Diamond",
    value: "diamond",
  },
  {
    title: "Expressive",
    value: "expressive",
  },
] as const;

export default function CheckboxExample() {
  return (
    <div className="flex w-full flex-wrap items-start justify-center gap-12">
      {checkboxVariants.map(({ title, value }) => (
        <div className="flex flex-col gap-4" key={value}>
          <span className="text-sm font-medium text-muted-foreground">
            {title}
          </span>
          <div className="flex flex-col gap-3">
            <Label>
              <Checkbox variant={value} defaultChecked /> Checked
            </Label>
            <Label>
              <Checkbox variant={value} /> Unchecked
            </Label>
            <Label>
              <Checkbox
                variant={value}
                defaultChecked={"indeterminate" as unknown as boolean}
              />{" "}
              Indeterminate
            </Label>
          </div>
        </div>
      ))}
    </div>
  );
}
```

## API Reference

### Checkbox

Also exported as `CheckboxGroupItem`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | `undefined` | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
| `defaultChecked` | `boolean` | `false` | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
| `id` | `string` | – | The id of the input element. |
| `indeterminate` | `boolean` | `false` | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden `<input>` element. |
| `name` | `string` | `undefined` | Identifies the field when a form is submitted. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void)` | – | Event handler called when the checkbox is ticked or unticked. |
| `parent` | `boolean` | `false` | Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group). |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to tick or untick the checkbox. |
| `required` | `boolean` | `false` | Whether the user must tick the checkbox before submitting a form. |
| `uncheckedValue` | `string` | – | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |
| `value` | `string` | – | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
| `variant` | `"default" \| "diamond" \| "expressive" \| "sharp"` | `default` | The visual style of the component. |

### CheckboxGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allValues` | `string[]` | – | Names of all checkboxes in the group. Use this when creating a parent checkbox. |
| `defaultValue` | `string[]` | – | Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onValueChange` | `((value: string[], eventDetails: CheckboxGroupChangeEventDetails) => void)` | – | Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument. |
| `value` | `string[]` | – | Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead. |

---

# Circular Progress

> A ring that shows progress toward completion, or spins while the duration is unknown.

Source: https://ui.xiod.dev/docs/components/circular-progress

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { CircularProgress } from "xiod-ui/circular-progress";
```

## Example

```tsx
"use client";

import { useEffect, useState } from "react";
import { CircularProgress } from "xiod-ui/circular-progress";

export default function CircularProgressExample() {
  const [value, setValue] = useState(20);

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((current) =>
        Math.min(100, Math.round(current + Math.random() * 25)),
      );
    }, 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div className="flex flex-col items-center gap-12 p-8 overflow-x-auto">
      <div className="flex items-center gap-8">
        {(["sm", "default", "lg", "xl", "2xl"] as const).map((s) => (
          <CircularProgress key={s} size={s} value={value} />
        ))}
      </div>
      <div className="flex items-center gap-8">
        {(["sm", "default", "lg", "xl", "2xl"] as const).map((s) => (
          <CircularProgress
            key={s}
            size={s}
            variant="expressive"
            value={value}
          />
        ))}
      </div>
    </div>
  );
}
```

## API Reference

### CircularProgress

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `100` | The maximum progress value. Defaults to 100. |
| `size` | `number \| "sm" \| "lg" \| "default" \| "xl" \| "2xl"` | `default` | The size of the circular progress indicator. Can be a string identifier ("sm" to "2xl") or explicit pixel dimensions. |
| `strokeWidth` | `number` | – | The stroke width of the SVG circle. |
| `value` | `number \| null` | – | The progress value (0 to max). If undefined, the indicator will be indeterminate. |
| `variant` | `"default" \| "expressive"` | `default` | Defines standard rendering or wavy geometries wrapping the progress stroke. |

---

# Collapsible

> A panel that opens and closes from a trigger.

Source: https://ui.xiod.dev/docs/components/collapsible

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "xiod-ui/collapsible";
```

Anatomy:

```tsx
<Collapsible>
  <CollapsibleTrigger />
  <CollapsiblePanel />
</Collapsible>
```

## Example

```tsx
import { ChevronDown as ChevronDownIcon } from "xiod-icons";
import {
  Collapsible,
  CollapsiblePanel,
  CollapsibleTrigger,
} from "xiod-ui/collapsible";

export default function CollapsibleExample() {
  return (
    <Collapsible>
      <CollapsibleTrigger className="inline-flex items-center gap-2 font-medium text-sm data-panel-open:[&_svg]:rotate-180">
        Show recovery keys
        <ChevronDownIcon className="size-4" />
      </CollapsibleTrigger>
      <CollapsiblePanel>
        <ul className="flex flex-col gap-1 py-2 text-muted-foreground text-sm">
          <li className="rounded-sm bg-muted px-2 py-1 font-mono">
            4829-1735-6621
          </li>
          <li className="rounded-sm bg-muted px-2 py-1 font-mono">
            9182-6407-5532
          </li>
          <li className="rounded-sm bg-muted px-2 py-1 font-mono">
            3051-7924-9018
          </li>
        </ul>
      </CollapsiblePanel>
    </Collapsible>
  );
}
```

## API Reference

### Collapsible

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` | Whether the collapsible panel is initially open. To render a controlled collapsible, use the `open` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onOpenChange` | `((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)` | – | Event handler called when the panel is opened or closed. |
| `open` | `boolean` | – | Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the `defaultOpen` prop instead. |

### CollapsiblePanel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hiddenUntilFound` | `boolean` | `false` | Allows the browser's built-in page search to find and expand the panel contents. Overrides the `keepMounted` prop and uses `hidden="until-found"` to hide the element without removing it from the DOM. |
| `keepMounted` | `boolean` | `false` | Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when `hiddenUntilFound` is used. |

### CollapsibleTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

---

# Color Picker

> A radial colour picker with hue, saturation and alpha controls.

Source: https://ui.xiod.dev/docs/components/color-picker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { BlossomColorPicker, ColorPicker } from "xiod-ui/color-picker";
```

## Example

```tsx
"use client";

import { Badge } from "xiod-ui/badge";
import { BlossomColorPicker } from "xiod-ui/color-picker";

// Any list of colors works — the picker sorts them into concentric layers by
// lightness and hue itself, so they do not need to arrive in ring order.
const brandColors = [
  "#C92A2A",
  "#A61E4D",
  "#862E9C",
  "#364FC7",
  "#0B7285",
  "#2B8A3E",
  "#FF6B6B",
  "#F06595",
  "#CC5DE8",
  "#5C7CFA",
  "#22B8CF",
  "#51CF66",
  "#FFA8A8",
  "#FCC2D7",
  "#E599F7",
  "#91A7FF",
  "#66D9E8",
  "#8CE99A",
];

export default function ColorPickerExample() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-12">
      {/* Blossom */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Blossom
        </Badge>
        {/* Collapsed until the core is clicked, so the petals need room to
            bloom into rather than a box sized to the resting state. */}
        <div className="flex h-56 w-full items-center justify-center">
          <BlossomColorPicker
            defaultValue={{
              hue: 327,
              saturation: 75,
              alpha: 100,
              layer: "outer",
            }}
            adaptivePositioning={false}
          />
        </div>
      </div>

      {/* Custom colors */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Custom colors
        </Badge>
        <div className="flex h-64 w-full items-center justify-center">
          <BlossomColorPicker
            colors={brandColors}
            initialExpanded
            collapsible={false}
            petalSize={28}
            adaptivePositioning={false}
          />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### BlossomColorPicker

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `adaptivePositioning` | `boolean` | `true` | Whether the open picker shifts to stay inside the window, and places its sliders where there is room when `sliderPosition` is unset. |
| `animationDuration` | `number` | `300` | How long the petals take to open and close, in milliseconds. |
| `circularBarWidth` | `number` | `12` | The thickness of the ring that shows the selected colour around the petals, in pixels. |
| `collapsible` | `boolean` | `true` | Whether the picker closes to its centre button. When `false`, it stays open. |
| `colors` | `ColorInput[]` | – | The petal colours, as hex, `rgb()` or `hsl()` strings or `{ h, s, l }` objects. Up to 10 sit in one ring; more are split into rings by lightness. |
| `coreSize` | `number` | `32` | The diameter of the centre button, in pixels. |
| `defaultValue` | `BlossomColorPickerValue` | – | The colour selected at first, when it isn't controlled. |
| `disabled` | `boolean` | `false` | Whether the picker ignores input. |
| `initialExpanded` | `boolean` | `false` | Whether the picker starts open. |
| `onChange` | `((color: BlossomColorPickerColor) => void)` | – | Called with the new colour, in every format, whenever it changes. |
| `onCollapse` | `((color: BlossomColorPickerColor) => void)` | – | Called with the selected colour when the picker closes. |
| `openOnHover` | `boolean` | `false` | Whether hovering the picker opens it, as well as clicking. Only applies when `collapsible`. |
| `petalSize` | `number` | `32` | The diameter of each petal, in pixels. |
| `showAlphaSlider` | `boolean` | `true` | Whether to show the Lightness arc slider beside the petals while open. |
| `showCoreColor` | `boolean` | `true` | Whether the centre shows the selected colour while open. When `false`, it turns white while open. |
| `showOpacitySlider` | `boolean` | `true` | Whether to show the Opacity arc slider, on the side opposite the Lightness slider, while open. |
| `sliderOffset` | `number` | `30` | The distance between the colour ring and the arc sliders, in pixels. |
| `sliderPosition` | `"top" \| "bottom" \| "left" \| "right"` | – | The side the Lightness slider sits on. The Opacity slider takes the opposite side. When unset, the picker picks the side with the most room. |
| `sliderWidth` | `number` | `12` | The thickness of the arc sliders, in pixels. |
| `value` | `BlossomColorPickerValue` | – | The selected colour. Use with `onChange` to control it. |

### ColorPicker

Accepts `className`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `adaptivePositioning` | `boolean` | `true` | Whether the open picker shifts to stay inside the window, and places its sliders where there is room when `sliderPosition` is unset. |
| `animationDuration` | `number` | `300` | How long the petals take to open and close, in milliseconds. |
| `circularBarWidth` | `number` | `12` | The thickness of the ring that shows the selected colour around the petals, in pixels. |
| `collapsible` | `boolean` | `false` | Whether the picker closes to its centre button. When `false`, it stays open. |
| `colors` | `ColorInput[]` | – | The petal colours, as hex, `rgb()` or `hsl()` strings or `{ h, s, l }` objects. Up to 10 sit in one ring; more are split into rings by lightness. |
| `coreSize` | `number` | `36` | The diameter of the centre button, in pixels. |
| `darkMode` | `boolean` | – | Whether the panel always uses dark colours, whatever the page's theme. |
| `defaultValue` | `BlossomColorPickerValue` | – | The colour selected at first, when it isn't controlled. |
| `disabled` | `boolean` | `false` | Whether the picker ignores input. |
| `initialExpanded` | `boolean` | `true` | Whether the picker starts open. |
| `onChange` | `((color: BlossomColorPickerColor) => void)` | – | Called with the new colour, in every format, whenever it changes. |
| `onCollapse` | `((color: BlossomColorPickerColor) => void)` | – | Called with the selected colour when the picker closes. |
| `openOnHover` | `boolean` | `false` | Whether hovering the picker opens it, as well as clicking. Only applies when `collapsible`. |
| `petalSize` | `number` | `32` | The diameter of each petal, in pixels. |
| `showAlphaSlider` | `boolean` | `true` | Whether to show the Lightness arc slider beside the petals while open. |
| `showCoreColor` | `boolean` | `true` | Whether the centre shows the selected colour while open. When `false`, it turns white while open. |
| `sliderOffset` | `number` | `30` | The distance between the colour ring and the arc sliders, in pixels. |
| `sliderPosition` | `"top" \| "bottom" \| "left" \| "right"` | – | The side the Lightness slider sits on. The Opacity slider takes the opposite side. When unset, the picker picks the side with the most room. |
| `sliderWidth` | `number` | `12` | The thickness of the arc sliders, in pixels. |
| `triggerIcon` | `ReactNode` | – | Replaces the icon on the colour format switch. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `value` | `BlossomColorPickerValue` | – | The selected colour. Use with `onChange` to control it. |

---

# Combobox

> An input with a filterable list of options to choose one or several from.

Source: https://ui.xiod.dev/docs/components/combobox

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxClear,
  ComboboxCollection,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxRow,
  ComboboxSeparator,
  ComboboxStatus,
  ComboboxTrigger,
  ComboboxValue
} from "xiod-ui/combobox";
```

Anatomy:

```tsx
<Combobox>
  <ComboboxInput />
  <ComboboxPopup>
    <ComboboxEmpty />
    <ComboboxList>
      <ComboboxItem />
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

## Example

```tsx
"use client";

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "xiod-ui/combobox";

const items = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Orange", value: "orange" },
  { label: "Grape", value: "grape" },
  { label: "Strawberry", value: "strawberry" },
  { label: "Mango", value: "mango" },
  { label: "Pineapple", value: "pineapple" },
  { label: "Kiwi", value: "kiwi" },
  { label: "Peach", value: "peach" },
  { label: "Pear", value: "pear" },
];

export default function ComboboxExample() {
  return (
    <div className="">
      <Combobox items={items}>
        <ComboboxInput
          aria-label="Select a item"
          placeholder="Select a item…"
        />
        <ComboboxPopup>
          <ComboboxEmpty>No items found.</ComboboxEmpty>
          <ComboboxList>
            {(item) => (
              <ComboboxItem key={item.value} value={item}>
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  );
}
```

## API Reference

### Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<Actions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the combobox. Call this after any externally controlled closing animation finishes. |
| `autoComplete` | `string` | – | Provides a hint to the browser for autofill. |
| `autoHighlight` | `boolean` | `false` | Whether the first matching item is highlighted automatically while filtering. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultInputValue` | `string \| number \| readonly string[]` | – | The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead. |
| `defaultOpen` | `boolean` | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. |
| `defaultValue` | `ComboboxValueType<Value, Multiple> \| null` | – | The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `filter` | `((item: Item, query: string, itemToString?: ((item: Item) => string)) => boolean) \| null` | – | Filter function used to match items vs input query. Receives the source item, which is the derived value's item when `items` is a `createItems()` collection, and the item itself otherwise. |
| `filteredItems` | `readonly Item[] \| readonly Group<Item>[]` | – | Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. With a `createItems()` collection, pass source items rather than derived values. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook. |
| `form` | `string` | – | Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form. |
| `grid` | `boolean` | `false` | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `id` | `string` | – | The id of the component. |
| `inline` | `boolean` | `false` | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root` composition, bind the Combobox's `open` and `onOpenChange` props to the `Dialog`'s `open` and `onOpenChange` state instead so the component resets its transient state (filter query, highlighted item, and input value) when the dialog closes. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to the hidden input element. |
| `inputValue` | `string \| number \| readonly string[]` | – | The input value of the combobox. Use when controlled. |
| `isItemEqualToValue` | `((itemValue: Value, value: Value) => boolean)` | – | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. With a `createItems()` collection, both arguments are derived values. Defaults to `Object.is` comparison. |
| `items` | `readonly any[] \| readonly Group<any>[] \| ComboboxItemCollection<Item, Value>` | – | The items to be displayed in the list. Can be a flat array of items, an array of groups with items, or a collection created by the `createItems()` function, which derives each item's selection value and label. Nullish entries are not supported: remove them from the data before passing it. |
| `itemToStringLabel` | `((itemValue: Value) => string)` | – | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value, and the collection's `getLabel` takes precedence for values it can resolve. |
| `itemToStringValue` | `((itemValue: Value) => string)` | – | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value. |
| `limit` | `number` | `-1` | The maximum number of items to display in the list. |
| `locale` | `LocalesArgument` | – | The locale to use for string comparison. Defaults to the user's runtime locale. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>. |
| `modal` | `boolean` | `false` | Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. |
| `multiple` | `Multiple` | `false` | Whether multiple items can be selected. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onInputValueChange` | `((inputValue: string, eventDetails: ChangeEventDetails) => void)` | – | Event handler called when the input value changes. |
| `onItemHighlighted` | `((highlightedValue: Value, eventDetails: HighlightEventDetails) => void)` | – | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. - `'none'`: the highlight changed programmatically. |
| `onOpenChange` | `((open: boolean, eventDetails: ChangeEventDetails) => void)` | – | Event handler called when the popup is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the popup is opened or closed. |
| `onValueChange` | `((value: ComboboxValueType<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void)` | – | Event handler called when the selected value of the combobox changes. |
| `open` | `boolean` | – | Whether the popup is currently open. Use when controlled. |
| `openOnInputClick` | `boolean` | `true` | Whether the popup opens when clicking the input. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to choose a different option from the popup. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `value` | `ComboboxValueType<Value, Multiple> \| null` | – | The selected value of the combobox. Use when controlled. |
| `virtualized` | `boolean` | `false` | Whether the items are being externally virtualized. |

### ComboboxChip

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `removeProps` | `ComboboxChipRemoveProps` | – | Props for the chip's remove button, such as `aria-label` or `className`. |

### ComboboxChips

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `startAddon` | `ReactNode` | – | Decorative content, such as an icon, shown at the start of the chips. It is hidden from screen readers. |

### ComboboxChipsInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |

### ComboboxClear

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `keepMounted` | `boolean` | `false` | Whether the component should remain mounted in the DOM when not visible. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### ComboboxCollection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `(item: any, index: number) => ReactNode` | – | The content of the component. |

### ComboboxEmpty

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ComboboxGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly any[]` | – | Items to be rendered within this group. When provided, child `Collection` components will use these items. |

### ComboboxGroupLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ComboboxInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `clearProps` | `ComboboxClearProps` | – | Props for the clear button, such as `aria-label` or `className`. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `showClear` | `boolean` | `false` | Whether to show a button at the end of the input that clears it. |
| `showTrigger` | `boolean` | `true` | Whether to show a button at the end of the input that opens the list. |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |
| `startAddon` | `ReactNode` | – | Decorative content, such as an icon, shown at the start of the input. It is hidden from screen readers. |
| `triggerIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `triggerProps` | `ComboboxTriggerProps` | – | Props for the open button, such as `aria-label` or `className`. |

### ComboboxItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `index` | `number` | – | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus. |
| `value` | `any` | `null` | A unique value that identifies this item. |

### ComboboxList

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((item: any, index: number) => ReactNode)` | – | The content of the component. |

### ComboboxPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Combobox$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popup is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popup is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `4` | Distance between the anchor and the popup, in pixels. |

### ComboboxRow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ComboboxSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### ComboboxStatus

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ComboboxTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### ComboboxValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((selectedValue: any) => ReactNode)` | – | Accepts a function that returns a `ReactNode` to format the selected value. Treat the value as read-only: in `multiple` mode it may be a shared frozen array when nothing is selected. |
| `placeholder` | `ReactNode` | – | The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`. |

---

# Command

> A searchable list of commands, usually opened as a palette with a keyboard shortcut.

Source: https://ui.xiod.dev/docs/components/command

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Command,
  CommandCollection,
  CommandDialog,
  CommandDialogPopup,
  CommandDialogTrigger,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandGroupLabel,
  CommandInput,
  CommandItem,
  CommandList,
  CommandPanel,
  CommandSeparator,
  CommandShortcut,
  CommandCreateHandle
} from "xiod-ui/command";
```

Anatomy:

```tsx
<CommandDialog>
  <CommandDialogTrigger />
  <CommandDialogPopup>
    <Command>
      <CommandInput />
      <CommandPanel>
        <CommandEmpty />
        <CommandList>
          <CommandGroup>
            <CommandGroupLabel />
            <CommandCollection>
              <CommandItem>
                <CommandShortcut />
              </CommandItem>
            </CommandCollection>
          </CommandGroup>
          <CommandSeparator />
        </CommandList>
      </CommandPanel>
      <CommandFooter />
    </Command>
  </CommandDialogPopup>
</CommandDialog>
```

## Example

```tsx
"use client";

import { Fragment, useEffect, useState } from "react";
import {
  ArrowDown as ArrowDownIcon,
  ArrowUp as ArrowUpIcon,
  CornerDownLeft as CornerDownLeftIcon,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Command,
  CommandCollection,
  CommandDialog,
  CommandDialogPopup,
  CommandDialogTrigger,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandGroupLabel,
  CommandInput,
  CommandItem,
  CommandList,
  CommandPanel,
  CommandSeparator,
  CommandShortcut,
} from "xiod-ui/command";
import { Kbd, KbdGroup } from "xiod-ui/kbd";

export interface Item {
  value: string;
  label: string;
  shortcut?: string;
}

export interface Group {
  value: string;
  items: Item[];
}

export const suggestions: Item[] = [
  { label: "Linear", shortcut: "⌘L", value: "linear" },
  { label: "Figma", shortcut: "⌘F", value: "figma" },
  { label: "Slack", shortcut: "⌘S", value: "slack" },
  { label: "YouTube", shortcut: "⌘Y", value: "youtube" },
  { label: "Raycast", shortcut: "⌘R", value: "raycast" },
];

export const commands: Item[] = [
  { label: "Clipboard History", shortcut: "⌘⇧C", value: "clipboard-history" },
  { label: "Import Extension", shortcut: "⌘I", value: "import-extension" },
  { label: "Create Snippet", shortcut: "⌘N", value: "create-snippet" },
  { label: "System Preferences", shortcut: "⌘,", value: "system-preferences" },
  { label: "Window Management", shortcut: "⌘⇧W", value: "window-management" },
];

export const groupedItems: Group[] = [
  { items: suggestions, value: "Suggestions" },
  { items: commands, value: "Commands" },
];

export default function CommandExample() {
  const [open, setOpen] = useState(false);

  function handleItemClick(_item: Item) {
    setOpen(false);
  }

  useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === "j" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen((isOpen) => !isOpen);
      }
    };

    document.addEventListener("keydown", down);
    return () => document.removeEventListener("keydown", down);
  }, []);

  return (
    <CommandDialog onOpenChange={setOpen} open={open}>
      <CommandDialogTrigger render={<Button variant="outline" />}>
        Open Command Palette
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>J</Kbd>
        </KbdGroup>
      </CommandDialogTrigger>
      <CommandDialogPopup>
        <Command items={groupedItems}>
          <CommandInput placeholder="Search for apps and commands..." />
          <CommandPanel>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandList>
              {(group: Group, _index: number) => (
                <Fragment key={group.value}>
                  <CommandGroup items={group.items}>
                    <CommandGroupLabel>{group.value}</CommandGroupLabel>
                    <CommandCollection>
                      {(item: Item) => (
                        <CommandItem
                          key={item.value}
                          onClick={() => handleItemClick(item)}
                          value={item.value}
                        >
                          <span className="flex-1">{item.label}</span>
                          {item.shortcut && (
                            <CommandShortcut>{item.shortcut}</CommandShortcut>
                          )}
                        </CommandItem>
                      )}
                    </CommandCollection>
                  </CommandGroup>
                  <CommandSeparator />
                </Fragment>
              )}
            </CommandList>
          </CommandPanel>
          <CommandFooter>
            <div className="flex items-center gap-4">
              <div className="flex items-center gap-2">
                <KbdGroup>
                  <Kbd>
                    <ArrowUpIcon />
                  </Kbd>
                  <Kbd>
                    <ArrowDownIcon />
                  </Kbd>
                </KbdGroup>
                <span>Navigate</span>
              </div>
              <div className="flex items-center gap-2">
                <Kbd>
                  <CornerDownLeftIcon />
                </Kbd>
                <span>Open</span>
              </div>
            </div>
            <div className="flex items-center gap-2">
              <Kbd>Esc</Kbd>
              <span>Close</span>
            </div>
          </CommandFooter>
        </Command>
      </CommandDialogPopup>
    </CommandDialog>
  );
}
```

## API Reference

### Command

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<AutocompleteRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the autocomplete. Call this after any externally controlled closing animation finishes. |
| `autoHighlight` | `boolean \| "always"` | `false` | Whether the first matching item is highlighted automatically. - `true`: highlight after the user types and keep the highlight while the query changes. - `'always'`: always highlight the first item. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultOpen` | `boolean` | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. |
| `defaultValue` | `string \| number \| readonly string[]` | – | The uncontrolled input value of the autocomplete when it's initially rendered. To render a controlled autocomplete, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `filter` | `AriaCombobox.Props<ItemValue, 'none'>['filter']` | – | Filter function used to match items against the input query. |
| `filteredItems` | `readonly unknown[] \| readonly Group<unknown>[]` | – | Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook. |
| `form` | `string` | – | Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form. |
| `grid` | `boolean` | `false` | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `id` | `string` | – | The id of the component. |
| `inline` | `boolean` | `false` | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Autocomplete.Root inline open>` |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to the hidden input element. |
| `items` | `readonly unknown[]` | – | The items to be displayed in the list. Can be either a flat array of items or an array of groups with items. Nullish entries are not supported: remove them from the data before passing it. |
| `itemToStringValue` | `((itemValue: unknown) => string)` | – | When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
| `keepHighlight` | `boolean` | `false` | Whether the highlighted item should be preserved when the pointer leaves the list. |
| `limit` | `number` | `-1` | The maximum number of items to display in the list. |
| `locale` | `LocalesArgument` | – | The locale to use for string comparison. Defaults to the user's runtime locale. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>. |
| `modal` | `boolean` | `false` | Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. |
| `mode` | `"none" \| "inline" \| "list" \| "both"` | `'list'` | Controls how the autocomplete behaves with respect to list filtering and inline autocompletion. - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item. - `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion). - `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion). - `none`: items are static (not filtered), and the input value will not change based on the active item. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onItemHighlighted` | `((highlightedValue: unknown, eventDetails: HighlightEventDetails) => void)` | – | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. - `'none'`: the highlight changed programmatically. |
| `onOpenChange` | `((open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void)` | – | Event handler called when the popup is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the popup is opened or closed. |
| `onValueChange` | `((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)` | – | Event handler called when the input value of the autocomplete changes. |
| `open` | `boolean` | – | Whether the popup is currently open. Use when controlled. |
| `openOnInputClick` | `boolean` | `false` | Whether the popup opens when clicking the input. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to choose a different option from the popup. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `submitOnItemClick` | `boolean` | `false` | Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input. |
| `value` | `string \| number \| readonly string[]` | – | The input value of the autocomplete. Use when controlled. |
| `virtualized` | `boolean` | `false` | Whether the items are being externally virtualized. |

### CommandCollection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `(item: any, index: number) => ReactNode` | – | The content of the component. |

### CommandDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<DialogRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog. |
| `disablePointerDismissal` | `boolean` | `false` | Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it. |
| `handle` | `DialogHandle<Payload>` | – | A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method. |
| `modal` | `boolean \| "trap-focus"` | `true` | Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup. |
| `onOpenChange` | `((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)` | – | Event handler called when the dialog is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the dialog is opened or closed. |
| `open` | `boolean` | – | Whether the dialog is currently open. |
| `triggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set). |

### CommandDialogPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |

### CommandDialogTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DialogHandle<unknown>` | – | A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `payload` | `unknown` | – | A payload to pass to the dialog when it is opened. |

### CommandEmpty

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### CommandFooter

Accepts `render`, plus every native `<div>` attribute.

### CommandGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly any[]` | – | Items to be rendered within this group. When provided, child `Collection` components will use these items. |

### CommandGroupLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### CommandInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `clearProps` | `ComboboxClearProps` | – | Props for the clear button, such as `aria-label` or `className`. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `showClear` | `boolean` | – | Whether to show a button at the end of the input that clears it. |
| `showTrigger` | `boolean` | – | Whether to show a button at the end of the input that opens the list. |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |
| `startAddon` | `ReactNode` | – | Decorative content, such as an icon, shown at the start of the input. It is hidden from screen readers. |
| `triggerIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `triggerProps` | `AutocompleteTriggerProps` | – | Props for the open button, such as `aria-label` or `className`. |

### CommandItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `index` | `number` | – | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus. |
| `value` | `any` | `null` | A unique value that identifies this item. |

### CommandList

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((item: any, index: number) => ReactNode)` | – | The content of the component. |

### CommandPanel

Accepts `render`, plus every native `<div>` attribute.

### CommandSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### CommandShortcut

Accepts `render`, plus every native `<kbd>` attribute.

### Helpers

`CommandCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Context Menu

> A menu of actions that opens on right-click or long-press.

Source: https://ui.xiod.dev/docs/components/context-menu

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuPopup,
  ContextMenuPortal,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubPopup,
  ContextMenuSubTrigger,
  ContextMenuTrigger
} from "xiod-ui/context-menu";
```

Anatomy:

```tsx
<ContextMenu>
  <ContextMenuTrigger />
  <ContextMenuPopup>
    <ContextMenuItem>
      <ContextMenuShortcut />
    </ContextMenuItem>
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubPopup>
        <ContextMenuItem>
          <ContextMenuShortcut />
        </ContextMenuItem>
        <ContextMenuSeparator />
      </ContextMenuSubPopup>
    </ContextMenuSub>
    <ContextMenuSeparator />
    <ContextMenuCheckboxItem />
    <ContextMenuGroup>
      <ContextMenuLabel />
      <ContextMenuRadioGroup>
        <ContextMenuRadioItem />
      </ContextMenuRadioGroup>
    </ContextMenuGroup>
  </ContextMenuPopup>
</ContextMenu>
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuPopup,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubPopup,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "xiod-ui/context-menu";

export default function ContextMenuExample() {
  const [showStatusBar, setShowStatusBar] = React.useState(true);
  const [showActivityBar, setShowActivityBar] = React.useState(false);
  const [showPanel, setShowPanel] = React.useState(false);
  const [colorProfile, setColorProfile] = React.useState<string>("srgb");

  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex h-[150px] w-full max-w-[400px] mx-auto items-center justify-center rounded-md border border-dashed text-sm">
        Right click here
      </ContextMenuTrigger>
      <ContextMenuPopup className="w-64">
        <ContextMenuItem inset>
          Back
          <ContextMenuShortcut>⌘[</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem inset disabled>
          Forward
          <ContextMenuShortcut>⌘]</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem inset>
          Reload
          <ContextMenuShortcut>⌘R</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSub>
          <ContextMenuSubTrigger inset>More Tools</ContextMenuSubTrigger>
          <ContextMenuSubPopup className="w-48">
            <ContextMenuItem>
              Save Page As...
              <ContextMenuShortcut>⇧⌘S</ContextMenuShortcut>
            </ContextMenuItem>
            <ContextMenuItem>Create Shortcut...</ContextMenuItem>
            <ContextMenuItem>Name Window...</ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem>Developer Tools</ContextMenuItem>
          </ContextMenuSubPopup>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuCheckboxItem
          checked={showStatusBar}
          onCheckedChange={setShowStatusBar}
        >
          Show Status Bar
        </ContextMenuCheckboxItem>
        <ContextMenuCheckboxItem
          checked={showActivityBar}
          onCheckedChange={setShowActivityBar}
          disabled
        >
          Show Activity Bar
        </ContextMenuCheckboxItem>
        <ContextMenuCheckboxItem
          checked={showPanel}
          onCheckedChange={setShowPanel}
        >
          Show Panel
        </ContextMenuCheckboxItem>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuLabel inset>Color Profile</ContextMenuLabel>
          <ContextMenuRadioGroup
            value={colorProfile}
            onValueChange={setColorProfile}
          >
            <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
            <ContextMenuRadioItem value="srgb">sRGB</ContextMenuRadioItem>
            <ContextMenuRadioItem value="p3">Display P3</ContextMenuRadioItem>
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
      </ContextMenuPopup>
    </ContextMenu>
  );
}
```

## API Reference

### ContextMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `onOpenChange` | `((open: boolean, eventDetails: ContextMenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |

### ContextMenuCheckboxItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – | Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `defaultChecked` | `boolean` | `false` | Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the checkbox item is ticked or unticked. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `variant` | `"switch" \| "default"` | `default` | The visual style of the component. |

### ContextMenuGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |

### ContextMenuItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnClick` | `boolean` | `true` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `variant` | `"default" \| "destructive"` | `default` | The visual style of the component. |

### ContextMenuLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | – | Whether to indent the label so it lines up with items that have an icon. |

### ContextMenuPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `8` | Distance between the anchor and the popup, in pixels. |

### ContextMenuPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### ContextMenuRadioGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultValue` | `any` | – | The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onValueChange` | `((value: any, eventDetails: MenuRootChangeEventDetails) => void)` | – | Function called when the selected value changes. |
| `value` | `any` | – | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |

### ContextMenuRadioItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |

### ContextMenuSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### ContextMenuShortcut

Accepts `render`, plus every native `<kbd>` attribute.

### ContextMenuSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode` | – | The content of the submenu. |
| `closeParentOnEsc` | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |

### ContextMenuSubPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `sideOffset` | `number \| OffsetFunction` | `0` | Distance between the anchor and the popup, in pixels. |

### ContextMenuSubTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `100` | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `openOnHover` | `boolean` | `true` | Whether the menu should also open when the trigger is hovered. |

### ContextMenuTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

---

# Copy To Clipboard

> A button that copies a value to the clipboard and confirms when it has.

Source: https://ui.xiod.dev/docs/components/copy-to-clipboard

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { CopyToClipboard } from "xiod-ui/copy-to-clipboard";
```

## Example

```tsx
import { CopyToClipboard } from "xiod-ui/copy-to-clipboard";

export default function CopyToClipboardExample() {
  return (
    <div className="flex flex-col gap-8 w-full max-w-sm">
      <div className="flex flex-col gap-2">
        <h3 className="text-sm font-medium">Default</h3>
        <CopyToClipboard text="npm install xiod-ui" />
      </div>

      <div className="flex flex-col gap-2">
        <h3 className="text-sm font-medium">Custom Tooltip & Toast</h3>
        <CopyToClipboard
          text="sk_test_12345"
          tooltipText="Copy API Key"
          copiedText="Key copied to clipboard!"
        />
      </div>

      <div className="flex flex-col gap-2">
        <h3 className="text-sm font-medium">Sizes</h3>
        <div className="flex flex-col gap-3">
          <CopyToClipboard size="sm" text="Small size (sm)" />
          <CopyToClipboard size="default" text="Default size" />
          <CopyToClipboard size="lg" text="Large size (lg)" />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### CopyToClipboard

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The text shown in the field. It is also what gets copied, unless you set `textToCopy`. |
| `copiedIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `copiedText` | `string` | `Copied!` | The message in the toast shown after copying. |
| `copyIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `disableTooltip` | `boolean` | `false` | Whether to hide the copy button's tooltip. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `textToCopy` | `string` | – | The text to copy, when it differs from what the field shows. |
| `tooltipText` | `string` | `Copy` | The copy button's tooltip, also used as its accessible name. |

---

# Corner Badge

> A count or status dot pinned to the corner of another element.

Source: https://ui.xiod.dev/docs/components/corner-badge

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { CornerBadge, CornerBadgeAnchor } from "xiod-ui/corner-badge";
```

Anatomy:

```tsx
<CornerBadgeAnchor>
  <CornerBadge />
</CornerBadgeAnchor>
```

## Example

```tsx
"use client";

import { Bell as BellIcon, Mail as MailIcon } from "xiod-icons";
import { Avatar, AvatarFallback, AvatarImage } from "xiod-ui/avatar";
import { Button } from "xiod-ui/button";
import { CornerBadge, CornerBadgeAnchor } from "xiod-ui/corner-badge";

const placeholderSrc = "/placeholder.svg";

export default function CornerBadgeExample() {
  return (
    <div className="flex flex-col gap-12 items-center">
      <div className="flex flex-wrap gap-8 items-center justify-center">
        {/* Rectangle overlap with number */}

        <CornerBadgeAnchor>
          <Button variant="outline" size="icon" className="size-12">
            <MailIcon className="size-5" />
          </Button>
          <CornerBadge position="top-left" variant="destructive">
            5
          </CornerBadge>
        </CornerBadgeAnchor>

        <CornerBadgeAnchor>
          <Button variant="outline" size="icon" className="size-12">
            <MailIcon className="size-5" />
          </Button>
          <CornerBadge className="bg-green-500 rounded-full">5</CornerBadge>
        </CornerBadgeAnchor>

        <CornerBadgeAnchor>
          <Button variant="outline" size="icon" className="size-12">
            <MailIcon className="size-5" />
          </Button>
          <CornerBadge position="bottom-left" dot variant="destructive">
            5
          </CornerBadge>
        </CornerBadgeAnchor>

        {/* Rectangle overlap with dot */}
        <CornerBadgeAnchor>
          <Button variant="outline" size="icon" className="size-12">
            <BellIcon className="size-5" />
          </Button>
          <CornerBadge variant="error" dot />
        </CornerBadgeAnchor>

        {/* Circular overlap with text */}
        <CornerBadgeAnchor>
          <Avatar className="size-12">
            <AvatarImage src={placeholderSrc} alt="example" />
            <AvatarFallback>EX</AvatarFallback>
          </Avatar>
          <CornerBadge
            overlap="circular"
            className="h-4 min-w-4 px-1.5 text-[0.6rem]"
          >
            New
          </CornerBadge>
        </CornerBadgeAnchor>

        {/* Circular overlap with dot (status indicator) */}
        <CornerBadgeAnchor>
          <Avatar className="size-12">
            <AvatarImage src={placeholderSrc} alt="example" />
            <AvatarFallback>EX</AvatarFallback>
          </Avatar>
          <CornerBadge
            dot
            overlap="circular"
            position="bottom-right"
            variant="success"
          />
        </CornerBadgeAnchor>
      </div>
    </div>
  );
}
```

## API Reference

### CornerBadge

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dot` | `boolean` | `false` | Whether to show a small dot instead of the badge's content. |
| `invisible` | `boolean` | – | Whether to hide the badge. It scales and fades out rather than unmounting. |
| `overlap` | `"rectangle" \| "circular"` | `rectangle` | The shape of the element the badge sits on. `circular` moves the badge in to meet the edge of a round element, such as an `Avatar`. |
| `position` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `top-right` | The corner of the parent element the badge sits on. |
| `size` | `"sm" \| "lg" \| "default"` | – | The size of the component. |
| `variant` | `"error" \| "default" \| "success" \| "warning" \| "info" \| "secondary" \| "outline" \| "destructive"` | – | The visual style of the component. |

### CornerBadgeAnchor

Accepts `render`, plus every native `<div>` attribute.

---

# Dashboard Grid

> A grid of tiles the user can rearrange and resize by dragging or with the keyboard.

Source: https://ui.xiod.dev/docs/components/dashboard-grid

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  DashboardGrid,
  DashboardTile,
  DashboardTileControls,
  DashboardTileHandle,
  DashboardTileHeader,
  DashboardTileResizeHandle,
  DashboardTileTitle
} from "xiod-ui/dashboard-grid";
```

Anatomy:

```tsx
<DashboardGrid>
  <DashboardTile>
    <DashboardTileHeader>
      <DashboardTileTitle />
    </DashboardTileHeader>
  </DashboardTile>
</DashboardGrid>
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  Activity,
  ChartBar,
  Coins,
  Lock,
  RefreshDouble as RefreshCw,
  User,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  DashboardGrid,
  DashboardTile,
  type DashboardTileData,
  DashboardTileHeader,
  DashboardTileTitle,
} from "xiod-ui/dashboard-grid";

const initialLayout: DashboardTileData[] = [
  { i: "traffic", x: 0, y: 0, w: 8, h: 4, minW: 4, minH: 3 },
  { i: "sources", x: 8, y: 0, w: 4, h: 4, minW: 3, minH: 3 },
  { i: "activity", x: 0, y: 4, w: 4, h: 3, minW: 3, minH: 2 },
  { i: "revenue", x: 4, y: 4, w: 4, h: 3, minW: 3, minH: 2 },
  { i: "pinned", x: 8, y: 4, w: 4, h: 3, static: true },
];

const trafficBars = [40, 65, 50, 85, 60, 95, 75, 100, 85, 110, 90, 120];

const sources = [
  { label: "Direct", value: "42%" },
  { label: "Search", value: "31%" },
  { label: "Referral", value: "18%" },
  { label: "Social", value: "9%" },
];

const activity = [
  { label: "Deploys", value: "12" },
  { label: "Builds", value: "48" },
  { label: "Errors", value: "3" },
];

const revenue = [
  { label: "This month", value: "$18,400" },
  { label: "Last month", value: "$16,120" },
  { label: "Growth", value: "+14%" },
];

function TileList({ rows }: { rows: { label: string; value: string }[] }) {
  return (
    <div className="flex flex-1 flex-col justify-around p-3 text-xs">
      {rows.map((row) => (
        <div key={row.label} className="flex items-center justify-between">
          <span className="text-muted-foreground">{row.label}</span>
          <span className="font-medium text-foreground">{row.value}</span>
        </div>
      ))}
    </div>
  );
}

export function DashboardGridExample() {
  const [layout, setLayout] =
    React.useState<DashboardTileData[]>(initialLayout);
  const [compactType, setCompactType] = React.useState<
    "vertical" | "horizontal" | null
  >("vertical");

  return (
    <div className="flex w-full max-w-4xl flex-col gap-4">
      {/* Dragging and compaction have no static form, so the grid keeps a small
          toolbar for the layout props a reader cannot otherwise observe. */}
      <div className="flex flex-wrap items-center justify-end gap-2">
        <Button
          variant={compactType === "vertical" ? "default" : "outline"}
          size="xs"
          onClick={() => setCompactType("vertical")}
        >
          Compact
        </Button>
        <Button
          variant={compactType === null ? "default" : "outline"}
          size="xs"
          onClick={() => setCompactType(null)}
        >
          Free
        </Button>
        <Button
          variant="ghost"
          size="xs"
          onClick={() => setLayout(initialLayout)}
        >
          <RefreshCw className="size-3" />
          Reset
        </Button>
      </div>

      <DashboardGrid
        layout={layout}
        // A fixed column count keeps every tile's `w` valid at any width. The
        // responsive `cols` map shrinks the grid without rescaling the layout,
        // so a tile wider than the current breakpoint's columns overflows.
        cols={12}
        rowHeight={65}
        compactType={compactType}
        showGridLines
        variant="canvas"
        onLayoutChange={setLayout}
        onTileRemove={(id) =>
          setLayout((prev) => prev.filter((item) => item.i !== id))
        }
      >
        <DashboardTile id="traffic" variant="expressive">
          <DashboardTileHeader id="traffic">
            <div className="flex items-center gap-2 truncate">
              <ChartBar className="size-4 shrink-0 text-primary" />
              <DashboardTileTitle>Traffic</DashboardTileTitle>
            </div>
          </DashboardTileHeader>
          <div className="flex flex-1 items-end gap-1 p-4">
            {trafficBars.map((height, index) => (
              <div
                key={index}
                className="flex-1 rounded-xs bg-primary/60"
                style={{ height: `${height / 1.4}%` }}
              />
            ))}
          </div>
        </DashboardTile>

        <DashboardTile id="sources">
          <DashboardTileHeader id="sources">
            <div className="flex items-center gap-2 truncate">
              <User className="size-4 shrink-0 text-primary" />
              <DashboardTileTitle>Sources</DashboardTileTitle>
            </div>
          </DashboardTileHeader>
          <TileList rows={sources} />
        </DashboardTile>

        <DashboardTile id="activity">
          <DashboardTileHeader id="activity">
            <div className="flex items-center gap-2 truncate">
              <Activity className="size-4 shrink-0 text-primary" />
              <DashboardTileTitle>Activity</DashboardTileTitle>
            </div>
          </DashboardTileHeader>
          <TileList rows={activity} />
        </DashboardTile>

        <DashboardTile id="revenue">
          <DashboardTileHeader id="revenue">
            <div className="flex items-center gap-2 truncate">
              <Coins className="size-4 shrink-0 text-primary" />
              <DashboardTileTitle>Revenue</DashboardTileTitle>
            </div>
          </DashboardTileHeader>
          <TileList rows={revenue} />
        </DashboardTile>

        <DashboardTile id="pinned" variant="flat">
          <DashboardTileHeader id="pinned">
            <div className="flex items-center gap-2 truncate">
              <Lock className="size-4 shrink-0 text-muted-foreground" />
              <DashboardTileTitle>Pinned</DashboardTileTitle>
            </div>
          </DashboardTileHeader>
          <div className="flex flex-1 items-center justify-center p-3 text-xs text-muted-foreground">
            Static tile
          </div>
        </DashboardTile>
      </DashboardGrid>
    </div>
  );
}

export default DashboardGridExample;
```

## API Reference

### DashboardGrid

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` (required) | `DashboardTileData[]` | – | The position and size of every tile. Keep it in state and update it from `onLayoutChange`. |
| `breakpoints` | `Breakpoints` | `{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0, }` | The smallest grid width, in pixels, at which each breakpoint applies. Only used when `cols` is an object. |
| `cols` | `number \| BreakpointCols` | `12` | The number of columns: one number for every width, or an object with a count per breakpoint (`lg`, `md`, `sm`, `xs`, `xxs`). |
| `compactType` | `"horizontal" \| "vertical"` | `vertical` | Which way tiles move to fill gaps: `vertical` pulls them up, `horizontal` pulls them left, and `null` leaves them where they are dropped. |
| `containerPadding` | `[number, number]` | `[12, 12]` | The space between the tiles and the edge of the grid, in pixels, as `[horizontal, vertical]`. |
| `isDraggable` | `boolean` | `true` | Whether tiles can be moved, by pointer or keyboard. |
| `isResizable` | `boolean` | `true` | Whether tiles can be resized, by pointer or keyboard. |
| `margin` | `[number, number]` | `[12, 12]` | The space between tiles, in pixels, as `[horizontal, vertical]`. |
| `onLayoutChange` | `((layout: DashboardTileData[]) => void)` | – | Called with the new layout after a tile is moved or resized. |
| `onTileRemove` | `((id: string) => void)` | – | Called with a tile's id when its remove button is pressed. The remove button only shows when this is set. |
| `preventCollision` | `boolean` | `false` | Whether a tile can't be dropped on top of another. When `false`, the other tiles move out of the way. |
| `rowHeight` | `number` | `60` | The height of one row, in pixels. |
| `showGridLines` | `boolean` | `false` | Whether to draw the column and row lines behind the tiles. |
| `variant` | `"canvas" \| "default" \| "ghost" \| "bordered"` | `default` | The visual style of the component. |

### DashboardTile

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The tile's id, matching an `i` in the grid's `layout`. |
| `variant` | `"default" \| "flat" \| "expressive"` | `default` | The visual style of the component. |

### DashboardTileControls

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `id` | `string` | – | The id of the tile these controls belong to. With it, and the grid's `onTileRemove` set, they show a remove button by default. |

### DashboardTileHandle

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `id` | `string` | – | The id of the tile this handle moves, by dragging or with the arrow keys. |

### DashboardTileHeader

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `id` | `string` | – | The id of the tile this header belongs to. With it, the header moves the tile when dragged and shows its remove button. |

### DashboardTileResizeHandle

Accepts `render`, plus every native attribute of the element it renders.

### DashboardTileTitle

Accepts `render`, plus every native attribute of the element it renders.

---

# Date Picker

> A field that opens a calendar for picking a date or a range.

Source: https://ui.xiod.dev/docs/components/date-picker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { DatePicker } from "xiod-ui/date-picker";
```

## Example

```tsx
"use client";

import * as React from "react";
import type { DateRange } from "xiod-ui/calendar";
import { DatePicker } from "xiod-ui/date-picker";

export default function DatePickerExample() {
  const [singleDateBtn, setSingleDateBtn] = React.useState<Date | undefined>(
    () => new Date(),
  );
  const [singleDateInput, setSingleDateInput] = React.useState<
    Date | undefined
  >(() => new Date());

  const [dateRangeBtn, setDateRangeBtn] = React.useState<DateRange | undefined>(
    () => {
      const today = new Date();
      const future = new Date();
      future.setDate(today.getDate() + 7);
      return { from: today, to: future };
    },
  );

  const [dateRangeInput, setDateRangeInput] = React.useState<
    DateRange | undefined
  >(() => {
    const today = new Date();
    const future = new Date();
    future.setDate(today.getDate() + 10);
    return { from: today, to: future };
  });

  return (
    <div className="flex flex-col gap-10 py-6 items-center w-full">
      {/* Button Triggers Group */}
      <div className="grid grid-cols-1 md:grid-cols-2 gap-8 w-full max-w-2xl">
        <div className="flex flex-col gap-2">
          <h4 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
            Single (Button Dropdown)
          </h4>
          <DatePicker
            mode="single"
            triggerType="button"
            value={singleDateBtn}
            onSelect={(val) => {
              if (val instanceof Date || val === undefined) {
                setSingleDateBtn(val);
              }
            }}
          />
        </div>

        <div className="flex flex-col gap-2">
          <h4 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
            Range (Button Dropdown)
          </h4>
          <DatePicker
            mode="range"
            triggerType="button"
            numberOfMonths={2}
            value={dateRangeBtn}
            onSelect={(val) => {
              if (
                val &&
                typeof val === "object" &&
                ("from" in val || "to" in val)
              ) {
                setDateRangeBtn(val as DateRange);
              } else if (val === undefined) {
                setDateRangeBtn(undefined);
              }
            }}
          />
        </div>
      </div>

      {/* Input Triggers Group */}
      <div className="grid grid-cols-1 md:grid-cols-2 gap-8 w-full max-w-2xl">
        <div className="flex flex-col gap-2">
          <h4 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
            Single (Typeable Input)
          </h4>
          <DatePicker
            mode="single"
            triggerType="input"
            value={singleDateInput}
            onSelect={(val) => {
              if (val instanceof Date || val === undefined) {
                setSingleDateInput(val);
              }
            }}
          />
        </div>

        <div className="flex flex-col gap-2">
          <h4 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
            Range (Typeable Inputs)
          </h4>
          <DatePicker
            mode="range"
            triggerType="input"
            numberOfMonths={2}
            value={dateRangeInput}
            onSelect={(val) => {
              if (
                val &&
                typeof val === "object" &&
                ("from" in val || "to" in val)
              ) {
                setDateRangeInput(val as DateRange);
              } else if (val === undefined) {
                setDateRangeInput(undefined);
              }
            }}
          />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### DatePicker

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `Date \| DateRange` | – | The date, or `{ from, to }` range, selected at first, when it isn't controlled. |
| `disabled` | `boolean \| Date \| Date[] \| ((date: Date) => boolean)` | – | Days that can't be selected: `true` for all, a date, a list of dates, or a function that returns `true` for a date. |
| `disableOutsideDays` | `boolean` | `false` | Whether days from the previous and next months can't be selected. |
| `fixedWeeks` | `boolean` | `true` | Whether every month shows six weeks, so the calendar's height doesn't change between months. |
| `formatStr` | `"PPP" \| "LLL dd, y" \| "yyyy-MM-dd"` | `PPP` | How the button shows a single date: `"PPP"` for September 26, 2026, `"LLL dd, y"` for Sep 26, 2026, or `"yyyy-MM-dd"` for 2026-09-26. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `maxDate` | `Date` | – | The latest date that can be selected. |
| `minDate` | `Date` | – | The earliest date that can be selected. |
| `mode` | `"single" \| "range"` | `single` | Whether the user picks one date (`single`) or a start and end date (`range`). |
| `numberOfMonths` | `number` | `1` | How many months the calendar shows side by side. |
| `onSelect` | `((value: Date \| DateRange) => void)` | – | Called with the new date, or the new `{ from, to }` range, when the user picks or types one. |
| `placeholder` | `string` | – | The text shown when no date is selected. |
| `showOutsideDays` | `boolean` | `true` | Whether the calendar shows the days of the previous and next months that fill the first and last weeks. |
| `triggerClassName` | `string` | – | Classes for the button or input that opens the calendar. |
| `triggerSize` | `"sm" \| "lg" \| "default" \| "xs"` | `default` | The `Button` size of the trigger, when `triggerType` is `button`. |
| `triggerType` | `"button" \| "input"` | `button` | What opens the calendar: a `button` showing the formatted date, or an `input` the user can also type a date into as YYYY-MM-DD. |
| `triggerVariant` | `"default" \| "secondary" \| "outline" \| "ghost"` | `outline` | The `Button` variant of the trigger, when `triggerType` is `button`. |
| `value` | `Date \| DateRange` | – | The selected date, or `{ from, to }` in `range` mode. Use with `onSelect` to control it. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` | The first day of the week, from 0 for Sunday to 6 for Saturday. |

---

# Dialog

> A modal window that opens over the page.

Source: https://ui.xiod.dev/docs/components/dialog

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogPanel,
  DialogPopup,
  DialogPortal,
  DialogTitle,
  DialogTrigger,
  DialogViewport,
  DialogCreateHandle
} from "xiod-ui/dialog";
```

Anatomy:

```tsx
<Dialog>
  <DialogTrigger />
  <DialogPopup>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogPanel />
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogPopup>
</Dialog>
```

## Example

```tsx
import { Button } from "xiod-ui/button";
import {
  Dialog,
  DialogClose,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogPanel,
  DialogPopup,
  DialogTitle,
  DialogTrigger,
} from "xiod-ui/dialog";
import { Field, FieldLabel } from "xiod-ui/field";
import { Form } from "xiod-ui/form";
import { Input } from "xiod-ui/input";

export default function DialogExample() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Open Dialog
      </DialogTrigger>
      <DialogPopup className="sm:max-w-sm">
        <Form className="contents">
          <DialogHeader>
            <DialogTitle>Edit profile</DialogTitle>
            <DialogDescription>
              Make changes to your profile here. Click save when you&apos;re
              done.
            </DialogDescription>
          </DialogHeader>
          <DialogPanel className="grid gap-4">
            <Field>
              <FieldLabel>Name</FieldLabel>
              <Input defaultValue="Optimus Prime" type="text" />
            </Field>
            <Field>
              <FieldLabel>Username</FieldLabel>
              <Input defaultValue="@optimus.prime" type="text" />
            </Field>
          </DialogPanel>
          <DialogFooter>
            <DialogClose render={<Button variant="ghost" />}>
              Cancel
            </DialogClose>
            <Button type="submit">Save</Button>
          </DialogFooter>
        </Form>
      </DialogPopup>
    </Dialog>
  );
}
```

## API Reference

### Dialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<DialogRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog. |
| `disablePointerDismissal` | `boolean` | `false` | Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it. |
| `handle` | `DialogHandle<Payload>` | – | A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method. |
| `modal` | `boolean \| "trap-focus"` | `true` | Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup. |
| `onOpenChange` | `((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)` | – | Event handler called when the dialog is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the dialog is opened or closed. |
| `open` | `boolean` | – | Whether the dialog is currently open. |
| `triggerId` | `string \| null` | – | ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set). |

### DialogBackdrop

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `forceRender` | `boolean` | `false` | Whether the backdrop is forced to render even when nested. |

### DialogClose

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### DialogDescription

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### DialogFooter

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "bare"` | `default` | The visual style of the component. |

### DialogHeader

Accepts `render`, plus every native `<div>` attribute.

### DialogPanel

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollFade` | `boolean` | `true` | Whether the content fades out at an edge that has more to scroll to. |

### DialogPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bottomStickOnMobile` | `boolean` | `true` | Whether the dialog docks to the bottom edge as a full-width sheet on small screens. |
| `closeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `closeProps` | `DialogCloseProps` | – | Props for the close button, such as `aria-label` or `className`. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `showCloseButton` | `boolean` | `true` | Whether to show the close button in the top corner. |

### DialogPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### DialogTitle

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### DialogTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DialogHandle<unknown>` | – | A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `payload` | `unknown` | – | A payload to pass to the dialog when it is opened. |

### DialogViewport

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### Helpers

`DialogCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Dot Matrix

> An animated grid of dots, for loading states and decorative displays.

Source: https://ui.xiod.dev/docs/components/dot-matrix

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { DotMatrix } from "xiod-ui/dot-matrix";
```

## Example

```tsx
"use client";

import { useEffect, useState } from "react";
import { Card, CardPanel } from "xiod-ui/card";
import { DotMatrix } from "xiod-ui/dot-matrix";

export default function DotMatrixExample() {
  const [vuLevels, setVuLevels] = useState<number[]>([0.5, 0.7, 0.4, 0.9, 0.6]);

  // Simulate audio VU levels changing dynamically
  useEffect(() => {
    const interval = setInterval(() => {
      setVuLevels(Array.from({ length: 5 }, () => Math.random() * 0.9 + 0.1));
    }, 150);
    return () => clearInterval(interval);
  }, []);

  // Custom digit "5" pattern for 5x5 grid
  const digitFivePattern = [
    [1, 1, 1, 1, 1],
    [1, 0, 0, 0, 0],
    [1, 1, 1, 1, 0],
    [0, 0, 0, 0, 1],
    [1, 1, 1, 1, 0],
  ];

  return (
    <div className="flex flex-col gap-6 p-4">
      {/* SECTION 1: Animations Presets */}
      <div>
        <h3 className="mb-3 font-heading font-semibold text-lg text-foreground">
          Preset Animations
        </h3>
        <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 md:grid-cols-7">
          {[
            { name: "Ripple", preset: "ripple" as const },
            { name: "Spiral", preset: "spiral" as const },
            { name: "Snake", preset: "snake" as const },
            { name: "Wave Horizontal", preset: "wave" as const },
            { name: "Wave Vertical", preset: "wave-vertical" as const },
            { name: "Diagonal Sweep", preset: "diagonal" as const },
            { name: "Diagonal Reverse", preset: "diagonal-reverse" as const },
            { name: "Core Rotor", preset: "rotor" as const },
            { name: "Columns Flux", preset: "columns-flux" as const },
            { name: "DNA Helix", preset: "helix" as const },
            { name: "Half Helix", preset: "half-helix" as const },
            { name: "Infinity Run", preset: "infinity" as const },
            { name: "Heart Beat", preset: "heart-pulse" as const },
            { name: "Orbit Chase", preset: "orbit" as const },
            { name: "Twin Orbit", preset: "twin-orbit" as const },
            { name: "Matrix Rain", preset: "matrix-rain" as const },
            { name: "Sine Wave", preset: "sine-wave" as const },
            { name: "CRT Glide", preset: "crt-glide" as const },
            { name: "Rung Shift", preset: "rung-shift" as const },
            { name: "Lunar Breath", preset: "lunar-breath" as const },
            { name: "Nova Wheel", preset: "nova-wheel" as const },
            { name: "Prism Bloom", preset: "prism-bloom" as const },
            { name: "Honey Gate", preset: "honey-gate" as const },
            { name: "Spiral Lattice", preset: "spiral-lattice" as const },
            { name: "Altitude Wave", preset: "altitude-wave" as const },
            { name: "Glyph Cluster", preset: "glyph-cluster" as const },
            { name: "Rail Scan", preset: "rail-scan" as const },
            { name: "Halo Drift", preset: "halo-drift" as const },
            { name: "Breathing Pulse", preset: "pulse" as const },
          ].map((item) => (
            <Card
              key={item.name}
              className="flex flex-col items-center justify-center p-4 text-center"
            >
              <DotMatrix
                preset={item.preset}
                rows={5}
                cols={5}
                dotSize={6}
                gap={2}
              />
              <span className="mt-2 text-muted-foreground text-xs">
                {item.name}
              </span>
            </Card>
          ))}
        </div>
      </div>

      {/* SECTION 2: Shapes & Sizing */}
      <div className="grid grid-cols-1 gap-6 md:grid-cols-2">
        <div>
          <h3 className="mb-3 font-heading font-semibold text-lg text-foreground">
            Dot Shapes
          </h3>
          <div className="grid grid-cols-4 gap-4">
            {[
              {
                name: "Circle",
                shape: "circle" as const,
                colorPreset: "sunset" as const,
              },
              {
                name: "Square",
                shape: "square" as const,
                colorPreset: "neon" as const,
              },
              {
                name: "Diamond",
                shape: "diamond" as const,
                colorPreset: "ocean" as const,
              },
              {
                name: "Heart",
                shape: "heart" as const,
                colorPreset: "fire" as const,
              },
            ].map((item) => (
              <Card
                key={item.name}
                className="flex flex-col items-center justify-center p-4 text-center"
              >
                <DotMatrix
                  shape={item.shape}
                  preset="ripple"
                  colorPreset={item.colorPreset}
                  rows={5}
                  cols={5}
                  dotSize={6}
                  gap={2.5}
                />
                <span className="mt-2 text-muted-foreground text-xs">
                  {item.name}
                </span>
              </Card>
            ))}
          </div>
        </div>

        <div>
          <h3 className="mb-3 font-heading font-semibold text-lg text-foreground">
            Grid Sizes
          </h3>
          <div className="grid grid-cols-4 gap-4">
            {[
              { name: "3x3 Mini", r: 3, c: 3, size: 8 },
              { name: "5x5 Standard", r: 5, c: 5, size: 6 },
              { name: "8x8 Large", r: 8, c: 8, size: 5 },
              { name: "12x12 HD", r: 12, c: 12, size: 4 },
            ].map((item) => (
              <Card
                key={item.name}
                className="flex flex-col items-center justify-center p-4 text-center"
              >
                <DotMatrix
                  rows={item.r}
                  cols={item.c}
                  dotSize={item.size}
                  gap={2}
                  preset="wave"
                  colorPreset="prism"
                />
                <span className="mt-2 text-muted-foreground text-xs text-center leading-tight">
                  {item.name}
                </span>
              </Card>
            ))}
          </div>
        </div>
      </div>

      {/* SECTION 3: Gradients & VU Equalizer & Custom Pattern */}
      <div className="grid grid-cols-1 gap-6 sm:grid-cols-3">
        <Card className="flex flex-col items-center justify-center p-6 text-center">
          <CardPanel className="flex flex-col items-center justify-center gap-4">
            <DotMatrix
              mode="vu"
              levels={vuLevels}
              rows={7}
              cols={5}
              dotSize={8}
              gap={3}
              shape="square"
              colorPreset="neon"
            />
            <div className="flex flex-col items-center">
              <span className="font-semibold text-sm">Equalizer (VU)</span>
              <span className="text-muted-foreground text-xs">
                Real-time level spectrum
              </span>
            </div>
          </CardPanel>
        </Card>

        <Card className="flex flex-col items-center justify-center p-6 text-center">
          <CardPanel className="flex flex-col items-center justify-center gap-4">
            <DotMatrix
              mode="static"
              pattern={digitFivePattern}
              rows={5}
              cols={5}
              dotSize={10}
              gap={3}
              shape="circle"
              colorPreset="sunset"
            />
            <div className="flex flex-col items-center">
              <span className="font-semibold text-sm">Static Pattern</span>
              <span className="text-muted-foreground text-xs">
                Custom digit &ldquo;5&rdquo;
              </span>
            </div>
          </CardPanel>
        </Card>

        <Card className="flex flex-col items-center justify-center p-6 text-center">
          <CardPanel className="flex flex-col items-center justify-center gap-4">
            <DotMatrix
              preset="spiral"
              speed={1.5}
              rows={6}
              cols={6}
              dotSize={7}
              gap={2.5}
              colorPreset="aurora"
            />
            <div className="flex flex-col items-center">
              <span className="font-semibold text-sm">Aurora Gradient</span>
              <span className="text-muted-foreground text-xs">
                Mapped matrix gradient
              </span>
            </div>
          </CardPanel>
        </Card>
      </div>
    </div>
  );
}
```

## API Reference

### DotMatrix

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaLabel` | `string` | `Dot matrix loader` | The name screen readers announce for the matrix. |
| `autoplay` | `boolean` | `true` | Whether the animation plays on its own. Animations never play when the user prefers reduced motion. |
| `bloom` | `boolean` | `true` | Whether lit dots glow. |
| `bloomIntensity` | `number` | `1.8` | How far the glow spreads. Higher values give a softer, wider glow. |
| `color` | `string` | `currentColor` | The colour of lit dots, as a CSS colour. |
| `colorOff` | `string` | `var(--muted-foreground)` | The colour of unlit dots, as a CSS colour. |
| `colorPreset` | `"solid" \| "sunset" \| "ocean" \| "neon" \| "aurora" \| "fire" \| "prism"` | `solid` | A gradient to colour the lit dots with. `solid` uses `color`. |
| `cols` | `number` | `5` | The number of columns of dots. |
| `dotSize` | `number` | `8` | The size of each dot, in pixels. |
| `fps` | `number` | `12` | How many custom `frames` to show per second. |
| `frames` | `number[][][]` | – | Your own animation for `animation` mode: a list of frames, each one array per row of brightness values from 0 to 1. Takes the place of `preset`. |
| `gap` | `number` | `3` | The space between dots, in pixels. |
| `halo` | `boolean` | `false` | Whether to add a soft glow behind the whole matrix. |
| `isPlaying` | `boolean` | `true` | Whether the animation is playing. Set it to `false` to pause. |
| `levels` | `number[]` | – | The height of each column in `vu` mode, from 0 to 1, left to right. |
| `loop` | `boolean` | `true` | Whether custom `frames` start over after the last one. When `false`, the animation stops on the last frame. |
| `mode` | `"animation" \| "static" \| "vu"` | `animation` | What the dots show: an animation (a `preset` or your own `frames`), a fixed `pattern`, or level bars from `levels`. |
| `onFrame` | `((index: number) => void)` | – | Called with the index of each custom frame as it is shown. |
| `pattern` | `number[][] \| boolean[][]` | – | The dots to light in `static` mode, one array per row. Each value is `true`/`false`, or a brightness from 0 to 1. |
| `preset` | `"none" \| "ripple" \| "spiral" \| "snake" \| "wave" \| "wave-vertical" \| "pulse" \| "diagonal" \| "diagonal-reverse" \| "rotor" \| "columns-flux" \| "helix" \| "infinity" \| "heart-pulse" \| "orbit" \| "matrix-rain" \| "sine-wave" \| "crt-glide" \| "twin-orbit" \| "rung-shift" \| "lunar-breath" \| "nova-wheel" \| "prism-bloom" \| "half-helix" \| "honey-gate" \| "spiral-lattice" \| "altitude-wave" \| "glyph-cluster" \| "rail-scan" \| "halo-drift"` | `ripple` | The built-in animation to play in `animation` mode when no `frames` are given. `none` shows every dot lit. |
| `rows` | `number` | `5` | The number of rows of dots. |
| `shape` | `"circle" \| "square" \| "diamond" \| "heart"` | `circle` | The shape of each dot. |
| `speed` | `number` | `1` | How fast a `preset` animation plays, as a multiple of its normal speed. |

---

# Draggable

> A floating panel the user can move, resize, minimize and maximize.

Source: https://ui.xiod.dev/docs/components/draggable

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Draggable,
  DraggableBody,
  DraggableControls,
  DraggableFooter,
  DraggableHandle,
  DraggableHeader,
  DraggableResizeHandle,
  DraggableTitle
} from "xiod-ui/draggable";
```

Anatomy:

```tsx
<Draggable>
  <DraggableHeader>
    <DraggableHandle />
    <DraggableTitle />
    <DraggableControls />
  </DraggableHeader>
  <DraggableBody />
  <DraggableFooter />
</Draggable>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Bot, Sent as Send, Sparkles } from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Draggable,
  DraggableBody,
  DraggableControls,
  DraggableFooter,
  DraggableHandle,
  DraggableHeader,
  DraggableTitle,
} from "xiod-ui/draggable";
import { Input } from "xiod-ui/input";

export function DraggableExample() {
  const [open, setOpen] = React.useState(true);
  const [messages, setMessages] = React.useState<string[]>([
    "Hello! I am your Draggable AI Assistant.",
    "Drag my header to move me, or focus the grip and use the arrow keys.",
    "Resize me using the bottom-right corner, or minimize/maximize me!",
  ]);
  const [inputText, setInputText] = React.useState("");

  const handleSendMessage = (e: React.FormEvent) => {
    e.preventDefault();
    if (!inputText.trim()) return;
    setMessages((prev) => [...prev, inputText.trim()]);
    setInputText("");
  };

  return (
    <div className="flex flex-col gap-6 w-full max-w-2xl mx-auto p-4 items-center justify-center min-h-[400px] border border-border/40 bg-background/40 rounded-xl relative overflow-hidden">
      {/* Trigger Button */}
      <div className="flex flex-col items-center gap-3">
        <Button onClick={() => setOpen((prev) => !prev)}>
          <Bot aria-hidden />
          {open ? "Hide Draggable Panel" : "Show Draggable AI Assistant"}
        </Button>
        <span className="text-[11px] font-mono text-muted-foreground">
          Click button to toggle draggable overlay window
        </span>
      </div>

      {/* Draggable Instance */}
      <Draggable
        open={open}
        onOpenChange={setOpen}
        defaultX={80}
        defaultY={60}
        defaultWidth={340}
        defaultHeight={320}
        variant="expressive"
      >
        <DraggableHeader>
          <div className="flex items-center gap-1.5 truncate">
            <DraggableHandle />
            <Sparkles className="size-3.5 text-primary shrink-0" />
            <DraggableTitle>AI Inspector</DraggableTitle>
          </div>
          <DraggableControls />
        </DraggableHeader>

        <DraggableBody className="flex flex-col gap-2.5">
          {messages.map((msg, idx) => (
            <div
              key={idx}
              className="p-2.5 rounded-lg border border-border/40 bg-muted/30 font-mono text-[11px] leading-relaxed"
            >
              {msg}
            </div>
          ))}
        </DraggableBody>

        <DraggableFooter>
          <form onSubmit={handleSendMessage} className="flex gap-1.5 w-full">
            <Input
              size="sm"
              value={inputText}
              onChange={(e) => setInputText(e.target.value)}
              placeholder="Ask AI assistant..."
              aria-label="Message"
            />
            <Button type="submit" size="icon-sm" aria-label="Send">
              <Send aria-hidden />
            </Button>
          </form>
        </DraggableFooter>
      </Draggable>
    </div>
  );
}

export default DraggableExample;
```

## API Reference

### Draggable

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bounds` | `"none" \| "viewport" \| "parent"` | `viewport` | What the panel can't be moved out of: the `viewport`, its `parent` element, or `none` to move freely. |
| `defaultHeight` | `number` | `300` | The panel's starting height, in pixels. |
| `defaultOpen` | `boolean` | `true` | Whether the panel is shown at first, when it isn't controlled. |
| `defaultWidth` | `number` | `360` | The panel's starting width, in pixels. |
| `defaultX` | `number` | `40` | The panel's starting distance from the left edge of the viewport, in pixels. |
| `defaultY` | `number` | `40` | The panel's starting distance from the top edge of the viewport, in pixels. |
| `isDraggable` | `boolean` | `true` | Whether the panel can be moved, by its header or handle. |
| `isResizable` | `boolean` | `true` | Whether the panel can be resized from its corner. |
| `maxHeight` | `number` | `600` | The tallest the panel can be resized to, in pixels. |
| `maxWidth` | `number` | `800` | The widest the panel can be resized to, in pixels. |
| `minHeight` | `number` | `160` | The shortest the panel can be resized to, in pixels. |
| `minWidth` | `number` | `240` | The narrowest the panel can be resized to, in pixels. |
| `onOpenChange` | `((open: boolean) => void)` | – | Called with `false` when the panel's close button is pressed. |
| `open` | `boolean` | – | Whether the panel is shown. Use with `onOpenChange` to control it. |
| `variant` | `"default" \| "flat" \| "expressive"` | `default` | The visual style of the component. |

### DraggableBody

Accepts `render`, plus every native attribute of the element it renders.

### DraggableControls

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `maximizeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `minimizeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `restoreIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### DraggableFooter

Accepts `render`, plus every native attribute of the element it renders.

### DraggableHandle

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### DraggableHeader

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### DraggableResizeHandle

Accepts `render`, plus every native attribute of the element it renders.

### DraggableTitle

Accepts `render`, plus every native attribute of the element it renders.

---

# Drawer

> A panel that slides in from an edge of the screen.

Source: https://ui.xiod.dev/docs/components/drawer

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerClose,
  DrawerSwipeArea,
  DrawerBackdrop,
  DrawerViewport,
  DrawerPopup,
  DrawerHeader,
  DrawerFooter,
  DrawerTitle,
  DrawerDescription,
  DrawerPanel,
  DrawerBar,
  DrawerMenu,
  DrawerMenuItem,
  DrawerMenuSeparator,
  DrawerMenuGroup,
  DrawerMenuGroupLabel,
  DrawerMenuTrigger,
  DrawerMenuCheckboxItem,
  DrawerMenuRadioGroup,
  DrawerMenuRadioItem,
  DrawerPortal,
  DrawerContent,
  DrawerCreateHandle
} from "xiod-ui/drawer";
```

Anatomy:

```tsx
<Drawer>
  <DrawerTrigger />
  <DrawerPopup>
    <DrawerHeader>
      <DrawerTitle />
      <DrawerDescription />
    </DrawerHeader>
    <DrawerFooter>
      <DrawerClose />
    </DrawerFooter>
  </DrawerPopup>
</Drawer>
```

## Example

```tsx
import { Button } from "xiod-ui/button";
import {
  Drawer,
  DrawerClose,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerPopup,
  DrawerTitle,
  DrawerTrigger,
} from "xiod-ui/drawer";

export default function DrawerExample() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline" />}>
        Open drawer
      </DrawerTrigger>
      <DrawerPopup showBar>
        <DrawerHeader className="text-center">
          <DrawerTitle>Notifications</DrawerTitle>
          <DrawerDescription>
            This is the description of the drawer.
          </DrawerDescription>
        </DrawerHeader>
        <DrawerFooter
          className="justify-center sm:justify-center"
          variant="bare"
        >
          <DrawerClose render={<Button variant="outline" />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerPopup>
    </Drawer>
  );
}
```

## API Reference

### Drawer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<DrawerRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the drawer. Call this after any externally controlled closing animation finishes. - `close`: Closes the drawer imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<unknown>` | – | The content of the drawer. |
| `defaultOpen` | `boolean` | `false` | Whether the drawer is initially open. To render a controlled drawer, use the `open` prop instead. |
| `defaultSnapPoint` | `DrawerSnapPoint \| null` | – | The initial snap point value when uncontrolled. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the drawer is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open drawer. |
| `disablePointerDismissal` | `boolean` | `false` | Whether to prevent the drawer from closing on outside presses. For non-modal drawers, this also prevents the drawer from closing when focus moves outside of it. |
| `handle` | `DrawerHandle<unknown>` | – | A handle to associate the drawer with a trigger. If specified, allows detached triggers to control the drawer's open state. Can be created with the Drawer.createHandle() method. |
| `modal` | `boolean \| "trap-focus"` | `true` | Determines if the drawer enters a modal state when open. - `true`: user interaction is limited to just the drawer: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the drawer, but document page scroll is not locked and pointer interactions outside of it remain enabled. |
| `onOpenChange` | `((open: boolean, eventDetails: DrawerRootChangeEventDetails) => void)` | – | Event handler called when the drawer is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the drawer is opened or closed. |
| `onSnapPointChange` | `((snapPoint: DrawerSnapPoint \| null, eventDetails: DrawerRootSnapPointChangeEventDetails) => void)` | – | Callback fired when the snap point changes. |
| `open` | `boolean` | – | Whether the drawer is currently open. |
| `position` | `"top" \| "bottom" \| "left" \| "right"` | `bottom` | The edge of the screen the drawer slides in from. Its parts follow it unless they set their own `position`. Swipe direction follows it too, unless `swipeDirection` is set. |
| `snapPoint` | `DrawerSnapPoint \| null` | – | The currently active snap point. Use with `onSnapPointChange` to control the snap point. |
| `snapPoints` | `DrawerSnapPoint[]` | – | Snap points used to position the drawer. Use numbers between 0 and 1 to represent fractions of the viewport height, numbers greater than 1 as pixel values, or strings in `px`/`rem` units (for example, `'148px'` or `'30rem'`). |
| `snapToSequentialPoints` | `boolean` | `false` | Disables velocity-based snap skipping so drag distance determines the next snap point. |
| `swipeDirection` | `"left" \| "right" \| "up" \| "down"` | `'down'` | The swipe direction used to dismiss the drawer. |
| `triggerId` | `string \| null` | – | ID of the trigger that the drawer is associated with. This is useful in conjunction with the `open` prop to create a controlled drawer. There's no need to specify this prop when the drawer is uncontrolled (that is, when the `open` prop is not set). |

### DrawerTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DrawerHandle<unknown>` | – | A handle to associate the trigger with a drawer. Can be created with the Drawer.createHandle() method. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for drawers in controlled mode (with the Drawer.Root `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `payload` | `unknown` | – | A payload to pass to the drawer when it is opened. |

### DrawerClose

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### DrawerSwipeArea

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the swipe area is disabled. |
| `position` | `"top" \| "bottom" \| "left" \| "right"` | – | The edge the swipe area sits along. Defaults to the `Drawer`'s `position`. |
| `swipeDirection` | `"left" \| "right" \| "up" \| "down"` | – | The swipe direction that opens the drawer. Defaults to the opposite of `Drawer.Root` `swipeDirection`. |

### DrawerBackdrop

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `forceRender` | `boolean` | `false` | Whether the backdrop is forced to render even when nested. |

### DrawerViewport

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"top" \| "bottom" \| "left" \| "right"` | – | The edge of the screen the popup is laid out against. `DrawerPopup` renders its own viewport, so set this only when composing the parts yourself. |
| `variant` | `"default" \| "straight" \| "inset"` | `default` | The popup's shape: `default` rounds the corners on the inner edge, `straight` keeps them square, and `inset` floats the popup away from the screen edges with every corner rounded, from the `sm` breakpoint up. |

### DrawerPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the drawer is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the drawer is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `position` | `"top" \| "bottom" \| "left" \| "right"` | – | The edge the popup slides in from. Defaults to the `Drawer`'s `position`. |
| `showBar` | `boolean` | `false` | Whether to show the grab bar along the popup's inner edge. |
| `showCloseButton` | `boolean` | `false` | Whether to show a close button in the top corner. |
| `variant` | `"default" \| "straight" \| "inset"` | `default` | The popup's shape: `default` rounds the corners on the inner edge, `straight` keeps them square, and `inset` floats the popup away from the screen edges with every corner rounded, from the `sm` breakpoint up. |

### DrawerHeader

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allowSelection` | `boolean` | `false` | Whether text in the header can be selected with a mouse. When `false`, dragging on it with a mouse swipes the drawer instead. |

### DrawerFooter

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allowSelection` | `boolean` | `true` | Whether text in the footer can be selected with a mouse. When `false`, dragging on it with a mouse swipes the drawer instead. |
| `variant` | `"default" \| "bare"` | `default` | The popup's shape: `default` rounds the corners on the inner edge, `straight` keeps them square, and `inset` floats the popup away from the screen edges with every corner rounded, from the `sm` breakpoint up. |

### DrawerTitle

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### DrawerDescription

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### DrawerPanel

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allowSelection` | `boolean` | `true` | Whether text in the panel can be selected with a mouse. When `false`, dragging on it with a mouse swipes the drawer instead. |
| `scrollable` | `boolean` | `true` | Whether the panel scrolls its content when it doesn't fit. |
| `scrollFade` | `boolean` | `true` | Whether the content fades out at an edge that has more to scroll to. |

### DrawerBar

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"top" \| "bottom" \| "left" \| "right"` | – | The edge the drawer slides in from, which decides where the bar sits and which way it points. Defaults to the `Drawer`'s `position`. |

### DrawerMenu

Accepts `render`, plus every native `<nav>` attribute.

### DrawerMenuItem

Accepts `render`, plus every native `<button>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `default` | The popup's shape: `default` rounds the corners on the inner edge, `straight` keeps them square, and `inset` floats the popup away from the screen edges with every corner rounded, from the `sm` breakpoint up. |

### DrawerMenuSeparator

Accepts `render`, plus every native `<div>` attribute.

### DrawerMenuGroup

Accepts `render`, plus every native `<div>` attribute.

### DrawerMenuGroupLabel

Accepts `render`, plus every native `<div>` attribute.

### DrawerMenuTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DrawerHandle<unknown>` | – | A handle to associate the trigger with a drawer. Can be created with the Drawer.createHandle() method. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for drawers in controlled mode (with the Drawer.Root `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `payload` | `unknown` | – | A payload to pass to the drawer when it is opened. |

### DrawerMenuCheckboxItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | `undefined` | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
| `defaultChecked` | `boolean` | `false` | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
| `id` | `string` | – | The id of the input element. |
| `indeterminate` | `boolean` | `false` | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden `<input>` element. |
| `name` | `string` | `undefined` | Identifies the field when a form is submitted. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void)` | – | Event handler called when the checkbox is ticked or unticked. |
| `parent` | `boolean` | `false` | Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group). |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to tick or untick the checkbox. |
| `required` | `boolean` | `false` | Whether the user must tick the checkbox before submitting a form. |
| `uncheckedValue` | `string` | – | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |
| `value` | `string` | – | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
| `variant` | `"switch" \| "default"` | `default` | The popup's shape: `default` rounds the corners on the inner edge, `straight` keeps them square, and `inset` floats the popup away from the screen edges with every corner rounded, from the `sm` breakpoint up. |

### DrawerMenuRadioGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `any` | – | The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onValueChange` | `((value: Value, eventDetails: RadioGroup.ChangeEventDetails) => void)` | – | Callback fired when the value changes. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to select a different radio button in the group. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `value` | `any` | – | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |

### DrawerMenuRadioItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | The unique identifying value of the radio in a group. |
| `disabled` | `boolean` | – | Whether the component should ignore user interaction. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `readOnly` | `boolean` | – | Whether the user should be unable to select the radio button. |
| `required` | `boolean` | – | Whether the user must choose a value before submitting a form. |

### DrawerPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### DrawerContent

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### Helpers

`DrawerCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Empty

> A placeholder for a view with no content yet, with room for an icon, message and action.

Source: https://ui.xiod.dev/docs/components/empty

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle
} from "xiod-ui/empty";
```

Anatomy:

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia />
    <EmptyTitle />
    <EmptyDescription />
  </EmptyHeader>
  <EmptyContent />
</Empty>
```

## Example

```tsx
import { Book as BookIcon, Route as RouteIcon } from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "xiod-ui/empty";

export default function EmptyExample() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <RouteIcon />
        </EmptyMedia>
        <EmptyTitle>No upcoming meetings</EmptyTitle>
        <EmptyDescription>Create a meeting to get started.</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <div className="flex gap-2">
          <Button size="sm">Create meeting</Button>
          <Button size="sm" variant="outline">
            <BookIcon />
            View docs
          </Button>
        </div>
      </EmptyContent>
    </Empty>
  );
}
```

## API Reference

### Empty

Accepts `render`, plus every native `<div>` attribute.

### EmptyContent

Accepts `render`, plus every native `<div>` attribute.

### EmptyDescription

Accepts `render`, plus every native `<p>` attribute.

### EmptyHeader

Accepts `render`, plus every native `<div>` attribute.

### EmptyMedia

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "icon"` | `default` | The visual style of the component. |

### EmptyTitle

Accepts `render`, plus every native `<div>` attribute.

---

# Field

> A form field that ties a label, control, description and validation message together.

Source: https://ui.xiod.dev/docs/components/field

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldItem,
  FieldLabel,
  FieldValidity
} from "xiod-ui/field";
```

Anatomy:

```tsx
<Field>
  <FieldLabel />
  <FieldDescription />
</Field>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Field, FieldDescription, FieldError, FieldLabel } from "xiod-ui/field";
import { Input } from "xiod-ui/input";

export default function FieldExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Default */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Default
        </Badge>
        <Field className="w-full">
          <FieldLabel>Workspace</FieldLabel>
          <Input placeholder="autobot-city" type="text" />
        </Field>
      </div>

      {/* Description */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Description
        </Badge>
        <Field className="w-full">
          <FieldLabel>Display name</FieldLabel>
          <Input placeholder="Optimus Prime" type="text" />
          <FieldDescription>Visible on your profile.</FieldDescription>
        </Field>
      </div>

      {/* Invalid */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Invalid
        </Badge>
        <Field className="w-full" invalid>
          <FieldLabel>Subdomain</FieldLabel>
          <Input defaultValue="my workspace" type="text" />
          <FieldError match>Subdomains cannot contain spaces.</FieldError>
        </Field>
      </div>

      {/* Disabled */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Disabled
        </Badge>
        <Field className="w-full" disabled>
          <FieldLabel>Plan</FieldLabel>
          <Input defaultValue="Enterprise" type="text" />
          <FieldDescription>Contact support to change plans.</FieldDescription>
        </Field>
      </div>
    </div>
  );
}
```

## API Reference

### Field

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<FieldRootActions \| null>` | – | A ref to imperative actions. - `validate`: Validates the field when called. |
| `dirty` | `boolean` | – | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component. |
| `invalid` | `boolean` | – | Whether the field is invalid. Useful when the field state is controlled by an external library. |
| `name` | `string` | – | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component. |
| `touched` | `boolean` | – | Whether the field has been touched. Useful when the field state is controlled by an external library. |
| `validate` | `((value: unknown, formValues: Form.Values) => string \| string[] \| null \| void \| Promise<string \| string[] \| null \| void>)` | – | A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, `null`, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using `validationMode="onSubmit"`. |
| `validationDebounceTime` | `number` | `0` | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. |
| `validationMode` | `"onBlur" \| "onChange" \| "onSubmit"` | `'onSubmit'` | Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`. - `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission. - `onBlur`: triggers validation when the control loses focus. - `onChange`: triggers validation on every change to the control value. |

### FieldControl

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The value the input starts with, when it isn't controlled. |
| `onValueChange` | `((value: string, eventDetails: FieldControl.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |

### FieldDescription

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### FieldError

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `match` | `boolean \| keyof ValidityState` | – | Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying `true` will always show the error message, and lets external libraries control the visibility. |

### FieldItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the wrapped control should ignore user interaction. The `disabled` prop on `<Field.Root>` takes precedence over this. |

### FieldLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeLabel` | `boolean` | `true` | Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (for example, `<div>`). This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button. |

### FieldValidity

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `(state: FieldValidityState) => ReactNode` | – | A function that accepts the field validity state as an argument. ```jsx <Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity> ``` |

---

# Fieldset

> Groups related form fields under a shared legend.

Source: https://ui.xiod.dev/docs/components/fieldset

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Fieldset, FieldsetLegend } from "xiod-ui/fieldset";
```

Anatomy:

```tsx
<Fieldset>
  <FieldsetLegend />
</Fieldset>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Field, FieldDescription, FieldLabel } from "xiod-ui/field";
import { Fieldset, FieldsetLegend } from "xiod-ui/fieldset";
import { Input } from "xiod-ui/input";

export default function FieldsetExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Default */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Default
        </Badge>
        <Fieldset className="w-full">
          <FieldsetLegend>Billing details</FieldsetLegend>
          <Field>
            <FieldLabel>Company</FieldLabel>
            <Input placeholder="Cybertron Industries" type="text" />
            <FieldDescription>Appears on every invoice.</FieldDescription>
          </Field>
          <Field>
            <FieldLabel>Tax ID</FieldLabel>
            <Input placeholder="GB123456789" type="text" />
          </Field>
        </Fieldset>
      </div>

      {/* Disabled */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Disabled
        </Badge>
        <Fieldset className="w-full" disabled>
          <FieldsetLegend>Legacy billing</FieldsetLegend>
          <Field>
            <FieldLabel>Company</FieldLabel>
            <Input defaultValue="Cybertron Industries" type="text" />
          </Field>
          <Field>
            <FieldLabel>Tax ID</FieldLabel>
            <Input defaultValue="GB123456789" type="text" />
            <FieldDescription>
              Disabling the fieldset disables every field inside it.
            </FieldDescription>
          </Field>
        </Fieldset>
      </div>
    </div>
  );
}
```

## API Reference

### Fieldset

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### FieldsetLegend

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

---

# File Upload

> A drop zone and file picker with type and size limits, progress and a file list.

Source: https://ui.xiod.dev/docs/components/file-upload

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  FileUpload,
  FileUploadTrigger,
  FileUploadInput,
  FileUploadList,
  FileUploadItem,
  FileUploadItemIcon,
  FileUploadItemName,
  FileUploadItemSize,
  FileUploadItemProgress,
  FileUploadItemStatus,
  FileUploadItemRemove,
  Attachment,
  AttachmentMedia,
  AttachmentContent,
  AttachmentTitle,
  AttachmentDescription,
  AttachmentActions,
  AttachmentAction,
  AttachmentTrigger,
  AttachmentGroup
} from "xiod-ui/file-upload";
```

Anatomy:

```tsx
<FileUpload>
  <FileUploadTrigger>
    <FileUploadInput />
  </FileUploadTrigger>
  <AttachmentGroup>
    <Attachment>
      <AttachmentMedia />
      <AttachmentContent>
        <AttachmentTitle />
        <AttachmentDescription />
      </AttachmentContent>
      <AttachmentActions>
        <AttachmentAction />
      </AttachmentActions>
    </Attachment>
  </AttachmentGroup>
</FileUpload>
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  Attachment as XiodPaperclip,
  Cancel as XiodX,
  CloudUpload as XiodUploadCloud,
  Delete as XiodTrash2,
  File as XiodFile,
  FileAudio as XiodFileAudio,
  FileImage as XiodFileImage,
  FileVideo as XiodFileVideo,
} from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
  type FileItem,
  FileUpload,
  FileUploadInput,
  FileUploadTrigger,
  formatFileSize,
} from "xiod-ui/file-upload";
import { toastManager } from "xiod-ui/toast";

const FileImagePreview = ({ file }: { file: File }) => {
  const [url, setUrl] = React.useState<string>("");

  React.useEffect(() => {
    const objectUrl = URL.createObjectURL(file);
    // Synchronous state update is required to pair the created object URL with cleanup revocation.
    // oxlint-disable-next-line react/set-state-in-effect
    setUrl(objectUrl);
    return () => URL.revokeObjectURL(objectUrl);
  }, [file]);

  if (!url) return null;
  // A local object URL has no origin for next/image to fetch and optimize.
  // oxlint-disable-next-line next/no-img-element
  return <img src={url} alt={file.name} />;
};

const getFileIcon = (file: File) => {
  const type = file.type.toLowerCase();
  if (type.startsWith("image/")) return <XiodFileImage className="size-4.5" />;
  if (type.startsWith("video/")) return <XiodFileVideo className="size-4.5" />;
  if (type.startsWith("audio/")) return <XiodFileAudio className="size-4.5" />;
  return <XiodFile className="size-4.5 text-muted-foreground" />;
};

const attachmentState = (item: FileItem) =>
  item.status === "success" ? "done" : item.status;

/** Steps freshly queued files to `success` so the progress states are visible. */
function useUploadQueue() {
  const [files, setFiles] = React.useState<FileItem[]>([]);

  const onFilesAdded = React.useCallback(() => {
    setFiles((current) =>
      current.map((item) =>
        item.status === "idle" ? { ...item, status: "uploading" } : item,
      ),
    );
  }, []);

  React.useEffect(() => {
    if (!files.some((item) => item.status === "uploading")) return;
    const timer = setInterval(() => {
      setFiles((current) =>
        current.map((item) => {
          if (item.status !== "uploading") return item;
          const progress = Math.min(100, item.progress + 20);
          return progress === 100
            ? { ...item, progress, status: "success" }
            : { ...item, progress };
        }),
      );
    }, 300);
    return () => clearInterval(timer);
  }, [files]);

  const remove = React.useCallback((id: string) => {
    setFiles((current) => current.filter((item) => item.id !== id));
  }, []);

  return { files, setFiles, onFilesAdded, remove };
}

export default function FileUploadExample() {
  const documents = useUploadQueue();
  const attachments = useUploadQueue();

  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-12">
      {/* Documents */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Documents
        </Badge>
        <FileUpload
          className="w-full"
          files={documents.files}
          onFilesChange={documents.setFiles}
          onFilesAdded={documents.onFilesAdded}
          onFilesRejected={(rejected) =>
            toastManager.add({
              type: "warning",
              title: "Up to 5 documents",
              description: `${rejected.length} file${rejected.length === 1 ? " was" : "s were"} left out.`,
            })
          }
          maxFiles={5}
          maxSizeMB={5}
          accept="image/*,application/pdf,.zip"
        >
          <FileUploadTrigger>
            <FileUploadInput />
            <div className="mb-4 flex size-14 items-center justify-center rounded-full bg-primary/10 text-primary">
              <XiodUploadCloud className="size-7" />
            </div>
            <h3 className="mb-1 text-base font-semibold text-foreground">
              Click to upload{" "}
              <span className="font-normal text-muted-foreground">
                or drag and drop
              </span>
            </h3>
            <p className="text-xs text-muted-foreground">
              PDF, PNG, JPG, GIF or ZIP (max. 5MB)
            </p>
          </FileUploadTrigger>

          {documents.files.length > 0 && (
            <div className="mt-6 grid gap-3">
              {documents.files.map((item) => (
                <Attachment
                  key={item.id}
                  state={attachmentState(item)}
                  className="w-full justify-between"
                >
                  <div className="flex min-w-0 flex-1 items-center gap-3">
                    <AttachmentMedia
                      variant={
                        item.file.type.startsWith("image/") ? "image" : "icon"
                      }
                    >
                      {item.file.type.startsWith("image/") ? (
                        <FileImagePreview file={item.file} />
                      ) : (
                        getFileIcon(item.file)
                      )}
                    </AttachmentMedia>
                    <AttachmentContent>
                      <AttachmentTitle>{item.file.name}</AttachmentTitle>
                      <AttachmentDescription>
                        {item.status === "uploading"
                          ? `Uploading… ${Math.round(item.progress)}%`
                          : item.errorMessage || formatFileSize(item.file.size)}
                      </AttachmentDescription>
                    </AttachmentContent>
                  </div>
                  <AttachmentActions>
                    <AttachmentAction
                      variant="ghost"
                      onClick={() => documents.remove(item.id)}
                    >
                      <XiodTrash2 className="size-4 text-muted-foreground" />
                    </AttachmentAction>
                  </AttachmentActions>
                </Attachment>
              ))}
            </div>
          )}
        </FileUpload>
      </div>

      {/* Attachments */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Attachments
        </Badge>
        <FileUpload
          className="w-full"
          files={attachments.files}
          onFilesChange={attachments.setFiles}
          onFilesAdded={attachments.onFilesAdded}
          maxFiles={10}
          accept="image/*,application/pdf"
        >
          <div className="flex flex-col gap-4">
            <FileUploadTrigger className="rounded-xl border-dashed py-6">
              <FileUploadInput />
              <XiodPaperclip className="mb-2 size-6 text-muted-foreground" />
              <span className="text-sm font-semibold text-foreground">
                Attach files to message
              </span>
              <span className="text-xs text-muted-foreground">
                Images or documents
              </span>
            </FileUploadTrigger>

            {attachments.files.length > 0 && (
              <AttachmentGroup className="w-full">
                {attachments.files.map((item) => (
                  <Attachment
                    key={item.id}
                    orientation="vertical"
                    size="sm"
                    state={attachmentState(item)}
                    className="w-28"
                  >
                    <AttachmentMedia
                      variant={
                        item.file.type.startsWith("image/") ? "image" : "icon"
                      }
                    >
                      {item.file.type.startsWith("image/") ? (
                        <FileImagePreview file={item.file} />
                      ) : (
                        getFileIcon(item.file)
                      )}
                    </AttachmentMedia>
                    <AttachmentContent>
                      <AttachmentTitle className="truncate text-center">
                        {item.file.name}
                      </AttachmentTitle>
                      <AttachmentDescription className="text-center font-normal">
                        {item.status === "uploading"
                          ? `${Math.round(item.progress)}%`
                          : formatFileSize(item.file.size)}
                      </AttachmentDescription>
                    </AttachmentContent>
                    <AttachmentActions>
                      <AttachmentAction
                        variant="ghost"
                        className="rounded-full bg-card/80"
                        onClick={() => attachments.remove(item.id)}
                      >
                        <XiodX className="size-3" />
                      </AttachmentAction>
                    </AttachmentActions>
                  </Attachment>
                ))}
              </AttachmentGroup>
            )}
          </div>
        </FileUpload>
      </div>
    </div>
  );
}
```

## API Reference

### FileUpload

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string` | – | The file types allowed, in the format of an input's `accept`: MIME types, wildcards such as `image/*`, or extensions such as `.pdf`, separated by commas. Other files are added with an error. |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `files` | `FileItem[]` | – | The files in the list. Use with `onFilesChange` to control them, for example to update each file's `progress` and `status` while it uploads. |
| `maxFiles` | `number` | `5` | The most files the list can hold. Files past the limit are left out and passed to `onFilesRejected`. |
| `maxSizeMB` | `number` | `10` | The largest file size allowed, in megabytes. Larger files are added with an error. |
| `onFileRemove` | `((id: string) => void)` | – | Called with a file's id when it is removed from the list. |
| `onFilesAdded` | `((files: File[]) => void)` | – | Called with the files the user just picked or dropped, including ones marked with an error for their size or type. Start uploads from here. |
| `onFilesChange` | `((files: FileItem[]) => void)` | – | Called with the new list whenever files are added or removed. |
| `onFilesRejected` | `((files: File[]) => void)` | – | Called with the files left out because the list already holds `maxFiles`. |

### FileUploadTrigger

Accepts `render`, plus every native `<div>` attribute.

### FileUploadInput

every native `<input>` attribute.

### FileUploadList

Accepts `render`, plus every native `<div>` attribute.

### FileUploadItem

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fileItem` (required) | `FileItem` | – | The file this item shows, from the `FileUpload`'s list. |

### FileUploadItemIcon

Accepts `render`, plus every native `<div>` attribute.

### FileUploadItemName

Accepts `render`, plus every native `<p>` attribute.

### FileUploadItemSize

Accepts `render`, plus every native `<span>` attribute.

### FileUploadItemProgress

Accepts `render`, plus every native `<div>` attribute.

### FileUploadItemStatus

Accepts `render`, plus every native `<div>` attribute.

### FileUploadItemRemove

Accepts `render`, plus every native `<button>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### Attachment

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Whether the items are laid out horizontally or vertically. |
| `size` | `"sm" \| "default" \| "xs"` | `default` | The size of the component. |
| `state` | `"done" \| "error" \| "idle" \| "uploading" \| "processing"` | `done` | The attachment's status, which sets its look: `idle` has a dashed border, `uploading` and `processing` pulse, and `error` turns it red. |

### AttachmentMedia

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"image" \| "icon"` | `icon` | The visual style of the component. |

### AttachmentContent

Accepts `render`, plus every native `<div>` attribute.

### AttachmentTitle

Accepts `render`, plus every native `<span>` attribute.

### AttachmentDescription

Accepts `render`, plus every native `<span>` attribute.

### AttachmentActions

Accepts `render`, plus every native `<div>` attribute.

### AttachmentAction

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `icon-xs` | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `icon` | The visual style of the component. |

### AttachmentTrigger

Accepts `render`, plus every native `<button>` attribute.

### AttachmentGroup

Accepts `render`, plus every native `<div>` attribute.

---

# Form

> A form that runs validation and shows each field's errors.

Source: https://ui.xiod.dev/docs/components/form

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Form } from "xiod-ui/form";
```

## Example

```tsx
"use client";

import * as React from "react";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import { Field, FieldError, FieldLabel } from "xiod-ui/field";
import { Form } from "xiod-ui/form";
import { Input } from "xiod-ui/input";

export default function FormExample() {
  const [errors, setErrors] = React.useState<Record<string, string>>({});
  const [status, setStatus] = React.useState<"idle" | "pending" | "sent">(
    "idle",
  );

  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Validation */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Validation
        </Badge>
        <Form className="w-full">
          <Field name="email">
            <FieldLabel>Email</FieldLabel>
            <Input placeholder="you@example.com" required type="email" />
            <FieldError />
          </Field>
          <Field name="workspace">
            <FieldLabel>Workspace</FieldLabel>
            <Input placeholder="autobot-city" required minLength={4} />
            <FieldError />
          </Field>
          <Button type="submit">Create</Button>
        </Form>
      </div>

      {/* Server errors */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Server Errors
        </Badge>
        <Form
          className="w-full"
          errors={errors}
          onSubmit={async (event) => {
            event.preventDefault();
            setErrors({});
            setStatus("pending");
            const email = new FormData(event.currentTarget).get("email");
            await new Promise((resolve) => setTimeout(resolve, 600));
            if (email === "taken@example.com") {
              setErrors({ email: "That address is already registered." });
              setStatus("idle");
              return;
            }
            setStatus("sent");
          }}
        >
          <Field name="email">
            <FieldLabel>Email</FieldLabel>
            <Input
              name="email"
              defaultValue="taken@example.com"
              required
              type="email"
            />
            <FieldError />
          </Field>
          <Button type="submit" disabled={status === "pending"}>
            {status === "sent" ? "Invite sent" : "Send invite"}
          </Button>
        </Form>
      </div>
    </div>
  );
}
```

## API Reference

### Form

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<FormActions \| null>` | – | A ref to imperative actions. - `validate`: Validates all fields when called. Optionally pass a field name to validate a single field. |
| `errors` | `Errors` | – | Validation errors returned externally, typically after submission by a server or a form action. This should be an object where keys correspond to the `name` attribute on `<Field.Root>`, and values correspond to error(s) related to that field. |
| `onFormSubmit` | `((formValues: FormValues, eventDetails: Form.SubmitEventDetails) => void)` | – | Event handler called when the form is submitted. `preventDefault()` is called on the native submit event when used. |
| `validationMode` | `"onBlur" \| "onChange" \| "onSubmit"` | `'onSubmit'` | Determines when the form should be validated. The `validationMode` prop on `<Field.Root>` takes precedence over this. - `onSubmit` (default): validates the field when the form is submitted, afterwards fields will re-validate on change. - `onBlur`: validates a field when it loses focus. - `onChange`: validates the field on every change to its value. |

---

# Frame

> A bordered container with a header, panels and a footer, for grouping cards or content.

Source: https://ui.xiod.dev/docs/components/frame

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Frame,
  FrameDescription,
  FrameFooter,
  FrameHeader,
  FramePanel,
  FrameTitle
} from "xiod-ui/frame";
```

Anatomy:

```tsx
<Frame>
  <FrameHeader>
    <FrameTitle />
    <FrameDescription />
  </FrameHeader>
  <FramePanel />
  <FrameFooter />
</Frame>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import {
  Frame,
  FrameDescription,
  FrameFooter,
  FrameHeader,
  FramePanel,
  FrameTitle,
} from "xiod-ui/frame";
import { Switch } from "xiod-ui/switch";
import { Text } from "xiod-ui/text";

export default function FrameExample() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-10">
      {/* Full */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Full
        </Badge>
        <Frame className="w-full">
          <FrameHeader>
            <FrameTitle>Deployment</FrameTitle>
            <FrameDescription>
              Choose how this project ships to production.
            </FrameDescription>
          </FrameHeader>
          <FramePanel className="flex items-center justify-between">
            <div className="flex flex-col">
              <Text className="text-sm font-medium">Automatic deploys</Text>
              <Text variant="secondary" size="xs">
                Every push to main goes live.
              </Text>
            </div>
            <Switch defaultChecked />
          </FramePanel>
          <FrameFooter className="justify-end">
            <Button size="sm">Save</Button>
          </FrameFooter>
        </Frame>
      </div>

      {/* Header only */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Header
        </Badge>
        <Frame className="w-full">
          <FrameHeader>
            <FrameTitle>Danger zone</FrameTitle>
            <FrameDescription>
              Deleting a project cannot be undone.
            </FrameDescription>
          </FrameHeader>
          <FramePanel>
            <Button variant="destructive" size="sm">
              Delete project
            </Button>
          </FramePanel>
        </Frame>
      </div>

      {/* Panel only */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Panel
        </Badge>
        <Frame className="w-full">
          <FramePanel className="flex flex-col gap-1">
            <Text className="text-sm font-medium">Build cache</Text>
            <Text variant="secondary" size="xs">
              Cleared 4 hours ago.
            </Text>
          </FramePanel>
        </Frame>
      </div>
    </div>
  );
}
```

## API Reference

### Frame

Accepts `render`, plus every native `<div>` attribute.

### FrameDescription

Accepts `render`, plus every native `<div>` attribute.

### FrameFooter

Accepts `render`, plus every native `<footer>` attribute.

### FrameHeader

Accepts `render`, plus every native `<header>` attribute.

### FramePanel

Accepts `render`, plus every native `<div>` attribute.

### FrameTitle

Accepts `render`, plus every native `<div>` attribute.

---

# Gauge

> A semicircular dial that shows a value within a range.

Source: https://ui.xiod.dev/docs/components/gauge

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Gauge } from "xiod-ui/gauge";
```

## Example

```tsx
"use client";

import { useEffect, useState } from "react";
import { Gauge } from "xiod-ui/gauge";

export default function GaugeExample() {
  const [value, setValue] = useState(20);

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((current) =>
        Math.min(100, Math.round(current + Math.random() * 25)),
      );
    }, 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div className="flex flex-col md:flex-row items-center justify-center gap-12 w-full p-12">
      {/* Determinate Gauge (Live) */}
      <div className="flex flex-col items-center gap-6">
        <Gauge value={value} size={140} strokeWidth={14} />
        <span className="text-sm font-medium text-muted-foreground whitespace-nowrap">
          Live Metric
        </span>
      </div>

      {/* Determinate Gauge (Full) */}
      <div className="flex flex-col items-center gap-6">
        <Gauge value={100} size={140} strokeWidth={14} />
        <span className="text-sm font-medium text-muted-foreground whitespace-nowrap">
          Completed State
        </span>
      </div>

      {/* Gauge (Without Value Display) */}
      <div className="flex flex-col items-center gap-6">
        <Gauge value={55} size={140} strokeWidth={14} showValue={false} />
        <span className="text-sm font-medium text-muted-foreground whitespace-nowrap">
          Hidden Label
        </span>
      </div>
    </div>
  );
}
```

## API Reference

### Gauge

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `100` | The maximum progress value. Defaults to 100. |
| `showValue` | `boolean` | `true` | Whether to display the value text in the center. Defaults to true. |
| `size` | `number` | `120` | The size of the gauge (diameter) in pixels. Defaults to 120. |
| `strokeWidth` | `number` | `12` | The stroke width of the SVG circle. Defaults to 12. |
| `value` | `number` | `0` | The progress value (0 to max). |

---

# Grid

> A responsive grid layout with column spans, for dashboards and bento layouts.

Source: https://ui.xiod.dev/docs/components/grid

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Grid, GridItem } from "xiod-ui/grid";
```

Anatomy:

```tsx
<Grid>
  <GridItem />
</Grid>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Grid, GridItem } from "xiod-ui/grid";

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex h-full min-h-16 items-center justify-center rounded-lg border bg-card/40 p-4 text-sm text-muted-foreground">
      {children}
    </div>
  );
}

export default function GridExample() {
  return (
    <div className="flex w-full max-w-2xl flex-col items-center gap-12">
      {/* Columns */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Columns
        </Badge>
        <Grid columns={3} gap="md" className="w-full">
          {Array.from({ length: 6 }, (_, index) => (
            <Cell key={index}>{index + 1}</Cell>
          ))}
        </Grid>
      </div>

      {/* Gap */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Gap
        </Badge>
        <div className="flex w-full flex-col gap-4">
          {(["sm", "md", "xl"] as const).map((gap) => (
            <Grid key={gap} columns={4} gap={gap} className="w-full">
              {Array.from({ length: 4 }, (_, index) => (
                <Cell key={index}>{gap}</Cell>
              ))}
            </Grid>
          ))}
        </div>
      </div>

      {/* Spanning */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Spanning
        </Badge>
        <Grid columns={4} rows={2} gap="md" className="w-full">
          <GridItem colSpan={2} rowSpan={2}>
            <Cell>colSpan 2 · rowSpan 2</Cell>
          </GridItem>
          <GridItem>
            <Cell>auto</Cell>
          </GridItem>
          <GridItem>
            <Cell>auto</Cell>
          </GridItem>
          <GridItem colSpan={2}>
            <Cell>colSpan 2</Cell>
          </GridItem>
        </Grid>
      </div>

      {/* Placement */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Placement
        </Badge>
        <Grid columns={4} gap="md" className="w-full">
          <GridItem colStart={2} colSpan={2}>
            <Cell>colStart 2</Cell>
          </GridItem>
          <GridItem colStart={1}>
            <Cell>colStart 1</Cell>
          </GridItem>
          <GridItem colStart={4}>
            <Cell>colStart 4</Cell>
          </GridItem>
        </Grid>
      </div>
    </div>
  );
}
```

## API Reference

### Grid

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end" \| "stretch" \| "baseline"` | – | How items line up vertically within their cells. |
| `columns` | `"none" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| "subgrid" \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` | – | The number of equal columns. `subgrid` lines up with the columns of a parent grid. |
| `flow` | `"col" \| "row" \| "dense" \| "row-dense" \| "col-dense"` | – | How items fill the grid: along rows or columns. The `dense` options fill earlier gaps with later, smaller items. |
| `gap` | `"base" \| "none" \| "sm" \| "md" \| "lg" \| "xl"` | `base` | The space between rows and columns. `base` is 1rem on phones and 1.5rem from the `sm` breakpoint up. |
| `justify` | `"center" \| "start" \| "end" \| "stretch" \| "between"` | – | How items line up horizontally within their cells. `between` spreads the columns out with the space between them. |
| `rows` | `"none" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| "subgrid" \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` | – | The number of equal rows. `subgrid` lines up with the rows of a parent grid. |

### GridItem

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colEnd` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | – | The column line the item ends at, counting from 1 at the left edge. |
| `colSpan` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| "auto" \| "full"` | – | How many columns the item spans. `full` spans every column. |
| `colStart` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | – | The column line the item starts at, counting from 1 at the left edge. |
| `rowEnd` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | – | The row line the item ends at, counting from 1 at the top. |
| `rowSpan` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| "auto" \| "full"` | – | How many rows the item spans. `full` spans every row. |
| `rowStart` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | – | The row line the item starts at, counting from 1 at the top. |

---

# Group

> Joins inputs, buttons and text into one attached segment.

Source: https://ui.xiod.dev/docs/components/group

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Group, GroupSeparator, GroupText } from "xiod-ui/group";
```

Anatomy:

```tsx
<Group>
  <GroupSeparator />
</Group>
```

## Example

```tsx
import {
  Archive as ArchiveIcon,
  Edit as EditIcon,
  Ellipsis as EllipsisIcon,
  Files as FilesIcon,
  Filmstrip as FilmIcon,
  Share as ShareIcon,
  Delete as TrashIcon,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import { Group, GroupSeparator } from "xiod-ui/group";
import { Menu, MenuItem, MenuPopup, MenuTrigger } from "xiod-ui/menu";

export default function GroupExample() {
  return (
    <Group aria-label="File actions">
      <Button variant="outline">
        <FilesIcon aria-hidden="true" />
        Files
      </Button>
      <GroupSeparator />
      <Button variant="outline">
        <FilmIcon aria-hidden="true" />
        Media
      </Button>
      <GroupSeparator />
      <Menu>
        <MenuTrigger
          render={<Button aria-label="Menu" size="icon" variant="outline" />}
        >
          <EllipsisIcon className="size-4" />
        </MenuTrigger>
        <MenuPopup align="end">
          <MenuItem>
            <EditIcon aria-hidden="true" />
            Edit
          </MenuItem>
          <MenuItem>
            <ArchiveIcon aria-hidden="true" />
            Archive
          </MenuItem>
          <MenuItem>
            <ShareIcon aria-hidden="true" />
            Share
          </MenuItem>
          <MenuItem variant="destructive">
            <TrashIcon aria-hidden="true" />
            Delete
          </MenuItem>
        </MenuPopup>
      </Menu>
    </Group>
  );
}
```

## API Reference

### Group

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Whether the items are laid out horizontally or vertically. |

### GroupSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### GroupText

Accepts `render`, plus every native `<div>` attribute.

---

# Input

> A text input field.

Source: https://ui.xiod.dev/docs/components/input

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Input } from "xiod-ui/input";
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Input } from "xiod-ui/input";

export default function InputExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Sizes */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Sizes
        </Badge>
        <div className="flex w-full flex-col gap-3">
          {(["sm", "default", "lg"] as const).map((size) => (
            <Input
              key={size}
              size={size}
              aria-label={`Size ${size}`}
              placeholder={size}
              type="text"
            />
          ))}
        </div>
      </div>

      {/* Types */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Types
        </Badge>
        <div className="flex w-full flex-col gap-3">
          <Input
            aria-label="Email"
            placeholder="you@example.com"
            type="email"
          />
          <Input aria-label="Password" placeholder="Password" type="password" />
          <Input aria-label="Amount" placeholder="0" type="number" />
        </div>
      </div>

      {/* States */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          States
        </Badge>
        <div className="flex w-full flex-col gap-3">
          <Input aria-label="Read only" defaultValue="Read only" readOnly />
          <Input aria-label="Disabled" defaultValue="Disabled" disabled />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Input

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `nativeInput` | `boolean` | `false` | Whether to render a plain `<input>` instead of Base UI's `Input`. A plain input doesn't register with a surrounding `Field`. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `unstyled` | `boolean` | `false` | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

---

# Input Group

> An input with icons, text or buttons attached inside its border.

Source: https://ui.xiod.dev/docs/components/input-group

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea
} from "xiod-ui/input-group";
```

Anatomy:

```tsx
<InputGroup>
  <InputGroupAddon>
    <InputGroupText />
  </InputGroupAddon>
  <InputGroupInput />
</InputGroup>
```

## Example

```tsx
import { CreditCard, Search as SearchIcon, Sent as SendIcon } from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "xiod-ui/input-group";

export default function InputGroupExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Icons */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Icons
        </Badge>
        <div className="flex w-full flex-col gap-3">
          <InputGroup>
            <InputGroupAddon>
              <SearchIcon aria-hidden="true" />
            </InputGroupAddon>
            <InputGroupInput
              aria-label="Search"
              placeholder="Search"
              type="search"
            />
          </InputGroup>
          <InputGroup>
            <InputGroupInput
              aria-label="Card number"
              placeholder="Card number"
              type="text"
            />
            <InputGroupAddon align="inline-end">
              <CreditCard aria-hidden="true" />
            </InputGroupAddon>
          </InputGroup>
        </div>
      </div>

      {/* Text */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Text
        </Badge>
        <div className="flex w-full flex-col gap-3">
          <InputGroup>
            <InputGroupAddon>
              <InputGroupText>https://</InputGroupText>
            </InputGroupAddon>
            <InputGroupInput aria-label="Domain" placeholder="xiod.dev" />
          </InputGroup>
          <InputGroup>
            <InputGroupInput aria-label="Workspace" placeholder="workspace" />
            <InputGroupAddon align="inline-end">
              <InputGroupText>.xiod.dev</InputGroupText>
            </InputGroupAddon>
          </InputGroup>
        </div>
      </div>

      {/* Textarea */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Textarea
        </Badge>
        <InputGroup className="w-full">
          <InputGroupTextarea
            aria-label="Message"
            placeholder="Write a message…"
            rows={3}
          />
          <InputGroupAddon align="block-end">
            <Button size="xs" className="ms-auto">
              <SendIcon aria-hidden="true" />
              Send
            </Button>
          </InputGroupAddon>
        </InputGroup>
      </div>
    </div>
  );
}
```

## API Reference

### InputGroup

Accepts `render`, plus every native `<div>` attribute.

### InputGroupAddon

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"inline-end" \| "inline-start" \| "block-end" \| "block-start"` | `inline-start` | Where the addon sits: before or after the text on the same line (`inline-*`), or on its own row above or below it (`block-*`). |

### InputGroupInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `nativeInput` | `boolean` | – | Whether to render a plain `<input>` instead of Base UI's `Input`. A plain input doesn't register with a surrounding `Field`. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |
| `unstyled` | `boolean` | – | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### InputGroupText

Accepts `render`, plus every native `<span>` attribute.

### InputGroupTextarea

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number \| "sm" \| "lg" \| "default"` | – | The size of the component. |
| `unstyled` | `boolean` | – | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |

---

# Input OTP

> A one-time code input with a separate box for each character.

Source: https://ui.xiod.dev/docs/components/input-otp

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  InputOtp,
  InputOtpGroup,
  InputOtpInput,
  InputOtpSeparator
} from "xiod-ui/input-otp";
```

Anatomy:

```tsx
<InputOtp>
  <InputOtpGroup>
    <InputOtpInput />
  </InputOtpGroup>
  <InputOtpSeparator />
</InputOtp>
```

## Example

```tsx
"use client";

import {
  InputOtp,
  InputOtpGroup,
  InputOtpInput,
  InputOtpSeparator,
} from "xiod-ui/input-otp";

export function InputOtpExample() {
  return (
    <div className="flex flex-col items-center justify-center gap-6 p-6 sm:p-12">
      <InputOtp length={6}>
        <InputOtpGroup>
          <InputOtpInput aria-label="Character 1 of 6" />
          <InputOtpInput aria-label="Character 2 of 6" />
          <InputOtpInput aria-label="Character 3 of 6" />
        </InputOtpGroup>
        <InputOtpSeparator />
        <InputOtpGroup>
          <InputOtpInput aria-label="Character 4 of 6" />
          <InputOtpInput aria-label="Character 5 of 6" />
          <InputOtpInput aria-label="Character 6 of 6" />
        </InputOtpGroup>
      </InputOtp>
    </div>
  );
}

export default InputOtpExample;
```

## API Reference

### InputOtp

Also exported as `OTPField`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` (required) | `number` | – | The number of OTP input slots. Required so the root can clamp values, detect completion, and generate consistent validation markup before all slots hydrate. |
| `autoComplete` | `string` | `'one-time-code'` | The input autocomplete attribute. Applied to the first slot and hidden validation input. |
| `autoSubmit` | `boolean` | `false` | Whether to submit the owning form when the OTP becomes complete. |
| `defaultValue` | `string` | – | The uncontrolled OTP value when the component is initially rendered. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | A string specifying the `form` element with which the hidden input is associated. This string's value must match the id of a `form` element in the same document. |
| `id` | `string` | – | The id of the first input element. Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on). |
| `inputMode` | `"search" \| "text" \| "none" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal"` | – | The virtual keyboard hint applied to the slot inputs and hidden validation input. Built-in validation modes provide sensible defaults, but you can override them when needed. |
| `mask` | `boolean` | `false` | Whether the slot inputs should mask entered characters. Pass `type` directly to individual `<OTPField.Input>` parts to use a custom input type. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `normalizeValue` | `((value: string) => string)` | – | Function that normalizes the OTP value after whitespace and `validationType` filtering. It runs whenever OTP Field normalizes a value, including initial/default values, controlled values, and user edits. The returned value is filtered by `validationType` again, then clamped to `length`. It should be idempotent because OTP Field may normalize the same value more than once while handling edits, storing state, and rendering controlled or uncontrolled values. Non-idempotent normalizers can compound across those normalization passes. Characters rejected while normalizing typed or pasted text are reported through `onValueInvalid`. |
| `onValueChange` | `((value: string, eventDetails: OTPFieldRootChangeEventDetails) => void)` | – | Callback fired when the OTP value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for typing or autofill - `'input-clear'` when a character is removed by text input - `'input-paste'` for paste interactions - `'keyboard'` for keyboard interactions that change the value |
| `onValueComplete` | `((value: string, eventDetails: OTPFieldRootCompleteEventDetails) => void)` | – | Callback function that is fired when the OTP value becomes complete, or when a complete value is pasted while the OTP is already complete. When the value changes, it runs later than `onValueChange`, after the internal value update is applied. If a complete pasted value matches the current value, `onValueChange` does not fire. If `autoSubmit` is enabled, it runs immediately before the owning form is submitted. |
| `onValueInvalid` | `((value: string, eventDetails: OTPFieldRootInvalidEventDetails) => void)` | – | Callback fired when entered text contains characters that are rejected by validation or normalization before the OTP value updates. The `value` argument is the attempted user-entered string before normalization. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to change the field value. |
| `required` | `boolean` | `false` | Whether the user must enter a value before submitting a form. |
| `validationType` | `"none" \| "numeric" \| "alpha" \| "alphanumeric"` | `'numeric'` | The type of input validation to apply to the OTP value. |
| `value` | `string` | – | The OTP value. |

### InputOtpGroup

Also exported as `OTPFieldGroup`. Accepts `render`, plus every native attribute of the element it renders.

### InputOtpInput

Also exported as `OTPFieldInput`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### InputOtpSeparator

Also exported as `OTPFieldSeparator`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

---

# Input Payment

> Card number, expiry and security code inputs with formatting and card brand detection.

Source: https://ui.xiod.dev/docs/components/input-payment

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  InputPayment,
  InputPaymentBrandIcon,
  InputPaymentCVC,
  InputPaymentCardNumber,
  InputPaymentExpiry,
  InputPaymentGroup,
  InputPaymentMethodSelector,
  InputPaymentUpiGroup,
  InputPaymentUpiId,
  InputPaymentUpiProviderIcon,
  InputPaymentZip
} from "xiod-ui/input-payment";
```

Anatomy:

```tsx
<InputPaymentMethodSelector />
<InputPaymentGroup>
  <InputPaymentBrandIcon />
  <InputPaymentCardNumber />
  <InputPaymentExpiry />
  <InputPaymentCVC />
</InputPaymentGroup>
<InputPaymentUpiGroup>
  <InputPaymentUpiProviderIcon />
  <InputPaymentUpiId />
</InputPaymentUpiGroup>
<InputPayment>
  <InputPaymentCardNumber />
  <InputPaymentBrandIcon />
  <InputPaymentExpiry />
  <InputPaymentCVC />
</InputPayment>
```

## Example

```tsx
"use client";

import * as React from "react";
import { AlertCircle as XiodAlertCircle, Lock as XiodLock } from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import { Field, FieldLabel } from "xiod-ui/field";
import { Input } from "xiod-ui/input";
import {
  InputPayment,
  InputPaymentBrandIcon,
  InputPaymentCardNumber,
  InputPaymentCVC,
  InputPaymentExpiry,
  InputPaymentGroup,
  InputPaymentMethodSelector,
  InputPaymentUpiGroup,
  InputPaymentUpiId,
  InputPaymentUpiProviderIcon,
  useInputPayment,
} from "xiod-ui/input-payment";

function CheckoutForm() {
  const { paymentMethod, errors, isValid } = useInputPayment();
  const messages = Object.values(errors).filter(Boolean);

  return (
    <div className="flex flex-col gap-5">
      <InputPaymentMethodSelector />

      {paymentMethod === "card" ? (
        <Field name="card-details">
          <FieldLabel>Card Details</FieldLabel>
          <InputPaymentGroup>
            <InputPaymentBrandIcon />
            <InputPaymentCardNumber className="flex-1" />
            <div className="mx-1 h-5 w-px shrink-0 self-center bg-border" />
            <InputPaymentExpiry />
            <div className="mx-1 h-5 w-px shrink-0 self-center bg-border" />
            <InputPaymentCVC />
          </InputPaymentGroup>
        </Field>
      ) : (
        <Field name="upi-details">
          <FieldLabel>UPI ID</FieldLabel>
          <InputPaymentUpiGroup>
            <InputPaymentUpiProviderIcon />
            <InputPaymentUpiId className="flex-1" />
          </InputPaymentUpiGroup>
        </Field>
      )}

      {messages.length > 0 && (
        <div className="flex flex-col gap-1 text-xs text-destructive">
          {messages.map((message) => (
            <p key={message} className="flex items-center gap-1">
              <XiodAlertCircle className="size-3" />
              {message}
            </p>
          ))}
        </div>
      )}

      <Button className="w-full" disabled={!isValid}>
        <XiodLock className="size-3.5" />
        Pay $49.00
      </Button>
    </div>
  );
}

export function InputPaymentExample() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-12">
      {/* Checkout */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Checkout
        </Badge>
        <InputPayment
          className="w-full"
          autoFocusNext
          defaultUpiId="nobita@okaxis"
        >
          <CheckoutForm />
        </InputPayment>
      </div>

      {/* Fields */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Fields
        </Badge>
        <InputPayment className="w-full">
          <div className="flex flex-col gap-4">
            <Field name="cardholder">
              <FieldLabel>Cardholder Name</FieldLabel>
              <Input placeholder="Nobita Nobi" autoComplete="cc-name" />
            </Field>

            <Field name="cardnumber">
              <FieldLabel>Card Number</FieldLabel>
              <div className="relative flex w-full items-center">
                <InputPaymentCardNumber className="w-full pr-10" />
                <div className="pointer-events-none absolute right-3 flex items-center">
                  <InputPaymentBrandIcon />
                </div>
              </div>
            </Field>

            <div className="grid grid-cols-2 gap-4">
              <Field name="expiry">
                <FieldLabel>Expiry Date</FieldLabel>
                <InputPaymentExpiry className="w-full" />
              </Field>
              <Field name="cvc">
                <FieldLabel>CVC</FieldLabel>
                <InputPaymentCVC className="w-full" />
              </Field>
            </div>
          </div>
        </InputPayment>
      </div>
    </div>
  );
}

export default InputPaymentExample;
```

## API Reference

### InputPayment

Also exported as `PaymentInput`. every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocusNext` | `boolean` | `true` | Whether focus moves to the next field once a field is complete and valid, and back to the previous one on Backspace in an empty field. |
| `cardCvc` | `string` | – | The security code. Use with `onCardCvcChange` to control it. |
| `cardExpiry` | `string` | – | The expiry date as `MM/YY`. Use with `onCardExpiryChange` to control it. |
| `cardNumber` | `string` | – | The card number, spaced in groups as it is shown. Use with `onCardNumberChange` to control it. |
| `cardZip` | `string` | – | The postal code. Use with `onCardZipChange` to control it. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultCardCvc` | `string` | – | The security code at first, when it isn't controlled. |
| `defaultCardExpiry` | `string` | – | The expiry date at first, when it isn't controlled. |
| `defaultCardNumber` | `string` | – | The card number at first, when it isn't controlled. |
| `defaultCardZip` | `string` | – | The postal code at first, when it isn't controlled. |
| `defaultPaymentMethod` | `"card" \| "upi"` | `card` | The payment method selected at first, when it isn't controlled. |
| `defaultUpiId` | `string` | – | The UPI ID at first, when it isn't controlled. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onCardCvcChange` | `((val: string) => void)` | – | Called with the security code as the user types, cut to the card brand's length. |
| `onCardExpiryChange` | `((val: string) => void)` | – | Called with the formatted expiry date as the user types. |
| `onCardNumberChange` | `((val: string) => void)` | – | Called with the formatted card number as the user types. |
| `onCardZipChange` | `((val: string) => void)` | – | Called with the postal code as the user types. |
| `onPaymentMethodChange` | `((method: PaymentMethod) => void)` | – | Called with the new method when the user switches between card and UPI. |
| `onUpiIdChange` | `((val: string) => void)` | – | Called with the UPI ID as the user types. |
| `onValidationChange` | `((isValid: boolean, errors: PaymentInputErrors) => void)` | – | Called whenever the details become valid or invalid, with a message for each field that has an error. |
| `paymentMethod` | `"card" \| "upi"` | – | Whether the user is paying by `card` or `upi`. Use with `onPaymentMethodChange` to control it. |
| `readOnly` | `boolean` | `false` | Whether the value can be seen but not changed. |
| `upiId` | `string` | – | The UPI ID, such as `name@bank`. Use with `onUpiIdChange` to control it. |

### InputPaymentBrandIcon

Also exported as `PaymentInputBrandIcon`. Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### InputPaymentCVC

Also exported as `PaymentInputCVC`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `onChange` | `ChangeEventHandler<HTMLInputElement, Element>` | – | Called with the input's change event, after the field has formatted and stored the new value. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | – | Called with the input's keydown event. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### InputPaymentCardNumber

Also exported as `PaymentInputCardNumber`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `onChange` | `ChangeEventHandler<HTMLInputElement, Element>` | – | Called with the input's change event, after the field has formatted and stored the new value. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | – | Called with the input's keydown event. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### InputPaymentExpiry

Also exported as `PaymentInputExpiry`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `onChange` | `ChangeEventHandler<HTMLInputElement, Element>` | – | Called with the input's change event, after the field has formatted and stored the new value. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | – | Called with the input's keydown event. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### InputPaymentGroup

Also exported as `PaymentInputGroup`. Accepts `render`, plus every native `<div>` attribute.

### InputPaymentMethodSelector

Also exported as `PaymentInputMethodSelector`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cardIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `defaultValue` | `any` | `0` | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
| `onValueChange` | `((value: any, eventDetails: TabsRootChangeEventDetails) => void)` | – | Callback invoked when new value is being set. The event `reason` is `'none'` for user-initiated changes, such as a click or keyboard navigation; `'initial'` for the first automatic selection or fallback in uncontrolled roots when `defaultValue` is omitted or `undefined`, including when the implicit initial value is disabled or missing; `'disabled'` for automatic fallback when the selected tab becomes disabled in uncontrolled roots; or `'missing'` for automatic fallback when the selected tab is removed, or when an explicit `defaultValue` never matches a mounted tab in uncontrolled roots. For automatic changes, the selected value can be `null` when no enabled Tab is available as a fallback. Automatic changes cannot be canceled; calling `eventDetails.cancel()` for `'initial'`, `'disabled'`, or `'missing'` has no effect. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The component orientation (layout flow direction). |
| `upiIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `value` | `any` | – | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |

### InputPaymentUpiGroup

Also exported as `PaymentInputUpiGroup`. Accepts `render`, plus every native `<div>` attribute.

### InputPaymentUpiId

Also exported as `PaymentInputUpiId`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `onChange` | `ChangeEventHandler<HTMLInputElement, Element>` | – | Called with the input's change event, after the field has formatted and stored the new value. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | – | Called with the input's keydown event. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### InputPaymentUpiProviderIcon

Also exported as `PaymentInputUpiProviderIcon`. Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### InputPaymentZip

Also exported as `PaymentInputZip`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `onChange` | `ChangeEventHandler<HTMLInputElement, Element>` | – | Called with the input's change event, after the field has formatted and stored the new value. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | – | Called with the input's keydown event. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

---

# Input Phone

> A phone number input with a country picker and formatting, submitted in E.164 format.

Source: https://ui.xiod.dev/docs/components/input-phone

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  InputPhone,
  InputPhoneCountrySelect,
  InputPhoneFlag,
  InputPhoneInput
} from "xiod-ui/input-phone";
```

## Example

```tsx
"use client";

import { Badge } from "xiod-ui/badge";
import { Field, FieldLabel } from "xiod-ui/field";
import { InputPhone } from "xiod-ui/input-phone";

export function InputPhoneExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-12">
      {/* Default */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Default
        </Badge>
        <Field name="phone" className="w-full">
          <FieldLabel>Mobile Number</FieldLabel>
          <InputPhone defaultCountry="US" defaultValue="+15552345678" />
        </Field>
      </div>

      {/* Filled */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Filled
        </Badge>
        <Field name="phone-filled" className="w-full">
          <FieldLabel>Recovery Number</FieldLabel>
          <InputPhone
            variant="filled"
            defaultCountry="IN"
            defaultValue="+919876543210"
          />
        </Field>
      </div>
    </div>
  );
}

export default InputPhoneExample;
```

## API Reference

### InputPhone

Also exported as `PhoneInput`. Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `countries` | `CountryData[]` | `[ { code: "US", name: "United States", dialCode: "+1", flag: "🇺🇸", mask: "(###) ###-####", }, { code: "GB", name: "United Kingdom", dialCode: "+44", flag: "🇬🇧", mask: "##### ######", }, { code: "IN", name: "India", dialCode: "+91", flag: "🇮🇳", mask: "##### #####", }, { code: "CA", name: "Canada", dialCode: "+1", flag: "🇨🇦", mask: "(###) ###-####", }, { code: "AU", name: "Australia", dialCode: "+61", flag: "🇦🇺", mask: "#### ### ###", }, { code: "DE", name: "Germany", dialCode: "+49", flag: "🇩🇪", mask: "#### ########", }, { code: "FR", name: "France", dialCode: "+33", flag: "🇫🇷", mask: "# ## ## ## ##", }, { code: "JP", name: "Japan", dialCode: "+81", flag: "🇯🇵", mask: "## #### ####", }, { code: "BR", name: "Brazil", dialCode: "+55", flag: "🇧🇷", mask: "(##) #####-####", }, { code: "CN", name: "China", dialCode: "+86", flag: "🇨🇳", mask: "### #### ####", }, { code: "ES", name: "Spain", dialCode: "+34", flag: "🇪🇸", mask: "### ## ## ##", }, { code: "IT", name: "Italy", dialCode: "+39", flag: "🇮🇹", mask: "### #######", }, { code: "MX", name: "Mexico", dialCode: "+52", flag: "🇲🇽", mask: "### ### ####", }, { code: "NL", name: "Netherlands", dialCode: "+31", flag: "🇳🇱", mask: "# ########", }, { code: "SG", name: "Singapore", dialCode: "+65", flag: "🇸🇬", mask: "#### ####", }, { code: "KR", name: "South Korea", dialCode: "+82", flag: "🇰🇷", mask: "## #### ####", }, { code: "ZA", name: "South Africa", dialCode: "+27", flag: "🇿🇦", mask: "## ### ####", }, { code: "AE", name: "United Arab Emirates", dialCode: "+971", flag: "🇦🇪", mask: "## ### ####", }, { code: "AR", name: "Argentina", dialCode: "+54", flag: "🇦🇷", mask: "### ###-####", }, { code: "CH", name: "Switzerland", dialCode: "+41", flag: "🇨🇭", mask: "## ### ## ##", }, { code: "SE", name: "Sweden", dialCode: "+46", flag: "🇸🇪", mask: "##-### ## ##", }, { code: "NO", name: "Norway", dialCode: "+47", flag: "🇳🇴", mask: "### ## ###", }, { code: "DK", name: "Denmark", dialCode: "+45", flag: "🇩🇰", mask: "## ## ## ##", }, { code: "FI", name: "Finland", dialCode: "+358", flag: "🇫🇮", mask: "## ### ## ##", }, { code: "NZ", name: "New Zealand", dialCode: "+64", flag: "🇳🇿", mask: "## ### ####", }, { code: "PL", name: "Poland", dialCode: "+48", flag: "🇵🇱", mask: "### ### ###", }, { code: "PT", name: "Portugal", dialCode: "+351", flag: "🇵🇹", mask: "### ### ###", }, { code: "IE", name: "Ireland", dialCode: "+353", flag: "🇮🇪", mask: "## ### ####", }, { code: "BE", name: "Belgium", dialCode: "+32", flag: "🇧🇪", mask: "### ## ## ##", }, { code: "AT", name: "Austria", dialCode: "+43", flag: "🇦🇹", mask: "#### ######", }, { code: "IL", name: "Israel", dialCode: "+972", flag: "🇮🇱", mask: "##-###-####", }, { code: "SA", name: "Saudi Arabia", dialCode: "+966", flag: "🇸🇦", mask: "## ### ####", }, { code: "TH", name: "Thailand", dialCode: "+66", flag: "🇹🇭", mask: "## #### ####", }, { code: "MY", name: "Malaysia", dialCode: "+60", flag: "🇲🇾", mask: "##-### ####", }, { code: "ID", name: "Indonesia", dialCode: "+62", flag: "🇮🇩", mask: "###-####-####", }, { code: "PH", name: "Philippines", dialCode: "+63", flag: "🇵🇭", mask: "### ### ####", }, { code: "VN", name: "Vietnam", dialCode: "+84", flag: "🇻🇳", mask: "### ### ####", }, { code: "GR", name: "Greece", dialCode: "+30", flag: "🇬🇷", mask: "### #######", }, { code: "TR", name: "Turkey", dialCode: "+90", flag: "🇹🇷", mask: "### ### ## ##", }, { code: "UA", name: "Ukraine", dialCode: "+380", flag: "🇺🇦", mask: "## ### ## ##", }, { code: "CZ", name: "Czech Republic", dialCode: "+420", flag: "🇨🇿", mask: "### ### ###", }, { code: "HU", name: "Hungary", dialCode: "+36", flag: "🇭🇺", mask: "## ### ####", }, { code: "RO", name: "Romania", dialCode: "+40", flag: "🇷🇴", mask: "### ### ###", }, { code: "CL", name: "Chile", dialCode: "+56", flag: "🇨🇱", mask: "# #### ####", }, { code: "CO", name: "Colombia", dialCode: "+57", flag: "🇨🇴", mask: "### ### ####", }, { code: "PE", name: "Peru", dialCode: "+51", flag: "🇵🇪", mask: "### ### ###", }, { code: "EG", name: "Egypt", dialCode: "+20", flag: "🇪🇬", mask: "## #### ####", }, { code: "NG", name: "Nigeria", dialCode: "+234", flag: "🇳🇬", mask: "### ### ####", }, { code: "KE", name: "Kenya", dialCode: "+254", flag: "🇰🇪", mask: "### ######", }, ]` | The countries the user can choose from. Defaults to the built-in list, exported as `COUNTRIES`. |
| `defaultCountry` | `string` | `US` | The code of the country selected at first, such as `"US"`, when no number sets it. |
| `defaultValue` | `string` | – | The number at first, when it isn't controlled, in E.164 format such as `"+15550000000"`. Its dialling code picks the country. |
| `disabled` | `boolean` | – | Whether the component should ignore user interaction. |
| `name` | `string` | – | Submits the E.164 value (e.g. "+15550000000") with a form under this name. |
| `onChange` | `((e164: string, country: CountryData, nationalNumber: string) => void)` | – | Called when the number or country changes, with the full number in E.164 format, the selected country, and the digits typed without the dialling code. |
| `readOnly` | `boolean` | – | Whether the value can be seen but not changed. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string` | – | The number in E.164 format, such as `"+15550000000"`. Use with `onChange` to control it. |
| `variant` | `"default" \| "ghost" \| "filled"` | `default` | The visual style of the component. |

### InputPhoneCountrySelect

Also exported as `PhoneInputCountrySelect`. Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `searchIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `selectedIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `triggerIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### InputPhoneFlag

Also exported as `PhoneInputFlag`. Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | – | The code of the country whose flag to show, such as `"GB"`. Defaults to the selected country. |

### InputPhoneInput

Also exported as `PhoneInputInput`. Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `nativeInput` | `boolean` | – | Whether to render a plain `<input>` instead of Base UI's `Input`. A plain input doesn't register with a surrounding `Field`. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `unstyled` | `boolean` | – | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |

---

# Input Sensitive

> An input that masks a secret value, with buttons to reveal and copy it.

Source: https://ui.xiod.dev/docs/components/input-sensitive

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { InputSensitive } from "xiod-ui/input-sensitive";
```

## Example

```tsx
import { Field, FieldDescription, FieldLabel } from "xiod-ui/field";
import { InputSensitive } from "xiod-ui/input-sensitive";

export default function InputSensitiveExample() {
  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-6">
      <Field name="apiKey">
        <FieldLabel>API Key</FieldLabel>
        <FieldDescription>Your secret API key.</FieldDescription>
        <InputSensitive defaultValue="sk_live_1234567890abcdef" />
      </Field>

      <Field name="token">
        <FieldLabel>Access Token</FieldLabel>
        <InputSensitive
          defaultValue=""
          placeholder="Paste your token here..."
        />
      </Field>

      <Field name="disabledKey">
        <FieldLabel>Disabled Key</FieldLabel>
        <InputSensitive defaultValue="sk_test_disabled" disabled />
      </Field>
    </div>
  );
}
```

## API Reference

### InputSensitive

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `copiedIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `copyIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `hideIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `onCopy` | `(() => void)` | – | Called after the copy button copies the value to the clipboard. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `revealIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

---

# Kbd

> Shows a keyboard key or shortcut.

Source: https://ui.xiod.dev/docs/components/kbd

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Kbd, KbdGroup } from "xiod-ui/kbd";
```

Anatomy:

```tsx
<Kbd />
<KbdGroup>
  <Kbd />
</KbdGroup>
```

## Example

```tsx
import { Kbd, KbdGroup } from "xiod-ui/kbd";

export default function KbdExample() {
  return (
    <div className="flex flex-col gap-4">
      <div>
        <p className="mb-2 text-muted-foreground text-sm">Single keys:</p>
        <div className="flex gap-2">
          <Kbd>K</Kbd>
          <Kbd>⌘</Kbd>
          <Kbd>⌃</Kbd>
          <Kbd>⇧</Kbd>
        </div>
      </div>
      <div>
        <p className="mb-2 text-muted-foreground text-sm">Key combinations:</p>
        <div className="flex gap-2">
          <Kbd>⌘ + K</Kbd>

          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>Shift</Kbd>
            <Kbd>P</Kbd>
          </KbdGroup>
          <KbdGroup>
            <Kbd>Ctrl</Kbd>
            <Kbd>Alt</Kbd>
            <Kbd>Delete</Kbd>
          </KbdGroup>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Kbd

Accepts `render`, plus every native `<kbd>` attribute.

### KbdGroup

Accepts `render`, plus every native `<kbd>` attribute.

---

# Kinetic Click

> Plays a particle burst when the element it wraps is clicked.

Source: https://ui.xiod.dev/docs/components/kinetic-click

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { KineticClick } from "xiod-ui/kinetic-click";
```

## Example

```tsx
"use client";

import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import { KineticClick, type KineticClickVariant } from "xiod-ui/kinetic-click";

const variants: KineticClickVariant[] = [
  "spark",
  "ripple",
  "embers",
  "quantum",
  "tesseract",
  "blackhole",
  "firework",
  "shatter",
  "warp",
  "matrix",
  "smoke",
  "supernova",
  "holosphere",
  "flowfield",
  "synapse",
  "diffusion",
  "rain",
  "binary",
  "fission",
  "bullettime",
];

export default function KineticClickExample() {
  return (
    <div className="flex w-full max-w-2xl flex-col items-center gap-12">
      {/* Variants */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Variants
        </Badge>
        <div className="grid w-full grid-cols-2 gap-2 sm:grid-cols-4">
          {variants.map((variant) => (
            <KineticClick key={variant} variant={variant}>
              <Button
                variant="outline"
                size="sm"
                className="w-full justify-center capitalize"
              >
                {variant}
              </Button>
            </KineticClick>
          ))}
        </div>
      </div>

      {/* Colors */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Colors
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-3">
          <KineticClick variant="firework" color="#6366f1">
            <Button variant="outline" size="sm">
              Indigo
            </Button>
          </KineticClick>
          <KineticClick variant="embers" color="#f59e0b">
            <Button variant="outline" size="sm">
              Amber
            </Button>
          </KineticClick>
          <KineticClick variant="supernova" color="#f43f5e">
            <Button variant="outline" size="sm">
              Rose
            </Button>
          </KineticClick>
        </div>
      </div>

      {/* Inherited color */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Inherited Color
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-3">
          <KineticClick variant="bullettime" colorFrom="background">
            <Button size="sm">Background</Button>
          </KineticClick>
          <KineticClick variant="binary" colorFrom="text">
            <Button variant="outline" size="sm" className="text-emerald-500">
              Text
            </Button>
          </KineticClick>
          <KineticClick variant="fission" colorFrom="border">
            <Button variant="outline" size="sm" className="border-rose-500">
              Border
            </Button>
          </KineticClick>
        </div>
      </div>

      {/* Surface */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Surface
        </Badge>
        <KineticClick variant="spark" className="w-full">
          <div className="flex h-48 w-full cursor-crosshair items-center justify-center rounded-xl border border-dashed bg-muted/20 text-sm text-muted-foreground select-none">
            Click anywhere
          </div>
        </KineticClick>
      </div>
    </div>
  );
}
```

## API Reference

### KineticClick

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `color` | `string` | `currentColor` | The colour of the effect, as a CSS colour. `currentColor` takes it from the clicked element, as `colorFrom` sets. |
| `colorFrom` | `"text" \| "auto" \| "background" \| "border"` | `auto` | Which colour of the clicked element to use when `color` is `currentColor`. `auto` uses the first of its text, background and border colours that isn't a neutral grey, so a white-text button still gets a coloured effect. |
| `count` | `number` | – | How many particles, ripples or shapes each click creates. Each effect has its own default. |
| `duration` | `number` | – | How long the effect lasts, in milliseconds. Each effect has its own default. |
| `size` | `number` | – | How large the effect is, in pixels: a particle's size, or a ripple's largest radius. Each effect has its own default. |
| `trigger` | `"click" \| "mousedown"` | `mousedown` | When the effect plays: as soon as the button is pressed (`mousedown`), or when it is released (`click`). |
| `variant` | `"ripple" \| "spark" \| "embers" \| "quantum" \| "tesseract" \| "blackhole" \| "firework" \| "shatter" \| "warp" \| "matrix" \| "smoke" \| "supernova" \| "holosphere" \| "flowfield" \| "synapse" \| "diffusion" \| "rain" \| "binary" \| "fission" \| "bullettime"` | `spark` | The effect that plays where the user clicks. |

---

# Label

> A text label for a form control.

Source: https://ui.xiod.dev/docs/components/label

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Label } from "xiod-ui/label";
```

## Example

```tsx
import { useId } from "react";
import { Badge } from "xiod-ui/badge";
import { Checkbox } from "xiod-ui/checkbox";
import { Input } from "xiod-ui/input";
import { Label } from "xiod-ui/label";
import { Switch } from "xiod-ui/switch";

export default function LabelExample() {
  const emailId = useId();

  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* For a control */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Linked
        </Badge>
        <div className="flex w-full flex-col items-start gap-2">
          <Label htmlFor={emailId}>Email</Label>
          <Input id={emailId} placeholder="you@example.com" type="email" />
        </div>
      </div>

      {/* Wrapping a control */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Wrapping
        </Badge>
        <div className="flex w-full flex-col items-start gap-3">
          <Label>
            <Checkbox defaultChecked /> Email me about releases
          </Label>
          <Label>
            <Switch /> Enable beta features
          </Label>
        </div>
      </div>

      {/* Disabled */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Disabled
        </Badge>
        <div className="flex w-full items-start">
          <Label>
            <Checkbox disabled /> Requires an upgraded plan
          </Label>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Label

Accepts `render`, plus every native `<label>` attribute.

---

# List Box

> An always-visible list of options to select one or several from.

Source: https://ui.xiod.dev/docs/components/list-box

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  ListBox,
  ListBoxGroup,
  ListBoxItem,
  ListBoxLabel,
  ListBoxSeparator
} from "xiod-ui/list-box";
```

Anatomy:

```tsx
<ListBoxItem />
<ListBox>
  <ListBoxGroup>
    <ListBoxLabel />
    <ListBoxItem />
  </ListBoxGroup>
</ListBox>
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  Check as CheckIcon,
  LayoutGrid as LayoutGridIcon,
  SecurityCheck as ShieldCheckIcon,
  Sparkles as SparklesIcon,
} from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Checkbox } from "xiod-ui/checkbox";
import {
  ListBox,
  ListBoxGroup,
  ListBoxItem,
  ListBoxLabel,
  ListBoxSeparator,
} from "xiod-ui/list-box";

const roles = [
  {
    value: "admin",
    label: "Administrator",
    hint: "Full access",
    icon: ShieldCheckIcon,
  },
  {
    value: "editor",
    label: "Editor",
    hint: "Review and publish",
    icon: LayoutGridIcon,
  },
  {
    value: "viewer",
    label: "Viewer",
    hint: "Read-only access",
    icon: SparklesIcon,
  },
];

const preferences = [
  { value: "dark-mode", label: "Dark mode" },
  { value: "compact-view", label: "Compact view" },
];

const system = [
  { value: "auto-save", label: "Auto-save" },
  { value: "telemetry", label: "Send telemetry", disabled: true },
];

export default function ListBoxExample() {
  const [selected, setSelected] = React.useState<string[]>([
    "auto-save",
    "dark-mode",
  ]);

  const renderCheckable = (item: {
    value: string;
    label: string;
    disabled?: boolean;
  }) => (
    <ListBoxItem key={item.value} value={item.value} disabled={item.disabled}>
      <Checkbox
        checked={selected.includes(item.value)}
        disabled={item.disabled}
        className="pointer-events-none"
        tabIndex={-1}
      />
      {item.label}
    </ListBoxItem>
  );

  return (
    <div className="flex w-full max-w-md flex-col items-center gap-12">
      {/* Single */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Single
        </Badge>
        <ListBox className="w-full" name="role" defaultValue="viewer">
          <ListBoxGroup>
            <ListBoxLabel>Permissions</ListBoxLabel>
            {roles.map(({ value, label, hint, icon: Icon }) => (
              <ListBoxItem key={value} value={value} className="group">
                <Icon className="text-muted-foreground" />
                <div className="flex flex-1 flex-col">
                  <span>{label}</span>
                  <span className="text-xs text-muted-foreground">{hint}</span>
                </div>
                <CheckIcon className="ms-auto opacity-0 group-data-[selected=true]:opacity-100" />
              </ListBoxItem>
            ))}
          </ListBoxGroup>
        </ListBox>
      </div>

      {/* Multiple */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Multiple
        </Badge>
        <ListBox
          className="w-full"
          multiple
          name="preferences"
          value={selected}
          onValueChange={(value) => {
            if (Array.isArray(value)) setSelected(value);
          }}
        >
          <ListBoxGroup>
            <ListBoxLabel>Appearance</ListBoxLabel>
            {preferences.map(renderCheckable)}
          </ListBoxGroup>
          <ListBoxSeparator />
          <ListBoxGroup>
            <ListBoxLabel>System</ListBoxLabel>
            {system.map(renderCheckable)}
          </ListBoxGroup>
        </ListBox>
      </div>
    </div>
  );
}
```

## API Reference

### ListBox

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `ListBoxValue` | – | The value selected at first, when the selection isn't controlled. |
| `multiple` | `boolean` | – | Whether more than one item can be selected. The value is then an array. |
| `name` | `string` | – | Submits the selection with a form: one hidden input per selected value. |
| `onValueChange` | `((value: ListBoxValue) => void)` | – | Called with the new value when the selection changes. |
| `value` | `ListBoxValue` | – | The selected value: a string, or an array of strings when `multiple` is set. Use with `onValueChange` to control the selection. |

### ListBoxGroup

Accepts `render`, plus every native `<div>` attribute.

### ListBoxItem

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | The value this item selects. Must be unique within the list. |
| `disabled` | `boolean` | – | Whether the component should ignore user interaction. |

### ListBoxLabel

Accepts `render`, plus every native `<div>` attribute.

### ListBoxSeparator

Accepts `render`, plus every native `<div>` attribute.

---

# Loader

> An animated indicator that shows something is loading.

Source: https://ui.xiod.dev/docs/components/loader

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Loader } from "xiod-ui/loader";
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import { Loader } from "xiod-ui/loader";

export default function LoaderExample() {
  return (
    <div className="flex flex-col gap-12 items-center w-full max-w-4xl">
      {/* Variants */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Variants
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-8">
          <div className="flex flex-col items-center gap-2">
            <Loader variant="ring" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Ring
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="expressive" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Expressive
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="circular-arrows" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Circular Arrows
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="radial-pulse" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Radial Pulse
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="arc-head" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Arc Head
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="segmented-ring" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Segmented Ring
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="chunked-circular" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Chunked Circular
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="petal" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Petal
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="orbiting-dots" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Orbiting Dots
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="dotted-ring" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Dotted Ring
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="radial-arrow" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Radial Arrow
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="bar-segment" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Bar Segment
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="orbiting-ball" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Orbiting Ball
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="dots" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Dots
            </span>
          </div>
          <div className="flex flex-col items-center gap-2">
            <Loader variant="pulse" size="lg" />
            <span className="text-xs text-muted-foreground font-medium">
              Pulse
            </span>
          </div>
        </div>
      </div>

      {/* Intents */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Intents
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-8 bg-card px-8 py-4 rounded-xl border">
          <Loader intent="default" size="md" variant="ring" />
          <Loader intent="primary" size="md" variant="ring" />
          <Loader intent="success" size="md" variant="ring" />
          <Loader intent="warning" size="md" variant="ring" />
          <Loader intent="danger" size="md" variant="ring" />
          <Loader intent="muted" size="md" variant="ring" />
        </div>
      </div>

      {/* Sizes */}
      <div className="flex flex-col space-y-4 items-center">
        <Badge variant="outline" className="mb-2">
          Sizes
        </Badge>
        <div className="flex items-center justify-center gap-8">
          <Loader variant="expressive" size="sm" />
          <Loader variant="expressive" size="md" />
          <Loader variant="expressive" size="lg" />
          <Loader variant="expressive" size="xl" />
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Loader

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intent` | `"default" \| "success" \| "warning" \| "muted" \| "primary" \| "danger"` | `default` | The loader's colour, from the theme's status colours. |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `md` | The size of the component. |
| `variant` | `"expressive" \| "pulse" \| "ring" \| "dots" \| "circular-arrows" \| "radial-pulse" \| "arc-head" \| "segmented-ring" \| "chunked-circular" \| "petal" \| "orbiting-dots" \| "dotted-ring" \| "radial-arrow" \| "bar-segment" \| "orbiting-ball"` | `ring` | The visual style of the component. |

---

# Marker

> A small line of muted text with an optional icon, for labels, dividers and annotations.

Source: https://ui.xiod.dev/docs/components/marker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Marker, MarkerIcon, MarkerContent } from "xiod-ui/marker";
```

Anatomy:

```tsx
<Marker>
  <MarkerIcon />
  <MarkerContent />
</Marker>
```

## Example

```tsx
"use client";

import { GitBranch as XiodGitBranch, Search as XiodSearch } from "xiod-icons";
import { AgentSteps } from "xiod-ui/agent-steps";
import { Marker, MarkerContent, MarkerIcon } from "xiod-ui/marker";

export default function MarkerExample() {
  return (
    <div className="flex w-full flex-col gap-5.5 max-w-sm p-5 border border-border/80 bg-background/50 rounded-2xl shadow-xs/5 relative before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]">
      {/* 1. Branch Switch Marker */}
      <Marker>
        <MarkerIcon>
          <XiodGitBranch />
        </MarkerIcon>
        <MarkerContent>Switched to a new branch</MarkerContent>
      </Marker>

      {/* 2. Thinking Loading Marker using AgentSteps */}
      <Marker className="p-0 select-none cursor-default">
        <AgentSteps
          size="md"
          label="Thinking..."
          icon="thinking"
          className="text-muted-foreground justify-start gap-2 p-0 font-normal"
        />
      </Marker>

      {/* 3. Conversation Compacted Separator */}
      <Marker variant="separator" size="sm" className="my-1">
        <MarkerContent className="px-1.5">Conversation compacted</MarkerContent>
      </Marker>

      {/* 4. File Search Exploration Marker */}
      <Marker>
        <MarkerIcon>
          <XiodSearch />
        </MarkerIcon>
        <MarkerContent>Explored 4 files</MarkerContent>
      </Marker>
    </div>
  );
}
```

## API Reference

### Marker

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `variant` | `"default" \| "separator" \| "border"` | `default` | The visual style of the component. |

### MarkerIcon

Accepts `render`, plus every native attribute of the element it renders.

### MarkerContent

Accepts `render`, plus every native attribute of the element it renders.

---

# Menu

> A dropdown menu of actions, opened from a button.

Source: https://ui.xiod.dev/docs/components/menu

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Menu,
  MenuArrow,
  MenuCheckboxItem,
  MenuGroup,
  MenuGroupLabel,
  MenuItem,
  MenuPopup,
  MenuPortal,
  MenuRadioGroup,
  MenuRadioItem,
  MenuSeparator,
  MenuShortcut,
  MenuSub,
  MenuSubPopup,
  MenuSubTrigger,
  MenuTrigger,
  MenuCreateHandle
} from "xiod-ui/menu";
```

Anatomy:

```tsx
<Menu>
  <MenuTrigger />
  <MenuPopup>
    <MenuGroup>
      <MenuGroupLabel />
      <MenuItem>
        <MenuShortcut />
      </MenuItem>
    </MenuGroup>
    <MenuSeparator />
    <MenuCheckboxItem />
    <MenuSub>
      <MenuSubTrigger />
      <MenuSubPopup>
        <MenuItem />
      </MenuSubPopup>
    </MenuSub>
    <MenuItem>
      <MenuShortcut />
    </MenuItem>
  </MenuPopup>
</Menu>
```

## Example

```tsx
import {
  Pause as PauseIcon,
  Play as PlayIcon,
  Previous as SkipBackIcon,
  Next as SkipForwardIcon,
  Delete as TrashIcon,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Menu,
  MenuCheckboxItem,
  MenuGroup,
  MenuGroupLabel,
  MenuItem,
  MenuPopup,
  MenuRadioGroup,
  MenuRadioItem,
  MenuSeparator,
  MenuShortcut,
  MenuSub,
  MenuSubPopup,
  MenuSubTrigger,
  MenuTrigger,
} from "xiod-ui/menu";

export default function MenuExample() {
  return (
    <Menu>
      <MenuTrigger render={<Button variant="outline" />}>Open menu</MenuTrigger>
      <MenuPopup>
        <MenuGroup>
          <MenuGroupLabel>Playback</MenuGroupLabel>
          <MenuItem>
            <PlayIcon aria-hidden="true" />
            Play
            <MenuShortcut>⌘P</MenuShortcut>
          </MenuItem>
          <MenuItem disabled>
            <PauseIcon aria-hidden="true" />
            Pause
            <MenuShortcut>⇧⌘P</MenuShortcut>
          </MenuItem>
          <MenuItem>
            <SkipBackIcon aria-hidden="true" />
            Previous
            <MenuShortcut>⌘[</MenuShortcut>
          </MenuItem>
          <MenuItem>
            <SkipForwardIcon aria-hidden="true" />
            Next
            <MenuShortcut>⌘]</MenuShortcut>
          </MenuItem>
        </MenuGroup>
        <MenuSeparator />
        <MenuCheckboxItem>Shuffle</MenuCheckboxItem>
        <MenuCheckboxItem>Repeat</MenuCheckboxItem>
        <MenuCheckboxItem disabled>Enhanced Audio</MenuCheckboxItem>
        <MenuSeparator />
        <MenuGroup>
          <MenuGroupLabel>Sort by</MenuGroupLabel>
          <MenuRadioGroup>
            <MenuRadioItem value="artist">Artist</MenuRadioItem>
            <MenuRadioItem value="album">Album</MenuRadioItem>
            <MenuRadioItem value="title">Title</MenuRadioItem>
          </MenuRadioGroup>
        </MenuGroup>
        <MenuSeparator />
        <MenuCheckboxItem variant="switch">Auto save</MenuCheckboxItem>
        <MenuSeparator />
        <MenuSub>
          <MenuSubTrigger>Add to Playlist</MenuSubTrigger>
          <MenuSubPopup>
            <MenuItem>Jazz</MenuItem>
            <MenuSub>
              <MenuSubTrigger>Rock</MenuSubTrigger>
              <MenuSubPopup>
                <MenuItem>Hard Rock</MenuItem>
                <MenuItem>Soft Rock</MenuItem>
                <MenuItem>Classic Rock</MenuItem>
                <MenuSeparator />
                <MenuItem>Metal</MenuItem>
                <MenuItem>Punk</MenuItem>
                <MenuItem>Grunge</MenuItem>
                <MenuItem>Alternative</MenuItem>
                <MenuItem>Indie</MenuItem>
                <MenuItem>Electronic</MenuItem>
              </MenuSubPopup>
            </MenuSub>
            <MenuItem>Pop</MenuItem>
          </MenuSubPopup>
        </MenuSub>
        <MenuSeparator />
        <MenuItem variant="destructive">
          <TrashIcon aria-hidden="true" />
          Delete
          <MenuShortcut>⌘⌫</MenuShortcut>
        </MenuItem>
      </MenuPopup>
    </Menu>
  );
}
```

## API Reference

### Menu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `closeParentOnEsc` | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the menu is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open menu. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `handle` | `MenuHandle<Payload>` | – | A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `modal` | `boolean` | `true` | Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal. |
| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |
| `triggerId` | `string \| null` | – | ID of the trigger that the menu is associated with. This is useful in conjunction with the `open` prop to create a controlled menu. There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set). |

### MenuArrow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### MenuCheckboxItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – | Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `defaultChecked` | `boolean` | `false` | Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the checkbox item is ticked or unticked. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `variant` | `"switch" \| "default"` | `default` | The visual style of the component. |

### MenuGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |

### MenuGroupLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | – | Whether to indent the label so it lines up with items that have an icon. |

### MenuItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnClick` | `boolean` | `true` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `variant` | `"default" \| "destructive"` | `default` | The visual style of the component. |

### MenuPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `center` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Menu$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `8` | Distance between the anchor and the popup, in pixels. |

### MenuPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### MenuRadioGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultValue` | `any` | – | The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onValueChange` | `((value: any, eventDetails: MenuRootChangeEventDetails) => void)` | – | Function called when the selected value changes. |
| `value` | `any` | – | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |

### MenuRadioItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |

### MenuSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### MenuShortcut

Accepts `render`, plus every native `<kbd>` attribute.

### MenuSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode` | – | The content of the submenu. |
| `closeParentOnEsc` | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |

### MenuSubPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `sideOffset` | `number \| OffsetFunction` | `0` | Distance between the anchor and the popup, in pixels. |

### MenuSubTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `100` | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `openOnHover` | `boolean` | `true` | Whether the menu should also open when the trigger is hovered. |

### MenuTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `closeDelay` | `number` | `0` | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `100` | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `handle` | `MenuHandle<unknown>` | – | A handle to associate the trigger with a menu. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `openOnHover` | `boolean` | – | Whether the menu should also open when the trigger is hovered. |
| `payload` | `unknown` | – | A payload to pass to the menu when it is opened. |

### Helpers

`MenuCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Menubar

> A horizontal bar of menus, as in a desktop app.

Source: https://ui.xiod.dev/docs/components/menubar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarGroup,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarPopup,
  MenubarPortal,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubPopup,
  MenubarSubTrigger,
  MenubarTrigger
} from "xiod-ui/menubar";
```

Anatomy:

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger />
    <MenubarPopup>
      <MenubarItem>
        <MenubarShortcut />
      </MenubarItem>
      <MenubarSeparator />
      <MenubarSub>
        <MenubarSubTrigger />
        <MenubarSubPopup>
          <MenubarItem />
          <MenubarSeparator />
        </MenubarSubPopup>
      </MenubarSub>
    </MenubarPopup>
  </MenubarMenu>
</Menubar>
```

## Example

```tsx
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarItem,
  MenubarMenu,
  MenubarPopup,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubPopup,
  MenubarSubTrigger,
  MenubarTrigger,
} from "xiod-ui/menubar";

export default function MenubarExample() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarPopup>
          <MenubarItem>
            New Tab
            <MenubarShortcut>⌘T</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            New Window
            <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarItem disabled>New Incognito Window</MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Share</MenubarSubTrigger>
            <MenubarSubPopup>
              <MenubarItem>Email link</MenubarItem>
              <MenubarItem>Messages</MenubarItem>
              <MenubarItem>Notes</MenubarItem>
            </MenubarSubPopup>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Print...
            <MenubarShortcut>⌘P</MenubarShortcut>
          </MenubarItem>
        </MenubarPopup>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarPopup>
          <MenubarItem>
            Undo
            <MenubarShortcut>⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Redo
            <MenubarShortcut>⇧⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Find</MenubarSubTrigger>
            <MenubarSubPopup>
              <MenubarItem>Search the web</MenubarItem>
              <MenubarSeparator />
              <MenubarItem>Find...</MenubarItem>
              <MenubarItem>Find Next</MenubarItem>
              <MenubarItem>Find Previous</MenubarItem>
            </MenubarSubPopup>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>Cut</MenubarItem>
          <MenubarItem>Copy</MenubarItem>
          <MenubarItem>Paste</MenubarItem>
        </MenubarPopup>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarPopup>
          <MenubarCheckboxItem>Always Show Bookmarks Bar</MenubarCheckboxItem>
          <MenubarCheckboxItem checked>
            Always Show Full URLs
          </MenubarCheckboxItem>
          <MenubarSeparator />
          <MenubarItem inset>
            Reload
            <MenubarShortcut>⌘R</MenubarShortcut>
          </MenubarItem>
          <MenubarItem disabled inset>
            Force Reload
            <MenubarShortcut>⇧⌘R</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem inset>Toggle Fullscreen</MenubarItem>
          <MenubarSeparator />
          <MenubarItem inset>Hide Sidebar</MenubarItem>
        </MenubarPopup>
      </MenubarMenu>

      <MenubarMenu>
        <MenubarTrigger>Profiles</MenubarTrigger>
        <MenubarPopup>
          <MenubarRadioGroup value="optimus">
            <MenubarRadioItem value="bumblebee">Bumblebee</MenubarRadioItem>
            <MenubarRadioItem value="optimus">Optimus</MenubarRadioItem>
            <MenubarRadioItem value="megatron">Megatron</MenubarRadioItem>
          </MenubarRadioGroup>
          <MenubarSeparator />
          <MenubarItem inset>Edit...</MenubarItem>
          <MenubarSeparator />
          <MenubarItem inset>Add Profile...</MenubarItem>
        </MenubarPopup>
      </MenubarMenu>
    </Menubar>
  );
}
```

## API Reference

### Menubar

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the whole menubar is disabled. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `modal` | `boolean` | `true` | Whether the menubar is modal. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the menubar. |

### MenubarCheckboxItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – | Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `defaultChecked` | `boolean` | `false` | Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the checkbox item is ticked or unticked. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |

### MenubarGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |

### MenubarItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnClick` | `boolean` | `true` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `variant` | `"default" \| "destructive"` | – | The visual style of the component. |

### MenubarLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | – | Whether to indent the label so it lines up with items that have an icon. |

### MenubarMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode \| PayloadChildRenderFunction<unknown>` | – | The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `closeParentOnEsc` | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the menu is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open menu. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `handle` | `MenuHandle<unknown>` | – | A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `modal` | `boolean` | `true` | Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal. |
| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |
| `triggerId` | `string \| null` | – | ID of the trigger that the menu is associated with. This is useful in conjunction with the `open` prop to create a controlled menu. There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set). |

### MenubarPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Menu.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the menu's trigger. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | – | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `10` | Distance between the anchor and the popup, in pixels. |

### MenubarPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### MenubarRadioGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultValue` | `any` | – | The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `onValueChange` | `((value: any, eventDetails: MenuRootChangeEventDetails) => void)` | – | Function called when the selected value changes. |
| `value` | `any` | – | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |

### MenubarRadioItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected. |
| `closeOnClick` | `boolean` | `false` | Whether to close the menu when the item is clicked. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |

### MenubarSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### MenubarShortcut

every native attribute of the element it renders.

### MenubarSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<MenuRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| `children` | `ReactNode` | – | The content of the submenu. |
| `closeParentOnEsc` | `boolean` | `false` | When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu. |
| `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | – | Event handler called when the menu is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the menu is opened or closed. |
| `open` | `boolean` | – | Whether the menu is currently open. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |

### MenubarSubPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |

### MenubarSubTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `100` | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `inset` | `boolean` | – | Whether to indent the item so its text lines up with items that have an icon. |
| `label` | `string` | – | Overrides the text label to use when the item is matched during keyboard text navigation. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onClick` | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | – | The click handler for the menu item. |
| `openOnHover` | `boolean` | `true` | Whether the menu should also open when the trigger is hovered. |

### MenubarTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `closeDelay` | `number` | `0` | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `100` | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `handle` | `MenuHandle<unknown>` | – | A handle to associate the trigger with a menu. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `openOnHover` | `boolean` | – | Whether the menu should also open when the trigger is hovered. |
| `payload` | `unknown` | – | A payload to pass to the menu when it is opened. |

---

# Message

> Chat message bubbles with avatars, alignment and reactions.

Source: https://ui.xiod.dev/docs/components/message

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  MessageGroup,
  Message,
  MessageAvatar,
  MessageContent,
  MessageHeader,
  MessageFooter,
  Bubble,
  BubbleContent,
  BubbleReactions
} from "xiod-ui/message";
```

Anatomy:

```tsx
<MessageGroup>
  <Message>
    <MessageAvatar />
    <MessageContent>
      <MessageHeader />
      <Bubble>
        <BubbleContent />
        <BubbleReactions />
      </Bubble>
      <MessageFooter />
    </MessageContent>
  </Message>
</MessageGroup>
```

## Example

```tsx
"use client";

import { Sparkles as XiodSparkles } from "xiod-icons";
import { Avatar, AvatarFallback, AvatarImage } from "xiod-ui/avatar";
import {
  Bubble,
  BubbleContent,
  BubbleReactions,
  Message,
  MessageAvatar,
  MessageContent,
  MessageFooter,
  MessageGroup,
  MessageHeader,
} from "xiod-ui/message";

export default function MessageExample() {
  return (
    <div className="flex w-full flex-col gap-4 max-w-md">
      <div className="flex flex-col gap-4 border border-border/80 bg-background/50 rounded-2xl p-6 shadow-xs/5 relative before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]">
        <MessageGroup>
          {/* 1. Incoming Message (Muted Bubble) */}
          <Message align="start">
            <MessageAvatar>
              <Avatar className="size-full">
                <AvatarImage src="/placeholder.svg" alt="Shizuka Minamoto" />
                <AvatarFallback>SM</AvatarFallback>
              </Avatar>
            </MessageAvatar>
            <MessageContent>
              <MessageHeader>Shizuka Minamoto</MessageHeader>
              <Bubble variant="muted" align="start">
                <BubbleContent>
                  Hey! Have you completed the file upload layout mockups we
                  discussed? Let me know once they are ready.
                </BubbleContent>
              </Bubble>
              <MessageFooter>10:24 AM</MessageFooter>
            </MessageContent>
          </Message>

          {/* 2. Outgoing Message (Default Primary Bubble) */}
          <Message align="end">
            <MessageContent>
              <MessageHeader>You</MessageHeader>
              <Bubble variant="default" align="end">
                <BubbleContent>
                  Yes, I just merged the FileUpload and Attachment components
                  into a unified interface! They support horizontal scrolling
                  queue lists and horizontal snapping.
                </BubbleContent>
              </Bubble>
              <MessageFooter className="gap-1">
                <span>10:25 AM</span>
                <span className="text-muted-foreground/60">•</span>
                <span className="text-primary font-medium">Read</span>
              </MessageFooter>
            </MessageContent>
          </Message>

          {/* 3. Incoming AI Assistant Message (Tinted Bubble + Reactions) */}
          <Message align="start" className="mt-2">
            <MessageAvatar className="bg-primary/10 text-primary border border-primary/20 dark:bg-primary/20 dark:border-primary/30">
              <XiodSparkles className="size-4" />
            </MessageAvatar>
            <MessageContent>
              <MessageHeader className="gap-1.5">
                <span>Xiod AI</span>
                <span className="inline-flex h-4 items-center rounded-sm bg-primary/10 px-1 text-[9px] font-bold uppercase tracking-wider text-primary dark:bg-primary/20">
                  Agent
                </span>
              </MessageHeader>
              <Bubble variant="tinted" align="start">
                <BubbleContent>
                  I've run the style audits. Both component setups compile
                  cleanly, formatting is optimized, and responsiveness is fully
                  verified.
                </BubbleContent>
                <BubbleReactions
                  side="bottom"
                  align="end"
                  className="border-background border-2 bg-muted shadow-none backdrop-blur-2xl text-muted-foreground"
                >
                  <span className="flex items-center gap-0.5">
                    <span>✨</span>
                    <span className="text-[10px] font-medium text-foreground">
                      1
                    </span>
                  </span>
                  <span className="text-muted-foreground/40 text-[9px]">|</span>
                  <span className="flex items-center gap-0.5">
                    <span>👍</span>
                    <span className="text-[10px] font-medium text-foreground">
                      2
                    </span>
                  </span>
                </BubbleReactions>
              </Bubble>
              <MessageFooter>Just now</MessageFooter>
            </MessageContent>
          </Message>
        </MessageGroup>
      </div>
    </div>
  );
}
```

## API Reference

### MessageGroup

Accepts `render`, plus every native attribute of the element it renders.

### Message

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end"` | `start` | Which side the message sits on. Use `end` for the current user's messages. |

### MessageAvatar

Accepts `render`, plus every native attribute of the element it renders.

### MessageContent

Accepts `render`, plus every native attribute of the element it renders.

### MessageHeader

Accepts `render`, plus every native attribute of the element it renders.

### MessageFooter

Accepts `render`, plus every native attribute of the element it renders.

### Bubble

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end"` | `start` | Which side the bubble lines up with. Match the surrounding `Message`'s `align`. |
| `variant` | `"default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "muted" \| "tinted"` | `default` | The visual style of the component. |

### BubbleContent

Accepts `render`, plus every native `<div>` attribute.

### BubbleReactions

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end"` | `end` | Whether the reactions sit near the bubble's start or end corner. |
| `side` | `"top" \| "bottom"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |

---

# Meter

> Shows a measurement within a known range, such as storage used.

Source: https://ui.xiod.dev/docs/components/meter

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Meter,
  MeterIndicator,
  MeterLabel,
  MeterTrack,
  MeterValue
} from "xiod-ui/meter";
```

Anatomy:

```tsx
<Meter>
  <MeterLabel />
  <MeterValue />
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import {
  Meter,
  MeterIndicator,
  MeterLabel,
  MeterTrack,
  MeterValue,
} from "xiod-ui/meter";

const usage = [
  { label: "Documents", value: 18 },
  { label: "Images", value: 54 },
  { label: "Backups", value: 92 },
];

export default function MeterExample() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Default */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Default
        </Badge>
        <Meter className="w-full" value={75}>
          <div className="flex items-center justify-between gap-2">
            <MeterLabel>Storage usage</MeterLabel>
            <MeterValue />
          </div>
          <MeterTrack>
            <MeterIndicator />
          </MeterTrack>
        </Meter>
      </div>

      {/* Values */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Values
        </Badge>
        <div className="flex w-full flex-col gap-4">
          {usage.map(({ label, value }) => (
            <Meter key={label} value={value}>
              <div className="flex items-center justify-between gap-2">
                <MeterLabel>{label}</MeterLabel>
                <MeterValue />
              </div>
              <MeterTrack>
                <MeterIndicator />
              </MeterTrack>
            </Meter>
          ))}
        </div>
      </div>

      {/* Custom range */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Custom Range
        </Badge>
        <Meter className="w-full" value={320} min={0} max={500}>
          <div className="flex items-center justify-between gap-2">
            <MeterLabel>Build minutes</MeterLabel>
            <MeterValue>{(_formatted, value) => `${value} / 500`}</MeterValue>
          </div>
          <MeterTrack>
            <MeterIndicator />
          </MeterTrack>
        </Meter>
      </div>
    </div>
  );
}
```

## API Reference

### Meter

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` | – | The current value. |
| `aria-valuetext` | `string` | – | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the meter. |
| `format` | `NumberFormatOptions` | – | Options to format the value. |
| `getAriaValueText` | `((formattedValue: string, value: number) => string)` | – | A function that returns a string value that provides a human-readable text alternative for `aria-valuenow`, the current value of the meter. |
| `locale` | `LocalesArgument` | – | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale. |
| `max` | `number` | `100` | The maximum value |
| `min` | `number` | `0` | The minimum value |

### MeterIndicator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### MeterLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### MeterTrack

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### MeterValue

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `((formattedValue: string, value: number) => ReactNode) \| null` | – | The content of the component. |

---

# Morphic Toast

> A toast that morphs out of a pill-shaped notification.

Source: https://ui.xiod.dev/docs/components/morphic-toast

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { MorphicToaster } from "xiod-ui/morphic-toast";
```

## Example

```tsx
"use client";

import { Sparkles as SparklesIcon } from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import { morphicToast } from "xiod-ui/morphic-toast";

const states = [
  {
    label: "Success",
    run: () =>
      morphicToast.success({
        title: "Success",
        description: "Your workspace settings have been saved.",
      }),
  },
  {
    label: "Error",
    run: () =>
      morphicToast.error({
        title: "Error",
        description: "Could not reach the database.",
        button: {
          title: "Retry",
          onClick: () =>
            morphicToast.success({
              title: "Connected",
              description: "The database is reachable again.",
            }),
        },
      }),
  },
  {
    label: "Warning",
    run: () =>
      morphicToast.warning({
        title: "Warning",
        description: "This workspace is at 90% of its storage limit.",
      }),
  },
  {
    label: "Info",
    run: () =>
      morphicToast.info({
        title: "Update available",
        description: "A newer version of XiodUI is ready to install.",
      }),
  },
];

// The toast morphs between shapes when an existing id is given a new state, so
// both examples here keep one toast alive rather than stacking a second one.
const morphs = [
  {
    label: "Loading → Success",
    run: () => {
      const id = morphicToast.show({
        type: "loading",
        title: "Uploading",
        description: "Sending project assets.",
        duration: null,
      });

      setTimeout(() => {
        morphicToast.success({
          id,
          title: "Uploaded",
          description: "All project assets are live.",
        });
      }, 2000);
    },
  },
  {
    label: "Promise",
    run: () => {
      const sync = new Promise((resolve) => setTimeout(resolve, 2000));

      morphicToast.promise(sync, {
        loading: { title: "Syncing", description: "Pulling remote changes." },
        success: { title: "Synced", description: "Everything is up to date." },
        error: { title: "Sync failed", description: "The sync timed out." },
      });
    },
  },
];

// Hoisted so the element is not re-created — and not mistaken for a component
// definition — on every render of the example.
const sparkles = <SparklesIcon className="size-3.5 text-white" />;

export default function MorphicToastExample() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-10">
      {/* States */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          States
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-3">
          {states.map(({ label, run }) => (
            <Button key={label} variant="outline" onClick={run}>
              {label}
            </Button>
          ))}
        </div>
      </div>

      {/* Morphing */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Morphing
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-3">
          {morphs.map(({ label, run }) => (
            <Button key={label} variant="outline" onClick={run}>
              {label}
            </Button>
          ))}
        </div>
      </div>

      {/* Custom */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Custom
        </Badge>
        <Button
          variant="outline"
          onClick={() =>
            morphicToast.show({
              title: "Indigo",
              description: "A custom fill, icon, and text colors.",
              fill: "#6366f1",
              icon: sparkles,
              styles: {
                badge: "bg-white/20 text-white border-0",
                title: "text-white font-bold",
                description: "text-indigo-100",
              },
            })
          }
        >
          Custom fill
        </Button>
      </div>
    </div>
  );
}
```

## API Reference

### MorphicToaster

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `offset` | `MorphicToastOffsetValue \| MorphicToastOffsetConfig` | – | The distance from the screen edges, as a number of pixels or a CSS length. Pass an object to set `top`, `right`, `bottom` and `left` separately; only the edges the toasts sit against apply. |
| `options` | `Partial<MorphicToastOptions>` | – | Defaults for every toast, such as `duration` or `styles`. Options passed to an individual toast override them. |
| `position` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left" \| "top-center" \| "bottom-center"` | `top-right` | Where toasts appear when they don't set their own `position`. |

---

# Navigation Menu

> Site navigation links with dropdown panels.

Source: https://ui.xiod.dev/docs/components/navigation-menu

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIcon,
  NavigationMenuIndicator,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuPopup,
  NavigationMenuPortal,
  NavigationMenuTrigger,
  NavigationMenuViewport
} from "xiod-ui/navigation-menu";
```

Anatomy:

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>
        <NavigationMenuIcon />
      </NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink />
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
  <NavigationMenuPopup>
    <NavigationMenuViewport />
  </NavigationMenuPopup>
</NavigationMenu>
```

## Example

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIcon,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuPopup,
  NavigationMenuTrigger,
  NavigationMenuViewport,
} from "xiod-ui/navigation-menu";

const overviewLinks = [
  {
    href: "/docs/overview/introduction",
    title: "Introduction",
    description: "What XiodUI is, how it's shipped, and its licence.",
  },
  {
    href: "/docs/overview/installation",
    title: "Installation",
    description: "Install the package, add the stylesheet, import a component.",
  },
  {
    href: "/docs/overview/agent-skill",
    title: "Agent Skill",
    description: "Teach coding agents XiodUI's real API.",
  },
  {
    href: "/changelog",
    title: "Changelog",
    description: "What changed in each release.",
  },
] as const;

const stylingLinks = [
  {
    href: "/docs/styling/colors",
    title: "Colors",
    description: "Every colour token, what it's for, and how tokens pair up.",
  },
  {
    href: "/docs/styling/themes",
    title: "Themes",
    description: "Ready-made palettes, and letting users switch between them.",
  },
  {
    href: "/docs/styling/dark-mode",
    title: "Dark Mode",
    description: "Light, dark and system modes with ThemeProvider.",
  },
] as const;

export default function NavigationMenuExample() {
  return (
    <div>
      <NavigationMenu>
        <NavigationMenuList>
          <NavigationMenuItem>
            <NavigationMenuTrigger>
              Overview
              <NavigationMenuIcon />
            </NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="grid list-none grid-cols-1 gap-2 p-2 w-[calc(100vw-3rem)] sm:w-[500px] sm:grid-cols-2 max-w-[480px] sm:max-w-none">
                <li className="row-span-3">
                  <NavigationMenuLink
                    className="flex h-full w-full select-none flex-col justify-end rounded-md bg-linear-to-b from-muted/50 to-muted p-6 no-underline outline-none focus:shadow-md"
                    href="/"
                  >
                    <div className="mb-2 mt-4 text-lg font-medium">XiodUI</div>
                    <p className="text-sm leading-tight text-muted-foreground">
                      Accessible React components built on Base UI and Tailwind
                      CSS 4.
                    </p>
                  </NavigationMenuLink>
                </li>
                {overviewLinks.map((item) => (
                  <li key={item.href}>
                    <NavigationMenuLink href={item.href}>
                      <div className="text-sm font-medium leading-none">
                        {item.title}
                      </div>
                      <p className="line-clamp-2 text-sm leading-snug text-muted-foreground mt-1.5">
                        {item.description}
                      </p>
                    </NavigationMenuLink>
                  </li>
                ))}
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>

          <NavigationMenuItem>
            <NavigationMenuTrigger>
              Styling
              <NavigationMenuIcon />
            </NavigationMenuTrigger>
            <NavigationMenuContent>
              <ul className="flex flex-col gap-2 p-4 w-[calc(100vw-3rem)] sm:w-[400px] max-w-[340px] sm:max-w-none">
                {stylingLinks.map((item) => (
                  <li key={item.href}>
                    <NavigationMenuLink href={item.href}>
                      <div className="text-sm font-medium leading-none">
                        {item.title}
                      </div>
                      <p className="line-clamp-2 text-sm leading-snug text-muted-foreground mt-1.5">
                        {item.description}
                      </p>
                    </NavigationMenuLink>
                  </li>
                ))}
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>

          <NavigationMenuItem>
            <NavigationMenuLink
              href="https://github.com/ImKKingshuk/XiodUI"
              className="group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:outline focus-visible:-outline-offset-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-64 data-popup-open:bg-accent/50 data-popup-open:text-accent-foreground sm:h-8"
            >
              GitHub
            </NavigationMenuLink>
          </NavigationMenuItem>
        </NavigationMenuList>

        {/* The popup portaled container orchestrates the animated frame constraints */}
        <NavigationMenuPopup>
          <NavigationMenuViewport />
        </NavigationMenuPopup>
      </NavigationMenu>
    </div>
  );
}
```

## API Reference

### NavigationMenu

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<NavigationMenuRootActions \| null>` | – | A ref to imperative actions. |
| `closeDelay` | `number` | `50` | How long to wait before closing the navigation popup. Specified in milliseconds. |
| `defaultValue` | `any` | `null` | The uncontrolled value of the item that should be initially selected. To render a controlled navigation menu, use the `value` prop instead. |
| `delay` | `number` | `50` | How long to wait before opening the navigation popup. Specified in milliseconds. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the navigation menu is closed. |
| `onValueChange` | `((value: any, eventDetails: NavigationMenuRootChangeEventDetails) => void)` | – | Callback fired when the value changes. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the navigation menu. |
| `value` | `any` | `null` | The controlled value of the navigation menu item that should be currently open. When non-nullish, the menu will be open. When nullish, the menu will be closed. To render an uncontrolled navigation menu, use the `defaultValue` prop instead. |

### NavigationMenuContent

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | Whether to keep the content mounted in the DOM while the popup is closed. Ensures the content is present during server-side rendering for web crawlers. |

### NavigationMenuIcon

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### NavigationMenuIndicator

Accepts `render`, plus every native `<div>` attribute.

### NavigationMenuItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – | A unique value that identifies this navigation menu item. If no value is provided, a unique ID will be generated automatically. Use when controlling the navigation menu programmatically. |

### NavigationMenuLink

Accepts `render`, plus every native `<a>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | – | Whether the link points to the current page. Marks it with `aria-current="page"`. |

### NavigationMenuList

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### NavigationMenuPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `center` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | – | Additional offset along the alignment axis, in pixels. |
| `anchor` | `NavigationMenu$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `10` | Distance between the anchor and the popup, in pixels. |

### NavigationMenuPortal

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | – | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |

### NavigationMenuTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### NavigationMenuViewport

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

---

# Number Field

> A numeric input with increment and decrement buttons.

Source: https://ui.xiod.dev/docs/components/number-field

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
  NumberFieldScrubArea
} from "xiod-ui/number-field";
```

Anatomy:

```tsx
<NumberField>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

## Example

```tsx
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "xiod-ui/number-field";

export default function NumberFieldExample() {
  return (
    <div className="w-1/2">
      <NumberField defaultValue={0}>
        <NumberFieldGroup>
          <NumberFieldDecrement />
          <NumberFieldInput />
          <NumberFieldIncrement />
        </NumberFieldGroup>
      </NumberField>
    </div>
  );
}
```

## API Reference

### NumberField

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allowOutOfRange` | `boolean` | `false` | When true, direct text entry may be outside the `min`/`max` range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp. |
| `allowWheelScrub` | `boolean` | `false` | Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input. |
| `defaultValue` | `number` | – | The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form. |
| `format` | `NumberFormatOptions` | – | Options to format the input value. |
| `id` | `string` | – | The id of the input element. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `largeStep` | `number` | `10` | The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value when `snapOnStep` is enabled. |
| `locale` | `LocalesArgument` | – | The locale of the input element. Defaults to the user's runtime locale. |
| `max` | `number` | – | The maximum value of the input element. |
| `min` | `number` | – | The minimum value of the input element. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onValueChange` | `((value: number \| null, eventDetails: NumberFieldRootChangeEventDetails) => void)` | – | Callback fired when the number value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for parseable typing or programmatic text updates - `'input-clear'` when the field becomes empty - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur - `'input-paste'` for paste interactions - `'keyboard'` for arrow-key/Home/End stepping (typing digits uses `'input-change'`/`'input-clear'`) - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls - `'wheel'` for wheel-based scrubbing - `'scrub'` for scrub area drags |
| `onValueCommitted` | `((value: number \| null, eventDetails: NumberFieldRootCommitEventDetails) => void)` | – | Callback function that is fired when the value is committed. It runs later than `onValueChange`, when: - The input is blurred after typing a value. - The pointer is released after scrubbing or pressing the increment/decrement buttons. It runs simultaneously with `onValueChange` when interacting with the keyboard or the mouse wheel. **Warning**: This is a generic event not a change event. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to change the field value. |
| `required` | `boolean` | `false` | Whether the user must enter a value before submitting a form. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `smallStep` | `number` | `0.1` | The small step value of the input element when incrementing while the alt key is held. Snaps to multiples of this value when `snapOnStep` is enabled. |
| `snapOnStep` | `boolean` | `false` | Whether the value should snap to the nearest step when incrementing or decrementing. |
| `step` | `number \| "any"` | `1` | Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop. Specify `step="any"` to always disable step validation; interactive stepping then uses a base amount of `1`, while the alt and shift keys still step by `smallStep` and `largeStep`. |
| `value` | `number \| null` | – | The raw numeric value of the field. |

### NumberFieldDecrement

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### NumberFieldGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### NumberFieldIncrement

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### NumberFieldInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-roledescription` | `string` | `'Number field'` | A user-friendly description of the input's role for assistive tech. This is a role description, not an accessible name — use `Field.Label` or `aria-label` to name the control. |

### NumberFieldScrubArea

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | The label text. Dragging across it changes the value. |
| `direction` | `"horizontal" \| "vertical"` | `'horizontal'` | Cursor movement direction in the scrub area. |
| `pixelSensitivity` | `number` | `2` | Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive. |
| `teleportDistance` | `number` | – | If specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around. |

---

# Option Picker

> A compact dropdown for choosing one option from a short list.

Source: https://ui.xiod.dev/docs/components/option-picker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { OptionPicker } from "xiod-ui/option-picker";
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  Eye as EyeIcon,
  Globe as GlobeIcon,
  Lock as LockIcon,
  Moon as MoonIcon,
  Computer as SystemIcon,
  Sun as SunIcon,
} from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { OptionPicker } from "xiod-ui/option-picker";

const visibilityOptions = [
  { id: "private", label: "Private", icon: LockIcon },
  { id: "public", label: "Public", icon: GlobeIcon },
  { id: "unlisted", label: "Unlisted", icon: EyeIcon },
];

const appearanceOptions = [
  { id: "light", label: "Light", icon: SunIcon },
  { id: "dark", label: "Dark", icon: MoonIcon },
  { id: "system", label: "System", icon: SystemIcon },
];

export default function OptionPickerExample() {
  const [visibility, setVisibility] = React.useState("private");

  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      {/* Controlled */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Controlled
        </Badge>
        <OptionPicker
          options={visibilityOptions}
          value={visibility}
          onChange={setVisibility}
        />
      </div>

      {/* Uncontrolled */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Uncontrolled
        </Badge>
        <OptionPicker options={appearanceOptions} defaultValue="system" />
      </div>
    </div>
  );
}
```

## API Reference

### OptionPicker

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `Option[]` | – | The options to choose from. Up to five are shown; any more are left out. |
| `defaultValue` | `string` | – | The `id` of the option selected at first, when it isn't controlled. Defaults to the first option. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `onChange` | `((value: string) => void)` | – | Called with the option's `id` when the user picks one. |
| `popupClassName` | `string` | – | Classes for the popup that lists the options. |
| `triggerClassName` | `string` | – | Classes for the button that shows the selected option. |
| `value` | `string` | – | The `id` of the selected option. Use with `onChange` to control it. |

---

# Orb

> An animated orb that shows what an AI assistant is doing, such as listening or working.

Source: https://ui.xiod.dev/docs/components/orb

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Orb, OrbBadge, OrbLabel } from "xiod-ui/orb";
```

Anatomy:

```tsx
<Orb />
<OrbBadge>
  <Orb />
  <OrbLabel />
</OrbBadge>
```

## Example

```tsx
"use client";

import { Badge } from "xiod-ui/badge";
import { Orb, OrbBadge, OrbLabel, type OrbState } from "xiod-ui/orb";

// Six of the thirty-five states. The full list is in the props table; these
// are the ones whose motion reads at this size, where the sparser fields —
// galaxy, supernova, vortex — barely register next to the dense ones.
const states: OrbState[] = [
  "working",
  "searching",
  "listening",
  "composing",
  "shaping",
  "torus",
];

const variants = [
  "default",
  "expressive",
  "classic",
  "sharp",
  "diamond",
  "ring",
  "cross",
] as const;

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;

const intents = [
  "default",
  "primary",
  "success",
  "warning",
  "destructive",
] as const;

function Caption({ children }: { children: string }) {
  return <span className="text-xs text-muted-foreground">{children}</span>;
}

export default function OrbExample() {
  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-10">
      {/* States */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          States
        </Badge>
        <div className="flex flex-wrap items-start justify-center gap-6">
          {states.map((state) => (
            <div key={state} className="flex flex-col items-center gap-2">
              <Orb state={state} size="lg" />
              <Caption>{state}</Caption>
            </div>
          ))}
        </div>
      </div>

      {/* Variants */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Variants
        </Badge>
        <div className="flex flex-wrap items-start justify-center gap-6">
          {variants.map((variant) => (
            <div key={variant} className="flex flex-col items-center gap-2">
              <Orb state="working" variant={variant} size="md" />
              <Caption>{variant}</Caption>
            </div>
          ))}
        </div>
      </div>

      {/* Sizes */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Sizes
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-6">
          {sizes.map((size) => (
            <Orb key={size} state="pulsing" size={size} />
          ))}
        </div>
      </div>

      {/* Intents */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Intents
        </Badge>
        <div className="flex flex-wrap items-center justify-center gap-6">
          {intents.map((intent) => (
            <Orb key={intent} state="listening" intent={intent} size="md" />
          ))}
          {/* `color` overrides the intent palette with any CSS color. */}
          <Orb state="listening" color="#8b5cf6" size="md" />
        </div>
      </div>

      {/* Badge */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Badge
        </Badge>
        <OrbBadge>
          <Orb state="working" size="xs" intent="primary" />
          <OrbLabel>Thinking</OrbLabel>
        </OrbBadge>
      </div>
    </div>
  );
}
```

## API Reference

### Orb

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | – | The name screen readers announce. Defaults to a label for the `state`, such as "Thinking…". |
| `color` | `string` | – | The colour of the dots, as a hex (`#f60`, `#ff6600`) or `rgb()` colour with comma-separated values. The dots are neutral when unset. |
| `glow` | `"none" \| "subtle" \| "intense"` | `none` | How strongly the orb glows in its own colour. |
| `intent` | `"default" \| "success" \| "warning" \| "info" \| "secondary" \| "destructive" \| "primary"` | `default` | The theme colour of the glow around the orb. The dots stay neutral unless you set `color`. |
| `interactive` | `boolean` | `false` | Whether the orb speeds up while the pointer is over it. |
| `paused` | `boolean` | `false` | Whether the animation is paused. It also stays still when the user prefers reduced motion. |
| `pixelSize` | `number` | – | The orb's width and height in pixels. Takes precedence over `size`. |
| `size` | `"sm" \| "md" \| "lg" \| "xs" \| "xl" \| "2xl"` | `lg` | The size of the component. |
| `speed` | `number` | `1` | How fast the orb animates, as a multiple of its normal speed. |
| `state` | `"thinking" \| "searching" \| "spiral" \| "pulse" \| "helix" \| "processing" \| "spark" \| "quantum" \| "matrix" \| "supernova" \| "working" \| "solving" \| "listening" \| "composing" \| "shaping" \| "pulsing" \| "vortex" \| "atom" \| "radar" \| "galaxy" \| "torus" \| "network" \| "analyzing" \| "beacon" \| "swarm" \| "nucleus" \| "dna" \| "sonar" \| "nebula" \| "donut" \| "ring_torus" \| "cube" \| "constellation" \| "nodes" \| "burst"` | `working` | What the orb is doing, which picks its animation. Some names share an animation, such as `thinking` and `working`. |
| `theme` | `"auto" \| "dark" \| "light"` | `auto` | Whether the orb is drawn for a dark or light background. `auto` follows the nearest `dark` or `light` class or `data-theme`, then the system setting. |
| `variant` | `"default" \| "diamond" \| "expressive" \| "sharp" \| "ring" \| "classic" \| "cross"` | `default` | The visual style of the component. |

### OrbBadge

Accepts `render`, plus every native attribute of the element it renders.

### OrbLabel

Accepts `render`, plus every native attribute of the element it renders.

---

# Pagination

> Links for moving between pages of results.

Source: https://ui.xiod.dev/docs/components/pagination

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationFirst,
  PaginationInput,
  PaginationItem,
  PaginationLast,
  PaginationLink,
  PaginationNext,
  PaginationPrevious
} from "xiod-ui/pagination";
```

Anatomy:

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

## Example

```tsx
"use client";

import * as React from "react";
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationFirst,
  PaginationInput,
  PaginationItem,
  PaginationLast,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "xiod-ui/pagination";

export default function PaginationExample() {
  const [page, setPage] = React.useState(1);
  const totalPages = 10;

  return (
    <div className="flex flex-col gap-8 w-full items-center">
      <div className="space-y-2 text-center">
        <h3 className="text-sm font-medium">Standard Pagination</h3>
        <Pagination>
          <PaginationContent>
            <PaginationItem>
              <PaginationPrevious href="#" />
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#">1</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#" isActive>
                2
              </PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#">3</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationEllipsis />
            </PaginationItem>
            <PaginationItem>
              <PaginationNext href="#" />
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      </div>

      <div className="space-y-2 text-center">
        <h3 className="text-sm font-medium">
          Advanced Pagination (Input & First/Last)
        </h3>
        <Pagination>
          <PaginationContent>
            <PaginationItem>
              <PaginationFirst
                href="#"
                onClick={(e) => {
                  e.preventDefault();
                  setPage(1);
                }}
                className={page <= 1 ? "pointer-events-none opacity-50" : ""}
              />
            </PaginationItem>
            <PaginationItem>
              <PaginationPrevious
                href="#"
                onClick={(e) => {
                  e.preventDefault();
                  setPage((p) => Math.max(1, p - 1));
                }}
                className={page <= 1 ? "pointer-events-none opacity-50" : ""}
              />
            </PaginationItem>

            <PaginationItem>
              <span className="text-sm text-muted-foreground mr-2">Page</span>
              <PaginationInput
                value={page}
                onChange={setPage}
                totalPages={totalPages}
              />
              <span className="text-sm text-muted-foreground ml-2">
                of {totalPages}
              </span>
            </PaginationItem>

            <PaginationItem>
              <PaginationNext
                href="#"
                onClick={(e) => {
                  e.preventDefault();
                  setPage((p) => Math.min(totalPages, p + 1));
                }}
                className={
                  page >= totalPages ? "pointer-events-none opacity-50" : ""
                }
              />
            </PaginationItem>
            <PaginationItem>
              <PaginationLast
                href="#"
                onClick={(e) => {
                  e.preventDefault();
                  setPage(totalPages);
                }}
                className={
                  page >= totalPages ? "pointer-events-none opacity-50" : ""
                }
              />
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      </div>
    </div>
  );
}
```

## API Reference

### Pagination

Accepts `render`, plus every native `<nav>` attribute.

### PaginationContent

Accepts `render`, plus every native `<ul>` attribute.

### PaginationEllipsis

Accepts `render`, plus every native `<span>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### PaginationFirst

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `isActive` | `boolean` | – | Whether the link is the current page. Highlights it and marks it with `aria-current="page"`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | – | The size of the component. |

### PaginationInput

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `((page: number) => void)` | – | Called with the page number when the user presses Enter or leaves the input. The number is clamped between 1 and `totalPages`. |
| `totalPages` | `number` | – | The number of pages. Entries above it are clamped to it. |
| `value` | `number` | – | The current page number. |

### PaginationItem

Accepts `render`, plus every native `<li>` attribute.

### PaginationLast

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `isActive` | `boolean` | – | Whether the link is the current page. Highlights it and marks it with `aria-current="page"`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | – | The size of the component. |

### PaginationLink

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | – | Whether the link is the current page. Highlights it and marks it with `aria-current="page"`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `icon` | The size of the component. |

### PaginationNext

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `isActive` | `boolean` | – | Whether the link is the current page. Highlights it and marks it with `aria-current="page"`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | – | The size of the component. |

### PaginationPrevious

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `isActive` | `boolean` | – | Whether the link is the current page. Highlights it and marks it with `aria-current="page"`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | – | The size of the component. |

---

# Popover

> A floating panel of content, opened from a button.

Source: https://ui.xiod.dev/docs/components/popover

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Popover,
  PopoverArrow,
  PopoverClose,
  PopoverDescription,
  PopoverPopup,
  PopoverTitle,
  PopoverTrigger,
  PopoverCreateHandle
} from "xiod-ui/popover";
```

Anatomy:

```tsx
<Popover>
  <PopoverTrigger />
  <PopoverPopup>
    <PopoverTitle />
    <PopoverDescription />
  </PopoverPopup>
</Popover>
```

## Example

```tsx
"use client";

import { Button } from "xiod-ui/button";
import { Field } from "xiod-ui/field";
import { Form } from "xiod-ui/form";
import {
  Popover,
  PopoverDescription,
  PopoverPopup,
  PopoverTitle,
  PopoverTrigger,
} from "xiod-ui/popover";
import { Textarea } from "xiod-ui/textarea";

export default function PopoverExample() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Open Popover
      </PopoverTrigger>
      <PopoverPopup className="w-80">
        <div className="mb-4">
          <PopoverTitle className="text-base">Send us feedback</PopoverTitle>
          <PopoverDescription>
            Let us know how we can improve.
          </PopoverDescription>
        </div>
        <Form>
          <Field>
            <Textarea
              aria-label="Send feedback"
              id="feedback"
              placeholder="How can we improve?"
            />
          </Field>
          <Button type="submit">Send feedback</Button>
        </Form>
      </PopoverPopup>
    </Popover>
  );
}
```

## API Reference

### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<PopoverRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - `close`: Closes the popover imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the popover is initially open. To render a controlled popover, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover. |
| `handle` | `PopoverHandle<Payload>` | – | A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state. |
| `modal` | `boolean \| "trap-focus"` | `false` | Determines if the popover enters a modal state when open. - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch screen readers can escape the popup. |
| `onOpenChange` | `((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)` | – | Event handler called when the popover is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the popover is opened or closed. |
| `open` | `boolean` | – | Whether the popover is currently open. |
| `triggerId` | `string \| null` | – | ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set). |

### PopoverArrow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### PopoverClose

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### PopoverDescription

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### PopoverPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `center` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Popover$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `collisionAvoidance` | `CollisionAvoidance` | – | How the popup avoids collisions with the edges of the viewport. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popover is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `8` | Distance between the anchor and the popup, in pixels. |
| `tooltipStyle` | `boolean` | `false` | Whether the popup uses the compact look of a tooltip: smaller text, tighter padding and a width that fits the content. |

### PopoverTitle

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### PopoverTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `delay` | `number` | `300` | How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop. |
| `handle` | `PopoverHandle<unknown>` | – | A handle to associate the trigger with a popover. |
| `id` | `string` | – | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop). |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`). |
| `openOnHover` | `boolean` | `false` | Whether the popover should also open when the trigger is hovered. |
| `payload` | `unknown` | – | A payload to pass to the popover when it is opened. |

### Helpers

`PopoverCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Preview Card

> A card that previews a link's content when the link is hovered or focused.

Source: https://ui.xiod.dev/docs/components/preview-card

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  PreviewCard,
  PreviewCardArrow,
  PreviewCardPopup,
  PreviewCardTrigger,
  PreviewCardCreateHandle
} from "xiod-ui/preview-card";
```

Anatomy:

```tsx
<PreviewCard>
  <PreviewCardTrigger />
  <PreviewCardPopup />
</PreviewCard>
<PreviewCardTrigger />
```

## Example

```tsx
"use client";

import {
  PreviewCard,
  PreviewCardCreateHandle,
  PreviewCardPopup,
  PreviewCardTrigger,
} from "xiod-ui/preview-card";

interface Package {
  name: string;
  description: string;
  href: string;
}

const XIOD_UI: Package = {
  name: "xiod-ui",
  description:
    "Accessible React components, palettes and themes in one npm package.",
  href: "https://www.npmjs.com/package/xiod-ui",
};

const BASE_UI: Package = {
  name: "Base UI",
  description:
    "Unstyled React components that handle focus, keyboard and screen readers.",
  href: "https://base-ui.com",
};

const XIOD_ICONS: Package = {
  name: "XiodIcons",
  description: "5,400+ React icons in six variants, tree-shakeable.",
  href: "https://icons.xiod.dev",
};

// Triggers outside a PreviewCard reach it through a handle. The card shows
// the payload of whichever trigger opened it.
const packageCard = PreviewCardCreateHandle<Package>();

function PackageSummary({ item }: { item: Package }) {
  return (
    <div className="flex max-w-64 flex-col gap-1">
      <p className="font-medium text-sm">{item.name}</p>
      <p className="text-muted-foreground text-sm">{item.description}</p>
    </div>
  );
}

const linkClassName =
  "font-medium text-foreground underline underline-offset-4";

export default function PreviewCardExample() {
  return (
    <p className="max-w-sm text-muted-foreground text-sm">
      <PreviewCard>
        <PreviewCardTrigger href={XIOD_UI.href} className={linkClassName}>
          xiod-ui
        </PreviewCardTrigger>
        <PreviewCardPopup>
          <PackageSummary item={XIOD_UI} />
        </PreviewCardPopup>
      </PreviewCard>{" "}
      builds on{" "}
      <PreviewCardTrigger
        handle={packageCard}
        payload={BASE_UI}
        href={BASE_UI.href}
        className={linkClassName}
      >
        Base UI
      </PreviewCardTrigger>{" "}
      and draws its icons from{" "}
      <PreviewCardTrigger
        handle={packageCard}
        payload={XIOD_ICONS}
        href={XIOD_ICONS.href}
        className={linkClassName}
      >
        XiodIcons
      </PreviewCardTrigger>
      .
      <PreviewCard handle={packageCard}>
        {({ payload }) => (
          <PreviewCardPopup>
            {payload && <PackageSummary item={payload} />}
          </PreviewCardPopup>
        )}
      </PreviewCard>
    </p>
  );
}
```

## API Reference

### PreviewCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<PreviewCardRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Unmounts the preview card popup. - `close`: Closes the preview card imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the preview card. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the preview card is initially open. To render a controlled preview card, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the preview card is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open preview card. |
| `handle` | `PreviewCardHandle<Payload>` | – | A handle to associate the preview card with a trigger. If specified, allows external triggers to control the card's open state. Can be created with the PreviewCard.createHandle() method. |
| `onOpenChange` | `((open: boolean, eventDetails: PreviewCardRootChangeEventDetails) => void)` | – | Event handler called when the preview card is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the preview card is opened or closed. |
| `open` | `boolean` | – | Whether the preview card is currently open. |
| `triggerId` | `string \| null` | – | ID of the trigger that the preview card is associated with. This is useful in conjunction with the `open` prop to create a controlled preview card. There's no need to specify this prop when the preview card is uncontrolled (that is, when the `open` prop is not set). |

### PreviewCardArrow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### PreviewCardPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `center` | How items line up vertically within their cells. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis, in pixels. |
| `anchor` | `PreviewCard$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `8` | Distance between the anchor and the popup, in pixels. |

### PreviewCardTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `300` | How long to wait before closing the preview card. Specified in milliseconds. |
| `delay` | `number` | `600` | How long to wait before the preview card opens. Specified in milliseconds. |
| `handle` | `PreviewCardHandle<unknown>` | – | A handle to associate the trigger with a preview card. |
| `payload` | `unknown` | – | A payload to pass to the preview card when it is opened. |

### Helpers

`PreviewCardCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Progress

> A bar that shows how far a task has progressed.

Source: https://ui.xiod.dev/docs/components/progress

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Progress,
  ProgressIndicator,
  ProgressLabel,
  ProgressTrack,
  ProgressValue
} from "xiod-ui/progress";
```

## Example

```tsx
"use client";

import { useEffect, useState } from "react";
import { Progress } from "xiod-ui/progress";

export default function ProgressExample() {
  const [value, setValue] = useState(20);

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((current) =>
        Math.min(100, Math.round(current + Math.random() * 25)),
      );
    }, 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div className="flex w-full md:w-1/2 flex-col gap-12">
      <div className="flex flex-col gap-6">
        {(["sm", "default", "lg", "xl", "2xl"] as const).map((size) => (
          <Progress key={size} size={size} value={value} />
        ))}
      </div>
      <div className="flex flex-col gap-6">
        {(["sm", "default", "lg", "xl", "2xl"] as const).map((size) => (
          <Progress key={size} variant="expressive" size={size} value={value} />
        ))}
      </div>
    </div>
  );
}
```

## API Reference

### Progress

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number \| null` | – | The current value. The component is indeterminate when value is `null`. |
| `aria-valuetext` | `string` | – | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar. |
| `format` | `NumberFormatOptions` | – | Options to format the value. |
| `getAriaValueText` | `((formattedValue: string, value: number \| null) => string)` | – | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar. |
| `locale` | `LocalesArgument` | – | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale. |
| `max` | `number` | `100` | The maximum value. |
| `min` | `number` | `0` | The minimum value. |
| `size` | `"sm" \| "lg" \| "default" \| "xl" \| "2xl"` | `default` | The size of the component. |
| `variant` | `"default" \| "expressive"` | `default` | The visual style of the component. |

### ProgressIndicator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ProgressLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ProgressTrack

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ProgressValue

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `((formattedValue: string \| null, value: number \| null) => ReactNode) \| null` | – | The content of the component. |

---

# Radio

> A set of options where only one can be selected.

Source: https://ui.xiod.dev/docs/components/radio

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Radio, RadioItem } from "xiod-ui/radio";
```

Anatomy:

```tsx
<Radio>
  <RadioItem />
</Radio>
```

## Example

```tsx
import { Label } from "xiod-ui/label";
import { Radio, RadioItem } from "xiod-ui/radio";

const radioVariants = [
  {
    title: "Default",
    value: "default",
  },
  {
    title: "Sharp",
    value: "sharp",
  },
  {
    title: "Diamond",
    value: "diamond",
  },
  {
    title: "Expressive",
    value: "expressive",
  },
] as const;

export default function RadioExample() {
  return (
    <div className="flex w-full flex-wrap items-start justify-center gap-12">
      {radioVariants.map(({ title, value }) => (
        <div className="flex flex-col gap-4" key={value}>
          <span className="text-sm font-medium text-muted-foreground">
            {title}
          </span>
          <Radio defaultValue="next">
            <Label>
              <RadioItem value="next" variant={value} /> Next.js
            </Label>
            <Label>
              <RadioItem value="vite" variant={value} /> Vite
            </Label>
            <Label>
              <RadioItem value="astro" variant={value} /> Astro
            </Label>
          </Radio>
        </div>
      ))}
    </div>
  );
}
```

## API Reference

### Radio

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `any` | – | The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onValueChange` | `((value: Value, eventDetails: RadioGroup.ChangeEventDetails) => void)` | – | Callback fired when the value changes. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to select a different radio button in the group. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `value` | `any` | – | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |

### RadioItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | The unique identifying value of the radio in a group. |
| `disabled` | `boolean` | – | Whether the component should ignore user interaction. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `readOnly` | `boolean` | – | Whether the user should be unable to select the radio button. |
| `required` | `boolean` | – | Whether the user must choose a value before submitting a form. |
| `variant` | `"default" \| "diamond" \| "expressive" \| "sharp"` | `default` | The visual style of the component. |

---

# Resizable

> Panels separated by handles the user can drag, or move with the arrow keys, to resize.

Source: https://ui.xiod.dev/docs/components/resizable

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "xiod-ui/resizable";
```

Anatomy:

```tsx
<ResizablePanelGroup>
  <ResizablePanel />
  <ResizableHandle />
</ResizablePanelGroup>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Badge } from "xiod-ui/badge";
import { useIsMobile } from "xiod-ui/hooks/use-media-query";
import {
  type ImperativePanelHandle,
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "xiod-ui/resizable";
import { Text } from "xiod-ui/text";

function PanelBody({ label }: { label: string }) {
  return (
    <div className="flex size-full items-center justify-center p-6">
      <Text className="text-sm font-medium text-muted-foreground">{label}</Text>
    </div>
  );
}

export default function ResizableExample() {
  const isMobile = useIsMobile();
  const sidebarRef = React.useRef<ImperativePanelHandle | null>(null);
  const direction = isMobile ? "vertical" : "horizontal";

  return (
    <div className="flex w-full max-w-3xl flex-col items-center gap-12">
      {/* Basic */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Basic
        </Badge>
        <div className="h-44 w-full overflow-hidden rounded-xl border bg-card/40">
          <ResizablePanelGroup direction={direction}>
            <ResizablePanel defaultSize="30%" minSize="15%" maxSize="60%">
              <PanelBody label="Sidebar" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="50%" minSize="20%">
              <PanelBody label="Content" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="20%" minSize="10%" maxSize="40%">
              <PanelBody label="Details" />
            </ResizablePanel>
          </ResizablePanelGroup>
        </div>
      </div>

      {/* Nested */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Nested
        </Badge>
        <div className="h-64 w-full overflow-hidden rounded-xl border bg-card/40">
          <ResizablePanelGroup
            direction={direction}
            storageKey="resizable-example-outer"
          >
            <ResizablePanel defaultSize="25%" minSize="15%" maxSize="40%">
              <PanelBody label="Explorer" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="75%">
              <ResizablePanelGroup
                direction={isMobile ? "horizontal" : "vertical"}
                storageKey="resizable-example-inner"
              >
                <ResizablePanel defaultSize="70%" minSize="30%">
                  <PanelBody label="Editor" />
                </ResizablePanel>
                <ResizableHandle withHandle />
                <ResizablePanel defaultSize="30%" minSize="15%">
                  <PanelBody label="Terminal" />
                </ResizablePanel>
              </ResizablePanelGroup>
            </ResizablePanel>
          </ResizablePanelGroup>
        </div>
      </div>

      {/* Collapsible */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Collapsible
        </Badge>
        <div className="h-44 w-full overflow-hidden rounded-xl border bg-card/40">
          <ResizablePanelGroup direction={direction}>
            <ResizablePanel
              panelRef={sidebarRef}
              defaultSize="25%"
              minSize="20%"
              maxSize="45%"
              collapsible
            >
              <PanelBody label="Drag to collapse" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="75%">
              <PanelBody label="Content" />
            </ResizablePanel>
          </ResizablePanelGroup>
        </div>
      </div>

      {/* Pixel constraints */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Pixel Constraints
        </Badge>
        <div className="h-44 w-full overflow-hidden rounded-xl border bg-card/40">
          <ResizablePanelGroup direction={direction}>
            <ResizablePanel
              defaultSize={isMobile ? "100px" : "200px"}
              minSize={isMobile ? "50px" : "150px"}
              maxSize={isMobile ? "150px" : "350px"}
              groupResizeBehavior="preserve-pixel-size"
            >
              <PanelBody label="150px – 350px" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="40%" disabled>
              <PanelBody label="Locked at 40%" />
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="30%">
              <PanelBody label="Fluid" />
            </ResizablePanel>
          </ResizablePanelGroup>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### ResizableHandle

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the user is prevented from dragging this handle. |
| `disableDoubleClick` | `boolean` | `false` | Whether double-clicking the handle leaves the panel before it as it is, instead of collapsing or expanding it. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `withHandle` | `boolean` | `false` | Whether to show a grip in the middle of the handle, so it's easier to see and grab. |

### ResizablePanel

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsedSize` | `string \| number` | `0%` | The panel's size when collapsed. A number is in pixels; a string can use `%`, `px`, `rem`, `em`, `vh` or `vw`. |
| `collapsible` | `boolean` | `false` | Whether the panel collapses to `collapsedSize` when dragged well below `minSize` (past halfway to `collapsedSize`), or when the handle after it is double-clicked. |
| `defaultSize` | `string \| number` | – | The panel's size at first. When no panel sets one, the space is split evenly. A number is in pixels; a string can use `%`, `px`, `rem`, `em`, `vh` or `vw`. |
| `disabled` | `boolean` | `false` | Whether the user is prevented from resizing this panel. `panelRef` can still resize it. |
| `groupResizeBehavior` | `"preserve-relative-size" \| "preserve-pixel-size"` | `preserve-relative-size` | What happens to the panel when the whole group changes size: `preserve-relative-size` keeps its share of the group, `preserve-pixel-size` keeps its width or height in pixels. |
| `id` | `string` | – | A stable id for the panel. Set it when the group has a `storageKey`, so the saved layout is matched to the right panels. |
| `maxSize` | `string \| number` | `100%` | The largest size the user can drag the panel to. A number is in pixels; a string can use `%`, `px`, `rem`, `em`, `vh` or `vw`. |
| `minSize` | `string \| number` | `0%` | The smallest size the user can drag the panel to. A number is in pixels; a string can use `%`, `px`, `rem`, `em`, `vh` or `vw`. |
| `onCollapse` | `(() => void)` | – | Called when the panel collapses. |
| `onExpand` | `(() => void)` | – | Called when the panel expands from collapsed. |
| `onResize` | `((size: { asPercentage: number; inPixels: number; }) => void)` | – | Called with the panel's new size, as a percentage of the group and in pixels, whenever it changes. |
| `panelRef` | `RefObject<ImperativePanelHandle \| null>` | – | A ref to control the panel from code: `collapse()`, `expand()`, `resize(size)`, `isCollapsed()`, `isExpanded()` and `getSize()`. |

### ResizablePanelGroup

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultLayout` | `(string \| number)[]` | – | The size of each panel at first, in order. Takes precedence over each panel's `defaultSize`. A number is in pixels; a string can use `%`, `px`, `rem`, `em`, `vh` or `vw`. |
| `direction` | `"horizontal" \| "vertical"` | `horizontal` | Whether the panels sit side by side (`horizontal`) or stacked (`vertical`). |
| `disabled` | `boolean` | `false` | Whether the user is prevented from resizing any panel. |
| `groupRef` | `RefObject<ImperativeGroupHandle \| null>` | – | A ref to read and set the whole layout from code, with `getLayout()` and `setLayout(layout)`. Sizes are percentages. |
| `onLayoutChange` | `((layout: number[]) => void)` | – | Called with each panel's size, as a percentage of the group, whenever the layout changes, including on every step of a drag. |
| `onLayoutChanged` | `((layout: number[]) => void)` | – | Called with each panel's size, as a percentage of the group, once the user finishes a resize: at the end of a drag, on a key press or on a double-click. |
| `storage` | `{ getItem: (key: string) => string \| null; setItem: (key: string, value: string) => void; }` | – | Where to save the layout when `storageKey` is set, instead of localStorage. |
| `storageKey` | `string` | – | A key to save the layout under, so it comes back on the next visit. Saved to localStorage unless you pass `storage`. Give each panel an `id` so the saved layout survives changes to the page. |

---

# Ruler Picker

> A value picker drawn as a ruler the user scrolls along.

Source: https://ui.xiod.dev/docs/components/ruler-picker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { RulerPicker } from "xiod-ui/ruler-picker";
```

## Example

```tsx
"use client";

import * as React from "react";
import { RulerPicker } from "xiod-ui/ruler-picker";

export default function RulerPickerExample() {
  const [val1, setVal1] = React.useState(15);
  const [val2, setVal2] = React.useState(50);
  const [val3, setVal3] = React.useState(75);

  return (
    <div className="flex w-full md:w-1/2 flex-col gap-12">
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Small Size (sm)
        </span>
        <RulerPicker
          size="sm"
          min={0}
          max={30}
          value={val1}
          onChange={setVal1}
          itemWidth={60}
          subDivisions={4}
        />
        <div className="text-sm text-foreground/80">
          Value: <span className="font-semibold tabular-nums">{val1}</span>
        </div>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Medium Size (md)
        </span>
        <RulerPicker
          size="md"
          min={0}
          max={100}
          value={val2}
          onChange={setVal2}
          itemWidth={80}
          subDivisions={4}
        />
        <div className="text-sm text-foreground/80">
          Value: <span className="font-semibold tabular-nums">{val2}</span>
        </div>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Large Size (lg)
        </span>
        <RulerPicker
          size="lg"
          min={0}
          max={100}
          value={val3}
          onChange={setVal3}
          itemWidth={100}
          subDivisions={9}
        />
        <div className="text-sm text-foreground/80">
          Value: <span className="font-semibold tabular-nums">{val3}</span>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### RulerPicker

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `number` | – | The value selected at first, when it isn't controlled. Defaults to `min`. |
| `itemWidth` | `number` | `80` | The distance between two whole-number marks, in pixels. |
| `max` | `number` | `100` | The highest value on the ruler. |
| `min` | `number` | `0` | The lowest value on the ruler. |
| `onChange` | `((value: number) => void)` | – | Called with the new value as the ruler settles on a mark, by scrolling, dragging or the arrow keys. |
| `size` | `"sm" \| "md" \| "lg"` | `md` | The size of the component. |
| `subDivisions` | `number` | `4` | The number of small ticks drawn between two whole-number marks. With `9`, the middle tick is drawn longer. |
| `value` | `number` | – | The selected whole number. Use with `onChange` to control it. |

---

# Scroll Area

> A scrollable region with styled scrollbars.

Source: https://ui.xiod.dev/docs/components/scroll-area

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { ScrollArea, ScrollBar } from "xiod-ui/scroll-area";
```

## Example

```tsx
import { ScrollArea } from "xiod-ui/scroll-area";

const tags = Array.from({ length: 50 }, (_, i) => `v1.0.0-alpha.${i}`);

export default function ScrollAreaExample() {
  return (
    <ScrollArea className="h-64 w-1/2 rounded-lg border">
      <div className="px-4 py-2">
        <h4 className="mb-2 font-medium text-sm">Tags</h4>
        <div className="flex flex-col gap-1">
          {tags.map((tag) => (
            <div className="text-sm" key={tag}>
              {tag}
            </div>
          ))}
        </div>
      </div>
    </ScrollArea>
  );
}
```

## API Reference

### ScrollArea

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflowEdgeThreshold` | `number \| Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>` | `0` | The threshold in pixels that must be passed before the overflow edge attributes are applied. Accepts a single number for all edges or an object to configure them individually. |
| `scrollbarGutter` | `boolean` | `false` | Whether to reserve space for the scrollbars so they don't overlap the content. |
| `scrollbarSize` | `"sm" \| "md" \| "lg"` | `sm` | The thickness of the scrollbars. |
| `scrollbarVariant` | `"default" \| "card"` | `default` | The scrollbar style. `card` gives the track a background and border. |
| `scrollbarVisibility` | `"always" \| "auto" \| "hover"` | `auto` | When the scrollbars show: `auto` while scrolling or hovered, `hover` only while hovered, `always` all the time. |
| `scrollFade` | `boolean` | `false` | Whether the content fades out at an edge that has more to scroll to. |

### ScrollBar

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | Whether to keep the HTML element in the DOM when the viewport isn't scrollable. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | Whether the scrollbar controls vertical or horizontal scroll. |
| `size` | `"sm" \| "md" \| "lg"` | – | The size of the component. |
| `variant` | `"default" \| "card"` | – | The visual style of the component. |
| `visibility` | `"always" \| "auto" \| "hover"` | – | When the scrollbar shows: `auto` while scrolling or hovered, `hover` only while hovered, `always` all the time. |

---

# Scroll Bar

> A styled scrollbar that expands on hover and can hide when idle.

Source: https://ui.xiod.dev/docs/components/scroll-bar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { ScrollBar } from "xiod-ui/scroll-bar";
```

## Example

```tsx
"use client";

import { ScrollArea } from "xiod-ui/scroll-area";

export default function ScrollBarExample() {
  const dummyItems = Array.from(
    { length: 30 },
    (_, i) => `Item number ${i + 1}`,
  );

  return (
    <div className="flex w-full flex-col gap-12">
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 w-full">
        {/* Size sm, visibility always */}
        <div className="flex flex-col gap-3">
          <span className="text-sm font-semibold text-foreground/90">
            Small Size (sm) + Always Visible
          </span>
          <div className="h-60 border border-border bg-card/30 rounded-xl overflow-hidden p-1">
            <ScrollArea
              scrollbarSize="sm"
              scrollbarVisibility="always"
              className="h-full"
            >
              <div className="flex flex-col gap-1 p-3">
                {dummyItems.map((item, idx) => (
                  <div
                    key={idx}
                    className="px-3 py-2 text-xs text-muted-foreground bg-muted/20 border border-border/30 rounded-md"
                  >
                    {item}
                  </div>
                ))}
              </div>
            </ScrollArea>
          </div>
        </div>

        {/* Size md (default), visibility auto */}
        <div className="flex flex-col gap-3">
          <span className="text-sm font-semibold text-foreground/90">
            Medium Size (md) + Auto Hide
          </span>
          <div className="h-60 border border-border bg-card/30 rounded-xl overflow-hidden p-1">
            <ScrollArea
              scrollbarSize="md"
              scrollbarVisibility="auto"
              className="h-full"
            >
              <div className="flex flex-col gap-1 p-3">
                {dummyItems.map((item, idx) => (
                  <div
                    key={idx}
                    className="px-3 py-2 text-xs text-muted-foreground bg-muted/20 border border-border/30 rounded-md"
                  >
                    {item}
                  </div>
                ))}
              </div>
            </ScrollArea>
          </div>
        </div>

        {/* Size lg, visibility hover-only */}
        <div className="flex flex-col gap-3">
          <span className="text-sm font-semibold text-foreground/90">
            Large Size (lg) + Hover Only
          </span>
          <div className="h-60 border border-border bg-card/30 rounded-xl overflow-hidden p-1">
            <ScrollArea
              scrollbarSize="lg"
              scrollbarVisibility="hover"
              className="h-full"
            >
              <div className="flex flex-col gap-1 p-3">
                {dummyItems.map((item, idx) => (
                  <div
                    key={idx}
                    className="px-3 py-2 text-xs text-muted-foreground bg-muted/20 border border-border/30 rounded-md"
                  >
                    {item}
                  </div>
                ))}
              </div>
            </ScrollArea>
          </div>
        </div>

        {/* Variant Card, Size md, Always Visible */}
        <div className="flex flex-col gap-3">
          <span className="text-sm font-semibold text-foreground/90">
            Card Track Variant + MD Size
          </span>
          <div className="h-60 border border-border bg-card/30 rounded-xl overflow-hidden p-1">
            <ScrollArea
              scrollbarSize="md"
              scrollbarVariant="card"
              scrollbarVisibility="always"
              className="h-full"
            >
              <div className="flex flex-col gap-1 p-3">
                {dummyItems.map((item, idx) => (
                  <div
                    key={idx}
                    className="px-3 py-2 text-xs text-muted-foreground bg-muted/20 border border-border/30 rounded-md"
                  >
                    {item}
                  </div>
                ))}
              </div>
            </ScrollArea>
          </div>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### ScrollBar

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | Whether to keep the HTML element in the DOM when the viewport isn't scrollable. |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | Whether the scrollbar controls vertical or horizontal scroll. |
| `size` | `"sm" \| "md" \| "lg"` | `sm` | The size of the component. |
| `variant` | `"default" \| "card"` | `default` | The visual style of the component. |
| `visibility` | `"always" \| "auto" \| "hover"` | `auto` | When the scrollbar shows: `auto` while scrolling or hovered, `hover` only while hovered, `always` all the time. |

---

# Select

> A button that opens a list of options to choose from.

Source: https://ui.xiod.dev/docs/components/select

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Select,
  SelectButton,
  SelectGroup,
  SelectGroupLabel,
  SelectItem,
  SelectPopup,
  SelectSeparator,
  SelectTrigger,
  SelectValue
} from "xiod-ui/select";
```

Anatomy:

```tsx
<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectPopup>
    <SelectItem />
  </SelectPopup>
</Select>
```

## Example

```tsx
import {
  Select,
  SelectItem,
  SelectPopup,
  SelectTrigger,
  SelectValue,
} from "xiod-ui/select";

const items = [
  { label: "Select framework", value: null },
  { label: "Next.js", value: "next" },
  { label: "Vite", value: "vite" },
  { label: "Astro", value: "astro" },
];

export default function SelectExample() {
  return (
    <div className="">
      <Select aria-label="Select framework" defaultValue="next" items={items}>
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectPopup>
          {items.map(({ label, value }) => (
            <SelectItem key={value} value={value}>
              {label}
            </SelectItem>
          ))}
        </SelectPopup>
      </Select>
    </div>
  );
}
```

## API Reference

### Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<SelectRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Manually unmounts the select. Call this after any externally controlled closing animation finishes. |
| `autoComplete` | `string` | – | Provides a hint to the browser for autofill. |
| `children` | `ReactNode` | – | The content of the component. |
| `defaultOpen` | `boolean` | `false` | Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead. |
| `defaultValue` | `SelectValueType<Value, Multiple> \| null` | – | The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. |
| `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| `id` | `string` | – | The id of the Select. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden input element. |
| `isItemEqualToValue` | `((itemValue: Value, value: Value) => boolean)` | – | Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison. |
| `items` | `readonly Group<any>[] \| Record<string, ReactNode> \| readonly { label: ReactNode; value: any; }[]` | – | Data structure of the items rendered in the select popup. When specified, `<Select.Value>` renders the label of the selected item instead of the raw value. |
| `itemToStringLabel` | `((itemValue: Value) => string)` | – | When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for display in the trigger. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
| `itemToStringValue` | `((itemValue: Value) => string)` | – | When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. |
| `modal` | `boolean` | `true` | Determines if the select enters a modal state when open. - `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. |
| `multiple` | `Multiple` | `false` | Whether multiple items can be selected. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onOpenChange` | `((open: boolean, eventDetails: SelectRootChangeEventDetails) => void)` | – | Event handler called when the select popup is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the select popup is opened or closed. |
| `onValueChange` | `((value: SelectValueType<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)` | – | Event handler called when the value of the select changes. |
| `open` | `boolean` | – | Whether the select popup is currently open. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to choose a different option from the select popup. |
| `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. |
| `value` | `SelectValueType<Value, Multiple> \| null` | – | The value of the select. Use when controlled. |

### SelectButton

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |

### SelectGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### SelectGroupLabel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### SelectItem

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `label` | `string` | – | Specifies the text label to use when the item is matched during keyboard text navigation. Defaults to the item text content if not provided. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `value` | `any` | `null` | A unique value that identifies this select item. |

### SelectPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `start` | How items line up vertically within their cells. |
| `alignItemWithTrigger` | `boolean` | `true` | Whether the popup opens with the selected item placed over the trigger, like a native select. When `false`, the popup opens beside the trigger. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis, in pixels. |
| `anchor` | `Select$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `children` | `ReactNode` | – | The content of the component. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | – | Determines the element to focus when the select popup is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing. |
| `scrollDownIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `scrollUpIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `bottom` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `4` | Distance between the anchor and the popup, in pixels. |

### SelectSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### SelectTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `disabled` | `boolean` | – | Whether the component should ignore user interaction. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |

### SelectValue

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((value: any) => ReactNode)` | – | Accepts a function that returns a `ReactNode` to format the selected value. Treat the value as read-only: in `multiple` mode it may be a shared frozen array when nothing is selected. |
| `placeholder` | `ReactNode` | – | The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`. |

---

# Separator

> A horizontal or vertical line between content.

Source: https://ui.xiod.dev/docs/components/separator

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Separator } from "xiod-ui/separator";
```

## Example

```tsx
import { Separator } from "xiod-ui/separator";

export default function SeparatorExample() {
  return (
    <div className="max-w-72">
      <div className="space-y-1">
        <h4 className="font-medium text-sm">XiodUI</h4>
        <p className="text-muted-foreground text-sm">
          Accessible React components built on Base UI and Tailwind CSS 4.
        </p>
      </div>
      <Separator className="my-4" />
      <div className="flex items-center gap-4 text-sm">
        <div>Blog</div>
        <Separator orientation="vertical" />
        <div>Docs</div>
        <Separator orientation="vertical" />
        <div>Source</div>
        <Separator orientation="vertical" />
        <div>Releases</div>
      </div>
    </div>
  );
}
```

## API Reference

### Separator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

---

# Sidebar

> A collapsible side panel for app navigation.

Source: https://ui.xiod.dev/docs/components/sidebar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInput,
  SidebarInset,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSkeleton,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarSeparator,
  SidebarTrigger
} from "xiod-ui/sidebar";
```

Anatomy:

```tsx
<SidebarProvider>
  <Sidebar>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel />
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton />
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
  </Sidebar>
  <SidebarTrigger />
</SidebarProvider>
```

## Example

```tsx
import {
  Calendar as CalendarIcon,
  Home as HomeIcon,
  Inbox as InboxIcon,
  Search as SearchIcon,
  Settings as SettingsIcon,
} from "xiod-icons";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "xiod-ui/sidebar";

const items = [
  { title: "Home", url: "#", icon: HomeIcon },
  { title: "Inbox", url: "#", icon: InboxIcon },
  { title: "Calendar", url: "#", icon: CalendarIcon },
  { title: "Search", url: "#", icon: SearchIcon },
  { title: "Settings", url: "#", icon: SettingsIcon },
];

export default function SidebarExample() {
  return (
    <SidebarProvider className="w-full relative h-[400px] min-h-0 overflow-hidden border border-border/40 rounded-lg shadow-sm">
      <Sidebar
        variant="inset"
        className="absolute inset-y-0 left-0 h-full border-r"
      >
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Application</SidebarGroupLabel>
            <SidebarGroupContent>
              <SidebarMenu>
                {items.map((item) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      render={<a aria-label={item.title} href={item.url} />}
                    >
                      <item.icon className="size-4" />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroupContent>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
      <main className="flex flex-1 flex-col p-4 w-full h-full relative overflow-auto bg-background">
        <div className="flex items-center gap-2 mb-4 shrink-0">
          <SidebarTrigger className="-ml-1" />
          <span className="font-semibold text-sm">Dashboard</span>
        </div>
        <div className="flex-1 rounded-lg border border-dashed bg-muted/40 grid place-items-center">
          <span className="text-muted-foreground text-sm">Main Content</span>
        </div>
      </main>
    </SidebarProvider>
  );
}
```

## API Reference

### Sidebar

every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsible` | `"none" \| "icon" \| "offcanvas"` | `offcanvas` | How the sidebar collapses: `offcanvas` slides it out of view, `icon` shrinks it to a strip of icons, and `none` keeps it open. |
| `side` | `"left" \| "right"` | `left` | The side of the screen the sidebar sits on. |
| `variant` | `"modal" \| "inset" \| "sidebar" \| "floating"` | `sidebar` | The visual style of the component. |

### SidebarContent

every native `<div>` attribute.

### SidebarFooter

Accepts `render`, plus every native `<div>` attribute.

### SidebarGroup

Accepts `render`, plus every native `<div>` attribute.

### SidebarGroupAction

Accepts `render`, plus every native `<button>` attribute.

### SidebarGroupContent

Accepts `render`, plus every native `<div>` attribute.

### SidebarGroupLabel

Accepts `render`, plus every native `<div>` attribute.

### SidebarHeader

Accepts `render`, plus every native `<div>` attribute.

### SidebarInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The default value of the input. Use when uncontrolled. |
| `nativeInput` | `boolean` | – | Whether to render a plain `<input>` instead of Base UI's `Input`. A plain input doesn't register with a surrounding `Field`. |
| `onValueChange` | `((value: string, eventDetails: Input.ChangeEventDetails) => void)` | – | Callback fired when the `value` changes. Use when controlled. |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `unstyled` | `boolean` | – | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |
| `value` | `string \| number \| readonly string[]` | – | The value of the input. Use when controlled. |

### SidebarInset

Accepts `render`, plus every native `<main>` attribute.

### SidebarMenu

Accepts `render`, plus every native `<ul>` attribute.

### SidebarMenuAction

Accepts `render`, plus every native `<button>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showOnHover` | `boolean` | `false` | Whether the action is hidden on larger screens until its menu item is hovered or focused. |

### SidebarMenuBadge

Accepts `render`, plus every native `<div>` attribute.

### SidebarMenuButton

Accepts `render`, plus every native `<button>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | Whether the button is for the current page or view. Highlights it. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `tooltip` | `string \| React$1.ComponentProps<typeof TooltipPopup>` | – | A tooltip shown beside the button while the sidebar is collapsed to icons: its text, or props for `TooltipPopup`. |
| `variant` | `"default" \| "outline"` | `default` | The visual style of the component. |

### SidebarMenuItem

Accepts `render`, plus every native `<li>` attribute.

### SidebarMenuSkeleton

Accepts `render`, plus every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showIcon` | `boolean` | `false` | Whether the placeholder includes a square for an icon. |

### SidebarMenuSub

Accepts `render`, plus every native `<ul>` attribute.

### SidebarMenuSubButton

Accepts `render`, plus every native `<a>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | Whether the link is for the current page or view. Highlights it. |
| `size` | `"sm" \| "md"` | `md` | The size of the component. |

### SidebarMenuSubItem

Accepts `render`, plus every native `<li>` attribute.

### SidebarProvider

every native `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `true` | Whether the sidebar is expanded at first, when it isn't controlled. |
| `onOpenChange` | `((open: boolean) => void)` | – | Called when the sidebar expands or collapses on larger screens, including through the ⌘B or Ctrl+B shortcut. |
| `open` | `boolean` | – | Whether the sidebar is expanded on larger screens. Use with `onOpenChange` to control it. On mobile, the sidebar opens as a sheet with its own state. |

### SidebarRail

Accepts `render`, plus every native `<button>` attribute.

### SidebarSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

### SidebarTrigger

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `size` | `"sm" \| "lg" \| "default" \| "xs" \| "xl" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xl" \| "icon-xs"` | `default` | The size of the component. |
| `variant` | `"link" \| "default" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "destructive-outline"` | `default` | The visual style of the component. |

---

# Skeleton

> A placeholder shape shown while content loads.

Source: https://ui.xiod.dev/docs/components/skeleton

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Skeleton } from "xiod-ui/skeleton";
```

## Example

```tsx
"use client";

import { useEffect, useState } from "react";
import {
  UserAdd as UserRoundPlusIcon,
  UserGroup as UsersRoundIcon,
} from "xiod-icons";
import { Avatar, AvatarFallback, AvatarImage } from "xiod-ui/avatar";
import { Button } from "xiod-ui/button";
import { Skeleton } from "xiod-ui/skeleton";

const users = [
  {
    delay: 3000,
    fallback: "OP",
    followers: "15k",
    image: "/placeholder.svg",
    name: "Optimus Prime",
    role: "Design Engineer",
  },
  {
    delay: 4000,
    fallback: "SH",
    followers: "8k",
    image: "/placeholder.svg",
    name: "Sonic the Hedgehog",
    role: "Product Designer",
  },
  {
    delay: 3400,
    fallback: "DO",
    followers: "12k",
    image: "/placeholder.svg",
    name: "Doraemon",
    role: "UI/UX Designer",
  },
];

function UserCard({ delay, user }: { delay: number; user: (typeof users)[0] }) {
  const [isLoaded, setIsLoaded] = useState(false);

  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, delay);

    return () => clearTimeout(timer);
  }, [delay]);

  if (!isLoaded) {
    return <UserCardSkeleton />;
  }

  return (
    <>
      <Avatar className="size-10">
        <AvatarImage alt={user.name} src={user.image} />
        <AvatarFallback>{user.fallback}</AvatarFallback>
      </Avatar>
      <div className="flex min-w-0 flex-1 flex-col gap-1">
        <h4 className="line-clamp-1 font-medium text-sm">{user.name}</h4>
        <div className="flex items-center gap-3 text-muted-foreground text-xs">
          <span className="truncate">{user.role}</span>
          <div className="flex min-w-0 items-center gap-1">
            <UsersRoundIcon className="size-3 shrink-0" />
            <span className="truncate">
              {user.followers}
              <span className="max-sm:hidden"> followers</span>
            </span>
          </div>
        </div>
      </div>
      <Button size="xs">
        <UserRoundPlusIcon />
        Follow
      </Button>
    </>
  );
}

function UserCardSkeleton() {
  return (
    <>
      <Skeleton className="size-10 rounded-full" />
      <div className="flex flex-1 flex-col">
        <Skeleton className="my-0.5 h-4 max-w-54" />
        <div className="flex max-w-54 items-center gap-1">
          <Skeleton className="my-0.5 h-4 w-1/2" />
          <Skeleton className="my-0.5 h-4 w-1/2" />
        </div>
      </div>
      <Skeleton className="h-7 w-19 sm:h-6 sm:w-17" />
    </>
  );
}

export default function SkeletonExample() {
  return (
    <div className="flex w-full max-w-92 flex-col gap-6">
      {users.map((user) => (
        <div className="flex items-center gap-4" key={user.fallback}>
          <UserCard delay={user.delay} user={user} />
        </div>
      ))}
    </div>
  );
}
```

## API Reference

### Skeleton

Accepts `render`, plus every native `<div>` attribute.

---

# Slider

> A control for picking a value or range by dragging a thumb along a track.

Source: https://ui.xiod.dev/docs/components/slider

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Slider, SliderValue } from "xiod-ui/slider";
```

## Example

```tsx
import { Slider } from "xiod-ui/slider";

export default function SliderExample() {
  return (
    <div className="flex w-full md:w-1/2 flex-col gap-12">
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Default
        </span>
        <Slider defaultValue={50} />
      </div>
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Expressive
        </span>
        <Slider defaultValue={50} variant="expressive" />
      </div>
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Classic
        </span>
        <Slider defaultValue={50} variant="classic" />
      </div>
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">Fader</span>
        <Slider defaultValue={35} variant="fader" />
      </div>
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Segmented
        </span>
        <Slider defaultValue={40} variant="segmented" />
      </div>
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Dotted
        </span>
        <Slider defaultValue={45} variant="dotted" />
      </div>
    </div>
  );
}
```

## API Reference

### Slider

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `number \| readonly number[]` | – | The uncontrolled value of the slider when it's initially rendered. To render a controlled slider, use the `value` prop instead. |
| `disabled` | `boolean` | `false` | Whether the slider should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the slider inputs. Useful when the slider is rendered outside the form. |
| `format` | `NumberFormatOptions` | – | Options to format the value. |
| `largeStep` | `number` | `10` | The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down. |
| `locale` | `LocalesArgument` | – | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale. |
| `max` | `number` | `100` | The maximum allowed value of the slider. Should not be equal to min. |
| `min` | `number` | `0` | The minimum allowed value of the slider. Should not be equal to max. |
| `minStepsBetweenValues` | `number` | `0` | The minimum steps between values in a range slider. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `onValueChange` | `((value: number \| readonly number[], eventDetails: SliderRootChangeEventDetails) => void)` | – | Callback function that is fired when the slider's value changed. Receives the new value as the first argument; the originating event is available as `eventDetails.event`. The value is also reflected on `eventDetails.event.target.value` for form integration. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` when the hidden range input emits a change event (for example, via form integration) - `'track-press'` when the control track is pressed - `'drag'` while dragging a thumb - `'keyboard'` for keyboard input - `'none'` when the change is triggered without a specific interaction |
| `onValueCommitted` | `((value: number \| readonly number[], eventDetails: SliderRootCommitEventDetails) => void)` | – | Callback function that is fired when a value change is committed. Does not fire if the value did not change, or if the change was canceled. **Warning**: This is a generic event, not a change event. The `eventDetails.reason` indicates what triggered the commit: - `'drag'` while dragging a thumb - `'track-press'` when the control track is pressed - `'keyboard'` for keyboard input - `'input-change'` when the hidden range input emits a change event (for example, via form integration) - `'none'` when the commit occurs without a specific interaction |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The component orientation. |
| `step` | `number` | `1` | The granularity with which the slider can step through values. (A "discrete" slider.) The `min` prop serves as the origin for the valid values. We recommend (max - min) to be evenly divisible by the step. |
| `thumbAlignment` | `"center" \| "edge" \| "edge-client-only"` | `'center'` | How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`: - `center`: The center of the thumb is aligned with the control edge - `edge`: The thumb is inset within the control such that its edge is aligned with the control edge - `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return |
| `thumbCollisionBehavior` | `"none" \| "push" \| "swap"` | `'push'` | Controls how thumbs behave when they collide during pointer interactions. - `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back. - `'swap'`: Thumbs swap places when dragged past each other. - `'none'`: Thumbs cannot move past each other; excess movement is ignored. |
| `value` | `number \| readonly number[]` | – | The value of the slider. For range sliders, provide an array with one value per thumb. |
| `variant` | `"default" \| "expressive" \| "classic" \| "fader" \| "segmented" \| "dotted"` | `default` | The visual style of the component. |

### SliderValue

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `((formattedValues: readonly string[], values: readonly number[]) => ReactNode) \| null` | – | The content of the component. |

---

# Sortable

> A list or grid the user can reorder by dragging or with the keyboard.

Source: https://ui.xiod.dev/docs/components/sortable

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Sortable,
  SortableColumn,
  SortableColumnHeader,
  SortableColumnTitle,
  SortableItem,
  SortableItemHandle,
  SortableItemRemove
} from "xiod-ui/sortable";
```

Anatomy:

```tsx
<Sortable>
  <SortableItem>
    <SortableItemHandle />
    <SortableItemRemove />
  </SortableItem>
</Sortable>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Badge } from "xiod-ui/badge";
import {
  Sortable,
  SortableItem,
  SortableItemHandle,
  SortableItemRemove,
} from "xiod-ui/sortable";

const initialTasks = [
  "Refactor design tokens",
  "Optimize the orb canvas",
  "Audit accessibility",
  "Add touch targets",
];

const initialTags = ["Design", "Docs", "Perf", "A11y", "Mobile", "Tooling"];

export default function SortableExample() {
  const [tasks, setTasks] = React.useState(initialTasks);
  const [tags, setTags] = React.useState(initialTags);

  return (
    <div className="flex w-full max-w-md flex-col items-center gap-10">
      {/* Vertical */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Vertical
        </Badge>
        <Sortable
          className="w-full"
          items={tasks}
          variant="bordered"
          onReorder={setTasks}
          onRemove={(id) =>
            setTasks((prev) => prev.filter((task) => task !== id))
          }
        >
          {tasks.map((task) => (
            <SortableItem key={task} id={task} className="p-3">
              <SortableItemHandle />
              <span className="flex-1 truncate text-sm">{task}</span>
              <SortableItemRemove id={task} />
            </SortableItem>
          ))}
        </Sortable>
      </div>

      {/* Grid */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Grid
        </Badge>
        <Sortable
          className="w-full"
          items={tags}
          orientation="grid"
          onReorder={setTags}
        >
          {tags.map((tag) => (
            <SortableItem key={tag} id={tag} variant="accent" className="p-3">
              <SortableItemHandle />
              <span className="flex-1 truncate text-sm">{tag}</span>
            </SortableItem>
          ))}
        </Sortable>
      </div>
    </div>
  );
}
```

## API Reference

### Sortable

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `string[]` | – | The ids of the items, in their current order. Each `SortableItem` finds its place by its `id`. |
| `onReorder` (required) | `(newItems: string[]) => void` | – | Called with the ids in their new order whenever an item moves: on drop with a pointer, or on each arrow key while moving one with the keyboard. Escape during a keyboard move calls it again with the original order. |
| `handleIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `onRemove` | `((id: string) => void)` | – | Called with an item's id when its `SortableItemRemove` button is pressed. |
| `orientation` | `"grid" \| "horizontal" \| "vertical"` | `vertical` | Whether the items are laid out horizontally or vertically. |
| `variant` | `"default" \| "ghost" \| "bordered"` | `default` | The visual style of the component. |

### SortableColumn

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The column's id. It also names the column for screen readers unless you pass `aria-label`. |

### SortableColumnHeader

Accepts `render`, plus every native attribute of the element it renders.

### SortableColumnTitle

Accepts `render`, plus every native attribute of the element it renders.

### SortableItem

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The item's id, as listed in the `Sortable`'s `items`. |
| `variant` | `"default" \| "flat" \| "accent"` | `default` | The visual style of the component. |

### SortableItemHandle

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

### SortableItemRemove

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The id of the item to remove, passed to the `Sortable`'s `onRemove`. |
| `icon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |

---

# Switch

> A toggle for turning a setting on or off.

Source: https://ui.xiod.dev/docs/components/switch

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Switch } from "xiod-ui/switch";
```

## Example

```tsx
import { Label } from "xiod-ui/label";
import { Switch } from "xiod-ui/switch";

const switchSizes = ["sm", "md", "lg", "xl", "2xl"] as const;

export default function SwitchExample() {
  return (
    <div className="flex flex-col gap-6 mx-auto ">
      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Default
        </span>
        <Label>
          <Switch />
          Marketing emails
        </Label>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Classic
        </span>
        <Label>
          <Switch variant="classic" />
          System notifications
        </Label>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">
          Expressive
        </span>
        <Label>
          <Switch variant="expressive" />
          Analytics tracking
        </Label>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">Sharp</span>
        <Label>
          <Switch variant="sharp" />
          Advanced settings
        </Label>
      </div>

      <div className="flex flex-col gap-4">
        <span className="text-sm font-medium text-muted-foreground">Sizes</span>
        <div className="flex flex-wrap items-end gap-4 sm:gap-6">
          {switchSizes.map((size) => (
            <div className="flex flex-col items-center gap-3" key={size}>
              <Switch defaultChecked={size !== "sm"} size={size} />
              <span className="text-muted-foreground text-xs font-medium uppercase tracking-[0.18em]">
                {size}
              </span>
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Switch

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – | Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead. |
| `defaultChecked` | `boolean` | `false` | Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `form` | `string` | – | Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form. |
| `id` | `string` | – | The id of the hidden input element. When `nativeButton` is `true`, the id is applied to the root element. |
| `inputRef` | `Ref<HTMLInputElement>` | – | A ref to access the hidden `<input>` element. |
| `name` | `string` | – | Identifies the field when a form is submitted. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `onCheckedChange` | `((checked: boolean, eventDetails: SwitchRoot.ChangeEventDetails) => void)` | – | Event handler called when the switch is activated or deactivated. |
| `readOnly` | `boolean` | `false` | Whether the user should be unable to activate or deactivate the switch. |
| `required` | `boolean` | `false` | Whether the user must activate the switch before submitting a form. |
| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `md` | The size of the component. |
| `uncheckedValue` | `string` | – | The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior. |
| `value` | `string` | – | The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior. |
| `variant` | `"default" \| "expressive" \| "sharp" \| "classic"` | `default` | The visual style of the component. |

---

# Table

> A table for rows of data.

Source: https://ui.xiod.dev/docs/components/table

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow
} from "xiod-ui/table";
```

Anatomy:

```tsx
<Table>
  <TableCaption />
  <TableHeader>
    <TableRow>
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableFooter>
</Table>
```

## Example

```tsx
import { Badge } from "xiod-ui/badge";
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "xiod-ui/table";

export default function TableExample() {
  return (
    <div className="w-full overflow-x-auto rounded-xl border bg-card/40">
      <Table>
        <TableCaption>A list of current projects.</TableCaption>
        <TableHeader>
          <TableRow>
            <TableHead>Project</TableHead>
            <TableHead>Status</TableHead>
            <TableHead>Team</TableHead>
            <TableHead className="text-right">Budget</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell className="font-medium">Website Redesign</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-emerald-500"
                />
                Paid
              </Badge>
            </TableCell>
            <TableCell>Frontend Team</TableCell>
            <TableCell className="text-right">$12,500</TableCell>
          </TableRow>
          <TableRow>
            <TableCell className="font-medium">Mobile App</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-muted-foreground/64"
                />
                Unpaid
              </Badge>
            </TableCell>
            <TableCell>Mobile Team</TableCell>
            <TableCell className="text-right">$8,750</TableCell>
          </TableRow>
          <TableRow>
            <TableCell className="font-medium">API Integration</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-amber-500"
                />
                Pending
              </Badge>
            </TableCell>
            <TableCell>Backend Team</TableCell>
            <TableCell className="text-right">$5,200</TableCell>
          </TableRow>
          <TableRow>
            <TableCell className="font-medium">Database Migration</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-emerald-500"
                />
                Paid
              </Badge>
            </TableCell>
            <TableCell>DevOps Team</TableCell>
            <TableCell className="text-right">$3,800</TableCell>
          </TableRow>
          <TableRow>
            <TableCell className="font-medium">User Dashboard</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-emerald-500"
                />
                Paid
              </Badge>
            </TableCell>
            <TableCell>UX Team</TableCell>
            <TableCell className="text-right">$7,200</TableCell>
          </TableRow>
          <TableRow>
            <TableCell className="font-medium">Security Audit</TableCell>
            <TableCell>
              <Badge variant="outline">
                <span
                  aria-hidden="true"
                  className="size-1.5 rounded-full bg-red-500"
                />
                Failed
              </Badge>
            </TableCell>
            <TableCell>Security Team</TableCell>
            <TableCell className="text-right">$2,100</TableCell>
          </TableRow>
        </TableBody>
        <TableFooter>
          <TableRow>
            <TableCell colSpan={3}>Total Budget</TableCell>
            <TableCell className="text-right">$39,550</TableCell>
          </TableRow>
        </TableFooter>
      </Table>
    </div>
  );
}
```

## API Reference

### Table

Accepts `render`, plus every native `<table>` attribute.

### TableBody

Accepts `render`, plus every native `<tbody>` attribute.

### TableCaption

Accepts `render`, plus every native `<caption>` attribute.

### TableCell

Accepts `render`, plus every native `<td>` attribute.

### TableFooter

Accepts `render`, plus every native `<tfoot>` attribute.

### TableHead

Accepts `render`, plus every native `<th>` attribute.

### TableHeader

Accepts `render`, plus every native `<thead>` attribute.

### TableRow

Accepts `render`, plus every native `<tr>` attribute.

---

# Tabs

> Switches between panels of content, one visible at a time.

Source: https://ui.xiod.dev/docs/components/tabs

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Tabs,
  TabsList,
  TabsPanel,
  TabsTab
} from "xiod-ui/tabs";
```

Anatomy:

```tsx
<Tabs>
  <TabsList>
    <TabsTab />
  </TabsList>
  <TabsPanel />
</Tabs>
```

## Example

```tsx
import { Tabs, TabsList, TabsPanel, TabsTab } from "xiod-ui/tabs";

export default function TabsExample() {
  return (
    <Tabs defaultValue="tab-1">
      <TabsList>
        <TabsTab value="tab-1">Tab 1</TabsTab>
        <TabsTab value="tab-2">Tab 2</TabsTab>
        <TabsTab value="tab-3">Tab 3</TabsTab>
      </TabsList>
      <TabsPanel value="tab-1">
        <p className="p-4 text-center text-muted-foreground text-xs">
          Tab 1 content
        </p>
      </TabsPanel>
      <TabsPanel value="tab-2">
        <p className="p-4 text-center text-muted-foreground text-xs">
          Tab 2 content
        </p>
      </TabsPanel>
      <TabsPanel value="tab-3">
        <p className="p-4 text-center text-muted-foreground text-xs">
          Tab 3 content
        </p>
      </TabsPanel>
    </Tabs>
  );
}
```

## API Reference

### Tabs

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `any` | `0` | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
| `onValueChange` | `((value: any, eventDetails: TabsRootChangeEventDetails) => void)` | – | Callback invoked when new value is being set. The event `reason` is `'none'` for user-initiated changes, such as a click or keyboard navigation; `'initial'` for the first automatic selection or fallback in uncontrolled roots when `defaultValue` is omitted or `undefined`, including when the implicit initial value is disabled or missing; `'disabled'` for automatic fallback when the selected tab becomes disabled in uncontrolled roots; or `'missing'` for automatic fallback when the selected tab is removed, or when an explicit `defaultValue` never matches a mounted tab in uncontrolled roots. For automatic changes, the selected value can be `null` when no enabled Tab is available as a fallback. Automatic changes cannot be canceled; calling `eventDetails.cancel()` for `'initial'`, `'disabled'`, or `'missing'` has no effect. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The component orientation (layout flow direction). |
| `value` | `any` | – | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |

### TabsList

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `activateOnFocus` | `boolean` | `false` | Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `variant` | `"default" \| "underline"` | `default` | The visual style of the component. |

### TabsPanel

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | The value of the TabPanel. It will be shown when the Tab with the corresponding value is active. |
| `keepMounted` | `boolean` | `false` | Whether to keep the HTML element in the DOM while the panel is hidden. |

### TabsTab

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `any` | – | The value of the Tab. |
| `disabled` | `boolean` | – | Whether the Tab is disabled. If a first Tab on a `<Tabs.List>` is disabled, it won't initially be selected. Instead, the next enabled Tab will be selected. However, it does not work like this during server-side rendering, as it is not known during pre-rendering which Tabs are disabled. To work around it, ensure that `defaultValue` or `value` on `<Tabs.Root>` is set to an enabled Tab's value. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

---

# Text

> Text in the library's type scale, rendered as any element.

Source: https://ui.xiod.dev/docs/components/text

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Text } from "xiod-ui/text";
```

## Example

```tsx
import { Text } from "xiod-ui/text";

export default function TextExample() {
  return (
    <div className="flex flex-col gap-6 w-full">
      <div className="flex flex-col gap-2">
        <Text variant="heading1">The quick brown fox</Text>
        <Text variant="heading2">Jumps over the lazy dog</Text>
        <Text variant="heading3">Almost before we knew it</Text>
      </div>
      <div className="flex flex-col gap-2">
        <Text variant="body">
          This is default body text. It is used for standard paragraphs and
          longer form content.
        </Text>
        <Text variant="secondary">
          Secondary text used for less important information or descriptions.
        </Text>
        <Text variant="mono">const message = "Hello, World!";</Text>
      </div>
    </div>
  );
}
```

## API Reference

### Text

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"none" \| "sm" \| "lg" \| "default" \| "xs" \| "xl"` | `default` | The size of the component. |
| `truncate` | `boolean \| null` | – | Whether to keep the text on one line and cut it off with an ellipsis. |
| `variant` | `"body" \| "error" \| "success" \| "warning" \| "info" \| "secondary" \| "heading1" \| "heading2" \| "heading3" \| "heading4" \| "mono" \| "mono-secondary"` | `body` | The visual style of the component. |
| `weight` | `"normal" \| "medium" \| "semibold" \| "bold"` | – | The font weight. When unset, the variant's own weight applies. |

---

# Textarea

> A multi-line text input.

Source: https://ui.xiod.dev/docs/components/textarea

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Textarea } from "xiod-ui/textarea";
```

## Example

```tsx
import { Textarea } from "xiod-ui/textarea";

export default function TextareaExample() {
  return (
    <div className="w-full md:w-1/2">
      <Textarea placeholder="Type your message here" />
    </div>
  );
}
```

## API Reference

### Textarea

every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number \| "sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `unstyled` | `boolean` | `false` | Whether to drop the border, background and focus ring, leaving only the text field. Use inside your own styled container. |

---

# Timeline

> Events or steps in order, vertical or horizontal, that can also track progress as a stepper.

Source: https://ui.xiod.dev/docs/components/timeline

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Timeline,
  TimelineItem,
  TimelineHeader,
  TimelineTitle,
  TimelineDate,
  TimelineContent,
  TimelineIndicator,
  TimelineSeparator,
  TimelineContext
} from "xiod-ui/timeline";
```

Anatomy:

```tsx
<Timeline>
  <TimelineItem>
    <TimelineSeparator />
    <TimelineIndicator />
    <TimelineHeader>
      <TimelineTitle />
      <TimelineDate />
    </TimelineHeader>
    <TimelineContent />
  </TimelineItem>
</Timeline>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Check as CheckIcon } from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import { useIsMobile } from "xiod-ui/hooks/use-media-query";
import {
  Timeline,
  TimelineContent,
  TimelineDate,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "xiod-ui/timeline";

const steps = [
  { step: 1, title: "Account details", body: "Tell us who you are." },
  { step: 2, title: "Payment method", body: "Add a card or connect PayPal." },
  { step: 3, title: "Review order", body: "Check everything before you pay." },
];

export default function TimelineExample() {
  const [activeStep, setActiveStep] = React.useState(2);
  // Horizontal timelines need room for every item's label side by side, so the
  // preview's narrow viewports fall back to the vertical layout.
  const isMobile = useIsMobile();

  return (
    <div className="flex w-full max-w-2xl flex-col items-center gap-12">
      {/* Vertical */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Vertical
        </Badge>
        <Timeline className="w-full">
          <TimelineItem status="completed">
            <TimelineSeparator />
            <TimelineIndicator variant="solid" />
            <TimelineHeader>
              <TimelineTitle>Kickoff</TimelineTitle>
              <TimelineDate>Sep 2, 2026</TimelineDate>
            </TimelineHeader>
            <TimelineContent>
              Scope and goals agreed with the team.
            </TimelineContent>
          </TimelineItem>

          <TimelineItem status="completed">
            <TimelineSeparator />
            <TimelineIndicator variant="solid" />
            <TimelineHeader>
              <TimelineTitle>Design review</TimelineTitle>
              <TimelineDate>Sep 16, 2026</TimelineDate>
            </TimelineHeader>
            <TimelineContent>
              Mockups approved, with two flows simplified.
            </TimelineContent>
          </TimelineItem>

          <TimelineItem status="pending">
            <TimelineIndicator />
            <TimelineHeader>
              <TimelineTitle>Public launch</TimelineTitle>
              <TimelineDate>Oct 1, 2026</TimelineDate>
            </TimelineHeader>
            <TimelineContent>Released to every user.</TimelineContent>
          </TimelineItem>
        </Timeline>
      </div>

      {/* Horizontal */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Horizontal
        </Badge>
        <Timeline
          className="w-full"
          orientation={isMobile ? "vertical" : "horizontal"}
        >
          <TimelineItem status="completed">
            <TimelineSeparator />
            <TimelineIndicator variant="solid" />
            <TimelineHeader>
              <TimelineTitle>Ordered</TimelineTitle>
            </TimelineHeader>
            <TimelineContent>We have your order.</TimelineContent>
          </TimelineItem>

          <TimelineItem status="active">
            <TimelineSeparator />
            <TimelineIndicator className="border-primary" />
            <TimelineHeader>
              <TimelineTitle>Packing</TimelineTitle>
            </TimelineHeader>
            <TimelineContent>Your items are being prepared.</TimelineContent>
          </TimelineItem>

          <TimelineItem status="pending">
            <TimelineIndicator />
            <TimelineHeader>
              <TimelineTitle>Shipped</TimelineTitle>
            </TimelineHeader>
            <TimelineContent>On its way to you.</TimelineContent>
          </TimelineItem>
        </Timeline>
      </div>

      {/* Stepper */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Stepper
        </Badge>
        {/* With `value`, each item's `step` decides on its own whether it is
            completed, active, or pending — no per-item status prop. */}
        <Timeline
          className="w-full"
          value={activeStep}
          onValueChange={setActiveStep}
        >
          {steps.map(({ step, title, body }) => (
            <TimelineItem key={step} step={step}>
              <TimelineSeparator />
              <TimelineIndicator variant="solid">
                {activeStep > step && (
                  <CheckIcon className="size-3 text-primary-foreground" />
                )}
              </TimelineIndicator>
              <TimelineHeader>
                <TimelineTitle>{title}</TimelineTitle>
              </TimelineHeader>
              <TimelineContent>{body}</TimelineContent>
            </TimelineItem>
          ))}
        </Timeline>
        <div className="flex gap-3">
          <Button
            variant="outline"
            disabled={activeStep <= 1}
            onClick={() => setActiveStep(activeStep - 1)}
          >
            Back
          </Button>
          <Button
            disabled={activeStep > steps.length}
            onClick={() => setActiveStep(activeStep + 1)}
          >
            {activeStep === steps.length ? "Finish" : "Next"}
          </Button>
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### Timeline

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `number` | – | The step that is active at first, when it isn't controlled. Items before it show as completed and items after it as pending. |
| `onValueChange` | `((value: number) => void)` | – | Called with the new step when the active step changes through `setActiveStep` from `useTimeline`. |
| `orientation` | `"horizontal" \| "vertical"` | `vertical` | Whether the items are laid out horizontally or vertically. |
| `value` | `number` | – | The active step. Items before it show as completed and items after it as pending. |

### TimelineItem

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"completed" \| "active" \| "pending"` | – | The item's status. Overrides the one worked out from `step`. |
| `step` | `number` | – | The item's position in the timeline, compared with the `Timeline`'s value to work out its status. |

### TimelineHeader

Accepts `render`, plus every native `<div>` attribute.

### TimelineTitle

Accepts `render`, plus every native `<h3>` attribute.

### TimelineDate

Accepts `render`, plus every native `<time>` attribute.

### TimelineContent

Accepts `render`, plus every native `<div>` attribute.

### TimelineIndicator

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `variant` | `"default" \| "solid"` | `default` | The visual style of the component. |

### TimelineSeparator

Accepts `render`, plus every native `<div>` attribute.

### TimelineContext

every native attribute of the element it renders.

---

# Toast

> A short message that appears briefly without interrupting the user.

Source: https://ui.xiod.dev/docs/components/toast

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { AnchoredToastProvider, ToastProvider } from "xiod-ui/toast";
```

## Example

```tsx
"use client";

import { Button } from "xiod-ui/button";
import { toastManager } from "xiod-ui/toast";

export default function ToastExample() {
  return (
    <div className="flex gap-4">
      <Button
        onClick={() => {
          toastManager.add({
            description: "Monday, January 3rd at 6:00pm",
            title: "Event has been created",
          });
        }}
        variant="outline"
      >
        Default Toast
      </Button>

      <Button
        onClick={() => {
          toastManager.add({
            description: "Click the X icon to dismiss this toast.",
            title: "Toast with Close Button",
            data: {
              closeButton: true,
            },
          });
        }}
        variant="outline"
      >
        Toast with Close Button
      </Button>
    </div>
  );
}
```

## API Reference

### AnchoredToastProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `closeButton` | `boolean` | `false` | Whether every toast shows a close button. A toast's own `closeButton` overrides this. |
| `closeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `limit` | `number` | `3` | The maximum number of toasts that can be displayed at once. When the limit is exceeded, the oldest toasts are marked as `limited` (via the `data-limited` attribute) rather than removed, so they can be hidden or animated out. |
| `timeout` | `number` | `5000` | The default amount of time (in ms) before a toast is auto dismissed. A value of `0` will prevent the toast from being dismissed automatically. |
| `toastManager` | `ToastManager<any>` | – | A global manager for toasts to use outside of a React component. |

### ToastProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `closeButton` | `boolean` | `false` | Whether every toast shows a close button. A toast's own `closeButton` overrides this. |
| `closeIcon` | `ReactNode` | – | Replaces this icon. Accepts any node; `null` renders no icon. Takes precedence over `IconProvider`. |
| `limit` | `number` | `3` | The maximum number of toasts that can be displayed at once. When the limit is exceeded, the oldest toasts are marked as `limited` (via the `data-limited` attribute) rather than removed, so they can be hidden or animated out. |
| `position` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left" \| "top-center" \| "bottom-center"` | `bottom-right` | The corner or edge of the screen where toasts appear. |
| `timeout` | `number` | `5000` | The default amount of time (in ms) before a toast is auto dismissed. A value of `0` will prevent the toast from being dismissed automatically. |
| `toastManager` | `ToastManager<any>` | – | A global manager for toasts to use outside of a React component. |

---

# Toggle

> A button that stays pressed or unpressed.

Source: https://ui.xiod.dev/docs/components/toggle

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { Toggle } from "xiod-ui/toggle";
```

## Example

```tsx
import { Toggle } from "xiod-ui/toggle";

export default function ToggleExample() {
  return <Toggle variant="outline">Toggle</Toggle>;
}
```

## API Reference

### Toggle

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultPressed` | `boolean` | `false` | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`. |
| `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `onPressedChange` | `((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void)` | – | Callback fired when the pressed state is changed. |
| `pressed` | `boolean` | – | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `string` | – | A unique string that identifies the toggle when used inside a toggle group. |
| `variant` | `"default" \| "outline"` | `default` | The visual style of the component. |

---

# Toggle Group

> A set of toggle buttons where one or several can be pressed.

Source: https://ui.xiod.dev/docs/components/toggle-group

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { ToggleGroup, ToggleGroupSeparator } from "xiod-ui/toggle-group";
```

## Example

```tsx
import {
  Bold as BoldIcon,
  TextItalic as ItalicIcon,
  TextUnderline as UnderlineIcon,
} from "xiod-icons";
import { ToggleGroup, ToggleGroupItem } from "xiod-ui/toggle-group";

export default function ToggleGroupExample() {
  return (
    <ToggleGroup defaultValue={["bold"]}>
      <ToggleGroupItem aria-label="Toggle bold" value="bold">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle italic" value="italic">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle underline" value="underline">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

## API Reference

### ToggleGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `readonly string[]` | – | The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`. |
| `disabled` | `boolean` | `false` | Whether the toggle group should ignore user interaction. |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `multiple` | `boolean` | `false` | When `false` only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When `true` multiple items can be pressed. |
| `onValueChange` | `((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void)` | – | Callback fired when the pressed states of the toggle group changes. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | Whether the items are laid out horizontally or vertically. |
| `size` | `"sm" \| "lg" \| "default"` | `default` | The size of the component. |
| `value` | `readonly string[]` | – | The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`. |
| `variant` | `"default" \| "outline"` | `default` | The visual style of the component. |

### ToggleGroupSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |

---

# Toolbar

> A row of buttons and controls, navigable with the arrow keys.

Source: https://ui.xiod.dev/docs/components/toolbar

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarInput,
  ToolbarLink,
  ToolbarSeparator
} from "xiod-ui/toolbar";
```

Anatomy:

```tsx
<Toolbar>
  <ToolbarSeparator />
  <ToolbarGroup>
    <ToolbarButton />
  </ToolbarGroup>
</Toolbar>
```

## Example

```tsx
"use client";

import {
  TextAlignCenter as AlignCenterIcon,
  AlignLeft as AlignLeftIcon,
  AlignRight as AlignRightIcon,
  DollarSign as DollarSignIcon,
  Percent as PercentIcon,
} from "xiod-icons";
import { Button } from "xiod-ui/button";
import {
  Select,
  SelectItem,
  SelectPopup,
  SelectTrigger,
  SelectValue,
} from "xiod-ui/select";
import { ToggleGroup, ToggleGroupItem } from "xiod-ui/toggle-group";
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarSeparator,
} from "xiod-ui/toolbar";
import {
  Tooltip,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
} from "xiod-ui/tooltip";

const items = [
  { label: "Helvetica", value: "helvetica" },
  { label: "Arial", value: "arial" },
  { label: "Times New Roman", value: "times-new-roman" },
];

export default function ToolbarExample() {
  return (
    <TooltipProvider>
      <Toolbar>
        <ToggleGroup className="border-none p-0" defaultValue={["left"]}>
          <Tooltip>
            <TooltipTrigger
              render={
                <ToolbarButton
                  aria-label="Align left"
                  render={<ToggleGroupItem value="left" />}
                >
                  <AlignLeftIcon />
                </ToolbarButton>
              }
            />
            <TooltipPopup sideOffset={8}>Align left</TooltipPopup>
          </Tooltip>
          <Tooltip>
            <TooltipTrigger
              render={
                <ToolbarButton
                  aria-label="Align center"
                  render={
                    <ToggleGroupItem
                      aria-label="Toggle center"
                      value="center"
                    />
                  }
                >
                  <AlignCenterIcon />
                </ToolbarButton>
              }
            />
            <TooltipPopup sideOffset={8}>Align center</TooltipPopup>
          </Tooltip>
          <Tooltip>
            <TooltipTrigger
              render={
                <ToolbarButton
                  aria-label="Align right"
                  render={
                    <ToggleGroupItem aria-label="Toggle right" value="right" />
                  }
                >
                  <AlignRightIcon />
                </ToolbarButton>
              }
            />
            <TooltipPopup sideOffset={8}>Align right</TooltipPopup>
          </Tooltip>
        </ToggleGroup>
        <ToolbarSeparator />
        <ToolbarGroup>
          <Tooltip>
            <TooltipTrigger
              render={
                <ToolbarButton
                  aria-label="Format as currency"
                  render={<Button size="icon" variant="ghost" />}
                >
                  <DollarSignIcon />
                </ToolbarButton>
              }
            />
            <TooltipPopup sideOffset={8}>Format as currency</TooltipPopup>
          </Tooltip>
          <Tooltip>
            <TooltipTrigger
              render={
                <ToolbarButton
                  aria-label="Format as percent"
                  render={<Button size="icon" variant="ghost" />}
                >
                  <PercentIcon />
                </ToolbarButton>
              }
            />
            <TooltipPopup sideOffset={8}>Format as percent</TooltipPopup>
          </Tooltip>
        </ToolbarGroup>
        <ToolbarSeparator />
        <ToolbarGroup>
          <Select defaultValue="helvetica" items={items}>
            <Tooltip>
              <TooltipTrigger
                render={
                  <ToolbarButton
                    render={
                      <SelectTrigger>
                        <SelectValue />
                      </SelectTrigger>
                    }
                  />
                }
              />
              <TooltipPopup sideOffset={8}>
                Select a different font
              </TooltipPopup>
            </Tooltip>
            <SelectPopup>
              {items.map(({ label, value }) => (
                <SelectItem key={value} value={value}>
                  {label}
                </SelectItem>
              ))}
            </SelectPopup>
          </Select>
        </ToolbarGroup>
        <ToolbarSeparator />
        <ToolbarGroup>
          <ToolbarButton render={<Button />}>Save</ToolbarButton>
        </ToolbarGroup>
      </Toolbar>
    </TooltipProvider>
  );
}
```

## API Reference

### Toolbar

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | – | When `true` the item is disabled. |
| `loopFocus` | `boolean` | `true` | If `true`, using keyboard navigation will wrap focus to the other end of the toolbar once the end is reached. |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the toolbar. |

### ToolbarButton

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | When `true` the item is disabled. |
| `focusableWhenDisabled` | `boolean` | `true` | When `true` the item remains focusable when disabled. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |

### ToolbarGroup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | When `true` all toolbar items in the group are disabled. |

### ToolbarInput

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| number \| readonly string[]` | – | The value the input starts with, when it isn't controlled. |
| `disabled` | `boolean` | `false` | When `true` the item is disabled. |
| `focusableWhenDisabled` | `boolean` | `true` | When `true` the item remains focusable when disabled. |

### ToolbarLink

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### ToolbarSeparator

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. Defaults to the opposite of the toolbar's orientation, so a horizontal toolbar renders vertical separators. |

---

# Tooltip

> A short label that appears when an element is hovered or focused.

Source: https://ui.xiod.dev/docs/components/tooltip

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Tooltip,
  TooltipArrow,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
  TooltipCreateHandle
} from "xiod-ui/tooltip";
```

Anatomy:

```tsx
<Tooltip>
  <TooltipTrigger />
  <TooltipPopup />
</Tooltip>
```

## Example

```tsx
import { Button } from "xiod-ui/button";
import { Tooltip, TooltipPopup, TooltipTrigger } from "xiod-ui/tooltip";

export default function TooltipExample() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>
        Hover me
      </TooltipTrigger>
      <TooltipPopup>Helpful hint</TooltipPopup>
    </Tooltip>
  );
}
```

## API Reference

### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<TooltipRootActions \| null>` | – | A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<Payload>` | – | The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | – | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip. |
| `disabled` | `boolean` | `false` | Whether the tooltip is disabled. |
| `disableHoverablePopup` | `boolean` | `false` | Whether the tooltip contents can be hovered without closing the tooltip. |
| `handle` | `TooltipHandle<Payload>` | – | A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method. |
| `onOpenChange` | `((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)` | – | Event handler called when the tooltip is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | – | Event handler called after any animations complete when the tooltip is opened or closed. |
| `open` | `boolean` | – | Whether the tooltip is currently open. |
| `trackCursorAxis` | `"none" \| "both" \| "x" \| "y"` | `'none'` | Determines which axis the tooltip should track the cursor on. |
| `triggerId` | `string \| null` | – | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set). |

### TooltipArrow

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

### TooltipPopup

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end"` | `center` | How items line up vertically within their cells. |
| `anchor` | `Tooltip$1.Positioner.Props["anchor"]` | – | An element to position the popup against. Defaults to the trigger. |
| `hideArrow` | `boolean` | `false` | Whether to hide the arrow that points at the trigger. |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | `top` | Whether the reactions overlap the bubble's top or bottom edge. |
| `sideOffset` | `number \| OffsetFunction` | `10` | Distance between the anchor and the popup, in pixels. |

### TooltipProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |
| `closeDelay` | `number` | – | How long to wait before closing a tooltip. Specified in milliseconds. |
| `delay` | `number` | – | How long to wait before opening the tooltip on hover. Specified in milliseconds. |
| `timeout` | `number` | `400` | Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds. |

### TooltipTrigger

Accepts `className`, `style`, `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the tooltip. Specified in milliseconds. |
| `closeOnClick` | `boolean` | `true` | Whether the tooltip should close when this trigger is clicked. |
| `delay` | `number` | `600` | How long to wait before opening the tooltip on hover. Specified in milliseconds. |
| `disabled` | `boolean` | `false` | If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop. |
| `handle` | `TooltipHandle<unknown>` | – | A handle to associate the trigger with a tooltip. |
| `payload` | `unknown` | – | A payload to pass to the tooltip when it is opened. |

### Helpers

`TooltipCreateHandle` is called, not rendered. It creates a handle: pass it as `handle` to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

---

# Waveform

> An audio waveform, from a file or a live microphone, with scrubbing.

Source: https://ui.xiod.dev/docs/components/waveform

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import {
  Waveform,
  WaveformVisual,
  WaveformScrubber,
  WaveformHandle
} from "xiod-ui/waveform";
```

Anatomy:

```tsx
<Waveform>
  <WaveformVisual />
  <WaveformScrubber />
  <WaveformHandle />
</Waveform>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Mic, MicOff, Pause, Play } from "xiod-icons";
import { Badge } from "xiod-ui/badge";
import { Button } from "xiod-ui/button";
import {
  Waveform,
  WaveformHandle,
  WaveformScrubber,
  WaveformVisual,
} from "xiod-ui/waveform";

const duration = 120;

const formatTime = (seconds: number) => {
  const minutes = Math.floor(seconds / 60);
  const rest = Math.floor(seconds % 60);
  return `${minutes}:${rest < 10 ? "0" : ""}${rest}`;
};

export default function WaveformExample() {
  const [isPlaying, setIsPlaying] = React.useState(false);
  const [progress, setProgress] = React.useState(12);
  const [isMicActive, setIsMicActive] = React.useState(false);

  React.useEffect(() => {
    if (!isPlaying) return;
    const interval = setInterval(() => {
      setProgress((prev) => {
        if (prev >= duration) {
          setIsPlaying(false);
          return 0;
        }
        return prev + 1;
      });
    }, 1000);
    return () => clearInterval(interval);
  }, [isPlaying]);

  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-12">
      {/* Scrubber */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Scrubber
        </Badge>
        <div className="flex w-full items-center gap-4">
          <Button
            variant="outline"
            size="icon"
            className="size-10 shrink-0 rounded-full"
            onClick={() => setIsPlaying(!isPlaying)}
            aria-label={isPlaying ? "Pause" : "Play"}
          >
            {isPlaying ? (
              <Pause className="size-4" />
            ) : (
              <Play className="size-4 fill-current" />
            )}
          </Button>
          <Waveform
            value={progress}
            duration={duration}
            onValueChange={setProgress}
            barWidth={3}
            barGap={1.5}
            barRadius={1.5}
            fadeEdges
            className="h-14 flex-1"
          >
            <WaveformVisual />
            <WaveformScrubber />
            <WaveformHandle className="size-3 border-2 border-background bg-primary" />
          </Waveform>
          <span className="shrink-0 font-mono text-xs text-muted-foreground">
            {formatTime(progress)} / {formatTime(duration)}
          </span>
        </div>
      </div>

      {/* Microphone */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Microphone
        </Badge>
        <div className="flex w-full items-center gap-4">
          <Button
            variant={isMicActive ? "destructive" : "default"}
            size="icon"
            className="size-10 shrink-0 rounded-full"
            onClick={() => setIsMicActive(!isMicActive)}
            aria-label={isMicActive ? "Stop microphone" : "Start microphone"}
          >
            {isMicActive ? (
              <MicOff className="size-4" />
            ) : (
              <Mic className="size-4" />
            )}
          </Button>
          <Waveform
            active={isMicActive}
            microphone={isMicActive}
            barWidth={3}
            barGap={2}
            barRadius={1.5}
            fadeEdges
            className="h-14 flex-1"
          />
        </div>
      </div>

      {/* Processing */}
      <div className="flex w-full flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Processing
        </Badge>
        <Waveform
          processing
          barWidth={3}
          barGap={2}
          barRadius={1.5}
          fadeEdges
          className="h-14 w-full"
        />
      </div>
    </div>
  );
}
```

## API Reference

### Waveform

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Whether the waveform shows live input instead of a recording. With `microphone`, the microphone is recorded while this is `true`. |
| `barColor` | `string` | – | The colour of bars not yet played, as a CSS colour. Defaults to the `--border` token. |
| `barGap` | `number` | `2` | The space between bars, in pixels. |
| `barRadius` | `number` | `1.5` | The corner radius of each bar, in pixels. `0` gives square bars. |
| `barWidth` | `number` | `3` | The width of each bar, in pixels. |
| `data` | `number[]` | – | The bar heights to draw, each from 0 to 1. They are stretched to fill the width. |
| `defaultValue` | `number` | – | The playback position at first, when it isn't controlled. |
| `deviceId` | `string` | – | The microphone to record from, as a `deviceId` from `navigator.mediaDevices.enumerateDevices()`. Uses the default microphone when unset. |
| `duration` | `number` | `1` | The total length, in the same unit as `value`. Leave it at 1 to use `value` as a fraction from 0 to 1. |
| `fadeEdges` | `boolean` | `true` | Whether the bars fade out towards the left and right edges. |
| `fadeWidth` | `number` | `24` | How far the fade reaches in from each edge, in pixels. |
| `microphone` | `boolean` | `false` | Whether to record from the microphone while `active`. The browser asks the user for permission first. |
| `mode` | `"static" \| "scrolling" \| "live"` | `static` | How live input is drawn: `scrolling` adds each sample at the right edge and moves older ones left; `static` and `live` redraw the bars across the full width. |
| `onValueChange` | `((value: number) => void)` | – | Called with the new position when the user clicks or drags to seek. |
| `processing` | `boolean` | `false` | Whether to show a gently moving wave, for example while an assistant is thinking. Ignored while `active`. |
| `progressColor` | `string` | – | The colour of played bars and of live input, as a CSS colour. Defaults to the `--primary` token. |
| `seed` | `number` | `42` | A number that picks the placeholder waveform drawn when there's no `data`. The same seed always draws the same shape. |
| `sensitivity` | `number` | `1` | How strongly microphone input moves the bars. Raise it for quiet input. |
| `updateRate` | `number` | `30` | How often to sample the microphone, in milliseconds. |
| `value` | `number` | – | The playback position, in the same unit as `duration`. Use with `onValueChange` to control it. |

### WaveformVisual

every native attribute of the element it renders.

### WaveformScrubber

Accepts `render`, plus every native attribute of the element it renders.

### WaveformHandle

Accepts `render`, plus every native attribute of the element it renders.

---

# Wheel Picker

> A scrolling wheel for picking a value, like the iOS picker.

Source: https://ui.xiod.dev/docs/components/wheel-picker

## Installation

```bash
npm install xiod-ui
```

## Usage

```tsx
import { WheelPickerGroup, WheelPicker } from "xiod-ui/wheel-picker";
```

Anatomy:

```tsx
<WheelPickerGroup>
  <WheelPicker />
</WheelPickerGroup>
```

## Example

```tsx
"use client";

import * as React from "react";
import { Badge } from "xiod-ui/badge";
import { WheelPicker, WheelPickerGroup } from "xiod-ui/wheel-picker";

const numberOptions = (length: number, offset = 0) =>
  Array.from({ length }, (_, i) => ({
    value: i + offset,
    label: String(i + offset).padStart(2, "0"),
  }));

const MONTHS = [
  "January",
  "February",
  "March",
  "April",
  "May",
  "June",
  "July",
  "August",
  "September",
  "October",
  "November",
  "December",
].map((name, index) => ({ value: index + 1, label: name }));

const WEEKDAYS = [
  { value: "sun", label: "Sunday" },
  { value: "mon", label: "Monday" },
  { value: "tue", label: "Tuesday" },
  { value: "wed", label: "Wednesday" },
  { value: "thu", label: "Thursday" },
  { value: "fri", label: "Friday" },
  { value: "sat", label: "Saturday", disabled: true },
];

const HOURS = numberOptions(12, 1);
const MINUTES = numberOptions(60);
const MERIDIEM = [
  { value: "AM", label: "AM" },
  { value: "PM", label: "PM" },
];

export default function WheelPickerExample() {
  const [month, setMonth] = React.useState(6);
  const [weekday, setWeekday] = React.useState("mon");
  const [hour, setHour] = React.useState(10);
  const [minute, setMinute] = React.useState(30);
  const [meridiem, setMeridiem] = React.useState("AM");

  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-12">
      {/* Single */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Single
        </Badge>
        <div className="flex flex-wrap items-start justify-center gap-8">
          <WheelPickerGroup className="w-40">
            <WheelPicker
              options={MONTHS}
              value={month}
              onValueChange={setMonth}
              infinite
              aria-label="Month"
            />
          </WheelPickerGroup>
          <WheelPickerGroup className="w-40">
            <WheelPicker
              options={WEEKDAYS}
              value={weekday}
              onValueChange={setWeekday}
              aria-label="Weekday"
            />
          </WheelPickerGroup>
        </div>
      </div>

      {/* Grouped */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Grouped
        </Badge>
        <WheelPickerGroup className="max-w-70">
          <WheelPicker
            options={HOURS}
            value={hour}
            onValueChange={setHour}
            infinite
            aria-label="Hours"
          />
          <div className="flex items-center px-1 font-semibold text-muted-foreground/60 select-none">
            :
          </div>
          <WheelPicker
            options={MINUTES}
            value={minute}
            onValueChange={setMinute}
            infinite
            aria-label="Minutes"
          />
          <div className="w-2" />
          <WheelPicker
            options={MERIDIEM}
            value={meridiem}
            onValueChange={setMeridiem}
            aria-label="AM or PM"
          />
        </WheelPickerGroup>
      </div>

      {/* Sizes */}
      <div className="flex flex-col items-center space-y-4">
        <Badge variant="outline" className="mb-2">
          Sizes
        </Badge>
        <div className="flex flex-wrap items-end justify-center gap-8">
          {(["sm", "md", "lg"] as const).map((size) => (
            <WheelPickerGroup key={size} className="w-28">
              <WheelPicker
                options={HOURS}
                size={size}
                infinite
                aria-label={`Hours, ${size}`}
              />
            </WheelPickerGroup>
          ))}
        </div>
      </div>
    </div>
  );
}
```

## API Reference

### WheelPickerGroup

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The content of the component. |

### WheelPicker

Accepts `render`, plus every native attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `WheelPickerOption<T>[]` | – | The options on the wheel. |
| `classNames` | `WheelPickerClassNames` | – | Classes for the parts of the wheel. |
| `defaultValue` | `T` | – | The value selected at first, when it isn't controlled. |
| `dragSensitivity` | `number` | `3` | How quickly the wheel slows after a flick. Higher values stop it sooner. |
| `infinite` | `boolean` | `false` | Whether the options repeat, so the wheel turns endlessly in either direction. |
| `onValueChange` | `((value: T) => void)` | – | Called with the new value when the wheel settles on an option. |
| `optionItemHeight` | `number` | – | The height of each option, in pixels. Defaults to 28, 36 or 44 depending on `size`. |
| `scrollSensitivity` | `number` | `5` | How far and fast the wheel turns for mouse-wheel and keyboard scrolling. Higher values turn it further and faster. |
| `size` | `"sm" \| "md" \| "lg"` | `md` | The size of the component. |
| `value` | `T` | – | The selected value. Use with `onValueChange` to control it. |
| `visibleCount` | `number` | `20` | The number of options around the whole wheel, which sets how sharply it curves. A quarter of them show on each side of the selected option. Use a multiple of 4. |